@symbiote-native/engine 0.3.0 → 0.4.0

package/build/commit.js

@@ -2,8 +2,8 @@
 // node, you clone it with new props/children and atomically hand a fresh child
 // set to completeRoot.
 //
-// Incremental strategy: each retained node keeps a "mirror" of what Fabric
-// currently holds for it: its handle, the flat props last sent, the child
+// Incremental strategy: each retained node keeps, in its own `committed` field (node.ts), a
+// mirror of what Fabric currently holds for it: its handle, the flat props last sent, the child
 // identities last committed, and the resolved view name. On commit we walk the
 // retained tree and only clone the nodes that actually changed; an untouched
 // sibling subtree is reused by reference. That both skips work and preserves the
@@ -13,18 +13,24 @@
 // references to specific child handles. That bubble is inherent to a persistent
 // tree and is exactly what React's own Fabric renderer does.
 import { getSlot, } from './fabric.js';
-import { createElement, debugNodeId, isAnchor, isEmptyRawText, markDirty, takePropStats, VIRTUAL_TEXT_COMPONENT, } from './node.js';
+import { createElement, debugNodeId, isAnchor, isEmptyRawText, committedOf, markDirty, markPropsDirty, markStructureDirty, takePropStats, VIRTUAL_TEXT_COMPONENT, } from './node.js';
 import { dlog, isDebug } from './debug.js';
 import { flattenStyle } from './style/index.js';
 import { nextTag } from './tags.js';
 import { registerPostCommit, runPostCommitHooks } from './post-commit.js';
 import { fabricProps } from './fabric-props.js';
 import { isRecord } from './type-guards.js';
+import { isAriaAliasKey } from './accessibility-props.js';
+import { runDeferredAttaches, sweepDetachedBehaviors } from './host-behavior.js';
 // Re-exported from ./platform-color so callers don't need to change their import path.
 export { processColor, setColorProcessor } from './platform-color/index.js';
 // Per-commit work counters, surfaced via dlog so a device run can prove the
 // engine is incremental (created=0 with clones after the first mount).
 const stats = { created: 0, cloneProps: 0, cloneChildren: 0, reused: 0 };
+// One append vs one clone is a wash by call count and a pure loss by allocation, so a parent with a
+// single child never takes the batched route whatever the switch says.
+const CREATE_BATCH_MIN_CHILDREN = 2;
+let batchCreate = false;
 // Cumulative cost of the reconcile walk. Unlike `stats` (per-commit, zeroed at the top of every
 // commit), this ACCUMULATES: one scroll frame produces a burst of commits and the frame's real cost
 // is only visible as their sum. Read-and-zeroed via readCommitProfile().
@@ -32,7 +38,23 @@ const stats = { created: 0, cloneProps: 0, cloneChildren: 0, reused: 0 };
 // Deliberately NOT gated behind isDebug(): two performance.now() calls per commit are noise next to
 // the walk they measure, and the number is only meaningful from a RELEASE build - dev-mode JS
 // drowns the signal. The dlog below stays gated as usual.
-const profile = { commits: 0, walkMs: 0, nodesVisited: 0 };
+// `propsBuilt` / `propsReused` price the props half of the walk, and they exist because that half
+// is INVISIBLE in the output: reusing the mirror's payload by reference and rebuilding a
+// byte-identical one emit the same Fabric calls, so only a counter separates a working fast lane
+// from a silently reverted one. `propsBuilt` counts fabricProps() calls made by the update path
+// (a fresh object plus a recursive propsEqual); `propsReused` counts nodes that re-cloned for a
+// child's sake and carried the committed payload through untouched. On an ordinary update the
+// second should dominate - that ratio IS the clone-bubble.
+//
+// The create path is deliberately not counted in either: it has no committed payload to reuse, so
+// its fabricProps() calls are not a cost any flag could remove and would only dilute the ratio.
+const profile = {
+    commits: 0,
+    walkMs: 0,
+    nodesVisited: 0,
+    propsBuilt: 0,
+    propsReused: 0,
+};
 // What `renderableChildren` costs, accumulated over the same window as `profile`. Anchors are the
 // only reason that function is not free, and how many a tree carries is a property of the ADAPTER,
 // not of the app: a Vue/React/Svelte/Solid component is a function returning children and allocates
@@ -164,7 +186,6 @@ function jsonEqual(a, b) {
         return false;
     return keys.every(key => key in b && jsonEqual(a[key], b[key]));
 }
-const mirror = new WeakMap();
 function isSkippedAtCommit(node) {
     return isAnchor(node) || isEmptyRawText(node);
 }
@@ -221,10 +242,14 @@ function childrenIdentical(kids, committed) {
 // committed tag/view-name is resolved. A `MULTI!!` line names the exact extra
 // node (tag + view-name) that pushed the scroll view past one child.
 function logScrollChildren(node, viewName, selfTag) {
+    // The whole function is a dlog, and it is called on every reconciled node, so the cheap boolean
+    // goes first: with logging off this is one property read instead of two string scans per node.
+    if (!isDebug())
+        return;
     if (!viewName.includes('Scroll') || viewName.includes('Content'))
         return;
     const kids = node.children.map(child => {
-        const committed = mirror.get(child);
+        const committed = committedOf(child);
         return `${committed?.viewName ?? child.component}#${committed?.tag ?? 'NEW'}`;
     });
     const flag = kids.length === 1 ? 'OK' : 'MULTI!!';
@@ -235,19 +260,25 @@ function logScrollChildren(node, viewName, selfTag) {
 // showing the old value - no error, no crash, nothing to grep for. So under DEBUG pay back the full
 // price just saved and verify the skip was honest, naming the node loudly enough to find the
 // missing mark.
-function warnIfStale(node, committed) {
+//
+// Two lanes reach it, and naming which one fired matters when reading a log: `subtree` is the whole
+// node skipped because nothing under it was marked, `props` is the node re-cloned for a child's
+// sake but its own payload reused because no prop write was recorded on it. They point at
+// different missing marks - markDirty vs markPropsDirty - so the line says which.
+function warnIfStale(node, committed, lane) {
     if (!isDebug())
         return;
     const fresh = fabricProps(node);
     if (propsEqual(committed.props, fresh))
         return;
-    dlog(`DIRTY-MISS ${committed.viewName}#${committed.tag} node=${debugNodeId(node)} skipped as clean ` +
-        `but props differ: committed=${JSON.stringify(committed.props)} desired=${JSON.stringify(fresh)}`);
+    dlog(`DIRTY-MISS(${lane}) ${committed.viewName}#${committed.tag} node=${debugNodeId(node)} ` +
+        `treated as clean but props differ: committed=${JSON.stringify(committed.props)} ` +
+        `desired=${JSON.stringify(fresh)}`);
 }
 function reconcile(slot, node, rootTag, hasTextAncestor, renderableParent, forceFreshFamily) {
     profile.nodesVisited += 1;
     const viewName = viewNameFor(node, hasTextAncestor);
-    const committed = mirror.get(node);
+    const committed = committedOf(node);
     // Nothing under here changed: hand back the committed handle without rebuilding this node's
     // Fabric props or descending into it at all. The walk below costs ~13 us/node on device, and an
     // untouched sibling subtree would pay it on every commit. `committed.parent` is re-checked rather
@@ -259,11 +290,18 @@ function reconcile(slot, node, rootTag, hasTextAncestor, renderableParent, force
         committed.parent === renderableParent &&
         committed.viewName === viewName) {
         stats.reused += 1;
-        warnIfStale(node, committed);
+        warnIfStale(node, committed, 'subtree');
         return { handle: committed.handle, changed: false };
     }
     node.dirty = false;
-    const props = fabricProps(node);
+    // Read before clearing. The create path below ignores it - a node Fabric has never seen needs its
+    // whole payload built regardless - so this only ever gates the update path.
+    const ownPropsChanged = node.propsDirty;
+    node.propsDirty = false;
+    // Cleared here because this call is what re-snapshots `committed.children` below, on both the
+    // create and the update path. Anything that reads that snapshot afterwards is reading a current
+    // one until the next structural op raises the flag again.
+    node.structureDirty = false;
     const childInText = node.isText || hasTextAncestor;
     const kids = renderableChildren(node);
     // First mount, or the view kind flipped (RCTText <-> RCTVirtualText when a
@@ -275,30 +313,56 @@ function reconcile(slot, node, rootTag, hasTextAncestor, renderableParent, force
         committed.viewName !== viewName ||
         parentChanged) {
         stats.created += 1;
+        // Full payload: there is no committed props object to reuse, whatever propsDirty said.
+        const props = fabricProps(node);
         const tag = nextTag();
-        const reason = committed === undefined
-            ? 'mount'
-            : forceFreshFamily
-                ? 'fresh-parent'
-                : committed.viewName !== viewName
-                    ? 'view-kind'
-                    : 'reparent';
-        dlog(`commit root=${rootTag} createNode tag=${tag} view=${viewName} reason=${reason}`);
-        if (viewName === 'RCTView' || viewName === 'RCTText') {
-            dlog(`commit root=${rootTag} colorProbe tag=${tag} view=${viewName} ` +
-                `bg=${JSON.stringify(props.backgroundColor)} color=${JSON.stringify(props.color)} ` +
-                `opacity=${JSON.stringify(props.opacity)}`);
+        // One gate for the whole diagnostic block, not three dlog calls. This runs once per CREATED
+        // node - 9 000 of them on one benchmark press - and dlog cannot help here: its argument is
+        // built at the CALL SITE (see debug.ts), so an eager template pays in full with logging off,
+        // and a thunk trades that for a closure allocation per node. A plain `if` costs neither.
+        if (isDebug()) {
+            const reason = committed === undefined
+                ? 'mount'
+                : forceFreshFamily
+                    ? 'fresh-parent'
+                    : committed.viewName !== viewName
+                        ? 'view-kind'
+                        : 'reparent';
+            dlog(`commit root=${rootTag} createNode tag=${tag} view=${viewName} reason=${reason}`);
+            if (viewName === 'RCTView' || viewName === 'RCTText') {
+                dlog(`commit root=${rootTag} colorProbe tag=${tag} view=${viewName} ` +
+                    `bg=${JSON.stringify(props.backgroundColor)} color=${JSON.stringify(props.color)} ` +
+                    `opacity=${JSON.stringify(props.opacity)}`);
+            }
+            if (viewName === 'AndroidSwipeRefreshLayout' ||
+                viewName === 'RCTScrollView') {
+                dlog(`commit root=${rootTag} layoutProbe tag=${tag} view=${viewName} ` +
+                    `flex=${JSON.stringify(props.flex)} height=${JSON.stringify(props.height)} ` +
+                    `width=${JSON.stringify(props.width)} minHeight=${JSON.stringify(props.minHeight)} ` +
+                    `flexGrow=${JSON.stringify(props.flexGrow)}`);
+            }
         }
-        if (viewName === 'AndroidSwipeRefreshLayout' ||
-            viewName === 'RCTScrollView') {
-            dlog(`commit root=${rootTag} layoutProbe tag=${tag} view=${viewName} ` +
-                `flex=${JSON.stringify(props.flex)} height=${JSON.stringify(props.height)} ` +
-                `width=${JSON.stringify(props.width)} minHeight=${JSON.stringify(props.minHeight)} ` +
-                `flexGrow=${JSON.stringify(props.flexGrow)}`);
+        const created = slot.createNode(tag, viewName, rootTag, props, node);
+        // `createNode` takes no children (UIManagerBinding.cpp gives it 5 params), so a fresh parent
+        // can only receive them one `appendChild` at a time — unless we spend a clone to hand the whole
+        // list over at once. That is a TRADE, not a win: it removes N-1 JSI crossings and adds one
+        // discarded ShadowNode per parent, and which side wins is a native-side question no headless
+        // bench can answer. Hence the switch: off, this is byte-for-byte the append loop.
+        //
+        // Below the threshold the trade is a wash by call count (1 append vs 1 clone) and pure loss by
+        // allocation, so a single-child parent never takes it.
+        let handle = created;
+        if (batchCreate && kids.length >= CREATE_BATCH_MIN_CHILDREN) {
+            const childHandles = [];
+            for (const child of kids) {
+                childHandles.push(reconcile(slot, child, rootTag, childInText, node, true).handle);
+            }
+            handle = slot.cloneNodeWithNewChildren(created, childHandles);
         }
-        const handle = slot.createNode(tag, viewName, rootTag, props, node);
-        for (const child of kids) {
-            slot.appendChild(handle, reconcile(slot, child, rootTag, childInText, node, true).handle);
+        else {
+            for (const child of kids) {
+                slot.appendChild(created, reconcile(slot, child, rootTag, childInText, node, true).handle);
+            }
         }
         logScrollChildren(node, viewName, tag);
         // Investigation instrumentation (search-bar-ref "node not committed" bug): scoped to RNS* so
@@ -306,17 +370,23 @@ function reconcile(slot, node, rootTag, hasTextAncestor, renderableParent, force
         // log below — same debugNodeId on both sides proves/disproves an identity mismatch. Kept
         // behind DEBUG per <keep_logs_gate_behind_DEBUG>, never removed.
         if (viewName.startsWith('RNS')) {
-            dlog(`mirror.set (create) node=${debugNodeId(node)} tag=${tag} view=${viewName}`);
+            dlog(`committed (create) node=${debugNodeId(node)} tag=${tag} view=${viewName}`);
         }
-        mirror.set(node, {
+        // `kids` is stored BY REFERENCE, not copied. With no anchors it IS `node.children`, so the
+        // record aliases the live array until the next structural op, which copies it out of the way
+        // (markStructureDirty, node.ts). Slicing here instead cost one array per node per commit -
+        // 9 002 on a 1 000-row create - and all but the handful of nodes that go on to change threw
+        // theirs away unread.
+        node.committed = {
             handle,
             tag,
             rootTag,
             props,
-            children: kids.slice(),
+            children: kids,
             viewName,
             parent: renderableParent,
-        });
+            owner: node,
+        };
         return { handle, changed: true };
     }
     // Reconcile children first; a child that re-cloned forces this node to re-clone
@@ -331,7 +401,32 @@ function reconcile(slot, node, rootTag, hasTextAncestor, renderableParent, force
     }
     logScrollChildren(node, viewName, committed.tag);
     const childrenChanged = !childrenIdentical(kids, committed.children) || descendantChanged;
-    const propsChanged = !propsEqual(committed.props, props);
+    // The fast lane. No prop write was recorded on this node since its last commit, so its Fabric
+    // payload is by construction the one the mirror already holds: reuse that object by reference -
+    // no rebuild, no allocation, no deep compare - and carry it into the mirror below untouched.
+    //
+    // This is what propsDirty (node.ts) exists for. Every node on the clone-bubble path from a
+    // changed leaf up to the root takes this branch, as does the synthetic container that
+    // commitContainer dirties at every single entry. They still re-clone - a persistent parent must
+    // point at the new child handles - they just stop paying `fabricProps` + a recursive `propsEqual`
+    // to rediscover that nobody touched them.
+    //
+    // Under DEBUG the saving is handed straight back to check it was honest: an in-place mutation of
+    // a style object or of node.props, which no flag can observe, is the same hazard warnIfStale
+    // already guards on the skip path, and this lane is open to it identically.
+    let props;
+    let propsChanged;
+    if (ownPropsChanged) {
+        profile.propsBuilt += 1;
+        props = fabricProps(node);
+        propsChanged = !propsEqual(committed.props, props);
+    }
+    else {
+        profile.propsReused += 1;
+        props = committed.props;
+        propsChanged = false;
+        warnIfStale(node, committed, 'props');
+    }
     if (!childrenChanged && !propsChanged) {
         stats.reused += 1;
         return { handle: committed.handle, changed: false };
@@ -339,16 +434,23 @@ function reconcile(slot, node, rootTag, hasTextAncestor, renderableParent, force
     let handle;
     if (childrenChanged) {
         stats.cloneChildren += 1;
+        // A clone comes back with an EMPTY child list, so every sibling handle has to be handed back
+        // one by one — that loop is why touching one row of a thousand costs a thousand JSI crossings
+        // at every level up to the root. Where the host accepts the list in the clone call itself it
+        // becomes ONE crossing (see supportsCloneWithChildren in fabric.ts).
+        const batched = slot.supportsCloneWithChildren;
         if (propsChanged) {
             const propsDiff = diffProps(committed.props, props);
             guardSerializable(propsDiff, viewName, committed.tag);
-            handle = slot.cloneNodeWithNewChildrenAndProps(committed.handle, propsDiff);
+            handle = slot.cloneNodeWithNewChildrenAndProps(committed.handle, propsDiff, batched ? childHandles : undefined);
         }
         else {
-            handle = slot.cloneNodeWithNewChildren(committed.handle);
+            handle = slot.cloneNodeWithNewChildren(committed.handle, batched ? childHandles : undefined);
         }
-        for (const childHandle of childHandles) {
-            slot.appendChild(handle, childHandle);
+        if (!batched) {
+            for (const childHandle of childHandles) {
+                slot.appendChild(handle, childHandle);
+            }
         }
     }
     else {
@@ -360,22 +462,22 @@ function reconcile(slot, node, rootTag, hasTextAncestor, renderableParent, force
     // Investigation instrumentation (search-bar-ref "node not committed" bug): see the create-path
     // dlog above. Kept behind DEBUG per <keep_logs_gate_behind_DEBUG>, never removed.
     if (viewName.startsWith('RNS')) {
-        dlog(`mirror.set (update) node=${debugNodeId(node)} tag=${committed.tag} view=${viewName}`);
-    }
-    // The clone keeps the node's family, so its reactTag is unchanged; carry it.
-    mirror.set(node, {
-        handle,
-        tag: committed.tag,
-        rootTag,
-        props,
-        // Store the same flattened child list we diffed against. Anchors are retained-tree
-        // bookkeeping only; keeping raw node.children here makes every anchored subtree look
-        // structurally changed on the next commit and can re-append already-parented Fabric
-        // ShadowNode families under a cloned parent.
-        children: kids.slice(),
-        viewName,
-        parent: renderableParent,
-    });
+        dlog(`committed (update) node=${debugNodeId(node)} tag=${committed.tag} view=${viewName}`);
+    }
+    // Written IN PLACE rather than as a fresh record. The node is the same node, its tag and owner
+    // are unchanged by a clone (the clone keeps the family), so replacing the object bought nothing
+    // and cost one allocation per changed node per commit - and on an ordinary update that is the
+    // whole clone-bubble from the changed leaf up to the root.
+    committed.handle = handle;
+    committed.rootTag = rootTag;
+    committed.props = props;
+    // The same flattened child list we diffed against, by reference (see the create path above for
+    // why it is not copied). Anchors are retained-tree bookkeeping only; keeping raw node.children
+    // here makes every anchored subtree look structurally changed on the next commit and can
+    // re-append already-parented Fabric ShadowNode families under a cloned parent.
+    committed.children = kids;
+    committed.viewName = viewName;
+    committed.parent = renderableParent;
     return { handle, changed: true };
 }
 // One persistent synthetic root container per surface, mirroring RN's AppContainer
@@ -407,15 +509,21 @@ function rootContainerFor(rootTag) {
 // now-stopped surface. Called from unmount (the bridgeless surface-stop path): the host stops then restarts a
 // surface (Fast Refresh, focus/lifecycle) reusing the same rootTag, and a stale root
 // container would re-clone dead handles into the new surface -> a blank screen. The old
-// container's descendants fall out of every reference and their mirror entries GC.
+// container's descendants fall out of every reference and are collected with the committed
+// records they carry.
 export function disposeRoot(rootTag) {
+    // Drop any setNativeProps writes still queued for this surface: their flush is a microtask away
+    // and would otherwise commit into a container that no longer exists, re-creating it from scratch.
+    pendingByRoot.delete(rootTag);
     if (rootContainers.delete(rootTag))
         dlog(`root container disposed root=${rootTag}`);
 }
 export function commitChildren(rootTag, children) {
     // The wrapper holds the surface's top-level children; reconcile walks from it so the
     // whole tree, synthetic root included, goes through the same clone-on-write path.
-    rootContainerFor(rootTag).children = children.slice();
+    const container = rootContainerFor(rootTag);
+    container.children = children.slice();
+    markStructureDirty(container);
     commitContainer(rootTag);
 }
 // Re-run the scoped commit for a surface from its synthetic root container, reusing
@@ -423,6 +531,9 @@ export function commitChildren(rootTag, children) {
 // a full mutation->commit and a single-node Animated frame (setNativeProps) funnel here.
 function commitContainer(rootTag) {
     const slot = getSlot();
+    batchCreate =
+        globalThis.__SYMBIOTE_BATCH_CREATE__ === true &&
+            slot.supportsCloneWithChildren;
     const container = rootContainerFor(rootTag);
     // The synthetic container is dirtied here, at the one entry point, because markDirty can never
     // bubble up to it: a surface's top-level nodes carry `parent === undefined` (surface.ts sets it
@@ -431,6 +542,11 @@ function commitContainer(rootTag) {
     // props rebuild per commit and closes the hole for both callers, mutation commit and
     // setNativeProps alike.
     markDirty(container);
+    // Before the walk, and before either early return: mutations for this tick are done, so a node
+    // that `removeChild` unlinked is now either back under a parent (a framework spelling a move as
+    // remove-then-reinsert) or gone for good. Costs one Set-size read until an app registers its
+    // first host behavior. See host-behavior.ts for why removal cannot answer this itself.
+    sweepDetachedBehaviors(container.children);
     stats.created = 0;
     stats.cloneProps = 0;
     stats.cloneChildren = 0;
@@ -451,6 +567,19 @@ function commitContainer(rootTag) {
     dlog(`commit root=${rootTag} reconciled changed=${result.changed}`);
     // The container's identity is stable, so its un-cloned flag is the no-op signal:
     // an over-scheduled commit that touched nothing makes zero native calls.
+    //
+    // TRAP FOR BEHAVIOR AUTHORS, and it cost two iterations to find: this return is ALSO the gate on
+    // `runDeferredAttaches` and `runPostCommitHooks` below. A host behavior that calls
+    // `requestCommitFor(node)` WITHOUT writing a prop therefore never reaches its `afterCommit` /
+    // `attachAfterCommit` half — the commit it asked for is a no-op, and a no-op returns here.
+    //
+    // That is correct for what the hooks are FOR: they exist to retry once fresh Fabric tags are
+    // assigned, and a commit that made zero native calls assigned none. So the fix is not to hoist
+    // them above this line — that would run every deferred hook on every over-scheduled commit, which
+    // is the common case. A behavior needing a turn of the loop with nothing to write should schedule
+    // its own (`queueMicrotask`, as Switch's snap-back and Angular's `snapBackIfNeeded` both do) and
+    // keep `afterCommit` registered for the case a microtask cannot reach: a prop change with no
+    // preceding native event.
     if (!result.changed) {
         dlog(`commit root=${rootTag} no-op (skipped completeRoot)`);
         return;
@@ -463,11 +592,18 @@ function commitContainer(rootTag) {
     // and ran too early (the Animated native driver binding a props node to a view under
     // an async-batched commit) retry now. No-op when nothing is pending.
     runPostCommitHooks();
+    // The same moment, for the half of a host behavior that could not run at `attach`. A behavior
+    // whose setup needs a Fabric tag (a view command, a native Animated binding, an event attach)
+    // declares `attachAfterCommit` and is drained here. `committedOf` is passed as the predicate
+    // rather than imported by `host-behavior.ts`, keeping that dependency one-directional — this
+    // module already imports from it, and a cycle is a live hazard under Metro's `inlineRequires`.
+    runDeferredAttaches(node => committedOf(node) !== undefined);
     if (isDebug()) {
         const mode = stats.created > 0 && stats.reused === 0 ? 'full' : 'incremental';
         dlog(`commit root=${rootTag} ${mode} ` +
             `created=${stats.created} cloneProps=${stats.cloneProps} ` +
             `cloneChildren=${stats.cloneChildren} reused=${stats.reused} ` +
+            `propsBuilt=${profile.propsBuilt} propsReused=${profile.propsReused} ` +
             `walk=${walkMs.toFixed(3)}ms`);
     }
 }
@@ -477,6 +613,8 @@ export function readCommitProfile() {
         commits: profile.commits,
         walkMs: profile.walkMs,
         nodesVisited: profile.nodesVisited,
+        propsBuilt: profile.propsBuilt,
+        propsReused: profile.propsReused,
         propWrites: props.writes,
         propNoops: props.noops,
         childScans: childScan.scans,
@@ -488,6 +626,8 @@ export function readCommitProfile() {
     profile.commits = 0;
     profile.walkMs = 0;
     profile.nodesVisited = 0;
+    profile.propsBuilt = 0;
+    profile.propsReused = 0;
     childScan.scans = 0;
     childScan.probed = 0;
     childScan.flattens = 0;
@@ -495,6 +635,224 @@ export function readCommitProfile() {
     childScan.widest = 0;
     return snapshot;
 }
+function commitTargeted(nodes) {
+    // ── PLAN FIRST, MUTATE SECOND ──────────────────────────────────────────────────────────────
+    // Every precondition is checked and every sibling handle resolved before a single native call,
+    // so a bail costs nothing and leaves the tree exactly as it was.
+    //
+    // This is not hypothetical tidiness: an earlier version validated the ancestor chain up front but
+    // resolved SIBLING handles inside the clone loop, so a bail half-way had already re-pointed a
+    // node's committed record at a clone that was never handed to completeRoot, and had already
+    // cleared its dirty flags - so the general-path fallback then skipped the node as clean and
+    // committed an orphan handle. The fallback test in animated-commit-cost.test.ts is what caught it.
+    const writes = [];
+    for (const node of nodes) {
+        const record = committedOf(node);
+        if (record === undefined)
+            return false;
+        // The node's own children must be the ones Fabric holds: this path never descends, so a
+        // pending structural change below would be published as if it had not happened.
+        if (node.structureDirty)
+            return false;
+        // THE TWIN OF THE CHECK ABOVE, and the one that was missing. `dirty` is a SUBTREE flag — it
+        // means "this node or something under it needs work" — while this path clears it as if it were
+        // a self flag. Clearing it over a dirty descendant strands that descendant permanently: the
+        // general commit reconciles from the root, finds a clean chain, and never descends again.
+        //
+        // Direct children are enough, and that is not an approximation. `markDirty` walks up from the
+        // dirtied node and STOPS at the first already-dirty ancestor; in this scenario that ancestor is
+        // this node, so the chain from any dirty descendant up to here is fully marked — which makes a
+        // dirty direct child a certainty whenever a dirty descendant exists. So the check is O(children)
+        // rather than a subtree walk, on a path that runs once per animation frame.
+        //
+        // Reproduced 2026-08-24 by a peer's flag dump after tier-2 made a press ask for its own commit:
+        // press the node, dirty its child in the same tick, and the child never commits again. Vue and
+        // Solid did not show it because their schedulers rewrite the prop on the node itself and
+        // re-dirty the chain — an accident of those schedulers, not a property of this contract.
+        if (node.children.some(child => child.dirty)) {
+            dlog('commit targeted: dirty descendant, using the general path');
+            return false;
+        }
+        // Counted like the general path's rebuild, because it is one: the meter must not read as though
+        // an animation frame builds no payload just because it took the short route.
+        profile.propsBuilt += 1;
+        const props = fabricProps(node);
+        const diff = diffProps(record.props, props);
+        if (Object.keys(diff).length === 0) {
+            // Fabric already holds these values. Not an error and not a fallback: the general path would
+            // reach the same conclusion, after walking the tree to get here. Dropping it from the batch
+            // is safe even if a LATER node bails the whole thing — its props genuinely match Fabric, so
+            // the general commit skipping it as clean publishes the same tree.
+            node.dirty = false;
+            node.propsDirty = false;
+            dlog(`commit targeted tag=${record.tag} no-op (props identical)`);
+            continue;
+        }
+        writes.push({ node, record, props, diff });
+    }
+    if (writes.length === 0)
+        return true;
+    // Build the union of the ancestor chains. `changed` is the whole union keyed by node, so a shared
+    // ancestor is entered ONCE however many of the batch's leaves sit under it — which is the entire
+    // saving over committing each leaf separately.
+    const changed = new Map();
+    let unionRoot;
+    for (const write of writes) {
+        let child = write.node;
+        let ancestor = write.record.parent;
+        while (ancestor !== undefined) {
+            const record = committedOf(ancestor);
+            if (record === undefined)
+                return false;
+            // THE precondition, and the one an earlier version of this function missed. `record.children`
+            // is a SNAPSHOT from the last commit. If this ancestor's real child list has moved on - a row
+            // added, removed, or reordered - rebuilding its child set from that snapshot silently
+            // publishes the OLD structure, with no error anywhere. Caught by the fallback row in
+            // animated-commit-cost.test.ts, which appends a sibling and then animates: without this check
+            // the new sibling never reached Fabric and every other assertion still passed.
+            if (ancestor.structureDirty) {
+                dlog('commit targeted: ancestor child list moved on, using the general path');
+                return false;
+            }
+            const seen = changed.get(ancestor);
+            if (seen !== undefined) {
+                // Already in the union via another leaf. Everything ABOVE it is therefore already in too,
+                // and already names this node as changed, so the walk stops here.
+                seen.add(child);
+                break;
+            }
+            changed.set(ancestor, new Set([child]));
+            if (record.parent === undefined)
+                unionRoot = ancestor;
+            child = ancestor;
+            ancestor = record.parent;
+        }
+    }
+    // Resolve every branch's child handles now, so the clone pass below cannot fail part-way.
+    const branches = new Map();
+    for (const [node, changedChildren] of changed) {
+        const record = committedOf(node);
+        if (record === undefined)
+            return false;
+        const handles = [];
+        const slots = new Map();
+        for (const child of record.children) {
+            const childRecord = committedOf(child);
+            // A sibling with no committed record means a structural change is pending, which this path
+            // cannot express. Bail before touching anything.
+            if (childRecord === undefined) {
+                dlog('commit targeted: uncommitted sibling, using the general path');
+                return false;
+            }
+            if (changedChildren.has(child))
+                slots.set(child, handles.length);
+            handles.push(childRecord.handle);
+        }
+        if (slots.size !== changedChildren.size) {
+            // A changed child is not in its parent's committed child list — an uncommitted move.
+            dlog('commit targeted: child not in committed set, using the general path');
+            return false;
+        }
+        branches.set(node, { record, handles, slots });
+    }
+    // Every write is on one surface (the caller batches by rootTag), so the chains converge on that
+    // surface's synthetic container and nowhere else. Checked HERE, the last statement of the plan,
+    // so the clone pass below has no way left to bail after it has started mutating.
+    const rootBranch = unionRoot === undefined ? undefined : branches.get(unionRoot);
+    if (unionRoot === undefined || rootBranch === undefined)
+        return false;
+    const rootTag = rootBranch.record.rootTag;
+    // ── MUTATE ─────────────────────────────────────────────────────────────────────────────────
+    const slot = getSlot();
+    const walkStart = performance.now();
+    const cloned = new Map();
+    for (const write of writes) {
+        guardSerializable(write.diff, write.record.viewName, write.record.tag);
+        const handle = slot.cloneNodeWithNewProps(write.record.handle, write.diff);
+        stats.cloneProps += 1;
+        write.record.handle = handle;
+        write.record.props = write.props;
+        write.node.dirty = false;
+        write.node.propsDirty = false;
+        cloned.set(write.node, handle);
+    }
+    // Re-clone each branch exactly once, deepest first. The recursion is bounded by the tree depth,
+    // and every branch it touches is in the plan above, so nothing here can bail.
+    const cloneBranch = (node) => {
+        const done = cloned.get(node);
+        if (done !== undefined)
+            return done;
+        const branch = branches.get(node);
+        // Unreachable by construction: cloneBranch is only ever called on a node the plan put in
+        // `branches` or the write loop put in `cloned`. Leaving the committed handle in place is the
+        // safe direction if that ever stops being true, and the oracle row would report it.
+        if (branch === undefined)
+            return undefined;
+        for (const [child, index] of branch.slots) {
+            const childHandle = cloneBranch(child);
+            if (childHandle !== undefined)
+                branch.handles[index] = childHandle;
+        }
+        const batched = slot.supportsCloneWithChildren;
+        const handle = slot.cloneNodeWithNewChildren(branch.record.handle, batched ? branch.handles : undefined);
+        stats.cloneChildren += 1;
+        if (!batched)
+            for (const childHandle of branch.handles)
+                slot.appendChild(handle, childHandle);
+        branch.record.handle = handle;
+        cloned.set(node, handle);
+        return handle;
+    };
+    const rootHandle = cloneBranch(unionRoot) ?? rootBranch.record.handle;
+    const childSet = slot.createChildSet(rootTag);
+    slot.appendChildToSet(childSet, rootHandle);
+    slot.completeRoot(rootTag, childSet);
+    profile.walkMs += performance.now() - walkStart;
+    profile.commits += 1;
+    profile.nodesVisited += cloned.size;
+    runPostCommitHooks();
+    dlog(`commit targeted root=${rootTag} leaves=${writes.length} ` +
+        `union=${branches.size}`);
+    return true;
+}
+// A JS-driven Animated frame lands in setNativeProps once per animated leaf. Five animations on
+// five rows of one list therefore used to mean FIVE commits per frame: five completeRoots, and
+// every shared ancestor re-cloned - with its whole child list re-appended - five times over. The
+// dirty-set census (`symbiote-perf-measurement` skill) measured that appendChild is the real floor
+// of a commit and that it multiplies almost exactly with the commit count. So the win here is not a
+// faster commit, it is FEWER of them.
+//
+// The batch never drops a value, and that is a rule, not a hope. Merging writes to DIFFERENT nodes
+// is free - each carries its own value and one commit publishes them all. The single case where
+// merging WOULD lose a value is a second write to a node already pending, so that case does not
+// merge: it publishes the pending batch first, synchronously, and opens a new one. Hence:
+//
+//   N writes to N different nodes in one task  ->  one completeRoot, all N values land
+//   two writes to the SAME node in one task    ->  two completeRoots, both values land
+//
+// The second row costs nothing in practice: an Animated.Value ticks its props node exactly once per
+// rAF (animations/timing.ts's onFrame calls onUpdate once, then schedules the next frame), so
+// concurrent animations are always distinct nodes. It exists for the paths that genuinely can write
+// twice - two animations bound to one prop of one node, or Animated.event when the host delivers
+// two scroll events in a single task.
+const pendingByRoot = new Map();
+let flushScheduled = false;
+// Publish every pending write: one commit per surface. A surface with exactly one pending node
+// takes the targeted chain clone (4.5x, §4a); with several it takes the general walk, which already
+// visits only dirty paths and reaches all of them under a single completeRoot - which is the point.
+export function flushNativeProps() {
+    flushScheduled = false;
+    if (pendingByRoot.size === 0)
+        return;
+    const batches = [...pendingByRoot];
+    pendingByRoot.clear();
+    for (const [rootTag, nodes] of batches) {
+        if (commitTargeted(nodes))
+            continue;
+        dlog(`flush native props root=${rootTag} nodes=${nodes.size} (general)`);
+        commitContainer(rootTag);
+    }
+}
 // Targeted per-frame prop write for the JS-driven Animated path. RN flushes an
 // animation frame with an in-place `instance.setNativeProps(...)`; we have no
 // in-place mutation (Fabric is persistent), so a frame is one scoped commit: mutate
@@ -503,11 +861,17 @@ export function readCommitProfile() {
 // by reference, and emits a single completeRoot. This is the "slow tier", viable for a
 // single shallow animation; driving the animation natively is the answer for scale.
 export function setNativeProps(node, partial) {
-    const record = mirror.get(node);
+    const record = committedOf(node);
     if (record === undefined) {
         dlog('setNativeProps skipped: node not committed');
         return;
     }
+    // BEFORE the prop writes below, deliberately: the pending batch still has to publish the value
+    // this node holds right now, and mutating first would overwrite the very thing being preserved.
+    if (pendingByRoot.get(record.rootTag)?.has(node) === true) {
+        dlog(`setNativeProps tag=${record.tag} written twice in one task, flushing`);
+        flushNativeProps();
+    }
     for (const [key, value] of Object.entries(partial)) {
         if (key === 'style') {
             // A partial style override MERGES onto the declarative style (RN semantics):
@@ -520,18 +884,57 @@ export function setNativeProps(node, partial) {
         }
         else {
             node.props[key] = value;
+            // Writes `node.props` directly, so it owes the aria gate for the same reason it owes the
+            // props mark below: `setProp` is where that flag is normally raised and this path bypasses
+            // it. An `aria-*` arriving only through setNativeProps would otherwise never be folded.
+            if (!node.hasAriaAlias && isAriaAliasKey(key))
+                node.hasAriaAlias = true;
         }
     }
-    // Writes node.props directly rather than through setProp, so it owes its own mark.
-    markDirty(node);
+    // Writes node.props directly rather than through setProp, so it owes its own mark - and it owes
+    // the PROPS mark specifically: markDirty alone would send the node down the fast lane above,
+    // which reuses the mirror's payload by reference and would drop the Animated frame entirely.
+    markPropsDirty(node);
     dlog(`setNativeProps root=${record.rootTag} tag=${record.tag} keys=${Object.keys(partial)}`);
-    commitContainer(record.rootTag);
+    // Queued, not committed: every write made in this task publishes together at the microtask
+    // boundary. See the batching note above commitTargeted's caller block for why that loses nothing.
+    requestCommitFor(node);
+}
+/**
+ * Publish a node whose props were changed OUTSIDE any renderer mutation.
+ *
+ * Dirtying is not publishing. Every other write reaches Fabric because the framework's own commit
+ * follows it; a change driven by a NATIVE EVENT has no such follow-up — `native-events.ts`
+ * requests no commit and no adapter does either, so a node marked dirty from an event handler
+ * simply stays dirty. The host-behavior press path (`setNodePressed` for `:active`) is the first
+ * caller that is not `setNativeProps`, and `setNodeHidden`'s React twin never needed it because
+ * the reconciler is already in its commit phase when it calls.
+ *
+ * Queued rather than committed on the spot, sharing `setNativeProps`' batch: several writes in one
+ * task publish together at the microtask boundary, one commit per surface.
+ */
+export function requestCommitFor(node) {
+    const record = committedOf(node);
+    if (record === undefined) {
+        dlog('requestCommitFor skipped: node not committed');
+        return;
+    }
+    let pending = pendingByRoot.get(record.rootTag);
+    if (pending === undefined) {
+        pending = new Set();
+        pendingByRoot.set(record.rootTag, pending);
+    }
+    pending.add(node);
+    if (!flushScheduled) {
+        flushScheduled = true;
+        queueMicrotask(flushNativeProps);
+    }
 }
 // The committed reactTag of a node (stable across clone-on-write), for binding the
 // native Animated driver via connectAnimatedNodeToView. Undefined until the node
 // has been committed at least once.
 export function getNativeTag(node) {
-    return mirror.get(node)?.tag;
+    return committedOf(node)?.tag;
 }
 // Actions waiting for their node's first commit. An adapter that wires an imperative/native call at
 // lifecycle time (autoFocus, a native Animated.event attach) can run BEFORE completeRoot under an
@@ -550,7 +953,7 @@ registerPostCommit(() => {
 // silently no-opping. Returns a cancel fn (drop the pending retry, e.g. on unmount).
 export function whenCommitted(node, action) {
     const attempt = () => {
-        if (mirror.get(node) === undefined)
+        if (committedOf(node) === undefined)
             return false;
         action();
         return true;
@@ -564,16 +967,16 @@ export function whenCommitted(node, action) {
 // The node's current Fabric handle (the createNode/clone return value), identical in
 // kind to React's stateNode.node, for the native driver's ShadowNodeFamily path.
 export function getNativeNode(node) {
-    return mirror.get(node)?.handle;
+    return committedOf(node)?.handle;
 }
 // Imperative view command (e.g. TextInput's setTextAndSelection / focus / blur),
 // aimed at a node's CURRENT Fabric handle. Only valid once the node has been
-// committed at least once; its handle is read from the mirror.
+// committed at least once; its handle is read from the node's committed record.
 export function dispatchViewCommand(node, commandName, args) {
-    const record = mirror.get(node);
+    const record = committedOf(node);
     if (record === undefined) {
-        // node=... compares directly against the mirror.set logs above (same debugNodeId scheme) to
-        // prove/disprove a node-identity mismatch — see the search-bar-ref investigation note there.
+        // node=... compares directly against the `committed (create|update)` logs above (same
+        // debugNodeId scheme) to prove/disprove an identity mismatch — see the note there.
         dlog(`dispatchViewCommand "${commandName}" skipped: node not committed (node=${debugNodeId(node)} component=${node.component})`);
         return;
     }
@@ -586,7 +989,7 @@ export function dispatchViewCommand(node, commandName, args) {
 // with the STRING eventType; the C++ side maps it to the platform's accessibility-event kind.
 // A no-op (logged) until the node is committed; there is no handle yet.
 export function sendAccessibilityEvent(node, eventType) {
-    const record = mirror.get(node);
+    const record = committedOf(node);
     if (record === undefined) {
         dlog(`sendAccessibilityEvent "${eventType}" skipped: node not committed`);
         return;
@@ -598,7 +1001,7 @@ export function sendAccessibilityEvent(node, eventType) {
 // measure family that reanimated / gesture-handler / scroll-to reach through). A
 // no-op with a dlog until the node is committed; there is no handle to measure yet.
 export function measure(node, callback) {
-    const record = mirror.get(node);
+    const record = committedOf(node);
     if (record === undefined) {
         dlog('measure skipped: node not committed');
         return;
@@ -606,7 +1009,7 @@ export function measure(node, callback) {
     getSlot().measure(record.handle, callback);
 }
 export function measureInWindow(node, callback) {
-    const record = mirror.get(node);
+    const record = committedOf(node);
     if (record === undefined) {
         dlog('measureInWindow skipped: node not committed');
         return;
@@ -617,8 +1020,8 @@ export function measureInWindow(node, callback) {
 // signature is (relative, onSuccess, onFail) but the native slot wants the fail
 // callback before success, so the order is swapped here.
 export function measureLayout(node, relativeTo, onSuccess, onFail = () => { }) {
-    const record = mirror.get(node);
-    const relativeRecord = mirror.get(relativeTo);
+    const record = committedOf(node);
+    const relativeRecord = committedOf(relativeTo);
     if (record === undefined || relativeRecord === undefined) {
         dlog('measureLayout skipped: a node is not committed');
         return;