@symbiote-native/test-utils 0.2.0 → 0.3.0

package/README.md

@@ -69,6 +69,32 @@ stays `null`, so a test can tell "explicitly reset" apart from "never set"), and
 throws on an illegal family reparent. A persistence bug in the fake is fixed once, here, for every
 test that depends on it.
 
+## Waiting for async settling
+
+`waitUntil(condition, label, timeoutMs?)` polls once per macrotask until `condition()` holds and
+throws (naming `label`) on timeout — the honest replacement for a fixed `setTimeout` tick count,
+which is only a proxy for "the framework has settled" and breaks under a loaded test run.
+`waitForQuiet(sample, label, stableTicks?, timeoutMs?)` waits until `sample()` returns the same
+value across `stableTicks` consecutive macrotasks and returns that settled value — the shape for
+"work has stopped arriving" (a batched commit, a zoneless change-detection pass, a press-timing
+timer). `advanceTicks(count)` is kept for the genuine "let the queue drain N times" case. Do not
+raise a tick count to fix a flaky test — that trades a fast failure for a slow one and keeps the
+race; reach for `waitUntil`/`waitForQuiet` instead.
+
+## The host-primitive lowering oracle
+
+`normalizeCommitted(nodes)` strips per-mount identity (`tag`, `instanceHandle`,
+`parentFamilyTag`) from a committed Fabric tree, and `compareLoweringEquivalence` /
+`expectCommittedProps` compare two such trees — used by React, Vue, Svelte, and Solid to mount a
+primitive (`Pressable`, `TextInput`, …) as a framework COMPONENT and as a lowered intrinsic tag
+with the same props, and assert the two committed payloads agree. It exists because a lowered
+element inherits nothing its wrapper component did — prop defaults, alias renames, and bag folds
+all live in the wrapper — so a naive lowering silently drops them (a lost `ellipsizeMode`, a
+never-applied `id -> nativeID`) with every other test green. Write BOTH assertions on every case:
+`compareLoweringEquivalence` catches a fold one path lost, `expectCommittedProps` catches a fold
+BOTH paths lost (an equivalence check alone can't tell "both arms agree" from "both arms are
+broken the same way").
+
 ## What it does NOT do
 
 - It is not a mocking framework — there's nothing to configure beyond calling `installFabric()`;

package/build/fake-fabric.d.ts

@@ -19,10 +19,19 @@ export interface IFabricRecorder {
         commandName: string;
         args: readonly unknown[];
     }>;
-    /** Call counters, for tests that assert "exactly N native nodes were created". */
+    /**
+     * Call counters, for tests that assert "exactly N native nodes were created" — and for pricing
+     * a commit's PROTOCOL half against its walk half. `appendChild` and `clone` are the two Fabric
+     * makes unavoidable: a parent whose child set changed is cloned empty and re-appends every child
+     * handle, so those counts are what a real JSI boundary would charge no matter how cheap the JS
+     * walk above them gets. Counting them here is the only way a headless run can say which half a
+     * proposed optimisation is even aimed at.
+     */
     counts: {
         createNode: number;
         completeRoot: number;
+        appendChild: number;
+        clone: number;
     };
     /**
      * RN wraps every commit in a synthetic `box-none` AppContainer root.

package/build/fake-fabric.js

@@ -10,11 +10,35 @@
 function mergeFabricProps(previous, diff) {
     return { ...previous, ...diff };
 }
+// Fabric clones keep the node's FAMILY, so a handle that already belongs to one parent can never
+// be appended under another. Enforced on both routes into a parent's child list — the append loop
+// and the batched clone — so switching between them cannot quietly drop the check.
+function assertSameFamily(parent, child) {
+    if (child.parentFamilyTag !== undefined &&
+        child.parentFamilyTag !== parent.tag) {
+        throw new Error(`Fabric family reparent: child ${child.viewName}#${child.tag} already belongs to parent #${child.parentFamilyTag}, cannot append to ${parent.viewName}#${parent.tag}`);
+    }
+}
+// `Array.isArray` narrows to `any[]`, which leaves the OTHER branch of the union un-narrowed;
+// an explicit predicate keeps both sides typed without a cast.
+function isFakeNodeList(value) {
+    return Array.isArray(value);
+}
+// A clone with no child list comes back EMPTY, exactly as the real binding does.
+function adoptChildren(parent, children) {
+    if (children === undefined)
+        return [];
+    for (const child of children) {
+        assertSameFamily(parent, child);
+        child.parentFamilyTag = parent.tag;
+    }
+    return [...children];
+}
 export function installFabric() {
     let committed = [];
     const created = [];
     const commands = [];
-    const counts = { createNode: 0, completeRoot: 0 };
+    const counts = { createNode: 0, completeRoot: 0, appendChild: 0, clone: 0 };
     let eventHandler;
     const slot = {
         createNode(tag, viewName, _rootTag, props, instanceHandle) {
@@ -29,25 +53,37 @@ export function installFabric() {
             created.push(node);
             return node;
         },
-        cloneNodeWithNewProps: (node, newProps) => ({
-            ...node,
-            props: mergeFabricProps(node.props, newProps),
-        }),
-        cloneNodeWithNewChildren: (node) => ({
-            ...node,
-            children: [],
-        }),
-        cloneNodeWithNewChildrenAndProps: (node, newProps) => ({
-            ...node,
-            props: mergeFabricProps(node.props, newProps),
-            children: [],
-        }),
+        cloneNodeWithNewProps: (node, newProps) => {
+            counts.clone += 1;
+            return { ...node, props: mergeFabricProps(node.props, newProps) };
+        },
+        // Both clone-with-children forms take the child list as an OPTIONAL trailing/second argument,
+        // mirroring UIManagerBinding.cpp: `cloneNodeWithNewChildren(node, children?)` and the 3-arg
+        // `cloneNodeWithNewChildrenAndProps(node, children, props)`. The engine probes support by
+        // ARITY, so these must keep 2 and 3 declared parameters — a default value on any of them
+        // would drop `.length` below the threshold and silently send every test down the append loop.
+        cloneNodeWithNewChildren: (node, children) => {
+            counts.clone += 1;
+            return { ...node, children: adoptChildren(node, children) };
+        },
+        cloneNodeWithNewChildrenAndProps: (node, childrenOrProps, maybeProps) => {
+            counts.clone += 1;
+            const children = isFakeNodeList(childrenOrProps)
+                ? childrenOrProps
+                : undefined;
+            const newProps = isFakeNodeList(childrenOrProps)
+                ? (maybeProps ?? {})
+                : childrenOrProps;
+            return {
+                ...node,
+                props: mergeFabricProps(node.props, newProps),
+                children: adoptChildren(node, children),
+            };
+        },
         createChildSet: () => [],
         appendChild(parent, child) {
-            if (child.parentFamilyTag !== undefined &&
-                child.parentFamilyTag !== parent.tag) {
-                throw new Error(`Fabric family reparent: child ${child.viewName}#${child.tag} already belongs to parent #${child.parentFamilyTag}, cannot append to ${parent.viewName}#${parent.tag}`);
-            }
+            counts.appendChild += 1;
+            assertSameFamily(parent, child);
             child.parentFamilyTag = parent.tag;
             parent.children.push(child);
             return parent;
@@ -103,8 +139,13 @@ export function installFabric() {
             committed = [];
             created.length = 0;
             commands.length = 0;
+            // Every counter, not a subset: `appendChild` and `clone` were left out, so any assertion
+            // on them across a reset read the PREVIOUS phase's total and could not fail. Both are now
+            // the metric that prices the clone protocol, so a stale one is a silent wrong answer.
             counts.createNode = 0;
             counts.completeRoot = 0;
+            counts.appendChild = 0;
+            counts.clone = 0;
         },
     };
 }

package/build/index.d.ts

@@ -1,2 +1,3 @@
 export * from './fake-fabric';
+export * from './lowering-equivalence';
 export * from './wait-for';

package/build/index.js

@@ -2,4 +2,5 @@
 // the co-located tests across engine, adapters, and the example apps so the fake-Fabric
 // recorder and its helpers live in exactly one place.
 export * from './fake-fabric.js';
+export * from './lowering-equivalence.js';
 export * from './wait-for.js';

package/build/lowering-equivalence.d.ts

@@ -0,0 +1,135 @@
+import type { IFakeNode } from './fake-fabric';
+/**
+ * A committed node stripped of per-mount identity. `tag`, `instanceHandle` and `parentFamilyTag`
+ * differ between two mounts of the same tree by construction, so comparing them would fail every
+ * correct adapter.
+ */
+export interface ICommittedShape {
+    viewName: string;
+    props: Record<string, unknown>;
+    children: ICommittedShape[];
+}
+export declare function normalizeCommitted(nodes: readonly IFakeNode[]): ICommittedShape[];
+/**
+ * The result of one comparison. Differences are returned rather than thrown so a caller can assert
+ * on an EMPTY ARRAY and have its runner print the whole list at once — a thrown error reports the
+ * first mismatch and hides the rest, and the interesting failures here are plural (six missing keys
+ * across three nodes was the real one).
+ */
+export interface IEquivalenceResult {
+    equal: boolean;
+    differences: string[];
+}
+/**
+ * The assertion. Compare two committed trees taken from two separate mounts of the same props.
+ *
+ * The committed tree is the right subject and the RETAINED tree is not: anchors live only in the
+ * retained tree and are exactly what lowering removes, so the two retained trees legitimately
+ * differ. A committed tree holds no anchors, so it must match exactly, `RCTRawText` children
+ * included.
+ */
+export declare function compareLoweringEquivalence(componentTree: readonly IFakeNode[], loweredTree: readonly IFakeNode[]): IEquivalenceResult;
+/**
+ * THE SECOND ASSERTION EVERY CASE OWES — an ABSOLUTE expectation, not a comparison.
+ *
+ * Find the committed node carrying `testID` and require `expected`'s keys to be present with those
+ * values. Extra keys are allowed: this asserts that a fold RAN, and pinning the whole payload would
+ * turn every unrelated prop addition into a failure here instead of in the test that owns it.
+ *
+ * Pass the value a fold PRODUCES, never the one the author wrote — `{ nativeID: 'x' }` for an
+ * authored `id="x"`, `{ ellipsizeMode: 'tail' }` for a `<Text>` that set none. An expectation
+ * restating the input passes with the fold deleted and is the same false green one level down.
+ */
+export declare function expectCommittedProps(tree: readonly IFakeNode[], testID: string, expected: Record<string, unknown>): IEquivalenceResult;
+/**
+ * THE GUARD AGAINST THE MOST LIKELY FALSE GREEN: both arms taking the SAME path.
+ *
+ * Angular is the live instance — its primitives carry a dual selector (`'symbiote-view, View'`) and
+ * directive matching is resolved per TEMPLATE, so writing the intrinsic inside a template that
+ * imports the component resolves straight back to the component, silently. The general form is any
+ * adapter where the "lowered" snippet is hand-written intrinsic markup the renderer happens to route
+ * through the wrapper anyway. Two identical arms agree perfectly and prove nothing.
+ *
+ * The discriminator here is the RETAINED tree: a component form allocates a wrapper the lowered
+ * form does not, so the counts cannot be equal.
+ *
+ * !! THAT PREMISE IS PER-ADAPTER AND IT IS FALSE ON AT LEAST TWO OF THE FIVE. Corrected 2026-09-01,
+ * after the Solid and React arms hit it independently within the hour. A component only allocates a
+ * retained node if the FRAMEWORK gives it one:
+ *
+ *     svelte    HALF TRUE, and corrected by the svelte arm the same day: it holds only for a
+ *               CHILDREN-BEARING wrapper, because the anchors are what cost the node. `Switch` and
+ *               `TextInput` render one childless element with `p={descriptor.props}` and BOTH arms
+ *               retain exactly one node — so this control fired on two correct arms before it ever
+ *               reached the two real divergences in that file
+ *     angular   a per-component host element      counts differ   -> this control holds
+ *     solid     a component is a plain function returning the same host node — MEASURED
+ *               byte-identical: {nodes:1, anchors:0, renderable:1} on both arms
+ *     react     the wrappers render the intrinsic themselves, so both arms build one node
+ *     vue       `hostComponent()` is a FunctionalComponent, so expected to match — UNMEASURED
+ *
+ * On an adapter where the counts legitimately agree this control fires on a CORRECT arm, which is
+ * worse than not having it: a control that cries wolf gets deleted, and the real guard goes with it.
+ *
+ * So each adapter owes a discriminator whose premise holds FOR IT, stated where it is used. THREE
+ * SHAPES EXIST, one per adapter family, and none is a fallback for another:
+ *
+ *     node count       this function. Holds where a component allocates a retained node —
+ *                      Svelte's anchors, Angular's per-component host. On Svelte it holds only
+ *                      for a CHILDREN-BEARING wrapper: `Switch` and `TextInput` render a single
+ *                      childless element and both arms retain one node. On ANGULAR it holds only
+ *                      for a COMPOSED component: `View`/`Text` are `SymbiotePrimitiveHost`s whose
+ *                      component IS the node, so both arms census 1.
+ *     template text    Angular's, and it exists because of the trap below. Both arms are built
+ *                      from template STRINGS, so the arm can assert that only the lowered one
+ *                      spells the intrinsic. Weaker than reading compiled output — it proves the
+ *                      author wrote two different tags, not that Angular resolved them
+ *                      differently — and it is the only thing left when no counter separates them.
+ *     source spelling  only the lowered arm names the BARE intrinsic, since a wrapper renders the
+ *                      `-managed` spelling. The strongest of the three — no runtime coincidence
+ *                      satisfies it — and available only where the arm can read its own source.
+ *     compiled output  `_$createComponent(View, …)` vs `_$createElement("symbiote-view")`. Solid's,
+ *                      because its arms are JSX compiled by the runner: there is no source to read
+ *                      at assertion time, and this is the same claim reachable from where it stands.
+ *
+ * A DISABLED discriminator can be disabled exactly where its trap lives, and only a break-test
+ * says so. Measured on Angular 2026-09-02: the node-count control was switched off for `View` and
+ * `Text` because their arms legitimately census equal — and those two are the ONLY primitives
+ * carrying the dual selector `'symbiote-view, View'`, i.e. the one construct that makes an
+ * intrinsic resolve back to its component. Handing the lowered arm its imports, which should have
+ * reproduced the trap, left all nine rows GREEN. The five rows where the control WAS active have
+ * single-name selectors and could never have shown it.
+ *
+ * So: when a control is scoped off for some members, ask whether the hazard it guards is
+ * concentrated in the members you excluded. Here it was entirely there.
+ *
+ * Do not generalise any of them into this file. Which artifact distinguishes the two paths is a fact
+ * about a framework, and this repo has a standing rule against absorbing those into shared code —
+ * a shared second control would force one answer onto five adapters, which is the mistake this
+ * correction exists to undo.
+ *
+ * THE SHAPE THAT TRANSFERS, offered as a pattern and deliberately NOT as a function here, for the
+ * reason the paragraph above gives. The one thing lowering must change on every adapter is the TAG:
+ * a wrapper renders the `-managed` spelling or a component boundary, and only the lowered path can
+ * name the bare intrinsic the spec declares. So the question each arm can ask in its own idiom is
+ * "does ONLY the lowered artifact name `HOST_PRIMITIVES[name].intrinsic`" — Svelte asks it of its
+ * two source strings, Solid of its compiled output, and an adapter with no compile step has to find
+ * its own answer. Two properties are worth keeping when you translate it: assert on the ARTIFACT
+ * rather than on runtime state, so no coincidence at mount can satisfy it, and assert the component
+ * arm does NOT name the intrinsic, or the check passes on two lowered arms.
+ *
+ * Match the tag with a boundary. `symbiote-text` is a prefix of `symbiote-text-input` and
+ * `symbiote-switch` of `symbiote-switch-managed`, so a bare substring test reads a wrapper's
+ * `-managed` output as the bare intrinsic and certifies two arms that are the same arm.
+ *
+ * Counts are passed IN rather than computed here: `censusRetainedTree` lives in the engine, and
+ * this package must not depend on it — test-utils is imported by the engine's own suite, so the
+ * edge would be a cycle. Each caller reads the census from the engine it already imports.
+ */
+export declare function assertArmsAreDistinct(componentRetainedNodes: number, loweredRetainedNodes: number): IEquivalenceResult;
+/**
+ * THE SECOND FALSE GREEN: both arms empty. `committed` is `[]` until `completeRoot` runs, and two
+ * empty trees compare equal, so a wrong flush count silently compares nothing at all. Every arm must
+ * prove it committed something before its diff is believed.
+ */
+export declare function assertCommittedSomething(tree: readonly IFakeNode[], armName: string): IEquivalenceResult;

package/build/lowering-equivalence.js

@@ -0,0 +1,224 @@
+export function normalizeCommitted(nodes) {
+    return nodes.map(node => ({
+        viewName: node.viewName,
+        props: { ...node.props },
+        children: normalizeCommitted(node.children),
+    }));
+}
+function describePath(path) {
+    return path.length === 0 ? '<root>' : path.join(' > ');
+}
+// Props are compared by KEY NAME and value, never by count. Counting is what cost a day: two arms
+// agreeing on a total while disagreeing on which keys make it up is a coincidence, not equivalence.
+//
+// `undefined` needs no special case, and adding one would HIDE a defect. `setProp` deletes a key
+// written as `undefined` and no-ops when it was never there, and `setEventListener` derives its
+// gate flag from `typeof value === 'function'` — so an absent key and an `undefined` key commit
+// identically. An adapter whose diff fails to route a disappeared key is exactly what must fail.
+function diffProps(path, component, lowered, differences) {
+    const keys = new Set([...Object.keys(component), ...Object.keys(lowered)]);
+    for (const key of [...keys].sort()) {
+        const inComponent = Object.hasOwn(component, key);
+        const inLowered = Object.hasOwn(lowered, key);
+        if (!inLowered) {
+            differences.push(`${describePath(path)}: lowered is MISSING "${key}" (component has ${JSON.stringify(component[key])}) — a fold the wrapper applied and the lowered path does not`);
+            continue;
+        }
+        if (!inComponent) {
+            differences.push(`${describePath(path)}: lowered has EXTRA "${key}" = ${JSON.stringify(lowered[key])}`);
+            continue;
+        }
+        const left = JSON.stringify(component[key]);
+        const right = JSON.stringify(lowered[key]);
+        if (left !== right) {
+            differences.push(`${describePath(path)}: "${key}" differs — component ${left}, lowered ${right}`);
+        }
+    }
+}
+function diffShapes(path, component, lowered, differences) {
+    if (component.length !== lowered.length) {
+        differences.push(`${describePath(path)}: child count differs — component ${component.length}, lowered ${lowered.length}`);
+    }
+    const count = Math.max(component.length, lowered.length);
+    for (let index = 0; index < count; index += 1) {
+        const left = component[index];
+        const right = lowered[index];
+        if (left === undefined || right === undefined)
+            continue;
+        const here = [...path, `${left.viewName}[${index}]`];
+        if (left.viewName !== right.viewName) {
+            differences.push(`${describePath(path)}: child ${index} is ${left.viewName} on the component path and ${right.viewName} on the lowered one`);
+            continue;
+        }
+        diffProps(here, left.props, right.props, differences);
+        diffShapes(here, left.children, right.children, differences);
+    }
+}
+/**
+ * The assertion. Compare two committed trees taken from two separate mounts of the same props.
+ *
+ * The committed tree is the right subject and the RETAINED tree is not: anchors live only in the
+ * retained tree and are exactly what lowering removes, so the two retained trees legitimately
+ * differ. A committed tree holds no anchors, so it must match exactly, `RCTRawText` children
+ * included.
+ */
+export function compareLoweringEquivalence(componentTree, loweredTree) {
+    const differences = [];
+    diffShapes([], normalizeCommitted(componentTree), normalizeCommitted(loweredTree), differences);
+    return { equal: differences.length === 0, differences };
+}
+/**
+ * THE SECOND ASSERTION EVERY CASE OWES — an ABSOLUTE expectation, not a comparison.
+ *
+ * Find the committed node carrying `testID` and require `expected`'s keys to be present with those
+ * values. Extra keys are allowed: this asserts that a fold RAN, and pinning the whole payload would
+ * turn every unrelated prop addition into a failure here instead of in the test that owns it.
+ *
+ * Pass the value a fold PRODUCES, never the one the author wrote — `{ nativeID: 'x' }` for an
+ * authored `id="x"`, `{ ellipsizeMode: 'tail' }` for a `<Text>` that set none. An expectation
+ * restating the input passes with the fold deleted and is the same false green one level down.
+ */
+export function expectCommittedProps(tree, testID, expected) {
+    const differences = [];
+    const found = findByTestID(tree, testID);
+    if (found === undefined) {
+        return {
+            equal: false,
+            differences: [
+                `no committed node carries testID "${testID}" — the mount did not flush, or the prop never reached the payload`,
+            ],
+        };
+    }
+    for (const key of Object.keys(expected).sort()) {
+        const actual = JSON.stringify(found.props[key]);
+        const wanted = JSON.stringify(expected[key]);
+        if (actual !== wanted) {
+            differences.push(`${testID}: "${key}" is ${actual}, expected ${wanted} — the fold that produces it did not run on this path`);
+        }
+    }
+    return { equal: differences.length === 0, differences };
+}
+function findByTestID(nodes, testID) {
+    for (const node of nodes) {
+        if (node.props.testID === testID)
+            return node;
+        const found = findByTestID(node.children, testID);
+        if (found !== undefined)
+            return found;
+    }
+    return undefined;
+}
+/**
+ * THE GUARD AGAINST THE MOST LIKELY FALSE GREEN: both arms taking the SAME path.
+ *
+ * Angular is the live instance — its primitives carry a dual selector (`'symbiote-view, View'`) and
+ * directive matching is resolved per TEMPLATE, so writing the intrinsic inside a template that
+ * imports the component resolves straight back to the component, silently. The general form is any
+ * adapter where the "lowered" snippet is hand-written intrinsic markup the renderer happens to route
+ * through the wrapper anyway. Two identical arms agree perfectly and prove nothing.
+ *
+ * The discriminator here is the RETAINED tree: a component form allocates a wrapper the lowered
+ * form does not, so the counts cannot be equal.
+ *
+ * !! THAT PREMISE IS PER-ADAPTER AND IT IS FALSE ON AT LEAST TWO OF THE FIVE. Corrected 2026-09-01,
+ * after the Solid and React arms hit it independently within the hour. A component only allocates a
+ * retained node if the FRAMEWORK gives it one:
+ *
+ *     svelte    HALF TRUE, and corrected by the svelte arm the same day: it holds only for a
+ *               CHILDREN-BEARING wrapper, because the anchors are what cost the node. `Switch` and
+ *               `TextInput` render one childless element with `p={descriptor.props}` and BOTH arms
+ *               retain exactly one node — so this control fired on two correct arms before it ever
+ *               reached the two real divergences in that file
+ *     angular   a per-component host element      counts differ   -> this control holds
+ *     solid     a component is a plain function returning the same host node — MEASURED
+ *               byte-identical: {nodes:1, anchors:0, renderable:1} on both arms
+ *     react     the wrappers render the intrinsic themselves, so both arms build one node
+ *     vue       `hostComponent()` is a FunctionalComponent, so expected to match — UNMEASURED
+ *
+ * On an adapter where the counts legitimately agree this control fires on a CORRECT arm, which is
+ * worse than not having it: a control that cries wolf gets deleted, and the real guard goes with it.
+ *
+ * So each adapter owes a discriminator whose premise holds FOR IT, stated where it is used. THREE
+ * SHAPES EXIST, one per adapter family, and none is a fallback for another:
+ *
+ *     node count       this function. Holds where a component allocates a retained node —
+ *                      Svelte's anchors, Angular's per-component host. On Svelte it holds only
+ *                      for a CHILDREN-BEARING wrapper: `Switch` and `TextInput` render a single
+ *                      childless element and both arms retain one node. On ANGULAR it holds only
+ *                      for a COMPOSED component: `View`/`Text` are `SymbiotePrimitiveHost`s whose
+ *                      component IS the node, so both arms census 1.
+ *     template text    Angular's, and it exists because of the trap below. Both arms are built
+ *                      from template STRINGS, so the arm can assert that only the lowered one
+ *                      spells the intrinsic. Weaker than reading compiled output — it proves the
+ *                      author wrote two different tags, not that Angular resolved them
+ *                      differently — and it is the only thing left when no counter separates them.
+ *     source spelling  only the lowered arm names the BARE intrinsic, since a wrapper renders the
+ *                      `-managed` spelling. The strongest of the three — no runtime coincidence
+ *                      satisfies it — and available only where the arm can read its own source.
+ *     compiled output  `_$createComponent(View, …)` vs `_$createElement("symbiote-view")`. Solid's,
+ *                      because its arms are JSX compiled by the runner: there is no source to read
+ *                      at assertion time, and this is the same claim reachable from where it stands.
+ *
+ * A DISABLED discriminator can be disabled exactly where its trap lives, and only a break-test
+ * says so. Measured on Angular 2026-09-02: the node-count control was switched off for `View` and
+ * `Text` because their arms legitimately census equal — and those two are the ONLY primitives
+ * carrying the dual selector `'symbiote-view, View'`, i.e. the one construct that makes an
+ * intrinsic resolve back to its component. Handing the lowered arm its imports, which should have
+ * reproduced the trap, left all nine rows GREEN. The five rows where the control WAS active have
+ * single-name selectors and could never have shown it.
+ *
+ * So: when a control is scoped off for some members, ask whether the hazard it guards is
+ * concentrated in the members you excluded. Here it was entirely there.
+ *
+ * Do not generalise any of them into this file. Which artifact distinguishes the two paths is a fact
+ * about a framework, and this repo has a standing rule against absorbing those into shared code —
+ * a shared second control would force one answer onto five adapters, which is the mistake this
+ * correction exists to undo.
+ *
+ * THE SHAPE THAT TRANSFERS, offered as a pattern and deliberately NOT as a function here, for the
+ * reason the paragraph above gives. The one thing lowering must change on every adapter is the TAG:
+ * a wrapper renders the `-managed` spelling or a component boundary, and only the lowered path can
+ * name the bare intrinsic the spec declares. So the question each arm can ask in its own idiom is
+ * "does ONLY the lowered artifact name `HOST_PRIMITIVES[name].intrinsic`" — Svelte asks it of its
+ * two source strings, Solid of its compiled output, and an adapter with no compile step has to find
+ * its own answer. Two properties are worth keeping when you translate it: assert on the ARTIFACT
+ * rather than on runtime state, so no coincidence at mount can satisfy it, and assert the component
+ * arm does NOT name the intrinsic, or the check passes on two lowered arms.
+ *
+ * Match the tag with a boundary. `symbiote-text` is a prefix of `symbiote-text-input` and
+ * `symbiote-switch` of `symbiote-switch-managed`, so a bare substring test reads a wrapper's
+ * `-managed` output as the bare intrinsic and certifies two arms that are the same arm.
+ *
+ * Counts are passed IN rather than computed here: `censusRetainedTree` lives in the engine, and
+ * this package must not depend on it — test-utils is imported by the engine's own suite, so the
+ * edge would be a cycle. Each caller reads the census from the engine it already imports.
+ */
+export function assertArmsAreDistinct(componentRetainedNodes, loweredRetainedNodes) {
+    if (componentRetainedNodes === loweredRetainedNodes) {
+        return {
+            equal: false,
+            differences: [
+                `both arms retained ${componentRetainedNodes} nodes — the lowered arm did not lower. ` +
+                    `Check that the intrinsic spelling is not resolving back to the component (a dual ` +
+                    `selector, or a template that still imports the wrapper).`,
+            ],
+        };
+    }
+    return { equal: true, differences: [] };
+}
+/**
+ * THE SECOND FALSE GREEN: both arms empty. `committed` is `[]` until `completeRoot` runs, and two
+ * empty trees compare equal, so a wrong flush count silently compares nothing at all. Every arm must
+ * prove it committed something before its diff is believed.
+ */
+export function assertCommittedSomething(tree, armName) {
+    const count = normalizeCommitted(tree).length;
+    return count > 0
+        ? { equal: true, differences: [] }
+        : {
+            equal: false,
+            differences: [
+                `the ${armName} arm committed nothing — the mount did not flush, so the diff below compares two empty trees`,
+            ],
+        };
+}

package/build/wait-for.d.ts

@@ -1,3 +1,11 @@
 export declare function waitUntil(condition: () => boolean, label: string, timeoutMs?: number): Promise<void>;
-export declare function waitForQuiet(sample: () => number, label: string, stableTicks?: number, timeoutMs?: number): Promise<number>;
+export interface IQuietOptions {
+    /** Consecutive macrotasks the sample must hold. */
+    readonly stableTicks?: number;
+    /** Wall time the sample must hold, so the settle does not measure machine speed. */
+    readonly quietMs?: number;
+    readonly timeoutMs?: number;
+}
+export declare function waitForQuiet(sample: () => number, label: string, options?: IQuietOptions): Promise<number>;
 export declare function advanceTicks(count: number): Promise<void>;
+export declare function advanceMs(durationMs?: number): Promise<void>;

package/build/wait-for.js

@@ -16,6 +16,12 @@
 // that trades a fast failure for a slow one and keeps the race.
 const TICK_MS = 0;
 const DEFAULT_TIMEOUT_MS = 2_000;
+// A tick count cannot express "no work arrived", only "the queue drained N times" — and how much
+// wall time that spans is a property of the machine. Measured 2026-09-02 on the FlatList window:
+// exactly one deferred commit lands 30-60 ticks after a 3-tick settle, so an idle machine declared
+// quiet before the list's own batch and a loaded one caught it. The producer is RN's VirtualizedList
+// batching period (50ms), the longest deferred one in this repo; quiet has to outlast it.
+const DEFAULT_QUIET_MS = 75;
 // Read off the host rather than imported, the same reason the engine's animations/raf.ts does:
 // this package's tsconfig carries no DOM and no Node lib, so the ambient names do not exist.
 function tick() {
@@ -42,21 +48,30 @@ export async function waitUntil(condition, label, timeoutMs = DEFAULT_TIMEOUT_MS
         await tick();
     }
 }
-// Waits until `sample` returns the same value across `stableTicks` consecutive macrotasks — the
-// shape for "work has stopped arriving". Returns the settled value so a caller can assert against
-// what actually happened rather than re-reading it.
+// Waits until `sample` stops changing — for both `stableTicks` consecutive macrotasks and
+// `quietMs` of wall time. Returns the settled value so a caller can assert against what actually
+// happened rather than re-reading it.
 //
 // This is the honest way to write a "does not free-run" test: settle FIRST on a real condition,
 // then observe. Asserting no-growth over a fixed window without settling first only tests whether
-// the machine was fast enough.
-export async function waitForQuiet(sample, label, stableTicks = 3, timeoutMs = DEFAULT_TIMEOUT_MS) {
+// the machine was fast enough — and a tick-only settle has the same defect one layer in, which is
+// why quiet is a duration here and not a count.
+export async function waitForQuiet(sample, label, options = {}) {
+    const { stableTicks = 3, quietMs = DEFAULT_QUIET_MS, timeoutMs = DEFAULT_TIMEOUT_MS, } = options;
     const deadline = now() + timeoutMs;
     let last = sample();
     let stable = 0;
-    while (stable < stableTicks) {
+    let quietSince = now();
+    while (stable < stableTicks || now() - quietSince < quietMs) {
         await tick();
         const current = sample();
-        stable = current === last ? stable + 1 : 0;
+        if (current === last) {
+            stable += 1;
+        }
+        else {
+            stable = 0;
+            quietSince = now();
+        }
         last = current;
         if (now() > deadline) {
             throw new Error(`waitForQuiet timed out after ${timeoutMs}ms, still changing: ${label}`);
@@ -70,3 +85,11 @@ export async function advanceTicks(count) {
     for (let index = 0; index < count; index += 1)
         await tick();
 }
+// Observes for a DURATION rather than a tick count. The counterpart to `waitForQuiet` for the
+// second half of a "does not free-run" test: the window in which a late producer would show up is
+// wall time, so the observation has to be too.
+export async function advanceMs(durationMs = DEFAULT_QUIET_MS) {
+    const until = now() + durationMs;
+    while (now() < until)
+        await tick();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@symbiote-native/test-utils",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Shared, framework-agnostic fake-Fabric test harness for SymbioteNative — the fake nativeFabricUIManager recorder used by the co-located test suites across the engine, every adapter, and the example apps.",
   "license": "MIT",
   "repository": {
@@ -17,6 +17,16 @@
   "main": "./build/index.js",
   "module": "./build/index.js",
   "types": "./build/index.d.ts",
+  "keywords": [
+    "react-native",
+    "symbiote-native",
+    "testing",
+    "test-utils",
+    "fabric",
+    "vitest",
+    "test-harness",
+    "mock"
+  ],
   "exports": {
     ".": {
       "types": "./build/index.d.ts",