@symbiote-native/engine 1.3.1 → 1.5.0

package/build/native-engine.js

@@ -25,59 +25,38 @@ import { isRecord } from './type-guards.js';
 // restate the number: a bump that leaves a fixture behind reads as "the binary is stale", which is
 // exactly the message this constant exists to produce.
 export const SUPPORTED_NATIVE_VERSION = 4;
+// A member missing from this list resolves fine at bring-up and throws at the first call site
+// instead. `getBoundingClientRect` stays out on purpose: it is optional on the type.
+const REQUIRED_METHOD_NAMES = [
+    'allocInt32Array',
+    'probeUIManager',
+    'applyOps',
+    'getProp',
+    'getProps',
+    'markPropsDirty',
+    'getViewName',
+    'parentOf',
+    'childrenOf',
+    'firstChildOf',
+    'nextSiblingOf',
+    'parentsOf',
+    'subtreesOf',
+    'teardownSubtreesOf',
+    'ancestorsOf',
+    'committedRecordOf',
+    'dispatchCommand',
+    'sendAccessibilityEvent',
+    'measure',
+    'measureInWindow',
+    'measureLayout',
+    'setIsJSResponder',
+];
 function isBindings(value) {
     if (!isRecord(value))
         return false;
     if (typeof value.version !== 'number')
         return false;
-    if (typeof value.allocInt32Array !== 'function')
-        return false;
-    if (typeof value.probeUIManager !== 'function')
-        return false;
-    if (typeof value.applyOps !== 'function')
-        return false;
-    // The tree reads, checked one by one: a member added to the type without a line here resolves
-    // fine at bring-up and throws at the first call site — a gesture or a measure() — one language
-    // and several seconds away from the install that caused it.
-    if (typeof value.getProp !== 'function')
-        return false;
-    if (typeof value.getProps !== 'function')
-        return false;
-    if (typeof value.markPropsDirty !== 'function')
-        return false;
-    if (typeof value.getViewName !== 'function')
-        return false;
-    if (typeof value.parentOf !== 'function')
-        return false;
-    if (typeof value.childrenOf !== 'function')
-        return false;
-    if (typeof value.firstChildOf !== 'function')
-        return false;
-    if (typeof value.nextSiblingOf !== 'function')
-        return false;
-    if (typeof value.parentsOf !== 'function')
-        return false;
-    if (typeof value.subtreesOf !== 'function')
-        return false;
-    if (typeof value.teardownSubtreesOf !== 'function')
-        return false;
-    if (typeof value.ancestorsOf !== 'function')
-        return false;
-    if (typeof value.committedRecordOf !== 'function')
-        return false;
-    // The imperative six, checked by name: a pod with applyOps but not these is an older binary,
-    // and accepting it means measure() reaches a missing method at gesture time, not bring-up.
-    if (typeof value.dispatchCommand !== 'function')
-        return false;
-    if (typeof value.sendAccessibilityEvent !== 'function')
-        return false;
-    if (typeof value.measure !== 'function')
-        return false;
-    if (typeof value.measureInWindow !== 'function')
-        return false;
-    if (typeof value.measureLayout !== 'function')
-        return false;
-    return typeof value.setIsJSResponder === 'function';
+    return REQUIRED_METHOD_NAMES.every(name => typeof value[name] === 'function');
 }
 // SUPPORTED_NATIVE_VERSION guards a memory layout, not a member list: the shape guard above
 // already refuses an older pod lacking a new function's name, so bumping for that alone would

package/build/native-tree-host.js

@@ -36,6 +36,7 @@ export function nativeTreeHost(bindings) {
         measureInWindow: bindings.measureInWindow,
         measureLayout: bindings.measureLayout,
         setIsJSResponder: bindings.setIsJSResponder,
+        getBoundingClientRect: bindings.getBoundingClientRect,
     };
 }
 // Install it, if this runtime has a native module and nothing has claimed the seam already.

package/build/node-events.d.ts

@@ -0,0 +1,11 @@
+import type { IEventDispatch, IListener, ISymbioteNode } from './node-types';
+export declare function setBehaviorListener(node: ISymbioteNode, name: string, listener: IListener | undefined): void;
+export declare function setNodeDispatch(node: ISymbioteNode, dispatch: IEventDispatch | undefined): void;
+/** Whether anything at all would receive `name` on this node. */
+export declare function hasListenerFor(node: ISymbioteNode, name: string): boolean;
+export declare function listenerFor(node: ISymbioteNode, name: string): IListener | undefined;
+export declare function setEventListener(node: ISymbioteNode, name: string, value: unknown): void;
+export declare function isOnEventName(key: string): boolean;
+/** `onChange` to `change`. */
+export declare function listenerName(propName: string): string;
+export declare const RESPONDER_EVENTS: ReadonlySet<string>;

package/build/node-events.js

@@ -0,0 +1,145 @@
+// The listener channel: which `on*` prop becomes a listener, who owns the slot, and the handful of
+// events Fabric gates behind a boolean prop
+import { recordSetOwnedListener } from './mutation-buffer.js';
+import { appListenerFor, hasHostBehaviors, notifyOwnedListenerChange, ownsListener, stashAppListener, } from './host-behavior.js';
+import { IMAGE_LOAD_EVENT_NAMES, anyImageLoadEventListenerWired, } from './image-source-write.js';
+import { setProp } from './node-props.js';
+// Fabric gates a handful of events behind a BOOLEAN prop: unlike scroll/touch/change these fire
+// only when the shadow node carries the flag, and a gated handler would otherwise attach on our
+// side while the native event silently never arrives
+// `magicTap` maps to `onMagicTap`, not the C++ member name `onAccessibilityMagicTap`: RN's own
+// `BaseViewConfig.ios.js` disagrees with its C++ prop name, and matching stock is the only choice
+const GATED_EVENT_PROPS = new Map([
+    ['layout', 'onLayout'],
+    ['textLayout', 'onTextLayout'],
+    ['accessibilityTap', 'onAccessibilityTap'],
+    ['magicTap', 'onMagicTap'],
+    ['accessibilityEscape', 'onAccessibilityEscape'],
+    ['accessibilityAction', 'onAccessibilityAction'],
+]);
+// Install a listener the BEHAVIOR owns, bypassing the ownership check, т.к. `setEventListener`
+// diverts an owned name into the stash and that would be circular for the behavior's dispatcher
+// `undefined` removes it, gate flag included: ScrollView takes the owner's `layout` only while
+// something wants it, and a one-way installer would leave `onLayout: true` stuck in the payload
+export function setBehaviorListener(node, name, listener) {
+    if (listener === undefined)
+        node.listeners?.delete(name);
+    else
+        (node.listeners ??= new Map()).set(name, listener);
+    // The flag is written UNCONDITIONALLY. Writing it only on the FLIP was measured and rejected: it
+    // saves 1 KB per item on the two anchor-backed touchables and costs 10 ms on their teardown
+    // (`gated-listener-writes.test.ts`, symbiote-perf-measurement §24)
+    const flagProp = GATED_EVENT_PROPS.get(name);
+    if (flagProp !== undefined)
+        setProp(node, flagProp, listener === undefined ? undefined : true);
+}
+// Arm (or release, with `undefined`) the shared handler a behavior dispatches through, instead of
+// installing one closure per name. See `IEventDispatch`
+export function setNodeDispatch(node, dispatch) {
+    node.dispatch = dispatch;
+}
+/** Whether anything at all would receive `name` on this node. */
+export function hasListenerFor(node, name) {
+    if (node.listeners?.has(name) === true)
+        return true;
+    return node.dispatch?.names.has(name) === true;
+}
+// The app's own listener first: a behavior owns its names, so the two never collide, and an
+// unarmed node stops at one `Map` probe
+export function listenerFor(node, name) {
+    const own = node.listeners?.get(name);
+    if (own !== undefined)
+        return own;
+    const dispatch = node.dispatch;
+    if (dispatch === undefined || !dispatch.names.has(name))
+        return undefined;
+    // ONE closure per delivered event, where a dispatcher per name built seven per mounted node.
+    // `name` is bound here rather than read off `event.type`, so a caller building its own event
+    // (every test driving a behavior by hand) reaches the same handler
+    return event => dispatch.deliver(node, name, event);
+}
+// The unowned names whose presence a platform rule reads
+const PRESSABILITY_NAMES = new Set([
+    'press',
+    'longPress',
+    'startShouldSetResponder',
+]);
+// A name a host behavior OWNS never reaches `node.listeners`: the behavior's dispatcher holds that
+// slot, and the map is single-slot, so the app's callback would evict it with no diagnostic
+function stashOwnedListener(node, name, value, isHandler) {
+    // The PRESENCE only, never the identity: a fresh closure nearly every render must not notify
+    const wasWired = appListenerFor(node, name) !== undefined;
+    stashAppListener(node, name, isHandler ? value : undefined);
+    if (wasWired !== isHandler) {
+        // The BIT, on the flip only, so a platform rule can resolve a key depending on whether the app
+        // wired anything without the closure leaving JS
+        recordSetOwnedListener(node, name, isHandler);
+        notifyOwnedListenerChange(node, name, isHandler);
+    }
+    const flagged = GATED_EVENT_PROPS.get(name);
+    if (flagged !== undefined)
+        setProp(node, flagged, isHandler ? true : undefined);
+}
+// The explicit event channel. Structural adapters (Svelte `addEventListener`, Angular
+// `Renderer2.listen`) call this with an already-known event name, flat-bag adapters reach it
+// through `routeProp`, and a non-function value clears the listener
+export function setEventListener(node, name, value) {
+    const isHandler = typeof value === 'function';
+    if (hasHostBehaviors() && ownsListener(node, name)) {
+        stashOwnedListener(node, name, value, isHandler);
+        return;
+    }
+    // A plain `<text>` presses through the engine's own synthesis with no behavior owning the names,
+    // yet its payload depends on whether it is pressable. Same bit as the owned path, on the flip
+    if (PRESSABILITY_NAMES.has(name)) {
+        const wasWired = node.listeners?.has(name) === true;
+        if (wasWired !== isHandler)
+            recordSetOwnedListener(node, name, isHandler);
+    }
+    if (isHandler) {
+        const handler = value;
+        const listeners = (node.listeners ??= new Map());
+        listeners.set(name, (event) => handler(event));
+    }
+    else {
+        node.listeners?.delete(name);
+    }
+    const flagProp = GATED_EVENT_PROPS.get(name);
+    if (flagProp !== undefined)
+        setProp(node, flagProp, isHandler ? true : undefined);
+    // `onLoad` and friends are real Fabric events on `RCTImageView`, so they land here rather than in
+    // `writeProp`. See `image-source-write.ts` for Android's synthesized `shouldNotifyLoadEvents`
+    if (node.resolvesImageSources && IMAGE_LOAD_EVENT_NAMES.has(name)) {
+        setProp(node, 'shouldNotifyLoadEvents', anyImageLoadEventListenerWired(node.listeners) ? true : undefined);
+    }
+}
+// `/^on[A-Z]/` spelled out, т.к. this runs on EVERY prop write and a regex costs measurably more
+// than the character reads. 111 is 'o', 110 is 'n', 65-90 is A-Z, and `charCodeAt` past the end
+// answers NaN, which fails every comparison
+export function isOnEventName(key) {
+    if (key.charCodeAt(0) !== 111 || key.charCodeAt(1) !== 110)
+        return false;
+    const third = key.charCodeAt(2);
+    return third >= 65 && third <= 90;
+}
+/** `onChange` to `change`. */
+export function listenerName(propName) {
+    return propName.charAt(2).toLowerCase() + propName.slice(3);
+}
+// PanResponder's `panHandlers`: a JS-side protocol synthesized from raw touches, not Fabric
+// ViewConfig events, so `isEventFor` never reports them. Treated as listeners on any node so the
+// handlers attach instead of reaching Fabric as dead props
+export const RESPONDER_EVENTS = new Set([
+    'startShouldSetResponder',
+    'startShouldSetResponderCapture',
+    'moveShouldSetResponder',
+    'moveShouldSetResponderCapture',
+    'responderGrant',
+    'responderReject',
+    'responderStart',
+    'responderMove',
+    'responderEnd',
+    'responderRelease',
+    'responderTerminate',
+    'responderTerminationRequest',
+]);

package/build/node-instance.d.ts

@@ -0,0 +1,8 @@
+import { type ISymbioteNode } from './node-types';
+export declare function createElement(component: string, isText?: boolean, tag?: string): ISymbioteNode;
+export declare function createRawText(text: string, tag?: string): ISymbioteNode;
+export declare function debugNodeId(node: ISymbioteNode): number;
+export declare function createAnchor(): ISymbioteNode;
+export declare function createVoid(): ISymbioteNode;
+export declare function createSurfaceRoot(): ISymbioteNode;
+export declare function setNodeComponent(node: ISymbioteNode, component: string): void;

package/build/node-instance.js

@@ -0,0 +1,168 @@
+// The one shape every retained node has, and the factories that mint it
+import { recordCreateAnchor, recordCreateVoid, recordCreateElement, recordCreateRawText, recordSetComponent, recordSetProp, } from './mutation-buffer.js';
+import { attachHostBehavior, hasHostBehaviors, } from './host-behavior.js';
+import { configPayloadFold } from './registry.js';
+import { dlog } from './debug.js';
+// A cycle, deliberately: `imperative.ts` imports this module and the prototype methods below call
+// back into it. Neither touches the other at module-evaluation time, only inside a function body
+import { measure as engineMeasure, measureInWindow as engineMeasureInWindow, measureLayout as engineMeasureLayout, setNativeProps as engineSetNativeProps, dispatchViewCommand, } from './imperative.js';
+import { ANCHOR_COMPONENT, BRAND, RAW_TEXT_COMPONENT, SURFACE_COMPONENT, VOID_COMPONENT, isSymbioteNode, } from './node-types.js';
+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';
+// A class, so the imperative methods share a prototype instead of being allocated per node, and
+// both factories below mint the same hidden class. Fields are `declare`d and assigned in the
+// constructor, the shape V8 and Hermes handle best
+class SymbioteNode {
+    constructor(component, isText) {
+        // Every field is assigned here, not lazily: present from the constructor, they all keep ONE
+        // hidden class for every node
+        this[BRAND] = true;
+        this.component = component;
+        this.isText = isText;
+        this.listeners = undefined;
+        this.dispatch = undefined;
+        this.hasCommitHook = false;
+        this.resolvesImageSources = false;
+        this.nativeIdWinsOverId = false;
+        this.styleParts = undefined;
+        this.payloadFold = undefined;
+        this.hostBehavior = undefined;
+        this.childHost = undefined;
+        this.wrapper = undefined;
+        this.mayHaveChildren = false;
+        this.isTornDown = false;
+        // `slotOf` reads this pair on EVERY handle operand of every op, so both must be stable slots.
+        // `slotBatch` starts at a value no real batch carries, so an untouched node needs no flag
+        this.slot = 0;
+        this.slotBatch = 0;
+        this.createdBatch = 0;
+    }
+    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, so `buildScrollViewHandle` delegating here 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, []);
+    }
+}
+// Mint an element and record its creation. The node object IS the handle: what the ops address,
+// what the host attaches its native node to, and what Fabric hands back as an event target
+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, so an adapter creating `<pressable>` must hand it over
+tag = component) {
+    const node = new SymbioteNode(component, isText);
+    // A primitive that commits NO VIEW resolves to the anchor component through `descriptorFor`, and
+    // a primitive whose ENTIRE subtree must vanish resolves to the void one the same way
+    if (component === ANCHOR_COMPONENT)
+        recordCreateAnchor(node);
+    else if (component === VOID_COMPONENT)
+        recordCreateVoid(node);
+    else
+        recordCreateElement(node, component, isText, node);
+    // 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);
+    // A third-party view's own ViewConfig processors, as a fold, AFTER the behavior's: the behavior
+    // rewrites wrapper-body props and `validAttributes[*].process` then converts what it produced
+    const configFold = configPayloadFold(component);
+    if (configFold !== undefined) {
+        const behaviorFold = node.payloadFold;
+        node.payloadFold =
+            behaviorFold === undefined
+                ? configFold
+                : props => configFold(behaviorFold(props));
+    }
+    return node;
+}
+// `tag` mirrors `createElement`'s, т.к. a raw text's CONTENT can still be a function of the
+// platform (Button renders its title uppercased on Android) even with no props an app can write
+export function createRawText(text, tag = RAW_TEXT_COMPONENT) {
+    const node = new SymbioteNode(RAW_TEXT_COMPONENT, false);
+    recordCreateRawText(node, text);
+    // TAG check first, not `hasHostBehaviors()`: almost no raw text is tagged, so an untagged one
+    // pays a pointer-equality compare against the default rather than a registry lookup
+    if (tag !== RAW_TEXT_COMPONENT && hasHostBehaviors())
+        attachHostBehavior(node, tag);
+    return node;
+}
+// A `WeakMap` cannot be logged, so this gives every node a small human-readable id assigned lazily,
+// which lets a `dlog` at ref-attach time and one at dispatch time prove they are the SAME object
+const debugIds = new WeakMap();
+let nextDebugId = 1;
+export function debugNodeId(node) {
+    let id = debugIds.get(node);
+    if (id === undefined) {
+        id = nextDebugId++;
+        debugIds.set(node, id);
+    }
+    return id;
+}
+export function createAnchor() {
+    const node = new SymbioteNode(ANCHOR_COMPONENT, false);
+    recordCreateAnchor(node);
+    return node;
+}
+export function createVoid() {
+    const node = new SymbioteNode(VOID_COMPONENT, false);
+    recordCreateVoid(node);
+    return node;
+}
+// One persistent root view per surface, mirroring RN's own `AppContainer`. Not decoration: without
+// `flex: 1` a non-flex root collapses to content height, and without `box-none` a touch outside the
+// app has no escape
+export function createSurfaceRoot() {
+    const node = new SymbioteNode(SURFACE_COMPONENT, false);
+    recordCreateElement(node, 'RCTView', false, node);
+    // Recorded straight, not through `routeProp`: these are literal Fabric props, not props an app
+    // authored, so they want none of the class merging or event routing that path exists for
+    recordSetProp(node, 'style', { flex: 1 });
+    recordSetProp(node, 'pointerEvents', 'box-none');
+    return node;
+}
+// Change which Fabric view a node commits as, keeping the node's identity. Both the JS field and
+// the op move, т.к. no prop write moves a node between views and the host must re-create it
+export function setNodeComponent(node, component) {
+    if (node.component === component)
+        return;
+    node.component = component;
+    recordSetComponent(node, component);
+}

package/build/node-props.d.ts

@@ -0,0 +1,13 @@
+import type { ISymbioteNode } from './node-types';
+export declare function takePropStats(): {
+    writes: number;
+};
+export declare function takePropKeyTally(): ReadonlyMap<string, number>;
+export declare const REACT_JSX_DEV_PROPS: ReadonlySet<string>;
+export declare function setProp(node: ISymbioteNode, key: string, value: unknown): void;
+export declare function writeProp(node: ISymbioteNode, key: string, value: unknown): void;
+/** What `propOf` consults before asking the host, `undefined` when nothing was stashed. */
+export declare function functionPropOf(node: ISymbioteNode, key: string): unknown;
+export declare function functionPropsOf(node: ISymbioteNode): ReadonlyMap<string, unknown> | undefined;
+export declare function markPropsDirty(node: ISymbioteNode): void;
+export declare function setText(node: ISymbioteNode, text: string): void;

package/build/node-props.js

@@ -0,0 +1,131 @@
+// The prop write path: the one choke point every writer passes on its way to an op, plus the
+// function-prop stash and the two counters `readCommitProfile` drains
+import { isPendingCreate, noteHostSideChange, recordSetProp, recordSetText, } from './mutation-buffer.js';
+import { derivedNodesOf, noteCommitHookNodeChanged, slotDerivesFrom, } from './host-behavior.js';
+import { resolveStructuredStyle } from './structured-style.js';
+import { IMAGE_SOURCE_PROPS, resolveImageSourceProp, } from './image-source-write.js';
+import { Platform } from './platform';
+import { isDebug } from './debug.js';
+import { flushOps, treeHost } from './tree-host.js';
+// How many prop writes an adapter pushed at the engine, read and zeroed through
+// `readCommitProfile`. Not gated behind `isDebug()`, т.к. an integer increment is noise next to the
+// prop write it counts
+const propStats = { writes: 0 };
+export function takePropStats() {
+    const snapshot = { writes: propStats.writes };
+    propStats.writes = 0;
+    return snapshot;
+}
+// `<component>.<key>` to write count, gated behind `isDebug()` т.к. a `Map` lookup per write is
+// real cost on the hottest path. Names which (view, key) pair an aggregate delta is hiding
+let propKeyTally;
+export function takePropKeyTally() {
+    const snapshot = propKeyTally ?? new Map();
+    propKeyTally = undefined;
+    return snapshot;
+}
+// React's JSX dev transform annotates every element with `__self` and `__source`, which React's own
+// host config consumes and never forwards. Both platforms reject them: `__self` is a cyclic module
+// `this`, and `jsi::dynamicFromValue` keeps no visited set
+export const REACT_JSX_DEV_PROPS = new Set([
+    '__self',
+    '__source',
+]);
+// Function props that never left JS, keyed by node. A function CANNOT cross this wire, т.к.
+// `jsi::dynamicFromValue` THROWS on a callable and kills the whole batch
+const functionProps = new WeakMap();
+// A pure prop set with no event inference: the event-vs-prop decision is `routeProp`'s, never the
+// key's name. `undefined` DELETES the key, where `null` is a legitimate Fabric "reset to default"
+// No `Object.is` dedupe here, т.к. it needs the value the node already holds, which JS does not.
+// The guard lives in the host's `OP_SET_PROP`, where the previous value is a local field
+export function setProp(node, key, value) {
+    // A composed primitive's slot, and its wrapper where it has one, can carry a value DERIVED from
+    // an owner prop, so `markPropsDirty` bubbles up or neither ever learns
+    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;
+    if (isDebug()) {
+        propKeyTally ??= new Map();
+        const tallyKey = `${node.component}.${key}`;
+        propKeyTally.set(tallyKey, (propKeyTally.get(tallyKey) ?? 0) + 1);
+    }
+    writeProp(node, key, value);
+}
+// The one place a prop reaches the wire, and the only place that can keep a function off it.
+// `setNativeProps` calls this rather than `recordSetProp`, т.к. it has no `routeProp` in front
+export function writeProp(node, key, value) {
+    // Repeated from `routeProp` т.к. THIS is the path with nothing in front of it: `AnimatedProps`
+    // re-sends its whole raw bag every frame, so on a JSX adapter `__self` rides straight past
+    if (REACT_JSX_DEV_PROPS.has(key))
+        return;
+    // Arms the node's recurring post-commit hook. HERE т.к. this is where the declarative and
+    // `setNativeProps` paths meet, and a hook armed only by the former misses the imperative write
+    if (node.hasCommitHook)
+        noteCommitHookNodeChanged(node);
+    // `boxShadow` / `filter` / `transform` and Image's source props resolve on the way IN, at this
+    // same choke point, т.к. the C++ payload builder has no JS to do it headless
+    let written = value;
+    if (key === 'style' || key === 'activeStyle') {
+        written = resolveStructuredStyle(value);
+    }
+    else if (node.resolvesImageSources && IMAGE_SOURCE_PROPS.has(key)) {
+        written = resolveImageSourceProp(value, key === 'source' && Platform.OS === 'android');
+    }
+    if (typeof written === 'function') {
+        let bag = functionProps.get(node);
+        if (bag === undefined) {
+            bag = new Map();
+            functionProps.set(node, bag);
+        }
+        bag.set(key, value);
+        // The host must not be left holding whatever stood under this key before: a stale value read
+        // back through `propOf` would beat the function this write just stashed
+        recordSetProp(node, key, undefined);
+        return;
+    }
+    // Written over with a non-function, so the stash must let go or it keeps answering
+    const bag = functionProps.get(node);
+    if (bag !== undefined)
+        bag.delete(key);
+    recordSetProp(node, key, written);
+}
+/** What `propOf` consults before asking the host, `undefined` when nothing was stashed. */
+export function functionPropOf(node, key) {
+    return functionProps.get(node)?.get(key);
+}
+// The same stash, whole, for `propsOf` to layer over the host's answer. `undefined` rather than an
+// empty `Map` for a node that stashed nothing, so the caller hands back the host's own object
+export function functionPropsOf(node) {
+    return functionProps.get(node);
+}
+// "Rebuild this node's payload, the fold reads state I just changed". A behavior whose payload is
+// DERIVED has no prop to write, so this is the one route that dirties it directly
+export function markPropsDirty(node) {
+    // Announced to the buffer even though it writes no op, т.к. a commit that cannot see this change
+    // would skip itself as idle
+    noteHostSideChange();
+    if (node.hasCommitHook)
+        noteCommitHookNodeChanged(node);
+    // A node this batch created has no committed payload and the host cannot name it yet, so the mark
+    // is a no-op and the `flushOps` it would force is the whole of its cost
+    if (isPendingCreate(node))
+        return;
+    // The host call takes a HANDLE, so it has to be ORDERED after the ops that built the node
+    flushOps();
+    treeHost()?.markPropsDirty(node);
+}
+// Counted in `propStats`, т.к. a text write IS a prop write, reaching Fabric as `RCTRawText`'s only
+// prop. Unguarded for the same reason `setProp` is: the host holds the standing text and dedupes
+export function setText(node, text) {
+    propStats.writes += 1;
+    recordSetText(node, text);
+}

package/build/node-route.d.ts

@@ -0,0 +1,2 @@
+import type { ISymbioteNode } from './node-types';
+export declare function routeProp(node: ISymbioteNode, key: string, value: unknown): void;