@symbiote-native/engine 1.3.0 → 1.3.1

package/build/surface.js

@@ -1,15 +1,5 @@
 // A surface is one mounted root: it owns the rootTag handed down by the native Fabric host and the
 // top-level nodes under it. Adapters mutate it and ask it to commit.
-//
-// A SURFACE IS ONE ORDINARY NODE, and that is the whole implementation rather than a trick. It holds
-// a real handle, its child ops are the ordinary append / insertBefore / removeChild, and `OP_COMMIT`
-// names that one handle — so the host needs no `rootTag -> node` map, which is what keeps it
-// stateless.
-//
-// The node is RN's AppContainer (`createSurfaceRoot` in `node.ts` — `flex: 1`, `box-none`), so what
-// reaches the root child set is one view with the app under it. An ANCHOR in the same position
-// hoists its children instead, and the host takes both through the same call, so nothing here is a
-// special case.
 import { dlog } from './debug.js';
 import { installEventHandler } from './events/index.js';
 import { detachAnimatedProps } from './animated/host-binding.js';
@@ -33,17 +23,10 @@ export class SymbioteSurface {
         this.rootTag = rootTag;
         this.node = createSurfaceRoot();
     }
-    /**
-     * Every OTHER live surface, so one commit names every root — see `commitSurfaceOps`.
-     *
-     * Static because it reads a sibling instance's private handle, which only a member of this class
-     * may do. One surface — the universal case — allocates nothing.
-     *
-     * `self` may already be OUT of the registry: a teardown unregisters and then commits, and that
-     * commit is the one carrying the removals. So the fast path cannot be a size check — with one
-     * live surface left, `size === 1` means either "only me" or "only the other one", and taking the
-     * shortcut on the second reading is how a surface loses the very batch that empties it.
-     */
+    // Every other live surface, so one commit names every root — see commitSurfaceOps. Static
+    // because it reads a sibling instance's private handle, which only a member of this class may do.
+    // self may already be out of the registry: a teardown unregisters and then commits, carrying the
+    // removals — so the fast path can't be a size check, since size===1 could mean either surface.
     static others(self) {
         let out;
         for (const other of surfaces.values()) {
@@ -54,13 +37,8 @@ export class SymbioteSurface {
         }
         return out ?? NO_CO_COMMITTERS;
     }
-    /**
-     * The top-level nodes, asked of the host.
-     *
-     * A getter rather than an array this class maintains: a second copy of a child list is the thing
-     * this design removes, and `nextSiblingOf` (host-access.ts) needs the same answer the host gives
-     * for a parented node.
-     */
+    // The top-level nodes, asked of the host. A getter rather than an array this class maintains: a
+    // second copy of a child list is the thing this design removes.
     get children() {
         return childrenOf(this.node);
     }
@@ -70,10 +48,8 @@ export class SymbioteSurface {
     insertBefore(child, beforeChild) {
         insertBefore(this.node, child, beforeChild);
     }
-    // Nomination for teardown rides on `node.ts`'s `removeChild`, and only NOMINATES for the reason
-    // stated there: a framework may spell a move as remove-then-reinsert, so the commit sweep
-    // decides. The surface is one ordinary node, so it is not a second removal path that could miss
-    // the sweep and leave a behavior — its timers included — outliving the surface.
+    // Nomination for teardown rides on node.ts's removeChild, and only nominates: a framework may
+    // spell a move as remove-then-reinsert, so the commit sweep decides.
     removeChild(child) {
         removeChild(this.node, child);
     }
@@ -81,63 +57,41 @@ export class SymbioteSurface {
         for (const child of this.children)
             removeChild(this.node, child);
     }
-    /**
-     * Release every host behavior still standing under this surface, at unmount.
-     *
-     * The sweep above cannot answer this: it only sees nodes a `removeChild` NOMINATED, and an
-     * unmount removes nothing — the adapter drops the whole surface. Without it every node keeps its
-     * `afterCommit` registration and its timers, and a restarted surface's commits drain the dead
-     * one's hooks forever.
-     */
+    // Release every host behavior still standing under this surface, at unmount. The sweep above
+    // can't answer this: it only sees nodes removeChild nominated, and an unmount removes nothing —
+    // the adapter drops the whole surface.
     teardown() {
-        // The nominations first: an adapter that empties the surface and disposes it without a commit
-        // in between (React's `clearContainer`) never reaches the commit sweep, and the walk below
-        // cannot see those nodes either — they already left the tree.
+        // The nominations first: an adapter that empties and disposes the surface without a commit in
+        // between never reaches the commit sweep, and the walk below can't see those nodes either.
         sweepDetachedBehaviors(this.children, detachAnimatedProps);
         teardownSubtree(this.node, detachAnimatedProps);
     }
     // Synchronous commit: used by React's resetAfterCommit, which already batches per logical update.
     commit() {
-        // A SUPERSEDED surface still flushes its ops and still names every other root — its teardown is
-        // what carries the removals — but it must not complete a root another surface now owns. Fast
-        // Refresh and the focus lifecycle re-mount the same rootTag, so the old surface's teardown
-        // commit lands AFTER the new one's mount commit and would hand Fabric the emptied tree.
-        // An UNREGISTERED surface is not superseded — nobody took the root, so its final emptied tree
-        // is still the truth for it. Only a live OTHER owner suppresses the op.
-        // The teardown half of the behavior lifecycle. It runs AFTER the ops are applied — it decides
-        // what really left by asking the host for a parent, and the host does not know about a removal
-        // it has not been handed — but BEFORE the root is completed, so a behavior's parting writes
-        // (ScrollView taking its forced `scrollEventThrottle` back) ride this commit instead of owing
-        // another one. `flushOps` is that split: apply, do not publish.
-        //
-        // `removeChild` only NOMINATES — a framework spells a move as remove-then-reinsert, so tearing
-        // down at the call would kill a machine that comes back in the same batch.
+        // A superseded surface still flushes its ops and names every other root (its teardown carries
+        // the removals), but must not complete a root another surface now owns — Fast Refresh and the
+        // focus lifecycle can re-mount the same rootTag while an old teardown commit is still pending.
+        // The behavior-teardown half runs after ops are applied (asking the host for a parent needs the
+        // removal already handed over) but before the root completes, so a behavior's parting writes
+        // ride this commit instead of owing another one. flushOps is that split: apply, don't publish.
         flushOps();
-        // GUARDED AT THE CALL SITE, not inside the sweep — `this.children` is a host read that builds
-        // the whole top-level list, and it would run on every commit for a sweep that had nothing to do.
+        // Guarded at the call site, not inside the sweep — this.children is a host read that builds the
+        // whole top-level list, and it would run on every commit for a sweep with nothing to do.
         if (hasDetachCandidates()) {
             sweepDetachedBehaviors(this.children, detachAnimatedProps);
         }
         const owner = surfaces.get(this.rootTag);
         const superseded = owner !== undefined && owner !== this;
         commitSurfaceOps(superseded ? undefined : this.rootTag, this.node, SymbioteSurface.others(this));
-        // Fresh Fabric handles are now assigned, so the three things that could not run before one
-        // existed all drain here — this is the moment the old `commitChildren` drained them too.
-        //
-        // `notifyCommitted` releases the imperative waiters (`whenCommitted`); `runPostCommitHooks` the
-        // consumers that needed a committed TAG and ran too early, which is the Animated native driver
-        // binding a props node under an async-batched commit; `runDeferredAttaches` the half of a host
-        // behavior whose setup needs a tag (a view command, an event attach). The predicate is passed in
-        // rather than imported by `host-behavior.ts`, keeping that dependency one-directional — a cycle
-        // there is a live hazard under Metro's `inlineRequires`.
+        // Fresh Fabric handles are now assigned, so the three things that couldn't run before one
+        // existed all drain here: notifyCommitted releases the imperative waiters, runPostCommitHooks
+        // the consumers that needed a committed tag, runDeferredAttaches the same for a host behavior.
         notifyCommitted();
         runPostCommitHooks();
         runDeferredAttaches(isNodeCommitted);
-        // After the setup half, never before it: a node carrying both hooks has `attachAfterCommit`
-        // seed the mirrors `afterCommit` then compares against. Unlike the two above it asks only
-        // "props were published", so it is NOT gated on the commit having made native calls — a fold
-        // that strips a prop makes its own commit byte-identical, and the hook that must react to the
-        // flip would be the one the flip cannot wake.
+        // After the setup half, never before: a node carrying both hooks has attachAfterCommit seed the
+        // mirrors afterCommit then compares against. Unlike the two above, this asks only "props were
+        // published", so it isn't gated on the commit having made native calls.
         runCommittedHooks(isNodeCommitted);
     }
     // Coalesced commit: for reactive frameworks that emit many mutations per tick. Collapses to a
@@ -152,9 +106,8 @@ export class SymbioteSurface {
         });
     }
 }
-// Every live surface, so the microtask flush in `imperative.ts` can commit the one a queued write
-// named. Registered from here rather than imported there: a surface owns its own commit, and
-// reaching into it from the imperative half would put back the cycle that split exists to remove.
+// Every live surface, so the microtask flush in imperative.ts can commit the one a queued write
+// named. Registered from here rather than imported there, keeping that dependency one-directional.
 const surfaces = new Map();
 registerSurfaceCommit(rootTag => {
     surfaces.get(rootTag)?.commit();

package/build/text-input-state.js

@@ -1,7 +1,5 @@
-// Mirrors RN's TextInput/TextInputState: the single currently-focused input, tracked
-// JS-side because native exposes no focus getter. TextInput reports focus/blur here so
-// Keyboard.dismiss can blur whatever holds focus without a ref, exactly how RN's
-// dismissKeyboard() works (blurTextInput(currentlyFocusedInput())).
+// Mirrors RN's TextInput/TextInputState: the single currently-focused input, tracked JS-side since
+// native exposes no focus getter. Lets Keyboard.dismiss blur whatever holds focus without a ref.
 import { dispatchViewCommand, propOf } from './imperative.js';
 import { dlog } from './debug.js';
 let currentlyFocused = null;
@@ -18,10 +16,8 @@ export function setInputBlurred(node) {
     if (currentlyFocused === node)
         currentlyFocused = null;
 }
-// Imperative blur: drive the native `blur` view command and drop the tracked focus.
-// Used by TextInput.blur() and Keyboard.dismiss(). A no-op if this node isn't the
-// currently-focused one — mirrors RN's TextInputState.blurTextInput, which guards the
-// same way so blurring an already-unfocused input never reaches native.
+// Imperative blur: drives the native `blur` command and drops tracked focus. A no-op if this
+// node isn't the currently-focused one, mirroring RN's TextInputState.blurTextInput guard.
 export function blurTextInput(node) {
     if (node === null || currentlyFocused !== node)
         return;

package/build/touch-history.js

@@ -1,14 +1,8 @@
-// Per-touch position/time tracking, ported from RN's
-// react-native-renderer/.../legacy-events/ResponderTouchHistoryStore.js. PanResponder's
-// multitouch dx/vx math needs each touch's own previous->current delta (RN counts only
-// touches that moved since `_accountsForMovesUpTo`), which a grant-relative centroid of
-// ALL live touches cannot reconstruct. We maintain the bank as touches flow and ATTACH
-// `touchHistory` onto the nativeEvent reaching responder handlers, exactly how
-// ResponderEventPlugin.js sets `*.touchHistory`.
-//
-// events/index.ts consumes only this file's public surface (recordTouchTrack,
-// attachTouchHistory, resetTouchHistory, touchHistory); everything else here is a
-// private implementation detail of the bank.
+// Per-touch position/time tracking, ported from RN's ResponderTouchHistoryStore. PanResponder's
+// multitouch dx/vx math needs each touch's own previous->current delta, which a grant-relative
+// centroid of all live touches can't reconstruct; the bank attaches to responder events.
+// events/index.ts consumes only this file's public surface (recordTouchTrack, attachTouchHistory,
+// resetTouchHistory, touchHistory); everything else here is a private implementation detail.
 import { isRecord } from './type-guards.js';
 // RN's bank is indexed by touch identifier and warns above 20; we never warn (headless
 // events may carry larger or absent ids), we just skip anything out of a sane range.

package/build/tree-host.d.ts

@@ -1,13 +1,6 @@
 import type { IMeasureInWindowOnSuccess, IMeasureLayoutOnSuccess, IMeasureOnSuccess, IRootTag } from './fabric';
 import { type IMutationBatch, type IMutationHandle } 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;
@@ -16,88 +9,24 @@ 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[];
     firstChildOf: (handle: object) => object | undefined;
     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 same walk, narrowed to the nodes a TEARDOWN has work for — each root, every node carrying
-     * an intrinsic tag, and every node between the two.
-     *
-     * It exists because the sweep's whole cost is how WIDE this walk is: a thousand-row clear crossed
-     * ten thousand handles to release a thousand machines, and eight in ten of those nodes were plain
-     * views the sweep marked and did nothing else with. An ancestor of a tagged node has to come back
-     * too, or a framework that returns an interior node on its own would never re-arm what hangs
-     * beneath it (`host-behavior.test.ts` guards exactly that shape).
-     *
-     * Not a replacement for `subtreesOf`: an animated binding is per node and carries no tag, so
-     * `host-access.ts` asks for the full walk whenever one exists.
-     */
     teardownSubtreesOf: (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;
@@ -107,137 +36,32 @@ export type ITreeHost = {
     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: IMutationHandle, others?: readonly (readonly [IRootTag, IMutationHandle])[]): void;
 export interface ICommitProfile {
     commits: number;
     propWrites: number;
-    /**
-     * Fresh Fabric families minted in this window — the SAME quantity a stock React Native app counts
-     * by wrapping `global.nativeFabricUIManager.createNode`, and the only like-for-like census left
-     * between the two stacks: our creates are issued from C++ (`SymbioteTree.cpp`,
-     * `uiManager.createNode`) and never touch that global, so a JS wrapper over it reads zero here by
-     * construction. Two arms whose node counts differ are not one workload, whatever their
-     * milliseconds say, so this belongs next to the writes rather than behind a surface id.
-     */
     nodesCreated: number;
-    /**
-     * How many times `applyOps` was ENTERED for this window — the number of JSI crossings the buffer
-     * actually cost, as against the one the architecture promises.
-     *
-     * A whole create should read 2. It reads more when something READS the tree while the tree is
-     * being built, because a read is a batch boundary: the buffer has to drain before the answer can
-     * be given, so a framework navigating what it is inserting enters `applyOps` once per mutation.
-     * `small-batch-crossing-cost.itest.ts` prices an empty prologue at 1.5-4.4 us, so ten thousand
-     * boundaries is tens of milliseconds that no node count and no write count can see — which is
-     * exactly the shape of a cost that shows up on a device and not in a fixture.
-     */
     applyCalls: number;
-    /**
-     * `applyOps` end to end, and the part of it that reads the buffer out of JS.
-     *
-     * THE ONE QUESTION A DEVICE HAS TO ANSWER and a fixture cannot. Our crossing is a single call
-     * carrying a 12 000-entry array that C++ walks element by element through JSI; stock's is ten
-     * thousand calls carrying scalars. On the harness's JavaScriptCore that walk is ~4 ms of a ~48 ms
-     * `applyOps`. Hermes is a different JSI implementation with different array-read costs and nothing
-     * headless can price it, so the number has to be read on a phone — near 4 ms and the buffer is
-     * innocent, tens of milliseconds and it is most of the gap the device reports.
-     */
     applyMs: number;
     decodeMs: number;
 }
-/**
- * NOTE: reading this now DRAINS the surface telemetry too — `nodesCreated` is folded in from
- * `readSurfaceTelemetry`, which zeroes on read in C++. A sampler polling this on an interval
- * therefore empties what a later `readSurfaceTelemetry` call would have reported.
- */
 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;
@@ -246,124 +70,30 @@ export type ISurfaceTelemetry = {
     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;
-    /**
-     * How many nodes the C++ tree is holding right now — a LEVEL, not a total, and the one counter
-     * here that is not drained on read.
-     *
-     * What it is for: JS ownership anchors the C++ side (a node lives while a parent holds it or while
-     * JS names it through `NativeState`), so a heap reading proves the JS half was released and only
-     * infers the other. This is the other half as a reading.
-     */
     liveNodes: 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[];