@symbiote-native/engine 0.3.0 → 0.5.0

package/build/index.js

@@ -2,7 +2,15 @@
 // 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, 
+// The component name of a node the commit walk skips and whose children flatten into its parent.
+// Exported so a PRIMITIVE that renders no view of its own can be born with it — RN's
+// TouchableNativeFeedback clones onto its single child and commits nothing
+// (TouchableNativeFeedback.js:339) — rather than being converted after the fact.
+ANCHOR_COMPONENT, isAnchor, appendChild, insertBefore, removeChild, setProp, setEventListener, routeProp, censusRetainedTree, getExplicitStyle, setNodeHidden, setNodeComponent, setNodePressed, setText, isSymbioteNode, isSymbioteEvent, RAW_TEXT_COMPONENT, debugNodeId, } from './node.js';
+// For a HOST BEHAVIOR that owns an animated style layer on its own node — TouchableOpacity's press
+// fade, which RN drives from an `Animated.View` the tag replaces.
+export { setAnimatedBehaviorStyle } from './animated/host-binding.js';
 export { isEventFor } from './view-config.js';
 export { registerComponent, setNativeViewConfigSource } from './registry.js';
 // Real cross-package consumer: core/components' KeyboardAvoidingView render narrows
@@ -24,9 +32,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 { ARIA_ALIAS_KEYS, 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 +99,10 @@ 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, addDerivedNode, } from './host-behavior.js';
+export { requestCommitFor } from './commit.js';
+// `markPropsDirty` is a behavior's only way to say "the fold reads state I just changed". Every
+// other dirtying route goes through a prop write, and a behavior whose payload is DERIVED — the
+// sticky header's debounced translateY lives in its own runtime, not in `node.props` — has no
+// prop to write. Pair it with `requestCommitFor`: dirtying is not publishing.
+export { setBehaviorListener, markPropsDirty } 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,68 @@ 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;
+    childHost: ISymbioteNode | undefined;
+    wrapper: ISymbioteNode | 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;
+    scrollTo(options?: {
+        x?: number;
+        y?: number;
+        animated?: boolean;
+    }): void;
+    scrollToEnd(options?: {
+        animated?: boolean;
+    }): void;
+    flashScrollIndicators(): 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 +85,53 @@ 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.
+ *
+ * `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;
+}
 /**
  * Stop a node painting without unmounting it, or let it paint again.
  *
@@ -44,12 +140,26 @@ 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;
-export declare function appendChild(parent: ISymbioteNode, child: ISymbioteNode): void;
-export declare function insertBefore(parent: ISymbioteNode, child: ISymbioteNode, beforeChild: ISymbioteNode): void;
-export declare function removeChild(parent: ISymbioteNode, child: ISymbioteNode): void;
+export declare function appendChild(requestedParent: ISymbioteNode, child: ISymbioteNode): void;
+export declare function insertBefore(requestedParent: ISymbioteNode, child: ISymbioteNode, beforeChild: ISymbioteNode | null): void;
+export declare function removeChild(requestedParent: ISymbioteNode, child: ISymbioteNode): void;
 export interface ITreeCensus {
     nodes: number;
     anchors: number;