@symbiote-native/engine 1.3.0 → 1.4.0

package/build/native-engine.d.ts

@@ -1,62 +1,10 @@
 import type { ICommittedRecord } from './tree-host';
-/**
- * The ABI this file knows how to talk to. A binary reporting anything else is refused outright rather
- * than probed method by method — the two artefacts ship separately (a pod and an npm package), so
- * disagreement is routine, and a partial match is the shape that corrupts memory quietly.
- *
- * Exported for the tests, which must DERIVE their supported and unsupported arms from it rather than
- * restate the number: a bump that leaves a fixture behind reads as "the binary is stale", which is
- * exactly the message this constant exists to produce, so the failure looks like the feature working.
- */
 export declare const SUPPORTED_NATIVE_VERSION = 4;
-/**
- * What `installJSIBindingsWithRuntime:` puts on the global.
- *
- * `allocInt32Array` hands back a view over memory NATIVE owns — not a copy — which is the only reason
- * any of this exists. Every other route from JS to native structure costs a JSI crossing per element,
- * and the census that sized this design counted ~4 000 reads for a two-row swap.
- */
 export type INativeEngineBindings = {
     version: number;
     allocInt32Array: (lengthInElements: number) => Int32Array;
-    /**
-     * Item 8c-1's bring-up probe: shadow trees the real `UIManager` holds, or -1 when we could not
-     * reach one at all. Not a capability the engine uses — it exists so one device run answers whether
-     * our pod compiles against ReactCommon's renderer, links against the prebuilt framework, and can
-     * resolve the UIManager from a plain JSI runtime. See the C++ side for why -1 and 0 differ.
-     */
     probeUIManager: () => number;
-    /**
-     * Replay one recorded mutation batch — the five fields of `IMutationBatch`, spread, because JSI
-     * reads five arguments cheaper than it reads five properties off one object.
-     *
-     * `ops` is read as MEMORY on the native side and never becomes JS values; the four side tables
-     * carry what JSI has to marshal either way.
-     *
-     * `handles` is the load-bearing one and it travels OUT, not back. It holds the placeholder object
-     * for every slot the ops address, and the host attaches each created node's
-     * `shared_ptr<const ShadowNode>` to the object at that slot as JSI `NativeState` — so the objects
-     * the adapter is already holding become the real handles in place. Nothing is returned.
-     *
-     * That is the whole lifetime design, and it is RN's own: `nativeFabricUIManager.createNode()`
-     * hands back an object whose NativeState owns the node, so Hermes collecting the object is what
-     * frees it. The version this replaced kept a `Map<int, shared_ptr>` in C++ instead — a second
-     * owner nothing could tell to let go, which cost 792 -> 1492 MB across one benchmark suite.
-     */
     applyOps: (ops: Int32Array, strings: readonly string[], values: readonly unknown[], instanceHandles: readonly unknown[], handles: readonly object[]) => void;
-    /**
-     * The four reads of `ITreeHost`, taking the same placeholder object `applyOps` put the node on.
-     *
-     * None 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), so
-     * the crossing cost is irrelevant. `undefined` / empty is an ordinary answer from all of them: a
-     * handle native has not seen and a genuinely absent value are indistinguishable here, and both
-     * degrade.
-     *
-     * `getViewName` answers the RESOLVED name, which native may have changed at insert — a `<Text>`
-     * inside another `<Text>` commits as `RCTVirtualText`, and only the side holding the parent link
-     * knows.
-     */
     getProp: (handle: object, key: string) => unknown;
     getProps: (handle: object) => Readonly<Record<string, unknown>>;
     /** The one WRITE among them: dirty a node no op named. See `markPropsDirty` (node.ts). */
@@ -77,63 +25,27 @@ export type INativeEngineBindings = {
     committedRecordOf: (handle: object) => ICommittedRecord | undefined;
     /** A TEST read — the payload the last commit sent. See `ITreeHost.committedPayloadOf`. */
     committedPayloadOf: (handle: object) => Readonly<Record<string, unknown>> | undefined;
-    /**
-     * The imperative six, taking the same placeholder object `applyOps` put the node on.
-     *
-     * They are here because `nativeFabricUIManager`'s own copies unwrap a handle IT minted, and under
-     * the batched applier every handle in play was minted by the batching slot. Ours carry the node on
-     * their `NativeState` exactly as RN's do, so these six are the same code reading a different
-     * object. An app calling `measure()` on a ref reaches native through here or not at all.
-     *
-     * The callback protocol is Fabric's own, not ours: `measure` answers six numbers, `measureInWindow`
-     * four, and `measureLayout` calls `onFail` when the surface has no committed revision — copied
-     * from `UIManagerBinding` so a component that already handles those cases keeps working.
-     */
     dispatchCommand: (handle: object, commandName: string, args: readonly unknown[]) => void;
     sendAccessibilityEvent: (handle: object, eventType: string) => void;
     measure: (handle: object, callback: (x: number, y: number, width: number, height: number, pageX: number, pageY: number) => void) => void;
     measureInWindow: (handle: object, callback: (x: number, y: number, width: number, height: number) => void) => void;
     measureLayout: (handle: object, relativeTo: object, onFail: () => void, onSuccess: (x: number, y: number, width: number, height: number) => void) => void;
     setIsJSResponder: (handle: object, isResponder: boolean, blockNativeResponder: boolean) => void;
-    /**
-     * RN's own commit telemetry for ANY surface, including one this host never drove.
-     *
-     * OPTIONAL: it is read with `?.`, so a pod predating it degrades instead of throwing, unlike the
-     * members above that `isBindings` requires. Treat an absent member as "no answer", never as
-     * zeroes — a zero reads as "React's commit measures no text", the claim this exists to test.
-     */
-    /**
-     * The C++ half's diagnostics (`SymbioteDebug.h`). OPTIONAL, like `readSurfaceTelemetry` and for
-     * the same reason: an older native binary that predates them must still pass `isBindings` rather
-     * than failing bring-up over a member nothing on the critical path needs.
-     */
+    getBoundingClientRect?: (handle: object, includeTransform: boolean) => {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | undefined;
     setDebugEnabled?: (enabled: boolean) => void;
     takeDebugLog?: () => readonly string[];
     readSurfaceTelemetry?: (surfaceId: number) => {
-        /**
-         * The inside of a commit, read out of RN's OWN `TransactionTelemetry` rather than timed by us
-         * — a `ShadowTreeRevision` carries the telemetry of the commit that produced it.
-         *
-         * `layoutNodes` is the one that answers the question the timings only pose: Yoga reports how
-         * many layoutable nodes it actually touched, so a one-row change that reports the whole tree is
-         * a re-layout, not a slow layout.
-         */
         layoutMs: number;
         textMs: number;
-        /**
-         * `ShadowTree::commit`'s own window, and NOT `materialize`'s — this used to say otherwise, and
-         * three rounds of investigation read the number that way. `materialize` runs in `kOpCommit`
-         * before `completeSurface` is called, so it falls outside this window and layout's alike.
-         */
         commitMs: number;
         layoutNodes: number;
         textMeasures: number;
-        /**
-         * Parents that took the targeted-replace path since the last read, zeroed on read. OURS, not
-         * RN's — a LIVENESS signal for a fast path whose absence no correctness test can see.
-         */
         targetedReplaces: number;
-        /** `materialize`'s own walk and its breakdown — ours, zeroed on read. See `ISurfaceTelemetry`. */
         walkMs: number;
         propsMs: number;
         foldLookupMs: number;
@@ -173,14 +85,6 @@ export type INativeEngineBindings = {
 declare global {
     var __symbioteEngineNative: unknown;
 }
-/**
- * The native bindings, or `undefined` when this platform has none.
- *
- * Resolving the TurboModule is done for its SIDE EFFECT: `RCTTurboModuleManager` runs
- * `installJSIBindingsWithRuntime:` at the moment it creates a module, so touching the module by name
- * is what puts the global there. The module's own methods are not the capability and are not called
- * here — which is why a reader looking for the payload in the spec file will not find it.
- */
 export declare function nativeEngine(): INativeEngineBindings | undefined;
 /** Test seam: forget what was resolved, so a fixture can install or remove the global between cases. */
 export declare function resetNativeEngine(): void;

package/build/native-engine.js

@@ -1,157 +1,77 @@
-// The JS half of our own native module (item 8c of `symbiote-fabric-cxx-surface`). It answers one
-// question — is there a native store on this platform — and every caller must be able to take `no`.
-//
-// `no` is not an error case, it is the majority case:
-//
-//   headless (vitest, 5 600 tests)   no native anything; the JS backing store is the only one
-//   Android                          the module is iOS-only for now, by choice, not by oversight
-//   an app that skipped `pod install` the standing hazard of this repo's local-dev loop
-//   an older pod against newer JS     two artefacts, two install steps, no shared version gate
-//
-// So the contract is: `nativeEngine()` returns the bindings or `undefined`, and nothing in the engine
-// may require them. The native store is an ACCELERATOR behind the same seam the JS one sits behind.
-//
-// ── THIS IS NOT A LICENCE FOR TWO IMPLEMENTATIONS, AND THE DISTINCTION IS THE POINT ──────────────
-//
-// Two different things get called "the native path" and only one of them is a fork:
-//
-//   the STORE (8b')      `new Int32Array(n)` vs an `Int32Array` over native memory. `node-table.ts`
-//                        is byte-identical either way — one implementation, two allocators. There is
-//                        nothing here that can drift.
-//   the APPLIER (8c-1)   `replayChildOps` in commit.ts vs `cloneMultiple` inside a commit hook. That
-//                        IS two implementations of one fold, and a permanent fallback to the JS half
-//                        would be exactly the silent divergence this repo keeps finding.
-//
-// So the graceful `undefined` below is correct for the store and TRANSITIONAL for the applier. When
-// the applier moves, the JS one is DELETED — the way `node.children` and `node.parent` were — and a
-// missing or mismatched module has to fail LOUD rather than quietly run a second implementation. A
-// silent fallback at that point is a measurement that lies, not resilience.
-//
-// The expensive part of that transition, named here because it is easy to discover too late: ~5 600
-// headless tests drive the JS applier against a fake Fabric slot. Faking `new Int32Array` is free;
-// faking C++ tree cloning is not, so those tests stop covering what actually runs.
-//
-// Fantom was the intended answer and it is NOT available — measured 2026-09-08, four independent
-// blockers. `@react-native/fantom` is not on npm at all (404); it exists only as vendored source
-// under `.vendors/react-native/private/`, marked `private: true`. That vendored tree is RN **main**
-// while this repo consumes 0.86.0, so a tester built from it would exercise the wrong C++. Building
-// it needs a yarn install plus a gradle/CMake build of Hermes, folly and ReactCommon, all written
-// INTO `.vendors/`. And `config/metro.config.js` computes `projectRoot` from `__dirname` with an
-// empty `watchFolders`, so a test file outside that monorepo cannot be resolved — not overridable
-// by env, config merge or CLI. RN's own README says it plainly: "not currently supported for
-// testing application-specific code in React Native apps."
-//
-// So the oracle for a C++ commit path has to be built here: a TypeScript reference implementation
+// The JS half of our own native module. It answers one question — is there a native store on this
+// platform — and every caller must be able to take no. no is the majority case: headless tests,
+// Android (iOS-only for now), a skipped pod install, or a pod/JS version mismatch.
+// nativeEngine() returns the bindings or undefined, and nothing in the engine may require them —
+// the native store is an accelerator behind the same seam the JS one sits behind.
+// Not a licence for two implementations, though. The store (Int32Array vs. native memory) is
+// byte-identical either way, one implementation two allocators — nothing here can drift. The
+// applier (replayChildOps vs. cloneMultiple) IS two implementations of one fold.
+// So undefined below is correct for the store and transitional for the applier: when the applier
+// moves, the JS one is deleted, and a missing or mismatched module must fail loud rather than
+// quietly run a second implementation — a silent fallback then would be a measurement that lies.
+// Fantom (RN's own headless C++ test runner) is not a usable oracle for this: not published to
+// npm, vendored from RN main against a repo pinned to 0.86, needing a from-scratch Hermes/folly/
+// ReactCommon build, and its own README says it isn't supported for app-specific test code yet.
+// So the oracle for a C++ commit path is built here instead: a TypeScript reference implementation
 // the existing suite already exercises, plus a gtest target linking ReactCommon from the installed
-// react-native. Do not cite Fantom as the plan again without re-running that check.
+// react-native.
 import { dlog } from './debug.js';
 import { getNativeModule } from './native-modules/index.js';
 import { isRecord } from './type-guards.js';
-/**
- * The ABI this file knows how to talk to. A binary reporting anything else is refused outright rather
- * than probed method by method — the two artefacts ship separately (a pod and an npm package), so
- * disagreement is routine, and a partial match is the shape that corrupts memory quietly.
- *
- * Exported for the tests, which must DERIVE their supported and unsupported arms from it rather than
- * restate the number: a bump that leaves a fixture behind reads as "the binary is stale", which is
- * exactly the message this constant exists to produce, so the failure looks like the feature working.
- */
+// The ABI this file knows how to talk to. A binary reporting anything else is refused outright
+// rather than probed method by method — the two artefacts ship separately (a pod and an npm
+// package), so disagreement is routine and a partial match corrupts memory quietly.
+// Exported for the tests, which must derive their supported/unsupported arms from it rather than
+// restate the number: a bump that leaves a fixture behind reads as "the binary is stale", which is
+// exactly the message this constant exists to produce.
 export const SUPPORTED_NATIVE_VERSION = 4;
+// A member missing from this list resolves fine at bring-up and throws at the first call site
+// instead. `getBoundingClientRect` stays out on purpose: it is optional on the type.
+const REQUIRED_METHOD_NAMES = [
+    'allocInt32Array',
+    'probeUIManager',
+    'applyOps',
+    'getProp',
+    'getProps',
+    'markPropsDirty',
+    'getViewName',
+    'parentOf',
+    'childrenOf',
+    'firstChildOf',
+    'nextSiblingOf',
+    'parentsOf',
+    'subtreesOf',
+    'teardownSubtreesOf',
+    'ancestorsOf',
+    'committedRecordOf',
+    'dispatchCommand',
+    'sendAccessibilityEvent',
+    'measure',
+    'measureInWindow',
+    'measureLayout',
+    'setIsJSResponder',
+];
 function isBindings(value) {
     if (!isRecord(value))
         return false;
     if (typeof value.version !== 'number')
         return false;
-    if (typeof value.allocInt32Array !== 'function')
-        return false;
-    if (typeof value.probeUIManager !== 'function')
-        return false;
-    if (typeof value.applyOps !== 'function')
-        return false;
-    // The tree reads, checked one by one rather than as a blob for the reason the whole guard is
-    // written this way: a member added to the type without a line here resolves fine at bring-up and
-    // throws at the first call site, which is a gesture or a `measure()` — one language and several
-    // seconds away from the install that caused it.
-    if (typeof value.getProp !== 'function')
-        return false;
-    if (typeof value.getProps !== 'function')
-        return false;
-    if (typeof value.markPropsDirty !== 'function')
-        return false;
-    if (typeof value.getViewName !== 'function')
-        return false;
-    if (typeof value.parentOf !== 'function')
-        return false;
-    if (typeof value.childrenOf !== 'function')
-        return false;
-    if (typeof value.firstChildOf !== 'function')
-        return false;
-    if (typeof value.nextSiblingOf !== 'function')
-        return false;
-    if (typeof value.parentsOf !== 'function')
-        return false;
-    if (typeof value.subtreesOf !== 'function')
-        return false;
-    if (typeof value.teardownSubtreesOf !== 'function')
-        return false;
-    if (typeof value.ancestorsOf !== 'function')
-        return false;
-    if (typeof value.committedRecordOf !== 'function')
-        return false;
-    // The imperative six, checked by name for the same reason as the rest: a pod that has `applyOps`
-    // but not these is an OLDER binary, and accepting it would leave `measure()` reaching a method
-    // that is not there — at the moment an app measures a ref, not at bring-up.
-    if (typeof value.dispatchCommand !== 'function')
-        return false;
-    if (typeof value.sendAccessibilityEvent !== 'function')
-        return false;
-    if (typeof value.measure !== 'function')
-        return false;
-    if (typeof value.measureInWindow !== 'function')
-        return false;
-    if (typeof value.measureLayout !== 'function')
-        return false;
-    return typeof value.setIsJSResponder === 'function';
+    return REQUIRED_METHOD_NAMES.every(name => typeof value[name] === 'function');
 }
-// Why `SUPPORTED_NATIVE_VERSION` did NOT move when `probeUIManager` was added, since bumping it is
-// the reflex. The version field guards a MEMORY LAYOUT — it is what stops JS reading a store whose
-// fields moved. Adding a host function changes no layout, and the shape guard above already refuses
-// an older pod that lacks the name, giving the same clean degrade for free. Bumping instead would
-// cost every app on an older pod its native STORE to announce a probe it does not use. Bump the
-// version when the meaning of the bytes changes, not when the object gains a key.
-//
-// ── AND WHY IT DID MOVE, 1 -> 2, FOR THE HANDLE REWRITE ──────────────────────────────────────────
-//
-// Because the shape guard cannot see this one. Every NAME is unchanged: a v1 pod has `applyOps` and
-// all five, so `isBindings` passes it. What changed is what the arguments MEAN — `applyOps` gained
-// `handles`, which a v1 binary silently ignores, and the five went from taking an integer id to
-// taking the handle object, which a v1 binary reads with `.asNumber()`. The first fails by
-// committing nothing and leaking; the second throws one language away from the cause. That is the
-// same class as a moved field, arriving through a calling convention rather than a struct, and it is
-// exactly what this number exists to refuse.
-//
-// ── AND 3 -> 4, FOR THE SAME REASON THE SHAPE GUARD CANNOT HELP WITH ─────────────────────────────
-//
-// The four tree reads are new NAMES, so the guard above would turn a v3 pod away on its own. But
-// `applyOps` also went from six arguments to five, and the name did not move: a v3 binary reads
-// argument 1 as `childIds` (an `Int32Array`) where JS now passes `strings`, and argument 2 as a
-// props table where JS now passes `values`. Every one of those reads succeeds against the wrong
-// object and commits a wrong tree rather than throwing. That is a calling convention change, which
-// is what this number is for — the guard would have refused this pod by luck, on the reads, and a
-// refusal by luck is not a refusal.
+// SUPPORTED_NATIVE_VERSION guards a memory layout, not a member list: the shape guard above
+// already refuses an older pod lacking a new function's name, so bumping for that alone would
+// cost every app on an older pod its native store for nothing.
+// Bump only when the meaning of existing bytes or arguments changes: a calling-convention change
+// the shape guard can't see, since names stay the same while what they mean does not — every read
+// still resolves to a value, just the wrong one, committing a wrong tree rather than throwing.
 // `undefined` means "resolved, and there is none" — distinct from `resolved === false`, which means
 // nobody has looked. Collapsing the two would re-run the lookup on every miss, and the miss is the
 // common case.
 let resolved = false;
 let bindings;
-/**
- * The native bindings, or `undefined` when this platform has none.
- *
- * Resolving the TurboModule is done for its SIDE EFFECT: `RCTTurboModuleManager` runs
- * `installJSIBindingsWithRuntime:` at the moment it creates a module, so touching the module by name
- * is what puts the global there. The module's own methods are not the capability and are not called
- * here — which is why a reader looking for the payload in the spec file will not find it.
- */
+// The native bindings, or undefined when this platform has none. Resolving the TurboModule is
+// done for its side effect: RCTTurboModuleManager runs installJSIBindingsWithRuntime: at the
+// moment it creates a module, so touching the module by name is what puts the global there.
 export function nativeEngine() {
     if (resolved)
         return bindings;
@@ -164,9 +84,8 @@ export function nativeEngine() {
         return undefined;
     }
     if (installed.version !== SUPPORTED_NATIVE_VERSION) {
-        // Loud, because the repair is a `pod install` and the symptom otherwise is a wrong memory layout
-        // rather than a missing feature. `<examples_vs_dot_examples>` records how routinely an install
-        // replaces the JS half without the native one.
+        // Loud, because the repair is a pod install and the symptom otherwise is a wrong memory
+        // layout rather than a missing feature — an install routinely replaces the JS half alone.
         dlog(`native-engine: REFUSING native store, ABI ${installed.version} ` +
             `against supported ${SUPPORTED_NATIVE_VERSION} — run \`pod install\`. Using the JS arrays`);
         return undefined;

package/build/native-events.js

@@ -1,12 +1,6 @@
-// native -> JS: receiving native module events. The native side emits ALL device
-// events by invoking ONE callable JS module under the fixed name
-// `RCTDeviceEventEmitter`. On a real RN host that name is already owned by RN's own
-// RCTDeviceEventEmitter, and `RN$registerCallableModule` cannot steal it: native's
-// `callableModules_.emplace` ignores a duplicate key (ReactInstance.cpp), so a
-// second registration is a silent no-op. So we do NOT register our own hub on a
-// real host: the app injects RN's DeviceEventEmitter (the bus native actually
-// calls) via `setDeviceEventSource`, exactly like setColorProcessor. The built-in
-// hub below stays as the fallback bus for headless/non-RN runs.
+// native -> JS: receiving native module events, all under one callable JS module name. A real
+// host already owns that name, so a second registration is a no-op — the app injects RN's
+// DeviceEventEmitter instead via setDeviceEventSource; below is the fallback for headless runs.
 import { dlog } from './debug.js';
 import { runWrapped } from './dispatch.js';
 import { invariant } from './invariant.js';
@@ -19,10 +13,9 @@ function emit(eventType, ...args) {
     dlog(`device hub emit "${eventType}" -> ${set?.size ?? 0} listener(s)`);
     if (set === undefined)
         return;
-    // A device event arrives outside the framework's update loop; route the fan-out
-    // through the shared dispatch wrapper so a listener's setState lands on the sync
-    // lane and flushes, the same seam Fabric touch events use. Snapshot before
-    // iterating: a listener may remove itself mid-dispatch.
+    // Route through the shared dispatch wrapper so a listener's setState flushes on the sync
+    // lane, the same seam Fabric touch events use. Snapshot first: a listener may remove
+    // itself mid-dispatch.
     const snapshot = [...set];
     runWrapped(() => {
         for (const listener of snapshot)
@@ -65,11 +58,9 @@ let injectedSource;
 export function setDeviceEventSource(source) {
     injectedSource = source;
 }
-// True only when the module actually carries both observe-counter methods. A
-// resolved TurboModule whose spec omits addListener/removeListeners (or a host where
-// the module isn't a real event emitter) leaves them undefined, so calling through
-// would throw "undefined is not a function" — the `?.` guards the module, not a
-// missing method. Mirrors RN's NativeEventEmitter constructor probe.
+// True only when the module carries both observe-counter methods. A spec that omits
+// addListener/removeListeners leaves them undefined, so calling through would throw —
+// the guard here protects the module, not a missing method. Mirrors RN's constructor probe.
 function hasObserveCounters(module) {
     return (typeof module.addListener === 'function' &&
         typeof module.removeListeners === 'function');

package/build/native-tree-host.d.ts

@@ -1,25 +1,4 @@
 import { type INativeEngineBindings } from './native-engine';
 import { type ITreeHost } from './tree-host';
-/**
- * Present one resolved set of bindings as the engine's tree host.
- *
- * `census` is the only member that does not reach native, and it is deliberately not on the ABI: it
- * has exactly ONE engine caller (`censusRetainedTree`), it is diagnostics, and answering it honestly
- * would cost a full native walk of the very tree the design exists to stop walking. The empty census
- * is what `censusRetainedTree` already answers with no host at all, so a probe reading it sees the
- * same zeroes it has always seen off a device.
- */
 export declare function nativeTreeHost(bindings: INativeEngineBindings): ITreeHost;
-/**
- * Install it, if this runtime has a native module and nothing has claimed the seam already.
- *
- * PRECEDENCE: an installed host WINS. `installFabric()` is the only other caller of `setTreeHost`,
- * and it puts the TypeScript applier in before any fixture can bind a slot — so a headless run that
- * also happens to carry fake bindings must keep the applier, or the ~5 500 tests written against it
- * would silently start driving a stub. The reverse ordering cannot occur on a device: nothing there
- * installs a host but this.
- *
- * No native module is the ORDINARY answer (`native-engine.ts`'s header lists where), and it stays a
- * quiet one here: the ops simply keep accumulating, exactly as they did before this file existed.
- */
 export declare function installNativeTreeHost(): void;

package/build/native-tree-host.js

@@ -1,24 +1,14 @@
-// The NATIVE tree host — `INativeEngineBindings` presented as an `ITreeHost`.
-//
-// It is the half that makes the buffer mean anything on a device. `tree-host.ts` records ops and
-// then asks a host to turn them into a tree; headlessly `installFabric()` installs the TypeScript
-// applier, and until this file existed a device installed NOTHING — `commitSurfaceOps` returned
-// early, the ops stayed pending forever, and the screen stayed blank with nothing red anywhere.
-//
-// There is no logic here on purpose. Everything the host is asked is something native already
-// answers, so this is a rename and an argument spread; a mapping thin enough to read in one pass is
-// what keeps the two sides auditable against each other.
+// The NATIVE tree host — `INativeEngineBindings` presented as an `ITreeHost`. It is the half that
+// makes the buffer mean anything on a device: `tree-host.ts` records ops and asks a host to turn
+// them into a tree; headlessly, `installFabric()` installs the TS applier instead.
+// No logic here on purpose: everything the host is asked is something native already answers, so
+// this stays a rename plus an argument spread, thin enough to audit against native's own side.
 import { nativeEngine } from './native-engine.js';
 import { EMPTY_CENSUS, setTreeHost, treeHost, } from './tree-host.js';
-/**
- * Present one resolved set of bindings as the engine's tree host.
- *
- * `census` is the only member that does not reach native, and it is deliberately not on the ABI: it
- * has exactly ONE engine caller (`censusRetainedTree`), it is diagnostics, and answering it honestly
- * would cost a full native walk of the very tree the design exists to stop walking. The empty census
- * is what `censusRetainedTree` already answers with no host at all, so a probe reading it sees the
- * same zeroes it has always seen off a device.
- */
+// Present one resolved set of bindings as the engine's tree host.
+// `census` is the only member that never reaches native — deliberately not on the ABI, since its
+// one caller (censusRetainedTree) is diagnostics and answering honestly costs a full native walk
+// of the tree the design exists to avoid walking. The empty census matches the no-host answer.
 export function nativeTreeHost(bindings) {
     return {
         // Spread rather than passed as the batch object: JSI reads five arguments cheaper than five
@@ -46,20 +36,14 @@ export function nativeTreeHost(bindings) {
         measureInWindow: bindings.measureInWindow,
         measureLayout: bindings.measureLayout,
         setIsJSResponder: bindings.setIsJSResponder,
+        getBoundingClientRect: bindings.getBoundingClientRect,
     };
 }
-/**
- * Install it, if this runtime has a native module and nothing has claimed the seam already.
- *
- * PRECEDENCE: an installed host WINS. `installFabric()` is the only other caller of `setTreeHost`,
- * and it puts the TypeScript applier in before any fixture can bind a slot — so a headless run that
- * also happens to carry fake bindings must keep the applier, or the ~5 500 tests written against it
- * would silently start driving a stub. The reverse ordering cannot occur on a device: nothing there
- * installs a host but this.
- *
- * No native module is the ORDINARY answer (`native-engine.ts`'s header lists where), and it stays a
- * quiet one here: the ops simply keep accumulating, exactly as they did before this file existed.
- */
+// Install it, if this runtime has a native module and nothing has claimed the seam already.
+// An installed host wins: installFabric() (the only other setTreeHost caller) puts the TS applier
+// in first, so a headless run carrying fake bindings must keep the applier, not the stub.
+// No native module is the ordinary answer (see native-engine.ts); ops then simply keep
+// accumulating, undelivered.
 export function installNativeTreeHost() {
     const bindings = nativeEngine();
     if (bindings === undefined || treeHost() !== undefined)

package/build/node-events.d.ts

@@ -0,0 +1,11 @@
+import type { IEventDispatch, IListener, ISymbioteNode } from './node-types';
+export declare function setBehaviorListener(node: ISymbioteNode, name: string, listener: IListener | undefined): void;
+export declare function setNodeDispatch(node: ISymbioteNode, dispatch: IEventDispatch | undefined): void;
+/** Whether anything at all would receive `name` on this node. */
+export declare function hasListenerFor(node: ISymbioteNode, name: string): boolean;
+export declare function listenerFor(node: ISymbioteNode, name: string): IListener | undefined;
+export declare function setEventListener(node: ISymbioteNode, name: string, value: unknown): void;
+export declare function isOnEventName(key: string): boolean;
+/** `onChange` to `change`. */
+export declare function listenerName(propName: string): string;
+export declare const RESPONDER_EVENTS: ReadonlySet<string>;