@symbiote-native/test-utils 0.3.0 → 0.4.0

package/README.md

@@ -81,19 +81,21 @@ timer). `advanceTicks(count)` is kept for the genuine "let the queue drain N tim
 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").
+## 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
 

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,3 +1,4 @@
-export * from './fake-fabric';
-export * from './lowering-equivalence';
+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,6 +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';
-export * from './lowering-equivalence.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 {};