@ghia/native 0.0.0-stage → 0.11.0

package/dist/motion-value.js

@@ -0,0 +1,941 @@
+/// Motion values: values that live in the renderer's native graph, are sampled
+/// at the frame clock, and bind to element style through the `motionValues`
+/// custom prop. This file is the framework-free core; the React and Solid
+/// adapters wrap it.
+///
+/// A value starts in JS, with its state here, and gets a native node when it is
+/// bound to a renderer (`bind`). Every binding and every listener keeps the node
+/// alive, and the node is disposed when the last one goes away, so a value
+/// outlives its elements without leaking. `destroy()` is for values the caller
+/// drops.
+import { createRendererState } from "./renderer-state.js";
+const HOST_METHODS = [
+    "createMotionValue",
+    "createMotionTransform",
+    "createMotionFollower",
+    "createMotionSpring",
+    "disposeMotionValue",
+    "getMotionValue",
+    "getMotionValueVelocity",
+    "isMotionValueAnimating",
+    "setMotionValue",
+    "jumpMotionValue",
+    "animateMotionValue",
+    "stopMotionValue",
+    "pauseMotionValue",
+    "playMotionValue",
+    "seekMotionValue",
+    "setMotionValueSpeed",
+    "completeMotionValue",
+    "detachMotionValueClock",
+    "getMotionValuePlayback",
+    "setMotionValueListener",
+];
+const INSTANT = { duration: 0 };
+export function wireTransition(transition) {
+    if (transition?.repeat !== Infinity)
+        return transition;
+    return { ...transition, repeat: "Infinity" };
+}
+/**
+ * `wireTransition` for what a `motion.*` component takes: the repeat of the
+ * curve at the top, of `default`, and of each property's own.
+ */
+export function wireMotionTransition(transition) {
+    if (transition === undefined)
+        return undefined;
+    const wired = { ...wireTransition(transition) };
+    for (const key of Object.keys(wired)) {
+        const value = wired[key];
+        if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+            wired[key] = wireTransition(value);
+        }
+    }
+    return wired;
+}
+function isShadowLayer(item) {
+    return typeof item === "object" && item !== null && !Array.isArray(item);
+}
+/**
+ * Where an animation of `target` ends. The renderer reads an array as keyframes
+ * unless it is a list of the kind `from` holds, and this reads it the same way.
+ */
+function endOf(target, from) {
+    if (!Array.isArray(target))
+        return target;
+    const items = target;
+    const holdsNumbers = Array.isArray(from) && typeof from[0] === "number";
+    const holdsShadows = !holdsNumbers && typeof from === "object";
+    if ((holdsNumbers && items.every((item) => typeof item === "number")) ||
+        (holdsShadows && items.every(isShadowLayer))) {
+        return target;
+    }
+    for (let index = items.length - 1; index >= 0; index--) {
+        if (items[index] !== null)
+            return items[index];
+    }
+    return from;
+}
+/** Where an animation of `target` begins: its first keyframe, or the value it started from. */
+function startOf(target, from) {
+    if (!Array.isArray(target) || endOf(target, from) === target)
+        return from;
+    const first = target[0];
+    return first === null ? from : first;
+}
+/** What the controls read before the animation started: what they were told so far. */
+function pendingPlayback(animation) {
+    const delay = animation.transition?.delay ?? 0;
+    let time = 0;
+    let speed = 1;
+    let state = "running";
+    for (const command of animation.pending) {
+        switch (command.kind) {
+            case "pause":
+                state = "paused";
+                break;
+            case "play":
+                if (state === "finished")
+                    time = 0;
+                state = "running";
+                break;
+            case "complete":
+                state = "finished";
+                break;
+            case "seek":
+                time = Math.max(0, command.seconds - delay);
+                if (state === "finished")
+                    state = "paused";
+                break;
+            case "speed":
+                speed = command.speed;
+                break;
+            case "attach":
+                break;
+        }
+    }
+    return { time, speed, duration: undefined, iterationDuration: undefined, state, startTime: null };
+}
+/** A cancelled animation is back at its start. */
+function rewound(animation) {
+    if (animation.ended)
+        animation.ended = { ...animation.ended, time: 0 };
+}
+const MEASURER_KEY = Symbol.for("@ghia/native/motion-measurer");
+/** Called by the entry points that load the native addon, as `registerKeyframesValidator` is. */
+export function registerAnimationMeasurer(measure) {
+    Reflect.set(globalThis, MEASURER_KEY, measure);
+}
+/** How long the animation lasts, before the value it animates is bound to a renderer. */
+function measured(animation) {
+    const measure = Reflect.get(globalThis, MEASURER_KEY);
+    if (!measure) {
+        throw new Error("The duration of an animation is not known until its value is bound to a renderer");
+    }
+    return measure(animation.from, animation.target, wireTransition(animation.transition));
+}
+/** `finished` is for callers; what cleans up after an animation waits on this one. */
+const settlements = new WeakMap();
+const COUNTER_KEY = Symbol.for("@ghia/native/motion-value-ids");
+/** One counter per process, so values from two copies of this module never share an id. */
+function nextId() {
+    const next = (Reflect.get(globalThis, COUNTER_KEY) ?? 0) + 1;
+    Reflect.set(globalThis, COUNTER_KEY, next);
+    return next;
+}
+let tracker;
+function tracking(onRead, run) {
+    const outer = tracker;
+    tracker = onRead;
+    try {
+        return run();
+    }
+    finally {
+        tracker = outer;
+    }
+}
+function deferred() {
+    let resolve = () => { };
+    const promise = new Promise((done) => {
+        resolve = done;
+    });
+    return { promise, resolve };
+}
+function sameValue(a, b) {
+    return a === b || JSON.stringify(a) === JSON.stringify(b);
+}
+function assertHost(renderer) {
+    const missing = HOST_METHODS.filter((method) => typeof Reflect.get(renderer, method) !== "function");
+    if (missing.length > 0) {
+        throw new Error(`This renderer has no motion value graph (missing ${missing.join(", ")}), so a motion value cannot be bound to it`);
+    }
+}
+export class MotionValue {
+    id = nextId();
+    #definition;
+    /** The value while there is no native node. Sources and springs only. */
+    #state;
+    #attachment;
+    #bindings = 0;
+    /** Elements that bind this value to `width`, `height` or an inset under reduced motion. */
+    #reducers = 0;
+    #destroyed = false;
+    #animation;
+    /**
+     * Motion's `value.animation`, which `isAnimating()` reads: set by `animate()`, cleared when the
+     * animation finishes and by the value's own `stop()` and `jump()`, not by the controls' `stop()`
+     * and `cancel()`.
+     */
+    #driving;
+    /** The animation `cancel()` ended last, which `play()` may start again until another one takes the value. */
+    #cancelled;
+    #counts = {
+        change: 0,
+        animationStart: 0,
+        animationComplete: 0,
+    };
+    #listeners = {
+        change: [],
+        animationStart: [],
+        animationComplete: [],
+    };
+    /** Use `motionValue`, `transformValue`, `springValue`, `computedValue` or `velocityValue`. */
+    constructor(definition, initial) {
+        this.#definition = definition;
+        this.#state = initial;
+    }
+    /** The renderer this value is bound to, if any. */
+    get host() {
+        return this.#attachment?.renderer;
+    }
+    /**
+     * The current value. Bound, it is read from the renderer at its clock. A
+     * transform and a spring follower have no state of their own, so they can
+     * only be read while bound.
+     */
+    get() {
+        tracker?.(this);
+        this.#assertAlive();
+        if (this.#attachment)
+            return this.#attachment.renderer.getMotionValue(this.id);
+        const definition = this.#definition;
+        switch (definition.kind) {
+            case "source":
+            case "spring":
+                return this.#state;
+            case "computed":
+                return definition.compute();
+            case "transform":
+            case "follower":
+                throw new Error(`A ${definition.kind} motion value has no state until it is bound to a renderer, so it cannot be read yet`);
+        }
+    }
+    /**
+     * Writes the value. It does not stop a running animation: call `stop()`
+     * first to take the value from the animation. On a spring it moves the
+     * target.
+     */
+    set(value) {
+        this.#write("set", value);
+    }
+    /** Writes the value, ending any animation and dropping its velocity. */
+    jump(value) {
+        // Like Motion's, it stops an animation only while the value has one: a finished one stays finished.
+        if (this.#driving)
+            this.#ending(() => this.#write("jump", value), "stopped");
+        else
+            this.#write("jump", value);
+        this.#driving = undefined;
+    }
+    /** Units per second, for a value that holds a number. A value that is not bound has none. */
+    getVelocity() {
+        tracker?.(this);
+        this.#assertAlive();
+        if (this.#attachment)
+            return this.#attachment.renderer.getMotionValueVelocity(this.id);
+        if (typeof this.get() !== "number") {
+            throw new Error("getVelocity is for motion values that hold a number");
+        }
+        return 0;
+    }
+    /** Whether an animation drives the value: it stays true after the controls' `stop()` and `cancel()`. */
+    isAnimating() {
+        this.#assertAlive();
+        // A spring and a transform move without an animate(): the renderer says.
+        if (this.#definition.kind !== "source" && this.#attachment) {
+            return this.#attachment.renderer.isMotionValueAnimating(this.id);
+        }
+        const driving = this.#driving;
+        if (driving?.started && !driving.done && !driving.ended && this.#attachment) {
+            // The completion event may not have reached JS yet.
+            if (this.#attachment.renderer.getMotionValuePlayback(this.id)?.state === "finished")
+                this.#finish(driving);
+        }
+        return this.#driving !== undefined;
+    }
+    /** Ends an animation where it is, keeping the speed for the next one. */
+    stop() {
+        this.#assertAlive();
+        if (this.#driving)
+            this.#endAnimation();
+        this.#driving = undefined;
+    }
+    #endAnimation() {
+        this.#ending(() => this.#attachment?.renderer.stopMotionValue(this.id), "stopped");
+    }
+    /**
+     * Animates from where the value is, with the speed it has. Before the value
+     * is bound the animation waits, and starts from the value at that point.
+     * Only a `motionValue()` animates: a spring is moved with `set()`. The controls
+     * it returns have the names and semantics of Motion's.
+     */
+    animate(target, transition) {
+        this.#assertAlive();
+        if (this.#definition.kind !== "source") {
+            throw new Error(this.#definition.kind === "spring"
+                ? "A spring motion value cannot be animated: set it to move its target"
+                : `A ${this.#definition.kind} motion value is computed from other values and cannot be animated`);
+        }
+        this.#cancelled = undefined;
+        const animation = {
+            target: target,
+            from: this.get(),
+            transition: this.#reducers > 0 ? INSTANT : transition,
+            started: false,
+            pending: [],
+            done: false,
+            finished: deferred(),
+            settled: deferred(),
+        };
+        const previous = this.#animation;
+        // Read before the new animation takes the value's place in the renderer.
+        const leaving = previous && this.#snapshot(previous);
+        this.#animation = animation;
+        const drivingBefore = this.#driving;
+        this.#driving = animation;
+        try {
+            if (this.#attachment)
+                this.#start(animation);
+        }
+        catch (error) {
+            if (this.#animation === undefined)
+                this.#animation = previous;
+            this.#driving = drivingBefore;
+            throw error;
+        }
+        // The new animation holds the node first, so replacing the last one
+        // cannot be the release that disposes it.
+        if (previous && leaving)
+            this.#end(previous, leaving, "released");
+        return this.#controls(animation);
+    }
+    #controls(animation) {
+        const playback = () => this.#snapshot(animation);
+        const command = (command) => this.#command(animation, command);
+        const controls = {
+            get time() {
+                return playback().time;
+            },
+            set time(seconds) {
+                command({ kind: "seek", seconds });
+            },
+            get speed() {
+                return playback().speed;
+            },
+            set speed(speed) {
+                command({ kind: "speed", speed });
+            },
+            get duration() {
+                return playback().duration ?? measured(animation).duration;
+            },
+            get iterationDuration() {
+                return playback().iterationDuration ?? measured(animation).iterationDuration;
+            },
+            get state() {
+                return playback().state;
+            },
+            get startTime() {
+                return playback().startTime;
+            },
+            get finished() {
+                return animation.finished.promise;
+            },
+            then: (onFulfilled, onRejected) => animation.finished.promise.then(onFulfilled, onRejected),
+            stop: () => {
+                if (animation.ended)
+                    animation.cleanup?.();
+                else
+                    this.#endAnimation();
+            },
+            cancel: () => {
+                if (animation.ended)
+                    return;
+                const finished = playback().state === "finished";
+                // Motion's cancel puts the time of a finished animation at its end.
+                if (finished && animation.started)
+                    this.#attached().renderer.completeMotionValue(this.id);
+                animation.cancelling = true;
+                this.#endAnimation();
+                this.#cancelled = animation;
+                if (finished)
+                    return;
+                this.#write("jump", startOf(animation.target, animation.from));
+                rewound(animation);
+            },
+            complete: () => command({ kind: "complete" }),
+            play: () => command({ kind: "play" }),
+            pause: () => command({ kind: "pause" }),
+            attachTimeline: (timeline) => {
+                this.#attachTimeline(animation, controls, timeline);
+                return () => {
+                    controls.stop();
+                    controls.stop();
+                };
+            },
+        };
+        animation.controls = controls;
+        settlements.set(controls, animation.settled.promise);
+        return controls;
+    }
+    #attachTimeline(animation, controls, timeline) {
+        if (!animation.started && !animation.ended) {
+            // Motion keeps one pending timeline.
+            const earlier = animation.pending.findIndex((command) => command.kind === "attach");
+            if (earlier >= 0)
+                animation.pending.splice(earlier, 1);
+            animation.pending.push({ kind: "attach", timeline });
+            return;
+        }
+        if (!animation.ended)
+            this.#attached().renderer.detachMotionValueClock(this.id);
+        animation.cleanup = timeline.observe(controls);
+    }
+    #command(animation, command) {
+        if (animation.ended) {
+            if (command.kind === "play")
+                this.#restart(animation);
+            return;
+        }
+        if (!animation.started) {
+            animation.pending.push(command);
+            return;
+        }
+        this.#apply(animation, command);
+    }
+    /** `play()` after `cancel()`: the animation runs again from its first keyframe, at the speed it had. */
+    #restart(animation) {
+        const ended = animation.ended;
+        if (this.#destroyed || !ended || this.#cancelled !== animation || this.#animation)
+            return;
+        this.#cancelled = undefined;
+        animation.ended = undefined;
+        animation.started = false;
+        animation.done = false;
+        animation.last = undefined;
+        animation.pending.length = 0;
+        if (ended.speed !== 1)
+            animation.pending.push({ kind: "speed", speed: ended.speed });
+        // A cancel that found the animation finished left the value on its end.
+        this.#write("jump", startOf(animation.target, animation.from));
+        this.#animation = animation;
+        animation.cancelling = false;
+        if (this.#attachment)
+            this.#start(animation);
+    }
+    /** Runs a control on the renderer, which owns the animation once it has started. */
+    #apply(animation, command) {
+        const renderer = this.#attached().renderer;
+        switch (command.kind) {
+            case "pause":
+                renderer.pauseMotionValue(this.id);
+                return;
+            case "play":
+                this.#play(animation);
+                return;
+            case "seek":
+                renderer.seekMotionValue(this.id, command.seconds);
+                return;
+            case "speed":
+                renderer.setMotionValueSpeed(this.id, command.speed);
+                return;
+            case "complete":
+                renderer.completeMotionValue(this.id);
+                this.#finish(animation);
+                return;
+            case "attach":
+                this.#attachTimeline(animation, this.#controlsOf(animation), command.timeline);
+                return;
+        }
+    }
+    #controlsOf(animation) {
+        if (!animation.controls)
+            throw new Error(`Motion value ${this.id} has an animation without controls`);
+        return animation.controls;
+    }
+    #play(animation) {
+        const renderer = this.#attached().renderer;
+        const playback = renderer.getMotionValuePlayback(this.id);
+        if (playback === null)
+            return;
+        if (playback.state === "finished") {
+            // Held through the hand-over, so letting go of the finished run cannot be the release
+            // that disposes the node.
+            const hold = this.#watch("animationComplete");
+            this.#finish(animation);
+            animation.finished = deferred();
+            animation.done = false;
+            animation.unwatch = hold;
+        }
+        renderer.playMotionValue(this.id);
+    }
+    /** What the controls of `animation` read now. */
+    #snapshot(animation) {
+        if (animation.ended)
+            return animation.ended;
+        if (!animation.started)
+            return pendingPlayback(animation);
+        const playback = this.#attached().renderer.getMotionValuePlayback(this.id);
+        if (playback === null) {
+            // The renderer let go of a finished animation when the value was written.
+            return {
+                ...(animation.last ?? pendingPlayback(animation)),
+                state: animation.done ? "finished" : "idle",
+                startTime: null,
+            };
+        }
+        animation.last = { ...playback, startTime: playback.startTime ?? null, state: playback.state };
+        return animation.last;
+    }
+    #attached() {
+        if (!this.#attachment)
+            throw new Error(`Motion value ${this.id} has no renderer to control an animation on`);
+        return this.#attachment;
+    }
+    /**
+     * Makes `animate()` jump to its target, finishing on the next frame as a
+     * zero-length animation does, for as long as the returned release is not
+     * called. The adapters call it for a value that a reduced-motion
+     * `motion.*` element binds to `width`, `height` or an inset.
+     */
+    reduceMotion() {
+        this.#reducers += 1;
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            this.#reducers -= 1;
+        };
+    }
+    on(event, callback) {
+        this.#assertAlive();
+        const listener = { callback: callback };
+        this.#listeners[event].push(listener);
+        const unwatch = this.#watch(event);
+        return () => {
+            const index = this.#listeners[event].indexOf(listener);
+            if (index >= 0)
+                this.#listeners[event].splice(index, 1);
+            unwatch();
+        };
+    }
+    /**
+     * Binds the value to a renderer, creating its native node on the first
+     * bind. Returns the release. The node goes when every binding is released
+     * and no listener is left; the value keeps its state in JS.
+     */
+    bind(renderer) {
+        this.#assertAlive();
+        assertHost(renderer);
+        if (this.#attachment && this.#attachment.renderer !== renderer) {
+            throw new Error(`Motion value ${this.id} is bound to another renderer. A value drives one window at a time; release it there first`);
+        }
+        // Counted before the node is attached, so an animation that ends while it is cannot take the node away.
+        this.#bindings += 1;
+        if (!this.#attachment) {
+            try {
+                this.#attach(renderer);
+            }
+            catch (error) {
+                this.#bindings -= 1;
+                throw error;
+            }
+        }
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            if (this.#destroyed)
+                return;
+            this.#bindings -= 1;
+            this.#maybeDetach();
+        };
+    }
+    /**
+     * Drops the value: its node is disposed whatever still binds it, its
+     * listeners are removed and any animation ends. Every later call throws.
+     */
+    destroy() {
+        if (this.#destroyed)
+            return;
+        this.#ending(() => { }, "released");
+        this.#driving = undefined;
+        this.#detach(false);
+        this.#destroyed = true;
+        this.#bindings = 0;
+        for (const kind of Object.keys(this.#listeners)) {
+            this.#listeners[kind].length = 0;
+            this.#counts[kind] = 0;
+        }
+    }
+    #assertAlive() {
+        if (this.#destroyed)
+            throw new Error(`Motion value ${this.id} was destroyed`);
+    }
+    #write(method, value) {
+        this.#assertAlive();
+        const definition = this.#definition;
+        if (definition.kind === "transform" || definition.kind === "computed") {
+            throw new Error(`A ${definition.kind} motion value is computed from other values and cannot be written`);
+        }
+        const attachment = this.#attachment;
+        if (attachment) {
+            if (method === "set")
+                attachment.renderer.setMotionValue(this.id, value);
+            else
+                attachment.renderer.jumpMotionValue(this.id, value);
+            return;
+        }
+        if (definition.kind === "follower") {
+            throw new Error("A spring follower has no state until it is bound to a renderer, so it cannot be written yet");
+        }
+        const changed = !sameValue(this.#state, value);
+        this.#state = value;
+        if (changed)
+            this.#emit("change", value);
+    }
+    #emit(event, ...args) {
+        for (const listener of [...this.#listeners[event]]) {
+            ;
+            listener.callback(...args);
+        }
+    }
+    #sink = {
+        change: (value) => this.#emit("change", value),
+        animationStart: () => this.#emit("animationStart"),
+        animationComplete: () => {
+            this.#emit("animationComplete");
+            const attachment = this.#attachment;
+            const animation = this.#animation;
+            if (!attachment || !animation?.started || animation.done)
+                return;
+            // A stop and a new animation in one frame deliver the old completion
+            // after the new start, so ask whether the animation is over.
+            if (attachment.renderer.getMotionValuePlayback(this.id)?.state === "finished")
+                this.#finish(animation);
+        },
+    };
+    #watch(kind) {
+        this.#counts[kind] += 1;
+        this.#syncListener();
+        let watching = true;
+        return () => {
+            if (!watching)
+                return;
+            watching = false;
+            if (this.#destroyed)
+                return;
+            this.#counts[kind] -= 1;
+            this.#syncListener();
+            this.#maybeDetach();
+        };
+    }
+    #syncListener() {
+        const attachment = this.#attachment;
+        if (!attachment)
+            return;
+        const change = this.#counts.change > 0;
+        const animation = this.#counts.animationStart + this.#counts.animationComplete > 0;
+        if (attachment.sentChange === change && attachment.sentAnimation === animation)
+            return;
+        attachment.sentChange = change;
+        attachment.sentAnimation = animation;
+        attachment.renderer.setMotionValueListener(this.id, change, animation);
+    }
+    #maybeDetach() {
+        if (!this.#attachment || this.#bindings > 0)
+            return;
+        if (Object.values(this.#counts).some((count) => count > 0))
+            return;
+        this.#detach(true);
+    }
+    #attach(renderer) {
+        const attachment = {
+            renderer,
+            teardown: [],
+            created: false,
+            sentChange: false,
+            sentAnimation: false,
+        };
+        this.#attachment = attachment;
+        try {
+            this.#create(attachment);
+            attachment.created = true;
+            attachment.unsubscribe = createRendererState(renderer).subscribeMotionValue(this.id, this.#sink);
+            this.#syncListener();
+            const animation = this.#animation;
+            if (animation && !animation.started)
+                this.#start(animation);
+        }
+        catch (error) {
+            this.#attachment = undefined;
+            attachment.unsubscribe?.();
+            if (attachment.created)
+                renderer.disposeMotionValue(this.id);
+            for (const undo of attachment.teardown.reverse())
+                undo();
+            throw error;
+        }
+    }
+    #create(attachment) {
+        const renderer = attachment.renderer;
+        const definition = this.#definition;
+        switch (definition.kind) {
+            case "source":
+                renderer.createMotionValue(this.id, this.#state);
+                return;
+            case "spring":
+                renderer.createMotionSpring(this.id, this.#state, definition.config);
+                return;
+            case "transform":
+                attachment.teardown.push(definition.input.bind(renderer));
+                renderer.createMotionTransform(this.id, definition.input.id, definition.inputRange, definition.outputRange, definition.options);
+                return;
+            case "follower":
+                attachment.teardown.push(definition.source.bind(renderer));
+                renderer.createMotionFollower(this.id, definition.source.id, definition.config);
+                return;
+            case "computed":
+                this.#createComputed(attachment, definition);
+                return;
+        }
+    }
+    /**
+     * A computed value is a source that JS keeps current: it follows the change
+     * events of every value its function read, so it is not linked natively and
+     * trails them by a frame.
+     */
+    #createComputed(attachment, definition) {
+        const renderer = attachment.renderer;
+        const watched = new Map();
+        let reads = new Set();
+        const read = (dep) => {
+            if (dep === this || reads.has(dep))
+                return;
+            reads.add(dep);
+            if (watched.has(dep))
+                return;
+            // Bound before the read goes on, so a transform can be read at all.
+            const release = dep.bind(renderer);
+            const stops = definition.triggers.map((trigger) => dep.on(trigger, update));
+            watched.set(dep, () => {
+                for (const stop of stops)
+                    stop();
+                release();
+            });
+        };
+        const evaluate = () => {
+            reads = new Set();
+            const result = tracking(read, definition.compute);
+            for (const [dep, release] of watched) {
+                if (reads.has(dep))
+                    continue;
+                watched.delete(dep);
+                release();
+            }
+            return result;
+        };
+        const update = () => {
+            if (this.#attachment !== attachment)
+                return;
+            renderer.setMotionValue(this.id, evaluate());
+        };
+        attachment.teardown.push(() => {
+            for (const release of watched.values())
+                release();
+            watched.clear();
+        });
+        renderer.createMotionValue(this.id, evaluate());
+    }
+    #detach(keepState) {
+        const attachment = this.#attachment;
+        if (!attachment)
+            return;
+        const animation = this.#animation;
+        const leaving = animation && this.#snapshot(animation);
+        this.#attachment = undefined;
+        const kind = this.#definition.kind;
+        if (keepState && (kind === "source" || kind === "spring")) {
+            this.#state = attachment.renderer.getMotionValue(this.id);
+        }
+        if (animation && leaving)
+            this.#end(animation, leaving, "released");
+        // The sink goes first, then the node, then the inputs the node read.
+        attachment.unsubscribe?.();
+        attachment.renderer.disposeMotionValue(this.id);
+        for (const undo of attachment.teardown.reverse())
+            undo();
+    }
+    #start(animation) {
+        const attachment = this.#attachment;
+        if (!attachment)
+            throw new Error(`Motion value ${this.id} has no renderer to animate on`);
+        animation.started = true;
+        // Listened before the animation starts, so its start and end are seen.
+        animation.unwatch = this.#watch("animationComplete");
+        const renderer = attachment.renderer;
+        try {
+            renderer.animateMotionValue(this.id, animation.target, wireTransition(animation.transition));
+            for (const command of animation.pending.splice(0))
+                this.#apply(animation, command);
+        }
+        catch (error) {
+            this.#end(animation, { ...pendingPlayback(animation), state: "idle" }, "stopped");
+            throw error;
+        }
+        const playback = renderer.getMotionValuePlayback(this.id);
+        if (playback === null)
+            throw new Error(`Motion value ${this.id} has no animation after it was started`);
+        animation.last = { ...playback, startTime: playback.startTime ?? null, state: playback.state };
+        if (playback.state === "finished")
+            this.#finish(animation);
+    }
+    /**
+     * Runs `operation`, which takes the value from the animation, and ends the animation. What the
+     * controls read is taken first, while the renderer still has the animation.
+     */
+    #ending(operation, how) {
+        const animation = this.#animation;
+        const leaving = animation && this.#snapshot(animation);
+        operation();
+        if (animation && leaving)
+            this.#end(animation, leaving, how);
+    }
+    /** The animation got to its end, or `complete()` took it there: `finished` resolves. */
+    #finish(animation) {
+        if (animation.done || animation.ended)
+            return;
+        if (this.#driving === animation)
+            this.#driving = undefined;
+        animation.done = true;
+        animation.finished.resolve();
+        animation.settled.resolve();
+        const unwatch = animation.unwatch;
+        animation.unwatch = undefined;
+        unwatch?.();
+    }
+    /**
+     * The animation is over for good: stopped, cancelled, replaced, or its value went away. Its
+     * controls read as `leaving` from then on, and `finished` stays as it was.
+     */
+    #end(animation, leaving, how) {
+        if (animation.ended)
+            return;
+        const finished = how === "released" && (animation.done || leaving.state === "finished");
+        animation.ended = { ...leaving, state: finished ? "finished" : "idle", startTime: null };
+        if (this.#animation === animation)
+            this.#animation = undefined;
+        const unwatch = animation.unwatch;
+        animation.unwatch = undefined;
+        animation.settled.resolve();
+        unwatch?.();
+        if (!animation.cancelling)
+            animation.cleanup?.();
+    }
+}
+/** A value that is written with `set` and `jump` or animated. */
+export function motionValue(initial) {
+    return new MotionValue({ kind: "source" }, initial);
+}
+export function isMotionValue(value) {
+    return value instanceof MotionValue;
+}
+/**
+ * Maps a number value through `inputRange` and `outputRange`, natively: it is
+ * sampled at the same instant as its input. The input range is ascending or
+ * descending and may repeat a value, which is a step. The output holds
+ * numbers, colours or shadows. A bad range is reported when the value is bound.
+ */
+export function transformValue(input, inputRange, outputRange, options) {
+    return new MotionValue({
+        kind: "transform",
+        input,
+        inputRange,
+        outputRange,
+        options,
+    });
+}
+export function springValue(source, config = {}) {
+    if (isMotionValue(source))
+        return new MotionValue({ kind: "follower", source, config });
+    return new MotionValue({ kind: "spring", config }, source);
+}
+/**
+ * A value computed in JS from the motion values `compute` reads with `get()`.
+ * It is not native-linked: it follows their change events and writes a source,
+ * so it trails them by a frame, and it only updates while it is bound.
+ * Unbound, `get()` runs `compute`.
+ */
+export function computedValue(compute) {
+    return new MotionValue({
+        kind: "computed",
+        compute,
+        triggers: ["change"],
+    });
+}
+/**
+ * The velocity of a number value, in units per second. Like `computedValue`
+ * it is JS-derived and not native-linked: it reads `getVelocity()` of the
+ * source on each of its changes, and again when its animation completes.
+ */
+export function velocityValue(source) {
+    return new MotionValue({
+        kind: "computed",
+        compute: () => source.getVelocity(),
+        triggers: ["change", "animationComplete"],
+    });
+}
+export function animate(first, second, third) {
+    if (first instanceof MotionValue)
+        return first.animate(second, third);
+    const options = third;
+    if (!options?.host)
+        throw new Error("animate(from, to) needs options.host, the renderer that samples the animation");
+    const curve = { ...options };
+    delete curve.host;
+    delete curve.onUpdate;
+    const temporary = motionValue(first);
+    const release = temporary.bind(options.host);
+    const onUpdate = options.onUpdate;
+    const stopUpdates = onUpdate ? temporary.on("change", onUpdate) : () => { };
+    try {
+        const controls = temporary.animate(second, curve);
+        const settled = settlements.get(controls);
+        if (!settled)
+            throw new Error("An animation of a motion value has no settlement");
+        void settled.then(() => {
+            stopUpdates();
+            release();
+            temporary.destroy();
+        });
+        return controls;
+    }
+    catch (error) {
+        stopUpdates();
+        release();
+        temporary.destroy();
+        throw error;
+    }
+}
+//# sourceMappingURL=motion-value.js.map