@symbiote-native/engine 1.3.0 → 1.4.0

package/build/host-behavior.js

@@ -1,31 +1,13 @@
-// Per-TAG behavior on an engine node — the seam that lets a primitive's state machine live BELOW
-// the framework instead of inside a framework component.
-//
-// WHY IT EXISTS. Vue, Svelte, Solid and Angular all optimize element subtrees and stop at a
-// component boundary, so a primitive shipped as a component is charged a per-instance price in
-// each framework's own currency (an instance, a props Proxy, anchor nodes, an LView). A primitive
-// whose state the TEMPLATE never reads does not need to be a component at all — its machine only
-// needs a per-node home, and the engine node is one. `.claude/rules/host-primitive-tier.md` has
-// the tier model; this module is the tier-2 half of it.
-//
-// WHY A REGISTRY RATHER THAN A DIRECT IMPORT. `@symbiote-native/components` depends on
-// `@symbiote-native/engine`, never the reverse, so the engine cannot import `createPressHandlers`
-// and friends. CLAUDE.md's preferred answer to a registration problem — delete the indirection —
-// is therefore unavailable here; the inversion is forced, not chosen.
-//
-// WHICH MEANS THE REGISTRATION ITSELF IS THE HAZARD, and it is the one CLAUDE.md spells out:
-// Metro turns on `inlineRequires` for production only, moving a `require` down to the first place
-// its binding is used as a VALUE, and a barrel's `export { X } from './x'` compiles to a lazy
-// getter. A module whose only job is to call `registerHostBehavior` is never named as a value, so
-// re-exporting it from a barrel means it NEVER EVALUATES in a release build — dev is perfect,
-// release silently has no behavior. The one shape that works is a bare side-effect import that is
-// never re-exported from that barrel, the pattern in
-// `packages/slider/src/{react,vue,svelte,angular}/index.ts`:
-//
-//     import '../register';     // in the adapter entry — NOT `export * from '../register'`
-//
-// `registerHostBehavior` emits a `dlog` precisely so `DEBUG=1` answers "did my registration run at
-// all" before anyone starts debugging the behavior itself.
+// Per-tag behavior on an engine node — lets a primitive's state machine live below the framework
+// instead of inside a framework component, which would otherwise charge it a per-instance cost in
+// every framework touching element subtrees (see .claude/rules/host-primitive-tier.md, tier 2).
+// A registry, not a direct import: components depends on engine and never the reverse, so the
+// engine cannot import createPressHandlers directly. The inversion is forced, not chosen.
+// The registration call itself is the hazard: Metro's inlineRequires makes a barrel re-export
+// lazy, so a module whose only job is registerHostBehavior() never evaluates in release unless
+// it's a bare side-effect import (`import '../register'`), never re-exported — see packages/slider.
+// registerHostBehavior emits a dlog so DEBUG=1 answers "did my registration run" before anyone
+// starts debugging the behavior itself.
 import { parentsOf, teardownSubtreesOf } from './host-access.js';
 import { recordSetTag } from './mutation-buffer.js';
 import { dlog } from './debug.js';
@@ -33,33 +15,17 @@ 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();
-// 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.
-//
-// 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
-// `view` arrives as `RCTView`. Keying the registry by Fabric name instead is not an
-// option — a pressable resolves to `RCTView` like any other view, so the press machine would
-// attach to every plain `View` in the app. So the tag alphabet is used EXACTLY ONCE, at
-// `attachHostBehavior`, where the caller still holds it; every later lookup reads this map.
-//
-// Found by a peer session probing the installed shape, not by a unit test: the tests built their
-// subject with `createElement(PRESSABLE_TAG)`, which passes the tag AS the Fabric name and makes
-// the key match by accident. No adapter constructs a node that way, so the registration could
-// never have fired in an app while all six break-tests kept failing correctly on their own axes.
-// 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`.
+// A node the sweep has torn down carries node.isTornDown — it can still be re-inserted (see
+// reattachHostBehaviors), and the bit tells an insert whether it must walk at all, so the common
+// case (building a fresh tree) never walks anything. A field, since both readers are per-node.
+// 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 a WeakMap, since a 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 resolved
+// Fabric view name (`view` arrives as `RCTView`), and keying by that would attach the press
+// machine to every plain View. The tag alphabet is used exactly once, at attachHostBehavior.
+// The gate: createElement and removeChild are the engine's hottest paths, so neither may pay a
+// Set insert for a feature no app uses yet. While this is false both cost one boolean read.
 let hasBehaviors = false;
 // See `hasAttachedBehaviors`. A behavior TYPE existing and a behavior being ON a node are different
 // questions, and the teardown sweep was asking the first one.
@@ -69,46 +35,29 @@ export function registerHostBehavior(component, behavior) {
     behaviors.set(component, behavior);
     hasBehaviors = true;
 }
-// Read access to the registry, so an audit can DERIVE what a behavior owns instead of restating it.
-// The one that matters: a name in `ownedListeners` is only reachable if `routeProp` also treats it
-// as a registered event — otherwise the app's callback lands in `node.props` and the machine, which
-// reads the stash, never sees it. That set difference is a test
-// (`core/components/src/behaviors/owned-listeners-are-routable.test.ts`) and it needs this to stay
-// derived rather than becoming another hand-written list.
+// Read access to the registry, so an audit can derive what a behavior owns rather than restating
+// it — a name in ownedListeners is only reachable if routeProp also treats it as a registered
+// event, and owned-listeners-are-routable.test.ts checks that gap stays empty.
 export function hostBehaviorFor(tag) {
     return behaviors.get(tag);
 }
 export function hasHostBehaviors() {
     return hasBehaviors;
 }
-/**
- * Has a behavior ever ATTACHED to a node, as opposed to a behavior TYPE having been registered?
- *
- * `hasBehaviors` answers the second, and it is on from module load in every app: registering
- * `Pressable` arms it whether or not one is ever mounted. It gates `createElement`'s attach probe
- * correctly — a node has to be offered to the registry to find out. It gates the TEARDOWN SWEEP
- * wrongly, and that is expensive: the sweep crosses every removed node into JS, which on a
- * 1 000-row clear is ten thousand handles. Measured on `build-release`
- * (`teardown-sweep-cost.itest.ts`): 1.8 ms with the sweep off against 6.3 ms with it on, i.e. 3.2x,
- * 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:
- * `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 `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
- * has no size and no destructor. Being late is the only way it can be wrong, and it cannot be late.
- */
+// Has a behavior ever attached to a node, as opposed to a behavior type having been registered?
+// hasBehaviors answers the second and is on from module load in every app — correct for gating
+// createElement's attach probe, wrong (and costly) for gating the teardown sweep.
+// Nothing the sweep does can matter before the first attach: every collection it touches is
+// written only from inside a behavior branch, and the only other effect (marking isTornDown) has
+// nothing to re-arm yet either.
+// Monotone, deliberately: turns on and never off, so it needs no accounting on a destructor-less
+// WeakMap. Being late is the only way it can be wrong, and it cannot be late.
 export function hasAttachedBehaviors() {
     return hasAttached;
 }
 // What an owner prop is called on the slot, or undefined when it belongs to the owner after all.
-//
-// Called from `routeProp` only for a node that HAS a slot (`node.childHost !== undefined`), which
-// is what keeps a WeakMap probe off the hot path: every other node is turned away by one field
-// read, the same gate `payloadFold` uses one layer down.
+// Called from routeProp only for a node that has a slot, which keeps a WeakMap probe off the hot
+// path — every other node is turned away by one field read, the same gate payloadFold uses.
 export function slotPropNameFor(node, key) {
     const behavior = node.hostBehavior;
     if (behavior === undefined)
@@ -128,16 +77,10 @@ export function slotTakesChildren(node) {
     return node.hostBehavior?.slotTakesNoChildren !== true;
 }
 // Nodes a behavior built that are NOT the slot, and whose payloads derive from the owner's props.
-//
-// `slotDerived` marks `node.childHost` and nothing else, which is one hop — enough for ScrollView,
-// whose only derived node IS the slot, and not enough for a primitive whose `buildStructure` builds
-// a chain. Button builds view > text > raw text and folds two of them from the same three owner
-// props; without this the deeper nodes freeze at their mount values, and the workaround is to write
-// them from inside a fold whose contract says it MUST be pure.
-//
-// A WeakMap rather than a field, for the reason `stashed` is one: this exists only for the handful
-// of nodes a composed behavior built, and a field costs a shape transition on every node in every
-// app. It is read only inside the `slotDerived` branch, which has already paid a WeakMap probe.
+// slotDerived marks only node.childHost, which is one hop — not enough for Button's view > text >
+// raw text chain, whose deeper nodes would otherwise freeze at their mount values.
+// A WeakMap rather than a field: this exists only for the handful of nodes a composed behavior
+// built, and a field would cost a shape transition on every node in every app.
 const derived = new WeakMap();
 // Called from `buildStructure` for each node past the slot. Not idempotent-checked: structure is
 // built exactly once (`attachHostBehavior`, never `reattachSubtree`), so a second call would be a
@@ -166,13 +109,9 @@ export function notifyChildInserted(node, child) {
 export function claimModeFor(node, component) {
     return node.hostBehavior?.claimedChildren?.[component];
 }
-/**
- * Every owner key feeds the slot. The spelling for a `cloneElement` primitive, whose slot is not
- * derived from a named set at all — see `IHostBehavior.slotDerived`.
- *
- * A sentinel in the SAME array rather than a second field, so `slotDerivesFrom` stays one lookup and
- * a behavior that wants both spellings cannot express a contradiction.
- */
+// Every owner key feeds the slot — the spelling for a cloneElement primitive, whose slot isn't
+// derived from a named set at all (see IHostBehavior.slotDerived). A sentinel in the same array
+// rather than a second field, so slotDerivesFrom stays one lookup.
 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.
@@ -207,20 +146,18 @@ export function stashAppListener(node, name, listener) {
 export function appListenerFor(node, name) {
     return stashed.get(node)?.get(name);
 }
-// `tag` is the INTRINSIC tag the adapter started from, not the resolved Fabric name it put on the
-// node. Defaulted to `node.component` so an adapter that has not been taught to pass it keeps
-// working for a behavior registered under a Fabric name — no adapter registers one, so in practice
-// the default simply never matches and costs one failed lookup.
+// `tag` is the intrinsic tag the adapter started from, not the resolved Fabric name on the node —
+// callers default it to node.component for an adapter not yet taught to pass it, which costs one
+// harmless failed lookup since no behavior is registered under a Fabric name.
 export function attachHostBehavior(node, tag) {
     const behavior = behaviors.get(tag);
     if (behavior === undefined)
         return;
     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
-    // something: an app's own `<div>`-equivalent would otherwise pay an intern and an op to tell the
-    // host a name it has no rule for.
+    // The tag itself, over the wire, so the host can resolve its platform props without a trip back
+    // into JS. Here rather than in createElement, since here is where a tag is known to name a rule
+    // the host actually has — an app's own arbitrary tag would pay an op for nothing.
     recordSetTag(node, tag);
     // BEFORE `attach` and before any prop is routed, which is the whole point: it changes how a
     // WRITE is stored, so a source written to this node must never arrive ahead of it.
@@ -243,10 +180,8 @@ export function attachHostBehavior(node, tag) {
     if (behavior.afterCommit !== undefined) {
         committedEachTime.add(node);
         node.hasCommitHook = true;
-        // Armed from the start, so the commit that first lands this node gives it a beat. A freshly
-        // created node has had no prop written through `setProp` yet — `createRawText`'s text is an OP,
-        // not a field — so nothing else would arm it, and its behavior would wait for a write that a
-        // purely declarative mount never makes.
+        // Armed from the start, so the commit that first lands this node gives it a beat — a freshly
+        // created node has had no setProp write yet, so nothing else would arm it.
         noteCommitHookNodeChanged(node);
     }
 }
@@ -254,20 +189,12 @@ export function attachHostBehavior(node, tag) {
 // opposite lifetimes: one empties as its nodes commit, this one holds until teardown.
 const committedEachTime = new Set();
 // Nodes whose behavior declared `attachAfterCommit` and whose first commit has not happened yet.
-//
-// A plain Set rather than a call into `whenCommitted`: `commit.ts` already imports this module, so
-// reaching back for it would close an import cycle. Metro's `inlineRequires` has made module
-// evaluation order a real hazard here rather than a theoretical one (see this file's own
-// registration comment), so the dependency stays one-directional and commit DRAINS this instead.
+// A plain Set rather than a call into whenCommitted: commit.ts already imports this module, so
+// reaching back for it would close an import cycle (see this file's own registration comment).
 const awaitingCommit = new Set();
-/**
- * Run the deferred half of every behavior whose node has now been committed. Called from the commit
- * path immediately after `completeRoot`, where fresh Fabric tags have just been assigned.
- *
- * `isCommitted` is passed in for the same no-cycle reason — `committedOf` lives in `commit.ts`. A
- * still-uncommitted node stays in the set: a create superseded before it ever reached Fabric waits
- * for the commit that lands it, and `detachSubtree` drops it if that commit never comes.
- */
+// Run the deferred half of every behavior whose node has now been committed, called right after
+// completeRoot assigns fresh Fabric tags. `isCommitted` is passed in for the same no-cycle reason.
+// A still-uncommitted node stays in the set until its commit lands, or detachSubtree drops it.
 export function runDeferredAttaches(isCommitted) {
     // The gate: an app registering no behavior pays one Set-size read per commit, matching the
     // discipline `hasBehaviors` sets for `createElement`.
@@ -277,56 +204,26 @@ export function runDeferredAttaches(isCommitted) {
         if (!isCommitted(node))
             continue;
         awaitingCommit.delete(node);
-        // The answer is worth recording, not just acting on. `runCommittedHooks` runs immediately after
-        // this and asks the SAME question about the SAME node, and `isCommitted` crosses the host
-        // 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.
+        // Worth recording, not just acting on: runCommittedHooks asks the same isCommitted question
+        // right after, and that crosses to the host — a node with both hooks would otherwise pay two
+        // crossings for one fact on the commit that landed it.
         everCommitted.add(node);
         node.hostBehavior?.attachAfterCommit?.(node);
     }
 }
-/**
- * The recurring beat. Split from `runDeferredAttaches` because the two answer different questions:
- * `attachAfterCommit` needs a FRESH FABRIC TAG, so it belongs below `completeRoot` and must not run
- * on a commit that made no native call; `afterCommit` needs only "props were published", which a
- * no-op commit satisfies just as well.
- *
- * Keeping them together made `afterCommit` unreachable for exactly the props a behavior owns: a fold
- * that STRIPS a prop makes its own commit byte-identical, `commitContainer` returns above the drain,
- * and the hook never sees the flip. TouchableOpacity's re-settle on `disabled` is the case
- * (`disabled` is a MACHINE_ONLY key), Button's `title`/`color` the other.
- *
- * SETUP STILL RUNS BEFORE THE BEAT on the first commit, and the order is load-bearing: a node
- * carrying both hooks has `attachAfterCommit` seed the mirrors `afterCommit` compares against. The
- * caller preserves it by calling this AFTER `runDeferredAttaches` on the changed path — the no-op
- * path has no setup to run, since a node with no Fabric tag has not committed at all.
- */
-/**
- * Nodes with a recurring hook whose props were written since the last beat.
- *
- * THE POPULATION THE BEAT RUNS OVER, and narrowing it to this is the second half of F-66. The
- * first half stopped the loop CROSSING to decide whether to run a hook; this stops it running the
- * hook at all for a node that cannot have anything to do — and the hook BODY is where the rest of
- * the cost was. TextInput's asks the host for its `value` to compare against its native mirror,
- * which the work ledger measures at `propOf` × 1 000 per commit, in all four adapters.
- *
- * Sound because both behaviors that document why they need the beat need it for the same event, a
- * prop written on their own node. `switch.ts` says so outright — "a check scheduled only from
- * `onChange` never re-runs for a prop change with no preceding native event … `afterCommit` costs
- * nothing extra (it fires only on a commit that already changed something)" — and TextInput's
- * controlled handshake has two sources, the app moving `value` and the user typing, the second of
- * which writes `mostRecentEventCount`. A fold that STRIPS a prop is covered too: the write
- * happened, and it is the PAYLOAD that comes out byte-identical, which is the case this hook was
- * split from `attachAfterCommit` for.
- */
+// The recurring beat, split from runDeferredAttaches: attachAfterCommit needs a fresh Fabric tag
+// and must not run on a no-op commit; afterCommit needs only "props were published", which a
+// no-op commit (a fold that stripped a prop, making the commit byte-identical) satisfies too.
+// Setup still runs before the beat on the first commit — a node carrying both hooks has
+// attachAfterCommit seed the mirrors afterCommit compares against, preserved by calling this after
+// runDeferredAttaches on the changed path only.
+// Nodes with a recurring hook whose props were written since the last beat — narrowing the
+// population the beat runs over, since the hook body itself (TextInput reading its native mirror)
+// is where the real cost is, not the loop deciding whether to run it.
 const commitHookNodesChanged = new Set();
-/**
- * Arm a node's recurring hook for the next commit.
- *
- * Called from `setProp` — gated there on `node.hasCommitHook`, a boolean field beside
- * `hasAriaAlias` on the same hidden class, so a node without a recurring hook pays one load and
- * one branch per write and never reaches this.
- */
+// Arm a node's recurring hook for the next commit. Called from setProp, gated on node.hasCommitHook
+// (a boolean field beside hasAriaAlias on the same hidden class), so a node without a recurring
+// hook pays one load and one branch per write and never reaches this.
 export function noteCommitHookNodeChanged(node) {
     commitHookNodesChanged.add(node);
 }
@@ -342,11 +239,9 @@ export function runCommittedHooks(isCommitted) {
         if (!committedEachTime.has(node))
             continue;
         if (!everCommitted.has(node)) {
-            // ARMED BUT NOT YET COMMITTED — put it back. A node is armed when its behavior attaches,
-            // which is at `createElement`, before it is in anyone's tree; dropping it here would mean the
-            // commit that finally lands it never gives it a beat. This is the one place the narrowed
-            // population can lose a node, and it is why the set is cleared by REMOVAL of what ran rather
-            // than wholesale.
+            // Armed but not yet committed — put it back. A node is armed at createElement, before it is
+            // in anyone's tree, so dropping it here would mean the commit that finally lands it never
+            // gives it a beat.
             if (!isCommitted(node)) {
                 commitHookNodesChanged.add(node);
                 continue;
@@ -356,173 +251,95 @@ export function runCommittedHooks(isCommitted) {
         node.hostBehavior?.afterCommit?.(node);
     }
 }
-// Nodes of `committedEachTime` that have reached Fabric at least once.
-//
-// ASKED ONCE PER NODE, not once per node per commit. `isCommitted` is `getNativeTag`, which is
-// `committedRecordOf` — a `flushOps()` and a CROSSING TO THE HOST. Before this, the loop above ran
-// over every mounted node whose behavior declared `afterCommit`, on every commit of ANY surface, so
-// a thousand-row list with a `<text-input>` per row paid a thousand crossings to select one row,
-// and paid them again on a commit that changed nothing at all. Measured at 550 for a 550-node set
-// (`__tests__/post-commit-hooks-are-not-the-tree.test.ts`).
-//
-// The cached answer is sound because within `committedEachTime` it is monotone: a node enters when
-// its behavior attaches, leaves in `detachOne` when it is torn down, and a live node that has been
-// committed keeps a Fabric record — a clone keeps the family. So the bit only ever goes TRUE for a
-// node still in the set, which is F-18's `mayHaveChildren` shape: a stale FALSE costs one more
-// crossing next commit, and a stale TRUE is impossible because leaving the set is what losing the
-// record means.
-//
-// A WeakSet rather than a node field: nothing outside this module has any business reading it, and
-// a node that leaves the tree takes its entry with it.
+// Nodes of committedEachTime that have reached Fabric at least once. Asked once per node, not
+// once per node per commit — isCommitted crosses to the host, and the loop above used to pay that
+// crossing for every mounted node with afterCommit, on every commit of any surface.
+// Sound because within committedEachTime it is monotone: a node enters when its behavior attaches,
+// leaves in detachOne when torn down, and a committed live node keeps its Fabric record — so the
+// bit only ever goes true for a node still in the set. A WeakSet, since nothing else reads it.
 const everCommitted = new WeakSet();
-// `removeChild` is NOT the destroy signal, and reading it as one is the bug this indirection
-// exists to avoid. Engine-side it looks like one — a reorder goes through `detach` inside
-// appendChild/insertBefore and never lands in removeChild — but a FRAMEWORK can spell a move as
-// remove-then-reinsert. Solid does, in `solid-js/universal`: `replaceNode` (universal.cjs:186) is
-// `insertNode` + `removeNode`, and `reconcileArrays` calls it at :157 for a node that IS in the
-// new array and is needed at a later index. Its sibling call at :130 is guarded by
-// `if (!map || !map.has(a[aStart]))` and removes only genuinely absent nodes — one guarded call
-// and one not, which is why a quick read of that file says "removeChild means gone".
-//
-// Tearing down there would kill the machine of a node that returns alive a few operations later,
-// in the same batch: long-press silently stops working after certain list reorders, on device
-// only, with nothing red. So removal only nominates.
+// removeChild is NOT the destroy signal — a framework can spell a move as remove-then-reinsert
+// (Solid's replaceNode does), so tearing down here would kill the machine of a node that comes
+// back alive later in the same batch. Removal only nominates; the commit sweep decides.
 export function markDetachCandidate(node) {
     detachCandidates.add(node);
 }
-// Commit is where a removal is CHEAPEST to distinguish from a move — a node unlinked and
-// reinserted before the commit is back in the tree by now, which covers Solid's replaceNode. It is
-// NOT a proof of death, and the earlier version of this comment claimed it was. Svelte parks LIVE
-// nodes offscreen across commits and sometimes across seconds: `detachFromParent`
-// (adapters/svelte/src/dom-shim/shim-node.ts) moves a node into a DocumentFragment that has no
-// engine node, calls engineRemoveChild AND requestCommit, and Svelte fully intends to bring it
-// back — from a parked `{#if}` branch, from `each.js`'s destroy_effects, and worst, from
-// boundary.js's move_effect while a pending snippet shows, which returns when async work resolves.
-// So a sweep can and does tear down a node that comes back, which is why `attach` is re-runnable
-// (reattachHostBehaviors) rather than why the sweep tries to be cleverer. The machine RESTARTS on
-// re-insert instead of surviving an arbitrary absence; a parked subtree is offscreen, so nobody is
-// mid-gesture in it, and teardown staying unconditional means there is no leak mode.
-//
-// The subtree walk lives here rather than at removal, and is cheaper for it: only the nodes that
-// actually left are walked.
-//
-// `onDetached` runs for EVERY node of a genuinely-removed subtree, whether or not it carries a
-// behavior — it is how the engine's other per-node lifetime state (an Animated subscription, see
-// `animated/host-binding.ts`) gets the same "did it really leave" answer this sweep exists to
-// compute. Passed in for the no-cycle reason `runDeferredAttaches`' predicate is: this module must
-// keep pointing one way, and Metro's `inlineRequires` makes that a live hazard rather than taste.
-/**
- * Whether the sweep has anything to do — asked BEFORE its arguments are built.
- *
- * The sweep's own first line already returns on an empty candidate set, and that was not enough:
- * its caller passes `surface.children`, which is a GETTER that crosses to the host, allocates the
- * whole top-level list and filters it into a second array. On a surface holding four thousand rows
- * that ran on every commit, including the ones with nothing to sweep, because an argument is
- * evaluated before the guard inside the callee can decline. Same shape as the `dlog` arguments that
- * cost Angular 5-10% while emitting nothing.
- */
+// Commit is where a removal is cheapest to distinguish from a move — reinserted before the commit,
+// a node is back in the tree by now. Not a proof of death either: Svelte parks live nodes offscreen
+// across commits (a pending `{#if}`/snippet) fully intending to bring them back.
+// So a sweep can and does tear down a node that returns, which is why attach is re-runnable
+// (reattachHostBehaviors) rather than the sweep trying to be cleverer. The subtree walk lives here
+// rather than at removal, so only nodes that actually left are walked.
+// onDetached runs for every node of a genuinely-removed subtree, behavior or not — it's how other
+// per-node lifetime state (an Animated subscription) gets the same "did it really leave" answer.
+// Whether the sweep has anything to do, asked before its arguments are built: the sweep's own
+// first line already returns on an empty candidate set, but its caller passes surface.children, a
+// getter that crosses to the host and allocates — evaluated before the guard can decline.
 export function hasDetachCandidates() {
     return detachCandidates.size > 0;
 }
 export function sweepDetachedBehaviors(topLevel, onDetached) {
     if (detachCandidates.size === 0)
         return;
-    // TWO crossings for the whole sweep, whatever it is sweeping — one for the parents, one for the
-    // subtrees. Asked per node instead, a Clear of a thousand rows spent eleven thousand
-    // (`ITreeHost.parentsOf` carries the measurement).
+    // Two crossings for the whole sweep, whatever it is sweeping — one for the parents, one for the
+    // subtrees. Asked per node instead, a large clear pays one crossing per candidate instead.
     const candidates = [...detachCandidates];
     const parents = parentsOf(candidates);
-    // A surface's top-level nodes carry `parent === undefined` by design (surface.ts), and
-    // `commitChildren` re-lists them without going through appendChild — so for those the parent
-    // check alone would report a live node as gone.
+    // A surface's top-level nodes carry parent === undefined by design, and commitChildren re-lists
+    // them without going through appendChild — so the parent check alone would report them as gone.
     const left = candidates.filter((node, at) => parents[at] === undefined && !topLevel.includes(node));
-    // 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.
+    // Narrowed, and it is the sweep's whole cost: what crosses is a handle per node, and most
+    // candidates are plain views the sweep marks and does nothing else with.
     for (const node of teardownSubtreesOf(left))
         detachOne(node, onDetached);
     detachCandidates.clear();
 }
-// Tear a subtree down unconditionally — the SURFACE teardown path, where there is nothing to
-// decide: `disposeRoot` drops the root container, so every node under it has left for good whatever
-// any framework intended.
-//
-// It exists because the sweep above cannot answer this. The sweep only sees nodes a `removeChild`
-// NOMINATED, and an unmount removes nothing — the adapter drops the whole surface. So before this,
-// `disposeRoot` touched no node at all: `committedOf` reads `node.committed`, a field on the node,
-// so every node of a dead surface still answered `isCommitted` and stayed in `committedEachTime`,
-// drained on every later commit anywhere in the process, with its timers still armed.
+// Tear a subtree down unconditionally — the surface teardown path, where disposeRoot drops the
+// root container and every node under it has left for good. The sweep above can't answer this: it
+// only sees nodes removeChild nominated, and an unmount removes nothing.
 export function teardownSubtree(node, onDetached) {
     // 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.
+    // surface, so the subtree is the screen.
     for (const each of teardownSubtreesOf([node]))
         detachOne(each, onDetached);
 }
-// `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
-//                      descendant arrives twice
-//   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: 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.
-//
-// It cost a Set allocation and two hash operations per node, against a teardown that visits every
-// removed node: 10 000 of them on a 1 000-row clear. Removing it is a simplification and NOT a
-// speed-up — measured on `build-release`, the sweep stayed at 4.4-4.6 ms either way
-// (`teardown-sweep-cost.itest.ts`). Whatever holds that time is not the bookkeeping per node.
-//
-// 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 marked node has its descendants marked too, and each of them
-// takes the same early return below.
+// isTornDown guards two overlaps: a removed parent and descendant both nominated in one call, and
+// a node the sweep released that disposeRoot then walks again on an ordinary unmount. The mark is
+// raised right below the guard, so a second arrival takes the same early return.
+// The subtree arrives flat, in one host read, instead of a childrenOf recursion — both this walk
+// and reattachSubtree mark or unmark a whole subtree at once, so descendants are marked too and
+// each takes the same early return below.
 function detachOne(node, onDetached) {
     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.
+    // Marked whether or not this node carries a behavior: the mark tells a later insert to walk, and
+    // the node re-inserted is usually a plain container whose descendant holds the machine.
     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.
+    // The rest of the body is the behavior's, so a node without one leaves here — nine of every ten
+    // nodes in a removed subtree are plain views, and the mark above is the whole of what they owe.
     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
-    // changes is that a node created and torn down inside one tick stays in the Set forever, holding
-    // a strong reference to a dead subtree. A leak, not a wrong result, and this file's break-test
-    // discipline correctly reports it as unfalsifiable.
+    // Drops a deferral the node never got to run. isCommitted already stops it from firing, so this
+    // changes no observable behavior — without it, a node torn down within one tick would stay in
+    // the Set forever, holding a strong reference to a dead subtree (a leak, not a wrong result).
     awaitingCommit.delete(node);
-    // The recurring hook stops with the node, and unlike the deferral above this one has a visible
-    // consequence if forgotten: a torn-down node would keep being asked to reconcile props against a
-    // subtree that has left the tree, on every commit, forever.
+    // The recurring hook stops with the node — without this 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);
     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.
+// Re-arms a node the sweep tore down but that the framework put back. A WeakSet miss (no walk at
+// all) for every node in a freshly built tree, the common path on every create.
 export function reattachHostBehaviors(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.
+// Flat, like the detach walk, and with nothing to reconcile — always descends into every child.
 function reattachSubtree(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.
+    // Narrowed like the teardown that marked them: reattachOne acts only on a node the sweep marked.
     for (const node of teardownSubtreesOf([root]))
         reattachOne(node);
 }
@@ -531,18 +348,15 @@ function reattachOne(node) {
         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
-        // PAIR. Restore only one and a behavior that splits its setup across the two comes back
-        // half-initialised, which is the failure this seam exists to prevent.
+        // Re-arms the deferred half too, keeping attach and attachAfterCommit a pair — restoring only
+        // one would leave a split-setup behavior half-initialised on return.
         if (behavior?.attachAfterCommit !== undefined)
             awaitingCommit.add(node);
         if (behavior?.afterCommit !== undefined) {
             committedEachTime.add(node);
             node.hasCommitHook = true;
-            // A node coming back out of the park has not necessarily had a prop written since, and its
-            // mirror may have moved while it was away. Arm it once so the next commit gives it a beat —
-            // the narrowed population must not turn a RETURNING node into a silently skipped one.
+            // A returning node may not have had a prop written since, so arm it once to guarantee the
+            // next commit still gives it a beat.
             noteCommitHookNodeChanged(node);
         }
     }