@symbiote-native/engine 0.1.0

package/build/animated/animations/composition.js

@@ -0,0 +1,236 @@
+// The driver factory + composition API, ported from RN's
+// AnimatedImplementation.js, JS orchestration only (ADR 0016). `timing` /
+// `spring` / `decay` wrap a value with a fresh driver and return a
+// CompositeAnimation; `parallel` / `sequence` / `stagger` / `loop` / `delay`
+// orchestrate those. Vector (XY/Color) handling, tracking, AnimatedEvent and
+// every native-loop branch are dropped.
+import { dlog } from '../../debug';
+import { isNativeAnimatedAvailable } from '../native/native-animated';
+import { AnimatedNode } from '../graph';
+import { AnimatedValue } from '../value';
+import { AnimatedTracking } from './tracking';
+import { TimingAnimation } from './timing';
+import { SpringAnimation } from './spring';
+import { DecayAnimation } from './decay';
+// A loop offloads to native only when the driver was asked for the native path AND
+// the module is present; otherwise the JS-restart loop must run (a JS timing runs
+// once, it does not loop itself).
+function canOffloadLoop(config) {
+    return config.useNativeDriver === true && isNativeAnimatedAvailable();
+}
+// Fold a config's onComplete into the caller's callback so both fire. Mirrors
+// RN's _combineCallbacks.
+function combineCallbacks(callback, config) {
+    if (callback !== undefined && config.onComplete !== undefined) {
+        const onComplete = config.onComplete;
+        return result => {
+            onComplete(result);
+            callback(result);
+        };
+    }
+    return callback ?? config.onComplete;
+}
+export function timing(value, config) {
+    return {
+        start(callback) {
+            const onEnd = combineCallbacks(callback, config);
+            const target = config.toValue;
+            if (target instanceof AnimatedNode) {
+                value.track(new AnimatedTracking(value, target, toValue => new TimingAnimation({ ...config, toValue }), onEnd));
+            }
+            else {
+                value.animate(new TimingAnimation({ ...config, toValue: target }), onEnd);
+            }
+        },
+        stop() {
+            value.stopAnimation();
+        },
+        reset() {
+            value.resetAnimation();
+        },
+        _nativeLoop(iterations, callback) {
+            const target = config.toValue;
+            if (target instanceof AnimatedNode || !canOffloadLoop(config))
+                return false;
+            // One native animation carrying `iterations` runs the loop in native; the
+            // completion callback only fires when the count exhausts (never for -1).
+            value.animate(new TimingAnimation({ ...config, toValue: target, iterations }), combineCallbacks(callback, config));
+            return true;
+        },
+    };
+}
+export function spring(value, config) {
+    return {
+        start(callback) {
+            const onEnd = combineCallbacks(callback, config);
+            const target = config.toValue;
+            if (target instanceof AnimatedNode) {
+                value.track(new AnimatedTracking(value, target, toValue => new SpringAnimation({ ...config, toValue }), onEnd));
+            }
+            else {
+                value.animate(new SpringAnimation({ ...config, toValue: target }), onEnd);
+            }
+        },
+        _nativeLoop(iterations, callback) {
+            const target = config.toValue;
+            if (target instanceof AnimatedNode || !canOffloadLoop(config))
+                return false;
+            value.animate(new SpringAnimation({ ...config, toValue: target, iterations }), combineCallbacks(callback, config));
+            return true;
+        },
+        stop() {
+            value.stopAnimation();
+        },
+        reset() {
+            value.resetAnimation();
+        },
+    };
+}
+export function decay(value, config) {
+    return {
+        start(callback) {
+            value.animate(new DecayAnimation(config), combineCallbacks(callback, config));
+        },
+        stop() {
+            value.stopAnimation();
+        },
+        reset() {
+            value.resetAnimation();
+        },
+    };
+}
+export function parallel(animations, config) {
+    let doneCount = 0;
+    // Track per-animation completion so stop() calls each at most once.
+    const hasEnded = {};
+    const stopTogether = !(config !== undefined && config.stopTogether === false);
+    const result = {
+        start(callback, isLooping) {
+            if (doneCount === animations.length) {
+                callback?.({ finished: true });
+                return;
+            }
+            animations.forEach((animation, idx) => {
+                const cb = (endResult) => {
+                    hasEnded[idx] = true;
+                    doneCount++;
+                    if (doneCount === animations.length) {
+                        doneCount = 0;
+                        callback?.(endResult);
+                        return;
+                    }
+                    if (!endResult.finished && stopTogether) {
+                        result.stop();
+                    }
+                };
+                animation.start(cb, isLooping);
+            });
+        },
+        stop() {
+            animations.forEach((animation, idx) => {
+                if (!hasEnded[idx])
+                    animation.stop();
+                hasEnded[idx] = true;
+            });
+        },
+        reset() {
+            animations.forEach((animation, idx) => {
+                animation.reset();
+                hasEnded[idx] = false;
+                doneCount = 0;
+            });
+        },
+    };
+    return result;
+}
+export function sequence(animations) {
+    let current = 0;
+    return {
+        start(callback, isLooping) {
+            const onComplete = (result) => {
+                if (!result.finished) {
+                    callback?.(result);
+                    return;
+                }
+                current++;
+                if (current === animations.length) {
+                    // A fresh start (without reset) should begin from the top.
+                    current = 0;
+                    callback?.(result);
+                    return;
+                }
+                animations[current].start(onComplete, isLooping);
+            };
+            if (animations.length === 0) {
+                callback?.({ finished: true });
+            }
+            else {
+                animations[current].start(onComplete, isLooping);
+            }
+        },
+        stop() {
+            if (current < animations.length) {
+                animations[current].stop();
+            }
+        },
+        reset() {
+            animations.forEach((animation, idx) => {
+                if (idx <= current)
+                    animation.reset();
+            });
+            current = 0;
+        },
+    };
+}
+export function delay(time) {
+    return timing(new AnimatedValue(0), {
+        toValue: 0,
+        delay: time,
+        duration: 0,
+    });
+}
+export function stagger(time, animations) {
+    return parallel(animations.map((animation, i) => sequence([delay(time * i), animation])));
+}
+export function loop(animation, config = {}) {
+    const iterations = config.iterations ?? -1;
+    const resetBeforeIteration = config.resetBeforeIteration ?? true;
+    let isFinished = false;
+    let iterationsSoFar = 0;
+    return {
+        start(callback) {
+            if (iterations === 0) {
+                callback?.({ finished: true });
+                return;
+            }
+            // Prefer the native loop: a single native animation runs all iterations in
+            // native with zero JS per cycle. Only a single timing/spring offers it; a
+            // sequence/parallel returns false (no _nativeLoop) and falls back to JS.
+            if (animation._nativeLoop?.(iterations, callback) === true) {
+                dlog(`loop: offloaded ${iterations} iterations to native`);
+                return;
+            }
+            const restart = (result = { finished: true }) => {
+                if (isFinished || iterationsSoFar === iterations || result.finished === false) {
+                    callback?.(result);
+                }
+                else {
+                    iterationsSoFar++;
+                    if (resetBeforeIteration)
+                        animation.reset();
+                    animation.start(restart, iterations === -1);
+                }
+            };
+            restart();
+        },
+        stop() {
+            isFinished = true;
+            animation.stop();
+        },
+        reset() {
+            iterationsSoFar = 0;
+            isFinished = false;
+            animation.reset();
+        },
+    };
+}

package/build/animated/animations/decay.d.ts

@@ -0,0 +1,22 @@
+import type { IAnimation, IEndCallback } from '../animation';
+import type { AnimatedValue } from '../value';
+import type { INativeAnimationConfig } from '../native/native-animated';
+import { BaseAnimation, type IAnimationConfig } from './base';
+export interface IDecayAnimationConfig extends IAnimationConfig {
+    velocity: number;
+    deceleration?: number;
+}
+export declare class DecayAnimation extends BaseAnimation {
+    private startTime;
+    private lastValue;
+    private fromValue;
+    private readonly deceleration;
+    private readonly velocity;
+    private onUpdate;
+    private animationFrame;
+    constructor(config: IDecayAnimationConfig);
+    protected getNativeAnimationConfig(): INativeAnimationConfig;
+    start(fromValue: number, onUpdate: (value: number) => void, onEnd: IEndCallback, _previousAnimation: IAnimation | null, animatedValue: AnimatedValue): void;
+    private onFrame;
+    stop(): void;
+}

package/build/animated/animations/decay.js

@@ -0,0 +1,65 @@
+// DecayAnimation: ported from RN's animations/DecayAnimation.js, JS path only
+// (ADR 0016). Models momentum bleeding off under friction: an initial velocity
+// decays exponentially toward a resting value. Ends when consecutive frames
+// move less than 0.1.
+import { dlog } from '../../debug';
+import { BaseAnimation } from './base';
+import { cancelFrame, requestFrame } from './raf';
+export class DecayAnimation extends BaseAnimation {
+    startTime = 0;
+    lastValue = 0;
+    fromValue = 0;
+    deceleration;
+    velocity;
+    onUpdate = () => { };
+    animationFrame = null;
+    constructor(config) {
+        super(config);
+        this.deceleration = config.deceleration ?? 0.998;
+        this.velocity = config.velocity;
+    }
+    getNativeAnimationConfig() {
+        return {
+            type: 'decay',
+            deceleration: this.deceleration,
+            velocity: this.velocity,
+            iterations: this.__iterations,
+            platformConfig: this.__platformConfig,
+            debugID: this.__getDebugID(),
+        };
+    }
+    start(fromValue, onUpdate, onEnd, _previousAnimation, animatedValue) {
+        this.begin(onEnd);
+        this.lastValue = fromValue;
+        this.fromValue = fromValue;
+        this.onUpdate = onUpdate;
+        this.startTime = Date.now();
+        if (this.startNativeIfNeeded(animatedValue))
+            return;
+        this.animationFrame = requestFrame(() => this.onFrame());
+    }
+    onFrame() {
+        const now = Date.now();
+        const value = this.fromValue +
+            (this.velocity / (1 - this.deceleration)) *
+                (1 - Math.exp(-(1 - this.deceleration) * (now - this.startTime)));
+        this.onUpdate(value);
+        if (Math.abs(this.lastValue - value) < 0.1) {
+            this.__notifyAnimationEnd({ finished: true });
+            return;
+        }
+        this.lastValue = value;
+        if (this.__active) {
+            this.animationFrame = requestFrame(() => this.onFrame());
+        }
+    }
+    stop() {
+        super.stop();
+        if (this.animationFrame !== null) {
+            cancelFrame(this.animationFrame);
+            this.animationFrame = null;
+        }
+        dlog('decay animation stopped');
+        this.__notifyAnimationEnd({ finished: false });
+    }
+}

package/build/animated/animations/raf.d.ts

@@ -0,0 +1,5 @@
+export declare function requestFrame(callback: () => void): number;
+export declare function cancelFrame(handle: number): void;
+export type ITimerHandle = unknown;
+export declare function setTimer(callback: () => void, delayMs: number): ITimerHandle;
+export declare function clearTimer(handle: ITimerHandle): void;

package/build/animated/animations/raf.js

@@ -0,0 +1,39 @@
+// Drivers read requestAnimationFrame / cancelAnimationFrame from the host at
+// call time rather than importing them: React Native installs them on the
+// global, but a Node headless run may not have them until a smoke polyfills
+// them. Resolving lazily means a polyfill installed after this module loads is
+// still seen. A driver that runs without a host scheduler is a bug, not a
+// silent no-op, so we throw.
+function readGlobal(name) {
+    return Reflect.get(globalThis, name);
+}
+export function requestFrame(callback) {
+    const raf = readGlobal('requestAnimationFrame');
+    if (typeof raf !== 'function') {
+        throw new Error('requestAnimationFrame is not available on the host');
+    }
+    const run = cb => Number(Reflect.apply(raf, globalThis, [cb]));
+    return run(callback);
+}
+export function cancelFrame(handle) {
+    const caf = readGlobal('cancelAnimationFrame');
+    if (typeof caf !== 'function')
+        return;
+    const run = h => {
+        Reflect.apply(caf, globalThis, [h]);
+    };
+    run(handle);
+}
+export function setTimer(callback, delayMs) {
+    const set = readGlobal('setTimeout');
+    if (typeof set !== 'function') {
+        throw new Error('setTimeout is not available on the host');
+    }
+    return Reflect.apply(set, globalThis, [callback, delayMs]);
+}
+export function clearTimer(handle) {
+    const clear = readGlobal('clearTimeout');
+    if (typeof clear !== 'function')
+        return;
+    Reflect.apply(clear, globalThis, [handle]);
+}

package/build/animated/animations/spring-config.d.ts

@@ -0,0 +1,6 @@
+export interface ISpringConfigValues {
+    stiffness: number;
+    damping: number;
+}
+export declare function fromOrigamiTensionAndFriction(tension: number, friction: number): ISpringConfigValues;
+export declare function fromBouncinessAndSpeed(bounciness: number, speed: number): ISpringConfigValues;

package/build/animated/animations/spring-config.js

@@ -0,0 +1,55 @@
+// Origami spring-parameter conversions, ported verbatim from RN's
+// SpringConfig.js. Maps the designer-friendly bounciness/speed and
+// tension/friction inputs onto the stiffness/damping the damped-oscillator
+// integrator actually consumes. Pure math, no dependencies.
+function stiffnessFromOrigamiValue(oValue) {
+    return (oValue - 30) * 3.62 + 194;
+}
+function dampingFromOrigamiValue(oValue) {
+    return (oValue - 8) * 3 + 25;
+}
+export function fromOrigamiTensionAndFriction(tension, friction) {
+    return {
+        stiffness: stiffnessFromOrigamiValue(tension),
+        damping: dampingFromOrigamiValue(friction),
+    };
+}
+export function fromBouncinessAndSpeed(bounciness, speed) {
+    function normalize(value, startValue, endValue) {
+        return (value - startValue) / (endValue - startValue);
+    }
+    function projectNormal(n, start, end) {
+        return start + n * (end - start);
+    }
+    function linearInterpolation(t, start, end) {
+        return t * end + (1 - t) * start;
+    }
+    function quadraticOutInterpolation(t, start, end) {
+        return linearInterpolation(2 * t - t * t, start, end);
+    }
+    function b3Friction1(x) {
+        return 0.0007 * Math.pow(x, 3) - 0.031 * Math.pow(x, 2) + 0.64 * x + 1.28;
+    }
+    function b3Friction2(x) {
+        return 0.000044 * Math.pow(x, 3) - 0.006 * Math.pow(x, 2) + 0.36 * x + 2;
+    }
+    function b3Friction3(x) {
+        return 0.00000045 * Math.pow(x, 3) - 0.000332 * Math.pow(x, 2) + 0.1078 * x + 5.84;
+    }
+    function b3Nobounce(tension) {
+        if (tension <= 18)
+            return b3Friction1(tension);
+        if (tension > 18 && tension <= 44)
+            return b3Friction2(tension);
+        return b3Friction3(tension);
+    }
+    let b = normalize(bounciness / 1.7, 0, 20);
+    b = projectNormal(b, 0, 0.8);
+    const s = normalize(speed / 1.7, 0, 20);
+    const bouncyTension = projectNormal(s, 0.5, 200);
+    const bouncyFriction = quadraticOutInterpolation(b, b3Nobounce(bouncyTension), 0.01);
+    return {
+        stiffness: stiffnessFromOrigamiValue(bouncyTension),
+        damping: dampingFromOrigamiValue(bouncyFriction),
+    };
+}

package/build/animated/animations/spring.d.ts

@@ -0,0 +1,50 @@
+import type { IAnimation, IEndCallback } from '../animation';
+import type { AnimatedValue } from '../value';
+import type { INativeAnimationConfig } from '../native/native-animated';
+import { BaseAnimation, type IAnimationConfig } from './base';
+export interface ISpringAnimationConfig extends IAnimationConfig {
+    toValue: number;
+    overshootClamping?: boolean;
+    restDisplacementThreshold?: number;
+    restSpeedThreshold?: number;
+    velocity?: number;
+    bounciness?: number;
+    speed?: number;
+    tension?: number;
+    friction?: number;
+    stiffness?: number;
+    damping?: number;
+    mass?: number;
+    delay?: number;
+}
+interface ISpringInternalState {
+    lastPosition: number;
+    lastVelocity: number;
+    lastTime: number;
+}
+export declare class SpringAnimation extends BaseAnimation {
+    private readonly overshootClamping;
+    private readonly restDisplacementThreshold;
+    private readonly restSpeedThreshold;
+    private lastVelocity;
+    private startPosition;
+    private lastPosition;
+    private readonly toValue;
+    private readonly stiffness;
+    private readonly damping;
+    private readonly mass;
+    private initialVelocity;
+    private readonly delay;
+    private lastTime;
+    private frameTime;
+    private onUpdate;
+    private animationFrame;
+    private timeout;
+    constructor(config: ISpringAnimationConfig);
+    getInternalState(): ISpringInternalState;
+    protected getNativeAnimationConfig(): INativeAnimationConfig;
+    start(fromValue: number, onUpdate: (value: number) => void, onEnd: IEndCallback, previousAnimation: IAnimation | null, animatedValue: AnimatedValue): void;
+    private onFrame;
+    stop(): void;
+}
+export {};

package/build/animated/animations/spring.js

@@ -0,0 +1,207 @@
+// SpringAnimation: ported from RN's animations/SpringAnimation.js, JS path
+// only (ADR 0016). Integrates the closed form of a damped harmonic oscillator
+// each frame and rests once both velocity and displacement fall below their
+// thresholds. A spring chained after a previous spring inherits its
+// position/velocity/time (getInternalState) so retargeting mid-flight stays
+// continuous. The native-config export is dropped.
+import { dlog } from '../../debug';
+import { BaseAnimation } from './base';
+import { cancelFrame, clearTimer, requestFrame, setTimer } from './raf';
+import { fromBouncinessAndSpeed, fromOrigamiTensionAndFriction } from './spring-config';
+function resolveStiffnessDampingMass(config) {
+    if (config.stiffness !== undefined || config.damping !== undefined || config.mass !== undefined) {
+        return {
+            stiffness: config.stiffness ?? 100,
+            damping: config.damping ?? 10,
+            mass: config.mass ?? 1,
+        };
+    }
+    if (config.bounciness !== undefined || config.speed !== undefined) {
+        const springConfig = fromBouncinessAndSpeed(config.bounciness ?? 8, config.speed ?? 12);
+        return { stiffness: springConfig.stiffness, damping: springConfig.damping, mass: 1 };
+    }
+    const springConfig = fromOrigamiTensionAndFriction(config.tension ?? 40, config.friction ?? 7);
+    return { stiffness: springConfig.stiffness, damping: springConfig.damping, mass: 1 };
+}
+export class SpringAnimation extends BaseAnimation {
+    overshootClamping;
+    restDisplacementThreshold;
+    restSpeedThreshold;
+    lastVelocity;
+    startPosition = 0;
+    lastPosition = 0;
+    toValue;
+    stiffness;
+    damping;
+    mass;
+    initialVelocity;
+    delay;
+    lastTime = 0;
+    frameTime = 0;
+    onUpdate = () => { };
+    animationFrame = null;
+    timeout = null;
+    constructor(config) {
+        super(config);
+        this.overshootClamping = config.overshootClamping ?? false;
+        this.restDisplacementThreshold = config.restDisplacementThreshold ?? 0.001;
+        this.restSpeedThreshold = config.restSpeedThreshold ?? 0.001;
+        this.initialVelocity = config.velocity ?? 0;
+        this.lastVelocity = config.velocity ?? 0;
+        this.toValue = config.toValue;
+        this.delay = config.delay ?? 0;
+        const resolved = resolveStiffnessDampingMass(config);
+        if (resolved.stiffness <= 0)
+            throw new Error('Stiffness value must be greater than 0');
+        if (resolved.damping <= 0)
+            throw new Error('Damping value must be greater than 0');
+        if (resolved.mass <= 0)
+            throw new Error('Mass value must be greater than 0');
+        this.stiffness = resolved.stiffness;
+        this.damping = resolved.damping;
+        this.mass = resolved.mass;
+    }
+    getInternalState() {
+        return {
+            lastPosition: this.lastPosition,
+            lastVelocity: this.lastVelocity,
+            lastTime: this.lastTime,
+        };
+    }
+    // Native: hand the oscillator parameters to native (QuartzCore CASpringAnimation).
+    getNativeAnimationConfig() {
+        return {
+            type: 'spring',
+            stiffness: this.stiffness,
+            damping: this.damping,
+            mass: this.mass,
+            initialVelocity: this.initialVelocity,
+            overshootClamping: this.overshootClamping,
+            restDisplacementThreshold: this.restDisplacementThreshold,
+            restSpeedThreshold: this.restSpeedThreshold,
+            toValue: this.toValue,
+            iterations: this.__iterations,
+            platformConfig: this.__platformConfig,
+            debugID: this.__getDebugID(),
+        };
+    }
+    start(fromValue, onUpdate, onEnd, previousAnimation, animatedValue) {
+        this.begin(onEnd);
+        this.startPosition = fromValue;
+        this.lastPosition = this.startPosition;
+        this.onUpdate = onUpdate;
+        this.lastTime = Date.now();
+        this.frameTime = 0;
+        if (previousAnimation instanceof SpringAnimation) {
+            const internalState = previousAnimation.getInternalState();
+            this.lastPosition = internalState.lastPosition;
+            this.lastVelocity = internalState.lastVelocity;
+            this.initialVelocity = this.lastVelocity;
+            this.lastTime = internalState.lastTime;
+        }
+        // Native took over → the JS rAF loop is skipped entirely.
+        if (this.startNativeIfNeeded(animatedValue))
+            return;
+        if (this.delay !== 0) {
+            this.timeout = setTimer(() => this.onFrame(), this.delay);
+        }
+        else {
+            this.onFrame();
+        }
+    }
+    // This spring model is based off of a damped harmonic oscillator
+    // (https://en.wikipedia.org/wiki/Harmonic_oscillator#Damped_harmonic_oscillator),
+    // using the closed form of the second-order differential equation. It matches
+    // the algorithm used by QuartzCore's CASpringAnimation.
+    onFrame() {
+        // If a lot of frames were lost (a large payload, a paused debugger) advance
+        // by at most 4 frames so the spring keeps running fast rather than jumping
+        // to the end.
+        const MAX_STEPS = 64;
+        let now = Date.now();
+        if (now > this.lastTime + MAX_STEPS) {
+            now = this.lastTime + MAX_STEPS;
+        }
+        const deltaTime = (now - this.lastTime) / 1000;
+        this.frameTime += deltaTime;
+        const c = this.damping;
+        const m = this.mass;
+        const k = this.stiffness;
+        const v0 = -this.initialVelocity;
+        const zeta = c / (2 * Math.sqrt(k * m));
+        const omega0 = Math.sqrt(k / m);
+        const omega1 = omega0 * Math.sqrt(1.0 - zeta * zeta);
+        const x0 = this.toValue - this.startPosition;
+        let position;
+        let velocity;
+        const t = this.frameTime;
+        if (zeta < 1) {
+            // Under-damped.
+            const envelope = Math.exp(-zeta * omega0 * t);
+            position =
+                this.toValue -
+                    envelope *
+                        (((v0 + zeta * omega0 * x0) / omega1) * Math.sin(omega1 * t) + x0 * Math.cos(omega1 * t));
+            velocity =
+                zeta *
+                    omega0 *
+                    envelope *
+                    ((Math.sin(omega1 * t) * (v0 + zeta * omega0 * x0)) / omega1 +
+                        x0 * Math.cos(omega1 * t)) -
+                    envelope *
+                        (Math.cos(omega1 * t) * (v0 + zeta * omega0 * x0) - omega1 * x0 * Math.sin(omega1 * t));
+        }
+        else {
+            // Critically damped.
+            const envelope = Math.exp(-omega0 * t);
+            position = this.toValue - envelope * (x0 + (v0 + omega0 * x0) * t);
+            velocity = envelope * (v0 * (t * omega0 - 1) + t * x0 * (omega0 * omega0));
+        }
+        this.lastTime = now;
+        this.lastPosition = position;
+        this.lastVelocity = velocity;
+        this.onUpdate(position);
+        if (!this.__active) {
+            // A listener may have stopped us inside onUpdate.
+            return;
+        }
+        let isOvershooting = false;
+        if (this.overshootClamping && this.stiffness !== 0) {
+            if (this.startPosition < this.toValue) {
+                isOvershooting = position > this.toValue;
+            }
+            else {
+                isOvershooting = position < this.toValue;
+            }
+        }
+        const isVelocity = Math.abs(velocity) <= this.restSpeedThreshold;
+        let isDisplacement = true;
+        if (this.stiffness !== 0) {
+            isDisplacement = Math.abs(this.toValue - position) <= this.restDisplacementThreshold;
+        }
+        if (isOvershooting || (isVelocity && isDisplacement)) {
+            if (this.stiffness !== 0) {
+                // Settle exactly on the target.
+                this.lastPosition = this.toValue;
+                this.lastVelocity = 0;
+                this.onUpdate(this.toValue);
+            }
+            this.__notifyAnimationEnd({ finished: true });
+            return;
+        }
+        this.animationFrame = requestFrame(() => this.onFrame());
+    }
+    stop() {
+        super.stop();
+        if (this.timeout !== null) {
+            clearTimer(this.timeout);
+            this.timeout = null;
+        }
+        if (this.animationFrame !== null) {
+            cancelFrame(this.animationFrame);
+            this.animationFrame = null;
+        }
+        dlog('spring animation stopped');
+        this.__notifyAnimationEnd({ finished: false });
+    }
+}