@symbiote-native/engine 0.3.0 → 0.5.0

package/build/fabric.d.ts

@@ -13,8 +13,9 @@ export type IMeasureLayoutOnSuccess = (left: number, top: number, width: number,
 export interface IFabricSlot {
     createNode(reactTag: number, viewName: string, rootTag: IRootTag, props: IFabricProps, instanceHandle: unknown): IFabricNode;
     cloneNodeWithNewProps(node: IFabricNode, newProps: IFabricProps): IFabricNode;
-    cloneNodeWithNewChildren(node: IFabricNode): IFabricNode;
-    cloneNodeWithNewChildrenAndProps(node: IFabricNode, newProps: IFabricProps): IFabricNode;
+    cloneNodeWithNewChildren(node: IFabricNode, children?: readonly IFabricNode[]): IFabricNode;
+    cloneNodeWithNewChildrenAndProps(node: IFabricNode, newProps: IFabricProps, children?: readonly IFabricNode[]): IFabricNode;
+    supportsCloneWithChildren: boolean;
     createChildSet(rootTag: IRootTag): IFabricChildSet;
     appendChild(parent: IFabricNode, child: IFabricNode): IFabricNode;
     appendChildToSet(childSet: IFabricChildSet, child: IFabricNode): void;
@@ -22,11 +23,18 @@ 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;
 }
+interface IFabricHost extends Omit<IFabricSlot, 'cloneNodeWithNewChildren' | 'cloneNodeWithNewChildrenAndProps' | 'supportsCloneWithChildren'> {
+    cloneNodeWithNewChildren(node: IFabricNode, children?: readonly IFabricNode[]): IFabricNode;
+    cloneNodeWithNewChildrenAndProps(node: IFabricNode, newProps: IFabricProps): IFabricNode;
+    cloneNodeWithNewChildrenAndProps(node: IFabricNode, children: readonly IFabricNode[], newProps: IFabricProps): IFabricNode;
+}
 declare global {
-    var nativeFabricUIManager: IFabricSlot | undefined;
+    var nativeFabricUIManager: IFabricHost | undefined;
 }
 export declare function getSlot(): IFabricSlot;
+export {};

package/build/fabric.js

@@ -29,14 +29,24 @@ 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;
     cached = {
         createNode: (reactTag, viewName, rootTag, props, instanceHandle) => createNode(reactTag, viewName, rootTag, props, instanceHandle),
         cloneNodeWithNewProps: (node, newProps) => cloneNodeWithNewProps(node, newProps),
-        cloneNodeWithNewChildren: node => cloneNodeWithNewChildren(node),
-        cloneNodeWithNewChildrenAndProps: (node, newProps) => cloneNodeWithNewChildrenAndProps(node, newProps),
+        // The host's 3-arg form is (node, children, props); ours keeps props second.
+        cloneNodeWithNewChildren: (node, children) => children === undefined
+            ? cloneNodeWithNewChildren(node)
+            : cloneNodeWithNewChildren(node, children),
+        cloneNodeWithNewChildrenAndProps: (node, newProps, children) => children === undefined
+            ? cloneNodeWithNewChildrenAndProps(node, newProps)
+            : cloneNodeWithNewChildrenAndProps(node, children, newProps),
+        supportsCloneWithChildren: typeof cloneNodeWithNewChildren === 'function' &&
+            cloneNodeWithNewChildren.length >= 2 &&
+            typeof cloneNodeWithNewChildrenAndProps === 'function' &&
+            cloneNodeWithNewChildrenAndProps.length >= 3,
         createChildSet: rootTag => createChildSet(rootTag),
         appendChild: (parent, child) => appendChild(parent, child),
         appendChildToSet: (childSet, child) => appendChildToSet(childSet, child),
@@ -50,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

@@ -0,0 +1,84 @@
+import type { ISymbioteNode } from './node';
+/**
+ * A pure props -> props mapping a behavior applies on the way to the Fabric payload.
+ *
+ * It exists because a lowered element has no component body, and a wrapper's body is where the
+ * per-primitive prop FOLDS live — TextInput's W3C aliases (`inputMode` -> `keyboardType`,
+ * `readOnly` -> `editable`), Pressable's `disabled` -> `accessibilityState`. Every one of those was
+ * silently dropped the moment the primitive lowered: the raw alias reached Fabric as a key no
+ * ViewConfig declares, so nothing threw and nothing rendered differently in a headless test —
+ * only the device showed a numeric keyboard that never appeared.
+ *
+ * NOT a hook on `setProp`, for the same reason `afterCommit` is not: `setProp` is the hottest path
+ * in the engine. This runs once per node per payload build, and only for a node whose behavior
+ * supplied one.
+ *
+ * MUST be pure and MUST NOT mutate its input — `node.props` is the live bag, and the folds beside
+ * 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;
+}
+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;
+export declare function attachHostBehavior(node: ISymbioteNode, tag: string): void;
+/**
+ * Run the deferred half of every behavior whose node has now been committed. Called from the commit
+ * path immediately after `completeRoot`, where fresh Fabric tags have just been assigned.
+ *
+ * `isCommitted` is passed in for the same no-cycle reason — `committedOf` lives in `commit.ts`. A
+ * still-uncommitted node stays in the set: a create superseded before it ever reached Fabric waits
+ * 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[], 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

@@ -0,0 +1,374 @@
+// Per-TAG behavior on an engine node — the seam that lets a primitive's state machine live BELOW
+// the framework instead of inside a framework component.
+//
+// WHY IT EXISTS. Vue, Svelte, Solid and Angular all optimize element subtrees and stop at a
+// component boundary, so a primitive shipped as a component is charged a per-instance price in
+// each framework's own currency (an instance, a props Proxy, anchor nodes, an LView). A primitive
+// whose state the TEMPLATE never reads does not need to be a component at all — its machine only
+// needs a per-node home, and the engine node is one. `.claude/rules/host-primitive-tier.md` has
+// the tier model; this module is the tier-2 half of it.
+//
+// WHY A REGISTRY RATHER THAN A DIRECT IMPORT. `@symbiote-native/components` depends on
+// `@symbiote-native/engine`, never the reverse, so the engine cannot import `createPressHandlers`
+// and friends. CLAUDE.md's preferred answer to a registration problem — delete the indirection —
+// is therefore unavailable here; the inversion is forced, not chosen.
+//
+// WHICH MEANS THE REGISTRATION ITSELF IS THE HAZARD, and it is the one CLAUDE.md spells out:
+// Metro turns on `inlineRequires` for production only, moving a `require` down to the first place
+// its binding is used as a VALUE, and a barrel's `export { X } from './x'` compiles to a lazy
+// getter. A module whose only job is to call `registerHostBehavior` is never named as a value, so
+// re-exporting it from a barrel means it NEVER EVALUATES in a release build — dev is perfect,
+// release silently has no behavior. The one shape that works is a bare side-effect import that is
+// never re-exported from that barrel, the pattern in
+// `packages/slider/src/{react,vue,svelte,angular}/index.ts`:
+//
+//     import '../register';     // in the adapter entry — NOT `export * from '../register'`
+//
+// `registerHostBehavior` emits a `dlog` precisely so `DEBUG=1` answers "did my registration run at
+// all" before anyone starts debugging the behavior itself.
+import { dlog } from './debug.js';
+const behaviors = new Map();
+// Nodes that `removeChild` unlinked and that may or may not be coming back. See
+// `sweepDetachedBehaviors` for why the answer is not known until commit.
+const detachCandidates = new Set();
+// Nodes the sweep has torn down. A torn-down node can still be re-inserted — see
+// `reattachHostBehaviors` — and this is what tells an insert whether it must walk at all, so the
+// common case (building a fresh tree) never walks anything.
+const tornDown = new WeakSet();
+// The behavior a node actually got, remembered from its one and only registry lookup.
+//
+// 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
+// `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.
+//
+// Found by a peer session probing the installed shape, not by a unit test: the tests built their
+// subject with `createElement(PRESSABLE_TAG)`, which passes the tag AS the Fabric name and makes
+// the key match by accident. No adapter constructs a node that way, so the registration could
+// never have fired in an app while all six break-tests kept failing correctly on their own axes.
+const attached = new WeakMap();
+// The gate. `createElement` and `removeChild` are the two hottest paths in the engine (9 002 and
+// ~1 000 calls on one benchmark row set), so neither may pay a Set insert for a feature no app
+// uses yet. While this is false both paths cost one boolean read, the same discipline as `isDebug`.
+let hasBehaviors = false;
+export function registerHostBehavior(component, behavior) {
+    dlog(`registerHostBehavior: ${component}`);
+    behaviors.set(component, behavior);
+    hasBehaviors = true;
+}
+// Read access to the registry, so an audit can DERIVE what a behavior owns instead of restating it.
+// The one that matters: a name in `ownedListeners` is only reachable if `routeProp` also treats it
+// as a registered event — otherwise the app's callback lands in `node.props` and the machine, which
+// reads the stash, never sees it. That set difference is a test
+// (`core/components/src/behaviors/owned-listeners-are-routable.test.ts`) and it needs this to stay
+// derived rather than becoming another hand-written list.
+export function hostBehaviorFor(tag) {
+    return behaviors.get(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.
+const stashed = new WeakMap();
+// Takes the NODE, not a component string: the caller (`setEventListener`) has only the Fabric name
+// by then, which is not the registry's alphabet. Reads the same map `attachHostBehavior` wrote.
+export function ownsListener(node, name) {
+    return attached.get(node)?.ownedListeners?.includes(name) === true;
+}
+export function stashAppListener(node, name, listener) {
+    let bag = stashed.get(node);
+    if (bag === undefined) {
+        bag = new Map();
+        stashed.set(node, bag);
+    }
+    if (listener === undefined)
+        bag.delete(name);
+    else
+        bag.set(name, listener);
+}
+// What the app wrote for an owned event name — the behavior's OUTPUT target. Undefined when the
+// app wired nothing, which is an ordinary case, not an error.
+export function appListenerFor(node, name) {
+    return stashed.get(node)?.get(name);
+}
+// `tag` is the INTRINSIC tag the adapter started from, not the resolved Fabric name it put on the
+// node. Defaulted to `node.component` so an adapter that has not been taught to pass it keeps
+// working for a behavior registered under a Fabric name — no adapter registers one, so in practice
+// the default simply never matches and costs one failed lookup.
+export function attachHostBehavior(node, tag) {
+    const behavior = behaviors.get(tag);
+    if (behavior === undefined)
+        return;
+    attached.set(node, behavior);
+    // 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);
+    if (behavior.afterCommit !== undefined)
+        committedEachTime.add(node);
+}
+// Nodes whose behavior declared `afterCommit`. Separate from `awaitingCommit` because the two have
+// opposite lifetimes: one empties as its nodes commit, this one holds until teardown.
+const committedEachTime = new Set();
+// Nodes whose behavior declared `attachAfterCommit` and whose first commit has not happened yet.
+//
+// A plain Set rather than a call into `whenCommitted`: `commit.ts` already imports this module, so
+// reaching back for it would close an import cycle. Metro's `inlineRequires` has made module
+// evaluation order a real hazard here rather than a theoretical one (see this file's own
+// registration comment), so the dependency stays one-directional and commit DRAINS this instead.
+const awaitingCommit = new Set();
+/**
+ * Run the deferred half of every behavior whose node has now been committed. Called from the commit
+ * path immediately after `completeRoot`, where fresh Fabric tags have just been assigned.
+ *
+ * `isCommitted` is passed in for the same no-cycle reason — `committedOf` lives in `commit.ts`. A
+ * still-uncommitted node stays in the set: a create superseded before it ever reached Fabric waits
+ * 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 one Set-size read per commit, matching the
+    // discipline `hasBehaviors` sets for `createElement`.
+    if (awaitingCommit.size === 0)
+        return;
+    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;
+        attached.get(node)?.afterCommit?.(node);
+    }
+}
+// `removeChild` is NOT the destroy signal, and reading it as one is the bug this indirection
+// exists to avoid. Engine-side it looks like one — a reorder goes through `detach` inside
+// appendChild/insertBefore and never lands in removeChild — but a FRAMEWORK can spell a move as
+// remove-then-reinsert. Solid does, in `solid-js/universal`: `replaceNode` (universal.cjs:186) is
+// `insertNode` + `removeNode`, and `reconcileArrays` calls it at :157 for a node that IS in the
+// new array and is needed at a later index. Its sibling call at :130 is guarded by
+// `if (!map || !map.has(a[aStart]))` and removes only genuinely absent nodes — one guarded call
+// and one not, which is why a quick read of that file says "removeChild means gone".
+//
+// Tearing down there would kill the machine of a node that returns alive a few operations later,
+// in the same batch: long-press silently stops working after certain list reorders, on device
+// only, with nothing red. So removal only nominates.
+export function markDetachCandidate(node) {
+    detachCandidates.add(node);
+}
+// Commit is where a removal is CHEAPEST to distinguish from a move — a node unlinked and
+// reinserted before the commit is back in the tree by now, which covers Solid's replaceNode. It is
+// NOT a proof of death, and the earlier version of this comment claimed it was. Svelte parks LIVE
+// nodes offscreen across commits and sometimes across seconds: `detachFromParent`
+// (adapters/svelte/src/dom-shim/shim-node.ts) moves a node into a DocumentFragment that has no
+// engine node, calls engineRemoveChild AND requestCommit, and Svelte fully intends to bring it
+// back — from a parked `{#if}` branch, from `each.js`'s destroy_effects, and worst, from
+// boundary.js's move_effect while a pending snippet shows, which returns when async work resolves.
+// So a sweep can and does tear down a node that comes back, which is why `attach` is re-runnable
+// (reattachHostBehaviors) rather than why the sweep tries to be cleverer. The machine RESTARTS on
+// re-insert instead of surviving an arbitrary absence; a parked subtree is offscreen, so nobody is
+// mid-gesture in it, and teardown staying unconditional means there is no leak mode.
+//
+// The subtree walk lives here rather than at removal, and is cheaper for it: only the nodes that
+// actually left are walked.
+//
+// `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
+    // `commitChildren` re-lists them without going through appendChild — so for those the parent
+    // check alone would report a live node as gone.
+    const seen = new Set();
+    for (const node of detachCandidates) {
+        if (node.parent !== undefined || topLevel.includes(node))
+            continue;
+        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. `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
+    // skip — the first version of the parked-node test caught exactly that.
+    tornDown.add(node);
+    // Drop a deferral the node never got to run. NO TEST CAN SEE THIS, and it is kept anyway —
+    // stated rather than left as apparent coverage. The `isCommitted` predicate in the drain already
+    // stops such a node from firing, so removing this line changes no observable behaviour; what it
+    // changes is that a node created and torn down inside one tick stays in the Set forever, holding
+    // a strong reference to a dead subtree. A leak, not a wrong result, and this file's break-test
+    // discipline correctly reports it as unfalsifiable.
+    awaitingCommit.delete(node);
+    // 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, 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
+// tree, which is the path that runs ~9 000 times per benchmark create.
+export function reattachHostBehaviors(node) {
+    if (!tornDown.has(node))
+        return;
+    reattachSubtree(node);
+}
+function reattachSubtree(node) {
+    if (tornDown.has(node)) {
+        tornDown.delete(node);
+        const behavior = attached.get(node);
+        behavior?.attach(node);
+        // Re-arm the deferred half too. A parked node usually returns with its tag intact, so this
+        // fires on the next drain — but re-arming is what keeps `attach` and `attachAfterCommit` a
+        // PAIR. Restore only one and a behavior that splits its setup across the two comes back
+        // half-initialised, which is the failure this seam exists to prevent.
+        if (behavior?.attachAfterCommit !== undefined)
+            awaitingCommit.add(node);
+        if (behavior?.afterCommit !== undefined)
+            committedEachTime.add(node);
+    }
+    for (const child of node.children)
+        reattachSubtree(child);
+}
+// Test-only. A registry is module state, so a suite that registers a behavior leaks it into every
+// later test in the same file unless it is cleared.
+export function clearHostBehaviors() {
+    behaviors.clear();
+    detachCandidates.clear();
+    awaitingCommit.clear();
+    committedEachTime.clear();
+    hasBehaviors = false;
+}

package/build/host-instance/index.d.ts

@@ -1,11 +1,3 @@
-import { type ISymbioteNode } from '../node';
-import type { IMeasureOnSuccess, IMeasureInWindowOnSuccess, IMeasureLayoutOnSuccess } from '../fabric';
-export interface IHostInstance extends ISymbioteNode {
-    measure(callback: IMeasureOnSuccess): void;
-    measureInWindow(callback: IMeasureInWindowOnSuccess): void;
-    measureLayout(relativeToNativeNode: IHostInstance | number, onSuccess: IMeasureLayoutOnSuccess, onFail?: () => void): void;
-    setNativeProps(nativeProps: Record<string, unknown>): void;
-    focus(): void;
-    blur(): void;
-}
+import type { ISymbioteNode } from '../node';
+export type IHostInstance = ISymbioteNode;
 export declare function toPublicInstance(node: ISymbioteNode): IHostInstance;

package/build/host-instance/index.js

@@ -1,49 +1,16 @@
-// The public instance a host ref hands back, RN's ReactFabricHostComponent. toPublicInstance
-// augments the retained node with the imperative API libraries reach through (reanimated,
-// gesture-handler, react-navigation): measure / measureInWindow / measureLayout /
-// setNativeProps / focus / blur. The methods are attached onto the node object itself (not its
-// props, so they never reach Fabric); each resolves the node's CURRENT committed handle at call
-// time through the engine, so a clone-on-write commit between calls is transparent.
+// The public instance a host ref hands back, RN's ReactFabricHostComponent: measure /
+// measureInWindow / measureLayout / setNativeProps / focus / blur, the imperative API libraries
+// reach through (reanimated, gesture-handler, react-navigation).
 //
-// This lives in the engine, not an adapter: it depends only on engine internals (the commit
-// free functions + the retained node), so every adapter inherits the SAME public instance for
-// free — React's getPublicInstance and the Vue renderer both graft this onto their host nodes.
-import { measure as engineMeasure, measureInWindow as engineMeasureInWindow, measureLayout as engineMeasureLayout, setNativeProps as engineSetNativeProps, dispatchViewCommand, } from '../commit.js';
-import { isSymbioteNode } from '../node.js';
-import { dlog } from '../debug.js';
-const FOCUS_COMMAND = 'focus';
-const BLUR_COMMAND = 'blur';
-function isHostInstance(node) {
-    return typeof Reflect.get(node, 'measure') === 'function';
-}
-// Augment the retained node with the public-instance methods, once. The same node
-// instance persists across commits, so attaching once is enough, every method reads
-// the live handle through the engine on each call.
+// EVERY retained node already carries it — the six methods live on the shared node prototype
+// (`SymbioteNode` in ../node), so there is nothing left to graft and `toPublicInstance` is the
+// identity. It used to Object.assign six fresh closures onto each node; that cost 54 000 closures
+// per 1 000-row create and made GC the largest bucket in the profile. The rationale, and why
+// React was the one adapter not paying it, is recorded on ISymbioteNode.
+//
+// The function and the type both stay: they are the seam every adapter names (React's
+// getPublicInstance, Vue's nodeOps createElement, Angular's Renderer2, Svelte's dom-shim), and a
+// call site saying "hand me the public instance" still reads correctly at a no-op.
 export function toPublicInstance(node) {
-    if (isHostInstance(node))
-        return node;
-    return Object.assign(node, {
-        measure(callback) {
-            engineMeasure(node, callback);
-        },
-        measureInWindow(callback) {
-            engineMeasureInWindow(node, callback);
-        },
-        measureLayout(relativeToNativeNode, onSuccess, onFail) {
-            if (!isSymbioteNode(relativeToNativeNode)) {
-                dlog('measureLayout: relative target must be a host ref');
-                return;
-            }
-            engineMeasureLayout(node, relativeToNativeNode, onSuccess, onFail);
-        },
-        setNativeProps(nativeProps) {
-            engineSetNativeProps(node, nativeProps);
-        },
-        focus() {
-            dispatchViewCommand(node, FOCUS_COMMAND, []);
-        },
-        blur() {
-            dispatchViewCommand(node, BLUR_COMMAND, []);
-        },
-    });
+    return node;
 }

package/build/index.d.ts

@@ -1,4 +1,5 @@
-export { createElement, createRawText, createAnchor, isAnchor, appendChild, insertBefore, removeChild, setProp, setEventListener, routeProp, censusRetainedTree, getExplicitStyle, setNodeHidden, 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,6 +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 { 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';
@@ -89,3 +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, addDerivedNode, } from './host-behavior';
+export type { IClaimMode, IHostBehavior, IPayloadFold } from './host-behavior';
+export { requestCommitFor } from './commit';
+export { setBehaviorListener, markPropsDirty } from './node';