@symbiote-native/engine 1.3.0 → 1.4.0

package/build/accessibility-props.d.ts

@@ -1,13 +1,2 @@
 export declare const ARIA_ALIAS_KEYS: readonly ["role", "aria-label", "aria-labelledby", "aria-live", "aria-hidden", "aria-busy", "aria-checked", "aria-disabled", "aria-expanded", "aria-selected", "aria-modal", "aria-valuemax", "aria-valuemin", "aria-valuenow", "aria-valuetext"];
-/**
- * Fold the web-alias `aria-*` / `role` props into RN's canonical `accessibility*` props.
- *
- * Returns the input BY IDENTITY when no alias is present — the fast path that keeps this off the
- * hot path for the ~99% of nodes carrying none, and the property idempotence rests on: pass 1
- * blanks every alias, so a second pass finds nothing and returns by identity again.
- *
- * The alias keys are blanked to `undefined` rather than deleted. That is not laziness: `setProp`
- * treats an `undefined` write as a delete and `fabricProps` skips undefined, so a blanked alias
- * cannot reach Fabric, while a `delete` would deoptimise the object's shape on every folded node.
- */
 export declare function foldAriaProps(props: Record<string, unknown>): Record<string, unknown>;

package/build/accessibility-props.js

@@ -1,27 +1,14 @@
-// RN's `aria-*` / `role` -> `accessibility*` fold, at the layer every path goes through.
-//
-// WHY IT IS HERE AND NOT IN A WRAPPER. It used to run inside each primitive's COMPONENT, and a tag
-// has none. It also cannot run per attribute — `aria-checked` has to be folded against a sibling
-// `accessibilityState` — so it belongs at the one point where the whole bag is known, which is the
-// payload build.
-//
-// IT IS A MOVE, NOT A REWRITE, AND THAT IS DELIBERATE. The function carries TWO CONTRADICTORY
-// PRECEDENCE RULES: for the scalars an explicit `accessibility*` WINS and the alias only fills a
-// hole (`if (next.X === undefined)`), while INSIDE the `accessibilityState` / `accessibilityValue`
-// composites the ALIAS wins per field (`ariaBusy ?? existing?.busy`). Both mirror RN's View.js.
-// Anyone "cleaning this up" collapses them into one rule, and every component test stays green
-// while real accessibility silently changes. `core/components/src/accessibility-props.test.ts`
-// pins both directions; read it before touching the branches below.
-//
-// Record-level rather than typed, because the engine's caller has a raw `node.props` bag and an
-// interface is not assignable to `Record<string, unknown>` (no index signature). The typed
-// `resolveAccessibilityProps<T>` in `core/components` stays where adapters already import it and
-// delegates here, keeping its own typed gate so the fast path allocates nothing.
+// RN's aria-* / role -> accessibility* fold, at the layer every path goes through: it can't run
+// per attribute (aria-checked folds against a sibling accessibilityState), so it belongs at the
+// one point where the whole bag is known, the payload build.
+// A move, not a rewrite: the function carries two contradictory precedence rules — scalars let an
+// explicit accessibility* win, alias only fills a hole; the composites let the alias win per field
+// instead. Both mirror RN's View.js. accessibility-props.test.ts pins both directions.
+// Record-level rather than typed: the engine's caller has a raw node.props bag with no index
+// signature. The typed resolveAccessibilityProps<T> in core/components delegates here.
 import { dlog } from './debug.js';
-// Copied line for line from the wrapper this replaces. The first copy silently dropped five
-// entries (`button`, `grid`, `link`, `list`, `listitem`) — a role that falls through simply passes
-// unmapped, so `role="listitem"` would have reached Fabric as `listitem` instead of `list` with
-// nothing red anywhere. Diff this against RN's View.js rather than reading it for plausibility.
+// A role that falls through here passes unmapped, reaching Fabric under the wrong name with
+// nothing red anywhere. Diff against RN's View.js, don't just read for plausibility.
 const ROLE_TO_ACCESSIBILITY_ROLE = {
     alert: 'alert',
     button: 'button',
@@ -52,14 +39,11 @@ const ROLE_TO_ACCESSIBILITY_ROLE = {
     timer: 'timer',
     toolbar: 'toolbar',
 };
-// Exported so a behavior that folds a DIFFERENT node's bag can name them without restating the
-// list. `slotDerived` (host-behavior.ts) takes prop NAMES, so a primitive whose payload derives
-// from an owner's aria props has to enumerate them — and a second hand-written copy is exactly what
-// `.claude/rules/adapter-parity-audit.md` records going stale one member at a time.
-// `as const` rather than `readonly string[]`, so the members are LITERALS. That is what lets a
-// consumer index a prop type with them — `pickAccessibilityProps` in the Svelte adapter forwards the
-// aria half by looping this list — and it makes the two sides check each other: a name here that is
-// not a key of `IAriaProps` stops compiling at the use site rather than going quietly unforwarded.
+// Exported so a behavior folding a different node's bag can name these without restating the
+// list — slotDerived (host-behavior.ts) takes prop names, so a derived primitive enumerates them.
+// as const rather than readonly string[], so the members are literals: pickAccessibilityProps
+// (Svelte adapter) indexes IAriaProps with them, and a name here not a key of IAriaProps then
+// fails to compile at the use site instead of going quietly unforwarded.
 export const ARIA_ALIAS_KEYS = [
     'role',
     'aria-label',
@@ -86,28 +70,17 @@ function hasAnyAriaKey(props) {
     }
     return false;
 }
-// `isAriaAliasKey` WAS HERE AND IS GONE (2026-09-18). Its whole reason was to maintain
-// `node.hasAriaAlias` from `setProp` — the hottest write path in the engine, 32 001 writes on one
-// benchmark create — and that flag existed only to gate the aria fold inside the headless payload
-// builder. The fold left for `SymbioteFabricProps.cpp`, which recomputes presence from the bag it
-// holds, so the flag became write-only and this function became its only maintainer. Both went.
 function isRecord(value) {
     return typeof value === 'object' && value !== null;
 }
 function fieldOf(source, field) {
     return isRecord(source) ? source[field] : undefined;
 }
-/**
- * Fold the web-alias `aria-*` / `role` props into RN's canonical `accessibility*` props.
- *
- * Returns the input BY IDENTITY when no alias is present — the fast path that keeps this off the
- * hot path for the ~99% of nodes carrying none, and the property idempotence rests on: pass 1
- * blanks every alias, so a second pass finds nothing and returns by identity again.
- *
- * The alias keys are blanked to `undefined` rather than deleted. That is not laziness: `setProp`
- * treats an `undefined` write as a delete and `fabricProps` skips undefined, so a blanked alias
- * cannot reach Fabric, while a `delete` would deoptimise the object's shape on every folded node.
- */
+// Fold the web-alias aria-*/role props into RN's canonical accessibility* props. Returns the input
+// by identity when no alias is present, keeping this off the hot path for nodes carrying none —
+// and idempotent, since pass 1 blanks every alias so a second pass finds nothing.
+// Alias keys are blanked to undefined rather than deleted: setProp treats undefined as a delete
+// and fabricProps skips it, while a real delete would deoptimise the object's shape.
 export function foldAriaProps(props) {
     if (!hasAnyAriaKey(props))
         return props;
@@ -157,27 +130,16 @@ export function foldAriaProps(props) {
     if (typeof role === 'string' && bag.accessibilityRole === undefined) {
         bag.accessibilityRole = ROLE_TO_ACCESSIBILITY_ROLE[role] ?? role;
     }
-    // RULE TWO, INSIDE the composites: the polarity INVERTS and the ALIAS wins per field. Read from
-    // the ORIGINAL props, not from `bag` — the loop above has already blanked the aliases there.
-    //
-    // UPSTREAM-BUG(react-native): View.js:96 is `checked: ariaChecked ?? accessibilityState?.checked`
-    // — NO type coercion. A template writes `aria-checked="true"` as a STRING in every framework we
-    // support, so `accessibilityState.checked` reaches native as `'true'` where the native side
-    // declares `boolean | 'mixed'`. Ported verbatim for parity; do NOT add a cast without recording
-    // a deliberate divergence. Found by the Svelte session 2026-08-31 and pinned as an ASSERTION in
-    // `adapters/svelte/src/aria-fold-parity.test.ts`, so a future decision to coerce shows up as a
-    // failing test at the point the decision was made rather than as a silent behaviour change.
-    //
-    // A SECOND, SMALLER DIVERGENCE, and this one is ours rather than upstream's — it predates the
-    // move down and is kept only because changing it here would be an undeclared behaviour change:
-    // upstream gates the composite on `!= null` (View.js:87-92) and this gates on `!== undefined`.
-    // So an explicit `aria-busy={null}` builds an all-undefined `accessibilityState` here and builds
-    // nothing upstream. The VALUES agree either way — `??` treats null and undefined alike — so only
-    // the composite's existence differs.
-    //
-    // The composite is REPLACED by a fresh literal listing exactly the known fields, so an unknown
-    // field riding on the incoming object is dropped. Faithful to RN and pinned by a test; it is the
-    // shape of bug that only shows for whoever passes a field RN adds later.
+    // Rule two, inside the composites: the polarity inverts and the alias wins per field. Read from
+    // the original props, not bag — the loop above has already blanked the aliases there.
+    // Upstream bug, ported verbatim: RN's View.js does `checked: ariaChecked ?? accessibilityState
+    // ?.checked` with no coercion, so a string "true" reaches native where it declares boolean |
+    // 'mixed'. No cast without recording a divergence (aria-fold-parity.test.ts pins it).
+    // A second, smaller divergence, ours rather than upstream's: upstream gates the composite on
+    // `!= null`, this on `!== undefined`, so `aria-busy={null}` builds an all-undefined
+    // accessibilityState here but nothing upstream — the values agree either way.
+    // The composite is replaced by a fresh literal listing exactly the known fields, so an unknown
+    // field riding on the incoming object is dropped, faithful to RN.
     const existingState = fieldOf(props, 'accessibilityState');
     if (existingState !== undefined ||
         ariaBusy !== undefined ||

package/build/animated/graph.js

@@ -278,7 +278,7 @@ export function flushValue(rootNode) {
 // in RELEASE builds only (dev was fine, every headless test was fine, and the code was even
 // present in the bundle — it just never ran). Adding a bare `import './interpolation-node'` to
 // the barrel does NOT fix it either: Babel merges that import with the adjacent re-export of the
-// same specifier, and the merged dependency stays lazy. Both were tried on device 2026-08-14.
+// same specifier, and the merged dependency stays lazy. Both were tried on device.
 //
 // Keeping the class next to its base class removes the cycle, the factory, and the entire class
 // of load-order bug with it: `interpolate()` constructs it directly and there is nothing left to

package/build/animated/leaf-lifecycle.js

@@ -7,7 +7,7 @@
 // create-animated-component.tsx, Vue's create-animated-component.ts, Svelte's
 // animated-props-runtime.ts, Angular's animated-leaf-binder.ts). Each re-derived the same policy,
 // and they drifted: only Svelte ever grew the rebuild guard below, after a day of device
-// debugging in 2026-08. React's `useMemo(..., [rest])` LOOKS like the same guard but is not - its
+// debugging. React's `useMemo(..., [rest])` LOOKS like the same guard but is not - its
 // dependency is a fresh rest-destructured object every render - and Vue's `pendingLeaf === null`
 // answers "has render run yet", not "did anything change". A fix landing in one copy is exactly
 // what <adapters_reach_full_feature_parity> forbids: parity has to be structural.
@@ -86,7 +86,7 @@ export function createAnimatedLeafLifecycle(label) {
             lastWantsNative = wantsNative;
             // A SNAPSHOT, never the reference. A caller can legitimately hand back the SAME object on
             // every update, mutating what its keys resolve to rather than allocating (Svelte's rest
-            // proxy does exactly that, device-confirmed 2026-08-13); storing it would make the next
+            // proxy does exactly that, device-confirmed); storing it would make the next
             // call run shallowEqualProps on that object against ITSELF - reading the same current values
             // through both sides - which is unconditionally true. `propsChanged` could then never be
             // true again and reconcile would be skipped forever, so every rebuilt AnimatedInterpolation

package/build/asset-source-resolver.d.ts

@@ -0,0 +1,2 @@
+export declare function setAssetSourceResolver(resolve: (source: unknown) => unknown): void;
+export declare function resolveAssetSource(source: unknown): unknown;

package/build/asset-source-resolver.js

@@ -0,0 +1,13 @@
+// Generic asset-id resolution seam, the non-Image sibling of image-source-resolver.ts. Kept as a
+// separate file so a non-image consumer (audio's `number` source, sqlite's `assetSource`) never
+// has to import something named "image" to resolve its own assets.
+let sourceResolver = source => source;
+export function setAssetSourceResolver(resolve) {
+    sourceResolver = resolve;
+}
+// Public mirror of image-source-resolver.ts's resolveImageSource, for non-Image consumers of RN's
+// require()'d-asset resolution (audio's `number` source form, sqlite's `assetSource` option).
+// Headless (no resolver wired) it is the identity, so smokes see the input unchanged.
+export function resolveAssetSource(source) {
+    return sourceResolver(source);
+}

package/build/back-handler/index.d.ts

@@ -1,10 +1,6 @@
 import { type IEventSubscription } from '../native-events';
 declare const DEVICE_BACK_EVENT = "hardwareBackPress";
-declare const BACK_PRESS_EVENT: {
-    readonly backPress: "backPress";
-    readonly hardwareBackPress: "hardwareBackPress";
-};
-export type IBackPressEventName = (typeof BACK_PRESS_EVENT)[keyof typeof BACK_PRESS_EVENT];
+export type IBackPressEventName = 'backPress' | 'hardwareBackPress';
 export type IHardwareBackPressEvent = {
     readonly type: typeof DEVICE_BACK_EVENT;
     readonly timeStamp: number;

package/build/back-handler/index.js

@@ -17,12 +17,6 @@ import { dlog } from '../debug.js';
 const DEVICE_EVENT_MANAGER_MODULE = 'DeviceEventManager';
 // The device event native emits when the hardware back button is pressed.
 const DEVICE_BACK_EVENT = 'hardwareBackPress';
-// The public event names callers subscribe to. `backPress` is RN's legacy alias
-// for `hardwareBackPress`; both map to the same chain.
-const BACK_PRESS_EVENT = {
-    backPress: 'backPress',
-    hardwareBackPress: 'hardwareBackPress',
-};
 function nativeTimeStamp(nativeEvent) {
     if (typeof nativeEvent !== 'object' || nativeEvent === null)
         return undefined;

package/build/debug.js

@@ -1,25 +1,11 @@
-// Opt-in diagnostic logging, off by default. Two switches, either flips it on:
-//   - env: DEBUG=1 — read directly off process.env.DEBUG at call time (Node,
-//     headless smokes); each example's index.js also mirrors it onto
-//     globalThis.__SYMBIOTE_DEBUG__ once at start, so changing it needs a fresh
-//     Metro start (--reset-cache), not a rebuild.
-//   - runtime: globalThis.__SYMBIOTE_DEBUG__ = true, an escape hatch for hosts
-//     where the env isn't reachable.
-// Production with neither set pays one property read per call and nothing else -
-// but ONLY if the caller does not build the message itself first. A template
-// literal is evaluated at the CALL SITE, before dlog can decide anything, so a
-// `dlog(\`… ${JSON.stringify(x)}\`)` on a per-frame path costs its full price with
-// logging off. On a hot path (a getter Angular re-reads every change-detection
-// pass, an Animated reconcile, a scroll-driven apply) pass a THUNK instead:
-// `dlog(() => \`…\`)` - it is only called once the switch is on.
-// Read ONCE, at module load. `process.env` is not a plain object in Node - each property read
-// crosses into the host environment - and isDebug() is called on the per-node commit path, so the
-// per-call read showed up as 17% of self time in a create-path CPU profile (headless; on a native
-// host `process` is a shim and the read is cheap, so treat that figure as a Node one).
-//
-// Safe to freeze because nothing toggles the ENV switch mid-process: every runtime toggle in the
-// repo goes through __SYMBIOTE_DEBUG__ below, which stays dynamic, and bootstrap mirrors the env
-// onto it at start anyway.
+// Opt-in diagnostic logging, off by default. Two switches: env DEBUG=1 (Node, headless smokes;
+// mirrored onto globalThis.__SYMBIOTE_DEBUG__ at bootstrap, so toggling it needs a Metro
+// --reset-cache, not a rebuild), or setting globalThis.__SYMBIOTE_DEBUG__ directly.
+// Read ONCE, at module load: `process.env` is not a plain object in Node, each property read
+// crosses into the host environment, and isDebug() runs on the per-node commit path — costly in
+// Node, cheap on a native host where `process` is just a shim.
+// Safe to freeze: nothing toggles the env switch mid-process, every runtime toggle goes through
+// the dynamic __SYMBIOTE_DEBUG__ instead.
 const envDebug = typeof process !== 'undefined' && process.env.DEBUG === '1';
 export function isDebug() {
     return envDebug || globalThis.__SYMBIOTE_DEBUG__ === true;

package/build/dispatch.js

@@ -1,12 +1,6 @@
-// The one place a native event re-enters a framework's update loop. A native
-// event (a touch from Fabric, a keyboard event from the device hub) runs its
-// listener (which may call setState) OUTSIDE the framework's own loop. The
-// adapter injects a wrapper that runs the listener at the right priority and
-// flushes synchronously so the result paints (React: discrete lane +
-// flushSyncWork). Both event rails, Fabric events (events.ts) and device-module
-// events (native-events.ts), route through this single seam, so the adapter
-// wires it once and both are covered. Default is a pass-through for adapters (and
-// the headless harness) that need no wrapping.
+// The one place a native event re-enters a framework's update loop: a native event runs its
+// listener outside that loop, so the adapter injects a wrapper that runs it at the right priority
+// and flushes synchronously. Both Fabric events and device-module events share this seam.
 let wrapDispatch = run => {
     run();
 };

package/build/events/delivery.d.ts

@@ -0,0 +1,9 @@
+import { type ISymbioteNode } from '../node';
+export declare function endsWithin(endTarget: ISymbioteNode, start: ISymbioteNode): boolean;
+export declare function pathToRoot(from: ISymbioteNode): ISymbioteNode[];
+export declare function lowestCommonAncestor(a: ISymbioteNode, b: ISymbioteNode): ISymbioteNode | undefined;
+export declare function hasListenerInPath(target: ISymbioteNode, listenerName: string): boolean;
+export declare function callOwnListener(node: ISymbioteNode, listenerName: string, nativeEvent: Record<string, unknown>): unknown;
+export declare function bubble(target: ISymbioteNode, listenerName: string, nativeEvent: Record<string, unknown>): void;
+/** Direct (non-bubbling) delivery: only the target's own listener fires. */
+export declare function deliverDirect(target: ISymbioteNode, listenerName: string, nativeEvent: Record<string, unknown>): void;

package/build/events/delivery.js

@@ -0,0 +1,143 @@
+// Getting an event to the listeners that want it: the ancestor path, the two-phase bubble, direct
+// delivery, and the single-node call the responder negotiation reads a boolean back from
+import { dlog, isDebug } from '../debug.js';
+import { ancestorsOf, parentOf } from '../host-access.js';
+import { hasListenerFor, isAnchor, listenerFor, } from '../node.js';
+// A press is honest only if the touch ends on the node it started on, or a descendant of it. The
+// start node may have been unmounted mid-touch, so the walk runs out and answers false, no throw
+export function endsWithin(endTarget, start) {
+    let node = endTarget;
+    while (node) {
+        if (node === start)
+            return true;
+        node = parentOf(node);
+    }
+    return false;
+}
+// The node chain from `from` up to the root, deepest first. The single allocation the two-phase
+// walk indexes both ways (capture reads it reversed)
+// ONE CROSSING, not one per level: climbing `parentOf` crossed the host boundary each step, 18
+// questions per event on a depth-8 chain and again on every frame of every drag
+export function pathToRoot(from) {
+    return [...ancestorsOf(from)];
+}
+// Depth below the root (root = 0), to align two nodes before the lockstep climb to their lowest
+// common ancestor
+function depthOf(node) {
+    let depth = 0;
+    for (let n = parentOf(node); n; n = parentOf(n))
+        depth++;
+    return depth;
+}
+// RN's `getLowestCommonAncestor` over our parent pointers: lift the deeper node to the shallower
+// one's depth, then climb both in lockstep until they meet. Scopes the move re-negotiation
+export function lowestCommonAncestor(a, b) {
+    let da = depthOf(a);
+    let db = depthOf(b);
+    let na = a;
+    let nb = b;
+    while (na && da > db) {
+        na = parentOf(na);
+        da--;
+    }
+    while (nb && db > da) {
+        nb = parentOf(nb);
+        db--;
+    }
+    while (na && nb) {
+        if (na === nb)
+            return na;
+        na = parentOf(na);
+        nb = parentOf(nb);
+    }
+    return undefined;
+}
+// Whether any node from `target` up to the root listens for `listenerName`, so the long-press
+// timer is armed only when a handler would actually receive it
+export function hasListenerInPath(target, listenerName) {
+    for (let node = target; node; node = parentOf(node)) {
+        if (hasListenerFor(node, listenerName))
+            return true;
+    }
+    return false;
+}
+// Invoke one node's own listener (no bubbling) and hand back its return value, so the responder
+// negotiation can read the boolean from `onStartShouldSetResponder`
+export function callOwnListener(node, listenerName, nativeEvent) {
+    const listener = listenerFor(node, listenerName);
+    if (!listener)
+        return undefined;
+    return listener({
+        type: listenerName,
+        target: node,
+        currentTarget: node,
+        nativeEvent,
+        stopPropagation: () => { },
+    });
+}
+// Anchors (Angular's `#anchor` component hosts) never paint and have no native view. A listener on
+// one only exists because the framework's own output binding already delivered it directly, so
+// bubbling into it would refire the same callback twice
+function capturedBy(node, captureName) {
+    return isAnchor(node) ? undefined : listenerFor(node, captureName);
+}
+// Two-phase delivery, mirroring RN's `accumulateTwoPhaseDispatches`: CAPTURE root -> target
+// invoking each node's `<EventName>Capture` listener, then BUBBLE target -> root invoking the
+// plain one. A `stopPropagation` in capture halts before bubble ever runs
+export function bubble(target, listenerName, nativeEvent) {
+    let stopped = false;
+    const stopPropagation = () => {
+        stopped = true;
+    };
+    // Built target -> root once, then read in reverse for capture and forward for bubble. Re-walking
+    // `parentOf` for the second pass crossed the host boundary per level and was the expensive half
+    const captureName = `${listenerName}Capture`;
+    const path = pathToRoot(target);
+    for (let i = path.length - 1; i >= 0; i--) {
+        const node = path[i];
+        const listener = capturedBy(node, captureName);
+        if (listener) {
+            if (isDebug())
+                dlog(`event ${listenerName} capture on ${node.component}`);
+            listener({
+                type: listenerName,
+                target,
+                currentTarget: node,
+                nativeEvent,
+                stopPropagation,
+            });
+            if (stopped)
+                return;
+        }
+    }
+    for (const node of path) {
+        const listener = isAnchor(node)
+            ? undefined
+            : listenerFor(node, listenerName);
+        if (listener) {
+            const event = {
+                type: listenerName,
+                target,
+                currentTarget: node,
+                nativeEvent,
+                stopPropagation,
+            };
+            listener(event);
+            if (stopped)
+                return;
+        }
+    }
+}
+/** Direct (non-bubbling) delivery: only the target's own listener fires. */
+export function deliverDirect(target, listenerName, nativeEvent) {
+    const listener = listenerFor(target, listenerName);
+    if (!listener)
+        return;
+    listener({
+        type: listenerName,
+        target,
+        currentTarget: target,
+        nativeEvent,
+        stopPropagation: () => { },
+    });
+}