@symbiote-native/engine 0.3.0 → 0.5.0

package/build/node.js

@@ -4,9 +4,24 @@
 // tree mutable while the Fabric mirror stays persistent lets every adapter mutate
 // freely without touching Fabric's clone-on-write protocol directly, and it
 // lives here in shared so no adapter re-implements it.
+import { isAriaAliasKey } from './accessibility-props.js';
 import { isEventFor } from './view-config.js';
-import { isClassNameValue, resolveClassName } from './style-registry/index.js';
+import { canonicalClassName, isClassNameValue, resolveActiveClassName, resolveClassName, } from './style-registry/index.js';
 import { dlog } from './debug.js';
+import { appListenerFor, attachHostBehavior, claimModeFor, hasHostBehaviors, markDetachCandidate, notifyChildInserted, notifyOwnedListenerChange, notifyWrapChange, ownsListener, reattachHostBehaviors, derivedNodesOf, slotDerivesFrom, slotPropNameFor, slotTakesChildren, stashAppListener, } from './host-behavior.js';
+// A cycle, deliberately: commit.ts imports this module for the node shape, and the imperative
+// methods below call back into it. Neither side touches the other at module-evaluation time -
+// only inside a function body - so every loader (tsc, vitest, Metro) resolves it fine. The
+// alternative was a load-time `SymbioteNode.prototype.measure = ...` installed from elsewhere,
+// which is exactly the registration-side-effect shape Metro's inlineRequires silently drops in
+// release builds (see CLAUDE.md, "Never make correctness depend on a module's load-time side
+// effect").
+import { measure as engineMeasure, measureInWindow as engineMeasureInWindow, measureLayout as engineMeasureLayout, setNativeProps as engineSetNativeProps, dispatchViewCommand, } from './commit.js';
+// The same deliberate cycle, for the same reason: `routeProp` resolves an AnimatedNode written
+// into a prop, and the module that owns that resolution reaches back here for `setProp`. See
+// `animated/host-binding.ts`'s header.
+import { hasAnimatedNodes } from './animated/graph.js';
+import { bindAnimatedEvent, bindAnimatedValue, hasAnimatedBindings, reattachAnimatedProps, } from './animated/host-binding.js';
 const BRAND = Symbol('symbiote.node');
 // A node carries the Fabric view name directly, so adding a primitive (Image,
 // ScrollView, TextInput) is just a new string from the adapter, no core change.
@@ -25,29 +40,144 @@ export function isSymbioteEvent(value) {
     const nativeEvent = Reflect.get(value, 'nativeEvent');
     return typeof nativeEvent === 'object' && nativeEvent !== null;
 }
-export function createElement(component, isText = false) {
-    return {
-        [BRAND]: true,
-        component,
-        isText,
-        props: {},
-        listeners: undefined,
-        children: [],
-        parent: undefined,
-        dirty: true,
-    };
+const FOCUS_COMMAND = 'focus';
+const BLUR_COMMAND = 'blur';
+// Names and arg order mirror RN's ScrollViewCommands.
+const SCROLL_TO_COMMAND = 'scrollTo';
+const SCROLL_TO_END_COMMAND = 'scrollToEnd';
+const FLASH_SCROLL_INDICATORS_COMMAND = 'flashScrollIndicators';
+// The one shape every retained node has. A class, not an object literal, for two reasons: the six
+// imperative methods live on the shared prototype instead of being allocated per node (see
+// ISymbioteNode above), and both factories below mint the same hidden class.
+//
+// Fields are `declare`d and assigned in the constructor rather than written as class fields: with
+// ES2022 field semantics the two are equivalent in meaning but not in emit, and a plain
+// constructor assignment is the shape every engine (V8 and Hermes both) handles without a
+// define-per-field.
+class SymbioteNode {
+    constructor(component, isText, props) {
+        this[BRAND] = true;
+        this.component = component;
+        this.isText = isText;
+        this.props = props;
+        this.listeners = undefined;
+        this.children = [];
+        this.parent = undefined;
+        // A node that has never committed must never take a fast path built on "the mirror already
+        // agrees with me", so all three flags start raised - including for createRawText, whose props
+        // are assigned here rather than through setText.
+        this.dirty = true;
+        this.propsDirty = true;
+        // Assigned here, not lazily on first use: every slot present from the constructor keeps one
+        // hidden class for every node. Adding it on demand buys a shape transition per aria-bearing
+        // node, which is the opposite of what this field is for.
+        //
+        // Starts false, and that is COMPLETE rather than optimistic: the only two constructions are
+        // `createElement`'s `{}` and `createRawText`'s `{ text }`, so no aria key can arrive here. It
+        // was first written as `hasAriaAliases(props)` — a probe that reads as a safeguard and can
+        // never fire, which the break-test caught by staying green with it removed. If a construction
+        // path is ever added that passes real props, this line owes that probe back.
+        this.hasAriaAlias = false;
+        this.structureDirty = true;
+        this.committed = undefined;
+        this.styleParts = undefined;
+        // Assigned here for the same hidden-class reason as `hasAriaAlias` above; `attachHostBehavior`
+        // overwrites it a few lines later for the rare node that has a behavior.
+        this.payloadFold = undefined;
+        // Same reason again, and here it is load-bearing rather than tidy: the redirect below is read
+        // on every append, so the slot must be a stable slot on one hidden class, not a property added
+        // to a few nodes after the fact.
+        this.childHost = undefined;
+        this.wrapper = undefined;
+    }
+    measure(callback) {
+        engineMeasure(this, callback);
+    }
+    measureInWindow(callback) {
+        engineMeasureInWindow(this, callback);
+    }
+    measureLayout(relativeToNativeNode, onSuccess, onFail) {
+        if (!isSymbioteNode(relativeToNativeNode)) {
+            dlog('measureLayout: relative target must be a host ref');
+            return;
+        }
+        engineMeasureLayout(this, relativeToNativeNode, onSuccess, onFail);
+    }
+    setNativeProps(nativeProps) {
+        engineSetNativeProps(this, nativeProps);
+    }
+    focus() {
+        dispatchViewCommand(this, FOCUS_COMMAND, []);
+    }
+    blur() {
+        dispatchViewCommand(this, BLUR_COMMAND, []);
+    }
+    // The defaults live HERE and nowhere else. `buildScrollViewHandle`
+    // (`@symbiote-native/components`) used to own them and now delegates, so the wrapper's handle and
+    // a lowered element's node cannot drift on what `scrollTo()` with no argument means.
+    scrollTo(options) {
+        const x = options?.x ?? 0;
+        const y = options?.y ?? 0;
+        const animated = options?.animated ?? true;
+        dlog(`ScrollView.scrollTo x=${x} y=${y} animated=${animated}`);
+        dispatchViewCommand(this, SCROLL_TO_COMMAND, [x, y, animated]);
+    }
+    scrollToEnd(options) {
+        const animated = options?.animated ?? true;
+        dlog(`ScrollView.scrollToEnd animated=${animated}`);
+        dispatchViewCommand(this, SCROLL_TO_END_COMMAND, [animated]);
+    }
+    flashScrollIndicators() {
+        dlog('ScrollView.flashScrollIndicators');
+        dispatchViewCommand(this, FLASH_SCROLL_INDICATORS_COMMAND, []);
+    }
+}
+/**
+ * The committed record for `node`, or `undefined` if it has never been committed - or if `node` is
+ * not the raw retained node at all.
+ *
+ * That second case is the reason this is a function rather than a bare `node.committed` read. The
+ * engine identifies a node BY IDENTITY, and the classic way to break that is to hand the engine a
+ * wrapper instead of the node: a Vue `reactive()`/deep-`ref()` Proxy around a host element is the
+ * one that actually happens (see the vue-adapter-reactivity skill; `shallowRef` is the fix).
+ *
+ * The old WeakMap caught this for free - a Proxy is a different object, so `mirror.get(proxy)` missed
+ * and every imperative API bailed with a clear "node not committed". A plain property read does NOT:
+ * a Proxy forwards `proxy.committed` straight to the target and hands back a real record, whose
+ * `handle` Vue would then deep-wrap on the way out. That handle is a JSI host object; a Proxy around
+ * it reaches `cloneNodeWithNewProps` and fails somewhere deep in native, far from the cause.
+ *
+ * So the identity check that was implicit in the WeakMap is explicit here: a record written on the
+ * raw node names it, and `record.owner !== node` means whatever we were handed is not that node.
+ * One reference comparison, and the wrap now fails LOUDER than it used to rather than quieter.
+ */
+export function committedOf(node) {
+    const record = node.committed;
+    if (record === undefined)
+        return undefined;
+    if (record.owner !== node) {
+        dlog(`node identity mismatch: committed record belongs to node=${debugNodeId(record.owner)}, ` +
+            `not to the object handed in. A wrapped/proxied node (Vue reactive() or deep ref() around ` +
+            `a host element) is the usual cause - hold host nodes with shallowRef.`);
+        return undefined;
+    }
+    return record;
+}
+export function createElement(component, isText = false, 
+// The intrinsic tag this node came from, when it differs from the Fabric view name above. The
+// behavior registry is keyed by tag and the node only ever carries the resolved name, so an
+// adapter lowering `<Pressable>` has to hand the tag over here or the registration cannot fire
+// (host-behavior.ts, `attached`). Nothing is stored — the lookup happens once, right below.
+tag = component) {
+    const node = new SymbioteNode(component, isText, {});
+    // Gated on the boolean, not on the Map: this runs ~9 000 times per benchmark create, and an app
+    // that registers nothing must pay one boolean read rather than a hash lookup per node.
+    if (hasHostBehaviors())
+        attachHostBehavior(node, tag);
+    return node;
 }
 export function createRawText(text) {
-    return {
-        [BRAND]: true,
-        component: RAW_TEXT_COMPONENT,
-        isText: false,
-        props: { text },
-        listeners: undefined,
-        children: [],
-        parent: undefined,
-        dirty: true,
-    };
+    return new SymbioteNode(RAW_TEXT_COMPONENT, false, { text });
 }
 // `instanceHandle` round-trips through Fabric unchanged: the object we pass to
 // createNode comes back as the event target. We brand our nodes so the event
@@ -106,6 +236,30 @@ export function isEmptyRawText(node) {
 // every render, so marking there would re-dirty the whole tree every commit and hand the win back.
 // The one listener that DOES change a Fabric prop, `layout`, raises `onLayout` through setProp
 // below and is marked that way.
+/**
+ * Change which Fabric view a node commits as, keeping the node's identity.
+ *
+ * The commit walk already re-creates a node whose `viewName` no longer matches its committed one —
+ * that is how a `<Text>` moving in or out of another `<Text>` flips between RCTText and
+ * RCTVirtualText (`commit.ts`, reason `view-kind`). This exposes the same door for a prop-driven
+ * view choice, so `intrinsicWhen` is honoured on UPDATE and not only at create.
+ *
+ * The POLICY stays out of the engine: which prop decides, and which view it decides between, lives
+ * in `HOST_PRIMITIVES` and is read by `resolveIntrinsicTag` in `@symbiote-native/components`. The
+ * engine only knows how to swap the name — the same split every other spec-driven fold has here.
+ *
+ * A no-op when the name is unchanged, so a renderer may call it on every update without comparing
+ * first.
+ */
+export function setNodeComponent(node, component) {
+    if (node.component === component)
+        return;
+    node.component = component;
+    // `dirty` alone is not enough: the walk's reuse test also requires the node be visited at all,
+    // and a node whose own props did not change this tick is exactly the case that would be skipped.
+    markDirty(node);
+    markPropsDirty(node);
+}
 export function markDirty(node) {
     let current = node;
     while (current !== undefined && !current.dirty) {
@@ -113,6 +267,40 @@ export function markDirty(node) {
         current = current.parent;
     }
 }
+// The prop-write twin of markDirty: raises this node's OWN props flag and then bubbles the subtree
+// flag as usual. Every path that writes `node.props` must come through here - setProp and setText
+// below, setNativeProps in commit.ts (which writes the record directly and so owes its own mark).
+//
+// Note the two flags are raised INDEPENDENTLY rather than one implying the other. markDirty stops
+// at the first already-dirty ancestor, so a node dirtied a moment ago by a child's change would
+// otherwise have its own prop write silently dropped: the walk would exit before setting anything
+// here. Setting propsDirty first, unconditionally, is what makes that ordering safe.
+export function markPropsDirty(node) {
+    node.propsDirty = true;
+    markDirty(node);
+}
+// The structural twin. Raised on the PARENT whose child list changed - never on the moved child,
+// for the same reason markDirty is not (see the structural ops below).
+//
+// Every caller must reach here BEFORE mutating `parent.children`, and that ordering is now
+// load-bearing rather than stylistic. reconcile stores the reconciled child list in the committed
+// record BY REFERENCE, so for a parent holding no anchors the record ALIASES `parent.children`;
+// this call is the last moment the committed list can still be read. Taking the copy here means it
+// is taken once per parent per commit->mutation cycle, and only for parents that actually change,
+// instead of once per node per commit - 9 002 arrays on a 1 000-row create, all but a handful
+// allocated only to be discarded unread.
+//
+// The identity test is what keeps it honest: a record whose `children` is NOT `parent.children`
+// either already holds a copy (this cycle's first structural op ran) or holds the private array
+// renderableChildren built to flatten anchors away, which nobody mutates. Neither needs saving.
+export function markStructureDirty(parent) {
+    const record = parent.committed;
+    if (record !== undefined && record.children === parent.children) {
+        record.children = parent.children.slice();
+    }
+    parent.structureDirty = true;
+    markDirty(parent);
+}
 // How many prop writes actually landed, and how many the no-op guard below turned away.
 // Read-and-zeroed through readCommitProfile() (commit.ts), which folds them into the same window
 // as the walk numbers so one read prices both halves: `propNoops` is the waste an adapter is
@@ -171,22 +359,104 @@ export function setProp(node, key, value) {
         }
         node.props[key] = value;
     }
+    // The single choke point for the aria gate. `routeProp`'s other branches — class, style,
+    // activeStyle, on* — return before reaching here and none of them can carry an alias, so every
+    // `role` / `aria-*` write in the engine passes through this line.
+    if (!node.hasAriaAlias && isAriaAliasKey(key))
+        node.hasAriaAlias = true;
+    // A composed primitive's slot — and its wrapper, where it has one — can carry a value DERIVED
+    // from an owner prop, and `markPropsDirty` bubbles up, so neither ever learns. Here rather than
+    // in `routeProp` because this is the one choke point every writer passes (a structural adapter's
+    // `setProperty` does not go through routeProp), and past the identity guard so a re-render
+    // writing an unchanged value costs them nothing. See `IHostBehavior.slotDerived`.
+    if (node.childHost !== undefined && slotDerivesFrom(node, key)) {
+        markPropsDirty(node.childHost);
+        // Past the slot: a `buildStructure` that builds a CHAIN registers the deeper nodes here, and
+        // each keeps its own pure fold reading the owner. See `addDerivedNode`.
+        const derived = derivedNodesOf(node);
+        if (derived !== undefined)
+            for (const each of derived)
+                markPropsDirty(each);
+        if (node.wrapper !== undefined)
+            markPropsDirty(node.wrapper);
+    }
     propStats.writes += 1;
-    markDirty(node);
+    markPropsDirty(node);
 }
-// Fabric gates layout events behind a boolean prop (BaseViewProps.onLayout): unlike
-// scroll / touch / change, which the native component emits unconditionally, a
-// layout event fires only when the shadow node is flagged. So a `layout` listener
-// must also raise that prop, mirroring RN's `onLayout: true` validAttribute;
-// otherwise onLayout never fires and anything measuring its own box (VirtualizedList
-// viewport) stays at zero.
-const LAYOUT_EVENT = 'layout';
-const LAYOUT_FLAG_PROP = 'onLayout';
+// Fabric gates a handful of events behind a BOOLEAN prop: unlike scroll / touch / change, which
+// the native component emits unconditionally, these fire only when the shadow node carries the
+// flag. RN raises them with an `on*: true` validAttribute; we drop function props from the
+// payload, so a gated handler attaches on our side and the native event simply never arrives.
+// That is silent - a test asserting the listener is present passes, and only a device shows it.
+//
+// The list is exhaustive as of react-native 0.86: every `bool on*` field in Fabric's C++ props
+// (`ReactCommon/react/renderer/components/**`), each read behind an `if` before the emitter runs:
+//
+//   BaseViewProps.onLayout                         ParagraphShadowNode.cpp / RCTViewComponentView
+//   AccessibilityProps.onAccessibilityTap          RCTViewComponentView.mm:1603
+//   AccessibilityProps.onAccessibilityMagicTap     RCTViewComponentView.mm:1613
+//   AccessibilityProps.onAccessibilityEscape       RCTViewComponentView.mm:1623
+//   AccessibilityProps.onAccessibilityAction       RCTViewComponentView.mm:1633
+//   BaseParagraphProps.onTextLayout                ParagraphShadowNode.cpp:351
+//
+// Keyed by the post-`listenerName` event name, valued with the payload key. `magicTap` maps to
+// `onMagicTap` and NOT to the C++ member name `onAccessibilityMagicTap`, because `onMagicTap` is
+// what RN's own view config declares (BaseViewConfig.ios.js) - the two disagree upstream, and
+// matching stock is the only defensible choice until RN resolves it.
+const GATED_EVENT_PROPS = new Map([
+    ['layout', 'onLayout'],
+    ['textLayout', 'onTextLayout'],
+    ['accessibilityTap', 'onAccessibilityTap'],
+    ['magicTap', 'onMagicTap'],
+    ['accessibilityEscape', 'onAccessibilityEscape'],
+    ['accessibilityAction', 'onAccessibilityAction'],
+]);
 // The explicit event channel. Structural adapters (Svelte addEventListener, Angular
 // Renderer2.listen) call this directly with an already-known event name; flat-bag
 // adapters reach it through routeProp. A non-function value clears the listener.
+/**
+ * Install a listener the BEHAVIOR owns, bypassing the ownership check.
+ *
+ * `setEventListener` diverts an owned name into the stash, which is right for an app listener and
+ * circular for the behavior's own dispatcher — it would stash itself and never occupy the slot it
+ * exists to hold. This is the one writer allowed past that gate.
+ *
+ * `undefined` removes it, gate flag included. A behavior whose dispatcher is conditional needs
+ * that as much as it needs the install: ScrollView takes the owner's `layout` only while the app
+ * or an inverted sticky header wants it, and a one-way installer leaves `onLayout: true` standing
+ * in the payload of a ScrollView that no longer reads the event.
+ */
+export function setBehaviorListener(node, name, listener) {
+    if (listener === undefined)
+        node.listeners?.delete(name);
+    else
+        (node.listeners ??= new Map()).set(name, listener);
+    const flagProp = GATED_EVENT_PROPS.get(name);
+    if (flagProp !== undefined)
+        setProp(node, flagProp, listener === undefined ? undefined : true);
+}
 export function setEventListener(node, name, value) {
     const isHandler = typeof value === 'function';
+    // A name a host behavior OWNS never reaches `node.listeners` — the behavior's dispatcher holds
+    // that slot and the app's callback is stashed beside it. `node.listeners` is single-slot, so
+    // without this the two evict each other and the last writer wins with no diagnostic; and the
+    // keys at stake are the ones a gesture STARTS on, so the loser is silently pressless. The
+    // component wrapper used to mediate this by destructuring the app's callbacks out before they
+    // reached the node; lowering removes the mediator. Gated on the boolean first, so an app with no
+    // behavior registered pays one read.
+    if (hasHostBehaviors() && ownsListener(node, name)) {
+        // The PRESENCE only, never the identity: listeners deliberately do not notify (a framework
+        // hands a fresh closure nearly every render — see `markDirty`'s note on why that must stay
+        // free). A flip is a mount-time event, not a per-render one.
+        const wasWired = appListenerFor(node, name) !== undefined;
+        stashAppListener(node, name, isHandler ? value : undefined);
+        if (wasWired !== isHandler)
+            notifyOwnedListenerChange(node, name, isHandler);
+        const flagged = GATED_EVENT_PROPS.get(name);
+        if (flagged !== undefined)
+            setProp(node, flagged, isHandler ? true : undefined);
+        return;
+    }
     if (isHandler) {
         const handler = value;
         const listeners = (node.listeners ??= new Map());
@@ -195,8 +465,9 @@ export function setEventListener(node, name, value) {
     else {
         node.listeners?.delete(name);
     }
-    if (name === LAYOUT_EVENT)
-        setProp(node, LAYOUT_FLAG_PROP, isHandler ? true : undefined);
+    const flagProp = GATED_EVENT_PROPS.get(name);
+    if (flagProp !== undefined)
+        setProp(node, flagProp, isHandler ? true : undefined);
 }
 const ON_PREFIX = /^on[A-Z]/;
 // onChange -> change
@@ -235,24 +506,149 @@ const REACT_JSX_DEV_PROPS = new Set([
     '__self',
     '__source',
 ]);
-const classStyleParts = new WeakMap();
-// The fresh array below means setProp's no-op guard never fires for `style`, and that is
-// DELIBERATE - do not "finish the optimization" by skipping when both halves are unchanged.
-// `classStyleParts` is a shadow copy of the declarative style, and setNativeProps bypasses it
-// (it writes node.props.style directly, merging an Animated frame onto whatever is there). An
-// app that hands over a hoisted style constant - StyleSheet.create, a module-level object - would
-// then re-push an identity-equal half, get skipped, and never restore the declarative style the
-// animation overwrote. The re-push IS the restore path.
-function commitClassStyle(node, patch) {
-    const entry = { ...classStyleParts.get(node), ...patch };
-    classStyleParts.set(node, entry);
+// All slots are present from the start rather than added as they are written: one hidden class for
+// every styled node in the app, instead of a shape transition per slot.
+// Narrowed rather than cast: `routeProp` takes `unknown`, and a bare `typeof v === 'function'`
+// leaves TS with `Function`, which is callable with anything. This states the shape the contract
+// actually promises.
+function isStyleCallback(value) {
+    return typeof value === 'function';
+}
+function stylePartsOf(node) {
+    return (node.styleParts ??= {
+        classStyle: undefined,
+        explicitStyle: undefined,
+        hiddenStyle: undefined,
+        className: undefined,
+        isPressed: false,
+        activeStyle: undefined,
+        activeStyleFromCallback: false,
+    });
+}
+// What belongs in slot 0 right now. The pressed variant is a complete REPLACEMENT rather than an
+// overlay: `resolveActiveClassName` resolves the element's tokens PLUS `:active` through the same
+// matcher, so a `.btn:active` rule joins the cascade exactly as its specificity says and the
+// result already contains everything `.btn` gave. That is why pressing needs no extra style slot
+// and leaves the published array's SHAPE untouched.
+//
+// Resolved LAZILY, at press time, never beside `classStyle`. Eager would mean two resolutions per
+// class WRITE — ~14 000 of them on one benchmark create — and twice the distinct keys in a cache
+// that clears whole on overflow, to serve a state almost no node is ever in. A press is one event
+// on one node, so the second lookup is invisible there.
+//
+// `:active` applies only to a class that reaches the engine as a STRING, and the reason it is a
+// footnote rather than a gap is that essentially nothing delivers anything else.
+//
+//   Vue      createVNode normalises class to a string before patchProp ever sees it — in
+//            @vue/runtime-core, `if (klass && !isString(klass)) props.class =
+//            normalizeClass(klass)`. So `:class="{btn:true}"` arrives as `"btn"`. Cited by the
+//            expression, not a line: the package ships several builds of that file and the same
+//            statement sits on a different line in each, so two readers comparing notes see a
+//            contradiction that is not one.
+//   Angular  Ivy compiles every class form to per-token addClass/removeClass, and the renderer
+//            joins the accumulated tokens into ONE string before routeProp.
+//   React    `className` is a string by convention.
+//   Svelte   `normalizeSvelteClass` (adapters/svelte/src/class-value.ts) joins a clsx-shaped
+//            value, and hands anything else through UNCHANGED — so Svelte never sends a class
+//            MAP, but it does send a non-string class, deliberately, and it is the one live
+//            producer of the branch below.
+//
+// An OBJECT here is not a class map at all — `IClassNameValue` types it as an IResolvedStyle, the
+// channel ScrollView / VirtualizedList / FlatList / ImageBackground use to hand a style through
+// the class prop, and Svelte's `resolveSvelteClass` exists to feed it. Canonicalising that into
+// tokens would not have been a category error only in theory: it would have hit a live producer on
+// four components, and they would have silently lost their styling. Do not "simplify" the object
+// branch away.
+//
+// What remains is an ARRAY of plain strings, which no adapter produces today and which reduces
+// fresh on every call, so it gets neither a pressed variant nor `isAlreadyPublished`. Narrow, and
+// closable by joining an all-string array before the string path — not done here.
+//
+// The identity reasoning underneath: the registry memoises a class STRING to the same object, and
+// `isAlreadyPublished` compares slot 0 with Object.is. A variant built from a value that resolves
+// fresh each call could never be turned away by the guard, and 1 000 unpressed rows would
+// republish and re-dirty — the storm the guard exists to stop.
+// Slot 1's twin of `baseStyleOf`. The variant stands in for the AUTHORED style, so it replaces
+// slot 1 and not slot 0 — it must beat the class cascade exactly the way the authored style does,
+// and a `:active` class rule must still be able to win slot 0 underneath it.
+function explicitStyleOf(parts) {
+    return parts.isPressed && parts.activeStyle !== undefined
+        ? parts.activeStyle
+        : parts.explicitStyle;
+}
+function baseStyleOf(parts) {
+    return parts.isPressed && typeof parts.className === 'string'
+        ? resolveActiveClassName(parts.className)
+        : parts.classStyle;
+}
+// Republish the merged style after one half changed. The halves are written IN PLACE by the
+// callers below - there is no patch object and no spread, because this is the hottest function in
+// the mutation API (9.3 ms self time and a large share of GC on a 4 000-row create, when it still
+// allocated a patch literal plus a merged copy per write).
+//
+// The fresh ARRAY is the one allocation that stays, and that is DELIBERATE - do not "finish the
+// optimization" by skipping when both halves are unchanged. The parts are a shadow copy of the
+// declarative style, and setNativeProps bypasses them (it writes node.props.style directly,
+// merging an Animated frame onto whatever is there). An app that hands over a hoisted style
+// constant - StyleSheet.create, a module-level object - would then re-push an identity-equal half,
+// get skipped by setProp's Object.is guard, and never restore the declarative style the animation
+// overwrote. The re-push IS the restore path.
+// Would `pushClassStyle` republish an array byte-identical to the one already standing? Reads the
+// last published array back out of `node.props.style` rather than remembering it in a field: that
+// array IS the record of what was published, so there is nothing to keep in sync, and no shape
+// change to the node or to IClassStyleParts.
+//
+// Sound because `pushClassStyle` is the ONLY writer of an array into that slot — both routeProp
+// branches and setNodeHidden funnel through it — so a foreign array cannot be mistaken for ours,
+// and a node whose props are still empty holds `undefined`, which is not an array, so the first
+// write can never be swallowed.
+function isAlreadyPublished(node, parts) {
+    const published = node.props.style;
+    if (!Array.isArray(published))
+        return false;
+    // `baseStyleOf`, not `parts.classStyle` — the guard and the publication must read slot 0 the
+    // same way or a press is turned away as already-published and silently does nothing on device
+    // while the behavior fires correctly and nothing goes red.
+    if (!Object.is(published[0], baseStyleOf(parts)))
+        return false;
+    // Through the resolver for the same reason as slot 0 above: guard and publication must agree, or
+    // a press is turned away as already-published and does nothing on device with nothing red.
+    if (!Object.is(published[1], explicitStyleOf(parts)))
+        return false;
+    return parts.hiddenStyle === undefined
+        ? published.length === 2
+        : published.length === 3 && Object.is(published[2], parts.hiddenStyle);
+}
+function pushClassStyle(node, parts) {
+    // The fresh array below can never be turned away by setProp's Object.is guard, so without this
+    // an UNCHANGED class still lands as a write AND marks the node dirty. Costs React / Vue / Svelte
+    // nothing — each diffs props before calling the engine — but Solid has no diff: a fine-grained
+    // effect re-runs whenever any signal it reads changes, so a list-wide signal makes every row
+    // re-push its own unchanged class. Measured on device 2026-08-23 (examples/solid, after
+    // host-primitive lowering): selecting one row of 1 000 read WRITES 1001 and a 10.3 ms reconcile
+    // window against Fabric's unmoved 0/0/10 — a thousand-node dirty walk for two nodes of change.
+    // Before lowering, the View component's splitProps/mergeProps memos had been absorbing it.
+    //
+    // This is NOT the naive skip the paragraph above forbids, and the array check is the difference.
+    // Skipping on "the parts are unchanged" alone would break the restore path, because
+    // setNativeProps writes node.props.style directly and a hoisted style constant would then never
+    // be restored. But setNativeProps writes an OBJECT (commit.ts: `{...flattenStyle(prev),
+    // ...flattenStyle(value)}`), never an array — so after any bypass isAlreadyPublished is false,
+    // the re-push happens exactly as before, and the restore path is untouched.
+    //
+    // Exact rather than approximate: resolveClassName memoizes a class STRING to the same object, so
+    // an unchanged class yields an identity-equal classStyle. It deliberately does not fire for an
+    // object/array class value, which resolves fresh every call — the same place setProp's Object.is
+    // already gives up on a style object, so no new asymmetry appears.
+    if (isAlreadyPublished(node, parts))
+        return;
     // The third slot is APPENDED ONLY WHILE HIDDEN. Writing a permanent three-element array would
     // change the style payload of every node in every app for a state almost none of them are ever
     // in — and this project spent a day removing per-frame allocations, so a slot that is undefined
     // 99.9% of the time does not get to ride along on every style write.
-    setProp(node, 'style', entry.hiddenStyle === undefined
-        ? [entry.classStyle, entry.explicitStyle]
-        : [entry.classStyle, entry.explicitStyle, entry.hiddenStyle]);
+    setProp(node, 'style', parts.hiddenStyle === undefined
+        ? [baseStyleOf(parts), explicitStyleOf(parts)]
+        : [baseStyleOf(parts), explicitStyleOf(parts), parts.hiddenStyle]);
 }
 // `display: 'none'` is a real RN style value (Yoga's DisplayNone), so a hidden node keeps its
 // place in the tree, its state and its children — it just stops laying out and painting.
@@ -265,14 +661,34 @@ const HIDDEN_STYLE = { display: 'none' };
  * author's style byte for byte — belongs to whoever owns the style merge, and that is here.
  */
 export function setNodeHidden(node, hidden) {
-    commitClassStyle(node, { hiddenStyle: hidden ? HIDDEN_STYLE : undefined });
+    const parts = stylePartsOf(node);
+    parts.hiddenStyle = hidden ? HIDDEN_STYLE : undefined;
+    pushClassStyle(node, parts);
+}
+/**
+ * Put a node into (or out of) its pressed state, so `.x:active` rules apply.
+ *
+ * The engine-owned half of what `:active` is on the web: the press state resolves BELOW the
+ * framework and never crosses into it, which is what lets a pressable be an intrinsic tag rather
+ * than a component (`.claude/rules/host-primitive-tier.md`, tier 2). A component is forced only
+ * when the TEMPLATE must read the state — `v-slot="{ pressed }"` and the function form of `style`
+ * — and this exists so the common case does not have to.
+ *
+ * Costs nothing when no `:active` rule is registered anywhere: `resolveActiveClassName` hands back
+ * the very same object the unpressed path returns, so `isAlreadyPublished` turns the re-push away
+ * and the node is never dirtied.
+ */
+export function setNodePressed(node, pressed) {
+    const parts = stylePartsOf(node);
+    parts.isPressed = pressed;
+    pushClassStyle(node, parts);
 }
 // The explicit (non-class-derived) style half, for an adapter that builds its style prop up
 // key-by-key (Angular's Ivy ɵɵstyleProp/setStyle) instead of handing over one whole object —
 // it must merge onto this, not onto node.props.style directly, which may be the
 // [classStyle, explicitStyle] array commitClassStyle writes above.
 export function getExplicitStyle(node) {
-    return classStyleParts.get(node)?.explicitStyle;
+    return node.styleParts?.explicitStyle;
 }
 const CLASS_PROP_KEYS = new Set(['class', 'className']);
 // The flat-bag split (React / Vue / Solid): an `onX` prop becomes an event listener
@@ -282,17 +698,104 @@ const CLASS_PROP_KEYS = new Set(['class', 'className']);
 export function routeProp(node, key, value) {
     if (REACT_JSX_DEV_PROPS.has(key))
         return;
+    // The prop twin of the child redirect in `appendChild`. A composed primitive's owner is written
+    // with props that belong to its internal slot — `contentContainerStyle` on a ScrollView styles
+    // the content view — and the adapter names the OWNER for a prop for the same reason it names the
+    // owner for a child: that is where the app wrote it.
+    //
+    // Gated on the FIELD, so a node with no slot pays one load and one branch and never touches the
+    // registry. The redirected write recurses into the slot's own `routeProp`, which is single-hop
+    // by construction: a slot has no slot of its own (`childHost` is documented single-hop, and
+    // `buildStructure` is what would have to nest one).
+    if (node.childHost !== undefined) {
+        const slotKey = slotPropNameFor(node, key);
+        if (slotKey !== undefined) {
+            // A class NAME is a legal spelling of `contentContainerStyle` — every canary writes
+            // `contentContainerStyle="scroll-content"` — so a string has to land on the slot as a
+            // CLASS. Only the class branch consults the registry; renaming it verbatim would publish a
+            // `style` holding a string, which is not a style and is dropped with nothing red. React's
+            // wrapper resolves the name itself (components/scroll-view/shared.ts), so this gap could
+            // only ever show on the tag path.
+            routeProp(node.childHost, slotKey === 'style' && typeof value === 'string' ? 'class' : slotKey, value);
+            return;
+        }
+    }
+    // An AnimatedNode written straight into a prop — `<view style={{opacity: value}}/>` — is
+    // resolved here into the value to PUBLISH, with the engine holding the subscription. Same
+    // shape as the `style` callback below: a value the engine interprets rather than forwards.
+    // Returns its input by identity when nothing is animated, so every branch under this line is
+    // unchanged. See `animated/host-binding.ts`; the gate is one boolean for an app that animates
+    // nothing.
+    //
+    // AFTER the slot redirect, so an animated `contentContainerStyle` binds on the node that
+    // actually carries the style.
+    const resolved = hasAnimatedNodes()
+        ? bindAnimatedValue(node, key, value)
+        : value;
     if (CLASS_PROP_KEYS.has(key)) {
-        commitClassStyle(node, {
-            classStyle: resolveClassName(isClassNameValue(value) ? value : undefined),
-        });
+        const parts = stylePartsOf(node);
+        // Canonicalised HERE so the stored value is what everything downstream keys on: an all-string
+        // array becomes one string, and then the pressed variant and isAlreadyPublished work on it
+        // exactly as on an authored string. One `typeof` for the common case.
+        parts.className = canonicalClassName(isClassNameValue(resolved) ? resolved : undefined);
+        parts.classStyle = resolveClassName(parts.className);
+        pushClassStyle(node, parts);
         return;
     }
     if (key === 'style') {
-        commitClassStyle(node, { explicitStyle: value });
+        const parts = stylePartsOf(node);
+        // A FUNCTION `style` is `style={({pressed}) => …}`, the idiom this ecosystem actually writes.
+        // A lowering transform normally splits it at build time into `style` + `activeStyle`, so the
+        // engine never sees the callback — but a PUBLIC primitive tag has no transform in front of it
+        // on three adapters, and there the callback arrives here intact. Resolving it makes the
+        // compile-time split an OPTIMIZATION rather than the mechanism, the same relationship
+        // `foldHostBag` has with the compile-time prop folds.
+        //
+        // Without this the failure is silent and total: a function is not an `on*` name, so it misses
+        // `setEventListener`, lands in `setProp` as a function value, and `fabricProps` drops function
+        // props — the node commits with NO style at all. Traced by the Solid session, 2026-09-01.
+        //
+        // The callback must be PURE in `pressed`: its result is read once per state, here and under
+        // every transform's emission (`core/components/src/state-style.ts` carries the same contract).
+        if (isStyleCallback(resolved)) {
+            parts.explicitStyle = resolved({ pressed: false });
+            parts.activeStyle = resolved({ pressed: true });
+            parts.activeStyleFromCallback = true;
+        }
+        else {
+            parts.explicitStyle = resolved;
+            // Only a variant WE derived is stale now. `style` switching from a callback to a plain value
+            // must not leave the old pressed look standing, and an `activeStyle` the transform wrote must
+            // survive a `style` write, because the two arrive as independent props in an unspecified
+            // order.
+            if (parts.activeStyleFromCallback) {
+                parts.activeStyle = undefined;
+                parts.activeStyleFromCallback = false;
+            }
+        }
+        pushClassStyle(node, parts);
+        return;
+    }
+    // Ours, never Fabric's — it is consumed here and must not reach the payload, or every pressable
+    // in the app carries an unknown key to native.
+    if (key === 'activeStyle') {
+        const parts = stylePartsOf(node);
+        parts.activeStyle = resolved;
+        // Slot 1 is no longer ours, by definition — whatever a callback derived earlier has just been
+        // replaced. Without this the flag outlives the value it describes: a callback sets it, this
+        // branch overwrites the slot silently, and a later plain `style` then clears a variant the
+        // engine never derived. Not reachable from a lowering transform (it emits either a callback or
+        // an explicit pair, never both for one node), but a flat-bag adapter routes a bag key by key
+        // and can deliver exactly that sequence.
+        parts.activeStyleFromCallback = false;
+        pushClassStyle(node, parts);
         return;
     }
     if (ON_PREFIX.test(key)) {
+        // A native-driven `Animated.event` needs the native module as well as the listener map, and
+        // registers under the PROP name — see `bindAnimatedEvent`, which no-ops for anything else.
+        if (hasAnimatedNodes())
+            bindAnimatedEvent(node, key, resolved);
         const name = listenerName(key);
         const isRegisteredEvent = RESPONDER_EVENTS.has(name) || isEventFor(node.component, name);
         // Investigation instrumentation (HeaderOptionsScreen unresponsive-buttons bug): RNS* views
@@ -305,11 +808,11 @@ export function routeProp(node, key, value) {
                 `registered=${isRegisteredEvent} at t=${Date.now()}`);
         }
         if (isRegisteredEvent) {
-            setEventListener(node, name, value);
+            setEventListener(node, name, resolved);
             return;
         }
     }
-    setProp(node, key, value);
+    setProp(node, key, resolved);
 }
 // The same no-op guard as setProp, and here it is strictly stronger: `text` is a string, so
 // `Object.is` is a real value comparison rather than the reference check it degrades to for a style
@@ -329,40 +832,204 @@ export function setText(node, text) {
     }
     node.props.text = text;
     propStats.writes += 1;
-    markDirty(node);
+    markPropsDirty(node);
 }
 // Structural ops mark the PARENT chain (both the old and the new one), never the moved child:
 // a child that only changed position may legitimately still be clean, and reconcile re-checks
 // `committed.parent` on its early-exit path, so a reparent is caught there rather than by a flag.
+//
+// Each marks BEFORE touching `parent.children`, never after: the committed record may be aliasing
+// that array, and markStructureDirty is what copies it out of the way. See there.
 function detach(child) {
     const parent = child.parent;
     if (!parent)
         return;
+    markStructureDirty(parent);
     const index = parent.children.indexOf(child);
     if (index >= 0)
         parent.children.splice(index, 1);
     child.parent = undefined;
-    markDirty(parent);
 }
-export function appendChild(parent, child) {
-    detach(child);
-    child.parent = parent;
-    parent.children.push(child);
-    markDirty(parent);
+// The one place a composed primitive's slot is honoured. See `ISymbioteNode.childHost`: the adapter
+// always names the OWNER, and a node whose behavior built an internal subtree redirects the app's
+// children into it.
+//
+// SINGLE HOP, not a loop, and the field's own comment says why — a chain would put a walk on the
+// engine's hottest path to express a depth no primitive has. A behavior needing depth points
+// `childHost` at the innermost node itself.
+//
+// Reads a field that is `undefined` on every node in every app that registers no composed
+// primitive, so the cost is one load and one branch — deliberately NOT behind `hasHostBehaviors()`,
+// which would be a second read to save nothing.
+// Which node a child actually lands on. See `ISymbioteNode.childHost`: the adapter always names the
+// OWNER, and a node whose behavior built an internal subtree redirects the app's children into it —
+// unless the behavior CLAIMS this particular child, which keeps it on the owner (`claimedChildren`).
+//
+// SINGLE HOP, not a loop, and the field's own comment says why — a chain would put a walk on the
+// engine's hottest path to express a depth no primitive has. A behavior needing depth points
+// `childHost` at the innermost node itself.
+//
+// Reads a field that is `undefined` on every node in every app that registers no composed
+// primitive, so the cost is one load and one branch — deliberately NOT behind `hasHostBehaviors()`,
+// which would be a second read to save nothing. The claim check sits BEHIND that branch, so only a
+// slot-bearing node ever pays the registry probe.
+function hostFor(parent, child) {
+    const slot = parent.childHost;
+    if (slot === undefined)
+        return parent;
+    // A slot that is a built SIBLING rather than a container — ImageBackground's absolutely-filled
+    // image — keeps the app's children on the owner. See `IHostBehavior.slotTakesNoChildren`.
+    if (!slotTakesChildren(parent))
+        return parent;
+    return claimModeFor(parent, child.component) === undefined ? slot : parent;
+}
+// What actually occupies this node's place in its parent's child list. See `ISymbioteNode.wrapper`:
+// a wrapped owner is what the adapter names and the wrapper is what the tree holds, so every
+// structural op takes the owner and moves the wrapper.
+function placedNode(node) {
+    return node.wrapper ?? node;
 }
-export function insertBefore(parent, child, beforeChild) {
+// Make `child` the owner's parent, in place. Returns false when this is not a wrap claim, so the
+// two inserts fall through to the ordinary path on one call.
+//
+// The owner being UNATTACHED is the normal case rather than the edge one: every adapter fills a
+// node's children before appending it to its own parent, so the wrap usually happens while
+// `owner.parent` is undefined and the swap below is skipped. The later `appendChild(root, owner)`
+// then inserts the wrapper instead, because `placedNode` says so.
+function wrapsOwner(owner, child) {
+    if (owner.childHost === undefined)
+        return false;
+    if (claimModeFor(owner, child.component) !== 'wrap')
+        return false;
+    if (hasHostBehaviors())
+        reattachHostBehaviors(child);
+    if (hasAnimatedBindings())
+        reattachAnimatedProps(child);
     detach(child);
-    child.parent = parent;
-    const index = parent.children.indexOf(beforeChild);
-    parent.children.splice(index < 0 ? parent.children.length : index, 0, child);
-    markDirty(parent);
+    const outerParent = owner.parent;
+    if (outerParent !== undefined) {
+        markStructureDirty(outerParent);
+        outerParent.children[outerParent.children.indexOf(owner)] = child;
+        child.parent = outerParent;
+    }
+    owner.wrapper = child;
+    owner.parent = child;
+    markStructureDirty(child);
+    child.children.push(owner);
+    notifyWrapChange(owner, child);
+    return true;
 }
-export function removeChild(parent, child) {
-    const index = parent.children.indexOf(child);
+// Put the owner back where its wrapper stood — the mirror of `wrapsOwner`. It must leave the owner
+// ATTACHED: the framework is removing the RefreshControl, not the ScrollView.
+function unwrapsOwner(owner, child) {
+    if (owner.wrapper !== child)
+        return false;
+    const outerParent = child.parent;
+    owner.wrapper = undefined;
+    if (outerParent !== undefined) {
+        markStructureDirty(outerParent);
+        outerParent.children[outerParent.children.indexOf(child)] = owner;
+    }
+    owner.parent = outerParent;
+    child.parent = undefined;
+    child.children.length = 0;
+    notifyWrapChange(owner, undefined);
+    return true;
+}
+// Where the child goes in its host's list.
+//
+// A host that STILL has a slot at this point is an owner taking a CLAIMED child, and that child
+// goes before the slot whatever the framework asked for. RN renders `{refreshControl}{content}` in
+// that order, and the node a framework names as `beforeChild` lives inside the slot, so `indexOf`
+// could not find it here anyway.
+function indexFor(host, beforeChild) {
+    const slot = host.childHost;
+    // A sibling slot is the OPPOSITE placement: RN paints the background image first and the app's
+    // children over it (ImageBackground.js:80-102), so they append past it rather than in front of
+    // it. Falls through to the ordinary index below, which is what leaves their relative order alone.
+    if (slot !== undefined && slotTakesChildren(host))
+        return host.children.indexOf(slot);
+    // `null` is Solid's spelling of "append"; `undefined` is `appendChild`'s own. Both end up here.
+    if (beforeChild === undefined || beforeChild === null)
+        return host.children.length;
+    const index = host.children.indexOf(beforeChild);
+    return index < 0 ? host.children.length : index;
+}
+export function appendChild(requestedParent, child) {
+    if (wrapsOwner(requestedParent, child))
+        return;
+    const parent = hostFor(requestedParent, child);
+    // A node the sweep tore down can be put back — Svelte parks live subtrees offscreen across
+    // commits. A WeakSet miss for anything freshly built, so the create path pays nothing.
+    if (hasHostBehaviors())
+        reattachHostBehaviors(child);
+    if (hasAnimatedBindings())
+        reattachAnimatedProps(child);
+    const placed = placedNode(child);
+    detach(placed);
+    markStructureDirty(parent);
+    placed.parent = parent;
+    if (parent.childHost !== undefined) {
+        parent.children.splice(indexFor(parent, undefined), 0, placed);
+    }
+    else {
+        parent.children.push(placed);
+    }
+    if (hasHostBehaviors())
+        notifyChildInserted(parent, placed);
+}
+// `beforeChild` is genuinely nullable and the signature used to say otherwise: Solid's renderer
+// spells "append" as `insertBefore(parent, child, null)`, which worked by accident because
+// `indexOf(null)` is -1 and the old fallback appended. Reading a field off it is what made the lie
+// fatal, so the type now says what the callers do.
+export function insertBefore(requestedParent, child, beforeChild) {
+    if (wrapsOwner(requestedParent, child))
+        return;
+    const parent = hostFor(requestedParent, child);
+    if (hasHostBehaviors())
+        reattachHostBehaviors(child);
+    if (hasAnimatedBindings())
+        reattachAnimatedProps(child);
+    const placed = placedNode(child);
+    detach(placed);
+    markStructureDirty(parent);
+    placed.parent = parent;
+    parent.children.splice(indexFor(parent, beforeChild === null ? null : placedNode(beforeChild)), 0, placed);
+    if (hasHostBehaviors())
+        notifyChildInserted(parent, placed);
+}
+// Removal only NOMINATES a behavior for teardown; the commit sweep decides. A framework may spell
+// a move as remove-then-reinsert (Solid does), so tearing down here kills the machine of a node
+// that comes back alive in the same batch — see host-behavior.ts's markDetachCandidate.
+export function removeChild(requestedParent, child) {
+    // Redirected for the same reason the two inserts are: the adapter removes from the node it
+    // appended to, which is the OWNER, while the child actually lives in the slot. Without this the
+    // `indexOf` misses, the splice no-ops, and the child stays committed under the slot forever
+    // while the framework believes it is gone — a leak with nothing red anywhere.
+    //
+    // A wrap claim leaving: the owner takes its own place back and stays in the tree. Nominated for
+    // teardown like any other removed node, because the wrapper IS leaving.
+    if (unwrapsOwner(requestedParent, child)) {
+        if (hasHostBehaviors() || hasAnimatedBindings())
+            markDetachCandidate(child);
+        return;
+    }
+    // A slot that IS the child being removed stops being one. Only a behavior that adopts an APP
+    // child as its slot can reach this (`onChildInserted`); a `buildStructure` slot is internal and
+    // no framework removes it. Without the clear, `hostFor` below redirects the removal INTO the very
+    // node being removed, `indexOf` misses, the splice no-ops, and the child stays committed under a
+    // parent the framework believes it left — and the NEXT child appended nests inside the orphan.
+    if (requestedParent.childHost === child)
+        requestedParent.childHost = undefined;
+    const parent = hostFor(requestedParent, child);
+    if (hasHostBehaviors() || hasAnimatedBindings())
+        markDetachCandidate(child);
+    markStructureDirty(parent);
+    const placed = placedNode(child);
+    const index = parent.children.indexOf(placed);
     if (index >= 0)
         parent.children.splice(index, 1);
     child.parent = undefined;
-    markDirty(parent);
 }
 export function censusRetainedTree(roots) {
     const census = {