Native Engine
Architecture
How Nitrowind connects compiled CSS, the C++ runtime, Fabric ShadowTree updates, and native iOS and Android effects.
Native Engine Architecture
The native engine lives in nitrocss. It combines a shared C++ runtime with
small platform drivers for effects that need UIKit or Android View APIs.
Core pieces:
| Piece | Role |
|---|---|
| Metro compiler | Converts CSS and Tailwind utilities into flattened native style tables. |
NitroCssEngine | Resolves class-name buckets against the current runtime state. |
DependencyIndex | Tracks linked nodes by theme, dimensions, safe area, container, and state dependency. |
ShadowTreeMutator | Clones props and commits updates to the Fabric ShadowTree. |
ScrollTimelineTargets | Shares compiled scroll sources, animation targets, ranges, and keyframes. |
| iOS scroll timeline driver | Reads UIScrollView progress and applies interpolated frames to native views. |
| Android scroll timeline driver | Reads Android scroll progress and applies the same compiled timeline model. |
| Nitro specs | Define generated bindings between JavaScript, Swift/Kotlin, and C++. |
| Platform HybridObjects | Read platform appearance, dimensions, insets, and configuration. |
Update flow
- Metro compiles authored CSS into style tables and native effect descriptors.
- JavaScript performs the initial style resolution and links the mounted Fabric node.
- The C++ dependency index records which runtime values can affect that node.
- Theme, color-scheme, dimension, safe-area, container, and interaction changes re-resolve only the linked nodes that depend on them.
- The ShadowTree mutator commits supported prop changes without a React re-render.
Scroll-driven animations use the same compiled descriptors but are sampled by
the platform scroll drivers. Both iOS and Android interpolate supported
keyframes from native scroll position without a JavaScript onScroll loop. See
Scroll-Driven Animations for supported
timelines, ranges, axes, and properties.