@rafaelaugusto/jolt 0.1.0-beta.9 → 0.1.0-rc.2

package/dist/motion-value.js

@@ -0,0 +1,1074 @@
+import { Application, Color, ScrollView, } from '@nativescript/core';
+import { toViews } from './animate.js';
+import { colorMixer, isColorProperty, parseColor, validateColorTarget, } from './color.js';
+import { onReducedMotion, reducedMotion, timeScale } from './config.js';
+import { springPhysics } from './spring.js';
+import { mixFor } from './mixer.js';
+import { liveSpringDriver, syncLiveSprings, } from './live-spring-driver.js';
+import { clampDecoration, isDecorationProperty, validateDecorationTarget, } from './decoration.js';
+import { getDriver } from './driver/index.js';
+import { setBase, stopBase, ViewAnimation } from './engine.js';
+import { linear } from './easing.js';
+import { isProperty } from './properties.js';
+import { createTrack, instantTrack } from './track.js';
+import { resolveTransition, springs, } from './transition.js';
+import { playbackSource } from './playback.js';
+import { TimedAnimation } from './timed-animation.js';
+import { valueTrack } from './value-track.js';
+import { ValueObservers, } from './value-observers.js';
+const bound = new WeakMap();
+class Derived {
+    source;
+    read;
+    color;
+    mappings;
+    constructor(source, read, color, mappings = []) {
+        this.source = source;
+        this.read = read;
+        this.color = color;
+        this.mappings = mappings;
+    }
+    get root() {
+        return this.source ?? this;
+    }
+    get() {
+        const value = this.read(this.root.raw());
+        return this.color ? new Color(value) : value;
+    }
+    subscribe(listener, options) {
+        const release = this.root.retainConsumer();
+        try {
+            const stop = this.root.observers.subscribe(this.read, this.color, listener, options);
+            return () => {
+                stop();
+                release();
+            };
+        }
+        catch (error) {
+            release();
+            throw error;
+        }
+    }
+    to(input, output, options) {
+        if (this.color)
+            throw new TypeError('A color cannot be mapped again.');
+        const map = mapping(input, output, options);
+        if (this.root instanceof SpringRoot && map.color)
+            throw new TypeError('Live spring bindings currently support numeric transforms and opacity.');
+        const read = this.read;
+        return new Derived(this.root, (value) => map.read(read(value)), map.color, map.color
+            ? []
+            : [
+                ...this.mappings,
+                {
+                    input: [...map.input],
+                    output: [...map.numbers],
+                    clamp: options?.clamp !== false,
+                },
+            ]);
+    }
+}
+class Root extends Derived {
+    consumers = 0;
+    demandListeners = new Set();
+    get demanded() {
+        return this.consumers > 0;
+    }
+    retainConsumer() {
+        this.consumers++;
+        try {
+            this.demandChanged();
+        }
+        catch (error) {
+            this.consumers--;
+            this.demandChanged();
+            throw error;
+        }
+        let ended = false;
+        return () => {
+            if (ended)
+                return;
+            ended = true;
+            this.consumers--;
+            this.demandChanged();
+        };
+    }
+    demandChanged() {
+        for (const listener of [...this.demandListeners])
+            listener(this.demanded);
+    }
+    bindings = new Set();
+    listeners = new Set();
+    observers = new ValueObservers((time) => this.raw(time), () => this.running);
+    rests = new Map();
+    runs = new Map();
+    presentation;
+    cancelPresentation;
+    constructor(initial) {
+        super(undefined, (value) => value, false);
+        if (!Number.isFinite(initial))
+            throw new RangeError(`A motion value starts from a finite number, got ${initial}.`);
+        this.rests.set('', initial);
+    }
+    raw(time = getDriver().now()) {
+        let result = 0;
+        for (const key of new Set([...this.rests.keys(), ...this.runs.keys()]))
+            result += this.part(key, time);
+        return result;
+    }
+    /** Drag input owns only the base; bounds and snap points stay in base units. */
+    base() {
+        return this.part('');
+    }
+    part(key, time = getDriver().now()) {
+        const run = this.runs.get(key);
+        return run
+            ? run.base + run.span * run.track.valueAt(this.runTime(run, time))
+            : (this.rests.get(key) ?? 0);
+    }
+    runTime(run, time = getDriver().now()) {
+        return run.clock?.time() ?? time - run.startedAt;
+    }
+    /** Internal development snapshot; reading it installs no observers. */
+    inspect() {
+        return {
+            velocity: [...this.runs.keys()].reduce((sum, key) => sum + this.velocity(key), 0),
+            resources: this.bindings.size + this.listeners.size + this.observers.size + this.runs.size,
+        };
+    }
+    velocity(key) {
+        const run = this.runs.get(key);
+        if (!run || run.animation.paused)
+            return 0;
+        return run.span * run.track.velocityAt(this.runTime(run));
+    }
+    animate(target, transition = {}) {
+        const options = typeof transition === 'string' ? springOf(transition) : transition;
+        const key = options.layer === undefined ? '' : layerName(options.layer);
+        const from = this.part(key);
+        const frames = (typeof target === 'number' ? [null, target] : [...target]).map((frame) => (frame === null ? from : frame));
+        if (frames.length < 2)
+            frames.unshift(from);
+        if (frames.some((frame) => typeof frame !== 'number' || !Number.isFinite(frame)))
+            throw new RangeError(`Invalid motion value keyframes: ${JSON.stringify(target)}.`);
+        const resolved = resolveTransition(options, 'x', frames.length);
+        const base = Math.min(...frames);
+        const span = Math.max(...frames) - base;
+        const velocity = this.velocity(key);
+        if (resolved.curve.type === 'gravity') {
+            // Acceleration and velocity belong to the value's units, not normalized progress.
+            const track = createTrack('x', frames, resolved, velocity);
+            this.halt(key);
+            return track.end === 0 ? this.jump(track.to, key) : this.start(track, 0, 1, key);
+        }
+        if (span === 0) {
+            this.halt(key);
+            return this.jump(frames.at(-1), key);
+        }
+        // Sampled in the value's own range so springs settle relative to the distance.
+        const track = createTrack('opacity', frames.map((frame) => (frame - base) / span), resolved, velocity / span);
+        this.halt(key);
+        return track.end === 0
+            ? this.jump(base + span * track.to, key)
+            : this.start(track, base, span, key);
+    }
+    /** Plays a track sampled in the value's own units, such as a drag release. */
+    playTrack(track) {
+        this.halt('');
+        return track.end === 0 ? this.jump(track.to, '') : this.start(track, 0, 1, '');
+    }
+    jump(value, key) {
+        this.rests.set(key, value);
+        this.sync();
+        const animation = new TimedAnimation(0, 0, () => { }, () => { });
+        animation.start();
+        return animation;
+    }
+    start(track, base, span, key) {
+        const driver = getDriver();
+        const animation = new TimedAnimation(track.end, track.arrival, () => this.sync(), (completed) => {
+            if (this.runs.get(key)?.animation !== animation)
+                return;
+            const held = base + span * track.valueAt(animation.time);
+            this.runs.delete(key);
+            if (!completed && key !== '')
+                this.rests.delete(key);
+            else
+                this.rests.set(key, completed ? base + span * track.to : held);
+            this.sync();
+        });
+        const run = {
+            track,
+            base,
+            span,
+            animation,
+            startedAt: driver.now(),
+            clock: { time: () => animation.time },
+        };
+        this.runs.set(key, run);
+        this.sync();
+        animation.start();
+        return animation;
+    }
+    set(value) {
+        if (!Number.isFinite(value))
+            throw new RangeError(`A motion value takes a finite number, got ${value}.`);
+        for (const key of [...this.runs.keys()])
+            this.halt(key);
+        this.rests.clear();
+        this.rests.set('', value);
+        this.sync();
+    }
+    setBase(value) {
+        if (!Number.isFinite(value))
+            throw new RangeError('A motion value takes a finite number.');
+        this.halt('');
+        this.rests.set('', value);
+        this.sync();
+    }
+    stopBase() {
+        this.stopChannel('');
+    }
+    stop(layer) {
+        if (layer !== undefined)
+            return this.stopChannel(layerName(layer));
+        if (!this.runs.size && this.rests.size === 1)
+            return;
+        const value = this.raw();
+        for (const key of [...this.runs.keys()])
+            this.halt(key);
+        this.rests.clear();
+        this.rests.set('', value);
+        this.sync();
+    }
+    stopChannel(key) {
+        if (!this.runs.has(key) && (key === '' || !this.rests.has(key)))
+            return;
+        const held = this.part(key);
+        this.halt(key);
+        if (key === '')
+            this.rests.set(key, held);
+        else
+            this.rests.delete(key);
+        this.sync();
+    }
+    sync() {
+        this.cancelPresentation?.();
+        this.cancelPresentation = undefined;
+        const now = getDriver().now();
+        let rest = 0;
+        for (const [key, value] of this.rests)
+            if (!this.runs.has(key))
+                rest += value;
+        const runs = [...this.runs.values()].filter((run) => !run.animation.paused);
+        for (const [key, run] of this.runs)
+            if (run.animation.paused)
+                rest += this.part(key, now);
+        if (!runs.length)
+            this.presentation = undefined;
+        else if (runs.length === 1) {
+            const run = runs[0];
+            this.presentation = { ...run, base: run.base + rest };
+        }
+        else {
+            const { track, windowed } = valueTrack(runs.map((run) => ({
+                track: run.track,
+                base: run.base,
+                span: run.span,
+                elapsed: this.runTime(run, now),
+            })), rest);
+            const driver = getDriver();
+            const clock = driver.clock?.(track.end);
+            this.presentation = { track, base: 0, span: 1, startedAt: now, clock };
+            const cancelWindow = windowed
+                ? driver.after(track.end, () => this.sync())
+                : undefined;
+            this.cancelPresentation = () => {
+                cancelWindow?.();
+                clock?.cancel();
+            };
+        }
+        this.changed();
+    }
+    changed() {
+        for (const binding of this.bindings)
+            binding.sync();
+        for (const listener of [...this.listeners])
+            listener();
+        this.observers.changed(this.running);
+    }
+    /** The plan that plays this value's run, mapped, on one bound property. */
+    plan(binding) {
+        const run = this.presentation;
+        const { property, read } = binding;
+        const write = (value) => isDecorationProperty(property)
+            ? clampDecoration(property, read(value))
+            : read(value);
+        if (!run) {
+            const value = write(this.raw());
+            return {
+                property,
+                keyframes: [],
+                transition: still,
+                track: () => instantTrack(property, value),
+            };
+        }
+        const { track, base, span } = run;
+        const at = (progress) => write(base + span * progress);
+        const transition = {
+            curve: {
+                type: 'tween',
+                duration: track.duration,
+                ease: [linear],
+                times: undefined,
+            },
+            delay: track.delay,
+            repeat: track.repeat,
+            reverse: track.reverse,
+        };
+        const mapped = () => {
+            if (reducedMotion() && property !== 'opacity' && !isColorProperty(property))
+                return instantTrack(property, at(track.to));
+            return {
+                property,
+                delay: track.delay,
+                duration: track.duration,
+                repeat: track.repeat,
+                reverse: track.reverse,
+                times: track.times,
+                values: track.values.map(at),
+                to: at(track.to),
+                end: track.end,
+                arrival: track.arrival,
+                valueAt: (elapsed) => at(track.valueAt(elapsed)),
+                velocityAt: isColorProperty(property)
+                    ? () => 0
+                    : (elapsed) => (at(track.valueAt(elapsed + 0.5)) - at(track.valueAt(elapsed - 0.5))) *
+                        1000,
+            };
+        };
+        return { property, keyframes: [], transition, track: mapped };
+    }
+    /** Capture the current native presentation clock, even if a later command replaces it. */
+    captureTime() {
+        const run = this.presentation;
+        return run ? () => this.runTime(run) : () => 0;
+    }
+    elapsed() {
+        return this.presentation ? this.runTime(this.presentation) : 0;
+    }
+    get paused() {
+        return this.runs.size > 0 && !this.running;
+    }
+    get running() {
+        return [...this.runs.values()].some((run) => !run.animation.paused);
+    }
+    halt(key) {
+        const run = this.runs.get(key);
+        if (!run)
+            return;
+        this.runs.delete(key);
+        run.animation.stop();
+    }
+}
+class SpringRoot extends Root {
+    input;
+    releaseDemand;
+    externalActive = false;
+    demandChanged() {
+        const active = this.demanded && !this.ended && !this.held && !this.background;
+        if (active && !this.releaseDemand) {
+            // A source status callback may synchronously suspend or dispose this follower.
+            this.releaseDemand = () => { };
+            let release;
+            try {
+                release = this.input.root.retainConsumer();
+            }
+            catch (error) {
+                this.releaseDemand = undefined;
+                throw error;
+            }
+            this.releaseDemand = release;
+            if (!this.demanded || this.ended || this.held || this.background) {
+                this.releaseDemand = undefined;
+                release();
+            }
+        }
+        else if (!active && this.releaseDemand) {
+            const release = this.releaseDemand;
+            this.releaseDemand = undefined;
+            release();
+        }
+        super.demandChanged();
+    }
+    node;
+    releaseSource = () => { };
+    releaseReduced = () => { };
+    ended = false;
+    held = false;
+    background = false;
+    suspend = () => {
+        this.background = true;
+        this.updatePause();
+    };
+    resume = () => {
+        this.background = false;
+        this.updatePause();
+    };
+    constructor(input, options) {
+        const source = input;
+        const initial = options.initial ?? source.get();
+        const instant = options.duration === 0;
+        const params = springPhysics(instant ? { ...options, duration: undefined } : options);
+        const speed = timeScale();
+        const physics = {
+            stiffness: params.stiffness * speed * speed,
+            damping: params.damping * speed,
+            mass: params.mass,
+            restDelta: options.restDelta ?? 0.001,
+            restSpeed: options.restSpeed ?? 0.01,
+        };
+        for (const [key, value] of Object.entries(physics))
+            if (!Number.isFinite(value) || (key === 'damping' ? value < 0 : value <= 0))
+                throw new RangeError(`Invalid springValue ${key}: ${value}.`);
+        if (options.duration !== undefined &&
+            (!Number.isFinite(options.duration) || options.duration < 0))
+            throw new RangeError('springValue duration must be finite and nonnegative.');
+        if (options.bounce !== undefined && !Number.isFinite(options.bounce))
+            throw new RangeError('springValue bounce must be finite.');
+        super(initial);
+        this.input = input;
+        this.node = liveSpringDriver().create(initial, physics, instant || reducedMotion());
+        const root = source.root;
+        try {
+            let update;
+            if (root instanceof SpringRoot) {
+                if (root.disposed)
+                    throw new Error('Cannot follow a disposed spring value.');
+                this.node.follow(root.node, source.mappings);
+                update = () => this.notify();
+            }
+            else {
+                const playback = valuePlayback(source);
+                update = () => {
+                    if (!root.running) {
+                        this.node.update({
+                            value: source.get(),
+                            running: false,
+                            elapsed: 0,
+                            duration: 0,
+                            delay: 0,
+                            repeat: 0,
+                            reverse: false,
+                            to: 0,
+                            times: [],
+                            values: [],
+                        });
+                        this.notify();
+                        return;
+                    }
+                    const { track, elapsed, running, value } = playback.snapshot();
+                    this.node.update({
+                        value,
+                        elapsed,
+                        running,
+                        duration: track.duration,
+                        delay: track.delay,
+                        repeat: Number.isFinite(track.repeat) ? track.repeat : -1,
+                        reverse: track.reverse,
+                        to: track.to,
+                        times: track.times,
+                        values: track.values,
+                    });
+                    this.notify();
+                };
+            }
+            root.listeners.add(update);
+            this.releaseSource = () => {
+                root.listeners.delete(update);
+            };
+            this.releaseReduced = onReducedMotion((reduced) => {
+                this.node.reduced(instant || reduced);
+                this.notify();
+            });
+            Application.on(Application.suspendEvent, this.suspend);
+            Application.on(Application.resumeEvent, this.resume);
+            update();
+        }
+        catch (error) {
+            this.dispose();
+            throw error;
+        }
+    }
+    raw() {
+        return this.node?.position() ?? super.raw();
+    }
+    get running() {
+        return (!this.ended &&
+            !this.held &&
+            !this.background &&
+            (this.externalActive || (this.node?.moving() ?? false)));
+    }
+    get moving() {
+        return this.running;
+    }
+    get disposed() {
+        return this.ended;
+    }
+    get paused() {
+        return this.held;
+    }
+    pause() {
+        if (!this.ended) {
+            this.held = true;
+            this.updatePause();
+        }
+    }
+    play() {
+        if (!this.ended) {
+            this.held = false;
+            this.updatePause();
+        }
+    }
+    updatePause() {
+        this.node.paused(this.held || this.background);
+        this.demandChanged();
+        this.notify();
+    }
+    getVelocity() {
+        return this.ended ? 0 : this.node.velocity();
+    }
+    plan() {
+        throw new TypeError('A live spring cannot be sampled as a fixed track. Bind it to transforms or opacity.');
+    }
+    notify() {
+        this.observers.changed(this.running);
+        for (const listener of [...this.listeners])
+            listener();
+    }
+    dispose() {
+        if (this.ended)
+            return;
+        this.ended = true;
+        this.demandChanged();
+        this.releaseSource();
+        this.releaseReduced();
+        Application.off(Application.suspendEvent, this.suspend);
+        Application.off(Application.resumeEvent, this.resume);
+        for (const binding of [...this.bindings])
+            release(binding);
+        this.node.dispose();
+        this.observers.clear();
+        for (const listener of [...this.listeners])
+            listener();
+        this.listeners.clear();
+    }
+}
+/** Follow changing targets without rebuilding sampled animation tracks. Dispose with the owning scope. */
+export function springValue(source, options = {}) {
+    if (!(source instanceof Derived) || source.color)
+        throw new TypeError('springValue() needs a numeric Jolt motion value.');
+    if (!options || typeof options !== 'object')
+        throw new TypeError('springValue() options must be an object.');
+    return new SpringRoot(source, options);
+}
+/** Internal boundary notification for values driven directly by native input. */
+export function liveValueInput(value) {
+    if (!(value instanceof Derived) || !(value.root instanceof SpringRoot))
+        throw new TypeError('Native input requires a live value.');
+    const root = value.root;
+    return {
+        node: root.node,
+        changed: () => root.notify(),
+        active(value) {
+            root.externalActive = value;
+            root.notify();
+        },
+        demand(listener) {
+            root.demandListeners.add(listener);
+            listener(root.demanded);
+            return () => {
+                root.demandListeners.delete(listener);
+            };
+        },
+    };
+}
+function layerName(name) {
+    if (typeof name !== 'string' || !name.length)
+        throw new TypeError('A layer is named by a nonempty string.');
+    return name;
+}
+const still = {
+    curve: { type: 'tween', duration: 0, ease: [linear], times: undefined },
+    delay: 0,
+    repeat: 0,
+    reverse: false,
+};
+/**
+ * A number that animates natively and drives the view properties bound to it.
+ *
+ * ```ts
+ * const progress = motionValue(0)
+ * bind(sheet, { y: progress.to([0, 1], [600, 0]) })
+ * animate(progress, 1, 'snappy')
+ * ```
+ */
+export function motionValue(initial = 0) {
+    return new Root(initial);
+}
+export function isMotionValue(target) {
+    return target instanceof Root && !(target instanceof SpringRoot);
+}
+export function asRoot(value) {
+    return value;
+}
+/**
+ * Lets motion values drive a view's properties. The view takes their current values
+ * at once and follows every change on the same native clock. Returns a cleanup function.
+ *
+ * ```ts
+ * const release = bind(backdrop, { opacity: progress.to([0, 1], [0, 0.4]) })
+ * ```
+ */
+export function bind(target, bindings) {
+    if (!bindings || typeof bindings !== 'object' || Array.isArray(bindings))
+        throw new TypeError('bind() takes an object of motion values.');
+    const views = toViews(target);
+    const entries = [];
+    for (const [key, source] of Object.entries(bindings)) {
+        if (source === undefined)
+            continue;
+        if (!(source instanceof Derived))
+            throw new TypeError(`"${key}" needs a motion value, got ${String(source)}.`);
+        const properties = key === 'scale' ? ['scaleX', 'scaleY'] : isProperty(key) ? [key] : [];
+        if (!properties.length)
+            throw new Error(`Can't bind "${key}".`);
+        for (const property of properties) {
+            if (source.root instanceof SpringRoot) {
+                if (source.root.disposed)
+                    throw new Error('Cannot bind a disposed spring value.');
+                if (isColorProperty(property) || isDecorationProperty(property))
+                    throw new TypeError('Live spring bindings currently support numeric transforms and opacity.');
+            }
+            if (isColorProperty(property) !== source.color)
+                throw new TypeError(source.color
+                    ? `"${key}" takes numbers; map the value to numbers.`
+                    : `"${key}" is a color; map the value to colors with to(input, colors).`);
+            entries.push([property, source]);
+        }
+    }
+    for (const view of views)
+        for (const [property] of entries)
+            if (isColorProperty(property))
+                validateColorTarget(view, property);
+            else if (isDecorationProperty(property))
+                validateDecorationTarget(view, property);
+    const made = [];
+    try {
+        for (const view of views)
+            for (const [property, source] of entries)
+                made.push(attach(view, property, source));
+    }
+    catch (error) {
+        for (const cleanup of made.reverse())
+            cleanup();
+        throw error;
+    }
+    return () => made.forEach((release) => release());
+}
+function attach(view, property, source) {
+    const existing = bound.get(view)?.get(property);
+    if (existing)
+        release(existing);
+    const root = source.root;
+    if (root instanceof SpringRoot)
+        return attachSpring(view, property, source, root);
+    const binding = {
+        view,
+        property,
+        root,
+        source,
+        read: source.read,
+        sync() {
+            if (!view.isLoaded || !view.nativeViewProtected)
+                return;
+            if (!root.running) {
+                // A value at rest writes straight through, so scroll offsets cost one write per event.
+                binding.animation?.stop();
+                binding.animation = undefined;
+                stopBase(view, [property]);
+                const value = source.read(root.raw());
+                setBase(view, property, isDecorationProperty(property) ? clampDecoration(property, value) : value);
+                if (isColorProperty(property) || isDecorationProperty(property))
+                    getDriver().sync?.(view);
+                return;
+            }
+            const animation = new ViewAnimation(view, [root.plan(binding)]);
+            // Native keyframe setup can take time, especially for a composite track on Android.
+            // Catch up after construction so each binding joins the source's current phase.
+            const elapsed = root.elapsed();
+            if (root.paused)
+                animation.pause();
+            if ((elapsed > 1 || root.paused) && animation.duration > 0)
+                animation.seekTime(elapsed);
+            binding.animation = animation;
+        },
+    };
+    let properties = bound.get(view);
+    if (!properties)
+        bound.set(view, (properties = new Map()));
+    properties.set(property, binding);
+    root.bindings.add(binding);
+    view.on('loaded', binding.sync);
+    try {
+        binding.sync();
+    }
+    catch (error) {
+        release(binding);
+        throw error;
+    }
+    return () => {
+        if (root.bindings.has(binding)) {
+            release(binding);
+            binding.animation?.stop();
+        }
+    };
+}
+function attachSpring(view, property, source, root) {
+    let native;
+    let releaseMix;
+    let releaseDemand;
+    const detach = () => {
+        if (!native)
+            return;
+        native.cancel();
+        releaseMix?.();
+        releaseMix = undefined;
+        native = undefined;
+        releaseDemand?.();
+        releaseDemand = undefined;
+        syncLiveSprings(view);
+    };
+    const binding = {
+        view,
+        property,
+        root,
+        source,
+        read: source.read,
+        sync() {
+            if (!view.isLoaded || !view.nativeViewProtected || root.disposed)
+                return;
+            detach();
+            stopBase(view, [property]);
+            native = root.node.bind(view, property, source.mappings);
+            const handle = native;
+            const retained = root.retainConsumer();
+            if (native !== handle || root.disposed) {
+                retained();
+                return;
+            }
+            releaseDemand = retained;
+            releaseMix = mixFor(view, property).attachLive({
+                read: () => handle.value(),
+                layers: (layers) => handle.layers(layers),
+            });
+            syncLiveSprings(view);
+        },
+        cleanup() {
+            view.off('unloaded', detach);
+            detach();
+        },
+    };
+    let properties = bound.get(view);
+    if (!properties)
+        bound.set(view, (properties = new Map()));
+    properties.set(property, binding);
+    root.bindings.add(binding);
+    view.on('loaded', binding.sync);
+    view.on('unloaded', detach);
+    try {
+        binding.sync();
+    }
+    catch (error) {
+        release(binding);
+        throw error;
+    }
+    return () => {
+        if (root.bindings.has(binding))
+            release(binding);
+    };
+}
+/** A read-only value on an existing finite animation's clock. No second animation or timer. */
+export function playbackProgress(animation) {
+    const source = playbackSource(animation);
+    if (!Number.isFinite(source.read().duration))
+        throw new RangeError('Progress requires a finite animation.');
+    const root = new PlaybackValue(source);
+    return new Derived(root, (value) => value, false);
+}
+class PlaybackValue extends Root {
+    playback;
+    constructor(playback) {
+        super(0);
+        this.playback = playback;
+        const source = playback;
+        const off = source.subscribe(() => {
+            this.changed();
+            if (source.read().settled)
+                off();
+        });
+        if (source.read().settled)
+            off();
+        this.observers.changed(this.running);
+    }
+    raw() {
+        const state = this.playback.read();
+        return (state.position ??
+            (state.completed
+                ? 1
+                : state.duration > 0
+                    ? Math.max(0, Math.min(1, state.time / state.duration))
+                    : 0));
+    }
+    get running() {
+        const state = this.playback.read();
+        return state.ready && !state.settled && !state.paused && state.duration > 0;
+    }
+    get paused() {
+        return this.playback.read().paused;
+    }
+    captureTime() {
+        return () => this.playback.read().time;
+    }
+    elapsed() {
+        return this.playback.read().time;
+    }
+    plan(binding) {
+        const state = this.playback.read();
+        if (!state.ready || state.settled || state.duration === 0)
+            return {
+                property: binding.property,
+                keyframes: [],
+                transition: still,
+                track: () => instantTrack(binding.property, binding.read(this.raw())),
+            };
+        // Bypass timeScale: the source duration is already in platform playback milliseconds.
+        const duration = state.duration;
+        const at = (ms) => binding.read(Math.max(0, Math.min(1, ms / duration)));
+        const track = {
+            property: binding.property,
+            delay: 0,
+            duration,
+            repeat: 0,
+            reverse: false,
+            times: [0, 1],
+            values: [at(0), at(duration)],
+            to: at(duration),
+            end: duration,
+            arrival: duration,
+            valueAt: at,
+            velocityAt: (ms) => (at(ms + 0.5) - at(ms - 0.5)) * 1000,
+        };
+        // Piecewise/color derivations need intermediate samples, not only the two endpoints.
+        const steps = Math.max(1, Math.min(6000, Math.ceil((duration * 60) / 1000)));
+        const times = Array.from({ length: steps + 1 }, (_, i) => i / steps);
+        return {
+            property: binding.property,
+            keyframes: [],
+            transition: still,
+            track: () => reducedMotion() &&
+                binding.property !== 'opacity' &&
+                !isColorProperty(binding.property)
+                ? instantTrack(binding.property, at(duration))
+                : { ...track, times, values: times.map((time) => at(time * duration)) },
+        };
+    }
+}
+/** Internal compound-binding bridge. One raw snapshot per root keeps sibling mappings coherent. */
+export function valueSource(source, color) {
+    if (!(source instanceof Derived) || source.color !== color)
+        throw new TypeError(`Gradient component needs a ${color ? 'color' : 'numeric'} Jolt value.`);
+    const { root, read } = source;
+    return {
+        identity: root,
+        read,
+        snapshot() {
+            return {
+                track: root.plan({ property: 'opacity', read: (value) => value })
+                    .track(),
+                elapsed: root.elapsed(),
+                time: root.captureTime(),
+                running: root.running,
+                value: root.raw(),
+            };
+        },
+        subscribe(listener) {
+            root.listeners.add(listener);
+            return () => {
+                root.listeners.delete(listener);
+            };
+        },
+    };
+}
+/** Treat values as opaque identities in declarative option comparisons. */
+export function isDerived(value) {
+    return value instanceof Derived;
+}
+/** Internal native-adapter bridge. Mappings are sampled at boundaries, never per frame. */
+export function valuePlayback(source) {
+    if (!(source instanceof Derived) || source.color)
+        throw new TypeError('A native binding needs a numeric Jolt value.');
+    const { root, read } = source;
+    return {
+        snapshot() {
+            return {
+                track: root.plan({ property: 'opacity', read }).track(),
+                elapsed: root.elapsed(),
+                paused: root.paused,
+                running: root.running,
+                value: read(root.raw()),
+            };
+        },
+        subscribe(listener) {
+            root.listeners.add(listener);
+            return () => {
+                root.listeners.delete(listener);
+            };
+        },
+    };
+}
+function release(binding) {
+    binding.root.bindings.delete(binding);
+    binding.view.off('loaded', binding.sync);
+    const properties = bound.get(binding.view);
+    if (properties?.get(binding.property) === binding)
+        properties.delete(binding.property);
+    binding.cleanup?.();
+}
+/** A regular animation on a bound property takes it over; the value keeps its other bindings. */
+export function detachBindings(view, properties) {
+    const map = bound.get(view);
+    if (!map)
+        return;
+    for (const property of properties) {
+        const binding = map.get(property);
+        if (binding)
+            release(binding);
+    }
+}
+/** Read existing binding topology without subscribing or constructing new tracks. */
+export function inspectViewBindings(view) {
+    const describe = (source, depth = 0) => ({
+        identity: source.root,
+        kind: source.root instanceof SpringRoot ? 'live spring' : 'motion value',
+        value: source.root.raw(),
+        mappings: source.mappings.map((mapping) => ({
+            ...mapping,
+            input: [...mapping.input],
+            output: [...mapping.output],
+        })),
+        input: source.root instanceof SpringRoot && depth < 8
+            ? describe(source.root.input, depth + 1)
+            : undefined,
+    });
+    return [...(bound.get(view)?.values() ?? [])].map((binding) => ({
+        property: binding.property,
+        source: describe(binding.source ?? binding.root),
+        value: binding.read(binding.root.raw()),
+    }));
+}
+function mapping(input, output, options = {}) {
+    if (!Array.isArray(input) || !Array.isArray(output) || input.length < 2)
+        throw new RangeError('to() needs at least two input and output values.');
+    if (input.length !== output.length)
+        throw new RangeError(`to() has ${input.length} inputs but ${output.length} outputs; give one output per input.`);
+    if (input.some((value) => !Number.isFinite(value)))
+        throw new RangeError('to() inputs must all be finite numbers.');
+    const descending = input[input.length - 1] < input[0];
+    if (input.some((value, i) => i > 0 && (descending ? value > input[i - 1] : value < input[i - 1])))
+        throw new RangeError('to() inputs must be monotonic (ascending or descending); ranges cannot change direction.');
+    // Normalize pairs together, without changing caller-owned arrays or duplicate-stop rules.
+    if (descending) {
+        input = [...input].reverse();
+        output = [...output].reverse();
+    }
+    const color = typeof output[0] !== 'number';
+    const numbers = color ? output.map((value) => parseColor(value)) : output;
+    if (!color &&
+        numbers.some((value) => typeof value !== 'number' || !Number.isFinite(value)))
+        throw new RangeError('to() outputs must all be finite numbers, or all colors.');
+    const mixers = color
+        ? numbers.slice(1).map((value, i) => colorMixer(numbers[i], value))
+        : undefined;
+    const clamp = color || options.clamp !== false;
+    const last = input.length - 1;
+    const read = (value) => {
+        if (clamp && value <= input[0])
+            return numbers[0];
+        if (clamp && value >= input[last])
+            return numbers[last];
+        let i = 0;
+        while (i < last - 1 && value > input[i + 1])
+            i++;
+        const span = input[i + 1] - input[i];
+        const t = span > 0 ? (value - input[i]) / span : value < input[i] ? 0 : 1;
+        if (mixers)
+            return mixers[i](Math.min(1, Math.max(0, t)));
+        return numbers[i] + (numbers[i + 1] - numbers[i]) * t;
+    };
+    return { read, color, input, numbers };
+}
+function springOf(name) {
+    if (!Object.hasOwn(springs, name))
+        throw new Error(`Unknown spring "${name}".`);
+    return springs[name];
+}
+/**
+ * The scroll offset of a ScrollView, in DIPs, as a value that bindings follow.
+ *
+ * ```ts
+ * const offset = scrollValue(scroll)
+ * bind(header, { y: offset.to([0, 120], [0, -60]), opacity: offset.to([0, 80], [1, 0]) })
+ * ```
+ */
+export function scrollValue(scrollView, options = {}) {
+    const axis = options.axis ?? 'y';
+    if (axis !== 'x' && axis !== 'y')
+        throw new TypeError('Scroll axis must be "x" or "y".');
+    const root = new Root(0);
+    let source;
+    const read = () => {
+        if (!source)
+            return;
+        const offset = axis === 'x' ? source.horizontalOffset : source.verticalOffset;
+        if (Number.isFinite(offset) && offset !== root.raw())
+            root.set(offset);
+    };
+    const onScroll = (event) => {
+        const { scrollX, scrollY } = event;
+        const offset = axis === 'x' ? scrollX : scrollY;
+        if (Number.isFinite(offset) && offset !== root.raw())
+            root.set(offset);
+    };
+    const detach = () => {
+        source?.off(ScrollView.scrollEvent, onScroll);
+        source?.off('loaded', read);
+        source = undefined;
+    };
+    const ref = (target) => {
+        const next = target === null ? undefined : toViews(target)[0];
+        if (next === source)
+            return;
+        if (next !== undefined && !(next instanceof ScrollView))
+            throw new TypeError('scrollValue() follows a NativeScript ScrollView.');
+        detach();
+        source = next;
+        source?.on(ScrollView.scrollEvent, onScroll);
+        source?.on('loaded', read);
+        read();
+    };
+    if (scrollView)
+        ref(scrollView);
+    return Object.assign(root, { ref, dispose: detach });
+}
+//# sourceMappingURL=motion-value.js.map