@symbiote-native/engine 1.3.0 → 1.3.1

package/build/fabric-props.js

@@ -1,41 +1,13 @@
 // Fabric-prop translation: turn a node's logical props into the flat payload Fabric's C++ props
-// expect. Color processing itself lives in ./platform-color (the stable leaf every color-touching
-// module imports from); this file only decides WHICH props are color props and wires the structured
-// CSS-style processors.
-//
-// IT IS CALLED BY THE HOST, and that is what the `props` parameter is for. The NODE still comes in
-// beside it for its authored component name and for a behavior's own `payloadFold`.
-//
-// **THIS IS THE HEADLESS BUILDER, and the device one is `SymbioteFabricProps.cpp`.** The header used
-// to say the C++ side "does not have this yet", which was true mid-branch and stopped being true
-// when the payload builder was ported; a reader who believed it would go looking for a blank screen.
-//
-// What follows from that, and it is the file's main rule: **no platform rule may live here.** The ten
-// tag rules never got a copy, and RN's two Text defaults lost theirs on 2026-09-18. A rule with a
-// copy on this side is a rule whose only test runs on this side, and the device copy can then break
-// with everything green — not hypothetical: it is how a disabled `touchable-highlight` shipped
-// `focusable: true`.
-//
-// **NONE IS LEFT, as of 2026-09-18.** Three went, one per commit, in that order: RN's Text defaults,
-// `value ?? defaultValue -> text`, and the aria fold. Separately on purpose — they had different test
-// topologies, and one commit removing several could not be attributed to any of them.
-//
-// SO THE HEADLESS PAYLOAD DIVERGES FROM THE DEVICE'S, deliberately and in named places: a text
-// input's carries `value` where the device's carries `text`, a text node's is missing two defaults,
-// and a bare tag's `aria-*` keys arrive unfolded. **That asymmetry is the harness working as
-// designed** — it is what forces a claim about a platform rule to be made where the rule runs. Do
-// not close it by adding a rule back.
-//
-// What is left is the framework-agnostic half: colour processing, the style hoist, and a node's own
-// `payloadFold`.
+// expect. Color processing lives in ./platform-color (the stable leaf every color-touching module
+// imports from); this file only decides WHICH props are color props.
 import { RAW_TEXT_COMPONENT } from './node.js';
 import { isProcessableColor, processColor } from './platform-color';
 import { configProcessedKeys } from './registry.js';
 import { isRecord } from './type-guards.js';
-// Color props must reach Fabric as platform ints, not CSS strings. Fabric's C++
-// color parser silently drops strings. The actual conversion (processColor) is
-// RN-platform-specific, so it is injected in platform-color.ts rather than imported,
-// keeping shared free of a react-native dependency (and the headless harness working).
+// Color props must reach Fabric as platform ints, not CSS strings — Fabric's C++ color parser
+// silently drops strings. processColor is RN-platform-specific, so it's injected from
+// platform-color.ts rather than imported, keeping this module free of a react-native dependency.
 const COLOR_PROPS = new Set([
     'backgroundColor',
     'color',
@@ -68,11 +40,9 @@ const COLOR_PROPS = new Set([
     // Text decoration color (underline/strike): same Fabric strictness as any color.
     'textDecorationColor',
     'selectionHandleColor',
-    // Switch track/thumb colors. RN processColors each via the Switch ViewConfig
-    // (SwitchNativeComponent / AndroidSwitchNativeComponent validAttributes). iOS takes
-    // onTintColor (ON) / tintColor (OFF); Android takes trackColorForTrue/False +
-    // trackTintColor, and Android's ColorPropConverter is strict ("the value must be a
-    // number or Object"), so a raw CSS string crashes. thumbTintColor reaches both.
+    // Switch track/thumb colors. RN processColors each via the Switch ViewConfig; Android's
+    // ColorPropConverter is strict ("must be a number or Object"), so a raw CSS string crashes.
+    // thumbTintColor reaches both platforms.
     'onTintColor',
     'thumbTintColor',
     'trackColorForTrue',
@@ -80,50 +50,33 @@ const COLOR_PROPS = new Set([
     'trackTintColor',
 ]);
 // Convert a prop to the shape Fabric's C++ expects: a CSS-string color runs through the injected
-// platform processor, because Fabric's C++ color parser silently drops strings.
-//
-// TWO FAMILIES OF PROCESSOR USED TO BE HERE AND BOTH MOVED, for one reason: on a device the payload
-// is built in C++ and this function does not run, so anything resolved only here is resolved only
-// headless. A third-party view's own `validAttributes[*].process` now runs in `configPayloadFold`
-// (installed on the node, called by the C++ through `payloadFold`); the structured style keys
-// — boxShadow, filter, transform, transformOrigin, aspectRatio, fontVariant,
-// experimental_backgroundImage — now run at WRITE time in `structured-style.ts`, so `node.props`
-// already holds the structured value whichever builder reads it.
-//
+// platform processor, since Fabric's C++ color parser silently drops strings.
+// Any other processor must NOT live here: on a device the payload is built in C++ and this
+// function never runs, so anything resolved only here is resolved only headless. A third-party
+// view's own config processors run in configPayloadFold; structured style keys run at write time.
 // Neither may come back here. Applying a processor twice is not a no-op: a color already converted
-// to a platform int, run through processColor again, is a DIFFERENT color.
+// to a platform int, run through processColor again, is a different color.
 function processValue(key, value, alreadyProcessed) {
-    // A key the component's own config already converted is DONE. Running the engine's colour pass
-    // over it as well is not a no-op: processColor rotates, so a second rotation is a different
-    // colour. This used to be prevented by accident — a processed colour is a number, and numbers
-    // were not processable — until a numeric colour became an author's own rrggbbaa literal.
+    // A key the component's own config already converted is done. Running the colour pass over it
+    // too is not a no-op: processColor rotates, so a second rotation is a different colour.
     if (alreadyProcessed?.has(key) === true)
         return value;
     if (COLOR_PROPS.has(key) && isProcessableColor(value))
         return processColor(value);
     return value;
 }
-// A style object is SHARED, and that is the one place this file has a complexity problem rather
-// than a constant-factor one. StyleSheet.create hands out one frozen object per rule, and the CSS
-// class registry resolves a class name to one cached object - so 1 000 rows carry the SAME handful
-// of style objects, and resolving each one per node costs O(nodes x styleKeys) to compute an
-// answer that only varies with O(distinct styles). Cache it on the style object's identity.
-//
-// Keyed by the style object ALONE. It used to carry a per-component dimension because processValue
-// consulted that component's ViewConfig processors and one style object could resolve differently
-// under two view names; those processors moved to `configPayloadFold`, which runs on the top-level
-// bag before this, so what is left here is component-independent.
-//
-// The cache assumes a style object is not MUTATED IN PLACE, which is already the engine's contract:
-// setProp compares with Object.is and skips a same-identity write, so an in-place style edit never
-// marks the node dirty and never reaches Fabric today either. What narrows slightly is the case
-// where some OTHER prop on the same node changed in the same commit - that used to pick the
-// mutation up as a side effect, and now does not.
-//
-// KEEPING undefined-valued keys is deliberate: the resolved object is a faithful picture of ONE
-// style entry, and addStyle below needs to see an explicit `undefined` to let a later entry clear
-// an earlier one. Dropping them here would silently turn `[{flex:1},{flex:undefined}]` into
-// `flex: 1`.
+// A style object is shared: StyleSheet.create hands out one frozen object per rule, and the CSS
+// class registry resolves a class name to one cached object, so a thousand rows carry the same
+// handful of style objects. Cache resolution on the style object's identity.
+// Keyed by the style object alone: the per-component ViewConfig processors that once made one
+// style object resolve differently under two view names moved to configPayloadFold, which runs on
+// the top-level bag before this, so what's left here is component-independent.
+// Assumes a style object is not mutated in place, which is already the engine's contract: setProp
+// compares with Object.is and skips a same-identity write, so an in-place edit never marks the
+// node dirty and never reaches Fabric either way.
+// Keeping undefined-valued keys is deliberate: the resolved object is a faithful picture of one
+// style entry, and addStyle below needs to see an explicit undefined to let a later entry clear an
+// earlier one — dropping them would silently turn [{flex:1},{flex:undefined}] into `flex: 1`.
 const styleCache = new WeakMap();
 function processedStyle(style) {
     const cached = styleCache.get(style);
@@ -132,43 +85,23 @@ function processedStyle(style) {
     const resolved = {};
     for (const key of Object.keys(style)) {
         const value = style[key];
-        // `undefined` for the already-processed set, and it must stay that way: this cache is keyed on
-        // the style object ALONE (see the note above), so anything component-dependent read here would
-        // be shared with every other component using the same style object. A config's processors are
-        // keyed on top-level prop names and never reach inside a style anyway.
+        // undefined for the already-processed set: this cache is keyed on the style object alone, so
+        // anything component-dependent read here would be shared with every user of that object.
         resolved[key] =
             value === undefined ? undefined : processValue(key, value, undefined);
     }
     styleCache.set(style, resolved);
     return resolved;
 }
-/**
- * Hoist one style slot's keys into the payload being built, recursing on POSITION only - the same
- * rule flattenStyle follows, and for the same reason: `transform: [{translateX: 5}]` is an
- * array-VALUED prop, not a nested style.
- *
- * The point is that there is no intermediate object. Every style entry's resolution is memoized on
- * its own identity and its keys are written straight into `out`, so a thousand rows sharing one
- * class-resolved style resolve it ONCE and each node pays a copy loop.
- *
- * This is also the shape React Native itself uses. `ReactNativeAttributePayload.addNestedProperty`
- * (.vendors/react/packages/react-native-renderer/src/ReactNativeAttributePayload.js:208) recurses
- * over the style array writing into a single `updatePayload`; upstream's `flattenStyle` appears
- * ONLY in `diffNestedProperty`, i.e. the update path where an array meets an object - never on
- * create. Our previous version flattened first and hoisted second, which allocated one merged
- * object per node per commit that nothing else ever read.
- *
- * It also fixed a dead cache. `processedStyle` used to be reachable only when `props.style` was a
- * bare object, and it never is: `commitClassStyle` (node.ts) always writes the two-element
- * `[classStyle, explicitStyle]` array, by design. So the memo existed, was correct, and never ran.
- *
- * Later entries win, because a later write overwrites the same key on `out`. An explicit
- * `undefined` CLEARS the key instead, matching the flatten path it replaces. One narrow
- * divergence, recorded rather than hidden: the `delete` also clears a same-named TOP-LEVEL prop
- * hoisted before the style pass, which flattening did not. Style keys and native prop keys do not
- * overlap in practice (one is Yoga/visual, the other is testID/accessibility/source), so this is
- * theoretical - but it is a difference, and `fabric-props.test.ts` pins both halves.
- */
+// Hoist one style slot's keys into the payload being built, recursing on position only — the same
+// rule flattenStyle follows, and for the same reason: `transform: [{translateX: 5}]` is an
+// array-valued prop, not a nested style.
+// No intermediate object: every style entry's resolution is memoized on its own identity and its
+// keys are written straight into `out`, so a thousand rows sharing one class-resolved style
+// resolve it once and each node only pays a copy loop.
+// Later entries win, because a later write overwrites the same key on `out`. An explicit
+// undefined clears the key instead — the one narrow divergence from flattenStyle is that this also
+// clears a same-named top-level prop hoisted before the style pass, pinned by fabric-props.test.ts.
 function addStyle(out, style) {
     if (Array.isArray(style)) {
         for (const entry of style)
@@ -186,93 +119,55 @@ function addStyle(out, style) {
             out[key] = value;
     }
 }
-// Translate the retained node's logical props into the flat payload Fabric's C++
-// props expect: `style` keys are hoisted to the top level, event handlers and
-// undefined values are dropped.
-// RN HAS NO `value` FABRIC PROP. A TextInput's controlled value rides as the private `text` prop,
-// and the fold that produces it — `value ?? defaultValue` — used to live in the component wrapper.
-// A tag has no wrapper, so an author's `value={x}` would reach Fabric as a key no ViewConfig
-// declares: silently dropped, `text` never set, and the field renders EMPTY. Nothing red anywhere —
-// found 2026-08-31 by an agent reading what the render function actually emitted rather than
-// trusting a header comment.
-//
-// So the fold lives in the layer every path goes through, exactly like the aria fold above it. This
-// is the third instance of one rule: a tag inherits NOTHING a wrapper did, and the repair belongs
-// below the fork.
-//
-// GATED ON THE COMPONENT, NOT ON THE PROP. `value` is also a prop of `Switch` and `Slider`; a fold
-// keyed on the prop name would write a bogus `text` onto both. Two string comparisons rather than a
+// Translate the retained node's logical props into the flat payload Fabric's C++ props expect:
+// style keys are hoisted to the top level, event handlers and undefined values are dropped.
+// RN has no `value` Fabric prop: a TextInput's controlled value rides as the private `text` prop,
+// via a `value ?? defaultValue` fold a wrapper used to run. A tag has no wrapper, so this fold
+// lives here instead — the same "a tag inherits nothing a wrapper did" rule as the aria fold above.
+// Gated on the component, not the prop: `value` is also a prop of Switch and Slider, and a fold
+// keyed on the prop name would write a bogus `text` onto both.
 export function fabricProps(node, nodeProps) {
     if (node.component === RAW_TEXT_COMPONENT) {
-        // A raw-text node gets its behavior's fold too — it TRANSFORMS the text that is already there
-        // (Button uppercases its label on Android) and may not SUPPLY one, which is narrower than this
-        // comment claimed when it landed. `isEmptyRawText` (node.ts) decides whether the node commits
-        // at all from the node's own `text` prop, before any fold runs, so a text that exists only as a fold
-        // result is dropped by `renderableChildren` and the fold never executes. Reported by the hook's
-        // first consumer, within the hour.
-        //
-        // Which is why the skip is NOT the thing to change: it runs for every raw-text node in every
-        // app, and consulting a fold there would put one on that walk. Get the value into `props.text`
-        // instead — Button routes the owner's `title` onto this node with `slotProps: {title: 'text'}`,
-        // so the skip and the fold read the same source and an empty title still commits nothing.
+        // A raw-text node gets its behavior's fold too — it transforms text already there (Button
+        // uppercases its label) but may not supply one: isEmptyRawText decides whether the node
+        // commits at all from the node's own text prop, before any fold runs.
+        // So the skip is not the thing to change — it runs for every raw-text node in every app. Get
+        // the value into props.text instead: Button routes its owner's title here via slotProps, so
+        // the skip and the fold read the same source.
         return {
             text: node.payloadFold !== undefined
                 ? node.payloadFold(nodeProps).text
                 : nodeProps.text,
         };
     }
-    // This runs once per node per commit - 9 000 times on one benchmark press - so the two loops
-    // below iterate with Object.keys rather than Object.entries: entries allocates a fresh
-    // two-element array PER KEY on top of the outer array, and the resulting garbage was 18% of the
-    // create path in a CPU profile.
-    //
-    // Do NOT "improve" this to `for...in`. It was tried and reverted 2026-08-23. On paper it is the
-    // strictly cheaper shape - Object.keys allocates one array per call, 10 007 of them on a
-    // 1 000-row create (counted), and for...in allocates none - and the headless V8 bench agreed,
-    // 12-13% off create/replace `min`. On DEVICE it lost: with the Fabric call counts and prop-key
-    // payload byte-identical either way (9000/5000/1009, 32001 keys), Release Create went 217.8 ->
-    // 243.2 ms while stock moved only inside its 4% noise floor. Hermes' for-in is not V8's enum
-    // cache. The general rule this bought: an allocation-count win measured on V8 is not a Hermes
-    // win, and only the on-device number decides (`perf-claims-need-numbers`).
+    // This runs once per node per commit, so the two loops below iterate with Object.keys rather
+    // than Object.entries: entries allocates a fresh two-element array per key on top of the outer
+    // array, measured as a real share of the create path's garbage.
+    // Do not "improve" this to for...in: tried and reverted. It wins on allocation count and even on
+    // headless V8 benchmarks, but loses on device — Hermes' for-in is not V8's enum cache, and only
+    // the on-device number decides.
     const out = {};
-    // THE ONE POINT WHERE THE WHOLE BAG IS KNOWN ON EVERY PATH, which is what the aria fold needs:
-    // `aria-checked` has to be folded against a sibling `accessibilityState`, and `routeProp` sees
-    // one key at a time. Both commit paths — create and update — reach here, so a tag gets the fold
-    // it has no wrapper to run.
-    //
-    // NOT memoised on the bag's identity. The host mutates it IN PLACE, so an identity-keyed cache
-    // (the `processedStyle` pattern below) would be stale forever. The gate is the node's sticky flag
-    // instead: one boolean read for a node with no alias, which is nearly all of them, and the fold's
-    // own fast path returns by identity for the rest.
-    // THE ARIA FOLD IS NOT CALLED HERE ANY MORE (2026-09-18), and it is the last platform rule to
-    // leave this builder. `foldAriaProps` itself STAYS in JS and is not a mirror: `pickAccessibilityProps`
-    // (`@symbiote-native/components`) folds a bag and then picks fields BY NAME, which it cannot do
-    // from a bag holding only `aria-label`. So the function has a real, load-bearing caller — what was
-    // wrong was this CALL, which put a rule the device runs in C++ back into the headless payload and
-    // invited 27 cases to assert it where the device copy is invisible.
-    //
-    // Where the claims live now: `core/engine/cpp/tests/js/aria-payload.itest.ts`, off a real payload.
+    // The one point where the whole bag is known on every path, which the aria fold needs:
+    // aria-checked must fold against a sibling accessibilityState, and routeProp sees one key at a
+    // time. Both commit paths reach here, so a tag gets the fold it has no wrapper to run.
+    // Not memoised on the bag's identity — the host mutates it in place, so an identity-keyed cache
+    // would be stale forever. The gate is the node's sticky flag instead, one boolean read for a
+    // node with no alias (nearly all of them); the fold's own fast path handles the rest.
     const aliasFolded = nodeProps;
-    // The behavior's own fold, keyed on the TAG — the two folds above are keyed on the resolved
-    // component name, which several tags share (`pressable` and a plain `view` are both `RCTView`),
-    // so neither could carry a per-primitive fold. See IPayloadFold.
-    //
-    // THE FOLD'S RETURN REPLACES THE BAG, and it costs more than it looks — see
-    // `payload-fold-merge.test.ts` for the measurement and for why the obvious fix does not fit yet.
-    // Briefly: every fold returns `{ ...props, ...whatItChanged }`, and on device reading that back is
-    // `jsi::dynamicFromValue`, 13.3 ms of a 17.8 ms fold phase against 1.6 ms to send the bag out and
-    // 1.6 ms to run the fold.
+    // The behavior's own fold, keyed on the tag — the two folds above are keyed on the resolved
+    // component name, which several tags share (pressable and a plain view are both RCTView), so
+    // neither could carry a per-primitive fold. See IPayloadFold.
+    // The fold's return REPLACES the bag, which costs more than it looks (payload-fold-merge.test.ts
+    // has the measurement): every fold returns `{ ...props, ...whatItChanged }`, and reading that
+    // back on device dominates the fold phase.
     const behaviorFolded = node.payloadFold !== undefined
         ? node.payloadFold(aliasFolded)
         : aliasFolded;
-    // RN'S TWO TEXT DEFAULTS USED TO BE APPLIED HERE AND ARE GONE (2026-09-18) — the rule lives in
-    // `SymbioteFabricProps.cpp` alone, and its claims in `committed-payload.itest.ts`, read off the
-    // payload a commit actually sent. It had FIVE other implementations that day (`resolveTextProps`,
-    // Angular's `TextHost`, Vue's and Solid's renderers, and this one); the engine is the only layer
-    // that can see the authored bag for every adapter at once, so it is the only one that needs to.
-    //
-    // So a text node's payload here is missing two keys the device's carries. That is a PROPERTY of
-    // this harness rather than a gap in it — do not close it by adding the rule back.
+    // RN's two text defaults are NOT applied here — the rule lives in SymbioteFabricProps.cpp alone,
+    // pinned by committed-payload.itest.ts off a real payload. The engine is the only layer that can
+    // see the authored bag for every adapter at once, so it's the only one that needs the rule.
+    // So a text node's payload here is missing two keys the device's carries. That is a property of
+    // this harness, not a gap in it — do not close it by adding the rule back.
     const props = behaviorFolded;
     // Hoisted out of the loop: one cached lookup per node per commit, not one per key.
     const alreadyProcessed = configProcessedKeys(node.component);

package/build/fabric.d.ts

@@ -34,23 +34,10 @@ interface IFabricHost extends Omit<IFabricSlot, 'cloneNodeWithNewChildren' | 'cl
     cloneNodeWithNewChildrenAndProps(node: IFabricNode, children: readonly IFabricNode[], newProps: IFabricProps): IFabricNode;
     findShadowNodeByTag_DEPRECATED?(tag: number): IFabricNode | null;
 }
-/**
- * An accessibility event addressed by a bare native TAG, the way RN's bridgeless
- * `UIManager.sendAccessibilityEvent` does it: resolve the tag to its committed shadow node, then send.
- * An unknown tag is dropped, as RN drops it (with a log rather than a throw).
- */
 export declare function sendAccessibilityEventByTag(tag: number, eventType: string): void;
 declare global {
     var nativeFabricUIManager: IFabricHost | undefined;
 }
-/**
- * Test seam: forget the bound slot, so a fixture can install a different host and be believed.
- *
- * `getSlot` caches the facade for the life of the module — the live binding re-mints a host function
- * on every property read, so caching is not an optimisation but the difference between reading each
- * method once and reading it per call. The cache has no invalidation in production because the
- * global is installed once, before anything commits.
- */
 export declare function resetSlot(): void;
 export declare function getSlot(): IFabricSlot;
 export {};

package/build/fabric.js

@@ -1,16 +1,11 @@
-// The one seam symbiote drives. `global.nativeFabricUIManager` is the
-// framework-agnostic, JSI-bound mutation API that Fabric exposes; React's
-// renderer is just one client of it. We bind to it directly.
-//
-// The live object is a lazy caching proxy: every property access mints a fresh
-// host function, so we read each method once and cache a plain facade.
+// The one seam symbiote drives. global.nativeFabricUIManager is the framework-agnostic, JSI-bound
+// mutation API Fabric exposes; React's renderer is just one client of it. We bind to it directly.
+// The live object is a lazy caching proxy, so we read each method once and cache a plain facade.
 import { dlog } from './debug.js';
 import { installNativeTreeHost } from './native-tree-host.js';
-/**
- * An accessibility event addressed by a bare native TAG, the way RN's bridgeless
- * `UIManager.sendAccessibilityEvent` does it: resolve the tag to its committed shadow node, then send.
- * An unknown tag is dropped, as RN drops it (with a log rather than a throw).
- */
+// An accessibility event addressed by a bare native tag, the way RN's bridgeless
+// UIManager.sendAccessibilityEvent does it: resolve the tag to its committed shadow node, then
+// send. An unknown tag is dropped, as RN drops it (with a log rather than a throw).
 export function sendAccessibilityEventByTag(tag, eventType) {
     const host = globalThis.nativeFabricUIManager;
     const node = host?.findShadowNodeByTag_DEPRECATED?.(tag);
@@ -21,22 +16,12 @@ export function sendAccessibilityEventByTag(tag, eventType) {
     host.sendAccessibilityEvent(node, eventType);
 }
 let cached;
-// BATCHING IS GONE, and it is worth one paragraph because the idea recurs. `batching-slot.ts`
-// recorded this slot's calls and replayed them once per commit — three ways, the last handing the
-// bytes to `SymbioteApplier` in C++. It existed to remove per-call JSI crossings from a JS walk that
-// worked out the Fabric operations. That walk no longer exists: adapters record their own mutations
-// and the tree host derives everything, so there are no per-call crossings left to batch. Removed
-// 2026-09-08 along with `setBatchedCommits`, the C++ applier and their differential. Root CLAUDE.md
-// keeps the measurement that made it uninteresting even on the old path — Create 256.8 on / 258.5
-// off, i.e. it demonstrably worked and bought nothing.
-/**
- * Test seam: forget the bound slot, so a fixture can install a different host and be believed.
- *
- * `getSlot` caches the facade for the life of the module — the live binding re-mints a host function
- * on every property read, so caching is not an optimisation but the difference between reading each
- * method once and reading it per call. The cache has no invalidation in production because the
- * global is installed once, before anything commits.
- */
+// Batching is gone: this slot's calls used to be recorded and replayed once per commit, to remove
+// per-call JSI crossings from a JS walk that worked out the Fabric operations. That walk no longer
+// exists — adapters record their own mutations — so there is nothing left to batch.
+// Test seam: forget the bound slot, so a fixture can install a different host and be believed.
+// getSlot caches the facade for the life of the module — the live binding re-mints a host function
+// on every property read, so caching means reading each method once instead of per call.
 export function resetSlot() {
     cached = undefined;
 }
@@ -106,17 +91,12 @@ export function getSlot() {
         measureLayout: (node, relativeToNode, onFail, onSuccess) => measureLayout(node, relativeToNode, onFail, onSuccess),
     };
     dlog('slot bound to nativeFabricUIManager');
-    // Resolve our own native module here, once, for its SIDE EFFECT: `RCTTurboModuleManager` runs
-    // `installJSIBindingsWithRuntime:` when it CREATES a module, so without this call the module is
-    // never created, the hook never runs, and `global.__symbioteEngineNative` is absent on a device
-    // carrying a perfectly working binary. A capability that is unreachable until its first consumer
-    // lands is indistinguishable from one that is broken, and the difference costs a build to find out.
-    //
-    // This is the right seam rather than a convenient one, and now for two reasons: binding the Fabric
-    // slot is the moment the engine has established it is on a native host at all, AND it is the last
-    // moment before a commit can happen — the tree host has to be in before `commitSurfaceOps` runs or
-    // the ops it names stay pending. It cannot throw: with no module `installNativeTreeHost()` is a
-    // no-op, which is most places (see `native-engine.ts`'s header).
+    // Resolve our own native module here, once, for its side effect: RCTTurboModuleManager runs
+    // installJSIBindingsWithRuntime: when it creates a module, so without this call the module is
+    // never created and the global bindings stay absent even on a working binary.
+    // The right seam, not just a convenient one: binding the Fabric slot is the moment the engine has
+    // established it's on a native host, and the last moment before commitSurfaceOps can run. Cannot
+    // throw: with no module, installNativeTreeHost() is a no-op (see native-engine.ts's header).
     installNativeTreeHost();
     return cached;
 }

package/build/host-access.d.ts

@@ -1,145 +1,18 @@
 import { type ISymbioteNode } from './node';
 import type { SymbioteSurface } from './surface';
-/**
- * The node's parent, or `undefined` for a node that sits directly under a surface.
- *
- * A top-level node answers `undefined` even though a surface IS a node in the host's tree, and the
- * three adapters depend on that exact miss: Angular reads `null` as "defer, `<ng-content>` will place
- * this", while Vue and Solid spell `?? surface` at their call sites and compare the result against
- * the `SymbioteSurface` object, which the surface's anchor node is not. `SURFACE_COMPONENT` is the
- * sentinel that stops the answer there.
- *
- * So `undefined` is not the same question as "is this node attached".
- *
- * IT DOES NOT ALWAYS DRAIN, unlike its neighbours. A node's parent link changes only through an op
- * that names it as the CHILD, so a node the pending batch has not placed already has its final
- * answer standing in the host — see `hasPendingPlacement`. Angular's 1 000-row create asks this
- * 1 000 times (its `addLViewToLContainer` calls `renderer.parentNode` once per embedded view) and
- * exactly ONE of those reads was about a node the batch had touched.
- */
 export declare function parentOf(node: ISymbioteNode): ISymbioteNode | undefined;
-/**
- * The node's children, INCLUDING anchors.
- *
- * Anchors are structural bookkeeping — the commit skips them — but they are not invisible to
- * traversal, and hiding them here would desync a framework runtime from the tree it built:
- * solid-js/universal keeps its own record of what it inserted and re-derives positions through these
- * lookups, so a node it placed must be a node it can find.
- */
 export declare function childrenOf(node: ISymbioteNode): readonly ISymbioteNode[];
-/**
- * Every node's parent, positionally, in ONE crossing — `parentOf` for a list.
- *
- * Engine-internal, like `subtreesOf` below, and for the same reason: what a framework seam needs is
- * the singular form, one step at a time. These two answer the question only TEARDOWN asks, and
- * teardown is the one lifecycle event whose size is the tree's (see `ITreeHost`).
- *
- * A `SURFACE_COMPONENT` parent reads as `undefined` here exactly as it does in `parentOf`, so the
- * two agree element for element.
- */
 export declare function parentsOf(nodes: readonly ISymbioteNode[]): readonly (ISymbioteNode | undefined)[];
 /** Each root and every descendant, pre-order, anchors included — all of it in ONE crossing. */
 export declare function subtreesOf(roots: readonly ISymbioteNode[]): readonly ISymbioteNode[];
-/**
- * The same walk narrowed to what a teardown must visit — see `ITreeHost.teardownSubtreesOf`.
- *
- * The gate is the ANIMATED one, not a behavior one: a binding is per node and carries no tag, so an
- * app that animates needs every node back and gets the full walk. Nothing else narrows, because
- * nothing else is charged per node of a removed subtree.
- */
 export declare function teardownSubtreesOf(roots: readonly ISymbioteNode[]): readonly ISymbioteNode[];
-/**
- * The node and every ancestor above it, deepest first, in ONE crossing.
- *
- * `parentOf` per level is a crossing per level, and the event path needs this chain for every
- * event — capture reads it reversed, bubble forward — plus again on every frame of a drag, for the
- * responder's scope. Measured at 18 crossings per event on a depth-8 chain before the two phases
- * shared a walk, 9 after, and 1 through here.
- *
- * Surfaces are dropped the same way `parentOf` drops them, by component, so a caller sees the same
- * chain it would have built by walking.
- */
 export declare function ancestorsOf(node: ISymbioteNode): readonly ISymbioteNode[];
-/**
- * The first child, anchors included, or `undefined` for a leaf.
- *
- * ONE HOST CALL, not `childrenOf(node)[0]`, and the difference is a complexity class rather than a
- * constant. `solid-js/universal`'s `cleanChildren` empties a parent with
- * `while (removed = getFirstChild(parent)) removeNode(parent, removed)` — so the old spelling read a
- * list of N, then N-1, then N-2, building and discarding every handle each time. Measured on a
- * 2 000-row Solid `Clear` (`solid-clear-scaling.itest.tsx`): **2 001 001 handles** crossed to remove
- * two thousand children, N(N+1)/2 to the unit, against the ~2 000 the work needs.
- *
- * The `mayHaveChildren` fast path is kept for the same reason `childrenOf` has it: FALSE is a
- * certainty, so a leaf answers without a drain and without a crossing.
- */
 export declare function firstChildOf(node: ISymbioteNode): ISymbioteNode | undefined;
-/**
- * The next sibling, or `undefined` at the end of the list.
- *
- * `surface` is required to answer for a TOP-LEVEL node, which has no parent to read the sibling
- * list from — the surface owns that list instead. Passing it for a parented node is harmless and
- * ignored, so a caller with one active surface can pass it unconditionally.
- */
-export declare function nextSiblingOf(node: ISymbioteNode, surface?: SymbioteSurface): ISymbioteNode | undefined;
-/**
- * Whether the node is a TEXT CONTAINER (`<Text>`), not whether it holds a string.
- *
- * The distinction is load-bearing for adapters that ask "can I write a string into this": a raw
- * text node answers FALSE here, and an anchor does too. Use `isRawTextNode` for that question.
- */
+export declare function nextSiblingOf(node: ISymbioteNode, _surface?: SymbioteSurface): ISymbioteNode | undefined;
 export declare function isTextContainer(node: ISymbioteNode): boolean;
-/**
- * Whether the node is a RAW TEXT node — one a string can be written into.
- *
- * This is the question `solid-js/universal`'s `insertExpression` actually asks before calling
- * replaceText, and answering it with `isTextContainer` would be wrong in both directions: a
- * `<Text>` is a container that holds no string of its own, and the empty-string ANCHOR that
- * cleanChildren leaves to hold a position is not writable either. An anchor is excluded here by
- * construction, since its component is the `#anchor` sentinel.
- */
 export declare function isRawTextNode(node: ISymbioteNode): boolean;
-/**
- * The Fabric view name this node currently resolves to (`RCTView`, `RCTText`, `RCTRawText`, the
- * `#anchor` sentinel …). Exposed because two seams branch on it — Solid to answer `isTextNode`,
- * Angular to recognise its own anchor hosts — and both read `node.component` directly today.
- *
- * NOT stable across a node's life: a primitive whose native view depends on a prop (`TextInput`'s
- * `multiline`) changes view without changing identity. Read it, never cache it.
- */
 export declare function componentOf(node: ISymbioteNode): string;
-/**
- * The string a raw-text node currently holds, or `undefined` for any other node.
- *
- * Exists for the DIAGNOSTIC path rather than the render path: a seam that rejects a bare string
- * outside a `<Text>` wants to name the offending text in its error, and reading `node.props.text`
- * to do so is the last thing keeping that seam coupled to the node's shape. Vue's
- * `setElementText` reads the same value for a real reason, so this is not a one-caller accessor.
- */
 export declare function textOf(node: ISymbioteNode): string | undefined;
-/**
- * Every prop standing on the node, function props included.
- *
- * The bag a payload fold reads. Two sources, because a function never crossed the wire (`writeProp`,
- * node.ts): the host holds the values it could take, JS holds the callbacks it could not, and a fold
- * asking for `onPress` must see the one the app wrote rather than the `undefined` the host was
- * handed in its place.
- *
- * A COPY when anything was stashed, the host's own object when nothing was — which is nearly every
- * node. Same caveat as `propOf`: `style` after a class merge is the `[classStyle, explicitStyle]`
- * array, not the author's object.
- */
 export declare function propsOf(node: ISymbioteNode): Readonly<Record<string, unknown>>;
-/**
- * A TEST read: the PAYLOAD the last commit handed Fabric for this node, `undefined` before one.
- *
- * `propsOf` above is the props AS THE OPS NAMED THEM — what the adapter said. This is what the
- * payload builder MADE of them, after the aria fold, the behavior's own fold, the component-keyed
- * folds and the style hoist. The two answer different questions and a test has to pick: "did the
- * adapter write `inputMode`" is `propsOf`, and "did that reach native as `keyboardType`" is this.
- *
- * Only the native host can answer it — see `ITreeHost.committedPayloadOf`. Under the recording host
- * it throws, on purpose, naming the itest suite as where the question belongs.
- */
 export declare function committedPayloadOf(node: ISymbioteNode): Readonly<Record<string, unknown>> | undefined;
 export declare function propOf(node: ISymbioteNode, key: string): unknown;