@symbiote-native/engine 0.5.0 → 1.0.0

package/build/tree-host.d.ts

@@ -0,0 +1,307 @@
+import type { IMeasureInWindowOnSuccess, IMeasureLayoutOnSuccess, IMeasureOnSuccess, IRootTag } from './fabric';
+import { type IMutationBatch } from './mutation-buffer';
+/** What Fabric currently holds for one node — the three fields every imperative call is aimed at. */
+export type ICommittedRecord = {
+    /**
+     * OPAQUE, and typed that way because it is: each host puts its own thing here — the native host a
+     * `ShadowNode`, a headless one whatever it committed — and the field's only contract is identity.
+     * It used to say `IFabricNode`, which promised a Fabric node from every host and was true of one.
+     * `IFabricNode` is a brand with no members, so nothing a caller could do with it is lost.
+     */
+    handle: object;
+    tag: number;
+    rootTag: IRootTag;
+};
+export interface ITreeCensus {
+    nodes: number;
+    anchors: number;
+    emptyRawTexts: number;
+    /** Nodes that actually become a Fabric view: `nodes` minus everything the commit skips. */
+    renderable: number;
+    /** children.length of every parent holding at least one skipped child, widest first. */
+    flattenWidths: number[];
+}
+/**
+ * The census of a tree nobody counted — what a host with no walk of its own answers, and what
+ * `censusRetainedTree` answers when no host is installed at all.
+ *
+ * Not exported from the package barrel: it is a HOST-author constant, and an app reading a census
+ * asserts against a mounted tree, where a zero from here cannot be mistaken for a zero from a real
+ * empty tree.
+ */
+export declare const EMPTY_CENSUS: ITreeCensus;
+/**
+ * Everything JS asks of the tree it no longer owns.
+ *
+ * No read here is on a commit path — they run at GESTURE or lifecycle rate (a host behavior seeing
+ * the props it reacts to, an app measuring a ref, a framework seam navigating what it just built).
+ * This comment used to conclude from that that the crossing cost was irrelevant, at "~10 reads per
+ * touch". Counted, it was 18 per EVENT and 19 per drag FRAME — 60 times a second for as long as a
+ * finger is down — because a gesture is not one touch and a walk that asks per level pays per
+ * level. Both are 1 now.
+ *
+ * `parentsOf`, `subtreesOf` and `ancestorsOf` are what that cost: each answers exactly what its
+ * singular twin answers, in ONE crossing, for the three walks whose size is the TREE's rather than
+ * a node's — teardown down, dispatch and responder negotiation up.
+ */
+export type ITreeHost = {
+    applyOps: (batch: IMutationBatch) => void;
+    propOf: (handle: object, key: string) => unknown;
+    propsOf: (handle: object) => Readonly<Record<string, unknown>>;
+    markPropsDirty: (handle: object) => void;
+    committedRecordOf: (handle: object) => ICommittedRecord | undefined;
+    /**
+     * A TEST read: the PAYLOAD the last commit handed Fabric for this node, `undefined` before one.
+     *
+     * It exists because the alternative reads are both blind. `Props::getDebugProps()` is a
+     * hand-written selection per component — `RCTSinglelineTextInputView` reports `testID` and nothing
+     * else — and RN's complete `Props::rawProps` needs `RN_SERIALIZABLE_STATE`, which pulls fbjni into
+     * `State` and does not compile on a host build. So the rules in `SymbioteFabricProps.cpp` were
+     * verifiable only through their TypeScript twins, which is the drift this read closes.
+     *
+     * Not on any commit path, and it adds no bookkeeping: the bag is already retained per node as the
+     * next commit's diff baseline.
+     *
+     * It answers what we SENT, not what Fabric parsed — a key no ViewConfig declares is still in here.
+     */
+    committedPayloadOf: (handle: object) => Readonly<Record<string, unknown>> | undefined;
+    parentOf: (handle: object) => object | undefined;
+    childrenOf: (handle: object) => readonly object[];
+    nextSiblingOf: (handle: object) => object | undefined;
+    parentsOf: (handles: readonly object[]) => readonly (object | undefined)[];
+    /** Each root and every descendant, PRE-ORDER, concatenated in root order. */
+    subtreesOf: (roots: readonly object[]) => readonly object[];
+    /**
+     * The node itself and every ancestor above it, DEEPEST FIRST.
+     *
+     * The upward twin of `subtreesOf`, and it exists for the same reason: a walk that asks per LEVEL
+     * pays a crossing per level. Event dispatch needs this chain for every event — capture reads it
+     * reversed, bubble reads it forward — and the responder negotiation needs it again on every frame
+     * of every drag. Measured before it existed: 18 crossings per event on a depth-8 chain, then 9
+     * once the two phases shared one walk, against the 1 an answer from here costs.
+     *
+     * A SURFACE is included, exactly as `parentOf`'s answer is — stopping at one is
+     * `host-access.ts`'s job, and it does it by reading the answer's `component`.
+     */
+    ancestorsOf: (handle: object) => readonly object[];
+    census: (roots: readonly object[]) => ITreeCensus;
+    dispatchCommand: (handle: object, commandName: string, args: readonly unknown[]) => void;
+    sendAccessibilityEvent: (handle: object, eventType: string) => void;
+    measure: (handle: object, callback: IMeasureOnSuccess) => void;
+    measureInWindow: (handle: object, callback: IMeasureInWindowOnSuccess) => void;
+    measureLayout: (handle: object, relativeTo: object, onFail: () => void, onSuccess: IMeasureLayoutOnSuccess) => void;
+    setIsJSResponder: (handle: object, isResponder: boolean, blockNativeResponder: boolean) => void;
+};
+/**
+ * Install the tree host. `installFabric()` (test-utils) calls this with the TypeScript applier; the
+ * native module installs itself the same way once its bindings carry these reads.
+ *
+ * Passing `undefined` uninstalls, so a fixture can prove a path degrades rather than throws.
+ */
+export declare function setTreeHost(next: ITreeHost | undefined): void;
+/** The installed host, or `undefined` on a runtime that has none. */
+export declare function treeHost(): ITreeHost | undefined;
+export declare function registerBeforeFlush(listener: () => void): () => void;
+/**
+ * Collect what the listeners are holding, WITHOUT draining.
+ *
+ * Separate from `flushOps` because a read may legitimately decide it needs no drain — `parentOf`
+ * skips one for a node whose placement is not pending — and skipping the drain must not also skip
+ * asking. A held write is still a write, and a reader that cannot see it is reading a stale tree.
+ */
+export declare function settleBeforeFlush(): void;
+export declare function flushOps(): void;
+/**
+ * Record a surface's commit and drain the buffer into the host.
+ *
+ * A SURFACE IS AN ANCHOR: an anchor is a node whose children belong to its parent's list, and a
+ * surface is a node whose children belong to the root child set. Same shape, which is why `OP_COMMIT`
+ * names one node and the host needs no `rootTag -> map`.
+ *
+ * `others` is every OTHER live surface, and it exists because the buffer is GLOBAL while a commit
+ * names ONE root. A framework can mutate a tree that belongs to a different surface than the one
+ * whose renderer it is holding — a portal, a tunnel, any cross-surface move — and every adapter
+ * then asks its OWN surface to commit. The ops reach the host either way, so the other surface is
+ * left correctly updated in the tree and never handed to `completeRoot`: a stale Fabric root that
+ * nothing will refresh until something unrelated dirties it. Naming every root here is what makes a
+ * commit mean "flush what changed" rather than "flush the surface I happen to be bound to".
+ *
+ * A single-surface app — every example, and the overwhelming case — passes an empty list and the
+ * behaviour is byte-identical to naming only itself.
+ */
+export declare function commitSurfaceOps(rootTag: IRootTag | undefined, surface: object, others?: readonly (readonly [IRootTag, object])[]): void;
+export interface ICommitProfile {
+    commits: number;
+    propWrites: number;
+}
+export declare function readCommitProfile(): ICommitProfile;
+export type ISurfaceTelemetry = {
+    layoutMs: number;
+    textMs: number;
+    /**
+     * `ShadowTree::commit`'s own window — and **NOT** `materialize`'s.
+     *
+     * This field's doc used to claim it was the clone-on-write walk, and F-80/F-81/F-82 each read it
+     * that way and concluded the native pipeline was too small to matter. `materialize` runs inside
+     * `kOpCommit` BEFORE `completeSurface` is called, so it is outside both this window and layout's.
+     * Pricing our own walk means timing `applyOps` from JS and subtracting these two.
+     */
+    commitMs: number;
+    layoutNodes: number;
+    textMeasures: number;
+    /**
+     * How many parents took the targeted-replace path since the last read, zeroed on read.
+     *
+     * OURS, not React Native's. It is a LIVENESS signal, not a performance one: every test in this
+     * repository stays green when `canReplaceInPlace` is off, which is how it spent eighteen months
+     * disabled. Assert it is non-zero wherever the fast path is the point of the test.
+     */
+    targetedReplaces: number;
+    /**
+     * `materialize`'s own walk, and the fields below break it down. OURS, zeroed on read.
+     *
+     * The doc above says the walk falls outside every window React Native times, which left it
+     * priceable only by subtraction — and a subtraction gives a budget, not an address. Measured
+     * 2026-09-17: ~200 ms of a 327 ms headless create sat here with nothing inside it named.
+     *
+     * `walkMs` is the single entry point in `kOpCommit`; `propsMs` / `rawPropsMs` / `createNodeMs` /
+     * `appendChildMs` / `diffPropsMs` are per-node sums inside it and do NOT add up to it — what is
+     * left over is the walk's own bookkeeping.
+     */
+    walkMs: number;
+    /** `fabricProps` alone, on both the create and the clone path. The fold LOOKUP is billed apart. */
+    propsMs: number;
+    /**
+     * Asking a node whether it carries a `payloadFold`: a JSI property read, and on a hit a
+     * `jsi::Function` allocation. The fold's own CALL is inside `propsMs`, where `fabricProps` makes
+     * it. Separated because the two answer different questions — how big the payload is, against how
+     * much the seam to JS costs to reach.
+     */
+    foldLookupMs: number;
+    /** How many nodes the lookup found one on. Zero makes `foldLookupMs` pure probe cost. */
+    foldsFound: number;
+    /**
+     * Inside a fold that runs, split three ways because a fold's CONTRACT is bag in, bag out: both
+     * conversions walk every key of the node whatever the fold actually reads. If the conversions
+     * dominate, the fix is a narrower contract; if `foldCallMs` does, the fix is not having a fold.
+     */
+    foldToJsMs: number;
+    foldCallMs: number;
+    foldFromJsMs: number;
+    /** The payload copy Fabric consumes, kept because `committedProps` is next commit's baseline. */
+    rawPropsMs: number;
+    createNodeMs: number;
+    appendChildMs: number;
+    diffPropsMs: number;
+    /** Nodes that minted a fresh Fabric family, were cloned, or were returned untouched. */
+    nodesCreated: number;
+    nodesCloned: number;
+    nodesReused: number;
+    /**
+     * `applyOps`' own decode, per created element, and its three biggest parts.
+     *
+     * A different question from the walk's. The walk asks what Fabric charges; this asks what it costs
+     * US to turn one op into one node — and the buffer architecture only pays for itself if that is
+     * well under the per-node JSI call it replaces. On `build-release` it was not, which is why these
+     * exist. `publishMs` contains `nativeStateMs`; neither contains `instanceHandleMs`.
+     */
+    decodeMs: number;
+    instanceHandleMs: number;
+    publishMs: number;
+    nativeStateMs: number;
+    nodesDecoded: number;
+    /**
+     * `kOpSetProp` and, inside it, the JS value -> `folly::dynamic` conversion.
+     *
+     * `setPropMs` skips the two early exits (deleting an absent key, and a value equal to the one
+     * standing), so it under-counts exactly the cheap paths; `propConvertMs` has no such hole.
+     */
+    setPropMs: number;
+    propConvertMs: number;
+    setProps: number;
+    /**
+     * The two `setProp` ops that changed nothing, counted apart because they are not the same waste.
+     *
+     * `deletesOfAbsent` leaves before the value conversion and costs a hash lookup. `writesOfUnchanged`
+     * leaves AFTER it, so the adapter has already paid the JSI -> `folly::dynamic` crossing for a value
+     * that changes nothing — that is the expensive one, and it is what the device benchmark's
+     * `WRITES n/m` second figure reports.
+     */
+    deletesOfAbsent: number;
+    writesOfUnchanged: number;
+    /**
+     * How well the buffer's value interning worked: entries in the batch's value table, and how many
+     * of them an op actually reached and converted.
+     *
+     * `setProps / valueEntries` is the dedup achieved. A ratio near 1 means the values are unique —
+     * which is a fact about what the caller HANDS the buffer, not about the interning: a style slot
+     * rebuilt per node arrives as a fresh reference and cannot be folded with anything.
+     */
+    valueEntries: number;
+    valueConversions: number;
+    /**
+     * `applyOps` end to end, plus the two parts of it that are neither a create nor a prop write.
+     *
+     * `applyMs` is the whole native call, so `applyMs` minus `decodeMs` / `setPropMs` /
+     * `stringDecodeMs` / `structureMs` is what the op loop itself costs — the books close here.
+     */
+    applyMs: number;
+    stringDecodeMs: number;
+    /** Every append / insert / remove op together. */
+    structureMs: number;
+    /** Inside `structureMs`: promoting a node's weak handle reference to a strong one. */
+    holdHandleMs: number;
+    /**
+     * `subtreesOf` — the batched host read the teardown sweep makes, and how many handles it returned.
+     *
+     * Not on a commit path and timed anyway: it hands JS a handle for every node in every removed
+     * subtree, which on a 1 000-row clear is ten thousand. Whether that time is the crossing or the JS
+     * loop above it decides whether the torn-down mark is worth moving into C++.
+     */
+    hostReadMs: number;
+    hostReadHandles: number;
+    /**
+     * How many times `applyOps` was entered since the last read.
+     *
+     * The string and value tables are interned PER BATCH, so a driver that flushes in many small
+     * batches cannot fold a repeated value across them. This is what distinguishes "this adapter sends
+     * more values" from "this adapter sends the same values in more batches" — two very different
+     * findings that look identical in `valueEntries` alone.
+     */
+    applyCalls: number;
+};
+/**
+ * RN's own commit telemetry for a surface THIS HOST NEED NOT HAVE DRIVEN, or `undefined` when the
+ * runtime cannot answer.
+ *
+ * It exists for one comparison and should not be reached for anything else: `readCommitProfile`
+ * accumulates inside our own commit, so it can only ever describe a tree we built, and the standing
+ * open question is whether a tree-wide text re-measure is something we cause or something a Fabric
+ * commit costs whoever drives it. Point this at a surface React Native's OWN renderer committed and
+ * the two numbers are directly comparable — same device, same RN, same tree.
+ *
+ * `undefined` rather than zeroes on a runtime without the binding, deliberately: zeroes would read
+ * as "the other renderer measures no text", which is precisely the claim under test.
+ */
+export declare function readSurfaceTelemetry(surfaceId: number): ISurfaceTelemetry | undefined;
+/**
+ * Arm the C++ half's diagnostics (`SymbioteDebug.h`), which `installBindings` already did from
+ * `DEBUG=1` / `globalThis.__SYMBIOTE_DEBUG__` at install.
+ *
+ * This is for the LATER toggle — the runtime escape hatch `debug.ts` documents for hosts where the
+ * env is not reachable. Without it a `globalThis.__SYMBIOTE_DEBUG__ = true` typed into a running app
+ * would flip the JS half and silently leave the engine's own half dark, which is the surprise worth
+ * the six lines.
+ */
+export declare function setNativeDebug(enabled: boolean): void;
+/**
+ * Drain what the C++ half has logged since the last call.
+ *
+ * The reason those lines are retained at all rather than only written to stderr: a diagnostic nobody
+ * can assert on is one that rots. This is what lets a test say "the engine warned about that" —
+ * see `core/engine/cpp/tests/js/native-debug-log.itest.ts`.
+ *
+ * An empty array on a runtime without the binding, not `undefined`: the question "what was logged"
+ * has an honest empty answer, unlike the telemetry read above, where a zero would be a false claim.
+ */
+export declare function takeNativeDebugLog(): readonly string[];

package/build/tree-host.js

@@ -0,0 +1,211 @@
+// The TREE HOST seam — the one place JS asks about a tree it does not hold.
+//
+// `@symbiote-native/engine` keeps NO tree. Every adapter mutation appends an opcode to
+// `mutation-buffer.ts`, and turning that buffer into a tree is the HOST's job: native on device, and
+// headlessly the TypeScript applier in `@symbiote-native/test-utils`, installed by `installFabric()`.
+// That applier lives there for the same reason the fake `nativeFabricUIManager` does — it is a JS
+// stand-in for a native thing, and `core/test-utils` is a devDependency of the adapters rather than a
+// runtime one, so nothing an app loads contains a JS tree.
+//
+// Shaped after `fabric.ts`'s slot seam on purpose: a resolver plus a test-time installer.
+//
+// `undefined` / empty is an ORDINARY answer from every read here, not an error — the same contract
+// `committedRecordOf` already carried. A runtime with no host, a node the host has not seen, and a
+// genuinely absent value are indistinguishable to a caller, and all three degrade.
+import { hasChangedSinceCommit, hasPendingOps, noteCommitDrained, recordCommit, takeBatch, } from './mutation-buffer.js';
+import { nativeEngine } from './native-engine.js';
+import { takePropStats } from './node.js';
+/**
+ * The census of a tree nobody counted — what a host with no walk of its own answers, and what
+ * `censusRetainedTree` answers when no host is installed at all.
+ *
+ * Not exported from the package barrel: it is a HOST-author constant, and an app reading a census
+ * asserts against a mounted tree, where a zero from here cannot be mistaken for a zero from a real
+ * empty tree.
+ */
+export const EMPTY_CENSUS = {
+    nodes: 0,
+    anchors: 0,
+    emptyRawTexts: 0,
+    renderable: 0,
+    flattenWidths: [],
+};
+let host;
+/**
+ * Install the tree host. `installFabric()` (test-utils) calls this with the TypeScript applier; the
+ * native module installs itself the same way once its bindings carry these reads.
+ *
+ * Passing `undefined` uninstalls, so a fixture can prove a path degrades rather than throws.
+ */
+export function setTreeHost(next) {
+    host = next;
+}
+/** The installed host, or `undefined` on a runtime that has none. */
+export function treeHost() {
+    return host;
+}
+/**
+ * Push everything recorded since the last apply into the host.
+ *
+ * Every READ goes through here first. A reconciler navigates the tree it is mid-way through
+ * BUILDING — Vue, Solid, Svelte and Angular all ask for a parent or a sibling between mutations and
+ * long before the commit — so a host that only learned of ops at `completeRoot` would answer about a
+ * tree several operations stale. The ops are structural, so applying them early costs nothing: only
+ * `OP_COMMIT` reaches Fabric, and one is recorded solely by `commitSurfaceOps` below, immediately
+ * before its own drain.
+ */
+/**
+ * Adapters that COALESCE writes, given the last moment to record what they are holding.
+ *
+ * An adapter cannot always publish a write the instant its framework hands it over. Angular's
+ * styling engine has no whole-value call — `ɵɵstyleMap` delivers one key per `Renderer2.setStyle`
+ * — so the renderer accumulates the run and writes RN's one `style` prop once. That accumulator has
+ * to be emptied before anything can observe the tree, and the adapter cannot know when that is: a
+ * read and a commit both arrive from elsewhere.
+ *
+ * Both of them come through `flushOps`, which is what makes this the right seam and a cheap one — it
+ * is the single door in front of every drain, `commit` included.
+ *
+ * NOT A COMMIT HOOK. It fires before every read as well, so a listener must be idempotent and must
+ * do nothing when it holds nothing. It runs BEFORE the `hasPendingOps` check on purpose: a listener
+ * holding a write has ops that are not in the buffer yet, so an empty buffer is no reason to skip it.
+ */
+const beforeFlush = new Set();
+export function registerBeforeFlush(listener) {
+    beforeFlush.add(listener);
+    return () => beforeFlush.delete(listener);
+}
+// A listener records ops, and `routeProp` can reach a read on the way — which would re-enter here
+// and ask the same listener for what it has already handed over. One flag rather than per-listener
+// bookkeeping: the whole set is being drained, and re-entering any of it is the same mistake.
+let settling = false;
+/**
+ * Collect what the listeners are holding, WITHOUT draining.
+ *
+ * Separate from `flushOps` because a read may legitimately decide it needs no drain — `parentOf`
+ * skips one for a node whose placement is not pending — and skipping the drain must not also skip
+ * asking. A held write is still a write, and a reader that cannot see it is reading a stale tree.
+ */
+export function settleBeforeFlush() {
+    if (settling || beforeFlush.size === 0)
+        return;
+    settling = true;
+    try {
+        for (const listener of beforeFlush)
+            listener();
+    }
+    finally {
+        settling = false;
+    }
+}
+export function flushOps() {
+    settleBeforeFlush();
+    if (host === undefined || !hasPendingOps())
+        return;
+    host.applyOps(takeBatch());
+}
+// Commits this window, for readCommitProfile below.
+let commits = 0;
+/**
+ * Record a surface's commit and drain the buffer into the host.
+ *
+ * A SURFACE IS AN ANCHOR: an anchor is a node whose children belong to its parent's list, and a
+ * surface is a node whose children belong to the root child set. Same shape, which is why `OP_COMMIT`
+ * names one node and the host needs no `rootTag -> map`.
+ *
+ * `others` is every OTHER live surface, and it exists because the buffer is GLOBAL while a commit
+ * names ONE root. A framework can mutate a tree that belongs to a different surface than the one
+ * whose renderer it is holding — a portal, a tunnel, any cross-surface move — and every adapter
+ * then asks its OWN surface to commit. The ops reach the host either way, so the other surface is
+ * left correctly updated in the tree and never handed to `completeRoot`: a stale Fabric root that
+ * nothing will refresh until something unrelated dirties it. Naming every root here is what makes a
+ * commit mean "flush what changed" rather than "flush the surface I happen to be bound to".
+ *
+ * A single-surface app — every example, and the overwhelming case — passes an empty list and the
+ * behaviour is byte-identical to naming only itself.
+ */
+export function commitSurfaceOps(rootTag, surface, others = []) {
+    commits += 1;
+    // No host: the ops STAY PENDING. Draining them here would be silent data loss — a surface created
+    // before a host is installed would have its own `createElement` thrown away, and the next commit
+    // that DOES reach a host names a node that host never saw. Nothing is red until then, and the
+    // throw when it comes names the commit rather than the discard.
+    //
+    // The commit op is not recorded either, for the same reason: it would sit at the head of the next
+    // batch, ahead of the creates it depends on.
+    if (host === undefined)
+        return;
+    // NOTHING TO PUBLISH — return before the host is asked to do anything.
+    //
+    // The host already declines `completeRoot` when the root child set comes back identical, but it
+    // decides that AFTER rebuilding the set: every child of the committed surface is visited to
+    // rediscover that none of them moved. Measured on the reference applier, a commit with nothing
+    // pending cost 0.0145 ms over 500 rows and 0.0822 over 4 000 — linear in the width of the surface,
+    // for a commit that publishes nothing.
+    //
+    // Who pays it: any frame where a framework re-ran an effect and produced no change, which for a
+    // reactive adapter is most frames.
+    //
+    // The post-commit hooks are NOT affected. `notifyCommitted`, `runPostCommitHooks`,
+    // `runDeferredAttaches` and the `afterCommit` drain all run in `surface.ts` AFTER this call and
+    // are deliberately not gated on the commit having made native calls — a fold that strips a prop
+    // makes its own commit byte-identical, and the hook reacting to that flip must still fire.
+    if (!hasChangedSinceCommit())
+        return;
+    for (const [otherTag, otherSurface] of others) {
+        recordCommit(otherTag, otherSurface);
+    }
+    // `undefined` means this surface no longer OWNS its root — a re-mount on the same rootTag took
+    // it. Its ops still drain, because a teardown is what carries the removals; completing the root
+    // would hand Fabric the dead surface's emptied tree over the live one's.
+    if (rootTag !== undefined)
+        recordCommit(rootTag, surface);
+    host.applyOps(takeBatch());
+    noteCommitDrained();
+}
+export function readCommitProfile() {
+    const snapshot = { commits, propWrites: takePropStats().writes };
+    commits = 0;
+    return snapshot;
+}
+/**
+ * RN's own commit telemetry for a surface THIS HOST NEED NOT HAVE DRIVEN, or `undefined` when the
+ * runtime cannot answer.
+ *
+ * It exists for one comparison and should not be reached for anything else: `readCommitProfile`
+ * accumulates inside our own commit, so it can only ever describe a tree we built, and the standing
+ * open question is whether a tree-wide text re-measure is something we cause or something a Fabric
+ * commit costs whoever drives it. Point this at a surface React Native's OWN renderer committed and
+ * the two numbers are directly comparable — same device, same RN, same tree.
+ *
+ * `undefined` rather than zeroes on a runtime without the binding, deliberately: zeroes would read
+ * as "the other renderer measures no text", which is precisely the claim under test.
+ */
+export function readSurfaceTelemetry(surfaceId) {
+    return nativeEngine()?.readSurfaceTelemetry?.(surfaceId);
+}
+/**
+ * Arm the C++ half's diagnostics (`SymbioteDebug.h`), which `installBindings` already did from
+ * `DEBUG=1` / `globalThis.__SYMBIOTE_DEBUG__` at install.
+ *
+ * This is for the LATER toggle — the runtime escape hatch `debug.ts` documents for hosts where the
+ * env is not reachable. Without it a `globalThis.__SYMBIOTE_DEBUG__ = true` typed into a running app
+ * would flip the JS half and silently leave the engine's own half dark, which is the surprise worth
+ * the six lines.
+ */
+export function setNativeDebug(enabled) {
+    nativeEngine()?.setDebugEnabled?.(enabled);
+}
+/**
+ * Drain what the C++ half has logged since the last call.
+ *
+ * The reason those lines are retained at all rather than only written to stderr: a diagnostic nobody
+ * can assert on is one that rots. This is what lets a test say "the engine warned about that" —
+ * see `core/engine/cpp/tests/js/native-debug-log.itest.ts`.
+ *
+ * An empty array on a runtime without the binding, not `undefined`: the question "what was logged"
+ * has an honest empty answer, unlike the telemetry read above, where a zero would be a false claim.
+ */
+export function takeNativeDebugLog() {
+    return nativeEngine()?.takeDebugLog?.() ?? [];
+}

package/build/view-config.js

@@ -31,10 +31,10 @@ const BASE_EVENTS = [
     'pressIn',
     'pressOut',
     // Synthesized from the touch stream like its four siblings, and omitted here until 2026-09-02.
-    // A name the press machine OWNS but the engine does not route is dead on the lowered path only:
-    // `routeProp` hands an `on*` prop to `setEventListener` (and thus to the behavior's stash) only
-    // for a registered event, so `onPressMove` landed in `node.props` where nothing reads it, while
-    // a wrapper passes the same callback to the machine directly and stayed correct.
+    // A name the press machine OWNS but the engine does not route is dead: `routeProp` hands an `on*`
+    // prop to `setEventListener` (and thus to the behavior's stash) only for a registered event, so
+    // `onPressMove` landed in `node.props` where nothing reads it. The wrapper that used to pass the
+    // same callback to the machine directly hid this.
     'pressMove',
     'longPress',
     'layout',

package/codegen-specs/NativeSymbioteEngine.ts

@@ -0,0 +1,27 @@
+// The TurboModule spec, and it exists almost entirely so that the module gets REGISTERED — the
+// capability it carries is installed by `installJSIBindingsWithRuntime:`, not by any method here.
+//
+// Why a spec at all, when nothing calls through it: `RCTTurboModuleManager` only runs the JSI-binding
+// hook when it CREATES the module, and it only creates a module some name resolves to. Codegen with
+// `ios.modulesProvider` is what puts `SymbioteEngine -> SymbioteEngineModule` into the generated
+// `RCTModuleProviders`, which is the lookup bridgeless mode actually consults. `RCT_EXPORT_MODULE`'s
+// load-time class registration is the legacy path and is not something to rely on here.
+//
+// `getVersion` is therefore not ceremony: it is the liveness probe. The JS side calls it to force
+// creation and to learn whether the binary it is talking to is old — a native module and the JS that
+// drives it ship in two different artefacts (a pod and an npm package), so they can disagree, and
+// nothing else in this repo would notice.
+//
+// This file lives OUTSIDE `src/` deliberately. `core/engine/tsconfig.json` includes only `src`, and
+// `core/engine/src` holds zero imports from `react-native` — an invariant the RN-port-elimination
+// work depends on. Codegen parses this file; nothing bundles it.
+
+import type { TurboModule } from 'react-native';
+import { TurboModuleRegistry } from 'react-native';
+
+export interface Spec extends TurboModule {
+  /** The native ABI version. Bumped whenever the host object's shape changes. */
+  getVersion(): number;
+}
+
+export default TurboModuleRegistry.getEnforcing<Spec>('SymbioteEngine');

package/cpp/SymbioteDebug.cpp

@@ -0,0 +1,51 @@
+#include "SymbioteDebug.h"
+
+#include <atomic>
+#include <cstdio>
+#include <mutex>
+
+namespace symbiote {
+namespace {
+
+std::atomic<bool> gEnabled{false};
+
+// Guarded separately from the flag: the flag is read on every call site and must stay a lock-free
+// load, while the buffer is touched only by calls that already passed the gate.
+std::mutex gMutex;
+std::vector<std::string> gLines;
+
+// A drain that never happens must not grow without bound — an app with the switch on and no test
+// reading it would otherwise retain every line for the life of the process. Oldest go first, which
+// is the right end to lose: a diagnostic is read after the thing it describes.
+constexpr size_t kMaxRetained = 512;
+
+} // namespace
+
+bool debugEnabled() {
+  return gEnabled.load(std::memory_order_relaxed);
+}
+
+void setDebugEnabled(bool enabled) {
+  gEnabled.store(enabled, std::memory_order_relaxed);
+}
+
+void debugLog(const std::string &message) {
+  const std::string line = "[symbiote] " + message;
+  // stderr rather than stdout: unbuffered by default, so a line written just before a crash is not
+  // lost with the buffer — which is the case a diagnostic is most often read for.
+  std::fputs(line.c_str(), stderr);
+  std::fputc('\n', stderr);
+
+  const std::lock_guard<std::mutex> lock(gMutex);
+  if (gLines.size() >= kMaxRetained) gLines.erase(gLines.begin());
+  gLines.push_back(line);
+}
+
+std::vector<std::string> takeDebugLog() {
+  const std::lock_guard<std::mutex> lock(gMutex);
+  std::vector<std::string> drained;
+  drained.swap(gLines);
+  return drained;
+}
+
+} // namespace symbiote

package/cpp/SymbioteDebug.h

@@ -0,0 +1,54 @@
+#pragma once
+
+#include <string>
+#include <vector>
+
+// Diagnostic logging for the C++ half of the engine — the twin of `core/engine/src/debug.ts`, and
+// until 2026-09-18 it did not exist at all.
+//
+// WHY IT HAD TO. The commit path, the payload builder and every tag rule live here now, and this
+// translation unit's only way to say anything was `throw jsi::JSError` — so a C++ rule could crash
+// or stay silent, with nothing in between. `<keep_logs_gate_behind_DEBUG>` asks new code with
+// non-trivial runtime behavior to log at its seam as a matter of course; that was unsatisfiable on
+// this side of the wire, and the first rule that wanted a developer WARNING rather than a crash
+// (ScrollView's ignored `horizontal`) is what made the gap block a port.
+//
+// THE SWITCH IS THE SAME ONE, pushed down rather than re-invented: `DEBUG=1` in the environment or
+// `globalThis.__SYMBIOTE_DEBUG__` in JS. `installBindings` reads both at install, and
+// `setDebugEnabled` is exposed so a later JS toggle reaches this side too — otherwise the runtime
+// escape hatch that exists for hosts where the env is unreachable would silently stop at the
+// boundary.
+//
+// THE MESSAGE IS BUILT ONLY WHEN THE SWITCH IS ON, and the macro is what guarantees it. C++ has the
+// same trap the JS module's header describes: an argument is evaluated at the CALL SITE, so a
+// `debugLog("x " + std::to_string(y))` on the per-node commit path costs its concatenation whether
+// or not anything is listening. `SYMBIOTE_DLOG` tests the flag first, so the expression is not
+// evaluated at all when logging is off — which makes the cheap thing the DEFAULT rather than a rule
+// every call site has to remember. Call `debugLog` directly only where the argument is already a
+// built string.
+//
+// WHERE IT GOES. stderr, so a device build surfaces it in the Xcode console and in logcat without
+// any bridge of its own. It is also RETAINED while the switch is on, which is what makes a log
+// assertable from a test rather than merely visible to a human — `takeDebugLog` drains it. Nothing
+// is retained while the switch is off, because nothing is called.
+
+namespace symbiote {
+
+/** One relaxed atomic read. The gate on every call site; see `SYMBIOTE_DLOG`. */
+bool debugEnabled();
+
+void setDebugEnabled(bool enabled);
+
+/** Prefixed, written to stderr, and retained for `takeDebugLog`. */
+void debugLog(const std::string &message);
+
+/** Drains the retained lines. The test-facing read, and the reason retention exists. */
+std::vector<std::string> takeDebugLog();
+
+} // namespace symbiote
+
+// Guards BEFORE evaluating, so building the message costs nothing with logging off.
+#define SYMBIOTE_DLOG(expr)                                                    \
+  do {                                                                         \
+    if (::symbiote::debugEnabled()) ::symbiote::debugLog((expr));              \
+  } while (false)