# How it works

> The SymbioteNative render pipeline from framework adapters to the stock React Native Fabric host.

SymbioteNative is built around one architectural fact: Fabric already exposes a
framework-agnostic JavaScript seam.

React Native's React renderer talks to this seam from its Fabric host config.
SymbioteNative talks to the same seam from its own engine.

## Render pipeline

```txt
Framework adapter
  React · Vue · Angular · Svelte · Solid
        ↓
Mutation API
  insert · remove · setProp · commit
        ↓
@symbiote-native/engine (JavaScript)
  builds a command buffer — no retained tree on this side
        ↓  one JSI crossing per commit
SymbioteTree (C++)
  retained tree · clone-on-write · tag-keyed platform rules · event normalization
        ↓
Fabric's UIManager
  createNode · cloneNodeWithNewProps · appendChildToSet · completeRoot
        ↓
stock React Native
  Fabric C++ · JSI · Yoga · native views
```

## Why the engine exists

Most UI frameworks express host updates as mutations: set a prop, insert a
child, remove a child. Fabric is persistent: you do not mutate an existing node;
you clone nodes with new props or children and atomically commit a new child set.

The engine is the translation layer between those worlds. Its JavaScript half
turns adapter mutations into a buffer of ops; its C++ half — `SymbioteTree` — owns
the retained tree, applies that buffer, and turns it into Fabric child set commits,
one JSI crossing per commit instead of one per mutation.

Platform behavior that React Native's own components carry in JavaScript —
a `Pressable`'s `disabled` folding into its accessibility state, a `Switch`'s
different prop names per platform, a `Text`'s default `ellipsizeMode` — is folded
into the same C++ layer, keyed off the Fabric tag a node was created with. Every
adapter gets it once, instead of porting it per framework.

That means each framework adapter stays thin. A persistence bug is fixed once in
the engine, not once per framework.

## What stays stock

SymbioteNative does not fork React Native native code. These stay ordinary React Native
runtime pieces:

- Fabric C++ shadow tree
- Yoga layout
- JSI and Hermes
- iOS/Android host surfaces
- native modules

The only replaced layer is the JavaScript renderer that drives Fabric.

## Events

Fabric returns events to the same handle passed at node creation time. In React,
that handle is a Fiber. In SymbioteNative, it is a retained-tree node owned by the
engine. The adapter maps framework event syntax onto engine listeners, and the
engine normalizes native events back into those listeners.

## Deeper architecture

The public site should explain the architecture directly instead of pointing
readers at local repository notes. Deeper design rationale can be promoted into
standalone public pages as the docs grow.