@symbiote-native/engine 0.1.7 → 0.3.0

package/build/animated/leaf-lifecycle.d.ts

@@ -0,0 +1,7 @@
+import type { ISymbioteNode } from '../node';
+export type IScheduleNativeBind = (bind: () => void) => (() => void) | void;
+export type IAnimatedLeafLifecycle = {
+    reconcile(props: Record<string, unknown>, node: ISymbioteNode | null, wantsNative: boolean, scheduleNativeBind?: IScheduleNativeBind): void;
+    teardown(): void;
+};
+export declare function createAnimatedLeafLifecycle(label: string): IAnimatedLeafLifecycle;

package/build/animated/leaf-lifecycle.js

@@ -0,0 +1,185 @@
+// The AnimatedProps leaf lifecycle every Animated.* wrapper needs: build a leaf from the current
+// props, swap it into the value graph, bind it to the committed node, go native when asked, and
+// rebind native event props. Framework-agnostic on purpose - it knows nothing about hooks,
+// effects, change detection or reactivity, only the engine's own Animated primitives.
+//
+// WHY THIS LIVES IN THE ENGINE. It used to live four times, once per adapter (React's
+// 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
+// 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.
+//
+// What stays in the adapter: WHEN to call reconcile (an effect, onUpdated, ngOnChanges, a $effect)
+// and HOW to find the host node (a ref, a ViewChild, a shim). Everything below is the same for all.
+import { AnimatedProps } from './props.js';
+import { attachNativeEventHandler } from './event.js';
+import { dlog } from '../debug.js';
+// Diagnostic-only, DEBUG-gated: a process-wide sequence number so every reconcile call across
+// every Animated.* instance in a log dump is individually identifiable and orderable.
+let globalReconcileSeq = 0;
+// Per-key identity comparison, NOT deep equality. A style/handler/props object that is memoized
+// upstream stays `===` across ticks that did not touch it, which is what distinguishes "same
+// content" from a real change. Deep-comparing instead would walk live AnimatedNode graphs, which
+// are circular.
+//
+// The caller MUST pass a stored SNAPSHOT as `a` - see `lastProps` below. Handing this the same
+// live object on both sides compares it with itself and is unconditionally true.
+function shallowEqualProps(a, b) {
+    const aKeys = Object.keys(a);
+    const bKeys = Object.keys(b);
+    if (aKeys.length !== bKeys.length)
+        return false;
+    for (const key of aKeys) {
+        if (a[key] !== b[key])
+            return false;
+    }
+    return true;
+}
+// Diagnostic-only. `style` here is a raw prop value, so it can be anything the caller wrote -
+// an object, an array of them, a class name, undefined. Read the field, do not assume a shape.
+function readTransform(style) {
+    if (typeof style !== 'object' || style === null)
+        return undefined;
+    return Reflect.get(style, 'transform');
+}
+// Diagnostic-only: a SHALLOW, non-serializing description of a style.transform array. Props here
+// carry RAW values - an animated entry is a live AnimatedNode in a circular parent<->children
+// graph - so JSON.stringify throws "Converting circular structure to JSON". Describe by
+// constructor name instead of walking it.
+function describeTransform(value) {
+    if (!Array.isArray(value))
+        return String(value);
+    const entries = value.map(entry => {
+        if (typeof entry !== 'object' || entry === null)
+            return String(entry);
+        const [key] = Object.keys(entry);
+        const inner = key === undefined ? undefined : Reflect.get(entry, key);
+        const innerDesc = typeof inner === 'number' || typeof inner === 'string'
+            ? String(inner)
+            : `<${inner !== null && typeof inner === 'object' ? inner.constructor.name : typeof inner}>`;
+        return `${key}:${innerDesc}`;
+    });
+    return `[${entries.join(',')}]`;
+}
+export function createAnimatedLeafLifecycle(label) {
+    let attached = null;
+    let eventDetachers = [];
+    // Diagnostic-only: the last node identity, plus a reentrancy flag to catch reconcile() being
+    // called AGAIN from inside its own call stack - the smoking-gun shape for a synchronous
+    // same-flush loop, as opposed to merely "called often".
+    let lastNode = null;
+    let inReconcile = false;
+    // Last-seen props/wantsNative for the skip below - a real content check, not diagnostics.
+    let lastProps = null;
+    let lastWantsNative = false;
+    // Canceller for a native bind the caller deferred and that has not run yet.
+    let cancelPendingBind;
+    function detachEvents() {
+        for (const detach of eventDetachers)
+            detach();
+        eventDetachers = [];
+    }
+    return {
+        reconcile(props, node, wantsNative, scheduleNativeBind) {
+            const seq = ++globalReconcileSeq;
+            const reentrant = inReconcile;
+            const nodeChanged = node !== lastNode;
+            const wantsNativeChanged = wantsNative !== lastWantsNative;
+            const propsChanged = lastProps === null || !shallowEqualProps(lastProps, props);
+            lastNode = node;
+            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
+            // 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
+            // never reaches the native graph: the view stays wired to the FIRST interpolation, built
+            // before measurement with range [-1,0]->[0,0]. One pixel of travel, which on device reads as
+            // "the sticky header ignores scrolling entirely".
+            lastProps = { ...props };
+            // Thunk, not a string: reconcile runs on EVERY update of every Animated.* wrapper in the
+            // app (Angular re-reads it on each change-detection pass), and describeTransform allocates.
+            // Built eagerly it would cost its full price with logging off.
+            dlog(() => `AnimatedProps[${label}] reconcile#${seq} reentrant=${reentrant} wantsNative=${wantsNative} ` +
+                `hasNode=${node !== null} nodeChanged=${nodeChanged} propsChanged=${propsChanged} ` +
+                `transform=${describeTransform(readTransform(props.style))}`);
+            if (reentrant) {
+                dlog(`AnimatedProps[${label}] reconcile#${seq} *** RE-ENTRANT CALL DETECTED - see reconcile above ***`);
+            }
+            // Nothing meaningfully changed since the last call AND we are already natively connected
+            // (steady state) - skip tearing down and rebuilding the native AnimatedProps graph.
+            //
+            // Deliberately scoped to `attached.__isNative()` ONLY: before the first native connection,
+            // reconcile must run unconditionally on every tick - that cadence is what wires a rebuilt
+            // interpolation node into the shared value's children (AnimatedInterpolation.__attach ->
+            // parent.__addChild, cascaded from AnimatedProps.__attach); skipping there can leave a
+            // freshly rebuilt interpolation never attached, so its listener never fires. Once native and
+            // staying native, that bootstrap concern is moot - and rebuilding there was the
+            // collision-disappearance bug: every scroll-driven passthrough tick reconnected a brand new
+            // native node (restoreDefaultValues + connect) even though nothing animated-relevant had
+            // changed, and a reconnect landing exactly when scrolling stopped left the view frozen at
+            // its post-reset default until the next tick.
+            if (attached !== null &&
+                attached.__isNative() &&
+                !nodeChanged &&
+                !wantsNativeChanged &&
+                !propsChanged) {
+                dlog(`AnimatedProps[${label}] reconcile#${seq} skipped (no-op: already native, props/node unchanged)`);
+                return;
+            }
+            inReconcile = true;
+            try {
+                // Attach the NEW leaf BEFORE detaching the OLD one: a shared Value self-detaches (dropping
+                // its native node) the instant its child count hits zero, so detaching first would kill a
+                // running native animation on any unrelated update. Mirrors RN's
+                // AnimatedComponent._attachProps.
+                const newLeaf = new AnimatedProps(props);
+                newLeaf.__attach();
+                if (attached !== null && attached !== newLeaf)
+                    attached.__detach();
+                attached = newLeaf;
+                // The native half, which a caller may defer. Rebinds events each reconcile so a new inline
+                // event re-attaches, detaching first so the prior binding does not leak;
+                // attachNativeEventHandler no-ops unless the prop really is a native event handler on a
+                // committed node, so the JS path stays the fallback.
+                const bindNative = () => {
+                    if (node !== null)
+                        newLeaf.setNativeView(node);
+                    if (wantsNative)
+                        newLeaf.__makeNative();
+                    detachEvents();
+                    if (node === null)
+                        return;
+                    for (const key of Object.keys(props)) {
+                        const attachment = attachNativeEventHandler(node, key, props[key]);
+                        if (attachment !== undefined)
+                            eventDetachers.push(attachment.detach);
+                    }
+                };
+                cancelPendingBind?.();
+                cancelPendingBind = undefined;
+                if (scheduleNativeBind === undefined || node === null) {
+                    bindNative();
+                    return;
+                }
+                cancelPendingBind = scheduleNativeBind(bindNative) ?? undefined;
+            }
+            finally {
+                inReconcile = false;
+            }
+        },
+        teardown() {
+            cancelPendingBind?.();
+            cancelPendingBind = undefined;
+            detachEvents();
+            if (attached !== null) {
+                attached.__detach();
+                attached = null;
+            }
+        },
+    };
+}

package/build/animated/mock.js

@@ -11,7 +11,7 @@ import { AnimatedValueXY } from './value-xy.js';
 import { AnimatedColor } from './color.js';
 import { AnimatedNode } from './graph.js';
 import { Easing } from './easing.js';
-import { add, subtract, multiply, divide, modulo, diffClamp } from './operators.js';
+import { add, subtract, multiply, divide, modulo, diffClamp, } from './operators.js';
 import { event, forkEvent, unforkEvent } from './event.js';
 import { dlog } from '../debug.js';
 // Prevent a callback invocation from recursively triggering another callback,

package/build/animated/native/native-animated.js

@@ -11,7 +11,7 @@
 // native host) is inert until a native-driven animation actually starts.
 import { dlog } from '../../debug.js';
 import { getNativeModule } from '../../native-modules/index.js';
-import { NativeEventEmitter } from '../../native-events.js';
+import { NativeEventEmitter, } from '../../native-events.js';
 import { isRecord } from '../../type-guards.js';
 // iOS bridgeless registers the Turbo variant; the legacy name is the fallback.
 const TURBO_MODULE_NAME = 'NativeAnimatedTurboModule';
@@ -101,6 +101,7 @@ export const nativeAnimated = {
         module()?.stopAnimation(animationId);
     },
     setAnimatedNodeValue(nodeTag, value) {
+        dlog(`native: setAnimatedNodeValue node=${nodeTag} value=${value}`);
         module()?.setAnimatedNodeValue(nodeTag, value);
     },
     setAnimatedNodeOffset(nodeTag, offset) {

package/build/animated/operators.js

@@ -57,7 +57,10 @@ export class AnimatedAddition extends AnimatedBinaryOp {
         return a + b;
     }
     __getNativeConfig() {
-        return { type: 'addition', input: [this.a.__getNativeTag(), this.b.__getNativeTag()] };
+        return {
+            type: 'addition',
+            input: [this.a.__getNativeTag(), this.b.__getNativeTag()],
+        };
     }
 }
 export class AnimatedSubtraction extends AnimatedBinaryOp {
@@ -65,7 +68,10 @@ export class AnimatedSubtraction extends AnimatedBinaryOp {
         return a - b;
     }
     __getNativeConfig() {
-        return { type: 'subtraction', input: [this.a.__getNativeTag(), this.b.__getNativeTag()] };
+        return {
+            type: 'subtraction',
+            input: [this.a.__getNativeTag(), this.b.__getNativeTag()],
+        };
     }
 }
 export class AnimatedMultiplication extends AnimatedBinaryOp {
@@ -73,7 +79,10 @@ export class AnimatedMultiplication extends AnimatedBinaryOp {
         return a * b;
     }
     __getNativeConfig() {
-        return { type: 'multiplication', input: [this.a.__getNativeTag(), this.b.__getNativeTag()] };
+        return {
+            type: 'multiplication',
+            input: [this.a.__getNativeTag(), this.b.__getNativeTag()],
+        };
     }
 }
 export class AnimatedDivision extends AnimatedBinaryOp {
@@ -97,7 +106,10 @@ export class AnimatedDivision extends AnimatedBinaryOp {
         return a / b;
     }
     __getNativeConfig() {
-        return { type: 'division', input: [this.a.__getNativeTag(), this.b.__getNativeTag()] };
+        return {
+            type: 'division',
+            input: [this.a.__getNativeTag(), this.b.__getNativeTag()],
+        };
     }
 }
 export class AnimatedModulo extends AnimatedWithChildren {
@@ -127,7 +139,11 @@ export class AnimatedModulo extends AnimatedWithChildren {
         super.__makeNative(platformConfig);
     }
     __getNativeConfig() {
-        return { type: 'modulus', input: this.a.__getNativeTag(), modulus: this.modulus };
+        return {
+            type: 'modulus',
+            input: this.a.__getNativeTag(),
+            modulus: this.modulus,
+        };
     }
 }
 export class AnimatedDiffClamp extends AnimatedWithChildren {
@@ -167,7 +183,12 @@ export class AnimatedDiffClamp extends AnimatedWithChildren {
         super.__makeNative(platformConfig);
     }
     __getNativeConfig() {
-        return { type: 'diffclamp', input: this.a.__getNativeTag(), min: this.min, max: this.max };
+        return {
+            type: 'diffclamp',
+            input: this.a.__getNativeTag(),
+            min: this.min,
+            max: this.max,
+        };
     }
 }
 export function add(a, b) {

package/build/animated/props.js

@@ -15,7 +15,7 @@ import { AnimatedNode, AnimatedWithChildren } from './graph.js';
 import { setNativeProps, getNativeTag } from '../commit.js';
 import { isSymbioteNode } from '../node.js';
 import { registerPostCommit } from '../post-commit.js';
-import { nativeAnimated } from './native/native-animated.js';
+import { nativeAnimated, } from './native/native-animated.js';
 import { AnimatedStyle } from './style.js';
 function isAnimatedNode(value) {
     return value instanceof AnimatedNode;

package/build/animated/rgba.d.ts

@@ -0,0 +1,8 @@
+export interface IRgbaValue {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+export declare const DEFAULT_COLOR: IRgbaValue;
+export declare function normalizeColor(color: string | number): IRgbaValue | undefined;

package/build/animated/rgba.js

@@ -0,0 +1,70 @@
+// Pure RGBA parsing — no graph node, no AnimatedValue, no imports from this package at all.
+//
+// It is split out of color.ts DELIBERATELY, and must stay dependency-free. `interpolation.ts`
+// needs `normalizeColor` for its color output ranges, and `graph.ts` needs `interpolation.ts`
+// (AnimatedInterpolation lives there). color.ts also defines `AnimatedColor extends
+// AnimatedWithChildren`, so leaving the parser there closes a cycle
+//   graph -> interpolation -> color -> graph
+// which surfaces at load time as `TypeError: Class extends value undefined is not a
+// constructor` — AnimatedWithChildren is still uninitialized when color.ts evaluates. Keeping
+// the pure half in its own leaf module breaks it structurally rather than by import ordering.
+export const DEFAULT_COLOR = { r: 0, g: 0, b: 0, a: 1 };
+// Decompose a #hex (3/4/6/8), rgb()/rgba(), or 0xRRGGBBAA number into channels.
+// undefined when unparseable (a named/platform color), so the caller falls back to
+// the default rather than throwing inside a render. Exported so interpolation's
+// color path parses through the same RGBA decoder (DRY) rather than duplicating it.
+export function normalizeColor(color) {
+    if (typeof color === 'number') {
+        const c = color >>> 0;
+        return {
+            r: (c >>> 24) & 255,
+            g: (c >>> 16) & 255,
+            b: (c >>> 8) & 255,
+            a: (c & 255) / 255,
+        };
+    }
+    const trimmed = color.trim();
+    if (trimmed.startsWith('#'))
+        return parseHex(trimmed);
+    if (/^rgba?\(/i.test(trimmed))
+        return parseRgb(trimmed);
+    return undefined;
+}
+function parseHex(hex) {
+    let body = hex.slice(1);
+    if (body.length === 3 || body.length === 4) {
+        body = body
+            .split('')
+            .map(c => c + c)
+            .join('');
+    }
+    if (body.length !== 6 && body.length !== 8)
+        return undefined;
+    const int = Number.parseInt(body, 16);
+    if (Number.isNaN(int))
+        return undefined;
+    if (body.length === 6) {
+        return { r: (int >>> 16) & 255, g: (int >>> 8) & 255, b: int & 255, a: 1 };
+    }
+    const c = int >>> 0;
+    return {
+        r: (c >>> 24) & 255,
+        g: (c >>> 16) & 255,
+        b: (c >>> 8) & 255,
+        a: (c & 255) / 255,
+    };
+}
+function parseRgb(str) {
+    const match = /^rgba?\(([^)]+)\)$/i.exec(str);
+    if (match === null)
+        return undefined;
+    const parts = match[1].split(',').map(part => Number.parseFloat(part.trim()));
+    if (parts.length < 3 || parts.some(n => Number.isNaN(n)))
+        return undefined;
+    return {
+        r: parts[0],
+        g: parts[1],
+        b: parts[2],
+        a: parts.length >= 4 ? parts[3] : 1,
+    };
+}

package/build/animated/style.js

@@ -73,7 +73,9 @@ export class AnimatedTransform extends AnimatedWithChildren {
             const result = {};
             for (const key of Object.keys(entry)) {
                 const value = entry[key];
-                result[key] = isAnimatedNode(value) ? value.__getAnimatedValue() : value;
+                result[key] = isAnimatedNode(value)
+                    ? value.__getAnimatedValue()
+                    : value;
             }
             return result;
         });
@@ -96,10 +98,18 @@ export class AnimatedTransform extends AnimatedWithChildren {
                 const value = entry[key];
                 if (isAnimatedNode(value)) {
                     // __getNativeTag only: creation is edge-free; the connect is a later phase.
-                    transforms.push({ type: 'animated', property: key, nodeTag: value.__getNativeTag() });
+                    transforms.push({
+                        type: 'animated',
+                        property: key,
+                        nodeTag: value.__getNativeTag(),
+                    });
                 }
                 else {
-                    transforms.push({ type: 'static', property: key, value: transformDataType(value) });
+                    transforms.push({
+                        type: 'static',
+                        property: key,
+                        value: transformDataType(value),
+                    });
                 }
             }
         }

package/build/animated/value-xy.d.ts

@@ -26,10 +26,13 @@ export declare class AnimatedValueXY {
         left: AnimatedValue;
         top: AnimatedValue;
     };
-    getTranslateTransform(): [{
-        translateX: AnimatedValue;
-    }, {
-        translateY: AnimatedValue;
-    }];
+    getTranslateTransform(): [
+        {
+            translateX: AnimatedValue;
+        },
+        {
+            translateY: AnimatedValue;
+        }
+    ];
 }
 export {};

package/build/animated/value-xy.js

@@ -17,7 +17,10 @@ export class AnimatedValueXY {
     // Each joint id maps to the two per-axis listener ids it registered, so
     // removeListener can tear both down together.
     jointListeners = new Map();
-    constructor(value = { x: 0, y: 0 }) {
+    constructor(value = {
+        x: 0,
+        y: 0,
+    }) {
         if (typeof value.x === 'number' && typeof value.y === 'number') {
             this.x = new AnimatedValue(value.x);
             this.y = new AnimatedValue(value.y);

package/build/animated/value.js

@@ -119,13 +119,12 @@ export class AnimatedValue extends AnimatedWithChildren {
             this.offset = offset;
         }
     }
-    // Own the native-driver "start" handshake end-to-end: make this value native, mint
+    // Owns the native-driver "start" handshake end-to-end: make this value native, mint
     // its tag, hand the curve to the native module, and on completion sync the JS value
-    // (no re-flush to bound leaves' native side; native already moved the view). A
-    // driver (BaseAnimation.startNativeIfNeeded) supplies only what IT owns: the curve
-    // config, its own animation id, its platform bag, and its own end callback, never
-    // touching __makeNative / __getNativeTag / __onNativeUpdate / flushValue directly.
-    // Information Expert: this value is the one object that actually holds those internals.
+    // (no re-flush; native already moved the view). The driver (BaseAnimation.
+    // startNativeIfNeeded) supplies only what it owns - curve config, animation id,
+    // platform bag, end callback - never touching __makeNative / __getNativeTag /
+    // __onNativeUpdate / flushValue directly; those internals live here.
     __startNativeAnimation(config, nativeId, onEnd, platformConfig) {
         this.__makeNative(platformConfig);
         nativeAnimated.startAnimatingNode(nativeId, this.__getNativeTag(), config, result => {
@@ -164,10 +163,16 @@ export class AnimatedValue extends AnimatedWithChildren {
             this.tracking = null;
         }
     }
-    // Stop any animation and reset to the original value.
+    // Stop any animation and reset to the original value. The native graph keeps its OWN copy of
+    // the value, so a native-driven node has to be told as well - otherwise the reset lands in JS
+    // only and the view stays wherever the animation left it. setValue above pushes for the same
+    // reason; RN pushes here too (Libraries/Animated/nodes/AnimatedValue.js:285).
     resetAnimation(callback) {
         this.stopAnimation(callback);
         this.value = this.startingValue;
+        if (this.isNative) {
+            nativeAnimated.setAnimatedNodeValue(this.__getNativeTag(), this.startingValue);
+        }
     }
     // Drive this value with an animation. Typically called by Animated.timing /
     // spring / decay rather than directly.

package/build/appearance/index.js

@@ -62,7 +62,10 @@ export const Appearance = {
             return;
         }
         module.setColorScheme(colorScheme);
-        cachedScheme = colorScheme === 'unspecified' ? (module.getColorScheme() ?? null) : colorScheme;
+        cachedScheme =
+            colorScheme === 'unspecified'
+                ? (module.getColorScheme() ?? null)
+                : colorScheme;
     },
     // Subscribe to color-scheme changes. The listener receives `{ colorScheme }`.
     addChangeListener(listener) {

package/build/commit.d.ts

@@ -3,6 +3,19 @@ import { type ISymbioteNode } from './node';
 export { processColor, setColorProcessor } from './platform-color';
 export declare function disposeRoot(rootTag: IRootTag): void;
 export declare function commitChildren(rootTag: IRootTag, children: readonly ISymbioteNode[]): void;
+export interface ICommitProfile {
+    commits: number;
+    walkMs: number;
+    nodesVisited: number;
+    propWrites: number;
+    propNoops: number;
+    childScans: number;
+    childScanProbed: number;
+    childFlattens: number;
+    childFlattenProbed: number;
+    childFlattenWidest: number;
+}
+export declare function readCommitProfile(): ICommitProfile;
 export declare function setNativeProps(node: ISymbioteNode, partial: Record<string, unknown>): void;
 export declare function getNativeTag(node: ISymbioteNode): number | undefined;
 export declare function whenCommitted(node: ISymbioteNode, action: () => void): () => void;