@symbiote-native/test-utils 0.2.0 → 0.3.1

package/README.md

@@ -69,6 +69,34 @@ 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.
+
+## Committed-payload assertions
+
+`normalizeCommitted(nodes)` strips per-mount identity (`tag`, `instanceHandle`, `parentFamilyTag`)
+from a committed Fabric tree. `expectCommittedProps(tree, testID, expected)` finds the node carrying
+`testID` and requires `expected`'s keys to be present with those values — the check that a per-
+primitive fold RAN. It exists because a bare tag inherits nothing a wrapper component used to do:
+prop defaults, alias renames and bag folds all lived in the wrapper, so one that failed to move down
+is silently dropped (a lost `ellipsizeMode`, a never-applied `id -> nativeID`) with every other test
+green.
+
+Pass the value a fold PRODUCES, never the one the author wrote — `{ nativeID: 'x' }` for an authored
+`id="x"`. An expectation restating the input passes with the fold deleted.
+
+`assertCommittedSomething(tree, name)` is the control: `committed` is `[]` until `completeRoot`
+runs, so a mount that never flushed satisfies almost anything read off it.
+
 ## What it does NOT do
 
 - It is not a mocking framework — there's nothing to configure beyond calling `installFabric()`;

package/build/host-crossings.d.ts

@@ -0,0 +1,21 @@
+/**
+ * How many times JS asked the installed tree host a question, since the last reset.
+ *
+ * Generic over any `ITreeHost` — `installFabric()`'s own `applierWalk.hostCrossings` did the same
+ * counting, but wrapped only its OWN mirror host, so a file measuring "does the dispatch code cross
+ * the host once per event, not once per ancestor" had no port to `installRecordingFabric()`. The
+ * subject here is a JS-SIDE call pattern (how many times the engine's dispatch code reaches across
+ * the host boundary), not anything about what Fabric does with the call — so it needs no committed
+ * tree and no clone protocol, only a host whose methods can be counted, which any `ITreeHost` is.
+ *
+ * `applyOps` is excluded from the count, matching the mirror's own convention: it is the mutation
+ * batch a commit carries, not a "question", and counting it would conflate two different budgets.
+ */
+import type { ITreeHost } from '@symbiote-native/engine';
+export type IHostCrossingTracker = {
+    /** Calls into the tracked host's methods (excluding `applyOps`) since the last `reset()`. */
+    crossings: number;
+    reset(): void;
+};
+/** Wraps `host`'s own methods IN PLACE, so whatever holds `host` (e.g. `setTreeHost`) sees the count. */
+export declare function trackHostCrossings(host: ITreeHost): IHostCrossingTracker;

package/build/host-crossings.js

@@ -0,0 +1,61 @@
+/**
+ * How many times JS asked the installed tree host a question, since the last reset.
+ *
+ * Generic over any `ITreeHost` — `installFabric()`'s own `applierWalk.hostCrossings` did the same
+ * counting, but wrapped only its OWN mirror host, so a file measuring "does the dispatch code cross
+ * the host once per event, not once per ancestor" had no port to `installRecordingFabric()`. The
+ * subject here is a JS-SIDE call pattern (how many times the engine's dispatch code reaches across
+ * the host boundary), not anything about what Fabric does with the call — so it needs no committed
+ * tree and no clone protocol, only a host whose methods can be counted, which any `ITreeHost` is.
+ *
+ * `applyOps` is excluded from the count, matching the mirror's own convention: it is the mutation
+ * batch a commit carries, not a "question", and counting it would conflate two different budgets.
+ */
+// The mirror's own `countingHost` (tree-applier.ts) can safely `Object.keys()` its host, because
+// the object it wraps carries ONLY these members. `installRecordingFabric()`'s host does not: it is
+// simultaneously the installed `ITreeHost` AND the test-facing API (`fireEvent`, `reset`, `commands`,
+// `find`…), all on one object, so `Object.keys` would ALSO wrap and count `fireEvent` itself —
+// measured: a 20-event budget that should read 1 crossing/event read 2, because firing the event was
+// one counted call before the dispatch code's own `ancestorsOf` added the second. Listed explicitly,
+// matching `ITreeHost` in tree-host.ts — keep the two in sync if that interface gains a member.
+const TREE_HOST_METHOD_NAMES = [
+    'applyOps',
+    'propOf',
+    'propsOf',
+    'markPropsDirty',
+    'committedRecordOf',
+    'parentOf',
+    'childrenOf',
+    'nextSiblingOf',
+    'parentsOf',
+    'subtreesOf',
+    'ancestorsOf',
+    'census',
+    'dispatchCommand',
+    'sendAccessibilityEvent',
+    'measure',
+    'measureInWindow',
+    'measureLayout',
+    'setIsJSResponder',
+];
+/** Wraps `host`'s own methods IN PLACE, so whatever holds `host` (e.g. `setTreeHost`) sees the count. */
+export function trackHostCrossings(host) {
+    const tracker = {
+        crossings: 0,
+        reset() {
+            tracker.crossings = 0;
+        },
+    };
+    for (const name of TREE_HOST_METHOD_NAMES) {
+        if (name === 'applyOps')
+            continue;
+        const member = Reflect.get(host, name);
+        if (typeof member !== 'function')
+            continue;
+        Reflect.set(host, name, (...args) => {
+            tracker.crossings += 1;
+            return Reflect.apply(member, host, args);
+        });
+    }
+    return tracker;
+}

package/build/index.d.ts

@@ -1,2 +1,4 @@
-export * from './fake-fabric';
+export { createRecordingHost, installRecordingFabric, payloadOf, type IAuthoredNode, type IRecordingHost, } from './recording-host';
+export { censusLive, createLiveTree, type ILiveCensus, type ILiveNode, type ILiveTree, } from './live-tree';
+export { trackHostCrossings, type IHostCrossingTracker, } from './host-crossings';
 export * from './wait-for';

package/build/index.js

@@ -1,5 +1,15 @@
-// @symbiote-native/test-utils: shared, framework-agnostic test harness. Imported by
-// 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';
+// @symbiote-native/test-utils: shared, framework-agnostic test harness. Imported by the co-located
+// tests across engine, adapters, and the example apps.
+//
+// The TypeScript mirror (`tree-applier.ts`/`fake-fabric.ts`, `installFabric()`) that used to stand
+// here is GONE (`.docs/mirror-elimination.md`) — every test commits into either the real C++ engine
+// (`core/engine/cpp/tests/js/*.itest.ts`, driven by `scripts/run-itests.mjs`) or
+// `installRecordingFabric()` below, which records the op stream and derives nothing.
+export { createRecordingHost, installRecordingFabric, payloadOf, } from './recording-host.js';
+// Reading the tree that is ON SCREEN over that recording — the lens for every residency question
+// (`is this still mounted`, `did the pop remove it`) that `find` cannot answer, because `find`
+// searches the creation log. Anchors flatten, as the commit walk flattens them. See its header.
+export { censusLive, createLiveTree, } from './live-tree.js';
+// How many times JS crossed the host boundary — generic over whichever host is installed.
+export { trackHostCrossings, } from './host-crossings.js';
 export * from './wait-for.js';

package/build/live-tree.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Reading the tree that is ON SCREEN, over the recording host.
+ *
+ * **This is not a second tree.** It derives nothing and decides nothing: the children come from the
+ * engine's own child links, the view name from `componentOf`, the props from `propsOf`, the payload
+ * from the engine's own `fabricProps`. It is a lens, and the reason it has to exist as one is that
+ * the obvious alternative is wrong in a way that passes.
+ *
+ * **`host.find` searches the CREATION LOG.** A recording remembers every node it ever saw created,
+ * so a node the app removed ten renders ago still answers it. Half of what a converted test asks is
+ * a residency question — a popped route, an evicted list cell, a portal toggled off — and phrased
+ * against the record, "this is gone" passes forever whatever the adapter did. Those questions walk
+ * the LIVE child links from a known root, which is what everything here does.
+ *
+ * **Anchors are FLATTENED**, the commit walk's own rule (`renderableChildren`). An anchor is
+ * structural bookkeeping nothing native ever sees, so its children stand in its place. It is not a
+ * detail on two adapters: Svelte leaves an anchor per block, Angular one per composed component,
+ * and a positional read that counts them is reading a different tree than the one it means.
+ *
+ * The one fact taken from the recording rather than the engine is `instanceHandle` — the object the
+ * engine gives Fabric per element, which `fireEvent` has to be aimed at. That is why this binds a
+ * host at all.
+ */
+import { type ISymbioteNode } from '@symbiote-native/engine';
+import type { IRecordingHost } from './recording-host';
+/** A node as it currently stands, with both of its readings and its renderable children. */
+export type ILiveNode = {
+    /** The Fabric view name it CURRENTLY resolves to — `componentOf`, not the name it was created under. */
+    viewName: string;
+    /**
+     * The INTRINSIC tag the engine was told, or `''` for a node no behavior attached to.
+     *
+     * What the host was TOLD, as against what a rule made of it — which is the only durable way to
+     * locate a node whose platform props are a tag rule in `SymbioteFabricProps.cpp`. The payload
+     * this type exposes is built by the TypeScript `fabricProps`, which deliberately carries no copy
+     * of those rules, so a locator written as `payload.<key the rule writes>` finds nothing. Several
+     * were, and expired together the day the sticky pin moved.
+     */
+    tagName: string;
+    /** The author's bag: `style` is still an object, the RN processors have not run. */
+    props: Readonly<Record<string, unknown>>;
+    /** What the engine would hand the renderer: style flattened, the aria fold and processors run. */
+    readonly payload: Record<string, unknown>;
+    handle: ISymbioteNode;
+    /** What `fireEvent` must be aimed at; `undefined` for a raw text or an anchor. */
+    instanceHandle: unknown;
+    /** The renderable children, anchors flattened. A getter, so a walk costs only what it reads. */
+    readonly children: ILiveNode[];
+};
+export type ILiveTree = {
+    /**
+     * The app's own root — one `box-none` container, the same node `installFabric`'s `appRoot()`
+     * returned. Note it is the SURFACE node, and the trees disagree about its NAME: it is created as
+     * an `RCTView` and then set to the surface component, so the recording says `RCTView`,
+     * `componentOf` says `#surface`, and Fabric commits it as `RootView`.
+     */
+    appRoot: () => ISymbioteNode;
+    /** One handle as a readable node — the entry point for a positional walk from a known root. */
+    nodeOf: (handle: ISymbioteNode) => ILiveNode;
+    /** Pre-order, the root included. */
+    walkLive: (root: ISymbioteNode, visit: (node: ILiveNode) => void) => void;
+    findAllLive: (root: ISymbioteNode, predicate: (node: ILiveNode) => boolean) => ILiveNode[];
+    findLive: (root: ISymbioteNode, predicate: (node: ILiveNode) => boolean) => ILiveNode | undefined;
+    /** A depth-indented `viewName` outline, for asserting an exact shape. */
+    outline: (root: ISymbioteNode) => string[];
+    /**
+     * The subtree as one line — `RCTView(RCTText(RCTRawText "hello"))`.
+     *
+     * Byte-compatible with the string the stand-in's own `serialize` produced, so a converted
+     * expectation does not have to be rewritten: same bracketing, same empty separator between
+     * siblings, the raw text's own string quoted after its name. It reads the FLATTENED tree, which
+     * is the right comparison — the committed tree it is being read against cannot hold an anchor.
+     */
+    serialize: (root: ISymbioteNode) => string;
+    /**
+     * Every raw text under `root`, in TREE order — what the screen currently says.
+     *
+     * Tree order is the half a search over the recording cannot give: the record is in CREATION
+     * order, and for a list that reorders its rows the two disagree without either being wrong.
+     */
+    texts: (root: ISymbioteNode) => string[];
+};
+export declare function createLiveTree(host: IRecordingHost): ILiveTree;
+/** How many nodes the adapter allocated, and how many of those are anchors. */
+export type ILiveCensus = {
+    /** Every retained node in the subtree, anchors INCLUDED. */
+    nodes: number;
+    anchors: number;
+    /** `nodes - anchors`: what the adapter allocated for something the app actually wrote. */
+    nonAnchors: number;
+};
+/**
+ * Count the retained subtree, asking no host.
+ *
+ * This replaces `censusRetainedTree` in the anchor-cost probes, and the replacement is not a
+ * convenience. `censusRetainedTree` delegates to `treeHost().census()`, which the TypeScript applier
+ * answers truthfully and NOTHING ELSE does — the native host returns zeroes deliberately (census is
+ * off the ABI, `native-tree-host.ts` says why), so a probe reading it on a device has always seen
+ * nothing. A number only the stand-in can produce is the definition of a mirror measurement.
+ *
+ * What those probes actually claim is about the ENGINE: how many nodes the adapter allocated, and
+ * how many of them are anchors. Both are read here off the engine's own child links and its own
+ * `isAnchor`, so the count means the same thing under every host.
+ *
+ * It does NOT answer the applier's `renderable`, and that is deliberate: `renderable` subtracts the
+ * empty raw texts as well, which is the COMMIT's rule and not the tree's. `empty-raw-text.itest.ts`
+ * is where that one is settled, against the real commit.
+ *
+ * The walk does not flatten anchors — it is counting them, which is the opposite of what `walkLive`
+ * is for.
+ *
+ * Variadic, because a surface holds a LIST of top-level nodes: `censusLive(...surface.children)`.
+ */
+export declare function censusLive(...roots: readonly ISymbioteNode[]): ILiveCensus;

package/build/live-tree.js

@@ -0,0 +1,135 @@
+/**
+ * Reading the tree that is ON SCREEN, over the recording host.
+ *
+ * **This is not a second tree.** It derives nothing and decides nothing: the children come from the
+ * engine's own child links, the view name from `componentOf`, the props from `propsOf`, the payload
+ * from the engine's own `fabricProps`. It is a lens, and the reason it has to exist as one is that
+ * the obvious alternative is wrong in a way that passes.
+ *
+ * **`host.find` searches the CREATION LOG.** A recording remembers every node it ever saw created,
+ * so a node the app removed ten renders ago still answers it. Half of what a converted test asks is
+ * a residency question — a popped route, an evicted list cell, a portal toggled off — and phrased
+ * against the record, "this is gone" passes forever whatever the adapter did. Those questions walk
+ * the LIVE child links from a known root, which is what everything here does.
+ *
+ * **Anchors are FLATTENED**, the commit walk's own rule (`renderableChildren`). An anchor is
+ * structural bookkeeping nothing native ever sees, so its children stand in its place. It is not a
+ * detail on two adapters: Svelte leaves an anchor per block, Angular one per composed component,
+ * and a positional read that counts them is reading a different tree than the one it means.
+ *
+ * The one fact taken from the recording rather than the engine is `instanceHandle` — the object the
+ * engine gives Fabric per element, which `fireEvent` has to be aimed at. That is why this binds a
+ * host at all.
+ */
+import { childrenOf, componentOf, fabricProps, isAnchor, propsOf, } from '@symbiote-native/engine';
+export function createLiveTree(host) {
+    const kidsOf = (handle) => childrenOf(handle).flatMap(child => isAnchor(child) ? kidsOf(child) : [child]);
+    const nodeOf = (handle) => ({
+        viewName: componentOf(handle),
+        tagName: host.find(one => one.handle === handle)?.tagName ?? '',
+        props: propsOf(handle),
+        get payload() {
+            return fabricProps(handle, propsOf(handle));
+        },
+        handle,
+        instanceHandle: host.find(one => one.handle === handle)?.instanceHandle,
+        get children() {
+            return kidsOf(handle).map(nodeOf);
+        },
+    });
+    const walkLive = (root, visit) => {
+        visit(nodeOf(root));
+        for (const child of kidsOf(root))
+            walkLive(child, visit);
+    };
+    const findAllLive = (root, predicate) => {
+        const found = [];
+        walkLive(root, node => {
+            if (predicate(node))
+                found.push(node);
+        });
+        return found;
+    };
+    return {
+        nodeOf,
+        walkLive,
+        findAllLive,
+        findLive: (root, predicate) => findAllLive(root, predicate)[0],
+        appRoot: () => {
+            const root = host.find(node => node.props.pointerEvents === 'box-none');
+            if (root === undefined)
+                throw new Error('no app root was created');
+            return root.handle;
+        },
+        serialize: (root) => {
+            const one = (handle) => {
+                const name = componentOf(handle);
+                const text = name === 'RCTRawText'
+                    ? ` "${String(fabricProps(handle, propsOf(handle)).text)}"`
+                    : '';
+                const kids = kidsOf(handle);
+                const nested = kids.length === 0 ? '' : `(${kids.map(one).join('')})`;
+                return `${name}${text}${nested}`;
+            };
+            return one(root);
+        },
+        texts: (root) => {
+            const out = [];
+            const visit = (handle) => {
+                if (componentOf(handle) === 'RCTRawText') {
+                    out.push(String(fabricProps(handle, propsOf(handle)).text));
+                }
+                for (const child of kidsOf(handle))
+                    visit(child);
+            };
+            visit(root);
+            return out;
+        },
+        outline: (root) => {
+            const lines = [];
+            const visit = (handle, depth) => {
+                lines.push(`${'  '.repeat(depth)}${componentOf(handle)}`);
+                for (const child of kidsOf(handle))
+                    visit(child, depth + 1);
+            };
+            visit(root, 0);
+            return lines;
+        },
+    };
+}
+/**
+ * Count the retained subtree, asking no host.
+ *
+ * This replaces `censusRetainedTree` in the anchor-cost probes, and the replacement is not a
+ * convenience. `censusRetainedTree` delegates to `treeHost().census()`, which the TypeScript applier
+ * answers truthfully and NOTHING ELSE does — the native host returns zeroes deliberately (census is
+ * off the ABI, `native-tree-host.ts` says why), so a probe reading it on a device has always seen
+ * nothing. A number only the stand-in can produce is the definition of a mirror measurement.
+ *
+ * What those probes actually claim is about the ENGINE: how many nodes the adapter allocated, and
+ * how many of them are anchors. Both are read here off the engine's own child links and its own
+ * `isAnchor`, so the count means the same thing under every host.
+ *
+ * It does NOT answer the applier's `renderable`, and that is deliberate: `renderable` subtracts the
+ * empty raw texts as well, which is the COMMIT's rule and not the tree's. `empty-raw-text.itest.ts`
+ * is where that one is settled, against the real commit.
+ *
+ * The walk does not flatten anchors — it is counting them, which is the opposite of what `walkLive`
+ * is for.
+ *
+ * Variadic, because a surface holds a LIST of top-level nodes: `censusLive(...surface.children)`.
+ */
+export function censusLive(...roots) {
+    let nodes = 0;
+    let anchors = 0;
+    const visit = (handle) => {
+        nodes += 1;
+        if (isAnchor(handle))
+            anchors += 1;
+        for (const child of childrenOf(handle))
+            visit(child);
+    };
+    for (const root of roots)
+        visit(root);
+    return { nodes, anchors, nonAnchors: nodes - anchors };
+}

package/build/recording-host.d.ts

@@ -0,0 +1,144 @@
+/**
+ * A tree host that RECORDS and derives nothing — for the 141 test files that never read a tree.
+ *
+ * Those files call `installFabric()` only because that is how a test gets a host at all: they
+ * assert on state machines, prop resolution, listeners, styles. Attaching them to a second
+ * implementation of Fabric's tree rules buys them nothing and costs the project a mirror.
+ *
+ * **Why this is not one.** It keeps the AUTHORED tree — who was appended to whom, what props were
+ * set — because that is what the ops literally say and what an adapter's own seam asks back
+ * (Solid's `getParentNode`, Vue's `nextSibling`, Svelte's `firstChild`). It does not decide what
+ * COMMITS: no flattening, no stacking contexts, no virtual nodes, no clone protocol, no view-name
+ * rewriting. There is no derived answer here to be wrong, which is the whole difference between
+ * recording a statement and re-deriving a conclusion.
+ *
+ * A test that needs the committed tree belongs in `core/engine/cpp/tests/js`, where React Native
+ * answers. Asking one of those questions here gets `undefined` rather than a plausible lie.
+ */
+import { type ISymbioteNode } from '@symbiote-native/engine';
+import type { ITreeHost } from '@symbiote-native/engine';
+export type IRecordingHost = ITreeHost & {
+    /** How many commits the engine asked for. The op stream's own count, not a tree's. */
+    commits: number;
+    /**
+     * The imperative calls the engine made, in order.
+     *
+     * These are the engine's own OUTPUT — it asked the platform to scroll, to focus, to take the
+     * responder — so recording them is reading what our code did, not deciding what the renderer
+     * would have done with it. The handle is the authored node, which is what a test holds.
+     */
+    commands: {
+        handle: object;
+        /** As the ops named it — the authored view name, not a committed one. */
+        viewName: string;
+        commandName: string;
+        args: readonly unknown[];
+    }[];
+    responderHandovers: {
+        handle: object;
+        isResponder: boolean;
+        blockNativeResponder: boolean;
+    }[];
+    accessibilityEvents: {
+        handle: object;
+        eventType: string;
+    }[];
+    /**
+     * Hand an event to the handler the engine registered, naming the target yourself.
+     *
+     * Not a tree read, and not the platform deciding anything: the engine installs this handler
+     * through `registerEventHandler` and this plays it back verbatim. What a REAL gesture needs —
+     * hit-testing coordinates to a target — is the renderer's answer and is not on offer here; a
+     * caller must already know which node it means, which is what an engine-side dispatch test does.
+     */
+    fireEvent: (handle: object, topLevelType: string, nativeEvent?: Record<string, unknown>) => void;
+    /** The slot call, kept here so one object owns both halves of the round trip. */
+    registerEventHandler: (handler: IEventHandler) => void;
+    /**
+     * The first AUTHORED node matching `predicate` — the handle a test needs when the adapter, not
+     * the test, created the node.
+     *
+     * **The authored tree, and the word carries the whole caveat.** These are the nodes the ops named
+     * and the props they carried; nothing here says which of them Fabric kept, what it renamed, or
+     * what it flattened away. So this answers "find the node the app wrote" — to read its props, to
+     * hand it to `fabricProps`, to fire an event at it — and it does NOT answer any question about
+     * shape. That one belongs to `committedTree()` in `core/engine/cpp/tests/js`.
+     */
+    find: (predicate: (node: IAuthoredNode) => boolean) => IAuthoredNode | undefined;
+    /** Every authored node matching `predicate`, in CREATION order — not document order. */
+    findAll: (predicate: (node: IAuthoredNode) => boolean) => IAuthoredNode[];
+    /**
+     * Clear the recordings. The authored tree survives, as it does under `installFabric`.
+     *
+     * What it also clears, and it is load-bearing: the list `find` searches. A file that mounts a
+     * fresh tree per case reuses its `testID`s, so a `find` spanning cases answers with the FIRST
+     * match — an earlier case's node, carrying an earlier case's props. Caught by a converted test
+     * whose second case read the first case's payload and reported a missing prop.
+     */
+    reset: () => void;
+    forget: () => void;
+};
+type IEventHandler = (handle: object, topLevelType: string, nativeEvent: Record<string, unknown>) => void;
+/**
+ * A node as the OPS described it. Not a committed node and not pretending to be one — there is no
+ * tag, because this host never spoke to Fabric and any number here would be an invention.
+ */
+export type IAuthoredNode = {
+    /** The engine node itself, so it can be handed straight back to the engine's own API. */
+    handle: ISymbioteNode;
+    /**
+     * The object the engine gave Fabric to hand back with an event — undefined for a raw text or an
+     * anchor, which are created with none.
+     *
+     * It is what `fireEvent` has to be aimed at: the engine's event handler resolves a target by
+     * this object, not by the node, so passing the node would silently deliver to nothing.
+     */
+    instanceHandle: unknown;
+    /** As the ops named it. Fabric may commit it under a different name; that is not known here. */
+    viewName: string;
+    /**
+     * The intrinsic tag, for a node a host behavior attached to; empty for every other node.
+     *
+     * Recorded so a test can ASK what a node is — the real host resolves a tag's platform props off
+     * it and a plain `RCTView` cannot be told from a `<pressable>` any other way. It changes nothing
+     * about the payload this host builds; see the `OP_SET_TAG` case.
+     */
+    tagName: string;
+    /**
+     * Which event names a BEHAVIOR owns currently have an app callback wired, by name.
+     *
+     * The presence only — the callback never crosses and is not here. It is what lets a platform rule
+     * resolve a key that depends on whether the app wired anything (`focusable` on a touchable is
+     * `focusable !== false && onPress !== undefined && !disabled`). Recorded for the same reason
+     * `tagName` is: so a test can ask what the host was TOLD, separately from what a rule made of it.
+     */
+    ownedListeners: Record<string, boolean>;
+    /** Whether a behavior's feedback is showing — see `OP_SET_UNDERLAY_SHOWN`. */
+    underlayShown: boolean;
+    props: Readonly<Record<string, unknown>>;
+};
+/**
+ * Install the recording host, with the minimum slot the engine insists on.
+ *
+ * `createSurface` calls `installEventHandler`, which reaches `globalThis.nativeFabricUIManager` and
+ * throws if it is absent — so a host alone is not enough to get a surface open. The slot below
+ * exists to be PRESENT: every method answers nothing except `registerEventHandler`, which hands the
+ * engine's handler to the host so `fireEvent` can play it back.
+ *
+ * What that does NOT buy is a real gesture. Deciding which node a touch lands on is hit-testing,
+ * and that is the renderer's answer; a test that needs it belongs in `core/engine/cpp/tests/js`.
+ */
+export declare function installRecordingFabric(): IRecordingHost;
+/**
+ * The Fabric payload for a node — what the engine WOULD hand the renderer for it, built by the
+ * engine's own builder rather than read off anything.
+ *
+ * This exists because the two are easy to confuse and the difference bites: a node's PROPS are the
+ * author's bag (`style` is still an object), while the PAYLOAD is what `fabricProps` makes of it —
+ * style flattened into top-level keys, the aria fold run, the ten RN processors applied. A test
+ * asking about `padding` or `accessibilityRole` or a parsed `backgroundSize` means the payload, and
+ * reading the bag instead comes back `undefined` with nothing to explain why.
+ */
+export declare function payloadOf(node: ISymbioteNode): Record<string, unknown>;
+export declare function createRecordingHost(): IRecordingHost;
+export {};

package/build/recording-host.js

@@ -0,0 +1,385 @@
+/**
+ * A tree host that RECORDS and derives nothing — for the 141 test files that never read a tree.
+ *
+ * Those files call `installFabric()` only because that is how a test gets a host at all: they
+ * assert on state machines, prop resolution, listeners, styles. Attaching them to a second
+ * implementation of Fabric's tree rules buys them nothing and costs the project a mirror.
+ *
+ * **Why this is not one.** It keeps the AUTHORED tree — who was appended to whom, what props were
+ * set — because that is what the ops literally say and what an adapter's own seam asks back
+ * (Solid's `getParentNode`, Vue's `nextSibling`, Svelte's `firstChild`). It does not decide what
+ * COMMITS: no flattening, no stacking contexts, no virtual nodes, no clone protocol, no view-name
+ * rewriting. There is no derived answer here to be wrong, which is the whole difference between
+ * recording a statement and re-deriving a conclusion.
+ *
+ * A test that needs the committed tree belongs in `core/engine/cpp/tests/js`, where React Native
+ * answers. Asking one of those questions here gets `undefined` rather than a plausible lie.
+ */
+import { NO_VALUE, OP_APPEND_CHILD, OP_COMMIT, OP_CREATE_ANCHOR, OP_CREATE_ELEMENT, OP_CREATE_RAW_TEXT, OP_INSERT_BEFORE, OP_REMOVE_CHILD, OP_SET_COMPONENT, OP_SET_OWNED_LISTENER, OP_SET_TAG, OP_SET_UNDERLAY_SHOWN, OP_SET_PROP, OP_SET_TEXT, OP_STRIDE, } from '@symbiote-native/engine/mutation-buffer';
+import { fabricProps, isSymbioteNode, propsOf, setTreeHost, } from '@symbiote-native/engine';
+/**
+ * Install the recording host, with the minimum slot the engine insists on.
+ *
+ * `createSurface` calls `installEventHandler`, which reaches `globalThis.nativeFabricUIManager` and
+ * throws if it is absent — so a host alone is not enough to get a surface open. The slot below
+ * exists to be PRESENT: every method answers nothing except `registerEventHandler`, which hands the
+ * engine's handler to the host so `fireEvent` can play it back.
+ *
+ * What that does NOT buy is a real gesture. Deciding which node a touch lands on is hit-testing,
+ * and that is the renderer's answer; a test that needs it belongs in `core/engine/cpp/tests/js`.
+ */
+export function installRecordingFabric() {
+    const host = createRecordingHost();
+    Object.assign(globalThis, {
+        nativeFabricUIManager: {
+            registerEventHandler(handler) {
+                host.registerEventHandler(handler);
+            },
+            dispatchCommand() { },
+            setIsJSResponder() { },
+            sendAccessibilityEvent() { },
+            measure() { },
+            measureInWindow() { },
+            measureLayout() { },
+        },
+    });
+    setTreeHost(host);
+    return host;
+}
+/**
+ * The Fabric payload for a node — what the engine WOULD hand the renderer for it, built by the
+ * engine's own builder rather than read off anything.
+ *
+ * This exists because the two are easy to confuse and the difference bites: a node's PROPS are the
+ * author's bag (`style` is still an object), while the PAYLOAD is what `fabricProps` makes of it —
+ * style flattened into top-level keys, the aria fold run, the ten RN processors applied. A test
+ * asking about `padding` or `accessibilityRole` or a parsed `backgroundSize` means the payload, and
+ * reading the bag instead comes back `undefined` with nothing to explain why.
+ */
+export function payloadOf(node) {
+    return fabricProps(node, propsOf(node));
+}
+/**
+ * Where a tag would be. Not a Fabric tag and not pretending to be one — this host never speaks to
+ * Fabric, so any number here would be an invention.
+ */
+const NO_TAG = -1;
+export function createRecordingHost() {
+    let recorded = new WeakMap();
+    let eventHandler;
+    // The WeakMap above cannot be enumerated, and `find` has to start somewhere. Strong references,
+    // so `forget()` is what a long file calls to stop this growing — the same deal `installFabric`'s
+    // `created` array made.
+    let created = [];
+    const nodeOf = (handle, what) => {
+        const node = recorded.get(handle);
+        if (node === undefined) {
+            throw new Error(`${what}: handle names no node in this tree`);
+        }
+        return node;
+    };
+    const detach = (node) => {
+        const { parent } = node;
+        if (parent === undefined)
+            return;
+        const at = parent.children.indexOf(node);
+        if (at >= 0)
+            parent.children.splice(at, 1);
+        node.parent = undefined;
+    };
+    // Lands a rootTag onto a whole subtree at OP_COMMIT, the same moment the real engine hands every
+    // node in the walk its own `ShadowNode`. `committedRootTag` never gets cleared afterwards, so a
+    // node removed after this still answers `committedRecordOf` — see that field's own comment.
+    const markCommitted = (node, rootTag) => {
+        node.committedRootTag = rootTag;
+        for (const child of node.children)
+            markCommitted(child, rootTag);
+    };
+    const host = {
+        commits: 0,
+        commands: [],
+        responderHandovers: [],
+        accessibilityEvents: [],
+        applyOps(batch) {
+            const { ops, strings, values, handles, instanceHandles } = batch;
+            const handleAt = (slot) => {
+                const handle = handles[slot];
+                if (handle === undefined) {
+                    throw new Error(`applyOps: slot ${slot} is outside this batch's handles`);
+                }
+                return handle;
+            };
+            const at = (slot) => nodeOf(handleAt(slot), 'applyOps');
+            const create = (slot, viewName, props, instanceHandle) => {
+                const handle = handleAt(slot);
+                // Checked rather than assumed: the batch types handles as `object`, and the whole value of
+                // holding the node is being able to hand it back to the engine's own API.
+                if (!isSymbioteNode(handle)) {
+                    throw new Error('applyOps: a handle in this batch is not an engine node');
+                }
+                const node = {
+                    handle,
+                    instanceHandle,
+                    viewName,
+                    tagName: '',
+                    ownedListeners: {},
+                    underlayShown: false,
+                    props,
+                    parent: undefined,
+                    children: [],
+                    committedRootTag: undefined,
+                };
+                recorded.set(handle, node);
+                created.push(node);
+            };
+            for (let cursor = 0; cursor + OP_STRIDE <= ops.length; cursor += OP_STRIDE) {
+                const code = ops[cursor];
+                const a = ops[cursor + 1];
+                const b = ops[cursor + 2];
+                const c = ops[cursor + 3];
+                const d = ops[cursor + 4];
+                switch (code) {
+                    case OP_CREATE_ELEMENT:
+                        // Slot 4 is the index into `instanceHandles` — the object Fabric would hand back with
+                        // an event. Recorded because it is what the op SAYS, and because a test firing an
+                        // event has to name the same object the engine registered.
+                        create(a, strings[b], {}, instanceHandles[d]);
+                        break;
+                    case OP_CREATE_RAW_TEXT:
+                        create(a, 'RCTRawText', { text: strings[b] });
+                        break;
+                    case OP_CREATE_ANCHOR:
+                        create(a, '', {});
+                        break;
+                    case OP_APPEND_CHILD: {
+                        const child = at(b);
+                        detach(child);
+                        child.parent = at(a);
+                        at(a).children.push(child);
+                        break;
+                    }
+                    case OP_INSERT_BEFORE: {
+                        const parent = at(a);
+                        const child = at(b);
+                        const before = at(c);
+                        detach(child);
+                        child.parent = parent;
+                        const index = parent.children.indexOf(before);
+                        parent.children.splice(index < 0 ? parent.children.length : index, 0, child);
+                        break;
+                    }
+                    case OP_REMOVE_CHILD:
+                        detach(at(b));
+                        break;
+                    case OP_SET_PROP: {
+                        const node = at(a);
+                        if (c === NO_VALUE)
+                            delete node.props[strings[b]];
+                        else
+                            node.props[strings[b]] = values[c];
+                        break;
+                    }
+                    case OP_SET_TEXT:
+                        at(a).props.text = strings[b];
+                        break;
+                    case OP_SET_COMPONENT:
+                        at(a).viewName = strings[b];
+                        break;
+                    // RECORDED AND NOT ACTED ON, deliberately. The real host resolves a tag's platform props
+                    // off this (`foldPressableProps`); this host builds its payload through the TypeScript
+                    // `fabricProps`, which carries no copy of those rules and must not grow one — a second
+                    // implementation is how a test goes green over a rule that no longer runs. A test that
+                    // needs to read what a tag actually sends belongs in `core/engine/cpp/tests/js`.
+                    case OP_SET_TAG:
+                        at(a).tagName = strings[b];
+                        break;
+                    // RECORDED, NOT APPLIED, exactly like the tag above. The real host resolves `focusable`'s
+                    // three-leg touchable form off this bit; this host builds its payload through the
+                    // TypeScript `fabricProps`, which carries no copy of the tag rules and must not grow one.
+                    // So a test that wants the resolved key reads the committed payload in an itest, and what
+                    // this records is the fact a test can ASK about.
+                    case OP_SET_OWNED_LISTENER:
+                        at(a).ownedListeners[strings[b]] = c !== 0;
+                        break;
+                    // Same treatment, and for the same reason: the real host paints TouchableHighlight's
+                    // underlay from this bit (`foldTouchableHighlightUnderlay`), and this one must not grow a
+                    // copy of that rule. Recorded so a test can ask whether the MACHINE flipped it — which is
+                    // the half that is still JS — while what the flip LOOKS like is asserted on a committed
+                    // payload in `core/engine/cpp/tests/js/touchable-highlight-underlay.itest.ts`.
+                    case OP_SET_UNDERLAY_SHOWN:
+                        at(a).underlayShown = b !== 0;
+                        break;
+                    case OP_COMMIT: {
+                        host.commits += 1;
+                        markCommitted(at(b), a);
+                        break;
+                    }
+                    default:
+                        throw new Error(`applyOps: unknown opcode ${String(code)}`);
+                }
+            }
+        },
+        propOf(handle, key) {
+            return nodeOf(handle, 'propOf').props[key];
+        },
+        propsOf(handle) {
+            return nodeOf(handle, 'propsOf').props;
+        },
+        // Nothing is memoized here, so there is nothing to invalidate.
+        markPropsDirty() { },
+        /**
+         * A record for a node standing under a surface the ops COMMITTED, and nothing more.
+         *
+         * The engine gates every imperative call on this, so answering `undefined` always would make
+         * `dispatchCommand` unreachable and quietly turn four command tests green-by-absence. What is
+         * answered here is read straight off the op stream — there WAS a commit, and this node is under
+         * that surface — with no claim about what the renderer did with it: no tag Fabric minted, no
+         * view that survived flattening, no guarantee it is mounted. A test that needs any of those
+         * belongs in `core/engine/cpp/tests/js`.
+         *
+         * `handle` is the authored node and `tag` is `NO_TAG`, so a test reading either gets something
+         * obviously not-from-Fabric rather than a plausible number. `rootTag` is real, not invented —
+         * see `IRecorded.committedRootTag`'s own comment for why the JS-level surface identifier is a
+         * different unknown from the native Fabric tag.
+         *
+         * Read off `committedRootTag` (set once per node at the commit that landed it, never cleared),
+         * not a live walk to a committed root — `removeChild` cuts the parent link before a behavior's
+         * teardown sweep runs in the SAME commit, so a walk answers `undefined` for exactly the node a
+         * parting write (`TextInput`'s unmount blur) needs to still reach. `node->committed` in the real
+         * engine works the same way, and for the same reason.
+         */
+        committedRecordOf(handle) {
+            const node = recorded.get(handle);
+            if (node === undefined || node.committedRootTag === undefined) {
+                return undefined;
+            }
+            return {
+                handle,
+                tag: NO_TAG,
+                rootTag: node.committedRootTag,
+            };
+        },
+        /**
+         * REFUSED, loudly, and that is the whole point of implementing it here.
+         *
+         * This host records the OPS it was handed; it never builds a Fabric payload, because building
+         * one is `SymbioteFabricProps.cpp`'s job and that code does not exist in a vitest process. An
+         * answer synthesised from the JS twin would be a test asserting against the wrong
+         * implementation — the exact drift `ITreeHost.committedPayloadOf` was added to close.
+         *
+         * So a test asking this question belongs in `core/engine/cpp/tests/js/` (`pnpm run test:itest`),
+         * where the real builder runs. `.props` on this host stays the read for "what did the adapter
+         * SAY", which is a different and still-useful question.
+         */
+        committedPayloadOf() {
+            throw new Error('recording host: committedPayloadOf needs the real payload builder — move this to an itest');
+        },
+        parentOf(handle) {
+            return nodeOf(handle, 'parentOf').parent?.handle;
+        },
+        childrenOf(handle) {
+            return nodeOf(handle, 'childrenOf').children.map(child => child.handle);
+        },
+        nextSiblingOf(handle) {
+            const node = nodeOf(handle, 'nextSiblingOf');
+            const siblings = node.parent?.children;
+            if (siblings === undefined)
+                return undefined;
+            return siblings[siblings.indexOf(node) + 1]?.handle;
+        },
+        parentsOf(handles) {
+            return handles.map(handle => nodeOf(handle, 'parentsOf').parent?.handle);
+        },
+        subtreesOf(roots) {
+            const out = [];
+            const walk = (node) => {
+                out.push(node.handle);
+                for (const child of node.children)
+                    walk(child);
+            };
+            for (const root of roots)
+                walk(nodeOf(root, 'subtreesOf'));
+            return out;
+        },
+        ancestorsOf(handle) {
+            const chain = [];
+            for (let node = nodeOf(handle, 'ancestorsOf'); node !== undefined; node = node.parent) {
+                chain.push(node.handle);
+            }
+            return chain;
+        },
+        census(roots) {
+            let nodes = 0;
+            const walk = (node) => {
+                nodes += 1;
+                for (const child of node.children)
+                    walk(child);
+            };
+            for (const root of roots)
+                walk(nodeOf(root, 'census'));
+            // The skip counts belong to the commit rules, which this host does not have. Zero is the
+            // honest answer: nothing here was skipped, because nothing here was decided.
+            return {
+                nodes,
+                anchors: 0,
+                emptyRawTexts: 0,
+                renderable: nodes,
+                flattenWidths: [],
+            };
+        },
+        // The imperative six ask the PLATFORM — a frame, a gesture, an announcement. Three of them
+        // carry a request the engine MADE, so they are recorded; the measuring three want an answer
+        // only a platform has, and there is none here.
+        dispatchCommand(handle, commandName, args) {
+            host.commands.push({
+                handle,
+                viewName: nodeOf(handle, 'dispatchCommand').viewName,
+                commandName,
+                args,
+            });
+        },
+        sendAccessibilityEvent(handle, eventType) {
+            host.accessibilityEvents.push({ handle, eventType });
+        },
+        measure(_handle, _callback) { },
+        measureInWindow(_handle, _callback) { },
+        measureLayout(_handle, _relativeTo, onFail, _onSuccess) {
+            onFail();
+        },
+        setIsJSResponder(handle, isResponder, blockNativeResponder) {
+            host.responderHandovers.push({
+                handle,
+                isResponder,
+                blockNativeResponder,
+            });
+        },
+        registerEventHandler(handler) {
+            eventHandler = handler;
+        },
+        find(predicate) {
+            return created.find(predicate);
+        },
+        findAll(predicate) {
+            return created.filter(predicate);
+        },
+        fireEvent(handle, topLevelType, nativeEvent = {}) {
+            if (eventHandler === undefined) {
+                throw new Error('no event handler registered by the renderer');
+            }
+            eventHandler(handle, topLevelType, nativeEvent);
+        },
+        reset() {
+            created = [];
+            host.commits = 0;
+            host.commands.length = 0;
+            host.responderHandovers.length = 0;
+            host.accessibilityEvents.length = 0;
+        },
+        forget() {
+            recorded = new WeakMap();
+            created = [];
+            host.reset();
+        },
+    };
+    return host;
+}

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.1",
   "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",
@@ -29,6 +39,9 @@
   "publishConfig": {
     "access": "public"
   },
+  "dependencies": {
+    "@symbiote-native/engine": "1.0.0"
+  },
   "scripts": {
     "typecheck": "tsc --build",
     "format": "prettier --write \"src/**/*.{ts,tsx}\""

package/build/fake-fabric.d.ts

@@ -1,42 +0,0 @@
-export interface IFakeNode {
-    tag: number;
-    viewName: string;
-    props: Record<string, unknown>;
-    children: IFakeNode[];
-    instanceHandle: unknown;
-    /** Fabric family parent. Clones keep the same tag/family, so reparenting a family is illegal. */
-    parentFamilyTag?: number;
-}
-export type IEventHandler = (instanceHandle: unknown, topLevelType: string, nativeEvent: Record<string, unknown>) => void;
-export interface IFabricRecorder {
-    /** The child set handed to the most recent `completeRoot`. */
-    committed: IFakeNode[];
-    /** Every node ever `createNode`'d this run (clones excluded). */
-    created: IFakeNode[];
-    /** Every imperative command dispatched at a committed Fabric node. */
-    commands: Array<{
-        node: IFakeNode;
-        commandName: string;
-        args: readonly unknown[];
-    }>;
-    /** Call counters, for tests that assert "exactly N native nodes were created". */
-    counts: {
-        createNode: number;
-        completeRoot: number;
-    };
-    /**
-     * RN wraps every commit in a synthetic `box-none` AppContainer root.
-     * Returns it, asserting it is the single expected root, so each test unwraps the
-     * AppContainer the same way instead of re-checking the invariant by hand.
-     */
-    appRoot(): IFakeNode;
-    /** Find the first `createNode`'d node matching a predicate (e.g. the app's own View). */
-    find(predicate: (node: IFakeNode) => boolean): IFakeNode | undefined;
-    /** Deliver a native event to the renderer's registered handler. */
-    fireEvent(handle: unknown, topLevelType: string, nativeEvent?: Record<string, unknown>): void;
-    /** Serialize a node list to `RCTView(RCTText(RCTRawText "text"))` shorthand. */
-    serialize(nodes: IFakeNode[]): string;
-    /** Zero the counters and clear `committed` / `created` (the event handler survives). */
-    reset(): void;
-}
-export declare function installFabric(): IFabricRecorder;

package/build/fake-fabric.js

@@ -1,110 +0,0 @@
-// 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.
-//
-// 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 };
-}
-export function installFabric() {
-    let committed = [];
-    const created = [];
-    const commands = [];
-    const counts = { createNode: 0, completeRoot: 0 };
-    let eventHandler;
-    const slot = {
-        createNode(tag, viewName, _rootTag, props, instanceHandle) {
-            counts.createNode += 1;
-            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: [],
-        }),
-        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}`);
-            }
-            child.parentFamilyTag = parent.tag;
-            parent.children.push(child);
-            return parent;
-        },
-        appendChildToSet(childSet, child) {
-            childSet.push(child);
-        },
-        completeRoot(_rootTag, childSet) {
-            counts.completeRoot += 1;
-            committed = childSet;
-        },
-        registerEventHandler(handler) {
-            eventHandler = handler;
-        },
-        dispatchCommand(node, commandName, args) {
-            commands.push({ node, commandName, args });
-        },
-    };
-    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('')})`
-            : '';
-        return `${node.viewName}${text}${kids}`;
-    };
-    return {
-        get committed() {
-            return committed;
-        },
-        created,
-        commands,
-        counts,
-        appRoot() {
-            const root = committed[0];
-            if (committed.length !== 1 || root?.props.pointerEvents !== 'box-none') {
-                throw new Error(`expected a single box-none AppContainer root, got ${committed.length} node(s)`);
-            }
-            return root;
-        },
-        find(predicate) {
-            return created.find(predicate);
-        },
-        fireEvent(handle, topLevelType, nativeEvent = {}) {
-            if (!eventHandler)
-                throw new Error('no event handler registered by the renderer');
-            eventHandler(handle, topLevelType, nativeEvent);
-        },
-        serialize(nodes) {
-            return nodes.map(serializeNode).join('');
-        },
-        reset() {
-            committed = [];
-            created.length = 0;
-            commands.length = 0;
-            counts.createNode = 0;
-            counts.completeRoot = 0;
-        },
-    };
-}