@symbiote-native/engine 0.1.0

package/build/animated/operators.js

@@ -0,0 +1,266 @@
+// Arithmetic / operator graph nodes: add, subtract, multiply, divide, modulo,
+// diffClamp. Each composes one or two upstream values into a derived value.
+// Ported from RN's AnimatedAddition / AnimatedSubtraction / AnimatedMultiplication
+// / AnimatedDivision / AnimatedModulo / AnimatedDiffClamp, numeric path only.
+//
+// Each node is an AnimatedWithChildren: its OWN children array holds downstream
+// consumers (wired by the base __connectNativeChildren), while its INPUTS are held
+// separately and wired by registering this node as a child of each input at
+// __attach (input.__addChild(this)). __getNativeConfig is creation-only: it reads
+// each input's native tag (creating the input node) but issues no connect.
+import { AnimatedNode, AnimatedWithChildren } from './graph';
+import { AnimatedValue } from './value';
+import { AnimatedInterpolation } from './interpolation-node';
+import { dlog } from '../debug';
+// Wrap a bare number in an AnimatedValue so every input is a graph node.
+function toNode(input) {
+    return typeof input === 'number' ? new AnimatedValue(input) : input;
+}
+function numericValue(node) {
+    const value = node.__getValue();
+    if (typeof value !== 'number') {
+        throw new Error('Animated operator input did not resolve to a number');
+    }
+    return value;
+}
+export class AnimatedAddition extends AnimatedWithChildren {
+    a;
+    b;
+    constructor(a, b) {
+        super();
+        this.a = toNode(a);
+        this.b = toNode(b);
+    }
+    __getValue() {
+        return numericValue(this.a) + numericValue(this.b);
+    }
+    interpolate(config) {
+        return new AnimatedInterpolation(this, config);
+    }
+    __attach() {
+        this.a.__addChild(this);
+        this.b.__addChild(this);
+        super.__attach();
+    }
+    __detach() {
+        this.a.__removeChild(this);
+        this.b.__removeChild(this);
+        super.__detach();
+    }
+    __makeNative(platformConfig) {
+        this.a.__makeNative(platformConfig);
+        this.b.__makeNative(platformConfig);
+        super.__makeNative(platformConfig);
+    }
+    __getNativeConfig() {
+        return { type: 'addition', input: [this.a.__getNativeTag(), this.b.__getNativeTag()] };
+    }
+}
+export class AnimatedSubtraction extends AnimatedWithChildren {
+    a;
+    b;
+    constructor(a, b) {
+        super();
+        this.a = toNode(a);
+        this.b = toNode(b);
+    }
+    __getValue() {
+        return numericValue(this.a) - numericValue(this.b);
+    }
+    interpolate(config) {
+        return new AnimatedInterpolation(this, config);
+    }
+    __attach() {
+        this.a.__addChild(this);
+        this.b.__addChild(this);
+        super.__attach();
+    }
+    __detach() {
+        this.a.__removeChild(this);
+        this.b.__removeChild(this);
+        super.__detach();
+    }
+    __makeNative(platformConfig) {
+        this.a.__makeNative(platformConfig);
+        this.b.__makeNative(platformConfig);
+        super.__makeNative(platformConfig);
+    }
+    __getNativeConfig() {
+        return { type: 'subtraction', input: [this.a.__getNativeTag(), this.b.__getNativeTag()] };
+    }
+}
+export class AnimatedMultiplication extends AnimatedWithChildren {
+    a;
+    b;
+    constructor(a, b) {
+        super();
+        this.a = toNode(a);
+        this.b = toNode(b);
+    }
+    __getValue() {
+        return numericValue(this.a) * numericValue(this.b);
+    }
+    interpolate(config) {
+        return new AnimatedInterpolation(this, config);
+    }
+    __attach() {
+        this.a.__addChild(this);
+        this.b.__addChild(this);
+        super.__attach();
+    }
+    __detach() {
+        this.a.__removeChild(this);
+        this.b.__removeChild(this);
+        super.__detach();
+    }
+    __makeNative(platformConfig) {
+        this.a.__makeNative(platformConfig);
+        this.b.__makeNative(platformConfig);
+        super.__makeNative(platformConfig);
+    }
+    __getNativeConfig() {
+        return { type: 'multiplication', input: [this.a.__getNativeTag(), this.b.__getNativeTag()] };
+    }
+}
+export class AnimatedDivision extends AnimatedWithChildren {
+    a;
+    b;
+    warnedAboutDivideByZero = false;
+    constructor(a, b) {
+        super();
+        if (b === 0 || (b instanceof AnimatedNode && b.__getValue() === 0)) {
+            dlog('AnimatedDivision: detected potential division by zero');
+        }
+        this.a = toNode(a);
+        this.b = toNode(b);
+    }
+    __getValue() {
+        const a = numericValue(this.a);
+        const b = numericValue(this.b);
+        if (b === 0) {
+            // A divide-by-zero yields Infinity/NaN, which crashes Fabric, so clamp to 0.
+            if (!this.warnedAboutDivideByZero) {
+                dlog('AnimatedDivision: detected division by zero');
+                this.warnedAboutDivideByZero = true;
+            }
+            return 0;
+        }
+        this.warnedAboutDivideByZero = false;
+        return a / b;
+    }
+    interpolate(config) {
+        return new AnimatedInterpolation(this, config);
+    }
+    __attach() {
+        this.a.__addChild(this);
+        this.b.__addChild(this);
+        super.__attach();
+    }
+    __detach() {
+        this.a.__removeChild(this);
+        this.b.__removeChild(this);
+        super.__detach();
+    }
+    __makeNative(platformConfig) {
+        this.a.__makeNative(platformConfig);
+        this.b.__makeNative(platformConfig);
+        super.__makeNative(platformConfig);
+    }
+    __getNativeConfig() {
+        return { type: 'division', input: [this.a.__getNativeTag(), this.b.__getNativeTag()] };
+    }
+}
+export class AnimatedModulo extends AnimatedWithChildren {
+    a;
+    modulus;
+    constructor(a, modulus) {
+        super();
+        this.a = a;
+        this.modulus = modulus;
+    }
+    // Euclidean modulo: always lands in [0, modulus), unlike JS % which keeps the
+    // dividend's sign.
+    __getValue() {
+        const a = numericValue(this.a);
+        return ((a % this.modulus) + this.modulus) % this.modulus;
+    }
+    interpolate(config) {
+        return new AnimatedInterpolation(this, config);
+    }
+    __attach() {
+        this.a.__addChild(this);
+        super.__attach();
+    }
+    __detach() {
+        this.a.__removeChild(this);
+        super.__detach();
+    }
+    __makeNative(platformConfig) {
+        this.a.__makeNative(platformConfig);
+        super.__makeNative(platformConfig);
+    }
+    __getNativeConfig() {
+        return { type: 'modulus', input: this.a.__getNativeTag(), modulus: this.modulus };
+    }
+}
+export class AnimatedDiffClamp extends AnimatedWithChildren {
+    a;
+    min;
+    max;
+    value;
+    lastValue;
+    constructor(a, min, max) {
+        super();
+        this.a = a;
+        this.min = min;
+        this.max = max;
+        this.value = numericValue(a);
+        this.lastValue = this.value;
+    }
+    // Accumulate the input's frame-to-frame DELTA and clamp the running total to
+    // [min, max]. The output tracks the input but never drifts past the band: the
+    // classic collapsing-header pattern.
+    __getValue() {
+        const value = numericValue(this.a);
+        const diff = value - this.lastValue;
+        this.lastValue = value;
+        this.value = Math.min(Math.max(this.value + diff, this.min), this.max);
+        return this.value;
+    }
+    interpolate(config) {
+        return new AnimatedInterpolation(this, config);
+    }
+    __attach() {
+        this.a.__addChild(this);
+        super.__attach();
+    }
+    __detach() {
+        this.a.__removeChild(this);
+        super.__detach();
+    }
+    __makeNative(platformConfig) {
+        this.a.__makeNative(platformConfig);
+        super.__makeNative(platformConfig);
+    }
+    __getNativeConfig() {
+        return { type: 'diffclamp', input: this.a.__getNativeTag(), min: this.min, max: this.max };
+    }
+}
+export function add(a, b) {
+    return new AnimatedAddition(a, b);
+}
+export function subtract(a, b) {
+    return new AnimatedSubtraction(a, b);
+}
+export function multiply(a, b) {
+    return new AnimatedMultiplication(a, b);
+}
+export function divide(a, b) {
+    return new AnimatedDivision(a, b);
+}
+export function modulo(a, modulus) {
+    return new AnimatedModulo(a, modulus);
+}
+export function diffClamp(a, min, max) {
+    return new AnimatedDiffClamp(a, min, max);
+}

package/build/animated/props.d.ts

@@ -0,0 +1,20 @@
+import { AnimatedWithChildren } from './graph';
+import { type INativeNodeConfig } from './native/native-animated';
+export declare class AnimatedProps extends AnimatedWithChildren {
+    private readonly nodes;
+    private readonly props;
+    private target;
+    private connectedViewTag;
+    constructor(inputProps: Record<string, unknown>);
+    __getValue(): Record<string, unknown>;
+    __getAnimatedValue(): Record<string, unknown>;
+    setNativeView(instance: unknown): void;
+    update(): void;
+    __attach(): void;
+    __detach(): void;
+    __makeNative(): void;
+    private connectToView;
+    retryViewConnect(): void;
+    private disconnectFromView;
+    __getNativeConfig(): INativeNodeConfig;
+}

package/build/animated/props.js

@@ -0,0 +1,187 @@
+// AnimatedProps: the leaf where the value graph meets symbiote's commit engine.
+// It holds the host SymbioteNode (the public instance a ref handed us) and a props
+// map whose entries may be AnimatedNodes (an animated `style` becomes an
+// AnimatedStyle, a bare animated prop stays an AnimatedNode). Each frame, the graph
+// flushes to this leaf via its `update()` method, which re-pulls the current values
+// into a flat partial and pushes it through shared's scoped setNativeProps: one
+// targeted clone-on-write commit. Ported from RN's AnimatedProps.js, JS-driven path
+// only: native config (__makeNative / __getNativeConfig / connectAnimatedNodeToView,
+// ADR 0017) is stripped.
+//
+// `update` MUST be a method, not a class field: flushValue detects a leaf by reading
+// a `update` function off the node, and under useDefineForClassFields a field
+// initialiser would shadow it and break subclassing. (See shared graph.ts leafUpdate.)
+import { AnimatedNode, AnimatedWithChildren } from './graph';
+import { setNativeProps, getNativeTag } from '../commit';
+import { isSymbioteNode } from '../node';
+import { registerPostCommit } from '../post-commit';
+import { nativeAnimated } from './native/native-animated';
+import { AnimatedStyle } from './style';
+function isAnimatedNode(value) {
+    return value instanceof AnimatedNode;
+}
+// Leaves that went native before their view's Fabric tag existed. Under an async-batched
+// commit (Vue/Svelte schedule completeRoot on a microtask) a native animation started in
+// onMounted cascades to the leaf BEFORE the first commit assigns the tag, so connectToView
+// finds no tag. We hold the leaf here and retry it once each commit assigns tags — the
+// third connect trigger alongside setNativeView and __makeNative. React commits
+// synchronously, so its leaves never land here.
+const pendingViewConnects = new Set();
+registerPostCommit(() => {
+    for (const leaf of pendingViewConnects)
+        leaf.retryViewConnect();
+});
+// Split the incoming props into (1) the AnimatedNodes to subscribe to and (2) the
+// props map with `style` wrapped in an AnimatedStyle when it holds animated values.
+// A fully-static style stays a plain object and contributes no node.
+function createAnimatedProps(inputProps) {
+    const nodes = [];
+    const props = {};
+    for (const key of Object.keys(inputProps)) {
+        const value = inputProps[key];
+        // `children` is a React element (its $$typeof is a Symbol), managed by the
+        // reconciler as real Fabric child nodes, never a serializable prop. The host
+        // config strips it from every prop bag; the Animated flush must too, else each
+        // frame's setNativeProps sends the element to Fabric and folly::dynamic throws
+        // "JS Symbols are not convertible to dynamic" (Android is strict; iOS ignores it).
+        if (key === 'children')
+            continue;
+        if (key === 'style') {
+            const styleNode = AnimatedStyle.from(value);
+            if (styleNode !== undefined) {
+                props[key] = styleNode;
+                nodes.push(styleNode);
+            }
+            else {
+                props[key] = value;
+            }
+        }
+        else if (isAnimatedNode(value)) {
+            props[key] = value;
+            nodes.push(value);
+        }
+        else {
+            props[key] = value;
+        }
+    }
+    return { nodes, props };
+}
+export class AnimatedProps extends AnimatedWithChildren {
+    nodes;
+    props;
+    // The host view this leaf flushes onto. Null until a ref captures the rendered
+    // base component's public instance via setNativeView.
+    target = null;
+    // The Fabric view tag this leaf is bound to natively (null until connected).
+    // Kept so __detach can disconnect exactly what it connected (ADR 0017).
+    connectedViewTag = null;
+    constructor(inputProps) {
+        super();
+        const { nodes, props } = createAnimatedProps(inputProps);
+        this.nodes = nodes;
+        this.props = props;
+    }
+    // Rasterize the whole props map: animated entries to their current value, static
+    // entries passed through. The flat partial setNativeProps hoists onto the view.
+    __getValue() {
+        const out = {};
+        for (const key of Object.keys(this.props)) {
+            const value = this.props[key];
+            out[key] = isAnimatedNode(value) ? value.__getValue() : value;
+        }
+        return out;
+    }
+    __getAnimatedValue() {
+        const out = {};
+        for (const key of Object.keys(this.props)) {
+            const value = this.props[key];
+            out[key] = isAnimatedNode(value) ? value.__getAnimatedValue() : value;
+        }
+        return out;
+    }
+    // Bind this leaf to the host view a ref just captured. A SymbioteNode is the
+    // public instance the host config returns (getPublicInstance), so we guard
+    // structurally rather than cast.
+    setNativeView(instance) {
+        if (this.target !== null && this.target === instance)
+            return;
+        if (!isSymbioteNode(instance))
+            return;
+        this.target = instance;
+        // If a native-driven animation already made this leaf native (view attached
+        // after the animation began), connect now.
+        if (this.__isNative())
+            this.connectToView();
+    }
+    // The leaf seam (a method, never a field). flushValue calls this once per frame;
+    // re-pull the current values and push them through the scoped commit. Skipped
+    // until the view is captured and committed at least once (setNativeProps no-ops
+    // on an uncommitted node).
+    update() {
+        if (this.target === null)
+            return;
+        setNativeProps(this.target, this.__getValue());
+    }
+    __attach() {
+        for (const node of this.nodes)
+            node.__addChild(this);
+    }
+    __detach() {
+        pendingViewConnects.delete(this);
+        if (this.__isNative()) {
+            // Reset the view's animated props to their defaults (native no longer
+            // tracks them) and unbind, before the graph drops the native node.
+            nativeAnimated.restoreDefaultValues(this.__getNativeTag());
+            this.disconnectFromView();
+        }
+        for (const node of this.nodes)
+            node.__removeChild(this);
+        this.target = null;
+        super.__detach();
+    }
+    // ---- native driver (ADR 0017) -------------------------------------------
+    // Marking the leaf native binds it to the host view. The value->...->props edges
+    // are wired by the upstream walk (AnimatedWithChildren.__makeNative); the one
+    // thing only the leaf can do is attach the props node to a real view tag.
+    __makeNative() {
+        super.__makeNative();
+        if (this.target !== null)
+            this.connectToView();
+    }
+    connectToView() {
+        if (this.target === null || this.connectedViewTag !== null)
+            return;
+        const viewTag = getNativeTag(this.target);
+        if (viewTag === undefined) {
+            // The view isn't committed yet (async-batched commit): retry after the commit
+            // that assigns its tag, via the post-commit hook.
+            pendingViewConnects.add(this);
+            return;
+        }
+        pendingViewConnects.delete(this);
+        nativeAnimated.connectAnimatedNodeToView(this.__getNativeTag(), viewTag);
+        this.connectedViewTag = viewTag;
+    }
+    // Post-commit retry of a connect deferred because the view tag wasn't assigned yet.
+    // No-op once connected (connectToView short-circuits on connectedViewTag).
+    retryViewConnect() {
+        this.connectToView();
+    }
+    disconnectFromView() {
+        if (this.connectedViewTag === null)
+            return;
+        nativeAnimated.disconnectAnimatedNodeFromView(this.__getNativeTag(), this.connectedViewTag);
+        this.connectedViewTag = null;
+    }
+    __getNativeConfig() {
+        const propsConfig = {};
+        for (const key of Object.keys(this.props)) {
+            const value = this.props[key];
+            if (isAnimatedNode(value)) {
+                // __getNativeTag only: creation is edge-free; the connect is a later phase.
+                propsConfig[key] = value.__getNativeTag();
+            }
+        }
+        return { type: 'props', props: propsConfig };
+    }
+}

package/build/animated/style.d.ts

@@ -0,0 +1,26 @@
+import { AnimatedNode, AnimatedWithChildren } from './graph';
+import type { INativeNodeConfig } from './native/native-animated';
+type ITransformEntry = Record<string, unknown>;
+export declare class AnimatedTransform extends AnimatedWithChildren {
+    private readonly nodes;
+    private readonly transforms;
+    static from(transforms: unknown): AnimatedTransform | undefined;
+    constructor(nodes: readonly AnimatedNode[], transforms: readonly ITransformEntry[]);
+    __getValue(): ITransformEntry[];
+    __getAnimatedValue(): ITransformEntry[];
+    __attach(): void;
+    __detach(): void;
+    __getNativeConfig(): INativeNodeConfig;
+}
+export declare class AnimatedStyle extends AnimatedWithChildren {
+    private readonly style;
+    private readonly nodes;
+    static from(styleProp: unknown): AnimatedStyle | undefined;
+    constructor(style: Record<string, unknown>, nodes: readonly AnimatedNode[]);
+    __getValue(): Record<string, unknown>;
+    __getAnimatedValue(): Record<string, unknown>;
+    __attach(): void;
+    __detach(): void;
+    __getNativeConfig(): INativeNodeConfig;
+}
+export {};

package/build/animated/style.js

@@ -0,0 +1,187 @@
+// AnimatedStyle / AnimatedTransform: graph nodes that flatten a `style` /
+// `transform` whose entries may themselves be AnimatedNodes. Ported from RN's
+// AnimatedStyle.js + AnimatedTransform.js, NUMERIC path only: the native-driver
+// config (__makeNative / __getNativeConfig / allowlist) and the web/string/color
+// branches are stripped (ADR 0016). On __getValue() each node re-pulls its
+// animated entries into a plain flat object the props leaf hoists onto the view.
+import { AnimatedNode, AnimatedWithChildren } from './graph';
+import { flattenStyle } from '../style';
+function isAnimatedNode(value) {
+    return value instanceof AnimatedNode;
+}
+// Normalize an angle string to radians so native gets a plain number (RN's
+// transformDataType). Anything else passes through untouched.
+function transformDataType(value) {
+    if (typeof value !== 'string')
+        return value;
+    if (value.endsWith('deg'))
+        return ((parseFloat(value) || 0) * Math.PI) / 180;
+    if (value.endsWith('rad'))
+        return parseFloat(value) || 0;
+    return value;
+}
+// Collect the AnimatedNodes nested directly under a list of transform entries,
+// so __attach can subscribe to each and a value change reaches this node.
+function animatedNodesInTransforms(transforms) {
+    const nodes = [];
+    for (const entry of transforms) {
+        for (const key of Object.keys(entry)) {
+            const value = entry[key];
+            if (isAnimatedNode(value))
+                nodes.push(value);
+        }
+    }
+    return nodes;
+}
+export class AnimatedTransform extends AnimatedWithChildren {
+    nodes;
+    transforms;
+    // Returns an AnimatedTransform only if at least one entry is animated;
+    // otherwise the transform is fully static and needs no graph node.
+    static from(transforms) {
+        if (!Array.isArray(transforms))
+            return undefined;
+        const entries = [];
+        for (const entry of transforms) {
+            if (typeof entry === 'object' && entry !== null)
+                entries.push(entry);
+        }
+        const nodes = animatedNodesInTransforms(entries);
+        if (nodes.length === 0)
+            return undefined;
+        return new AnimatedTransform(nodes, entries);
+    }
+    constructor(nodes, transforms) {
+        super();
+        this.nodes = nodes;
+        this.transforms = transforms;
+    }
+    // Rasterize every entry: animated values pulled to their current number, static
+    // values passed through. Each result is a single-key object, order preserved.
+    __getValue() {
+        return this.transforms.map(entry => {
+            const result = {};
+            for (const key of Object.keys(entry)) {
+                const value = entry[key];
+                result[key] = isAnimatedNode(value) ? value.__getValue() : value;
+            }
+            return result;
+        });
+    }
+    __getAnimatedValue() {
+        return this.transforms.map(entry => {
+            const result = {};
+            for (const key of Object.keys(entry)) {
+                const value = entry[key];
+                result[key] = isAnimatedNode(value) ? value.__getAnimatedValue() : value;
+            }
+            return result;
+        });
+    }
+    __attach() {
+        for (const node of this.nodes)
+            node.__addChild(this);
+    }
+    __detach() {
+        for (const node of this.nodes)
+            node.__removeChild(this);
+        super.__detach();
+    }
+    // Native: one entry per transform, animated entries pointing at their value's
+    // native tag, static ones carrying the (angle-normalized) literal (ADR 0017).
+    __getNativeConfig() {
+        const transforms = [];
+        for (const entry of this.transforms) {
+            for (const key of Object.keys(entry)) {
+                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() });
+                }
+                else {
+                    transforms.push({ type: 'static', property: key, value: transformDataType(value) });
+                }
+            }
+        }
+        return { type: 'transform', transforms };
+    }
+}
+export class AnimatedStyle extends AnimatedWithChildren {
+    // The flat style with animated keys still pointing at their AnimatedNode (so a
+    // re-pull on __getValue reads the live value); static keys hold plain values.
+    style;
+    nodes;
+    // Returns an AnimatedStyle only if the flattened style contains AnimatedNodes
+    // (directly, or a `transform` array with animated entries). Otherwise undefined.
+    static from(styleProp) {
+        const flat = flattenStyle(styleProp);
+        const style = {};
+        const nodes = [];
+        for (const key of Object.keys(flat)) {
+            const value = Reflect.get(flat, key);
+            if (key === 'transform') {
+                const transformNode = AnimatedTransform.from(value);
+                if (transformNode !== undefined) {
+                    style[key] = transformNode;
+                    nodes.push(transformNode);
+                }
+                else {
+                    style[key] = value;
+                }
+            }
+            else if (isAnimatedNode(value)) {
+                style[key] = value;
+                nodes.push(value);
+            }
+            else {
+                style[key] = value;
+            }
+        }
+        if (nodes.length === 0)
+            return undefined;
+        return new AnimatedStyle(style, nodes);
+    }
+    constructor(style, nodes) {
+        super();
+        this.style = style;
+        this.nodes = nodes;
+    }
+    __getValue() {
+        const out = {};
+        for (const key of Object.keys(this.style)) {
+            const value = this.style[key];
+            out[key] = isAnimatedNode(value) ? value.__getValue() : value;
+        }
+        return out;
+    }
+    __getAnimatedValue() {
+        const out = {};
+        for (const key of Object.keys(this.style)) {
+            const value = this.style[key];
+            out[key] = isAnimatedNode(value) ? value.__getAnimatedValue() : value;
+        }
+        return out;
+    }
+    __attach() {
+        for (const node of this.nodes)
+            node.__addChild(this);
+    }
+    __detach() {
+        for (const node of this.nodes)
+            node.__removeChild(this);
+        super.__detach();
+    }
+    // Native: map each animated style key to its value's native tag (ADR 0017).
+    // Static keys are not in the native style node. The view already carries them.
+    __getNativeConfig() {
+        const style = {};
+        for (const key of Object.keys(this.style)) {
+            const value = this.style[key];
+            if (isAnimatedNode(value)) {
+                // __getNativeTag only: creation is edge-free; the connect is a later phase.
+                style[key] = value.__getNativeTag();
+            }
+        }
+        return { type: 'style', style };
+    }
+}