@symbiote-native/engine 0.5.0 → 1.0.0

package/build/host-access.js

@@ -0,0 +1,280 @@
+// Host access — the READ half of a DOM, which Fabric does not ship.
+//
+// Mostly navigation, plus the two value reads a seam needs (`textOf`, `propOf`). Named for the
+// whole rather than for navigation alone: this is the surface an adapter is allowed to ask a node
+// about, and keeping value reads out of it would only push them back to raw field access, which is
+// the thing being removed.
+//
+// Four of five framework renderer seams navigate the host on their hot paths, and it is their
+// contract, not our choice: Solid's nodeOps declare getParentNode / getFirstChild / getNextSibling,
+// Vue's RendererOptions declare parentNode / nextSibling, Angular's Renderer2 declares the same
+// pair, and Svelte's compiled output reaches firstChild / nextSibling as real prototype getters.
+// React is the only one that needs none, because it navigates its own fibers.
+//
+// In a browser the DOM answers these. Fabric cannot: `nativeFabricUIManager` exposes no structural
+// read at all, and RN's `NativeDOM` (which does expose getChildNodes / getParentNode) answers
+// against the CURRENT REVISION — so a node that is created, moved or removed but not yet committed
+// answers empty or null. A reconciler navigates the tree it is mid-way through BUILDING, which is
+// exactly the state no committed revision holds. See the `symbiote-fabric-cxx-surface` skill, §1a
+// and §7b.
+//
+// So these accessors exist to give adapters the navigation their seams require WITHOUT handing them
+// the node's fields. There are no fields left to hand them: since 2026-09-08 every one of these is a
+// read into the TREE HOST (`tree-host.ts`) — native on device, the TypeScript applier headlessly —
+// because JS holds no tree at all. The historical note: every seam used to read `node.parent` /
+// `node.children` directly (8 reads in Solid's renderer, 12 in Vue's, 13 in Angular's), which
+// couples each adapter to a shape that no longer exists on this side of the wire.
+//
+// Each read FLUSHES the mutation buffer first. A reconciler navigates the tree it is mid-way through
+// BUILDING, so the host has to be told about the ops recorded since the last commit before it can
+// answer. That is what `flushOps` is for, and it is why these are not simply the host's own methods.
+//
+// A survey of the three adapters that navigate (Vue, Angular, Solid) confirmed none can answer from
+// state it already holds — Vue's `RendererOptions` callbacks cannot see the vnode tree, Solid's
+// `universal.js` deliberately re-derives from the host rather than trust its own record, and Angular
+// calls `parentNode` exactly where its TNode/LView does not know. Pushing this into the adapters
+// would build three JS trees instead of the one being removed.
+import { flushOps, settleBeforeFlush, treeHost } from './tree-host.js';
+import { hasPendingPlacement } from './mutation-buffer.js';
+import { functionPropOf, functionPropsOf, isSymbioteNode, RAW_TEXT_COMPONENT, SURFACE_COMPONENT, } from './node.js';
+// One frozen empty list rather than a fresh `[]`, because the fast path in `childrenOf` is the
+// common answer during a build: solid asks 2 000 times on a 1 000-row create and every answer is
+// this.
+const NO_CHILDREN = [];
+/**
+ * The node's parent, or `undefined` for a node that sits directly under a surface.
+ *
+ * A top-level node answers `undefined` even though a surface IS a node in the host's tree, and the
+ * three adapters depend on that exact miss: Angular reads `null` as "defer, `<ng-content>` will place
+ * this", while Vue and Solid spell `?? surface` at their call sites and compare the result against
+ * the `SymbioteSurface` object, which the surface's anchor node is not. `SURFACE_COMPONENT` is the
+ * sentinel that stops the answer there.
+ *
+ * So `undefined` is not the same question as "is this node attached".
+ *
+ * IT DOES NOT ALWAYS DRAIN, unlike its neighbours. A node's parent link changes only through an op
+ * that names it as the CHILD, so a node the pending batch has not placed already has its final
+ * answer standing in the host — see `hasPendingPlacement`. Angular's 1 000-row create asks this
+ * 1 000 times (its `addLViewToLContainer` calls `renderer.parentNode` once per embedded view) and
+ * exactly ONE of those reads was about a node the batch had touched.
+ */
+export function parentOf(node) {
+    // Asked FIRST and outside the gate: an adapter holding a coalesced write has ops that are not in
+    // the buffer yet, so the gate cannot judge this node until they are. A listener that re-places
+    // this very node lands it in `hasPendingPlacement` below, which is then read after the fact.
+    settleBeforeFlush();
+    if (hasPendingPlacement(node))
+        flushOps();
+    const parent = treeHost()?.parentOf(node);
+    // A runtime guard, not a cast: the host stores handles as bare objects, and the brand is what says
+    // one of them is ours. It also refuses anything a foreign host might hand back.
+    if (!isSymbioteNode(parent))
+        return undefined;
+    return parent.component === SURFACE_COMPONENT ? undefined : parent;
+}
+/**
+ * The node's children, INCLUDING anchors.
+ *
+ * Anchors are structural bookkeeping — the commit skips them — but they are not invisible to
+ * traversal, and hiding them here would desync a framework runtime from the tree it built:
+ * solid-js/universal keeps its own record of what it inserted and re-derives positions through these
+ * lookups, so a node it placed must be a node it can find.
+ */
+export function childrenOf(node) {
+    // A READ IS A BATCH BOUNDARY, which is what makes this guard worth a field. `flushOps` below
+    // drains the buffer into the host, so a question whose answer is EMPTY still cuts the op stream
+    // in two and costs a crossing. Measured on solid's 1 000-row create: 2 000 child-list reads, every
+    // one returning zero handles, and 2 002 drains of a buffer that should have crossed twice.
+    //
+    // `mayHaveChildren` is raised by the two structural recorders in `node.ts` and never lowered, so
+    // FALSE is a certainty and TRUE only means "ask". See its declaration for why it is not a tree.
+    if (!node.mayHaveChildren)
+        return NO_CHILDREN;
+    flushOps();
+    return treeHost()?.childrenOf(node).filter(isSymbioteNode) ?? [];
+}
+/**
+ * Every node's parent, positionally, in ONE crossing — `parentOf` for a list.
+ *
+ * Engine-internal, like `subtreesOf` below, and for the same reason: what a framework seam needs is
+ * the singular form, one step at a time. These two answer the question only TEARDOWN asks, and
+ * teardown is the one lifecycle event whose size is the tree's (see `ITreeHost`).
+ *
+ * A `SURFACE_COMPONENT` parent reads as `undefined` here exactly as it does in `parentOf`, so the
+ * two agree element for element.
+ */
+export function parentsOf(nodes) {
+    flushOps();
+    const parents = treeHost()?.parentsOf(nodes);
+    if (parents === undefined)
+        return nodes.map(() => undefined);
+    return parents.map(parent => {
+        if (!isSymbioteNode(parent))
+            return undefined;
+        return parent.component === SURFACE_COMPONENT ? undefined : parent;
+    });
+}
+/** Each root and every descendant, pre-order, anchors included — all of it in ONE crossing. */
+export function subtreesOf(roots) {
+    flushOps();
+    return treeHost()?.subtreesOf(roots).filter(isSymbioteNode) ?? [];
+}
+/**
+ * The node and every ancestor above it, deepest first, in ONE crossing.
+ *
+ * `parentOf` per level is a crossing per level, and the event path needs this chain for every
+ * event — capture reads it reversed, bubble forward — plus again on every frame of a drag, for the
+ * responder's scope. Measured at 18 crossings per event on a depth-8 chain before the two phases
+ * shared a walk, 9 after, and 1 through here.
+ *
+ * Surfaces are dropped the same way `parentOf` drops them, by component, so a caller sees the same
+ * chain it would have built by walking.
+ */
+export function ancestorsOf(node) {
+    flushOps();
+    const chain = treeHost()?.ancestorsOf(node) ?? [];
+    const out = [];
+    for (const each of chain) {
+        // The same runtime guard `parentOf` applies, for the same two reasons: the host stores handles
+        // as bare objects, and a surface ends the chain rather than appearing in it.
+        if (!isSymbioteNode(each) || each.component === SURFACE_COMPONENT)
+            break;
+        out.push(each);
+    }
+    return out;
+}
+/** The first child, anchors included, or `undefined` for a leaf. */
+export function firstChildOf(node) {
+    return childrenOf(node)[0];
+}
+/**
+ * The next sibling, or `undefined` at the end of the list.
+ *
+ * `surface` is required to answer for a TOP-LEVEL node, which has no parent to read the sibling
+ * list from — the surface owns that list instead. Passing it for a parented node is harmless and
+ * ignored, so a caller with one active surface can pass it unconditionally.
+ */
+export function nextSiblingOf(node, surface) {
+    // ONE host call, not `parentOf` plus a whole child list.
+    //
+    // The previous spelling built every sibling to read one of them, and a keyed patch calls this
+    // once per row: measured on vue, appending 1 000 rows to 1 000 standing crossed 1 002 001 handles
+    // and removing them 2 002 002 — quadratic in the list, with every handle a host object built,
+    // filtered and discarded. The host holds the list and can scan it in place.
+    //
+    // `surface` is no longer read and stays in the signature because three adapters pass it: a
+    // top-level node's parent IS the surface node in the host's tree, so the host answers that case
+    // without being told which surface. The old code needed it only because `parentOf` masks a
+    // surface parent to `undefined` and there was then nothing left to ask.
+    flushOps();
+    const sibling = treeHost()?.nextSiblingOf(node);
+    return isSymbioteNode(sibling) ? sibling : undefined;
+}
+/**
+ * Whether the node is a TEXT CONTAINER (`<Text>`), not whether it holds a string.
+ *
+ * The distinction is load-bearing for adapters that ask "can I write a string into this": a raw
+ * text node answers FALSE here, and an anchor does too. Use `isRawTextNode` for that question.
+ */
+export function isTextContainer(node) {
+    return node.isText;
+}
+/**
+ * Whether the node is a RAW TEXT node — one a string can be written into.
+ *
+ * This is the question `solid-js/universal`'s `insertExpression` actually asks before calling
+ * replaceText, and answering it with `isTextContainer` would be wrong in both directions: a
+ * `<Text>` is a container that holds no string of its own, and the empty-string ANCHOR that
+ * cleanChildren leaves to hold a position is not writable either. An anchor is excluded here by
+ * construction, since its component is the `#anchor` sentinel.
+ */
+export function isRawTextNode(node) {
+    return node.component === RAW_TEXT_COMPONENT;
+}
+/**
+ * The Fabric view name this node currently resolves to (`RCTView`, `RCTText`, `RCTRawText`, the
+ * `#anchor` sentinel …). Exposed because two seams branch on it — Solid to answer `isTextNode`,
+ * Angular to recognise its own anchor hosts — and both read `node.component` directly today.
+ *
+ * NOT stable across a node's life: a primitive whose native view depends on a prop (`TextInput`'s
+ * `multiline`) changes view without changing identity. Read it, never cache it.
+ */
+export function componentOf(node) {
+    return node.component;
+}
+/**
+ * The string a raw-text node currently holds, or `undefined` for any other node.
+ *
+ * Exists for the DIAGNOSTIC path rather than the render path: a seam that rejects a bare string
+ * outside a `<Text>` wants to name the offending text in its error, and reading `node.props.text`
+ * to do so is the last thing keeping that seam coupled to the node's shape. Vue's
+ * `setElementText` reads the same value for a real reason, so this is not a one-caller accessor.
+ */
+export function textOf(node) {
+    if (node.component !== RAW_TEXT_COMPONENT)
+        return undefined;
+    flushOps();
+    const text = treeHost()?.propOf(node, 'text');
+    return typeof text === 'string' ? text : undefined;
+}
+/**
+ * The value currently standing on a prop, `undefined` if none is set.
+ *
+ * The one accessor here that reads a VALUE rather than the tree, and it earns its place from a
+ * real caller: Vue's `v-model` shim has to compose with whatever `onValueChange` the author
+ * already bound, so it must read the standing handler before writing its own. Without this the
+ * shim reaches for `el.props`, which is the last field read keeping a non-seam file coupled to the
+ * node's shape.
+ *
+ * Deliberately NOT a general property bag escape hatch: it answers what is on the node, which for
+ * `style` after a class merge is the `[classStyle, explicitStyle]` ARRAY rather than the author's
+ * object. `getExplicitStyle` exists for that question and this is not a substitute for it.
+ */
+const NO_PROPS = {};
+/**
+ * Every prop standing on the node, function props included.
+ *
+ * The bag a payload fold reads. Two sources, because a function never crossed the wire (`writeProp`,
+ * node.ts): the host holds the values it could take, JS holds the callbacks it could not, and a fold
+ * asking for `onPress` must see the one the app wrote rather than the `undefined` the host was
+ * handed in its place.
+ *
+ * A COPY when anything was stashed, the host's own object when nothing was — which is nearly every
+ * node. Same caveat as `propOf`: `style` after a class merge is the `[classStyle, explicitStyle]`
+ * array, not the author's object.
+ */
+export function propsOf(node) {
+    flushOps();
+    const stored = treeHost()?.propsOf(node) ?? NO_PROPS;
+    const stashed = functionPropsOf(node);
+    if (stashed === undefined)
+        return stored;
+    const merged = { ...stored };
+    for (const [key, value] of stashed)
+        merged[key] = value;
+    return merged;
+}
+/**
+ * A TEST read: the PAYLOAD the last commit handed Fabric for this node, `undefined` before one.
+ *
+ * `propsOf` above is the props AS THE OPS NAMED THEM — what the adapter said. This is what the
+ * payload builder MADE of them, after the aria fold, the behavior's own fold, the component-keyed
+ * folds and the style hoist. The two answer different questions and a test has to pick: "did the
+ * adapter write `inputMode`" is `propsOf`, and "did that reach native as `keyboardType`" is this.
+ *
+ * Only the native host can answer it — see `ITreeHost.committedPayloadOf`. Under the recording host
+ * it throws, on purpose, naming the itest suite as where the question belongs.
+ */
+export function committedPayloadOf(node) {
+    flushOps();
+    return treeHost()?.committedPayloadOf(node);
+}
+export function propOf(node, key) {
+    // Before the host, because a function prop never reached it — see `writeProp`. Cheap enough to be
+    // unconditional: this runs at gesture and lifecycle rate, never on a commit path.
+    const stashed = functionPropOf(node, key);
+    if (stashed !== undefined)
+        return stashed;
+    flushOps();
+    return treeHost()?.propOf(node, key);
+}

package/build/host-behavior.d.ts

@@ -2,12 +2,12 @@ import type { ISymbioteNode } from './node';
 /**
  * A pure props -> props mapping a behavior applies on the way to the Fabric payload.
  *
- * It exists because a lowered element has no component body, and a wrapper's body is where the
- * per-primitive prop FOLDS live — TextInput's W3C aliases (`inputMode` -> `keyboardType`,
- * `readOnly` -> `editable`), Pressable's `disabled` -> `accessibilityState`. Every one of those was
- * silently dropped the moment the primitive lowered: the raw alias reached Fabric as a key no
- * ViewConfig declares, so nothing threw and nothing rendered differently in a headless test —
- * only the device showed a numeric keyboard that never appeared.
+ * It exists because a tag has no component body, and a wrapper's body is where the per-primitive
+ * prop FOLDS live — TextInput's W3C aliases (`inputMode` -> `keyboardType`, `readOnly` ->
+ * `editable`), Pressable's `disabled` -> `accessibilityState`. Every one of those was silently
+ * dropped the moment the wrapper went: the raw alias reached Fabric as a key no ViewConfig
+ * declares, so nothing threw and nothing rendered differently in a headless test — only the device
+ * showed a numeric keyboard that never appeared.
  *
  * NOT a hook on `setProp`, for the same reason `afterCommit` is not: `setProp` is the hottest path
  * in the engine. This runs once per node per payload build, and only for a node whose behavior
@@ -29,23 +29,83 @@ export interface IHostBehavior {
     buildStructure?(node: ISymbioteNode): ISymbioteNode | undefined;
     attach(node: ISymbioteNode): void;
     attachAfterCommit?(node: ISymbioteNode): void;
-    onWrapChange?(owner: ISymbioteNode, wrapper: ISymbioteNode | undefined): void;
     onOwnedListenerChange?(node: ISymbioteNode, name: string, wired: boolean): void;
     afterCommit?(node: ISymbioteNode): void;
     detach(node: ISymbioteNode): void;
+    /**
+     * This primitive's own prop folds. See IPayloadFold.
+     *
+     * NO PRODUCTION BEHAVIOR DECLARES ONE since 2026-09-18 — the sticky header's was the last, and it
+     * is `foldStickyHeaderProps` in `SymbioteFabricProps.cpp` now. So this reads as a leftover, and
+     * the question this codebase asks of one is what it REACHES rather than who uses it today. Two
+     * answers, and either alone would keep it:
+     *
+     * - It is the JS ARM of every cost measurement in `tag-rule-cost.itest.ts`. That file prices a
+     *   rule by running it on both sides of the wire with the payloads asserted equal key by key
+     *   first; without a fold there is no second arm, and the ~9-31 us-per-node figures every port in
+     *   this migration was justified by could not be taken again.
+     * - It is the declared seam a third-party behavior would extend. A tag rule is ours to write in
+     *   C++; a package that ships its own primitive has no such option.
+     *
+     * What it is NOT any more is where a Symbiote primitive puts its platform props. A new one that
+     * reaches for this is one whose rule belongs in the engine — read `SymbioteFabricProps.h` first.
+     */
     readonly foldPayload?: IPayloadFold;
+    /**
+     * Resolve `source` / `defaultSource` / `loadingIndicatorSource` on the way IN — Image's, and only
+     * Image's. See `image-source-write.ts`.
+     *
+     * It is declared here rather than inferred from the tag because it is a statement about what the
+     * primitive's props MEAN, which is exactly what a behavior is for. And it is a flag rather than a
+     * function: `routeProp` is the hottest path in the engine, so what it can afford per write is a
+     * boolean read on the node, not a call into a behavior.
+     */
+    readonly resolvesImageSources?: boolean;
+    /**
+     * Flips `id`/`nativeID` precedence to nativeID-over-id — TouchableWithoutFeedback's, and only
+     * its. See `routeIdAlias` in `node.ts` for why the flip exists and which vendor file demands it.
+     */
+    readonly nativeIdWinsOverId?: boolean;
 }
 export declare function registerHostBehavior(component: string, behavior: IHostBehavior): void;
 export declare function hostBehaviorFor(tag: string): IHostBehavior | undefined;
 export declare function hasHostBehaviors(): boolean;
+/**
+ * Has a behavior ever ATTACHED to a node, as opposed to a behavior TYPE having been registered?
+ *
+ * `hasBehaviors` answers the second, and it is on from module load in every app: registering
+ * `Pressable` arms it whether or not one is ever mounted. It gates `createElement`'s attach probe
+ * correctly — a node has to be offered to the registry to find out. It gates the TEARDOWN SWEEP
+ * wrongly, and that is expensive: the sweep crosses every removed node into JS, which on a
+ * 1 000-row clear is ten thousand handles. Measured on `build-release`
+ * (`teardown-sweep-cost.itest.ts`): 1.8 ms with the sweep off against 6.3 ms with it on, i.e. 3.2x,
+ * all of it inside the commit. `Clear` is the one row where stock React Native beats every adapter.
+ *
+ * Nothing the sweep does can matter before the first attach, and the four collections say so:
+ * `attached` is written only by `attachHostBehavior`; `awaitingCommit` and `committedEachTime` are
+ * written only inside a `behavior.` branch; `parked` only by `detachAnimatedProps`, which has its
+ * own gate. The one remaining effect is marking `tornDown`, which exists so a later re-insert knows
+ * to re-arm — and there is nothing to re-arm.
+ *
+ * MONOTONE, deliberately: it turns on and never off, so it needs no accounting on a `WeakMap` that
+ * has no size and no destructor. Being late is the only way it can be wrong, and it cannot be late.
+ */
+export declare function hasAttachedBehaviors(): boolean;
 export declare function slotPropNameFor(node: ISymbioteNode, key: string): string | undefined;
 export declare function slotTakesChildren(node: ISymbioteNode): boolean;
 export declare function addDerivedNode(owner: ISymbioteNode, node: ISymbioteNode): void;
 export declare function derivedNodesOf(owner: ISymbioteNode): readonly ISymbioteNode[] | undefined;
 export declare function notifyOwnedListenerChange(node: ISymbioteNode, name: string, wired: boolean): void;
 export declare function notifyChildInserted(node: ISymbioteNode, child: ISymbioteNode): void;
-export declare function notifyWrapChange(owner: ISymbioteNode, wrapper: ISymbioteNode | undefined): void;
 export declare function claimModeFor(node: ISymbioteNode, component: string): IClaimMode | undefined;
+/**
+ * Every owner key feeds the slot. The spelling for a `cloneElement` primitive, whose slot is not
+ * derived from a named set at all — see `IHostBehavior.slotDerived`.
+ *
+ * A sentinel in the SAME array rather than a second field, so `slotDerivesFrom` stays one lookup and
+ * a behavior that wants both spellings cannot express a contradiction.
+ */
+export declare const SLOT_DERIVED_ALL = "*";
 export declare function slotDerivesFrom(node: ISymbioteNode, key: string): boolean;
 export declare function ownsListener(node: ISymbioteNode, name: string): boolean;
 export declare function stashAppListener(node: ISymbioteNode, name: string, listener: unknown): void;
@@ -61,23 +121,26 @@ export declare function attachHostBehavior(node: ISymbioteNode, tag: string): vo
  */
 export declare function runDeferredAttaches(isCommitted: (node: ISymbioteNode) => boolean): void;
 /**
- * The recurring beat. Split from `runDeferredAttaches` because the two answer different questions:
- * `attachAfterCommit` needs a FRESH FABRIC TAG, so it belongs below `completeRoot` and must not run
- * on a commit that made no native call; `afterCommit` needs only "props were published", which a
- * no-op commit satisfies just as well.
- *
- * Keeping them together made `afterCommit` unreachable for exactly the props a behavior owns: a fold
- * that STRIPS a prop makes its own commit byte-identical, `commitContainer` returns above the drain,
- * and the hook never sees the flip. TouchableOpacity's re-settle on `disabled` is the case
- * (`disabled` is a MACHINE_ONLY key), Button's `title`/`color` the other.
+ * Arm a node's recurring hook for the next commit.
  *
- * SETUP STILL RUNS BEFORE THE BEAT on the first commit, and the order is load-bearing: a node
- * carrying both hooks has `attachAfterCommit` seed the mirrors `afterCommit` compares against. The
- * caller preserves it by calling this AFTER `runDeferredAttaches` on the changed path — the no-op
- * path has no setup to run, since a node with no Fabric tag has not committed at all.
+ * Called from `setProp` — gated there on `node.hasCommitHook`, a boolean field beside
+ * `hasAriaAlias` on the same hidden class, so a node without a recurring hook pays one load and
+ * one branch per write and never reaches this.
  */
+export declare function noteCommitHookNodeChanged(node: ISymbioteNode): void;
 export declare function runCommittedHooks(isCommitted: (node: ISymbioteNode) => boolean): void;
 export declare function markDetachCandidate(node: ISymbioteNode): void;
+/**
+ * Whether the sweep has anything to do — asked BEFORE its arguments are built.
+ *
+ * The sweep's own first line already returns on an empty candidate set, and that was not enough:
+ * its caller passes `surface.children`, which is a GETTER that crosses to the host, allocates the
+ * whole top-level list and filters it into a second array. On a surface holding four thousand rows
+ * that ran on every commit, including the ones with nothing to sweep, because an argument is
+ * evaluated before the guard inside the callee can decline. Same shape as the `dlog` arguments that
+ * cost Angular 5-10% while emitting nothing.
+ */
+export declare function hasDetachCandidates(): boolean;
 export declare function sweepDetachedBehaviors(topLevel: readonly ISymbioteNode[], onDetached: (node: ISymbioteNode) => void): void;
 export declare function teardownSubtree(node: ISymbioteNode, onDetached: (node: ISymbioteNode) => void): void;
 export declare function reattachHostBehaviors(node: ISymbioteNode): void;