@symbiote-native/engine 1.2.0 → 1.3.1

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[];