@symbiote-native/engine 1.0.0 → 1.1.0

package/build/host-access.d.ts

@@ -40,6 +40,14 @@ export declare function childrenOf(node: ISymbioteNode): readonly ISymbioteNode[
 export declare function parentsOf(nodes: readonly ISymbioteNode[]): readonly (ISymbioteNode | undefined)[];
 /** Each root and every descendant, pre-order, anchors included — all of it in ONE crossing. */
 export declare function subtreesOf(roots: readonly ISymbioteNode[]): readonly ISymbioteNode[];
+/**
+ * The same walk narrowed to what a teardown must visit — see `ITreeHost.teardownSubtreesOf`.
+ *
+ * The gate is the ANIMATED one, not a behavior one: a binding is per node and carries no tag, so an
+ * app that animates needs every node back and gets the full walk. Nothing else narrows, because
+ * nothing else is charged per node of a removed subtree.
+ */
+export declare function teardownSubtreesOf(roots: readonly ISymbioteNode[]): readonly ISymbioteNode[];
 /**
  * The node and every ancestor above it, deepest first, in ONE crossing.
  *
@@ -52,7 +60,19 @@ export declare function subtreesOf(roots: readonly ISymbioteNode[]): readonly IS
  * chain it would have built by walking.
  */
 export declare function ancestorsOf(node: ISymbioteNode): readonly ISymbioteNode[];
-/** The first child, anchors included, or `undefined` for a leaf. */
+/**
+ * The first child, anchors included, or `undefined` for a leaf.
+ *
+ * ONE HOST CALL, not `childrenOf(node)[0]`, and the difference is a complexity class rather than a
+ * constant. `solid-js/universal`'s `cleanChildren` empties a parent with
+ * `while (removed = getFirstChild(parent)) removeNode(parent, removed)` — so the old spelling read a
+ * list of N, then N-1, then N-2, building and discarding every handle each time. Measured on a
+ * 2 000-row Solid `Clear` (`solid-clear-scaling.itest.tsx`): **2 001 001 handles** crossed to remove
+ * two thousand children, N(N+1)/2 to the unit, against the ~2 000 the work needs.
+ *
+ * The `mayHaveChildren` fast path is kept for the same reason `childrenOf` has it: FALSE is a
+ * certainty, so a leaf answers without a drain and without a crossing.
+ */
 export declare function firstChildOf(node: ISymbioteNode): ISymbioteNode | undefined;
 /**
  * The next sibling, or `undefined` at the end of the list.

package/build/host-access.js

@@ -36,6 +36,7 @@
 // would build three JS trees instead of the one being removed.
 import { flushOps, settleBeforeFlush, treeHost } from './tree-host.js';
 import { hasPendingPlacement } from './mutation-buffer.js';
+import { hasAnimatedBindings } from './animated/host-binding.js';
 import { functionPropOf, functionPropsOf, isSymbioteNode, RAW_TEXT_COMPONENT, SURFACE_COMPONENT, } from './node.js';
 // One frozen empty list rather than a fresh `[]`, because the fast path in `childrenOf` is the
 // common answer during a build: solid asks 2 000 times on a 1 000-row create and every answer is
@@ -117,8 +118,26 @@ export function parentsOf(nodes) {
 /** Each root and every descendant, pre-order, anchors included — all of it in ONE crossing. */
 export function subtreesOf(roots) {
     flushOps();
+    // The `.filter` is the type NARROWING, not a defensive check, and it costs ~0.6 ms of the 5.5 ms
+    // a thousand-row clear spends in the engine — measured on `build-release` by returning the host's
+    // array unnarrowed (`teardown-sweep-cost.itest.ts`, rest of the sweep 2.75 -> 2.16 ms). It stays,
+    // because removing it means either an `as` or declaring `ITreeHost.subtreesOf` to hand back our
+    // own type, and a pluggable host is exactly what that `object` boundary is for.
     return treeHost()?.subtreesOf(roots).filter(isSymbioteNode) ?? [];
 }
+/**
+ * The same walk narrowed to what a teardown must visit — see `ITreeHost.teardownSubtreesOf`.
+ *
+ * The gate is the ANIMATED one, not a behavior one: a binding is per node and carries no tag, so an
+ * app that animates needs every node back and gets the full walk. Nothing else narrows, because
+ * nothing else is charged per node of a removed subtree.
+ */
+export function teardownSubtreesOf(roots) {
+    if (hasAnimatedBindings())
+        return subtreesOf(roots);
+    flushOps();
+    return treeHost()?.teardownSubtreesOf(roots).filter(isSymbioteNode) ?? [];
+}
 /**
  * The node and every ancestor above it, deepest first, in ONE crossing.
  *
@@ -143,9 +162,25 @@ export function ancestorsOf(node) {
     }
     return out;
 }
-/** The first child, anchors included, or `undefined` for a leaf. */
+/**
+ * The first child, anchors included, or `undefined` for a leaf.
+ *
+ * ONE HOST CALL, not `childrenOf(node)[0]`, and the difference is a complexity class rather than a
+ * constant. `solid-js/universal`'s `cleanChildren` empties a parent with
+ * `while (removed = getFirstChild(parent)) removeNode(parent, removed)` — so the old spelling read a
+ * list of N, then N-1, then N-2, building and discarding every handle each time. Measured on a
+ * 2 000-row Solid `Clear` (`solid-clear-scaling.itest.tsx`): **2 001 001 handles** crossed to remove
+ * two thousand children, N(N+1)/2 to the unit, against the ~2 000 the work needs.
+ *
+ * The `mayHaveChildren` fast path is kept for the same reason `childrenOf` has it: FALSE is a
+ * certainty, so a leaf answers without a drain and without a crossing.
+ */
 export function firstChildOf(node) {
-    return childrenOf(node)[0];
+    if (!node.mayHaveChildren)
+        return undefined;
+    flushOps();
+    const child = treeHost()?.firstChildOf(node);
+    return isSymbioteNode(child) ? child : undefined;
 }
 /**
  * The next sibling, or `undefined` at the end of the list.

package/build/host-behavior.d.ts

@@ -82,9 +82,9 @@ export declare function hasHostBehaviors(): boolean;
  * all of it inside the commit. `Clear` is the one row where stock React Native beats every adapter.
  *
  * Nothing the sweep does can matter before the first attach, and the four collections say so:
- * `attached` is written only by `attachHostBehavior`; `awaitingCommit` and `committedEachTime` are
+ * `node.hostBehavior` is written only by `attachHostBehavior`; `awaitingCommit` and `committedEachTime` are
  * written only inside a `behavior.` branch; `parked` only by `detachAnimatedProps`, which has its
- * own gate. The one remaining effect is marking `tornDown`, which exists so a later re-insert knows
+ * own gate. The one remaining effect is marking `isTornDown`, which exists so a later re-insert knows
  * to re-arm — and there is nothing to re-arm.
  *
  * MONOTONE, deliberately: it turns on and never off, so it needs no accounting on a `WeakMap` that

package/build/host-behavior.js

@@ -26,18 +26,25 @@
 //
 // `registerHostBehavior` emits a `dlog` precisely so `DEBUG=1` answers "did my registration run at
 // all" before anyone starts debugging the behavior itself.
-import { parentsOf, subtreesOf } from './host-access.js';
+import { parentsOf, teardownSubtreesOf } from './host-access.js';
 import { recordSetTag } from './mutation-buffer.js';
 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
+// A node the sweep has torn down carries `node.isTornDown`. It can still be re-inserted — see
+// `reattachHostBehaviors` — and the bit 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.
+//
+// A FIELD rather than the `WeakSet` it was, for the reason `slotBatch` is one: both of its readers
+// are per-node paths at list scale — the sweep touches every node of a removed subtree, and every
+// insert asks the question once.
+// The behavior a node actually got lives on the NODE, as `node.hostBehavior`, remembered from its
+// one and only registry lookup. A field rather than the `WeakMap` it was, for the reason
+// `node.payloadFold` — written on the next line of `attachHostBehavior` — already is one: every
+// reader here is a per-node path at list scale, and a `WeakMap` probe is the dearest way to ask a
+// question whose answer is almost always "none".
 //
 // 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
@@ -50,7 +57,6 @@ const tornDown = new WeakSet();
 // 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`.
@@ -87,9 +93,9 @@ export function hasHostBehaviors() {
  * all of it inside the commit. `Clear` is the one row where stock React Native beats every adapter.
  *
  * Nothing the sweep does can matter before the first attach, and the four collections say so:
- * `attached` is written only by `attachHostBehavior`; `awaitingCommit` and `committedEachTime` are
+ * `node.hostBehavior` is written only by `attachHostBehavior`; `awaitingCommit` and `committedEachTime` are
  * written only inside a `behavior.` branch; `parked` only by `detachAnimatedProps`, which has its
- * own gate. The one remaining effect is marking `tornDown`, which exists so a later re-insert knows
+ * own gate. The one remaining effect is marking `isTornDown`, which exists so a later re-insert knows
  * to re-arm — and there is nothing to re-arm.
  *
  * MONOTONE, deliberately: it turns on and never off, so it needs no accounting on a `WeakMap` that
@@ -104,7 +110,7 @@ export function hasAttachedBehaviors() {
 // 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);
+    const behavior = node.hostBehavior;
     if (behavior === undefined)
         return undefined;
     const named = behavior.slotProps?.[key];
@@ -119,7 +125,7 @@ export function slotPropNameFor(node, key) {
 // `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;
+    return node.hostBehavior?.slotTakesNoChildren !== true;
 }
 // Nodes a behavior built that are NOT the slot, and whose payloads derive from the owner's props.
 //
@@ -149,16 +155,16 @@ export function derivedNodesOf(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);
+    node.hostBehavior?.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);
+    node.hostBehavior?.onChildInserted?.(node, child);
 }
 // 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];
+    return node.hostBehavior?.claimedChildren?.[component];
 }
 /**
  * Every owner key feeds the slot. The spelling for a `cloneElement` primitive, whose slot is not
@@ -171,7 +177,7 @@ export const SLOT_DERIVED_ALL = '*';
 // 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) {
-    const names = attached.get(node)?.slotDerived;
+    const names = node.hostBehavior?.slotDerived;
     if (names === undefined)
         return false;
     return names.includes(SLOT_DERIVED_ALL) || names.includes(key);
@@ -183,7 +189,7 @@ 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;
+    return node.hostBehavior?.ownedListeners?.includes(name) === true;
 }
 export function stashAppListener(node, name, listener) {
     let bag = stashed.get(node);
@@ -209,7 +215,7 @@ export function attachHostBehavior(node, tag) {
     const behavior = behaviors.get(tag);
     if (behavior === undefined)
         return;
-    attached.set(node, behavior);
+    node.hostBehavior = behavior;
     hasAttached = true;
     // The tag itself, over the wire, so the host can resolve this tag's PLATFORM props without a trip
     // back into JS. Here rather than in `createElement` because here is where a tag is known to name
@@ -276,7 +282,7 @@ export function runDeferredAttaches(isCommitted) {
         // boundary — so a node carrying both hooks paid two crossings for one fact on the commit that
         // landed it. Two per `<text-input>` on a 1 000-row create, measured at the call site.
         everCommitted.add(node);
-        attached.get(node)?.attachAfterCommit?.(node);
+        node.hostBehavior?.attachAfterCommit?.(node);
     }
 }
 /**
@@ -347,7 +353,7 @@ export function runCommittedHooks(isCommitted) {
             }
             everCommitted.add(node);
         }
-        attached.get(node)?.afterCommit?.(node);
+        node.hostBehavior?.afterCommit?.(node);
     }
 }
 // Nodes of `committedEachTime` that have reached Fabric at least once.
@@ -430,7 +436,10 @@ export function sweepDetachedBehaviors(topLevel, onDetached) {
     // `commitChildren` re-lists them without going through appendChild — so for those the parent
     // check alone would report a live node as gone.
     const left = candidates.filter((node, at) => parents[at] === undefined && !topLevel.includes(node));
-    for (const node of subtreesOf(left))
+    // NARROWED, and it is the sweep's whole cost: what crosses is a handle per node, and on the
+    // benchmark row eight of every ten are plain views the sweep would mark and do nothing else
+    // with. See `ITreeHost.teardownSubtreesOf` for which nodes come back and why an ancestor must.
+    for (const node of teardownSubtreesOf(left))
         detachOne(node, onDetached);
     detachCandidates.clear();
 }
@@ -444,10 +453,12 @@ export function sweepDetachedBehaviors(topLevel, onDetached) {
 // 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) {
-    for (const each of subtreesOf([node]))
+    // Narrowed for the same reason the sweep is, and with more to gain: this path tears down a whole
+    // SURFACE, so the subtree is the screen.
+    for (const each of teardownSubtreesOf([node]))
         detachOne(each, onDetached);
 }
-// `tornDown` guards BOTH overlaps, and it used to be helped by a per-call `seen` Set that guarded
+// `isTornDown` guards BOTH overlaps, and it used to be helped by a per-call `seen` Set that guarded
 // only the first of them:
 //
 //   within one call    a removed parent and a removed descendant are both nominated, so the
@@ -455,7 +466,7 @@ export function teardownSubtree(node, onDetached) {
 //   across calls       a node the sweep released and that `disposeRoot` then walks again, the
 //                      ordinary shape of an unmount after the framework emptied the tree
 //
-// `seen` was redundant for the first: `tornDown.add(node)` runs unconditionally two lines below the
+// `seen` was redundant for the first: the mark is raised unconditionally two lines below the
 // guard, in the same call, so a second arrival takes the same early return. The only behaviour it
 // changed was after a THROWING `onDetached`, where the node would be retried — and a sweep that
 // threw half way has already left the tree in a state no retry repairs.
@@ -468,17 +479,24 @@ export function teardownSubtree(node, onDetached) {
 // The subtree arrives FLAT, in one host read, instead of a `childrenOf` recursion. The recursion
 // stopped descending at an already-torn-down node where this skips it and carries on; the two agree
 // because both marks are whole-subtree — the sweep adds every descendant and `reattachSubtree`
-// removes every descendant — so a node in `tornDown` has its own descendants in it, and each of them
+// removes every descendant — so a marked node has its descendants marked too, and each of them
 // takes the same early return below.
 function detachOne(node, onDetached) {
-    if (tornDown.has(node))
+    if (node.isTornDown)
         return;
     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);
+    node.isTornDown = true;
+    // AND THE REST OF THE BODY IS THE BEHAVIOUR'S, so a node without one leaves here. Nine of every
+    // ten nodes in a removed subtree are plain views: the mark above is the whole of what they owe,
+    // and the three collection probes below were being paid for them anyway. All three are written
+    // only inside `attachHostBehavior`, so an absent behavior means an absent entry in each.
+    const behavior = node.hostBehavior;
+    if (behavior === undefined)
+        return;
     // 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
@@ -490,27 +508,28 @@ function detachOne(node, onDetached) {
     // 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);
+    behavior.detach(node);
 }
 // 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))
+    if (!node.isTornDown)
         return;
     reattachSubtree(node);
 }
 // Flat for the same reason the detach walk is, and with nothing to reconcile: this one always
 // descended into every child, whatever the node's own mark said.
 function reattachSubtree(root) {
-    for (const node of subtreesOf([root]))
+    // Narrowed like the teardown that marked them: `reattachOne` acts only on a node the sweep
+    // marked, and the sweep marked exactly what this walk returns.
+    for (const node of teardownSubtreesOf([root]))
         reattachOne(node);
 }
 function reattachOne(node) {
-    if (tornDown.has(node)) {
-        tornDown.delete(node);
-        const behavior = attached.get(node);
+    if (node.isTornDown) {
+        node.isTornDown = false;
+        const behavior = node.hostBehavior;
         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

package/build/mutation-buffer.d.ts

@@ -118,6 +118,22 @@ export declare const KIND_ANCHOR = 2;
  * array. Native converts each to `folly::dynamic` ONCE, when the op is applied — never again per
  * commit, which is the half that ships today.
  */
+/**
+ * What the buffer needs a handle to BE.
+ *
+ * Still an identity and nothing else as far as the ops are concerned — no parent, no children, no
+ * order. The two fields are the buffer's own scratch space for `slotOf`, written by this file and
+ * read by nobody else; `ISymbioteNode` declares them from its constructor so every real handle
+ * carries the pair on one hidden class.
+ *
+ * Spelled as a requirement rather than as optional fields on purpose: a handle that cannot hold its
+ * slot would fall back to nothing, and the failure would be a silently re-pushed node rather than a
+ * type error.
+ */
+export type IMutationHandle = {
+    slot: number;
+    slotBatch: number;
+};
 export type IMutationBatch = {
     readonly ops: Int32Array;
     readonly strings: readonly string[];
@@ -137,9 +153,9 @@ export type IMutationBatch = {
  */
 export type INativeTree = {
     applyOps: (batch: IMutationBatch) => void;
-    getProp: (handle: object, key: string) => unknown;
+    getProp: (handle: IMutationHandle, key: string) => unknown;
     /** The resolved Fabric view name, which native may have changed at insert (see `KIND_ELEMENT`). */
-    getViewName: (handle: object) => string;
+    getViewName: (handle: IMutationHandle) => string;
 };
 /** Whether a commit would publish anything. See `changedSinceCommit`. */
 export declare function hasChangedSinceCommit(): boolean;
@@ -156,17 +172,17 @@ export declare function noteCommitDrained(): void;
  */
 export declare function noteHostSideChange(): void;
 /** Does the pending batch hold anything that could change what the host says this node's parent is? */
-export declare function hasPendingPlacement(handle: object): boolean;
-export declare function recordCreateElement(handle: object, viewName: string, isText: boolean, instanceHandle: unknown): void;
-export declare function recordCreateRawText(handle: object, text: string): void;
-export declare function recordCreateAnchor(handle: object): void;
-export declare function recordCreateVoid(handle: object): void;
-export declare function recordAppendChild(parent: object, child: object): void;
-export declare function recordInsertBefore(parent: object, child: object, before: object): void;
-export declare function recordRemoveChild(parent: object, child: object): void;
+export declare function hasPendingPlacement(handle: IMutationHandle): boolean;
+export declare function recordCreateElement(handle: IMutationHandle, viewName: string, isText: boolean, instanceHandle: unknown): void;
+export declare function recordCreateRawText(handle: IMutationHandle, text: string): void;
+export declare function recordCreateAnchor(handle: IMutationHandle): void;
+export declare function recordCreateVoid(handle: IMutationHandle): void;
+export declare function recordAppendChild(parent: IMutationHandle, child: IMutationHandle): void;
+export declare function recordInsertBefore(parent: IMutationHandle, child: IMutationHandle, before: IMutationHandle): void;
+export declare function recordRemoveChild(parent: IMutationHandle, child: IMutationHandle): void;
 /** `undefined` DELETES the key — the collapse `setProp` has always performed, spelled on the wire. */
-export declare function recordSetProp(handle: object, key: string, value: unknown): void;
-export declare function recordSetText(handle: object, text: string): void;
+export declare function recordSetProp(handle: IMutationHandle, key: string, value: unknown): void;
+export declare function recordSetText(handle: IMutationHandle, text: string): void;
 /**
  * Change a node's Fabric view name after creation.
  *
@@ -179,8 +195,8 @@ export declare function recordSetText(handle: object, text: string): void;
  * A JS-only workaround was the alternative and it is the one thing this design rules out: to know
  * what to rebuild, JS would have to hold the tree.
  */
-export declare function recordSetComponent(handle: object, viewName: string): void;
-export declare function recordSetTag(handle: object, tag: string): void;
+export declare function recordSetComponent(handle: IMutationHandle, viewName: string): void;
+export declare function recordSetTag(handle: IMutationHandle, tag: string): void;
 /**
  * Whether an app callback is currently wired to an event name the BEHAVIOR owns. `[slot, name,
  * present]`, `present` being 1 or 0.
@@ -199,10 +215,10 @@ export declare function recordSetTag(handle: object, tag: string): void;
  * identity because a framework hands a fresh closure nearly every render. So this is a mount-time
  * op, not a per-render one — against the per-commit fold it replaces.
  */
-export declare function recordSetOwnedListener(handle: object, name: string, isPresent: boolean): void;
+export declare function recordSetOwnedListener(handle: IMutationHandle, name: string, isPresent: boolean): void;
 /** See `OP_SET_UNDERLAY_SHOWN`. Emitted on a flip only, from the behavior that owns the timer. */
-export declare function recordSetUnderlayShown(handle: object, shown: boolean): void;
-export declare function recordCommit(rootTag: number, surface: object): void;
+export declare function recordSetUnderlayShown(handle: IMutationHandle, shown: boolean): void;
+export declare function recordCommit(rootTag: number, surface: IMutationHandle): void;
 /** Whether anything is pending. The commit path asks before paying for a drain. */
 export declare function hasPendingOps(): boolean;
 /**

package/build/mutation-buffer.js

@@ -187,7 +187,12 @@ let handles = [];
 // Interning matters more here than it looks: a 1 000-row create emits about a dozen distinct view
 // names across 10 000 elements, and every prop KEY is drawn from a set of a few hundred.
 const stringIds = new Map();
-const slots = new Map();
+// Which batch the `slot` standing on a handle belongs to. Bumped by `takeBatch`, which is what
+// invalidates every slot at once without walking the handles that hold them.
+//
+// It starts at 1 because a fresh node's `slotBatch` is 0, so an untouched handle can never match a
+// live batch and needs no separate "is it in this batch" flag.
+let batchId = 1;
 // The same table for prop VALUES, and the reason it pays is the far side rather than this one: the
 // host turns each entry into a `folly::dynamic` when the op is applied, so a style object reused
 // across a thousand rows was a thousand conversions of one object. Measured on `build-release`,
@@ -265,6 +270,22 @@ function pushValue(value) {
  * Assigned on first mention rather than at creation, so a batch carries exactly the nodes it names.
  * A handle created by an earlier batch arrives already owning its native node, which is what lets a
  * clone source three commits old resolve with no bookkeeping on either side.
+ *
+ * THE SLOT LIVES ON THE HANDLE, not in a `Map` keyed by it, and that is a measured decision. This
+ * function runs once per handle OPERAND — every `setProp` names its node and every append names
+ * two, so a thousand-row create mentions handles about forty thousand times — and a `Map<object,
+ * number>` charges a hash for each one, plus a second for the `set` on a miss. Two fields on a shape
+ * the node already carries turn that into a compare.
+ *
+ * Measured on `build-release` by `mutation-api-fill-cost.itest.ts`, both arms in one sitting, three
+ * runs each: `createRawText` 0.70 -> 0.51 us, `appendChild` 0.65 -> 0.58, `recordSetProp` 0.34 ->
+ * 0.30, and the whole `fill` phase of a 10 001-node create 25.0 -> 23.2 ms. `createElement` barely
+ * moved (0.72 -> 0.70), which is the control: it does enough else that one lookup is noise in it.
+ *
+ * WHY AN EPOCH RATHER THAN CLEARING: a slot is meaningless outside its batch (see `IMutationBatch`),
+ * so every slot must die when the batch drains. Walking the handles to reset them would cost exactly
+ * what the `Map.clear` cost; bumping one counter invalidates all of them at once, and a handle that
+ * is never mentioned again is never touched.
  */
 function slotOf(handle) {
     // The retained tree used to ABSORB a handle that was not a node: `children.indexOf(x)` returned
@@ -283,12 +304,12 @@ function slotOf(handle) {
             `passing a framework sentinel straight through — an absent insert anchor is spelled by ` +
             `calling appendChild.`);
     }
-    const existing = slots.get(handle);
-    if (existing !== undefined)
-        return existing;
+    if (handle.slotBatch === batchId)
+        return handle.slot;
     handles.push(handle);
-    slots.set(handle, handles.length - 1);
-    return handles.length - 1;
+    handle.slot = handles.length - 1;
+    handle.slotBatch = batchId;
+    return handle.slot;
 }
 // Has anything changed the TREE since the last commit drained?
 //
@@ -479,7 +500,8 @@ export function takeBatch() {
     // held ten thousand handles on a benchmark create costs more than dropping it.
     placementPending = new Set();
     stringIds.clear();
-    slots.clear();
+    // Every slot standing on a handle dies here, without touching one of them — see `slotOf`.
+    batchId += 1;
     valueIds.clear();
     trueId = NOT_INTERNED;
     falseId = NOT_INTERNED;

package/build/native-engine.d.ts

@@ -64,11 +64,14 @@ export type INativeEngineBindings = {
     getViewName: (handle: object) => string;
     parentOf: (handle: object) => object | undefined;
     childrenOf: (handle: object) => readonly object[];
-    /** One entry, not the whole list — see `ITreeHost` for the quadratic it replaces. */
+    /** One entry, not the whole list — see `ITreeHost` for the quadratic each of these replaces. */
+    firstChildOf: (handle: object) => object | undefined;
     nextSiblingOf: (handle: object) => object | undefined;
     /** The batched twins of `parentOf` / `childrenOf`. See `ITreeHost` for why the sweep needs them. */
     parentsOf: (handles: readonly object[]) => readonly (object | undefined)[];
     subtreesOf: (roots: readonly object[]) => readonly object[];
+    /** The same walk narrowed to what a teardown visits. See `ITreeHost.teardownSubtreesOf`. */
+    teardownSubtreesOf: (roots: readonly object[]) => readonly object[];
     /** The upward twin, deepest first — one crossing for a chain the event path walks per event. */
     ancestorsOf: (handle: object) => readonly object[];
     committedRecordOf: (handle: object) => ICommittedRecord | undefined;

package/build/native-engine.js

@@ -84,12 +84,16 @@ function isBindings(value) {
         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')

package/build/native-tree-host.js

@@ -31,9 +31,11 @@ export function nativeTreeHost(bindings) {
         committedPayloadOf: bindings.committedPayloadOf,
         parentOf: bindings.parentOf,
         childrenOf: bindings.childrenOf,
+        firstChildOf: bindings.firstChildOf,
         nextSiblingOf: bindings.nextSiblingOf,
         parentsOf: bindings.parentsOf,
         subtreesOf: bindings.subtreesOf,
+        teardownSubtreesOf: bindings.teardownSubtreesOf,
         ancestorsOf: bindings.ancestorsOf,
         census: () => EMPTY_CENSUS,
         // Straight through: native already takes the placeholder, which is what `committedRecordOf`

package/build/node.d.ts

@@ -1,6 +1,6 @@
 import type { IMeasureOnSuccess, IMeasureInWindowOnSuccess, IMeasureLayoutOnSuccess } from './fabric';
 import { type IClassNameValue } from './style-registry';
-import { type IPayloadFold } from './host-behavior';
+import { type IHostBehavior, type IPayloadFold } from './host-behavior';
 import { type ITreeCensus } from './tree-host';
 declare const BRAND: unique symbol;
 export declare const RAW_TEXT_COMPONENT = "RCTRawText";
@@ -46,10 +46,32 @@ export interface ISymbioteNode {
     resolvesImageSources: boolean;
     nativeIdWinsOverId: boolean;
     payloadFold: IPayloadFold | undefined;
+    /**
+     * The behavior that attached to this node, or `undefined` for the vast majority that have none.
+     *
+     * A field for the same reason `payloadFold` above it is one, and set on the same line: every
+     * reader is a per-node path at list scale — the teardown sweep touches every node of a removed
+     * subtree, and `routeProp`'s slot/owned-listener questions run per prop write. A `WeakMap` probe
+     * is the dearest way to ask a question whose answer is almost always "none".
+     *
+     * Owned by `host-behavior.ts`; `attachHostBehavior` is the only writer.
+     */
+    hostBehavior: IHostBehavior | undefined;
     styleParts: IClassStyleParts | undefined;
     childHost: ISymbioteNode | undefined;
     wrapper: ISymbioteNode | undefined;
     mayHaveChildren: boolean;
+    /**
+     * Whether the teardown sweep has released this node and not seen it come back.
+     *
+     * Owned by `host-behavior.ts` — see `detachOne` / `reattachHostBehaviors`. A field rather than
+     * the `WeakSet` it was, because the sweep reads and writes it for EVERY node of a removed
+     * subtree (ten thousand on a thousand-row clear) and every insert reads it to decide whether to
+     * walk at all, which is the ~9 000-call path of a create.
+     */
+    isTornDown: boolean;
+    slot: number;
+    slotBatch: number;
     measure(callback: IMeasureOnSuccess): void;
     measureInWindow(callback: IMeasureInWindowOnSuccess): void;
     measureLayout(relativeToNativeNode: ISymbioteNode | number, onSuccess: IMeasureLayoutOnSuccess, onFail?: () => void): void;

package/build/node.js

@@ -84,6 +84,9 @@ class SymbioteNode {
         // Assigned here for the same hidden-class reason as `hasAriaAlias` above; `attachHostBehavior`
         // overwrites it a few lines later for the rare node that has a behavior.
         this.payloadFold = undefined;
+        // Same reason again, and the same writer: `attachHostBehavior` fills it for the rare node that
+        // gets a behavior at all.
+        this.hostBehavior = undefined;
         // Same reason again, and here it is load-bearing rather than tidy: the redirect below is read
         // on every append, so the slot must be a stable slot on one hidden class, not a property added
         // to a few nodes after the fact.
@@ -93,6 +96,16 @@ class SymbioteNode {
         // guards is read on every `childrenOf`, so it must be a stable slot rather than a property that
         // appears on some nodes later.
         this.mayHaveChildren = false;
+        // Same hidden-class reason again, and the same measured one: every insert reads it and the
+        // teardown sweep writes it per node.
+        this.isTornDown = false;
+        // Same hidden-class reason as every field above, and the most load-bearing of them: `slotOf`
+        // reads this pair on EVERY handle operand of every op — about two hundred thousand times on a
+        // thousand-row create — so it has to be a stable slot on one shape. `slotBatch` starts at a
+        // value no batch ever carries, which is what makes an untouched node read as "not in this
+        // batch" without a separate flag.
+        this.slot = 0;
+        this.slotBatch = 0;
     }
     measure(callback) {
         engineMeasure(this, callback);

package/build/tree-host.d.ts

@@ -1,5 +1,5 @@
 import type { IMeasureInWindowOnSuccess, IMeasureLayoutOnSuccess, IMeasureOnSuccess, IRootTag } from './fabric';
-import { type IMutationBatch } from './mutation-buffer';
+import { type IMutationBatch, type IMutationHandle } from './mutation-buffer';
 /** What Fabric currently holds for one node — the three fields every imperative call is aimed at. */
 export type ICommittedRecord = {
     /**
@@ -67,10 +67,25 @@ export type ITreeHost = {
     committedPayloadOf: (handle: object) => Readonly<Record<string, unknown>> | undefined;
     parentOf: (handle: object) => object | undefined;
     childrenOf: (handle: object) => readonly object[];
+    firstChildOf: (handle: object) => object | undefined;
     nextSiblingOf: (handle: object) => object | undefined;
     parentsOf: (handles: readonly object[]) => readonly (object | undefined)[];
     /** Each root and every descendant, PRE-ORDER, concatenated in root order. */
     subtreesOf: (roots: readonly object[]) => readonly object[];
+    /**
+     * The same walk, narrowed to the nodes a TEARDOWN has work for — each root, every node carrying
+     * an intrinsic tag, and every node between the two.
+     *
+     * It exists because the sweep's whole cost is how WIDE this walk is: a thousand-row clear crossed
+     * ten thousand handles to release a thousand machines, and eight in ten of those nodes were plain
+     * views the sweep marked and did nothing else with. An ancestor of a tagged node has to come back
+     * too, or a framework that returns an interior node on its own would never re-arm what hangs
+     * beneath it (`host-behavior.test.ts` guards exactly that shape).
+     *
+     * Not a replacement for `subtreesOf`: an animated binding is per node and carries no tag, so
+     * `host-access.ts` asks for the full walk whenever one exists.
+     */
+    teardownSubtreesOf: (roots: readonly object[]) => readonly object[];
     /**
      * The node itself and every ancestor above it, DEEPEST FIRST.
      *
@@ -129,7 +144,7 @@ export declare function flushOps(): void;
  * A single-surface app — every example, and the overwhelming case — passes an empty list and the
  * behaviour is byte-identical to naming only itself.
  */
-export declare function commitSurfaceOps(rootTag: IRootTag | undefined, surface: object, others?: readonly (readonly [IRootTag, object])[]): void;
+export declare function commitSurfaceOps(rootTag: IRootTag | undefined, surface: IMutationHandle, others?: readonly (readonly [IRootTag, IMutationHandle])[]): void;
 export interface ICommitProfile {
     commits: number;
     propWrites: number;

package/cpp/SymbioteEngineBindings.cpp

@@ -206,9 +206,11 @@ void installBindings(jsi::Runtime &runtime) {
   install("getViewName", 1, &Tree::getViewName);
   install("parentOf", 1, &Tree::parentOf);
   install("childrenOf", 1, &Tree::childrenOf);
+  install("firstChildOf", 1, &Tree::firstChildOf);
   install("nextSiblingOf", 1, &Tree::nextSiblingOf);
   install("parentsOf", 1, &Tree::parentsOf);
   install("subtreesOf", 1, &Tree::subtreesOf);
+  install("teardownSubtreesOf", 1, &Tree::teardownSubtreesOf);
   install("ancestorsOf", 1, &Tree::ancestorsOf);
   install("committedRecordOf", 1, &Tree::committedRecordOf);
   // A TEST read, and it is on this list rather than behind a build flag because the bag it returns

package/cpp/SymbioteTree.cpp

@@ -395,6 +395,18 @@ void holdHandle(jsi::Runtime &runtime, Node &node) {
   if (live.isObject()) node.attachedHandle.emplace(live.getObject(runtime));
 }
 
+/**
+ * The UIManager for this runtime.
+ *
+ * NOT cached, and the failed attempt is worth recording: keying a cache on `&runtime` treats an
+ * ADDRESS as a lifetime, and an allocator reuses addresses. `symbiote_tree_tests` builds and tears
+ * down a JSCRuntime per case, so the second one can land where the first was and inherit a dangling
+ * binding — a crash, not a wrong number. The same mistake with three interned `PropNameID`s aborted
+ * that suite outright (`~JSCRuntime`: "destroyed with a dangling API string").
+ *
+ * It bought nothing anyway: both caches together moved an empty drain 4.46 -> 4.38 us, against the
+ * 4.38 -> 1.54 that dropping the checked JSI casts gave.
+ */
 react::UIManager &uiManagerFor(jsi::Runtime &runtime, const char *what) {
   auto binding = react::UIManagerBinding::getBinding(runtime);
   if (binding == nullptr) {
@@ -411,10 +423,14 @@ react::UIManager &uiManagerFor(jsi::Runtime &runtime, const char *what) {
  * `ArrayBuffer::data` hands back the backing store, so the commands never become JS values — which
  * is the entire reason the format is flat. `byteOffset` is read rather than assumed: a typed array
  * need not start at the head of its buffer.
+ *
+ * The three names are built from UTF-8 on every call and that stands: interning them in a
+ * file-scope cache is what aborted `symbiote_tree_tests`, because a `PropNameID` outliving its
+ * runtime is a dangling API string. See `uiManagerFor` above for the general form and the price.
  */
 const int32_t *int32ArrayData(jsi::Runtime &runtime, const jsi::Value &value, size_t &lengthOut) {
   auto typedArray = value.asObject(runtime);
-  auto buffer = typedArray.getPropertyAsObject(runtime, "buffer").getArrayBuffer(runtime);
+  auto buffer = typedArray.getProperty(runtime, "buffer").asObject(runtime).getArrayBuffer(runtime);
   auto byteOffset = static_cast<size_t>(typedArray.getProperty(runtime, "byteOffset").asNumber());
   lengthOut = static_cast<size_t>(typedArray.getProperty(runtime, "length").asNumber());
   return reinterpret_cast<const int32_t *>(buffer.data(runtime) + byteOffset);
@@ -1490,10 +1506,27 @@ jsi::Value Tree::applyOps(jsi::Runtime &runtime, const jsi::Value *arguments, si
 
   size_t opsLength = 0;
   const int32_t *ops = int32ArrayData(runtime, arguments[0], opsLength);
-  auto strings = arguments[1].asObject(runtime).asArray(runtime);
-  auto values = arguments[2].asObject(runtime).asArray(runtime);
-  auto instanceHandles = arguments[3].asObject(runtime).asArray(runtime);
-  auto handles = arguments[4].asObject(runtime).asArray(runtime);
+  // ── THE PROLOGUE WAS THE COST, AND THIS LINE WAS THE PROLOGUE ──────────────────────────────────
+  //
+  // `getObject`/`getArray` rather than `asObject`/`asArray`. The checking pair runs an `isObject`
+  // and an `isArray` per table — eight JSI round trips for four arguments — and they were 2.8 us of
+  // a 4.4 us fixed entry cost. Measured on an EMPTY batch against a 0.13 us bare host call
+  // (`small-batch-crossing-cost.itest.ts`): prologue 4.38 -> 1.54 us, and a whole small drain
+  // 5.54 -> 2.76 us.
+  //
+  // WHY IT IS SAFE TO DROP THEM, and it is the harness's own split rather than a shrug: `takeBatch`
+  // is the only producer on this wire and always hands over four arrays, and `jsi::Value::getObject`
+  // / `Object::getArray` carry `assert`s that are LIVE in the correctness build — `core/engine/cpp/
+  // tests/build` is Debug with `NDEBUG` off, which is the whole reason it exists. So a fixture that
+  // hand-builds a malformed batch aborts there and the build that ships pays nothing for the check.
+  //
+  // WHAT IT COSTS ANYONE: a framework that navigates between mutations pays this entry per
+  // mutation, not per commit. Solid's `cleanChildren` enters `applyOps` 2 000 times to clear a
+  // thousand rows.
+  auto strings = arguments[1].getObject(runtime).getArray(runtime);
+  auto values = arguments[2].getObject(runtime).getArray(runtime);
+  auto instanceHandles = arguments[3].getObject(runtime).getArray(runtime);
+  auto handles = arguments[4].getObject(runtime).getArray(runtime);
   const size_t slotCount = handles.size(runtime);
 
   // Slot -> node, resolved at most ONCE per batch and usually not at all: a slot this batch creates
@@ -2028,6 +2061,34 @@ jsi::Value Tree::nextSiblingOf(jsi::Runtime &runtime, const jsi::Value *argument
   return handleOf(runtime, **std::next(at));
 }
 
+/**
+ * The first live child, anchors included.
+ *
+ * WHY IT IS ITS OWN CALL, and it is `nextSiblingOf`'s argument one door along. The JS spelling was
+ * `childrenOf(node)[0]`, and `solid-js/universal`'s `cleanChildren` empties a parent with
+ * `while (removed = getFirstChild(parent)) removeNode(parent, removed)` — so a list of N children
+ * was read N times, each read building and discarding the whole remaining list. Measured on a
+ * 2 000-row `Clear` before this existed: **2 001 001 handles** crossed the boundary to remove two
+ * thousand children, which is N(N+1)/2 to the unit, and the step cost 435 ms against stock's 14.
+ *
+ * SKIPS A DEAD HANDLE rather than answering `undefined` on one, exactly as `childrenOf` does. The
+ * two must agree element for element or a caller that switches between them sees a different tree —
+ * and `cleanChildren`'s loop terminates on `undefined`, so answering it early would orphan every
+ * child behind the dead one.
+ */
+jsi::Value Tree::firstChildOf(jsi::Runtime &runtime, const jsi::Value *arguments, size_t count) {
+  if (count < 1) {
+    throw jsi::JSError(runtime, "symbiote engine: expected firstChildOf(handle)");
+  }
+  const auto node = nodeFrom(runtime, arguments[0].asObject(runtime), "firstChildOf");
+  compactChildren(*node);
+  for (const auto &child : node->children) {
+    auto handle = handleOf(runtime, *child);
+    if (!handle.isUndefined()) return handle;
+  }
+  return jsi::Value::undefined();
+}
+
 jsi::Value Tree::childrenOf(jsi::Runtime &runtime, const jsi::Value *arguments, size_t count) {
   if (count < 1) {
     throw jsi::JSError(runtime, "symbiote engine: expected childrenOf(handle)");
@@ -2070,6 +2131,42 @@ void collectSubtree(jsi::Runtime &runtime, const NodePtr &node, std::vector<jsi:
   for (const auto &child : node->children) collectSubtree(runtime, child, into);
 }
 
+// The same walk, narrowed to the nodes a TEARDOWN has anything to do with — and it is the whole of
+// what the sweep costs, because it is the walk that decides how many handles cross.
+//
+// A node earns its place three ways, and the third is the one that keeps the narrowing honest:
+//
+//   it is a ROOT           the sweep was handed it, and marking it is what makes a re-insert walk
+//   it carries a TAG       `kOpSetTag` arrives from `attachHostBehavior` and from nowhere else, so
+//                          a non-empty `tagName` is exactly "a behavior attached to this node"
+//   something under it     an ANCESTOR of a tagged node, because the framework may bring back an
+//                          interior node on its own and its insert has to walk
+//
+// What drops out is a node with no behavior and none beneath it, which on the benchmark row is
+// eight of every ten: the sweep would mark it, call `onDetached` on it, and change nothing.
+//
+// Returns whether this node earned its place, which is how its parent learns it has to keep its
+// own. Pre-order is preserved by reserving the slot BEFORE recursing and dropping it afterwards —
+// a node that turns out uninteresting resizes away, and by then every uninteresting descendant has
+// already resized itself away, so nothing interesting is ever discarded with it.
+bool collectTeardownSubtree(
+    jsi::Runtime &runtime,
+    const NodePtr &node,
+    std::vector<jsi::Value> &into,
+    bool isRoot) {
+  auto handle = handleOf(runtime, *node);
+  if (handle.isUndefined()) return false;
+  const size_t reserved = into.size();
+  into.push_back(std::move(handle));
+  bool isWanted = isRoot || !node->tagName.empty();
+  compactChildren(*node);
+  for (const auto &child : node->children) {
+    if (collectTeardownSubtree(runtime, child, into, false)) isWanted = true;
+  }
+  if (!isWanted) into.resize(reserved);
+  return isWanted;
+}
+
 jsi::Value Tree::ancestorsOf(jsi::Runtime &runtime, const jsi::Value *arguments, size_t count) {
   if (count < 1) {
     throw jsi::JSError(runtime, "symbiote engine: expected ancestorsOf(handle)");
@@ -2118,9 +2215,15 @@ jsi::Value Tree::parentsOf(jsi::Runtime &runtime, const jsi::Value *arguments, s
   return out;
 }
 
-jsi::Value Tree::subtreesOf(jsi::Runtime &runtime, const jsi::Value *arguments, size_t count) {
+// Shared by `subtreesOf` and `teardownSubtreesOf`, which differ only in which nodes the walk keeps.
+jsi::Value Tree::collectRoots(
+    jsi::Runtime &runtime,
+    const jsi::Value *arguments,
+    size_t count,
+    const char *what,
+    bool narrowToTeardown) {
   if (count < 1) {
-    throw jsi::JSError(runtime, "symbiote engine: expected subtreesOf(roots)");
+    throw jsi::JSError(runtime, std::string("symbiote engine: expected ") + what + "(roots)");
   }
   const auto readStartedAt = ISteadyClock::now();
   auto roots = arguments[0].asObject(runtime).asArray(runtime);
@@ -2134,8 +2237,9 @@ jsi::Value Tree::subtreesOf(jsi::Runtime &runtime, const jsi::Value *arguments,
   std::vector<jsi::Value> flat;
   for (size_t at = 0; at < length; at += 1) {
     const auto root =
-        nodeFrom(runtime, roots.getValueAtIndex(runtime, at).asObject(runtime), "subtreesOf");
-    collectSubtree(runtime, root, flat);
+        nodeFrom(runtime, roots.getValueAtIndex(runtime, at).asObject(runtime), what);
+    if (narrowToTeardown) collectTeardownSubtree(runtime, root, flat, true);
+    else collectSubtree(runtime, root, flat);
   }
 
   auto out = jsi::Array(runtime, flat.size());
@@ -2147,6 +2251,17 @@ jsi::Value Tree::subtreesOf(jsi::Runtime &runtime, const jsi::Value *arguments,
   return out;
 }
 
+jsi::Value Tree::subtreesOf(jsi::Runtime &runtime, const jsi::Value *arguments, size_t count) {
+  return collectRoots(runtime, arguments, count, "subtreesOf", false);
+}
+
+jsi::Value Tree::teardownSubtreesOf(
+    jsi::Runtime &runtime,
+    const jsi::Value *arguments,
+    size_t count) {
+  return collectRoots(runtime, arguments, count, "teardownSubtreesOf", true);
+}
+
 jsi::Value Tree::committedRecordOf(
     jsi::Runtime &runtime,
     const jsi::Value *arguments,

package/cpp/SymbioteTree.h

@@ -126,6 +126,18 @@ class Tree {
       facebook::jsi::Runtime &runtime,
       const facebook::jsi::Value *arguments,
       size_t count);
+  /**
+   * `firstChildOf(handle)` — the first entry of the child list, anchors included.
+   *
+   * Its own call for the same reason `nextSiblingOf` is, and it is the same bug one door along: the
+   * JS spelling was `childrenOf(node)[0]`, so emptying a list one child at a time read the whole
+   * remaining list on every step. Measured on a 2 000-row Solid `Clear`: 2 001 001 handles crossed
+   * to remove two thousand children, N(N+1)/2 exactly, against the ~2 000 the work needs.
+   */
+  facebook::jsi::Value firstChildOf(
+      facebook::jsi::Runtime &runtime,
+      const facebook::jsi::Value *arguments,
+      size_t count);
   /** `childrenOf(handle)` — in order, ANCHORS INCLUDED. */
   facebook::jsi::Value childrenOf(
       facebook::jsi::Runtime &runtime,
@@ -151,6 +163,22 @@ class Tree {
       facebook::jsi::Runtime &runtime,
       const facebook::jsi::Value *arguments,
       size_t count);
+  /**
+   * `teardownSubtreesOf(roots)` — `subtreesOf` narrowed to the nodes a teardown has work for.
+   *
+   * The sweep's cost IS this walk's width: it crosses a handle per node to release the few that
+   * carry a machine, and on the benchmark row that is one node in ten. What comes back is each
+   * root, every node carrying an intrinsic TAG (which `kOpSetTag` sets from `attachHostBehavior`
+   * and nowhere else), and every node BETWEEN the two — an ancestor has to be marked or the
+   * framework bringing it back alone would never re-arm what hangs beneath it.
+   *
+   * NOT a substitute when an app animates: `detachAnimatedProps` is per node and knows nothing
+   * about tags, so `host-access.ts` asks for the full walk whenever a binding exists.
+   */
+  facebook::jsi::Value teardownSubtreesOf(
+      facebook::jsi::Runtime &runtime,
+      const facebook::jsi::Value *arguments,
+      size_t count);
   /**
    * `ancestorsOf(handle)` — the node and every ancestor above it, DEEPEST FIRST, in one crossing.
    *
@@ -252,6 +280,15 @@ class Tree {
       facebook::jsi::Runtime &runtime,
       const facebook::jsi::Value *arguments,
       size_t count);
+
+ private:
+  /** The body `subtreesOf` and `teardownSubtreesOf` share; `narrowToTeardown` picks the walk. */
+  facebook::jsi::Value collectRoots(
+      facebook::jsi::Runtime &runtime,
+      const facebook::jsi::Value *arguments,
+      size_t count,
+      const char *what,
+      bool narrowToTeardown);
 };
 
 } // namespace symbiote

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@symbiote-native/engine",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "SymbioteNative's retained shadow-tree engine — clone-on-write commit path + event normalization over React Native Fabric, shared by every framework adapter.",
   "license": "MIT",
   "repository": {
@@ -71,7 +71,7 @@
   },
   "peerDependenciesMeta": {},
   "devDependencies": {
-    "@symbiote-native/test-utils": "0.3.1"
+    "@symbiote-native/test-utils": "0.4.0"
   },
   "scripts": {
     "typecheck": "tsc --build",