@symbiote-native/engine 0.5.0 → 1.1.0

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 IHostBehavior, 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,19 +19,59 @@ 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;
+    /**
+     * The behavior that attached to this node, or `undefined` for the vast majority that have none.
+     *
+     * A field for the same reason `payloadFold` above it is one, and set on the same line: every
+     * reader is a per-node path at list scale — the teardown sweep touches every node of a removed
+     * subtree, and `routeProp`'s slot/owned-listener questions run per prop write. A `WeakMap` probe
+     * is the dearest way to ask a question whose answer is almost always "none".
+     *
+     * Owned by `host-behavior.ts`; `attachHostBehavior` is the only writer.
+     */
+    hostBehavior: IHostBehavior | undefined;
     styleParts: IClassStyleParts | undefined;
     childHost: ISymbioteNode | undefined;
     wrapper: ISymbioteNode | undefined;
+    mayHaveChildren: boolean;
+    /**
+     * Whether the teardown sweep has released this node and not seen it come back.
+     *
+     * Owned by `host-behavior.ts` — see `detachOne` / `reattachHostBehaviors`. A field rather than
+     * the `WeakSet` it was, because the sweep reads and writes it for EVERY node of a removed
+     * subtree (ten thousand on a thousand-row clear) and every insert reads it to decide whether to
+     * walk at all, which is the ~9 000-call path of a create.
+     */
+    isTornDown: boolean;
+    slot: number;
+    slotBatch: number;
     measure(callback: IMeasureOnSuccess): void;
     measureInWindow(callback: IMeasureInWindowOnSuccess): void;
     measureLayout(relativeToNativeNode: ISymbioteNode | number, onSuccess: IMeasureLayoutOnSuccess, onFail?: () => void): void;
@@ -47,68 +88,106 @@ export interface ISymbioteNode {
     }): void;
     flashScrollIndicators(): void;
 }
-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.
+ * 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.
  *
@@ -131,7 +210,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.
  *
@@ -154,20 +256,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(requestedParent: ISymbioteNode, child: ISymbioteNode): void;
-export declare function insertBefore(requestedParent: ISymbioteNode, child: ISymbioteNode, beforeChild: ISymbioteNode | null): void;
+export declare function insertBefore(requestedParent: ISymbioteNode, child: ISymbioteNode, beforeChild: ISymbioteNode | null | undefined): void;
 export declare function removeChild(requestedParent: 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 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 {};