@symbiote-native/engine 0.3.0 → 0.4.0

package/build/host-behavior.js

@@ -0,0 +1,262 @@
+// Per-TAG behavior on an engine node — the seam that lets a primitive's state machine live BELOW
+// the framework instead of inside a framework component.
+//
+// WHY IT EXISTS. Vue, Svelte, Solid and Angular all optimize element subtrees and stop at a
+// component boundary, so a primitive shipped as a component is charged a per-instance price in
+// each framework's own currency (an instance, a props Proxy, anchor nodes, an LView). A primitive
+// whose state the TEMPLATE never reads does not need to be a component at all — its machine only
+// needs a per-node home, and the engine node is one. `.claude/rules/host-primitive-tier.md` has
+// the tier model; this module is the tier-2 half of it.
+//
+// WHY A REGISTRY RATHER THAN A DIRECT IMPORT. `@symbiote-native/components` depends on
+// `@symbiote-native/engine`, never the reverse, so the engine cannot import `createPressHandlers`
+// and friends. CLAUDE.md's preferred answer to a registration problem — delete the indirection —
+// is therefore unavailable here; the inversion is forced, not chosen.
+//
+// WHICH MEANS THE REGISTRATION ITSELF IS THE HAZARD, and it is the one CLAUDE.md spells out:
+// Metro turns on `inlineRequires` for production only, moving a `require` down to the first place
+// its binding is used as a VALUE, and a barrel's `export { X } from './x'` compiles to a lazy
+// getter. A module whose only job is to call `registerHostBehavior` is never named as a value, so
+// re-exporting it from a barrel means it NEVER EVALUATES in a release build — dev is perfect,
+// release silently has no behavior. The one shape that works is a bare side-effect import that is
+// never re-exported from that barrel, the pattern in
+// `packages/slider/src/{react,vue,svelte,angular}/index.ts`:
+//
+//     import '../register';     // in the adapter entry — NOT `export * from '../register'`
+//
+// `registerHostBehavior` emits a `dlog` precisely so `DEBUG=1` answers "did my registration run at
+// all" before anyone starts debugging the behavior itself.
+import { dlog } from './debug.js';
+const behaviors = new Map();
+// Nodes that `removeChild` unlinked and that may or may not be coming back. See
+// `sweepDetachedBehaviors` for why the answer is not known until commit.
+const detachCandidates = new Set();
+// Nodes the sweep has torn down. A torn-down node can still be re-inserted — see
+// `reattachHostBehaviors` — and this is what tells an insert whether it must walk at all, so the
+// common case (building a fresh tree) never walks anything.
+const tornDown = new WeakSet();
+// The behavior a node actually got, remembered from its one and only registry lookup.
+//
+// THE REGISTRY IS KEYED BY INTRINSIC TAG AND THE NODE IS NOT. `node.component` is the FABRIC view
+// name: every adapter resolves the tag through `descriptorFor` before calling `createElement`, so
+// `symbiote-view` arrives as `RCTView`. Keying the registry by Fabric name instead is not an
+// option — a pressable resolves to `RCTView` like any other view, so the press machine would
+// attach to every plain `View` in the app. So the tag alphabet is used EXACTLY ONCE, at
+// `attachHostBehavior`, where the caller still holds it; every later lookup reads this map.
+//
+// Found by a peer session probing the installed shape, not by a unit test: the tests built their
+// subject with `createElement(PRESSABLE_TAG)`, which passes the tag AS the Fabric name and makes
+// the key match by accident. No adapter constructs a node that way, so the registration could
+// never have fired in an app while all six break-tests kept failing correctly on their own axes.
+const attached = new WeakMap();
+// The gate. `createElement` and `removeChild` are the two hottest paths in the engine (9 002 and
+// ~1 000 calls on one benchmark row set), so neither may pay a Set insert for a feature no app
+// uses yet. While this is false both paths cost one boolean read, the same discipline as `isDebug`.
+let hasBehaviors = false;
+export function registerHostBehavior(component, behavior) {
+    dlog(`registerHostBehavior: ${component}`);
+    behaviors.set(component, behavior);
+    hasBehaviors = true;
+}
+// Read access to the registry, so an audit can DERIVE what a behavior owns instead of restating it.
+// The one that matters: a name in `ownedListeners` is only reachable if `routeProp` also treats it
+// as a registered event — otherwise the app's callback lands in `node.props` and the machine, which
+// reads the stash, never sees it. That set difference is a test
+// (`core/components/src/behaviors/owned-listeners-are-routable.test.ts`) and it needs this to stay
+// derived rather than becoming another hand-written list.
+export function hostBehaviorFor(tag) {
+    return behaviors.get(tag);
+}
+export function hasHostBehaviors() {
+    return hasBehaviors;
+}
+// The app's listeners for names a behavior owns, per node. Not on the node: this exists only for
+// nodes carrying a behavior, and adding a field for it would pay a shape transition on every node
+// in every app for a feature almost none of them use.
+const stashed = new WeakMap();
+// Takes the NODE, not a component string: the caller (`setEventListener`) has only the Fabric name
+// by then, which is not the registry's alphabet. Reads the same map `attachHostBehavior` wrote.
+export function ownsListener(node, name) {
+    return attached.get(node)?.ownedListeners?.includes(name) === true;
+}
+export function stashAppListener(node, name, listener) {
+    let bag = stashed.get(node);
+    if (bag === undefined) {
+        bag = new Map();
+        stashed.set(node, bag);
+    }
+    if (listener === undefined)
+        bag.delete(name);
+    else
+        bag.set(name, listener);
+}
+// What the app wrote for an owned event name — the behavior's OUTPUT target. Undefined when the
+// app wired nothing, which is an ordinary case, not an error.
+export function appListenerFor(node, name) {
+    return stashed.get(node)?.get(name);
+}
+// `tag` is the INTRINSIC tag the adapter started from, not the resolved Fabric name it put on the
+// node. Defaulted to `node.component` so an adapter that has not been taught to pass it keeps
+// working for a behavior registered under a Fabric name — no adapter registers one, so in practice
+// the default simply never matches and costs one failed lookup.
+export function attachHostBehavior(node, tag) {
+    const behavior = behaviors.get(tag);
+    if (behavior === undefined)
+        return;
+    attached.set(node, behavior);
+    // A field rather than a lookup at payload-build time: `fabricProps` runs per node per commit and
+    // must not pay a Map probe to discover that almost nothing has a fold.
+    node.payloadFold = behavior.foldPayload;
+    behavior.attach(node);
+    if (behavior.attachAfterCommit !== undefined)
+        awaitingCommit.add(node);
+    if (behavior.afterCommit !== undefined)
+        committedEachTime.add(node);
+}
+// Nodes whose behavior declared `afterCommit`. Separate from `awaitingCommit` because the two have
+// opposite lifetimes: one empties as its nodes commit, this one holds until teardown.
+const committedEachTime = new Set();
+// Nodes whose behavior declared `attachAfterCommit` and whose first commit has not happened yet.
+//
+// A plain Set rather than a call into `whenCommitted`: `commit.ts` already imports this module, so
+// reaching back for it would close an import cycle. Metro's `inlineRequires` has made module
+// evaluation order a real hazard here rather than a theoretical one (see this file's own
+// registration comment), so the dependency stays one-directional and commit DRAINS this instead.
+const awaitingCommit = new Set();
+/**
+ * Run the deferred half of every behavior whose node has now been committed. Called from the commit
+ * path immediately after `completeRoot`, where fresh Fabric tags have just been assigned.
+ *
+ * `isCommitted` is passed in for the same no-cycle reason — `committedOf` lives in `commit.ts`. A
+ * still-uncommitted node stays in the set: a create superseded before it ever reached Fabric waits
+ * for the commit that lands it, and `detachSubtree` drops it if that commit never comes.
+ */
+export function runDeferredAttaches(isCommitted) {
+    // The gate: an app registering no behavior pays two Set-size reads per commit, matching the
+    // discipline `hasBehaviors` sets for `createElement`.
+    if (awaitingCommit.size === 0 && committedEachTime.size === 0)
+        return;
+    // SETUP BEFORE THE RECURRING BEAT, and the order is load-bearing on the FIRST commit, where a
+    // node carrying both hooks is drained by both. `attachAfterCommit` is where a behavior seeds the
+    // mirrors that `afterCommit` then compares against; run them the other way round and the first
+    // beat compares against nothing and commands a redundant write down to native.
+    for (const node of awaitingCommit) {
+        if (!isCommitted(node))
+            continue;
+        awaitingCommit.delete(node);
+        attached.get(node)?.attachAfterCommit?.(node);
+    }
+    for (const node of committedEachTime) {
+        if (!isCommitted(node))
+            continue;
+        attached.get(node)?.afterCommit?.(node);
+    }
+}
+// `removeChild` is NOT the destroy signal, and reading it as one is the bug this indirection
+// exists to avoid. Engine-side it looks like one — a reorder goes through `detach` inside
+// appendChild/insertBefore and never lands in removeChild — but a FRAMEWORK can spell a move as
+// remove-then-reinsert. Solid does, in `solid-js/universal`: `replaceNode` (universal.cjs:186) is
+// `insertNode` + `removeNode`, and `reconcileArrays` calls it at :157 for a node that IS in the
+// new array and is needed at a later index. Its sibling call at :130 is guarded by
+// `if (!map || !map.has(a[aStart]))` and removes only genuinely absent nodes — one guarded call
+// and one not, which is why a quick read of that file says "removeChild means gone".
+//
+// Tearing down there would kill the machine of a node that returns alive a few operations later,
+// in the same batch: long-press silently stops working after certain list reorders, on device
+// only, with nothing red. So removal only nominates.
+export function markDetachCandidate(node) {
+    detachCandidates.add(node);
+}
+// Commit is where a removal is CHEAPEST to distinguish from a move — a node unlinked and
+// reinserted before the commit is back in the tree by now, which covers Solid's replaceNode. It is
+// NOT a proof of death, and the earlier version of this comment claimed it was. Svelte parks LIVE
+// nodes offscreen across commits and sometimes across seconds: `detachFromParent`
+// (adapters/svelte/src/dom-shim/shim-node.ts) moves a node into a DocumentFragment that has no
+// engine node, calls engineRemoveChild AND requestCommit, and Svelte fully intends to bring it
+// back — from a parked `{#if}` branch, from `each.js`'s destroy_effects, and worst, from
+// boundary.js's move_effect while a pending snippet shows, which returns when async work resolves.
+// So a sweep can and does tear down a node that comes back, which is why `attach` is re-runnable
+// (reattachHostBehaviors) rather than why the sweep tries to be cleverer. The machine RESTARTS on
+// re-insert instead of surviving an arbitrary absence; a parked subtree is offscreen, so nobody is
+// mid-gesture in it, and teardown staying unconditional means there is no leak mode.
+//
+// The subtree walk lives here rather than at removal, and is cheaper for it: only the nodes that
+// actually left are walked.
+export function sweepDetachedBehaviors(topLevel) {
+    if (detachCandidates.size === 0)
+        return;
+    // A surface's top-level nodes carry `parent === undefined` by design (surface.ts), and
+    // `commitChildren` re-lists them without going through appendChild — so for those the parent
+    // check alone would report a live node as gone.
+    const seen = new Set();
+    for (const node of detachCandidates) {
+        if (node.parent !== undefined || topLevel.includes(node))
+            continue;
+        detachSubtree(node, seen);
+    }
+    detachCandidates.clear();
+}
+// `seen` guards the one overlap the candidate set can contain: a removed parent and a removed
+// descendant of it are both nominated, and without it the descendant is detached twice.
+function detachSubtree(node, seen) {
+    if (seen.has(node))
+        return;
+    seen.add(node);
+    // Marked whether or not THIS node carries a behavior: the mark is what tells a later insert to
+    // walk, and the node re-inserted is usually a plain container whose DESCENDANT holds the
+    // machine. Gating the mark on `behaviors.has` made the row wrapper unmarked and the whole walk
+    // skip — the first version of the parked-node test caught exactly that.
+    tornDown.add(node);
+    // Drop a deferral the node never got to run. NO TEST CAN SEE THIS, and it is kept anyway —
+    // stated rather than left as apparent coverage. The `isCommitted` predicate in the drain already
+    // stops such a node from firing, so removing this line changes no observable behaviour; what it
+    // changes is that a node created and torn down inside one tick stays in the Set forever, holding
+    // a strong reference to a dead subtree. A leak, not a wrong result, and this file's break-test
+    // discipline correctly reports it as unfalsifiable.
+    awaitingCommit.delete(node);
+    // The recurring hook stops with the node, and unlike the deferral above this one has a visible
+    // consequence if forgotten: a torn-down node would keep being asked to reconcile props against a
+    // subtree that has left the tree, on every commit, forever.
+    // The recurring hook stops with the node, and unlike the deferral above this one has a visible
+    // consequence if forgotten: a torn-down node would keep being asked to reconcile props against a
+    // subtree that has left the tree, on every commit, forever.
+    committedEachTime.delete(node);
+    // The map, not the registry: by here only the Fabric name is left on the node.
+    attached.get(node)?.detach(node);
+    for (const child of node.children)
+        detachSubtree(child, seen);
+}
+// Re-arms a node the sweep tore down but that the framework put back. Called from appendChild and
+// insertBefore, and it is a WeakSet miss — no walk at all — for every node in a freshly built
+// tree, which is the path that runs ~9 000 times per benchmark create.
+export function reattachHostBehaviors(node) {
+    if (!tornDown.has(node))
+        return;
+    reattachSubtree(node);
+}
+function reattachSubtree(node) {
+    if (tornDown.has(node)) {
+        tornDown.delete(node);
+        const behavior = attached.get(node);
+        behavior?.attach(node);
+        // Re-arm the deferred half too. A parked node usually returns with its tag intact, so this
+        // fires on the next drain — but re-arming is what keeps `attach` and `attachAfterCommit` a
+        // PAIR. Restore only one and a behavior that splits its setup across the two comes back
+        // half-initialised, which is the failure this seam exists to prevent.
+        if (behavior?.attachAfterCommit !== undefined)
+            awaitingCommit.add(node);
+        if (behavior?.afterCommit !== undefined)
+            committedEachTime.add(node);
+    }
+    for (const child of node.children)
+        reattachSubtree(child);
+}
+// Test-only. A registry is module state, so a suite that registers a behavior leaks it into every
+// later test in the same file unless it is cleared.
+export function clearHostBehaviors() {
+    behaviors.clear();
+    detachCandidates.clear();
+    awaitingCommit.clear();
+    committedEachTime.clear();
+    hasBehaviors = false;
+}

package/build/host-instance/index.d.ts

@@ -1,11 +1,3 @@
-import { type ISymbioteNode } from '../node';
-import type { IMeasureOnSuccess, IMeasureInWindowOnSuccess, IMeasureLayoutOnSuccess } from '../fabric';
-export interface IHostInstance extends ISymbioteNode {
-    measure(callback: IMeasureOnSuccess): void;
-    measureInWindow(callback: IMeasureInWindowOnSuccess): void;
-    measureLayout(relativeToNativeNode: IHostInstance | number, onSuccess: IMeasureLayoutOnSuccess, onFail?: () => void): void;
-    setNativeProps(nativeProps: Record<string, unknown>): void;
-    focus(): void;
-    blur(): void;
-}
+import type { ISymbioteNode } from '../node';
+export type IHostInstance = ISymbioteNode;
 export declare function toPublicInstance(node: ISymbioteNode): IHostInstance;

package/build/host-instance/index.js

@@ -1,49 +1,16 @@
-// The public instance a host ref hands back, RN's ReactFabricHostComponent. toPublicInstance
-// augments the retained node with the imperative API libraries reach through (reanimated,
-// gesture-handler, react-navigation): measure / measureInWindow / measureLayout /
-// setNativeProps / focus / blur. The methods are attached onto the node object itself (not its
-// props, so they never reach Fabric); each resolves the node's CURRENT committed handle at call
-// time through the engine, so a clone-on-write commit between calls is transparent.
+// The public instance a host ref hands back, RN's ReactFabricHostComponent: measure /
+// measureInWindow / measureLayout / setNativeProps / focus / blur, the imperative API libraries
+// reach through (reanimated, gesture-handler, react-navigation).
 //
-// This lives in the engine, not an adapter: it depends only on engine internals (the commit
-// free functions + the retained node), so every adapter inherits the SAME public instance for
-// free — React's getPublicInstance and the Vue renderer both graft this onto their host nodes.
-import { measure as engineMeasure, measureInWindow as engineMeasureInWindow, measureLayout as engineMeasureLayout, setNativeProps as engineSetNativeProps, dispatchViewCommand, } from '../commit.js';
-import { isSymbioteNode } from '../node.js';
-import { dlog } from '../debug.js';
-const FOCUS_COMMAND = 'focus';
-const BLUR_COMMAND = 'blur';
-function isHostInstance(node) {
-    return typeof Reflect.get(node, 'measure') === 'function';
-}
-// Augment the retained node with the public-instance methods, once. The same node
-// instance persists across commits, so attaching once is enough, every method reads
-// the live handle through the engine on each call.
+// EVERY retained node already carries it — the six methods live on the shared node prototype
+// (`SymbioteNode` in ../node), so there is nothing left to graft and `toPublicInstance` is the
+// identity. It used to Object.assign six fresh closures onto each node; that cost 54 000 closures
+// per 1 000-row create and made GC the largest bucket in the profile. The rationale, and why
+// React was the one adapter not paying it, is recorded on ISymbioteNode.
+//
+// The function and the type both stay: they are the seam every adapter names (React's
+// getPublicInstance, Vue's nodeOps createElement, Angular's Renderer2, Svelte's dom-shim), and a
+// call site saying "hand me the public instance" still reads correctly at a no-op.
 export function toPublicInstance(node) {
-    if (isHostInstance(node))
-        return node;
-    return Object.assign(node, {
-        measure(callback) {
-            engineMeasure(node, callback);
-        },
-        measureInWindow(callback) {
-            engineMeasureInWindow(node, callback);
-        },
-        measureLayout(relativeToNativeNode, onSuccess, onFail) {
-            if (!isSymbioteNode(relativeToNativeNode)) {
-                dlog('measureLayout: relative target must be a host ref');
-                return;
-            }
-            engineMeasureLayout(node, relativeToNativeNode, onSuccess, onFail);
-        },
-        setNativeProps(nativeProps) {
-            engineSetNativeProps(node, nativeProps);
-        },
-        focus() {
-            dispatchViewCommand(node, FOCUS_COMMAND, []);
-        },
-        blur() {
-            dispatchViewCommand(node, BLUR_COMMAND, []);
-        },
-    });
+    return node;
 }

package/build/index.d.ts

@@ -1,4 +1,4 @@
-export { createElement, createRawText, createAnchor, isAnchor, appendChild, insertBefore, removeChild, setProp, setEventListener, routeProp, censusRetainedTree, getExplicitStyle, setNodeHidden, setText, isSymbioteNode, isSymbioteEvent, RAW_TEXT_COMPONENT, debugNodeId, } from './node';
+export { createElement, createRawText, createAnchor, isAnchor, appendChild, insertBefore, removeChild, setProp, setEventListener, routeProp, censusRetainedTree, getExplicitStyle, setNodeHidden, setNodeComponent, setNodePressed, setText, isSymbioteNode, isSymbioteEvent, RAW_TEXT_COMPONENT, debugNodeId, } from './node';
 export { isEventFor } from './view-config';
 export { registerComponent, setNativeViewConfigSource } from './registry';
 export { isRecord } from './type-guards';
@@ -13,6 +13,7 @@ export { setEventDispatcher } from './dispatch';
 export { setColorProcessor, processColor, dispatchViewCommand, sendAccessibilityEvent, setNativeProps, getNativeTag, getNativeNode, whenCommitted, measure, measureInWindow, measureLayout, disposeRoot, readCommitProfile, } from './commit';
 export type { ICommitProfile } from './commit';
 export { registerPostCommit, unregisterPostCommit } from './post-commit';
+export { foldAriaProps } from './accessibility-props';
 export { toPublicInstance } from './host-instance';
 export type { IHostInstance } from './host-instance';
 export { PlatformColor, DynamicColorIOS, isOpaqueColorValue, } from './platform-color';
@@ -89,3 +90,7 @@ export type { IAccessibilityChangeEvent, IAccessibilityChangeEventName, IAccessi
 export { applyStatusBarProps, statusBarImperative, statusBarCurrentHeight, } from './status-bar';
 export { hideTransition, STATUS_BAR_MANAGER, ANIMATED_HIDE_TRANSITION, STATIC_HIDE_TRANSITION, } from './status-bar/shared';
 export type { IStatusBarProps, IStatusBarStyle, IStatusBarAnimation, IStatusBarImperative, } from './status-bar/shared';
+export { registerHostBehavior, hasHostBehaviors, hostBehaviorFor, clearHostBehaviors, appListenerFor, } from './host-behavior';
+export type { IHostBehavior } from './host-behavior';
+export { requestCommitFor } from './commit';
+export { setBehaviorListener } from './node';

package/build/index.js

@@ -2,7 +2,7 @@
 // Every framework adapter drives this tiny mutation API; all Fabric-specific
 // logic (tag allocation, view-name resolution, clone-on-write, event
 // normalization) lives behind it, in one place.
-export { createElement, createRawText, createAnchor, isAnchor, appendChild, insertBefore, removeChild, setProp, setEventListener, routeProp, censusRetainedTree, getExplicitStyle, setNodeHidden, setText, isSymbioteNode, isSymbioteEvent, RAW_TEXT_COMPONENT, debugNodeId, } from './node.js';
+export { createElement, createRawText, createAnchor, isAnchor, appendChild, insertBefore, removeChild, setProp, setEventListener, routeProp, censusRetainedTree, getExplicitStyle, setNodeHidden, setNodeComponent, setNodePressed, setText, isSymbioteNode, isSymbioteEvent, RAW_TEXT_COMPONENT, debugNodeId, } from './node.js';
 export { isEventFor } from './view-config.js';
 export { registerComponent, setNativeViewConfigSource } from './registry.js';
 // Real cross-package consumer: core/components' KeyboardAvoidingView render narrows
@@ -24,9 +24,13 @@ export { setColorProcessor, processColor, dispatchViewCommand, sendAccessibility
 // across adapters has to hang off this, not off a per-framework lifecycle hook, or it measures a
 // different quantity in each one under the same name.
 export { registerPostCommit, unregisterPostCommit } from './post-commit.js';
-// The public instance grafted onto a host node by every adapter (React's getPublicInstance,
-// the Vue renderer's createElement): the imperative measure/setNativeProps/focus API. Lives
-// here because it depends only on engine internals, so all adapters inherit it identically.
+// The aria/role -> accessibility* fold. Lives here rather than in a component wrapper because a
+// LOWERED element has no wrapper: `fabricProps` runs it on the way to the payload, so every path
+// gets it. `core/components`' typed `resolveAccessibilityProps` delegates to this one.
+export { foldAriaProps } from './accessibility-props.js';
+// The public instance every host node already is (React's getPublicInstance, the Vue renderer's
+// createElement): the imperative measure/setNativeProps/focus API, on the shared node prototype.
+// toPublicInstance is the identity that names the seam — see ./host-instance.
 export { toPublicInstance } from './host-instance/index.js';
 export { PlatformColor, DynamicColorIOS, isOpaqueColorValue, } from './platform-color/index.js';
 // CSS-style processors (boxShadow/filter): RN parses these in JS before native because
@@ -87,3 +91,6 @@ export { AccessibilityInfo } from './accessibility-info';
 // .ios re-export would otherwise duplicate-export the type symbols).
 export { applyStatusBarProps, statusBarImperative, statusBarCurrentHeight, } from './status-bar';
 export { hideTransition, STATUS_BAR_MANAGER, ANIMATED_HIDE_TRANSITION, STATIC_HIDE_TRANSITION, } from './status-bar/shared.js';
+export { registerHostBehavior, hasHostBehaviors, hostBehaviorFor, clearHostBehaviors, appListenerFor, } from './host-behavior.js';
+export { requestCommitFor } from './commit.js';
+export { setBehaviorListener } from './node.js';

package/build/node.d.ts

@@ -1,3 +1,6 @@
+import type { IFabricNode, IFabricProps, IRootTag, IMeasureOnSuccess, IMeasureInWindowOnSuccess, IMeasureLayoutOnSuccess } from './fabric';
+import { type IClassNameValue } from './style-registry';
+import { type IPayloadFold } from './host-behavior';
 declare const BRAND: unique symbol;
 export declare const RAW_TEXT_COMPONENT = "RCTRawText";
 export declare const TEXT_COMPONENT = "RCTText";
@@ -13,15 +16,57 @@ export type IListener = (event: ISymbioteEvent) => unknown;
 export declare function isSymbioteEvent(value: unknown): value is ISymbioteEvent;
 export interface ISymbioteNode {
     readonly [BRAND]: true;
-    readonly component: string;
+    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;
+    payloadFold: IPayloadFold | undefined;
+    structureDirty: boolean;
+    committed: IMirror | undefined;
+    styleParts: IClassStyleParts | undefined;
+    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 declare function createElement(component: string, isText?: boolean): ISymbioteNode;
+export interface IMirror {
+    handle: IFabricNode;
+    tag: number;
+    rootTag: IRootTag;
+    props: IFabricProps;
+    children: readonly ISymbioteNode[];
+    viewName: string;
+    parent: ISymbioteNode | undefined;
+    owner: ISymbioteNode;
+}
+/**
+ * The committed record for `node`, or `undefined` if it has never been committed - or if `node` is
+ * not the raw retained node at all.
+ *
+ * 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 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.
+ *
+ * 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.
+ */
+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 isSymbioteNode(value: unknown): value is ISymbioteNode;
 export declare function debugNodeId(node: ISymbioteNode): number;
@@ -29,13 +74,48 @@ export declare const ANCHOR_COMPONENT = "#anchor";
 export declare function createAnchor(): 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.
+ */
+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 setProp(node: ISymbioteNode, key: string, value: unknown): 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.
+ */
+export declare function setBehaviorListener(node: ISymbioteNode, name: string, listener: IListener): void;
 export declare function setEventListener(node: ISymbioteNode, name: string, value: unknown): void;
+export interface IClassStyleParts {
+    classStyle: unknown;
+    explicitStyle: unknown;
+    hiddenStyle: unknown;
+    className: IClassNameValue | undefined;
+    isPressed: boolean;
+    activeStyle: unknown;
+    activeStyleFromCallback: boolean;
+}
 /**
  * Stop a node painting without unmounting it, or let it paint again.
  *
@@ -44,6 +124,20 @@ export declare function setEventListener(node: ISymbioteNode, name: string, valu
  * author's style byte for byte — belongs to whoever owns the style merge, and that is here.
  */
 export declare function setNodeHidden(node: ISymbioteNode, hidden: boolean): void;
+/**
+ * Put a node into (or out of) its pressed state, so `.x:active` rules apply.
+ *
+ * The engine-owned half of what `:active` is on the web: the press state resolves BELOW the
+ * framework and never crosses into it, which is what lets a pressable be an intrinsic tag rather
+ * than a component (`.claude/rules/host-primitive-tier.md`, tier 2). A component is forced only
+ * when the TEMPLATE must read the state — `v-slot="{ pressed }"` and the function form of `style`
+ * — and this exists so the common case does not have to.
+ *
+ * Costs nothing when no `:active` rule is registered anywhere: `resolveActiveClassName` hands back
+ * the very same object the unpressed path returns, so `isAlreadyPublished` turns the re-push away
+ * and the node is never dirtied.
+ */
+export declare function setNodePressed(node: ISymbioteNode, pressed: boolean): void;
 export declare function getExplicitStyle(node: ISymbioteNode): unknown;
 export declare function routeProp(node: ISymbioteNode, key: string, value: unknown): void;
 export declare function setText(node: ISymbioteNode, text: string): void;