@symbiote-native/test-utils 0.1.6 → 0.3.0

package/README.md

@@ -30,16 +30,21 @@ test('tap increments the counter', () => {
   const fabric = installFabric();
   mount(1, createElement(App));
 
-  const button = fabric.find((n) => n.viewName === 'RCTView' && n.props.testID === 'tap-target');
+  const button = fabric.find(
+    n => n.viewName === 'RCTView' && n.props.testID === 'tap-target',
+  );
   fabric.fireEvent(button!.instanceHandle, 'topClick', {});
 
   expect(fabric.serialize(fabric.committed)).toContain('Taps: 1');
 });
 ```
 
-Each test calls `installFabric()` fresh (or `.reset()` an existing handle between assertions in the
-same test) — the fake slot is a `globalThis` singleton, so a stale handle from a previous test would
-otherwise leak state into the next one.
+Call `installFabric()` ONCE per test file, at module scope, and `.reset()` the handle between
+tests. Do not re-install per test: the engine's `getSlot()` (`core/engine/src/fabric.ts`) reads the
+slot's methods once and caches them for the process lifetime, so a second `installFabric()` after
+anything has committed swaps the global while the engine keeps writing through the handle it
+already bound — the new recorder just stays empty, with nothing to signal why. File-level isolation
+comes from the test runner; `reset()` is what separates tests within a file.
 
 ## What `installFabric()` gives you
 
@@ -64,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()`;
@@ -78,5 +109,5 @@ test that depends on it.
 
 ## Test it
 
-This package has no tests of its own — it *is* the test double every other package's `vitest` suite
+This package has no tests of its own — it _is_ the test double every other package's `vitest` suite
 imports.

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

@@ -1,45 +1,89 @@
-// One shared fake `nativeFabricUIManager` for the unit suite. `installFabric()`
-// puts a fresh recording slot on `globalThis` and returns a handle to inspect what the
-// renderer committed. It replaces the per-file slot the smokes each copy-pasted (×65).
+// One shared fake `nativeFabricUIManager` for the unit suite. `installFabric()` puts a
+// fresh recording slot on `globalThis` and returns a handle to inspect what was committed.
 //
-// Faithful persistent (clone-on-write) semantics, identical to what the engine drives
-// against real Fabric: every clone is a NEW identity; `*NewProps` MERGES the payload onto
-// the previous props (the engine always sends a minimal diff — see `diffProps` in
-// commit.ts — and relies on native Fabric to merge it onto the retained props; a removed
-// key arrives as literal `null` and is kept as `null`, not deleted, so a test can still see
-// "explicitly reset" distinct from "never set"); the `*Children` variants reset children
-// (the engine re-appends). A persistence bug in the fake is now fixed once, here, for every
-// test, matching how the real engine's clone-on-write commit path behaves.
-// Mirrors real Fabric's clone*WithNewProps merge: `diff` is a minimal payload (only changed
-// keys, plus a removed key sent as literal `null` — kept as `null` here, not deleted, so a
-// test can tell "explicitly reset to default" apart from "never set").
+// Mirrors real Fabric's clone-on-write semantics: every clone gets a NEW identity;
+// `*NewProps` MERGES the diff onto previous props (the engine always sends a minimal diff —
+// see `diffProps` in commit.ts). A removed key arrives as literal `null` and stays `null`,
+// not deleted, so a test can tell "explicitly reset" apart from "never set". `*Children`
+// variants reset children (the engine re-appends).
+// See the header comment above for the merge/null-removal semantics this mirrors.
 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) {
             counts.createNode += 1;
-            const node = { tag, viewName, props, children: [], instanceHandle };
+            const node = {
+                tag,
+                viewName,
+                props,
+                children: [],
+                instanceHandle,
+            };
             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;
@@ -61,7 +105,9 @@ export function installFabric() {
     Object.assign(globalThis, { nativeFabricUIManager: slot });
     const serializeNode = (node) => {
         const text = node.viewName === 'RCTRawText' ? ` "${String(node.props.text)}"` : '';
-        const kids = node.children.length ? `(${node.children.map(serializeNode).join('')})` : '';
+        const kids = node.children.length
+            ? `(${node.children.map(serializeNode).join('')})`
+            : '';
         return `${node.viewName}${text}${kids}`;
     };
     return {
@@ -93,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 +1,3 @@
 export * from './fake-fabric';
+export * from './lowering-equivalence';
+export * from './wait-for';

package/build/index.js

@@ -2,3 +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

@@ -0,0 +1,11 @@
+export declare function waitUntil(condition: () => boolean, label: string, timeoutMs?: number): Promise<void>;
+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

@@ -0,0 +1,95 @@
+// Condition-based waiting, for tests that need "the framework has settled" rather than "N
+// macrotasks have elapsed".
+//
+// Nearly every suite here spells the wait as `await new Promise(r => setTimeout(r, 0))`, repeated
+// two or ten times. That is a PROXY for settling, and it holds only while the machine is idle: a
+// macrotask boundary guarantees the queue drained once, not that a batched commit, a zoneless
+// change-detection pass, or a press-timing timer has finished. Under a loaded full-suite run the
+// proxy breaks, and the failure reads as a product bug — a press that produced no event, change
+// detection that never stopped — rather than as the harness giving up early.
+//
+// Measured 2026-08-19: three tests across two adapters failed only inside a loaded `vitest run`
+// and passed in isolation, every one of them on a fixed tick count.
+//
+// Use `waitUntil` when a condition names what you are waiting for, and `waitForQuiet` when the
+// thing to wait for is the ABSENCE of further work. Do not raise a tick count to fix a flake —
+// 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() {
+    const set = Reflect.get(globalThis, 'setTimeout');
+    if (typeof set !== 'function') {
+        throw new Error('setTimeout is not available on the host');
+    }
+    return new Promise(resolve => {
+        Reflect.apply(set, globalThis, [resolve, TICK_MS]);
+    });
+}
+function now() {
+    return Date.now();
+}
+// Polls `condition` once per macrotask until it holds, then resolves. Throws on timeout with
+// `label` in the message, so a genuine product failure still fails the test — loudly, and naming
+// what never happened.
+export async function waitUntil(condition, label, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    const deadline = now() + timeoutMs;
+    while (!condition()) {
+        if (now() > deadline) {
+            throw new Error(`waitUntil timed out after ${timeoutMs}ms: ${label}`);
+        }
+        await tick();
+    }
+}
+// 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 — 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;
+    let quietSince = now();
+    while (stable < stableTicks || now() - quietSince < quietMs) {
+        await tick();
+        const current = sample();
+        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}`);
+        }
+    }
+    return last;
+}
+// Advances a fixed number of macrotasks. Kept for the cases where the wait genuinely is "let the
+// queue drain once" — a commit that is known to be one microtask away — rather than a settle.
+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.1.6",
+  "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",