@symbiote-native/engine 1.3.0 → 1.4.0

package/build/node.d.ts

@@ -1,310 +1,8 @@
-import type { IMeasureOnSuccess, IMeasureInWindowOnSuccess, IMeasureLayoutOnSuccess } from './fabric';
-import { type IClassNameValue } from './style-registry';
-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";
-export declare const VIRTUAL_TEXT_COMPONENT = "RCTVirtualText";
-export interface ISymbioteEvent {
-    type: string;
-    target: ISymbioteNode;
-    currentTarget: ISymbioteNode;
-    nativeEvent: Record<string, unknown>;
-    stopPropagation: () => void;
-}
-export type IListener = (event: ISymbioteEvent) => unknown;
-export declare function isSymbioteEvent(value: unknown): value is ISymbioteEvent;
-export interface ISymbioteNode {
-    readonly [BRAND]: true;
-    component: string;
-    readonly isText: boolean;
-    listeners: Map<string, IListener> | undefined;
-    /**
-     * 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;
-    /**
-     * 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;
-    setNativeProps(nativeProps: Record<string, unknown>): void;
-    focus(): void;
-    blur(): void;
-    scrollTo(options?: {
-        x?: number;
-        y?: number;
-        animated?: boolean;
-    }): void;
-    scrollToEnd(options?: {
-        animated?: boolean;
-    }): void;
-    flashScrollIndicators(): void;
-}
-/**
- * Mint an element and record its creation.
- *
- * 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.
- *
- * 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.
- *
- * 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 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;
-/**
- * Change which Fabric view a node commits as, keeping the node's identity.
- *
- * 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 takePropStats(): {
-    writes: 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 | undefined): 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;
-    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.
- *
- * The seam React's `Activity`/`Suspense` reach for through `hideInstance`/`unhideInstance`. It
- * lives in the engine rather than an adapter because the reversibility problem — restoring the
- * 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;
-/**
- * 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 | undefined): void;
-export declare function removeChild(requestedParent: ISymbioteNode, child: ISymbioteNode): void;
+export { ANCHOR_COMPONENT, RAW_TEXT_COMPONENT, SURFACE_COMPONENT, TEXT_COMPONENT, VIRTUAL_TEXT_COMPONENT, VOID_COMPONENT, isAnchor, isSymbioteEvent, isSymbioteNode, type IClassStyleParts, type IEventDispatch, type IListener, type ISymbioteEvent, type ISymbioteNode, } from './node-types';
+export { createAnchor, createElement, createRawText, createSurfaceRoot, createVoid, debugNodeId, setNodeComponent, } from './node-instance';
+export { functionPropOf, functionPropsOf, markPropsDirty, setProp, setText, takePropKeyTally, takePropStats, writeProp, } from './node-props';
+export { clearPublishedStyle, getExplicitStyle, getPublishedStyle, isSameShallowStyle, setNodeHidden, setNodePressed, setNodeUnderlayShown, } from './node-style';
+export { hasListenerFor, listenerFor, setBehaviorListener, setEventListener, setNodeDispatch, } from './node-events';
+export { routeProp } from './node-route';
+export { appendChild, censusRetainedTree, insertBefore, removeChild, } from './node-tree';
 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;