@symbiote-native/test-utils 0.4.3 → 0.4.5

package/build/recorded-tree.d.ts

@@ -0,0 +1,14 @@
+import { type IMutationBatch } from '@symbiote-native/engine/mutation-buffer';
+import type { IRecorded } from './recording-host';
+export type IRecordedTree = {
+    /** How many commits the ops asked for. */
+    commits: number;
+    /** Every node the ops created, in creation order, which is what `find` searches. */
+    readonly authored: IRecorded[];
+    applyOps: (batch: IMutationBatch) => void;
+    recordedOf: (handle: object) => IRecorded | undefined;
+    nodeOf: (handle: object, what: string) => IRecorded;
+    reset: () => void;
+    forget: () => void;
+};
+export declare function createRecordedTree(): IRecordedTree;

package/build/recorded-tree.js

@@ -0,0 +1,182 @@
+// The authored tree an op batch describes, and the walk that builds it. Apart from
+// `recording-host` so that file holds the `ITreeHost` surface and this one the mechanism
+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 { isSymbioteNode } from '@symbiote-native/engine';
+function 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, the moment the real engine hands every node in the walk
+// its own `ShadowNode`. Never cleared afterwards, see `IRecorded.committedRootTag`
+function markCommitted(node, rootTag) {
+    node.committedRootTag = rootTag;
+    for (const child of node.children)
+        markCommitted(child, rootTag);
+}
+function applyStructureOp(ctx, op) {
+    const { strings, instanceHandles } = ctx.batch;
+    switch (op.code) {
+        case OP_CREATE_ELEMENT:
+            // Slot 4 indexes `instanceHandles`, the object Fabric would hand back with an event, which is
+            // what a test firing one has to name
+            ctx.create(op.a, strings[op.b], {}, instanceHandles[op.d]);
+            return true;
+        case OP_CREATE_RAW_TEXT:
+            ctx.create(op.a, 'RCTRawText', { text: strings[op.b] });
+            return true;
+        case OP_CREATE_ANCHOR:
+            ctx.create(op.a, '', {});
+            return true;
+        case OP_APPEND_CHILD: {
+            const parent = ctx.at(op.a);
+            const child = ctx.at(op.b);
+            detach(child);
+            child.parent = parent;
+            parent.children.push(child);
+            return true;
+        }
+        case OP_INSERT_BEFORE: {
+            const parent = ctx.at(op.a);
+            const child = ctx.at(op.b);
+            const before = ctx.at(op.c);
+            detach(child);
+            child.parent = parent;
+            const index = parent.children.indexOf(before);
+            const landing = index < 0 ? parent.children.length : index;
+            parent.children.splice(landing, 0, child);
+            return true;
+        }
+        case OP_REMOVE_CHILD:
+            detach(ctx.at(op.b));
+            return true;
+        default:
+            return false;
+    }
+}
+// `OP_SET_TAG`, `OP_SET_OWNED_LISTENER` and `OP_SET_UNDERLAY_SHOWN` are RECORDED and not acted on,
+// т.к. what each one means is resolved in `SymbioteFabricProps.cpp`, and this host must not grow a
+// second copy of those rules. A test that needs the resolved key reads a committed payload instead
+function applyValueOp(ctx, op) {
+    const { strings, values } = ctx.batch;
+    switch (op.code) {
+        case OP_SET_PROP: {
+            const node = ctx.at(op.a);
+            if (op.c === NO_VALUE)
+                delete node.props[strings[op.b]];
+            else
+                node.props[strings[op.b]] = values[op.c];
+            return true;
+        }
+        case OP_SET_TEXT:
+            ctx.at(op.a).props.text = strings[op.b];
+            return true;
+        case OP_SET_COMPONENT:
+            ctx.at(op.a).viewName = strings[op.b];
+            return true;
+        case OP_SET_TAG:
+            ctx.at(op.a).tagName = strings[op.b];
+            return true;
+        case OP_SET_OWNED_LISTENER:
+            ctx.at(op.a).ownedListeners[strings[op.b]] = op.c !== 0;
+            return true;
+        case OP_SET_UNDERLAY_SHOWN:
+            ctx.at(op.a).underlayShown = op.b !== 0;
+            return true;
+        case OP_COMMIT:
+            ctx.onCommit(op.a, ctx.at(op.b));
+            return true;
+        default:
+            return false;
+    }
+}
+function walkBatch(ctx) {
+    const { ops } = ctx.batch;
+    for (let cursor = 0; cursor + OP_STRIDE <= ops.length; cursor += OP_STRIDE) {
+        const op = {
+            code: ops[cursor],
+            a: ops[cursor + 1],
+            b: ops[cursor + 2],
+            c: ops[cursor + 3],
+            d: ops[cursor + 4],
+        };
+        if (applyStructureOp(ctx, op))
+            continue;
+        if (applyValueOp(ctx, op))
+            continue;
+        throw new Error(`applyOps: unknown opcode ${String(op.code)}`);
+    }
+}
+function handleAt(batch, slot) {
+    const handle = batch.handles[slot];
+    if (handle === undefined) {
+        throw new Error(`applyOps: slot ${slot} is outside this batch's handles`);
+    }
+    return handle;
+}
+function newRecord(handle, viewName, props, instanceHandle) {
+    // 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');
+    }
+    return {
+        handle,
+        instanceHandle,
+        viewName,
+        tagName: '',
+        ownedListeners: {},
+        underlayShown: false,
+        props,
+        parent: undefined,
+        children: [],
+        committedRootTag: undefined,
+    };
+}
+export function createRecordedTree() {
+    let recorded = new WeakMap();
+    // A `WeakMap` cannot be enumerated and `find` has to start somewhere. Strong references, so
+    // `forget()` is what a long file calls to stop this growing
+    const authored = [];
+    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 tree = {
+        commits: 0,
+        authored,
+        recordedOf: handle => recorded.get(handle),
+        nodeOf,
+        applyOps(batch) {
+            walkBatch({
+                batch,
+                at: slot => nodeOf(handleAt(batch, slot), 'applyOps'),
+                create: (slot, viewName, props, instanceHandle) => {
+                    const node = newRecord(handleAt(batch, slot), viewName, props, instanceHandle);
+                    recorded.set(node.handle, node);
+                    authored.push(node);
+                },
+                onCommit: (rootTag, node) => {
+                    tree.commits += 1;
+                    markCommitted(node, rootTag);
+                },
+            });
+        },
+        reset() {
+            authored.length = 0;
+            tree.commits = 0;
+        },
+        forget() {
+            recorded = new WeakMap();
+            tree.reset();
+        },
+    };
+    return tree;
+}

package/build/recording-host.d.ts

@@ -17,6 +17,18 @@
  */
 import { type ISymbioteNode } from '@symbiote-native/engine';
 import type { ITreeHost } from '@symbiote-native/engine';
+export type IRecorded = {
+    handle: ISymbioteNode;
+    instanceHandle: unknown;
+    viewName: string;
+    tagName: string;
+    ownedListeners: Record<string, boolean>;
+    underlayShown: boolean;
+    props: Record<string, unknown>;
+    parent: IRecorded | undefined;
+    children: IRecorded[];
+    committedRootTag: number | undefined;
+};
 export type IRecordingHost = ITreeHost & {
     /** How many commits the engine asked for. The op stream's own count, not a tree's. */
     commits: number;

package/build/recording-host.js

@@ -15,8 +15,8 @@
  * 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';
+import { fabricProps, propsOf, setTreeHost, } from '@symbiote-native/engine';
+import { createRecordedTree } from './recorded-tree.js';
 /**
  * Install the recording host, with the minimum slot the engine insists on.
  *
@@ -65,160 +65,26 @@ export function payloadOf(node) {
  */
 const NO_TAG = -1;
 export function createRecordingHost() {
-    let recorded = new WeakMap();
+    const tree = createRecordedTree();
+    const { nodeOf } = tree;
     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 commands = [];
+    const responderHandovers = [];
+    const accessibilityEvents = [];
+    const clearRecords = () => {
+        tree.reset();
+        commands.length = 0;
+        responderHandovers.length = 0;
+        accessibilityEvents.length = 0;
     };
-    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)}`);
-                }
-            }
-        },
+    return {
+        get commits() {
+            return tree.commits;
+        },
+        commands,
+        responderHandovers,
+        accessibilityEvents,
+        applyOps: tree.applyOps,
         propOf(handle, key) {
             return nodeOf(handle, 'propOf').props[key];
         },
@@ -227,29 +93,11 @@ export function createRecordingHost() {
         },
         // 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.
-         */
+        // That the ops COMMITTED this node, and nothing more. Read off `committedRootTag` and not a
+        // live walk, т.к. `removeChild` cuts the parent link before the teardown sweep runs in the
+        // SAME commit
         committedRecordOf(handle) {
-            const node = recorded.get(handle);
+            const node = tree.recordedOf(handle);
             if (node === undefined || node.committedRootTag === undefined) {
                 return undefined;
             }
@@ -259,18 +107,9 @@ export function createRecordingHost() {
                 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.
-         */
+        // REFUSED loudly, т.к. the payload is `SymbioteFabricProps.cpp`'s and that code does not run
+        // in vitest. A test asking this belongs in `core/engine/cpp/tests/js`, where the real builder
+        // does run
         committedPayloadOf() {
             throw new Error('recording host: committedPayloadOf needs the real payload builder — move this to an itest');
         },
@@ -304,9 +143,9 @@ export function createRecordingHost() {
                 walk(nodeOf(root, 'subtreesOf'));
             return out;
         },
-        // The twin of the engine's narrowed walk, and it MUST narrow here too: the vitest suite is where
-        // the sweep's behaviour is asserted, so a recording host that handed back everything would make
-        // every one of those cases pass whatever the engine does.
+        // The twin of the engine's narrowed walk, and it MUST narrow here too: the vitest suite is
+        // where the sweep is asserted, so handing back everything would pass those cases whatever the
+        // engine does
         teardownSubtreesOf(roots) {
             const out = [];
             const walk = (node, isRoot) => {
@@ -355,7 +194,7 @@ export function createRecordingHost() {
         // 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({
+            commands.push({
                 handle,
                 viewName: nodeOf(handle, 'dispatchCommand').viewName,
                 commandName,
@@ -363,28 +202,28 @@ export function createRecordingHost() {
             });
         },
         sendAccessibilityEvent(handle, eventType) {
-            host.accessibilityEvents.push({ handle, eventType });
+            accessibilityEvents.push({ handle, eventType });
         },
         measure(_handle, _callback) { },
         measureInWindow(_handle, _callback) { },
+        // No Yoga layout runs headless, so every node reads one zero rect instead of a fake number
+        getBoundingClientRect() {
+            return { x: 0, y: 0, width: 0, height: 0 };
+        },
         measureLayout(_handle, _relativeTo, onFail, _onSuccess) {
             onFail();
         },
         setIsJSResponder(handle, isResponder, blockNativeResponder) {
-            host.responderHandovers.push({
-                handle,
-                isResponder,
-                blockNativeResponder,
-            });
+            responderHandovers.push({ handle, isResponder, blockNativeResponder });
         },
         registerEventHandler(handler) {
             eventHandler = handler;
         },
         find(predicate) {
-            return created.find(predicate);
+            return tree.authored.find(predicate);
         },
         findAll(predicate) {
-            return created.filter(predicate);
+            return tree.authored.filter(predicate);
         },
         fireEvent(handle, topLevelType, nativeEvent = {}) {
             if (eventHandler === undefined) {
@@ -392,18 +231,10 @@ export function createRecordingHost() {
             }
             eventHandler(handle, topLevelType, nativeEvent);
         },
-        reset() {
-            created = [];
-            host.commits = 0;
-            host.commands.length = 0;
-            host.responderHandovers.length = 0;
-            host.accessibilityEvents.length = 0;
-        },
+        reset: clearRecords,
         forget() {
-            recorded = new WeakMap();
-            created = [];
-            host.reset();
+            tree.forget();
+            clearRecords();
         },
     };
-    return host;
 }

package/build/wait-for.js

@@ -8,19 +8,14 @@
 // 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.
+// wall time that spans is a property of the machine. The longest deferred producer in this repo
+// is RN's VirtualizedList batching period (50ms); 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@symbiote-native/test-utils",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "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": {
@@ -40,7 +40,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@symbiote-native/engine": "1.3.0"
+    "@symbiote-native/engine": "1.4.0"
   },
   "scripts": {
     "typecheck": "tsc --build",