@symbiote-native/engine 0.4.0 → 0.5.0

package/build/events/index.js

@@ -8,7 +8,7 @@
 import { dlog } from '../debug.js';
 import { runWrapped } from '../dispatch.js';
 import { getSlot } from '../fabric.js';
-import { isAnchor, isSymbioteNode, } from '../node.js';
+import { committedOf, isAnchor, isSymbioteNode, } from '../node.js';
 import { registeredNativeEvent } from '../registry.js';
 import { attachTouchHistory, recordTouchTrack, resetTouchHistory, touchHistory, } from '../touch-history.js';
 import { isRecord } from '../type-guards.js';
@@ -248,6 +248,34 @@ function findWantsResponder(path, captureName, bubbleName, nativeEvent, skip) {
     }
     return undefined;
 }
+// Tell native which node owns the gesture, RN's `injectGlobalResponderHandler`
+// (ReactFabric-dev.js:18862) — the OLD owner first, then the new one, both in one call so no
+// site can do half of it.
+//
+// WITHOUT THIS A JS RESPONDER LOSES TO ANY SCROLL VIEW ABOVE IT, and it is invisible from JS:
+// `onStartShouldSetResponder` returns true, the native UIScrollView never learns the gesture was
+// claimed, and every subsequent move arrives as `topScroll` instead of `topTouchMove` — so the
+// negotiation never even gets a move to grant on. Device-diagnosed 2026-09-08 on a PanResponder
+// drag box inside the canary's ScrollView: `startShouldSet -> true` followed by
+// `topScrollBeginDrag` and twenty `topScroll`, with no grant and no move.
+//
+// `blockNativeResponder` is the taker's own `onResponderGrant` return, exactly as RN reads it.
+function handOverNativeResponder(from, to, blockNativeResponder) {
+    const slot = getSlot();
+    const fromHandle = from === undefined ? undefined : committedOf(from)?.handle;
+    const toHandle = to === undefined ? undefined : committedOf(to)?.handle;
+    dlog(`setIsJSResponder from=${from === undefined ? 'none' : fromHandle === undefined ? 'UNCOMMITTED' : 'yes'} ` +
+        `to=${to === undefined ? 'none' : toHandle === undefined ? 'UNCOMMITTED' : 'yes'} block=${blockNativeResponder}`);
+    if (fromHandle !== undefined)
+        slot.setIsJSResponder(fromHandle, false, blockNativeResponder);
+    if (toHandle !== undefined)
+        slot.setIsJSResponder(toHandle, true, blockNativeResponder);
+}
+// Whether the taker asked native to stand down. RN reads this off the grant dispatch's return;
+// an absent listener means no claim, which is RN's `blockNativeResponder || false`.
+function blocksNative(result) {
+    return result === true;
+}
 // Negotiate (or re-negotiate) the responder for a touch start/move. If nobody holds
 // it, the winner is granted. If someone does, the incumbent is asked to relinquish
 // via onResponderTerminationRequest (absent listener = implicit yes); on yes it is
@@ -268,12 +296,21 @@ function negotiateResponder(target, phase, nativeEvent) {
     const wants = phase === 'start'
         ? findWantsResponder(path, START_SHOULD_SET_CAPTURE, START_SHOULD_SET, nativeEvent, skip)
         : findWantsResponder(path, MOVE_SHOULD_SET_CAPTURE, MOVE_SHOULD_SET, nativeEvent, skip);
-    if (!wants || wants === currentResponder)
+    // Every exit is logged: a negotiation that declines is indistinguishable from one that never
+    // ran, and the two have opposite causes.
+    if (!wants) {
+        dlog(`responder ${phase}: nobody wants it (path=${path.length}${skip === undefined ? '' : ', one skipped'})`);
+        return;
+    }
+    if (wants === currentResponder) {
+        dlog(`responder ${phase}: ${wants.component} already holds it`);
         return;
+    }
     if (currentResponder === undefined) {
         currentResponder = wants;
         dlog(`responder granted to ${wants.component}`);
-        callOwnListener(wants, RESPONDER_GRANT, nativeEvent);
+        const granted = callOwnListener(wants, RESPONDER_GRANT, nativeEvent);
+        handOverNativeResponder(undefined, wants, blocksNative(granted));
         return;
     }
     const incumbent = currentResponder;
@@ -292,9 +329,10 @@ function negotiateResponder(target, phase, nativeEvent) {
         // before terminate on the consent path (matching RN's grant<terminate ordering) and
         // omit it on reject; the consent OUTCOME is unchanged either way.
         dlog(`responder transferred ${incumbent.component} -> ${wants.component}`);
-        callOwnListener(wants, RESPONDER_GRANT, nativeEvent);
+        const granted = callOwnListener(wants, RESPONDER_GRANT, nativeEvent);
         callOwnListener(incumbent, RESPONDER_TERMINATE, nativeEvent);
         currentResponder = wants;
+        handOverNativeResponder(incumbent, wants, blocksNative(granted));
     }
     else {
         dlog(`responder takeover of ${incumbent.component} rejected`);
@@ -309,7 +347,7 @@ export function installEventHandler() {
         if (!isSymbioteNode(instanceHandle))
             return;
         if (topLevelType === TOUCH_START) {
-            dlog(`event ${TOUCH_START}`);
+            dlog(`event ${TOUCH_START} on ${isSymbioteNode(instanceHandle) ? instanceHandle.component : 'NON-NODE'}`);
             // Update the touch bank, then attach it so responder handlers (PanResponder)
             // read each touch's own previous->current delta; RN records before dispatch.
             recordTouchTrack('start', nativeEvent);
@@ -432,8 +470,10 @@ export function installEventHandler() {
                 // release) only when the last responder touch lifted.
                 if (responder) {
                     callOwnListener(responder, RESPONDER_END, nativeEvent);
-                    if (releases)
+                    if (releases) {
                         callOwnListener(responder, RESPONDER_RELEASE, nativeEvent);
+                        handOverNativeResponder(responder, undefined, false);
+                    }
                     else
                         dlog('responderEnd without release (touches remain inside responder)');
                 }
@@ -468,8 +508,10 @@ export function installEventHandler() {
                     // Like touch-end, every finger leaving emits responderEnd. Termination is final only
                     // when no touch remains inside the responder.
                     callOwnListener(responder, RESPONDER_END, nativeEvent);
-                    if (terminatesResponder)
+                    if (terminatesResponder) {
                         callOwnListener(responder, RESPONDER_TERMINATE, nativeEvent);
+                        handOverNativeResponder(responder, undefined, false);
+                    }
                 }
             });
             if (touchHistory.numberActiveTouches === 0)

package/build/fabric-props.js

@@ -291,7 +291,22 @@ function foldTextInputValue(props) {
 }
 export function fabricProps(node) {
     if (node.component === RAW_TEXT_COMPONENT) {
-        return { text: node.props.text };
+        // 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 `node.props.text`, 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.
+        return {
+            text: node.payloadFold !== undefined
+                ? node.payloadFold(node.props).text
+                : node.props.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

package/build/fabric.d.ts

@@ -23,6 +23,7 @@ export interface IFabricSlot {
     registerEventHandler(handler: IFabricEventHandler): void;
     dispatchCommand(node: IFabricNode, commandName: string, args: readonly unknown[]): void;
     sendAccessibilityEvent(node: IFabricNode, eventType: string): void;
+    setIsJSResponder(node: IFabricNode, isResponder: boolean, blockNativeResponder: boolean): void;
     measure(node: IFabricNode, callback: IMeasureOnSuccess): void;
     measureInWindow(node: IFabricNode, callback: IMeasureInWindowOnSuccess): void;
     measureLayout(node: IFabricNode, relativeToNode: IFabricNode, onFail: () => void, onSuccess: IMeasureLayoutOnSuccess): void;

package/build/fabric.js

@@ -29,6 +29,7 @@ export function getSlot() {
     // Optional on some hosts: read it off the live binding and feature-detect below so an
     // older slot without it degrades to a logged no-op instead of throwing.
     const { sendAccessibilityEvent } = host;
+    const { setIsJSResponder } = host;
     const { measure } = host;
     const { measureInWindow } = host;
     const { measureLayout } = host;
@@ -59,6 +60,13 @@ export function getSlot() {
             }
             sendAccessibilityEvent(node, eventType);
         },
+        setIsJSResponder: (node, isResponder, blockNativeResponder) => {
+            if (typeof setIsJSResponder !== 'function') {
+                dlog('setIsJSResponder -> host lacks the method (no-op)');
+                return;
+            }
+            setIsJSResponder(node, isResponder, blockNativeResponder);
+        },
         measure: (node, callback) => measure(node, callback),
         measureInWindow: (node, callback) => measureInWindow(node, callback),
         measureLayout: (node, relativeToNode, onFail, onSuccess) => measureLayout(node, relativeToNode, onFail, onSuccess),

package/build/host-behavior.d.ts

@@ -17,10 +17,20 @@ import type { ISymbioteNode } from './node';
  * this one return their input by identity when there is nothing to do.
  */
 export type IPayloadFold = (props: Readonly<Record<string, unknown>>) => Record<string, unknown>;
+export type IClaimMode = 'beside' | 'wrap';
 export interface IHostBehavior {
     readonly ownedListeners?: readonly string[];
+    readonly slotProps?: Readonly<Record<string, string>>;
+    readonly slotPropsExcept?: readonly string[];
+    readonly slotTakesNoChildren?: boolean;
+    readonly slotDerived?: readonly string[];
+    readonly claimedChildren?: Readonly<Record<string, IClaimMode>>;
+    onChildInserted?(node: ISymbioteNode, child: ISymbioteNode): void;
+    buildStructure?(node: ISymbioteNode): ISymbioteNode | undefined;
     attach(node: ISymbioteNode): void;
     attachAfterCommit?(node: ISymbioteNode): void;
+    onWrapChange?(owner: ISymbioteNode, wrapper: ISymbioteNode | undefined): void;
+    onOwnedListenerChange?(node: ISymbioteNode, name: string, wired: boolean): void;
     afterCommit?(node: ISymbioteNode): void;
     detach(node: ISymbioteNode): void;
     readonly foldPayload?: IPayloadFold;
@@ -28,6 +38,15 @@ export interface IHostBehavior {
 export declare function registerHostBehavior(component: string, behavior: IHostBehavior): void;
 export declare function hostBehaviorFor(tag: string): IHostBehavior | undefined;
 export declare function hasHostBehaviors(): boolean;
+export declare function slotPropNameFor(node: ISymbioteNode, key: string): string | undefined;
+export declare function slotTakesChildren(node: ISymbioteNode): boolean;
+export declare function addDerivedNode(owner: ISymbioteNode, node: ISymbioteNode): void;
+export declare function derivedNodesOf(owner: ISymbioteNode): readonly ISymbioteNode[] | undefined;
+export declare function notifyOwnedListenerChange(node: ISymbioteNode, name: string, wired: boolean): void;
+export declare function notifyChildInserted(node: ISymbioteNode, child: ISymbioteNode): void;
+export declare function notifyWrapChange(owner: ISymbioteNode, wrapper: ISymbioteNode | undefined): void;
+export declare function claimModeFor(node: ISymbioteNode, component: string): IClaimMode | undefined;
+export declare function slotDerivesFrom(node: ISymbioteNode, key: string): boolean;
 export declare function ownsListener(node: ISymbioteNode, name: string): boolean;
 export declare function stashAppListener(node: ISymbioteNode, name: string, listener: unknown): void;
 export declare function appListenerFor(node: ISymbioteNode, name: string): unknown;
@@ -41,7 +60,25 @@ export declare function attachHostBehavior(node: ISymbioteNode, tag: string): vo
  * for the commit that lands it, and `detachSubtree` drops it if that commit never comes.
  */
 export declare function runDeferredAttaches(isCommitted: (node: ISymbioteNode) => boolean): void;
+/**
+ * The recurring beat. Split from `runDeferredAttaches` because the two answer different questions:
+ * `attachAfterCommit` needs a FRESH FABRIC TAG, so it belongs below `completeRoot` and must not run
+ * on a commit that made no native call; `afterCommit` needs only "props were published", which a
+ * no-op commit satisfies just as well.
+ *
+ * Keeping them together made `afterCommit` unreachable for exactly the props a behavior owns: a fold
+ * that STRIPS a prop makes its own commit byte-identical, `commitContainer` returns above the drain,
+ * and the hook never sees the flip. TouchableOpacity's re-settle on `disabled` is the case
+ * (`disabled` is a MACHINE_ONLY key), Button's `title`/`color` the other.
+ *
+ * SETUP STILL RUNS BEFORE THE BEAT on the first commit, and the order is load-bearing: a node
+ * carrying both hooks has `attachAfterCommit` seed the mirrors `afterCommit` compares against. The
+ * caller preserves it by calling this AFTER `runDeferredAttaches` on the changed path — the no-op
+ * path has no setup to run, since a node with no Fabric tag has not committed at all.
+ */
+export declare function runCommittedHooks(isCommitted: (node: ISymbioteNode) => boolean): void;
 export declare function markDetachCandidate(node: ISymbioteNode): void;
-export declare function sweepDetachedBehaviors(topLevel: readonly ISymbioteNode[]): void;
+export declare function sweepDetachedBehaviors(topLevel: readonly ISymbioteNode[], onDetached: (node: ISymbioteNode) => void): void;
+export declare function teardownSubtree(node: ISymbioteNode, onDetached: (node: ISymbioteNode) => void): void;
 export declare function reattachHostBehaviors(node: ISymbioteNode): void;
 export declare function clearHostBehaviors(): void;

package/build/host-behavior.js

@@ -39,7 +39,7 @@ const tornDown = new WeakSet();
 //
 // THE REGISTRY IS KEYED BY INTRINSIC TAG AND THE NODE IS NOT. `node.component` is the FABRIC view
 // name: every adapter resolves the tag through `descriptorFor` before calling `createElement`, so
-// `symbiote-view` arrives as `RCTView`. Keying the registry by Fabric name instead is not an
+// `view` arrives as `RCTView`. Keying the registry by Fabric name instead is not an
 // option — a pressable resolves to `RCTView` like any other view, so the press machine would
 // attach to every plain `View` in the app. So the tag alphabet is used EXACTLY ONCE, at
 // `attachHostBehavior`, where the caller still holds it; every later lookup reads this map.
@@ -70,6 +70,78 @@ export function hostBehaviorFor(tag) {
 export function hasHostBehaviors() {
     return hasBehaviors;
 }
+// What an owner prop is called on the slot, or undefined when it belongs to the owner after all.
+//
+// Called from `routeProp` only for a node that HAS a slot (`node.childHost !== undefined`), which
+// is what keeps a WeakMap probe off the hot path: every other node is turned away by one field
+// read, the same gate `payloadFold` uses one layer down.
+export function slotPropNameFor(node, key) {
+    const behavior = attached.get(node);
+    if (behavior === undefined)
+        return undefined;
+    const named = behavior.slotProps?.[key];
+    if (named !== undefined)
+        return named;
+    const except = behavior.slotPropsExcept;
+    if (except !== undefined && !except.includes(key))
+        return key;
+    return undefined;
+}
+// Does this owner's slot host the app's children, or is it a built sibling they land beside? See
+// `slotTakesNoChildren`. Same `node.childHost` gate as every other probe here: the two callers ask
+// only after the field said there is a slot at all.
+export function slotTakesChildren(node) {
+    return attached.get(node)?.slotTakesNoChildren !== true;
+}
+// Nodes a behavior built that are NOT the slot, and whose payloads derive from the owner's props.
+//
+// `slotDerived` marks `node.childHost` and nothing else, which is one hop — enough for ScrollView,
+// whose only derived node IS the slot, and not enough for a primitive whose `buildStructure` builds
+// a chain. Button builds view > text > raw text and folds two of them from the same three owner
+// props; without this the deeper nodes freeze at their mount values, and the workaround is to write
+// them from inside a fold whose contract says it MUST be pure.
+//
+// A WeakMap rather than a field, for the reason `stashed` is one: this exists only for the handful
+// of nodes a composed behavior built, and a field costs a shape transition on every node in every
+// app. It is read only inside the `slotDerived` branch, which has already paid a WeakMap probe.
+const derived = new WeakMap();
+// Called from `buildStructure` for each node past the slot. Not idempotent-checked: structure is
+// built exactly once (`attachHostBehavior`, never `reattachSubtree`), so a second call would be a
+// bug worth seeing rather than one worth absorbing.
+export function addDerivedNode(owner, node) {
+    const existing = derived.get(owner);
+    if (existing === undefined)
+        derived.set(owner, [node]);
+    else
+        existing.push(node);
+}
+export function derivedNodesOf(owner) {
+    return derived.get(owner);
+}
+// Called from `setEventListener` on a PRESENCE flip of an owned name, and only there — the caller
+// has already established that this node owns the name, so the WeakMap probe is one it just paid.
+export function notifyOwnedListenerChange(node, name, wired) {
+    attached.get(node)?.onOwnedListenerChange?.(node, name, wired);
+}
+// Called from the two inserts once the child is in place. See `onChildInserted`.
+export function notifyChildInserted(node, child) {
+    attached.get(node)?.onChildInserted?.(node, child);
+}
+// Called from the two structural entry points when a wrap claim lands or leaves. See
+// `onWrapChange`.
+export function notifyWrapChange(owner, wrapper) {
+    attached.get(owner)?.onWrapChange?.(owner, wrapper);
+}
+// What this owner does with a child of that Fabric component, or undefined when it does not claim
+// it at all. See `claimedChildren`.
+export function claimModeFor(node, component) {
+    return attached.get(node)?.claimedChildren?.[component];
+}
+// Does this owner key feed the slot's payload? See `slotDerived`. Same `node.childHost` gate as
+// above keeps the WeakMap probe off every node that has no slot.
+export function slotDerivesFrom(node, key) {
+    return attached.get(node)?.slotDerived?.includes(key) === true;
+}
 // The app's listeners for names a behavior owns, per node. Not on the node: this exists only for
 // nodes carrying a behavior, and adding a field for it would pay a shape transition on every node
 // in every app for a feature almost none of them use.
@@ -107,6 +179,12 @@ export function attachHostBehavior(node, tag) {
     // A field rather than a lookup at payload-build time: `fabricProps` runs per node per commit and
     // must not pay a Map probe to discover that almost nothing has a fold.
     node.payloadFold = behavior.foldPayload;
+    // Shape before runtime: `attach` may want to read `node.childHost`, and nothing in `attach`'s
+    // contract depends on the node being childless. Deliberately NOT repeated in `reattachSubtree` —
+    // see `buildStructure`.
+    if (behavior.buildStructure !== undefined) {
+        node.childHost = behavior.buildStructure(node);
+    }
     behavior.attach(node);
     if (behavior.attachAfterCommit !== undefined)
         awaitingCommit.add(node);
@@ -132,20 +210,36 @@ const awaitingCommit = new Set();
  * for the commit that lands it, and `detachSubtree` drops it if that commit never comes.
  */
 export function runDeferredAttaches(isCommitted) {
-    // The gate: an app registering no behavior pays two Set-size reads per commit, matching the
+    // The gate: an app registering no behavior pays one Set-size read per commit, matching the
     // discipline `hasBehaviors` sets for `createElement`.
-    if (awaitingCommit.size === 0 && committedEachTime.size === 0)
+    if (awaitingCommit.size === 0)
         return;
-    // SETUP BEFORE THE RECURRING BEAT, and the order is load-bearing on the FIRST commit, where a
-    // node carrying both hooks is drained by both. `attachAfterCommit` is where a behavior seeds the
-    // mirrors that `afterCommit` then compares against; run them the other way round and the first
-    // beat compares against nothing and commands a redundant write down to native.
     for (const node of awaitingCommit) {
         if (!isCommitted(node))
             continue;
         awaitingCommit.delete(node);
         attached.get(node)?.attachAfterCommit?.(node);
     }
+}
+/**
+ * The recurring beat. Split from `runDeferredAttaches` because the two answer different questions:
+ * `attachAfterCommit` needs a FRESH FABRIC TAG, so it belongs below `completeRoot` and must not run
+ * on a commit that made no native call; `afterCommit` needs only "props were published", which a
+ * no-op commit satisfies just as well.
+ *
+ * Keeping them together made `afterCommit` unreachable for exactly the props a behavior owns: a fold
+ * that STRIPS a prop makes its own commit byte-identical, `commitContainer` returns above the drain,
+ * and the hook never sees the flip. TouchableOpacity's re-settle on `disabled` is the case
+ * (`disabled` is a MACHINE_ONLY key), Button's `title`/`color` the other.
+ *
+ * SETUP STILL RUNS BEFORE THE BEAT on the first commit, and the order is load-bearing: a node
+ * carrying both hooks has `attachAfterCommit` seed the mirrors `afterCommit` compares against. The
+ * caller preserves it by calling this AFTER `runDeferredAttaches` on the changed path — the no-op
+ * path has no setup to run, since a node with no Fabric tag has not committed at all.
+ */
+export function runCommittedHooks(isCommitted) {
+    if (committedEachTime.size === 0)
+        return;
     for (const node of committedEachTime) {
         if (!isCommitted(node))
             continue;
@@ -182,7 +276,13 @@ export function markDetachCandidate(node) {
 //
 // The subtree walk lives here rather than at removal, and is cheaper for it: only the nodes that
 // actually left are walked.
-export function sweepDetachedBehaviors(topLevel) {
+//
+// `onDetached` runs for EVERY node of a genuinely-removed subtree, whether or not it carries a
+// behavior — it is how the engine's other per-node lifetime state (an Animated subscription, see
+// `animated/host-binding.ts`) gets the same "did it really leave" answer this sweep exists to
+// compute. Passed in for the no-cycle reason `runDeferredAttaches`' predicate is: this module must
+// keep pointing one way, and Metro's `inlineRequires` makes that a live hazard rather than taste.
+export function sweepDetachedBehaviors(topLevel, onDetached) {
     if (detachCandidates.size === 0)
         return;
     // A surface's top-level nodes carry `parent === undefined` by design (surface.ts), and
@@ -192,16 +292,31 @@ export function sweepDetachedBehaviors(topLevel) {
     for (const node of detachCandidates) {
         if (node.parent !== undefined || topLevel.includes(node))
             continue;
-        detachSubtree(node, seen);
+        detachSubtree(node, seen, onDetached);
     }
     detachCandidates.clear();
 }
+// Tear a subtree down unconditionally — the SURFACE teardown path, where there is nothing to
+// decide: `disposeRoot` drops the root container, so every node under it has left for good whatever
+// any framework intended.
+//
+// It exists because the sweep above cannot answer this. The sweep only sees nodes a `removeChild`
+// NOMINATED, and an unmount removes nothing — the adapter drops the whole surface. So before this,
+// `disposeRoot` touched no node at all: `committedOf` reads `node.committed`, a field on the node,
+// so every node of a dead surface still answered `isCommitted` and stayed in `committedEachTime`,
+// drained on every later commit anywhere in the process, with its timers still armed.
+export function teardownSubtree(node, onDetached) {
+    detachSubtree(node, new Set(), onDetached);
+}
 // `seen` guards the one overlap the candidate set can contain: a removed parent and a removed
-// descendant of it are both nominated, and without it the descendant is detached twice.
-function detachSubtree(node, seen) {
-    if (seen.has(node))
+// descendant of it are both nominated, and without it the descendant is detached twice. `tornDown`
+// guards the same overlap ACROSS calls — a node the sweep already released and that `disposeRoot`
+// then walks again, which is the ordinary shape of an unmount after the framework emptied the tree.
+function detachSubtree(node, seen, onDetached) {
+    if (seen.has(node) || tornDown.has(node))
         return;
     seen.add(node);
+    onDetached(node);
     // Marked whether or not THIS node carries a behavior: the mark is what tells a later insert to
     // walk, and the node re-inserted is usually a plain container whose DESCENDANT holds the
     // machine. Gating the mark on `behaviors.has` made the row wrapper unmarked and the whole walk
@@ -217,14 +332,11 @@ function detachSubtree(node, seen) {
     // The recurring hook stops with the node, and unlike the deferral above this one has a visible
     // consequence if forgotten: a torn-down node would keep being asked to reconcile props against a
     // subtree that has left the tree, on every commit, forever.
-    // The recurring hook stops with the node, and unlike the deferral above this one has a visible
-    // consequence if forgotten: a torn-down node would keep being asked to reconcile props against a
-    // subtree that has left the tree, on every commit, forever.
     committedEachTime.delete(node);
     // The map, not the registry: by here only the Fabric name is left on the node.
     attached.get(node)?.detach(node);
     for (const child of node.children)
-        detachSubtree(child, seen);
+        detachSubtree(child, seen, onDetached);
 }
 // Re-arms a node the sweep tore down but that the framework put back. Called from appendChild and
 // insertBefore, and it is a WeakSet miss — no walk at all — for every node in a freshly built

package/build/index.d.ts

@@ -1,4 +1,5 @@
-export { createElement, createRawText, createAnchor, isAnchor, appendChild, insertBefore, removeChild, setProp, setEventListener, routeProp, censusRetainedTree, getExplicitStyle, setNodeHidden, setNodeComponent, setNodePressed, setText, isSymbioteNode, isSymbioteEvent, RAW_TEXT_COMPONENT, debugNodeId, } from './node';
+export { createElement, createRawText, createAnchor, ANCHOR_COMPONENT, isAnchor, appendChild, insertBefore, removeChild, setProp, setEventListener, routeProp, censusRetainedTree, getExplicitStyle, setNodeHidden, setNodeComponent, setNodePressed, setText, isSymbioteNode, isSymbioteEvent, RAW_TEXT_COMPONENT, debugNodeId, } from './node';
+export { setAnimatedBehaviorStyle } from './animated/host-binding';
 export { isEventFor } from './view-config';
 export { registerComponent, setNativeViewConfigSource } from './registry';
 export { isRecord } from './type-guards';
@@ -13,7 +14,7 @@ export { setEventDispatcher } from './dispatch';
 export { setColorProcessor, processColor, dispatchViewCommand, sendAccessibilityEvent, setNativeProps, getNativeTag, getNativeNode, whenCommitted, measure, measureInWindow, measureLayout, disposeRoot, readCommitProfile, } from './commit';
 export type { ICommitProfile } from './commit';
 export { registerPostCommit, unregisterPostCommit } from './post-commit';
-export { foldAriaProps } from './accessibility-props';
+export { ARIA_ALIAS_KEYS, foldAriaProps } from './accessibility-props';
 export { toPublicInstance } from './host-instance';
 export type { IHostInstance } from './host-instance';
 export { PlatformColor, DynamicColorIOS, isOpaqueColorValue, } from './platform-color';
@@ -90,7 +91,7 @@ export type { IAccessibilityChangeEvent, IAccessibilityChangeEventName, IAccessi
 export { applyStatusBarProps, statusBarImperative, statusBarCurrentHeight, } from './status-bar';
 export { hideTransition, STATUS_BAR_MANAGER, ANIMATED_HIDE_TRANSITION, STATIC_HIDE_TRANSITION, } from './status-bar/shared';
 export type { IStatusBarProps, IStatusBarStyle, IStatusBarAnimation, IStatusBarImperative, } from './status-bar/shared';
-export { registerHostBehavior, hasHostBehaviors, hostBehaviorFor, clearHostBehaviors, appListenerFor, } from './host-behavior';
-export type { IHostBehavior } from './host-behavior';
+export { registerHostBehavior, hasHostBehaviors, hostBehaviorFor, clearHostBehaviors, appListenerFor, addDerivedNode, } from './host-behavior';
+export type { IClaimMode, IHostBehavior, IPayloadFold } from './host-behavior';
 export { requestCommitFor } from './commit';
-export { setBehaviorListener } from './node';
+export { setBehaviorListener, markPropsDirty } from './node';

package/build/index.js

@@ -2,7 +2,15 @@
 // Every framework adapter drives this tiny mutation API; all Fabric-specific
 // logic (tag allocation, view-name resolution, clone-on-write, event
 // normalization) lives behind it, in one place.
-export { createElement, createRawText, createAnchor, isAnchor, appendChild, insertBefore, removeChild, setProp, setEventListener, routeProp, censusRetainedTree, getExplicitStyle, setNodeHidden, setNodeComponent, setNodePressed, setText, isSymbioteNode, isSymbioteEvent, RAW_TEXT_COMPONENT, debugNodeId, } from './node.js';
+export { createElement, createRawText, createAnchor, 
+// The component name of a node the commit walk skips and whose children flatten into its parent.
+// Exported so a PRIMITIVE that renders no view of its own can be born with it — RN's
+// TouchableNativeFeedback clones onto its single child and commits nothing
+// (TouchableNativeFeedback.js:339) — rather than being converted after the fact.
+ANCHOR_COMPONENT, isAnchor, appendChild, insertBefore, removeChild, setProp, setEventListener, routeProp, censusRetainedTree, getExplicitStyle, setNodeHidden, setNodeComponent, setNodePressed, setText, isSymbioteNode, isSymbioteEvent, RAW_TEXT_COMPONENT, debugNodeId, } from './node.js';
+// For a HOST BEHAVIOR that owns an animated style layer on its own node — TouchableOpacity's press
+// fade, which RN drives from an `Animated.View` the tag replaces.
+export { setAnimatedBehaviorStyle } from './animated/host-binding.js';
 export { isEventFor } from './view-config.js';
 export { registerComponent, setNativeViewConfigSource } from './registry.js';
 // Real cross-package consumer: core/components' KeyboardAvoidingView render narrows
@@ -27,7 +35,7 @@ export { registerPostCommit, unregisterPostCommit } from './post-commit.js';
 // The aria/role -> accessibility* fold. Lives here rather than in a component wrapper because a
 // LOWERED element has no wrapper: `fabricProps` runs it on the way to the payload, so every path
 // gets it. `core/components`' typed `resolveAccessibilityProps` delegates to this one.
-export { foldAriaProps } from './accessibility-props.js';
+export { ARIA_ALIAS_KEYS, foldAriaProps } from './accessibility-props.js';
 // The public instance every host node already is (React's getPublicInstance, the Vue renderer's
 // createElement): the imperative measure/setNativeProps/focus API, on the shared node prototype.
 // toPublicInstance is the identity that names the seam — see ./host-instance.
@@ -91,6 +99,10 @@ export { AccessibilityInfo } from './accessibility-info';
 // .ios re-export would otherwise duplicate-export the type symbols).
 export { applyStatusBarProps, statusBarImperative, statusBarCurrentHeight, } from './status-bar';
 export { hideTransition, STATUS_BAR_MANAGER, ANIMATED_HIDE_TRANSITION, STATIC_HIDE_TRANSITION, } from './status-bar/shared.js';
-export { registerHostBehavior, hasHostBehaviors, hostBehaviorFor, clearHostBehaviors, appListenerFor, } from './host-behavior.js';
+export { registerHostBehavior, hasHostBehaviors, hostBehaviorFor, clearHostBehaviors, appListenerFor, addDerivedNode, } from './host-behavior.js';
 export { requestCommitFor } from './commit.js';
-export { setBehaviorListener } from './node.js';
+// `markPropsDirty` is a behavior's only way to say "the fold reads state I just changed". Every
+// other dirtying route goes through a prop write, and a behavior whose payload is DERIVED — the
+// sticky header's debounced translateY lives in its own runtime, not in `node.props` — has no
+// prop to write. Pair it with `requestCommitFor`: dirtying is not publishing.
+export { setBehaviorListener, markPropsDirty } from './node.js';

package/build/node.d.ts

@@ -29,12 +29,23 @@ export interface ISymbioteNode {
     structureDirty: boolean;
     committed: IMirror | undefined;
     styleParts: IClassStyleParts | undefined;
+    childHost: ISymbioteNode | undefined;
+    wrapper: ISymbioteNode | undefined;
     measure(callback: IMeasureOnSuccess): void;
     measureInWindow(callback: IMeasureInWindowOnSuccess): void;
     measureLayout(relativeToNativeNode: ISymbioteNode | number, onSuccess: IMeasureLayoutOnSuccess, onFail?: () => void): void;
     setNativeProps(nativeProps: Record<string, unknown>): void;
     focus(): void;
     blur(): void;
+    scrollTo(options?: {
+        x?: number;
+        y?: number;
+        animated?: boolean;
+    }): void;
+    scrollToEnd(options?: {
+        animated?: boolean;
+    }): void;
+    flashScrollIndicators(): void;
 }
 export interface IMirror {
     handle: IFabricNode;
@@ -104,8 +115,13 @@ export declare function setProp(node: ISymbioteNode, key: string, value: unknown
  * `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 declare function setBehaviorListener(node: ISymbioteNode, name: string, listener: IListener): void;
+export declare function setBehaviorListener(node: ISymbioteNode, name: string, listener: IListener | undefined): void;
 export declare function setEventListener(node: ISymbioteNode, name: string, value: unknown): void;
 export interface IClassStyleParts {
     classStyle: unknown;
@@ -141,9 +157,9 @@ export declare function setNodePressed(node: ISymbioteNode, pressed: boolean): v
 export declare function getExplicitStyle(node: ISymbioteNode): unknown;
 export declare function routeProp(node: ISymbioteNode, key: string, value: unknown): void;
 export declare function setText(node: ISymbioteNode, text: string): void;
-export declare function appendChild(parent: ISymbioteNode, child: ISymbioteNode): void;
-export declare function insertBefore(parent: ISymbioteNode, child: ISymbioteNode, beforeChild: ISymbioteNode): void;
-export declare function removeChild(parent: ISymbioteNode, child: ISymbioteNode): void;
+export declare function appendChild(requestedParent: ISymbioteNode, child: ISymbioteNode): void;
+export declare function insertBefore(requestedParent: ISymbioteNode, child: ISymbioteNode, beforeChild: ISymbioteNode | null): void;
+export declare function removeChild(requestedParent: ISymbioteNode, child: ISymbioteNode): void;
 export interface ITreeCensus {
     nodes: number;
     anchors: number;