@symbiote-native/engine 0.4.0 → 1.0.0

package/build/native-engine.js

@@ -0,0 +1,178 @@
+// 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 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.
+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.
+ */
+export const SUPPORTED_NATIVE_VERSION = 4;
+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.nextSiblingOf !== 'function')
+        return false;
+    if (typeof value.parentsOf !== 'function')
+        return false;
+    if (typeof value.subtreesOf !== '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';
+}
+// 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.
+// `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.
+ */
+export function nativeEngine() {
+    if (resolved)
+        return bindings;
+    resolved = true;
+    getNativeModule('SymbioteEngine');
+    const installed = globalThis.__symbioteEngineNative;
+    if (!isBindings(installed)) {
+        dlog('native-engine: no native store on this platform ' +
+            `(global is ${typeof installed}) — using the JS backing arrays`);
+        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.
+        dlog(`native-engine: REFUSING native store, ABI ${installed.version} ` +
+            `against supported ${SUPPORTED_NATIVE_VERSION} — run \`pod install\`. Using the JS arrays`);
+        return undefined;
+    }
+    dlog(`native-engine: native store available, ABI ${installed.version}`);
+    bindings = installed;
+    return bindings;
+}
+/** Test seam: forget what was resolved, so a fixture can install or remove the global between cases. */
+export function resetNativeEngine() {
+    resolved = false;
+    bindings = undefined;
+}

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

@@ -0,0 +1,25 @@
+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

@@ -0,0 +1,66 @@
+// 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.
+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.
+ */
+export function nativeTreeHost(bindings) {
+    return {
+        // Spread rather than passed as the batch object: JSI reads five arguments cheaper than five
+        // properties, and this is the one member on a commit path.
+        applyOps: batch => bindings.applyOps(batch.ops, batch.strings, batch.values, batch.instanceHandles, batch.handles),
+        propOf: bindings.getProp,
+        propsOf: bindings.getProps,
+        markPropsDirty: bindings.markPropsDirty,
+        committedRecordOf: bindings.committedRecordOf,
+        committedPayloadOf: bindings.committedPayloadOf,
+        parentOf: bindings.parentOf,
+        childrenOf: bindings.childrenOf,
+        nextSiblingOf: bindings.nextSiblingOf,
+        parentsOf: bindings.parentsOf,
+        subtreesOf: bindings.subtreesOf,
+        ancestorsOf: bindings.ancestorsOf,
+        census: () => EMPTY_CENSUS,
+        // Straight through: native already takes the placeholder, which is what `committedRecordOf`
+        // above hands back in its `handle` field for exactly this reason.
+        dispatchCommand: bindings.dispatchCommand,
+        sendAccessibilityEvent: bindings.sendAccessibilityEvent,
+        measure: bindings.measure,
+        measureInWindow: bindings.measureInWindow,
+        measureLayout: bindings.measureLayout,
+        setIsJSResponder: bindings.setIsJSResponder,
+    };
+}
+/**
+ * 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 function installNativeTreeHost() {
+    const bindings = nativeEngine();
+    if (bindings === undefined || treeHost() !== undefined)
+        return;
+    setTreeHost(nativeTreeHost(bindings));
+}

package/build/node.d.ts

@@ -1,6 +1,7 @@
-import type { IFabricNode, IFabricProps, IRootTag, IMeasureOnSuccess, IMeasureInWindowOnSuccess, IMeasureLayoutOnSuccess } from './fabric';
+import type { IMeasureOnSuccess, IMeasureInWindowOnSuccess, IMeasureLayoutOnSuccess } from './fabric';
 import { type IClassNameValue } from './style-registry';
 import { type IPayloadFold } from './host-behavior';
+import { type ITreeCensus } from './tree-host';
 declare const BRAND: unique symbol;
 export declare const RAW_TEXT_COMPONENT = "RCTRawText";
 export declare const TEXT_COMPONENT = "RCTText";
@@ -18,94 +19,166 @@ export interface ISymbioteNode {
     readonly [BRAND]: true;
     component: string;
     readonly isText: boolean;
-    props: Record<string, unknown>;
     listeners: Map<string, IListener> | undefined;
-    children: ISymbioteNode[];
-    parent: ISymbioteNode | undefined;
-    dirty: boolean;
-    propsDirty: boolean;
-    hasAriaAlias: boolean;
+    /**
+     * Whether this node's host behavior declared `afterCommit`.
+     *
+     * Read on every prop write, exactly as `hasAriaAlias` beside it is and for the same reason: the
+     * alternative is a Set lookup per write, on the hottest path in the engine. What it gates is the
+     * NARROWING of the post-commit beat — the hook runs for nodes whose props moved rather than for
+     * every mounted behavior, which is what took TextInput's `propOf` off every commit (F-67).
+     *
+     * Set once at `createElement`, by `attachHostBehavior`. Not sticky in the `hasAriaAlias` sense:
+     * it describes the behavior's shape, and a behavior is attached once and detached whole.
+     */
+    hasCommitHook: boolean;
+    /**
+     * Whether this node's three image-source props are resolved on the way IN — see
+     * `image-source-write.ts` for why the asset lookup happens at write time and not in the payload.
+     *
+     * A boolean read per write, same shape and same reason as `hasCommitHook` above. It has to be
+     * gated on the NODE rather than applied to the key everywhere, because the resolution normalises
+     * to Image's ARRAY shape: a `WebView` or a third-party video view also spells `source`, and
+     * wrapping theirs would hand native a shape it does not read.
+     *
+     * Set once at `createElement`, by `attachHostBehavior`, for the behavior that declares it.
+     */
+    resolvesImageSources: boolean;
+    nativeIdWinsOverId: boolean;
     payloadFold: IPayloadFold | undefined;
-    structureDirty: boolean;
-    committed: IMirror | undefined;
     styleParts: IClassStyleParts | undefined;
+    childHost: ISymbioteNode | undefined;
+    wrapper: ISymbioteNode | undefined;
+    mayHaveChildren: boolean;
     measure(callback: IMeasureOnSuccess): void;
     measureInWindow(callback: IMeasureInWindowOnSuccess): void;
     measureLayout(relativeToNativeNode: ISymbioteNode | number, onSuccess: IMeasureLayoutOnSuccess, onFail?: () => void): void;
     setNativeProps(nativeProps: Record<string, unknown>): void;
     focus(): void;
     blur(): void;
-}
-export interface IMirror {
-    handle: IFabricNode;
-    tag: number;
-    rootTag: IRootTag;
-    props: IFabricProps;
-    children: readonly ISymbioteNode[];
-    viewName: string;
-    parent: ISymbioteNode | undefined;
-    owner: ISymbioteNode;
+    scrollTo(options?: {
+        x?: number;
+        y?: number;
+        animated?: boolean;
+    }): void;
+    scrollToEnd(options?: {
+        animated?: boolean;
+    }): void;
+    flashScrollIndicators(): void;
 }
 /**
- * The committed record for `node`, or `undefined` if it has never been committed - or if `node` is
- * not the raw retained node at all.
+ * Mint an element and record its creation.
  *
- * That second case is the reason this is a function rather than a bare `node.committed` read. The
- * engine identifies a node BY IDENTITY, and the classic way to break that is to hand the engine a
- * wrapper instead of the node: a Vue `reactive()`/deep-`ref()` Proxy around a host element is the
- * one that actually happens (see the vue-adapter-reactivity skill; `shallowRef` is the fix).
+ * The node object IS the handle: it is what the ops address, what the host attaches its native node
+ * to, and what Fabric hands back as an event target. Nothing else is allocated.
+ */
+export declare function createElement(component: string, isText?: boolean, tag?: string): ISymbioteNode;
+/**
+ * `tag` mirrors `createElement`'s, and a raw text needs it for the same reason an element does: the
+ * behavior registry is keyed by tag, so a node that does not hand one over cannot have a rule.
  *
- * The old WeakMap caught this for free - a Proxy is a different object, so `mirror.get(proxy)` missed
- * and every imperative API bailed with a clear "node not committed". A plain property read does NOT:
- * a Proxy forwards `proxy.committed` straight to the target and hands back a real record, whose
- * `handle` Vue would then deep-wrap on the way out. That handle is a JSI host object; a Proxy around
- * it reaches `cloneNodeWithNewProps` and fails somewhere deep in native, far from the cause.
+ * A raw text carrying a tag looks odd and is not. It has no props an app can write — its whole
+ * payload is `text` — but its CONTENT can still be a function of the platform rather than of the
+ * app: Button renders its title uppercased on Android (`Button.js:352-353`), which is a user-agent
+ * decision about a control, not anything the app asked for. That rule needs the node to be
+ * identifiable, and a tag is how this codebase identifies one.
  *
- * So the identity check that was implicit in the WeakMap is explicit here: a record written on the
- * raw node names it, and `record.owner !== node` means whatever we were handed is not that node.
- * One reference comparison, and the wrap now fails LOUDER than it used to rather than quieter.
+ * Defaulted to the raw-text component, so every existing caller is unchanged and pays the same
+ * lookup miss `createElement` already pays for a node nobody registered.
  */
-export declare function committedOf(node: ISymbioteNode): IMirror | undefined;
-export declare function createElement(component: string, isText?: boolean, tag?: string): ISymbioteNode;
-export declare function createRawText(text: string): ISymbioteNode;
+export declare function createRawText(text: string, tag?: string): ISymbioteNode;
 export declare function isSymbioteNode(value: unknown): value is ISymbioteNode;
 export declare function debugNodeId(node: ISymbioteNode): number;
 export declare const ANCHOR_COMPONENT = "#anchor";
 export declare function createAnchor(): ISymbioteNode;
+export declare const VOID_COMPONENT = "#void";
+export declare function createVoid(): ISymbioteNode;
+/**
+ * The sentinel a SURFACE's own root node carries, so `parentOf` can stop there.
+ *
+ * A top-level node must answer `undefined` for its parent, and adapters depend on the exact miss:
+ * Angular reads `null` as "defer, `<ng-content>` will place this" (answering the surface once
+ * mounted every FlatList cell at top level), while Vue and Solid spell `?? surface` at their call
+ * sites and would be handed an object that is not the `SymbioteSurface` they compare against. One
+ * component name, read in JS, keeps all three right without a second structure.
+ *
+ * It is a JS-side name only. What goes over the wire is `RCTView`, because this node is REAL.
+ */
+export declare const SURFACE_COMPONENT = "#surface";
+/**
+ * One persistent root view per surface, mirroring RN's own AppContainer — `renderApplication` wraps
+ * the app in `<View style={{flex:1}} pointerEvents="box-none">`.
+ *
+ * It is not decoration. Without `flex: 1` a non-flex root collapses to content height, and without
+ * `box-none` a touch landing outside the app's own children has no escape. Living here rather than
+ * in each adapter's `mount()` gives every framework a full-screen root for free and keeps layout in
+ * the shared layer (`<adapters_stay_thin>`).
+ *
+ * The surface therefore commits as ONE node rather than hoisting its children into the child set —
+ * which is why the host materializes the node `OP_COMMIT` names instead of walking its children. An
+ * anchor in that position still hoists, so the host handles both without a special case.
+ */
+export declare function createSurfaceRoot(): ISymbioteNode;
 export declare function isAnchor(node: ISymbioteNode): boolean;
-export declare function isEmptyRawText(node: ISymbioteNode): boolean;
 /**
  * Change which Fabric view a node commits as, keeping the node's identity.
  *
- * The commit walk already re-creates a node whose `viewName` no longer matches its committed one —
- * that is how a `<Text>` moving in or out of another `<Text>` flips between RCTText and
- * RCTVirtualText (`commit.ts`, reason `view-kind`). This exposes the same door for a prop-driven
- * view choice, so `intrinsicWhen` is honoured on UPDATE and not only at create.
- *
  * The POLICY stays out of the engine: which prop decides, and which view it decides between, lives
  * in `HOST_PRIMITIVES` and is read by `resolveIntrinsicTag` in `@symbiote-native/components`. The
  * engine only knows how to swap the name — the same split every other spec-driven fold has here.
  *
  * A no-op when the name is unchanged, so a renderer may call it on every update without comparing
  * first.
+ *
+ * The JS field and the op BOTH move, and both are load-bearing. `node.component` is what the aria
+ * fold, the behavior registry and `fabricProps` key on; the op is what makes the host re-create the
+ * node under the new name, since no prop write moves a node between native views.
  */
 export declare function setNodeComponent(node: ISymbioteNode, component: string): void;
-export declare function markDirty(node: ISymbioteNode): void;
-export declare function markPropsDirty(node: ISymbioteNode): void;
-export declare function markStructureDirty(parent: ISymbioteNode): void;
 export declare function takePropStats(): {
     writes: number;
-    noops: number;
 };
+export declare function takePropKeyTally(): ReadonlyMap<string, number>;
 export declare function setProp(node: ISymbioteNode, key: string, value: unknown): void;
+/**
+ * The one place a prop reaches the wire, and the only place that can keep a function off it.
+ *
+ * `setNativeProps` calls this rather than `recordSetProp` for that reason — it is the path that has
+ * no `routeProp` in front of it.
+ */
+export declare function writeProp(node: ISymbioteNode, key: string, value: unknown): void;
+/** What `propOf` consults before asking the host. `undefined` when nothing was stashed. */
+export declare function functionPropOf(node: ISymbioteNode, key: string): unknown;
+/**
+ * The same stash, whole — what `propsOf` layers over the host's answer.
+ *
+ * `undefined` rather than an empty Map for a node that stashed nothing, which is nearly every node:
+ * the caller then hands back the host's own object instead of copying it.
+ */
+export declare function functionPropsOf(node: ISymbioteNode): ReadonlyMap<string, unknown> | undefined;
+/**
+ * "Rebuild this node's payload — the fold reads state I just changed."
+ *
+ * A behavior whose payload is DERIVED has no prop to write: the sticky header's debounced
+ * translateY lives in its own runtime, not on the node, so nothing names the node and the host
+ * never marks it. This is the one route that says so directly.
+ *
+ * Dirtying is not publishing — pair it with `requestCommitFor` (imperative.ts).
+ */
+export declare function markPropsDirty(node: ISymbioteNode): void;
 /**
  * Install a listener the BEHAVIOR owns, bypassing the ownership check.
  *
  * `setEventListener` diverts an owned name into the stash, which is right for an app listener and
  * circular for the behavior's own dispatcher — it would stash itself and never occupy the slot it
  * exists to hold. This is the one writer allowed past that gate.
+ *
+ * `undefined` removes it, gate flag included. A behavior whose dispatcher is conditional needs
+ * that as much as it needs the install: ScrollView takes the owner's `layout` only while the app
+ * or an inverted sticky header wants it, and a one-way installer leaves `onLayout: true` standing
+ * in the payload of a ScrollView that no longer reads the event.
  */
-export declare function setBehaviorListener(node: ISymbioteNode, name: string, listener: IListener): void;
+export declare function setBehaviorListener(node: ISymbioteNode, name: string, listener: IListener | undefined): void;
 export declare function setEventListener(node: ISymbioteNode, name: string, value: unknown): void;
 export interface IClassStyleParts {
     classStyle: unknown;
@@ -115,7 +188,30 @@ export interface IClassStyleParts {
     isPressed: boolean;
     activeStyle: unknown;
     activeStyleFromCallback: boolean;
+    published: readonly unknown[] | undefined;
 }
+/**
+ * Is this rebuilt style the same style, key for key?
+ *
+ * A component body that writes its style inline hands over a FRESH object every render, equal to
+ * the one already standing — the commonest shape any app produces, and one `Object.is` cannot see.
+ * Without this the write crosses into the host, becomes a `folly::dynamic`, and is only THEN found
+ * to be unchanged. Measured on `build-release` (`no-op-rerender-cost.itest.ts`), 1 000 rows
+ * re-rendered with nothing changed: 9.7 ms against 0.3 ms for the same app with its style hoisted,
+ * and 5.2 ms of that was the conversion. The cheapest place to refuse a write is the earliest place
+ * that can see it is a no-op.
+ *
+ * SHALLOW AND CONSERVATIVE, both deliberately. A nested value (a transform list, a shadow, a style
+ * array) reports "not the same" rather than being compared deeply, because a deep compare makes this
+ * guard cost the size of the style — which is the cost it exists to avoid. Those keep crossing and
+ * the host's own `diffProps` refuses them exactly as before, so being wrong here is slow, never
+ * incorrect.
+ *
+ * `undefined` on either side also reports "not the same", which is what lets the key COUNT stand in
+ * for a key-set comparison: equal counts plus every key of `next` matching a defined value in
+ * `standing` cannot leave a key unaccounted for.
+ */
+export declare function isSameShallowStyle(next: unknown, standing: unknown): boolean;
 /**
  * Stop a node painting without unmounting it, or let it paint again.
  *
@@ -138,20 +234,55 @@ export declare function setNodeHidden(node: ISymbioteNode, hidden: boolean): voi
  * and the node is never dirtied.
  */
 export declare function setNodePressed(node: ISymbioteNode, pressed: boolean): void;
+/**
+ * Tell the host a behavior's FEEDBACK is showing — TouchableHighlight's underlay, and only that.
+ *
+ * The sibling of `setNodePressed` and deliberately NOT the same bit. Press state drives `:active`
+ * class resolution, which happens in JS because a class name resolves against a JS registry; this
+ * drives a rule that lives in C++ (`foldTouchableHighlightUnderlay`), so it crosses as one op rather
+ * than resolving to a style here. And the two are genuinely different facts: RN holds the underlay
+ * past release so a fast tap still flashes, so `shown` LAGS `pressed` by a `delayPressOut` timer.
+ *
+ * No style is computed on this side at all, which is the whole point — the two props the rule reads
+ * (`underlayColor`, `activeOpacity`) are ones the engine already strips from the payload, so the
+ * values and their defaults live in one place instead of being erased in C++ and reached around for
+ * in JS.
+ */
+export declare function setNodeUnderlayShown(node: ISymbioteNode, shown: boolean): void;
+/**
+ * Forget what was last published, so the next `pushClassStyle` cannot be turned away.
+ *
+ * The one caller is `setNativeProps` (imperative.ts), which writes the style slot past this file —
+ * see the note on `IClassStyleParts.published` for why the restore path depends on this. A no-op for
+ * a node nobody has styled, which is why it is not `stylePartsOf(node).published = undefined`: that
+ * would allocate the parts on a node that has none.
+ */
+export declare function clearPublishedStyle(node: ISymbioteNode): void;
 export declare function getExplicitStyle(node: ISymbioteNode): unknown;
+/**
+ * The `[classStyle, explicitStyle]` pair the node currently PUBLISHES — the same value
+ * `commitClassStyle` writes, in the same order, so `flattenStyle` collapses it the way Fabric will.
+ *
+ * For a caller that wants the merged answer without a host: the pair reaches the payload as an op,
+ * and only a host holds ops. A test that has not installed one — `core/css-parser` reaches into the
+ * engine by relative path and depends on neither package — can read it here instead of reaching
+ * into `styleParts`, which is engine-owned and not a shape anything outside may bind to.
+ */
+export declare function getPublishedStyle(node: ISymbioteNode): readonly unknown[];
 export declare function routeProp(node: ISymbioteNode, key: string, value: unknown): void;
 export declare function setText(node: ISymbioteNode, text: string): void;
-export declare function appendChild(parent: ISymbioteNode, child: ISymbioteNode): void;
-export declare function insertBefore(parent: ISymbioteNode, child: ISymbioteNode, beforeChild: ISymbioteNode): void;
-export declare function removeChild(parent: ISymbioteNode, child: ISymbioteNode): void;
-export interface ITreeCensus {
-    nodes: number;
-    anchors: number;
-    emptyRawTexts: number;
-    /** Nodes the commit walk actually reconciles: `nodes` minus everything it skips. */
-    renderable: number;
-    /** children.length of every parent holding at least one skipped child, widest first. */
-    flattenWidths: number[];
-}
+export declare function appendChild(requestedParent: ISymbioteNode, child: ISymbioteNode): void;
+export declare function insertBefore(requestedParent: ISymbioteNode, child: ISymbioteNode, beforeChild: ISymbioteNode | null | undefined): void;
+export declare function removeChild(requestedParent: ISymbioteNode, child: ISymbioteNode): void;
+export type { ITreeCensus } from './tree-host';
+/**
+ * A structural census of the tree the HOST holds — see `ITreeCensus` (tree-host.ts) for what each
+ * number is for and why the anchor count says more about the adapter than about the app.
+ *
+ * It walks nothing here: the walk needs `props.text` to tell an empty raw text from a real one, and
+ * a child list to measure a flatten width, and JS has neither. `undefined` from `treeHost()` means
+ * nothing is installed, and the empty census is the honest answer — every probe that reads this
+ * asserts against a mounted tree, so a zero from an uninstalled host cannot be mistaken for one from
+ * an empty one.
+ */
 export declare function censusRetainedTree(roots: readonly ISymbioteNode[]): ITreeCensus;
-export {};