@msb235/blits 0.2.0 → 0.3.0

package/dist/motion.js

@@ -1,89 +1,540 @@
+import { curve } from './easing.js';
+import { absent, Numbers } from './numbers.js';
+import { reading } from './reading.js';
 import { Store } from './store.js';
+const UNDER = 0;
+const CRITICAL = 1;
+const OVER = 2;
+const COAST = 3;
+const EASED = 4;
+/**
+ * A patch's law, `[form, settle, k1, k2, k3]`: which closed form its stretches follow, its `settle`,
+ * and up to three constants that form reads. It heads the patch's `runs`, so `solve` finds them in
+ * the buffer a sample already reads rather than in an object of their own.
+ */
+const HEAD = 5;
+/** A motion patch's `frame` while no mix plays it: no subject has a latest frame. */
+export const noFrame = () => Number.NaN;
+const solved = { y: 0, dy: 0 };
+/** Where every patch's `sample` leaves a value on its way to the mix; none outlives its call. */
+let shared = { xs: new Float64Array(4), vs: new Float64Array(4) };
+/** A subject's flags: its value is a number; it has changes pending; it has older stretches. */
+const SCALAR = 1;
+const PENDING = 2;
+const OLDER = 4;
+/**
+ * The terms of a stretch that depend only on how long since its release, the same on every axis, so
+ * a sample works them out once rather than once per axis.
+ */
+const timed = { e: 0, e2: 0, cos: 0, sin: 0 };
+/** How far a tween's slope is read either side of `u`, for an easing that is only a function. */
+const SPAN = 1e-4;
+/**
+ * Whether an evaluation wants a tween's velocity, which costs two more reads of its easing. Only
+ * `read` reports it; a mix and a retarget never use it.
+ */
+let slope = false;
+/** The last tween sample's time, curve and length, and the share of the way it had left to go. */
+const memo = { dt: Number.NaN, ease: undefined, secs: 0, left: 0 };
+/** `t` seconds after release, the terms every axis shares, into `timed`. */
+function prepare(law, t) {
+    switch (law[0]) {
+        case UNDER: {
+            const zeta = law[2];
+            const w0 = law[3];
+            const wd = law[4];
+            timed.e = Math.exp(-zeta * w0 * t);
+            timed.cos = Math.cos(wd * t);
+            timed.sin = Math.sin(wd * t);
+            return;
+        }
+        case CRITICAL: {
+            const w0 = law[3];
+            timed.e = Math.exp(-w0 * t);
+            return;
+        }
+        case OVER: {
+            timed.e = Math.exp(law[2] * t);
+            timed.e2 = Math.exp(law[3] * t);
+            return;
+        }
+        default:
+            timed.e = Math.exp(-t / law[2]);
+    }
+}
+/**
+ * One axis, `t` seconds after release, `y0` from where it heads and moving at `v0`, into `solved`,
+ * with `timed` prepared for `t`.
+ */
+function solve(law, y0, v0, t) {
+    switch (law[0]) {
+        case UNDER: {
+            const zeta = law[2];
+            const w0 = law[3];
+            const wd = law[4];
+            const e = timed.e;
+            const b = (v0 + zeta * w0 * y0) / wd;
+            const cos = timed.cos;
+            const sin = timed.sin;
+            const y = e * (y0 * cos + b * sin);
+            solved.y = y;
+            solved.dy = -zeta * w0 * y + e * wd * (b * cos - y0 * sin);
+            return;
+        }
+        case CRITICAL: {
+            const w0 = law[3];
+            const e = timed.e;
+            const b = v0 + w0 * y0;
+            const y = e * (y0 + b * t);
+            solved.y = y;
+            solved.dy = e * b - w0 * y;
+            return;
+        }
+        case OVER: {
+            const r1 = law[2];
+            const r2 = law[3];
+            const a = (v0 - r2 * y0) / (r1 - r2);
+            const b = y0 - a;
+            const e1 = timed.e;
+            const e2 = timed.e2;
+            solved.y = a * e1 + b * e2;
+            solved.dy = a * r1 * e1 + b * r2 * e2;
+            return;
+        }
+        default: {
+            // Released at x moving at v, a glide comes to rest at x + v·τ; y is the distance still to go,
+            // which friction closes as e^(−t/τ), and its derivative at release is v again.
+            const tau = law[2];
+            const e = timed.e;
+            solved.y = y0 * e;
+            solved.dy = (-y0 / tau) * e;
+        }
+    }
+}
 const axes = (v) => (typeof v === 'number' ? [v] : [...v]);
 const per = (p, subject) => typeof p === 'function' ? p(subject) : p;
-function moving(writes, shape) {
-    const held = new Store();
-    const entry = (subject) => {
-        let h = held.get(subject);
-        if (h === undefined) {
-            h = { segment: null, pending: [], last: Number.NaN };
-            held.set(subject, h);
-        }
-        return h;
-    };
-    const evaluate = (seg, at) => {
-        const t = Math.max(0, at - seg.at) / 1000;
-        const x = new Array(seg.to.length);
-        const v = new Array(seg.to.length);
-        let still = shape.settle > 0;
-        for (let i = 0; i < seg.to.length; i++) {
-            const to = seg.to[i];
-            const [y, dy] = shape.solve(seg.x0[i] - to, seg.v0[i], t);
-            x[i] = to + y;
-            v[i] = dy;
-            if (Math.abs(y) > shape.settle || Math.abs(dy) > shape.settle)
+/**
+ * A motion patch's subjects: the stretch each is playing, in one flat array by a number the patch
+ * gives it, with earlier stretches a read back may reach and changes not yet applied beside them.
+ * The one copy, read by `at` and by a mix's lane alike.
+ *
+ * After the law, each subject's run of `stride` numbers is its release time, its flags, then `x0`,
+ * `v0` and `to` per axis. A live sample reads this one buffer and nothing else the patch owns: at
+ * 10k springs of one subject each, a buffer per field, a map lookup per sample and the law in an
+ * object of its own took a call from 130 ns to 490.
+ */
+export class Motions {
+    shape;
+    numbers = new Numbers((slot) => this.forget(slot));
+    slots = new Store();
+    /** Axes per subject; -1 until the first subject sets it. */
+    n = -1;
+    cap = 0;
+    stride = 0;
+    runs;
+    /**
+     * Where `sample` leaves a subject's position and velocity, per axis. Shared by every patch, so
+     * read it before the next sample.
+     */
+    xs = new Float64Array(0);
+    vs = new Float64Array(0);
+    pending = new Map();
+    older = new Map();
+    /**
+     * The subject's voice time at the mix's latest frame, which an untimed change and a `read` with
+     * no time take; NaN where no frame of the patch's voice has met the subject. Set by the mix that
+     * cues the patch, and put back when its voice retires.
+     */
+    frame = noFrame;
+    constructor(shape) {
+        this.shape = shape;
+        this.runs = Float64Array.from(shape.law);
+    }
+    /** The patch's number for `subject`, made with its first stretch on first ask. */
+    slot(subject) {
+        const known = this.slots.get(subject);
+        if (known !== undefined)
+            return known;
+        const x = this.shape.from(subject);
+        const v = this.shape.velocity(subject);
+        const to = this.shape.aim(x, v, null, subject);
+        const n = this.n < 0 ? x.length : this.n;
+        for (const a of [x, v, to])
+            this.check(a, n);
+        if (this.n < 0) {
+            this.n = n;
+            this.stride = 2 + 3 * n;
+            if (shared.xs.length < n)
+                shared = { xs: new Float64Array(n), vs: new Float64Array(n) };
+            this.xs = shared.xs;
+            this.vs = shared.vs;
+        }
+        const s = this.numbers.take(subject);
+        this.slots.set(subject, s);
+        this.grow(s + 1);
+        this.runs[this.base(s) + 1] = this.shape.scalar(subject) ? SCALAR : 0;
+        this.write(s, { at: 0, x0: x, v0: v, to });
+        return s;
+    }
+    /** Forgets a subject, so a later ask starts it afresh from `from`. */
+    release(subject) {
+        const s = this.slots.get(subject);
+        if (s === undefined)
+            return;
+        this.slots.delete(subject);
+        this.numbers.release(s);
+    }
+    /** Whether subject `s`'s value is a number rather than an array. */
+    scalar(s) {
+        return (this.runs[this.base(s) + 1] & SCALAR) !== 0;
+    }
+    /** The value `at` hands the mix: the first axis for a number, a fresh array otherwise. */
+    value(s, xs) {
+        if ((this.runs[this.base(s) + 1] & SCALAR) !== 0)
+            return xs[0];
+        const n = this.n;
+        const out = new Array(n);
+        for (let i = 0; i < n; i++)
+            out[i] = xs[i];
+        return out;
+    }
+    /**
+     * Position and velocity at voice time `t` into `xo` and `vo`, a tween's velocity left at 0. A live
+     * read stamps every untimed change with `t` and commits every change due by then, in time order;
+     * a projection's read applies the timed ones to a copy and commits nothing.
+     */
+    sample(s, t, xo, vo) {
+        if (reading.live) {
+            const runs = this.runs;
+            const b = this.base(s);
+            if (runs[b + 1] & PENDING)
+                this.commit(s, t);
+            if (runs[b + 1] & OLDER)
+                this.prune(s);
+            const at = runs[b];
+            if (t < at && runs[b + 1] & OLDER)
+                this.evaluateSegment(this.playing(s, t), t, xo, vo);
+            else {
+                const x = b + 2;
+                this.evaluate(at, runs, x, runs, x + this.n, runs, x + 2 * this.n, t, xo, vo);
+            }
+            return;
+        }
+        this.peek(s, t, xo, vo);
+    }
+    /**
+     * Whether a live `sample` at `t` would leave the subject's state as it is: nothing to stamp or
+     * commit by then, and nothing older than `reading.horizon` to let go of.
+     */
+    quiet(s, t) {
+        const runs = this.runs;
+        const b = this.base(s);
+        const flags = runs[b + 1];
+        if (flags & PENDING) {
+            const list = this.pending.get(s);
+            const first = list[0].at;
+            if (first === undefined || first <= t || list[list.length - 1].at === undefined)
+                return false;
+        }
+        if (flags & OLDER) {
+            const list = this.older.get(s);
+            const next = list.length > 1 ? list[1].at : runs[b];
+            if (next <= reading.horizon)
+                return false;
+        }
+        return true;
+    }
+    /** Position and velocity at `at`, default the latest frame; undefined until there is one. */
+    read(subject, at) {
+        const s = this.slots.get(subject);
+        if (s === undefined)
+            return undefined;
+        const when = at ?? this.frame(subject);
+        if (Number.isNaN(when))
+            return undefined;
+        const x = new Float64Array(this.n);
+        const v = new Float64Array(this.n);
+        slope = true;
+        try {
+            this.peek(s, when, x, v);
+        }
+        finally {
+            slope = false;
+        }
+        return { x, v, s };
+    }
+    /**
+     * Queues a retarget or push, untimed at the latest frame, for `subject`'s next read past its time.
+     * The queue keeps the changes with a time in time order, ahead of any still waiting for one.
+     */
+    change(subject, c) {
+        const s = this.slot(subject);
+        this.check(c.to, this.n);
+        this.check(c.v, this.n);
+        if (c.at === undefined) {
+            const at = this.frame(subject);
+            if (!Number.isNaN(at))
+                c.at = at;
+        }
+        const list = this.pending.get(s);
+        if (list === undefined) {
+            this.pending.set(s, [c]);
+            this.flag(s, PENDING, true);
+        }
+        else if (c.at === undefined)
+            list.push(c);
+        else
+            this.queue(list, c, c.at);
+        reading.moved++;
+    }
+    /** Files a change with a time after every one due by then, ahead of those still waiting for one. */
+    queue(list, c, at) {
+        let i = list.length;
+        while (i > 0) {
+            const before = list[i - 1].at;
+            if (before !== undefined && before <= at)
+                break;
+            i--;
+        }
+        list.splice(i, 0, c);
+    }
+    /** Every change due by `t` applied to a copy of the stretch playing then, committing nothing. */
+    peek(s, t, xo, vo) {
+        let seg = this.playing(s, t);
+        const list = this.pending.get(s);
+        if (list !== undefined)
+            for (const change of list) {
+                const a = change.at;
+                if (a === undefined || !(a <= t))
+                    break;
+                if (a >= seg.at)
+                    seg = this.applied(s, seg, change, a);
+            }
+        this.evaluateSegment(seg, t, xo, vo);
+    }
+    check(a, n) {
+        if (a !== undefined && a.length !== n)
+            throw new Error('blits: a motion patch moves every subject on the same number of axes');
+    }
+    flag(s, bit, on) {
+        const i = this.base(s) + 1;
+        const flags = this.runs[i];
+        this.runs[i] = on ? flags | bit : flags & ~bit;
+    }
+    forget(s) {
+        this.pending.delete(s);
+        this.older.delete(s);
+    }
+    /** Where subject `s`'s run starts in `runs`. */
+    base(s) {
+        return HEAD + s * this.stride;
+    }
+    grow(size) {
+        if (size <= this.cap)
+            return;
+        const cap = Math.max(size, this.cap * 2);
+        const runs = new Float64Array(HEAD + cap * this.stride);
+        runs.set(this.runs);
+        this.runs = runs;
+        this.cap = cap;
+    }
+    write(s, seg) {
+        const n = this.n;
+        const b = this.base(s);
+        this.runs[b] = seg.at;
+        for (let i = 0; i < n; i++) {
+            this.runs[b + 2 + i] = seg.x0[i];
+            this.runs[b + 2 + n + i] = seg.v0[i];
+            this.runs[b + 2 + 2 * n + i] = seg.to[i];
+        }
+    }
+    /** The stretch subject `s` is playing now, as an object. */
+    latest(s) {
+        const n = this.n;
+        const x = this.base(s) + 2;
+        return {
+            at: this.runs[this.base(s)],
+            x0: Array.from(this.runs.subarray(x, x + n)),
+            v0: Array.from(this.runs.subarray(x + n, x + 2 * n)),
+            to: Array.from(this.runs.subarray(x + 2 * n, x + 3 * n)),
+        };
+    }
+    /** The stretch playing at voice time `t`: the latest released by then, else the first. */
+    playing(s, t) {
+        const list = this.older.get(s);
+        if (list === undefined || t >= this.runs[this.base(s)])
+            return this.latest(s);
+        if (list[0].at > t)
+            return list[0];
+        let lo = 0;
+        let hi = list.length - 1;
+        while (lo < hi) {
+            const mid = (lo + hi + 1) >> 1;
+            if (list[mid].at <= t)
+                lo = mid;
+            else
+                hi = mid - 1;
+        }
+        return list[lo];
+    }
+    applied(s, seg, change, at) {
+        const x = new Float64Array(this.n);
+        const v = new Float64Array(this.n);
+        this.evaluateSegment(seg, at, x, v);
+        const xs = Array.from(x);
+        const vs = change.v ?? Array.from(v);
+        const subject = this.numbers.subject(s);
+        const to = this.shape.aim(xs, vs, change.to ?? seg.to, subject === absent ? undefined : subject);
+        return { at, x0: xs, v0: vs, to };
+    }
+    commit(s, t) {
+        const list = this.pending.get(s);
+        // The first read of a subject no frame had met: those waiting for a time take this one.
+        if (list[list.length - 1].at === undefined) {
+            let i = list.length;
+            while (i > 0 && list[i - 1].at === undefined)
+                i--;
+            for (const c of list.splice(i)) {
+                c.at = t;
+                this.queue(list, c, t);
+            }
+        }
+        while (list.length > 0) {
+            const change = list[0];
+            const a = change.at;
+            if (a > t)
+                break;
+            list.shift();
+            this.insert(s, this.applied(s, this.playing(s, a), change, a));
+        }
+        if (list.length === 0) {
+            this.pending.delete(s);
+            this.flag(s, PENDING, false);
+        }
+    }
+    insert(s, seg) {
+        let list = this.older.get(s);
+        if (seg.at >= this.runs[this.base(s)]) {
+            if (list === undefined) {
+                list = [];
+                this.older.set(s, list);
+                this.flag(s, OLDER, true);
+            }
+            list.push(this.latest(s));
+            this.write(s, seg);
+            return;
+        }
+        if (list === undefined) {
+            list = [];
+            this.older.set(s, list);
+            this.flag(s, OLDER, true);
+        }
+        let i = list.length;
+        while (i > 0 && list[i - 1].at > seg.at)
+            i--;
+        list.splice(i, 0, seg);
+    }
+    /** Lets go of stretches older than the one in force at `reading.horizon`. */
+    prune(s) {
+        const list = this.older.get(s);
+        if (list === undefined)
+            return;
+        while (list.length > 0 &&
+            (list.length > 1 ? list[1].at : this.runs[this.base(s)]) <=
+                reading.horizon)
+            list.shift();
+        if (list.length === 0) {
+            this.older.delete(s);
+            this.flag(s, OLDER, false);
+        }
+    }
+    evaluateSegment(seg, t, xo, vo) {
+        this.evaluate(seg.at, seg.x0, 0, seg.v0, 0, seg.to, 0, t, xo, vo);
+    }
+    evaluate(at, x0, x, v0, v, to, g, t, xo, vo) {
+        const n = this.n;
+        const dt = Math.max(0, t - at) / 1000;
+        const law = this.runs;
+        if (law[0] === EASED) {
+            this.eased(dt, law[2], x0, x, to, g, xo, vo);
+            return;
+        }
+        const settle = law[1];
+        let still = settle > 0;
+        prepare(law, dt);
+        for (let i = 0; i < n; i++) {
+            const goal = to[g + i];
+            solve(law, x0[x + i] - goal, v0[v + i], dt);
+            xo[i] = goal + solved.y;
+            vo[i] = solved.dy;
+            if (Math.abs(solved.y) > settle || Math.abs(solved.dy) > settle)
                 still = false;
         }
         if (still)
-            return { x: [...seg.to], v: seg.to.map(() => 0) };
-        return { x, v };
-    };
-    const release = (at, x, v, was, subject) => ({
-        at,
-        x0: x,
-        v0: v,
-        to: shape.aim(x, v, was, subject),
-    });
-    /** Brings a subject's motion up to `now`, applying every change due by then, in order. */
-    const advance = (subject, h, now) => {
-        h.segment ??= release(0, shape.from(subject), shape.velocity(subject), null, subject);
-        while (h.pending.length > 0) {
-            const change = h.pending[0];
-            const at = change.at ?? now;
-            if (at > now)
-                break;
-            h.pending.shift();
-            const seg = h.segment;
-            const { x, v } = evaluate(seg, at);
-            const vel = change.v ?? v;
-            h.segment = release(at, x, vel, change.to ?? seg.to, subject);
+            for (let i = 0; i < n; i++) {
+                xo[i] = to[g + i];
+                vo[i] = 0;
+            }
+    }
+    /** A tween's stretch, `dt` seconds after release, kept out of `evaluate` so a spring's stays small. */
+    eased(dt, secs, x0, x, to, g, xo, vo) {
+        const ease = this.shape.ease;
+        const u = dt / secs;
+        // Subjects released together share `dt`, so a frame reads a bezier once, not once each.
+        if (dt !== memo.dt || ease !== memo.ease || secs !== memo.secs) {
+            memo.dt = dt;
+            memo.ease = ease;
+            memo.secs = secs;
+            memo.left = u >= 1 ? 0 : 1 - ease(u);
         }
-        return h.segment;
-    };
-    const out = (subject, xs) => {
-        const t = shape.template(subject);
-        return (typeof t === 'number' ? xs[0] : xs);
-    };
+        const left = memo.left;
+        let rate = 0;
+        if (slope && u < 1) {
+            const lo = Math.max(0, u - SPAN);
+            const hi = Math.min(1, u + SPAN);
+            rate = (ease(hi) - ease(lo)) / (hi - lo) / secs;
+        }
+        for (let i = 0; i < this.n; i++) {
+            const goal = to[g + i];
+            const gap = x0[x + i] - goal;
+            xo[i] = left === 0 ? goal : goal + gap * left;
+            vo[i] = -gap * rate;
+        }
+    }
+}
+const states = new WeakMap();
+/** The state behind a `'motion'` patch, for an engine that reads it directly. */
+export function motionOf(p) {
+    return states.get(p);
+}
+function moving(writes, motion, shape) {
+    const state = new Motions(shape);
+    const push = (subject, velocity, at) => state.change(subject, { at, v: axes(velocity) });
     const patch = {
-        form: 'fn',
+        form: 'motion',
         period: 0,
         writes: [writes],
+        motion,
         at(_phase, subject, setting) {
-            const h = entry(subject);
-            const seg = advance(subject, h, setting.elapsed);
-            h.last = setting.elapsed;
-            return { [writes]: out(subject, evaluate(seg, setting.elapsed).x) };
+            const s = state.slot(subject);
+            state.sample(s, setting.elapsed, state.xs, state.vs);
+            return { [writes]: state.value(s, state.xs) };
         },
         read(subject, at) {
-            const h = held.get(subject);
-            if (h === undefined || h.segment === null)
+            const r = state.read(subject, at);
+            if (r === undefined)
                 return undefined;
-            const { x, v } = evaluate(h.segment, at ?? h.last);
-            return { value: out(subject, x), velocity: out(subject, v) };
-        },
-        push(subject, velocity, at) {
-            entry(subject).pending.push({ at, v: axes(velocity) });
+            return { value: state.value(r.s, r.x), velocity: state.value(r.s, r.v) };
         },
     };
-    const change = (subject, c) => entry(subject).pending.push(c);
-    return { patch, change };
+    states.set(patch, state);
+    return { patch, state, push };
 }
 /**
  * A damped spring toward a target, solved in closed form. `to(subject, target)` retargets one
  * subject mid-flight, and the new stretch starts from where it is and how fast it moves, so there is
- * no kink. Time is the voice's, so `rate` and `seek` apply; a read earlier than the latest change
- * evaluates the latest stretch, not history. Its state is its own, kept per subject: cue each spring
- * on one voice.
+ * no kink. Time is the voice's, so `rate` and `seek` apply. Its state is its own, kept per subject:
+ * cue each spring on one voice. Every subject moves on the same number of axes.
  *
  * @category patch
  */
@@ -91,51 +542,30 @@ export function spring(writes, opts) {
     const k = opts.stiffness ?? 170;
     const c = opts.damping ?? 26;
     const m = opts.mass ?? 1;
+    const settle = opts.settle ?? 1e-4;
     const w0 = Math.sqrt(k / m);
     const zeta = c / (2 * Math.sqrt(k * m));
-    let solve;
-    if (zeta < 1) {
-        const wd = w0 * Math.sqrt(1 - zeta * zeta);
-        solve = (y0, v0, t) => {
-            const e = Math.exp(-zeta * w0 * t);
-            const b = (v0 + zeta * w0 * y0) / wd;
-            const cos = Math.cos(wd * t);
-            const sin = Math.sin(wd * t);
-            const y = e * (y0 * cos + b * sin);
-            return [y, -zeta * w0 * y + e * wd * (b * cos - y0 * sin)];
-        };
-    }
-    else if (zeta === 1) {
-        solve = (y0, v0, t) => {
-            const e = Math.exp(-w0 * t);
-            const b = v0 + w0 * y0;
-            const y = e * (y0 + b * t);
-            return [y, e * b - w0 * y];
-        };
-    }
+    let law;
+    if (zeta < 1)
+        law = [UNDER, settle, zeta, w0, w0 * Math.sqrt(1 - zeta * zeta)];
+    else if (zeta === 1)
+        law = [CRITICAL, settle, 0, w0, 0];
     else {
         const s = Math.sqrt(zeta * zeta - 1);
-        const r1 = -w0 * (zeta - s);
-        const r2 = -w0 * (zeta + s);
-        solve = (y0, v0, t) => {
-            const a = (v0 - r2 * y0) / (r1 - r2);
-            const b = y0 - a;
-            const e1 = Math.exp(r1 * t);
-            const e2 = Math.exp(r2 * t);
-            return [a * e1 + b * e2, a * r1 * e1 + b * r2 * e2];
-        };
+        law = [OVER, settle, -w0 * (zeta - s), -w0 * (zeta + s), 0];
     }
     const target = (subject) => axes(per(opts.to, subject));
-    const { patch, change } = moving(writes, {
+    const { patch, state, push } = moving(writes, { kind: 'spring', stiffness: k, damping: c, mass: m, settle }, {
         from: (s) => axes(per(opts.from ?? opts.to, s)),
         velocity: (s) => opts.velocity === undefined ? target(s).map(() => 0) : axes(per(opts.velocity, s)),
         aim: (_x, _v, was, s) => was ?? target(s),
-        solve,
-        settle: opts.settle ?? 1e-4,
-        template: (s) => per(opts.to, s),
+        law,
+        scalar: (s) => typeof per(opts.to, s) === 'number',
+        ease: undefined,
     });
     return Object.assign(patch, {
-        to: (subject, goal, at) => change(subject, { at, to: axes(goal) }),
+        push,
+        to: (subject, goal, at) => state.change(subject, { at, to: axes(goal) }),
     });
 }
 /**
@@ -146,22 +576,44 @@ export function spring(writes, opts) {
  * @category patch
  */
 export function glide(writes, opts) {
-    const tau = (opts.ms ?? 325) / 1000;
-    // Released at x moving at v, a glide comes to rest at x + v·τ; y is the distance still to go,
-    // which friction closes as e^(−t/τ), and its derivative at release is v again.
-    const solve = (y0, _v0, t) => {
-        const e = Math.exp(-t / tau);
-        return [y0 * e, (-y0 / tau) * e];
-    };
-    const { patch } = moving(writes, {
+    const ms = opts.ms ?? 325;
+    const tau = ms / 1000;
+    const settle = opts.settle ?? 1e-4;
+    const { patch, push } = moving(writes, { kind: 'glide', ms, settle }, {
         from: (s) => axes(per(opts.from, s)),
         velocity: (s) => opts.velocity === undefined
             ? axes(per(opts.from, s)).map(() => 0)
             : axes(per(opts.velocity, s)),
         aim: (x, v) => x.map((xi, i) => xi + v[i] * tau),
-        solve,
-        settle: opts.settle ?? 1e-4,
-        template: (s) => per(opts.from, s),
+        law: [COAST, settle, tau, 0, 0],
+        scalar: (s) => typeof per(opts.from, s) === 'number',
+        ease: undefined,
+    });
+    return Object.assign(patch, { push });
+}
+/**
+ * From one value to another over `ms` along an easing, solved in closed form, so frame rate does not
+ * change where a subject is. `to(subject, target)` retargets one subject mid-flight: the new stretch
+ * starts from where it is and takes the full `ms` again, so its velocity jumps where a spring's
+ * would not. Time is the voice's, so `rate` and `seek` apply, and a voice's `loop` does not repeat
+ * it. Cue each tween on one voice. Every subject moves on the same number of axes.
+ *
+ * @category patch
+ */
+export function tween(writes, opts) {
+    if (!(opts.ms > 0))
+        throw new Error('blits: a tween takes a positive ms');
+    const ease = opts.ease ?? 'ease';
+    const target = (subject) => axes(per(opts.to, subject));
+    const { patch, state } = moving(writes, { kind: 'tween', ms: opts.ms, ease }, {
+        from: (s) => axes(per(opts.from, s)),
+        velocity: (s) => target(s).map(() => 0),
+        aim: (_x, _v, was, s) => was ?? target(s),
+        law: [EASED, 0, opts.ms / 1000, 0, 0],
+        scalar: (s) => typeof per(opts.to, s) === 'number',
+        ease: curve(ease),
+    });
+    return Object.assign(patch, {
+        to: (subject, goal, at) => state.change(subject, { at, to: axes(goal) }),
     });
-    return patch;
 }