@msb235/blits 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -4,9 +4,42 @@ This package follows [semver](https://semver.org). Below 1.0.0, a breaking chang
 version and everything else the patch. Each release lists its changes as **Breaking**, **Added** and
 **Fixed**, and the release workflow refuses a tag with no section here.
 
+## 0.2.0
+
+### Breaking
+
+- A `keys` voice cued with `from: 'current'` now leaves at the velocity the subject had, taken from
+  its last two probed poses, instead of on the first segment's own curve. A subject that was still
+  leaves at rest. Only the first segment changes, and it still lands on its stop.
+- `Handle` gains `ramp`, so an object written to stand in for a handle needs one.
+
+### Added
+
+- `handle.ramp(rate, over)`: eases a voice's playback rate to a new one over `over` ms, so a pause
+  or a slow-motion does not snap. The voice clock integrates the ramp.
+
+- `spring` and `glide`: momentum in closed form, per subject, so where a subject is does not depend
+  on frame rate. `spring.to` retargets and `push` sets a velocity mid-flight, each starting the next
+  stretch from where the subject is and how fast it moves; `read` returns both, for handing motion
+  to another patch.
+
+### Fixed
+
+- Keyed stops, and a `from: 'current'` retarget, interpolate through the channel's own `lerp`, as
+  the schema says. They used plain numeric interpolation unless `lerpBy` named one, so a keyed
+  `hex` color blended its packed integer instead of its components. `lerpBy` still wins, and a
+  `keys` patch read outside a mix uses the `kit` it names.
+
 ## 0.1.1
 
-First release. 0.1.0 was never published: npm holds the number and will not take it. A mix folds concurrent effects into one value per subject per frame: each effect runs
+### Fixed
+
+- Published from the release workflow through npm's trusted publishing, with a provenance
+  statement. The code is 0.1.0's; only the version and this changelog differ.
+
+## 0.1.0
+
+First release, published by hand. A mix folds concurrent effects into one value per subject per frame: each effect runs
 on its own clock with its own state and weight, and the rules for combining them belong to the
 channel being written rather than to the effect writing it.
 

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export { hex, kit, last, max, mixHex, mul, sum, vec } from './channels.js';
 export { mix, mixer } from './mixer.js';
+export type { Motion, Moving, PerSubject, Value } from './motion.js';
+export { glide, spring } from './motion.js';
 export type { KeysOptions, PatchOptions } from './patch.js';
 export { keys, patch } from './patch.js';
 export { gate, lag, level, peak, slew } from './signals.js';

package/dist/index.js

@@ -1,4 +1,5 @@
 export { hex, kit, last, max, mixHex, mul, sum, vec } from './channels.js';
 export { mix, mixer } from './mixer.js';
+export { glide, spring } from './motion.js';
 export { keys, patch } from './patch.js';
 export { gate, lag, level, peak, slew } from './signals.js';

package/dist/mixer.js

@@ -26,15 +26,22 @@ class Voice {
     state = 'pending';
     rate;
     weight;
-    /** elapsed = anchorElapsed + (now − anchorNow) · rate, rebased on a rate change or a seek. */
+    /**
+     * elapsed = anchorElapsed + the rate integrated from anchorNow, rebased on a rate change or a seek.
+     * Without a ramp the rate is constant; with one it moves linearly from `from` to `to` over `over`
+     * mix ms starting at the anchor, and holds `to` after.
+     */
     anchorNow;
     anchorElapsed = 0;
+    ramp = null;
     out = null;
     subjects = new Store();
     /** Kit slot of each channel the patch writes, in `writes` order. */
     slots;
     /** The stops built ahead of time, for a `keys` patch. */
     built;
+    /** The kit's `lerp` for each channel the patch writes, which keyed stops interpolate through. */
+    lerps;
     ease;
     /** Reused for every call this voice makes, so it is valid only during the call. */
     setting;
@@ -45,7 +52,7 @@ class Voice {
     restedCount = 0;
     resolve;
     done;
-    constructor(id, spec, patch, fade, now, start, slotOf, host, send) {
+    constructor(id, spec, patch, fade, now, start, slotOf, channels, host, send) {
         this.id = id;
         this.spec = spec;
         this.patch = patch;
@@ -53,6 +60,7 @@ class Voice {
         this.start = start;
         this.slots = patch.writes.map((k) => slotOf.get(k));
         this.built = patch.form === 'keys' && patch.keys ? builtOf(patch) : null;
+        this.lerps = this.slots.map((slot) => channels[slot].lerp);
         this.ease = fade.ease === undefined ? undefined : curve(fade.ease);
         this.setting = {
             timestamp: 0,
@@ -75,10 +83,33 @@ class Voice {
             this.state = 'live';
     }
     elapsedAt(now) {
-        return this.anchorElapsed + (now - this.anchorNow) * this.rate;
-    }
+        const dt = now - this.anchorNow;
+        const r = this.ramp;
+        if (r === null)
+            return this.anchorElapsed + dt * this.rate;
+        if (dt <= 0)
+            return this.anchorElapsed + dt * r.from;
+        const d = r.to - r.from;
+        if (dt <= r.over)
+            return this.anchorElapsed + r.from * dt + (d * dt * dt) / (2 * r.over);
+        return this.anchorElapsed + r.from * r.over + (d * r.over) / 2 + r.to * (dt - r.over);
+    }
+    rateAt(now) {
+        const r = this.ramp;
+        if (r === null)
+            return this.rate;
+        const u = (now - this.anchorNow) / r.over;
+        return u >= 1 ? r.to : u <= 0 ? r.from : r.from + (r.to - r.from) * u;
+    }
+    /** Moves the anchor to `now`, carrying what is left of a ramp. */
     rebase(now) {
+        const rate = this.rateAt(now);
         this.anchorElapsed = this.elapsedAt(now);
+        const r = this.ramp;
+        if (r !== null) {
+            const left = this.anchorNow + r.over - now;
+            this.ramp = left > 0 ? { from: rate, to: r.to, over: left } : null;
+        }
         this.anchorNow = now;
     }
 }
@@ -86,6 +117,7 @@ class Mixer {
     kit;
     opts;
     voices = [];
+    /** Each subject's last two poses and when they were probed, for `from: 'current'`. */
     pose = new Store();
     nextId = 1;
     /** The mix clock: the host's timestamp less every gap `rebase` has taken out. */
@@ -169,7 +201,7 @@ class Mixer {
         if (spec.from === 'current' && patch.form !== 'keys')
             throw new Error("blits: from: 'current' needs a keys patch");
         const start = spec.start !== undefined ? spec.start - this.offset : Number.isNaN(this.now) ? 0 : this.now;
-        const voice = new Voice(this.nextId++, spec, patch, spec.fade ?? {}, this.now, start, this.slotOf, this.opts.host, this.send);
+        const voice = new Voice(this.nextId++, spec, patch, spec.fade ?? {}, this.now, start, this.slotOf, this.channels, this.opts.host, this.send);
         this.voices.push(voice);
         this.version++;
         if (spec.target !== undefined)
@@ -246,16 +278,29 @@ class Mixer {
         const pose = this.fold(subject, out);
         // Keeping last frame's pose is free when the mix allocated it; a host sampling into its own
         // object only pays for the copy once something in the mix has asked to retarget from it.
+        let kept;
         if (out === undefined)
-            this.pose.set(subject, pose);
+            kept = pose;
         else if (this.wantsPose) {
-            const kept = {};
+            kept = {};
             for (const key of this.names) {
                 const v = pose[key];
                 if (v !== undefined)
                     kept[key] = copy(v);
             }
-            this.pose.set(subject, kept);
+        }
+        if (kept !== undefined) {
+            const rec = this.pose.get(subject);
+            if (rec === undefined)
+                this.pose.set(subject, { pose: kept, at: this.now, prev: undefined, prevAt: Number.NaN });
+            else if (rec.at === this.now)
+                rec.pose = kept;
+            else {
+                rec.prev = rec.pose;
+                rec.prevAt = rec.at;
+                rec.pose = kept;
+                rec.at = this.now;
+            }
         }
         return pose;
     }
@@ -320,14 +365,22 @@ class Mixer {
                 voice.weight = w;
             },
             get rate() {
-                return voice.rate;
+                return voice.rateAt(Number.isNaN(mix.now) ? voice.start : mix.now);
             },
             set rate(r) {
                 voice.rebase(Number.isNaN(mix.now) ? voice.start : mix.now);
+                voice.ramp = null;
+                voice.rate = r;
+            },
+            ramp(r, over) {
+                const now = Number.isNaN(mix.now) ? voice.start : mix.now;
+                voice.rebase(now);
+                const from = voice.rateAt(now);
+                voice.ramp = over > 0 && r !== from ? { from, to: r, over } : null;
                 voice.rate = r;
             },
             seek(elapsed) {
-                voice.anchorNow = Number.isNaN(mix.now) ? voice.start : mix.now;
+                voice.rebase(Number.isNaN(mix.now) ? voice.start : mix.now);
                 voice.anchorElapsed = elapsed;
             },
             fade(opts) {
@@ -388,7 +441,8 @@ class Mixer {
             return held;
         const reaches = voice.spec.target ? voice.spec.target(subject) : true;
         const delay = reaches && voice.spec.stagger ? voice.spec.stagger(subject) : 0;
-        // When the voice clock reads `delay`, from where it is anchored now.
+        // When the voice clock reads `delay`, from where it is anchored now; during a ramp this assumes
+        // the rate it is ramping to.
         const since = voice.rate > 0
             ? voice.anchorNow + (delay - voice.anchorElapsed) / voice.rate
             : voice.start + delay;
@@ -487,11 +541,13 @@ class Mixer {
         if (voice.built) {
             let base;
             if (voice.spec.from === 'current') {
-                if (held.base === undefined)
+                if (held.base === undefined) {
                     held.base = this.baseFor(voice, subject);
+                    held.slope = this.slopeFor(voice, subject);
+                }
                 base = held.base;
             }
-            delta = readKeys(voice.built, phase, held.delta ?? {}, base);
+            delta = readKeys(voice.built, phase, held.delta ?? {}, base, voice.lerps, held.slope);
         }
         else {
             delta = voice.patch.at(phase, subject, setting);
@@ -543,7 +599,7 @@ class Mixer {
      * samples into its own object — it is this frame's pose with every other voice folded in.
      */
     baseFor(voice, subject) {
-        let prior = this.pose.get(subject);
+        let prior = this.pose.get(subject)?.pose;
         if (prior === undefined && !this.folding.has(voice.id)) {
             this.folding.add(voice.id);
             try {
@@ -565,6 +621,28 @@ class Mixer {
         }
         return base;
     }
+    /**
+     * How fast each numeric channel this voice writes was moving, from the subject's last two probed
+     * poses, in units per ms. Undefined with fewer than two on record, which starts the voice at rest.
+     */
+    slopeFor(voice, subject) {
+        const rec = this.pose.get(subject);
+        if (rec?.prev === undefined || !(rec.at > rec.prevAt))
+            return undefined;
+        const dt = rec.at - rec.prevAt;
+        const now = rec.pose;
+        const before = rec.prev;
+        const slope = {};
+        for (const key of voice.patch.writes) {
+            const a = before[key];
+            const b = now[key];
+            if (typeof a === 'number' && typeof b === 'number')
+                slope[key] = (b - a) / dt;
+            else if (Array.isArray(a) && Array.isArray(b) && a.length === b.length)
+                slope[key] = b.map((v, i) => (v - a[i]) / dt);
+        }
+        return slope;
+    }
     isRest(delta) {
         for (const key of Object.keys(delta)) {
             if (delta[key] === undefined)

package/dist/motion.d.ts

@@ -0,0 +1,72 @@
+import type { Patch } from './types.js';
+/** A number, or one number per axis. */
+export type Value = number | readonly number[];
+/** One value for every subject, or one per subject. */
+export type PerSubject<I, V> = V | ((subject: I) => V);
+/**
+ * Where a subject is and how fast it is moving, at one moment of voice time.
+ *
+ * @category patch
+ */
+export interface Motion<V extends Value = number> {
+    value: V;
+    /** Units per second. */
+    velocity: V;
+}
+/**
+ * A patch whose motion is a closed form per subject, so it lands in the same place at any frame
+ * rate, and whose changes mid-flight start from where the subject is and how fast it moves.
+ *
+ * @category patch
+ */
+export type Moving<I, O, V extends Value> = Patch<I, O, void> & {
+    /** Where `subject` is and how fast it moves at voice time `at`, default its last read. */
+    read(subject: I, at?: number): Motion<V> | undefined;
+    /** Sets `subject` moving at `velocity`, units per second, from voice time `at`, default its next read. */
+    push(subject: I, velocity: V, at?: number): void;
+};
+interface Common<I, V extends Value> {
+    /** Units per second each subject starts moving at. Default 0. */
+    velocity?: PerSubject<I, V>;
+    /**
+     * Within this distance of where it heads, and this slow, a subject lands there exactly, so a mix
+     * can see it at rest. Default 1e-4; 0 keeps the curve exact.
+     */
+    settle?: number;
+}
+/**
+ * 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.
+ *
+ * @category patch
+ */
+export declare function spring<I, O, V extends Value = number>(writes: keyof O, opts: Common<I, V> & {
+    to: PerSubject<I, V>;
+    /** Where each subject starts. Default: `to`, at rest. */
+    from?: PerSubject<I, V>;
+    /** Per second squared. Default 170. */
+    stiffness?: number;
+    /** Per second. Default 26, just short of critical at the default stiffness. */
+    damping?: number;
+    mass?: number;
+}): Moving<I, O, V> & {
+    /** Heads `subject` for `target` from voice time `at`, default its next read, keeping its velocity. */
+    to(subject: I, target: V, at?: number): void;
+};
+/**
+ * Coasting under friction, a fling: a subject keeps its velocity, which falls by a factor of e every
+ * `ms`, and comes to rest `velocity · ms / 1000` past where it was released. `push` sets it moving
+ * again from wherever it is. Closed form, so frame rate does not change where it stops.
+ *
+ * @category patch
+ */
+export declare function glide<I, O, V extends Value = number>(writes: keyof O, opts: Common<I, V> & {
+    /** Where each subject starts. */
+    from: PerSubject<I, V>;
+    /** The friction's time constant, ms. Default 325, a touch scroll's. */
+    ms?: number;
+}): Moving<I, O, V>;
+export {};

package/dist/motion.js

@@ -0,0 +1,167 @@
+import { Store } from './store.js';
+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)
+                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);
+        }
+        return h.segment;
+    };
+    const out = (subject, xs) => {
+        const t = shape.template(subject);
+        return (typeof t === 'number' ? xs[0] : xs);
+    };
+    const patch = {
+        form: 'fn',
+        period: 0,
+        writes: [writes],
+        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) };
+        },
+        read(subject, at) {
+            const h = held.get(subject);
+            if (h === undefined || h.segment === null)
+                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) });
+        },
+    };
+    const change = (subject, c) => entry(subject).pending.push(c);
+    return { patch, change };
+}
+/**
+ * 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.
+ *
+ * @category patch
+ */
+export function spring(writes, opts) {
+    const k = opts.stiffness ?? 170;
+    const c = opts.damping ?? 26;
+    const m = opts.mass ?? 1;
+    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];
+        };
+    }
+    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];
+        };
+    }
+    const target = (subject) => axes(per(opts.to, subject));
+    const { patch, change } = moving(writes, {
+        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),
+    });
+    return Object.assign(patch, {
+        to: (subject, goal, at) => change(subject, { at, to: axes(goal) }),
+    });
+}
+/**
+ * Coasting under friction, a fling: a subject keeps its velocity, which falls by a factor of e every
+ * `ms`, and comes to rest `velocity · ms / 1000` past where it was released. `push` sets it moving
+ * again from wherever it is. Closed form, so frame rate does not change where it stops.
+ *
+ * @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, {
+        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),
+    });
+    return patch;
+}

package/dist/patch.d.ts

@@ -33,7 +33,10 @@ export interface KeysOptions<O> {
     easeBy?: (channel: keyof O) => Easing | undefined;
     /** Milliseconds one channel waits before it starts moving, within the period. */
     delayBy?: (channel: keyof O) => number;
-    /** How one channel interpolates, where its values are not numbers or number arrays. */
+    /**
+     * How one channel interpolates, where it should differ from the channel's own `lerp`. A mix hands
+     * every keyed channel its kit's `lerp` unless this names one.
+     */
     lerpBy?: (channel: keyof O) => ((a: never, b: never, u: number) => unknown) | undefined;
     /** The channels these stops were written against, which `cue` checks a mix's kit against. */
     kit?: Partial<Kit<O>>;
@@ -46,6 +49,7 @@ interface Point {
     /** The curve into this point from the one before: the stop's own, else the channel's. */
     ease: Curve | undefined;
 }
+type Lerp = (a: never, b: never, u: number) => unknown;
 /** One channel of a stop list, sorted and resolved once, so a read is a binary search. */
 interface Track {
     channel: string;
@@ -60,8 +64,14 @@ export interface Built {
     tracks: Track[];
     period: number;
 }
-/** Evaluates built stops into `out`; a channel with nothing to read at this phase is left undefined. */
-export declare function readKeys(built: Built, phase: number, out: Record<string, unknown>, base?: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Evaluates built stops into `out`; a channel with nothing to read at this phase is left undefined.
+ * `lerps` holds the mix's channel `lerp` per track, in `writes` order, for a track the patch did not
+ * give one.
+ */
+export declare function readKeys(built: Built, phase: number, out: Record<string, unknown>, base?: Record<string, unknown>, lerps?: readonly (Lerp | undefined)[], 
+/** Per channel, how fast a retargeted subject was moving, units per ms. */
+slopes?: Record<string, unknown>): Record<string, unknown>;
 /** The built form of a patch's stops, made on first ask for a patch `keys()` did not build. */
 export declare function builtOf<I, O, S>(p: Patch<I, O, S>): Built;
 /** Evaluates a stop list into a fresh delta. */

package/dist/patch.js

@@ -59,7 +59,7 @@ function build(stops, writes, period, opts) {
             all,
             tail: all.filter((pt) => pt.at !== 0),
             delay: opts.delayBy?.(channel) ?? 0,
-            lerp: opts.lerpBy?.(channel),
+            lerp: opts.lerpBy?.(channel) ?? opts.kit?.[channel]?.lerp,
         });
     }
     return { tracks, period };
@@ -68,7 +68,7 @@ function build(stops, writes, period, opts) {
  * Reads one track at a phase. `base` stands in for the value at phase 0, which is how
  * `from: 'current'` starts a voice wherever the subject already is.
  */
-function read(track, phase, base) {
+function read(track, phase, base, lerp, slope) {
     const pts = base === undefined ? track.all : track.tail;
     const o = base === undefined ? 0 : 1;
     const n = pts.length + o;
@@ -95,17 +95,46 @@ function read(track, phase, base) {
     const aValue = lo - 1 < o ? base : pts[lo - 1 - o].value;
     const u = (phase - aAt) / (b.at - aAt);
     const eased = b.ease ? b.ease(u) : u;
-    return track.lerp
-        ? track.lerp(aValue, b.value, eased)
+    const by = track.lerp ?? lerp;
+    const value = by
+        ? by(aValue, b.value, eased)
         : interpolate(aValue, b.value, eased);
+    // Leaving a retarget's base, bend the first segment so it starts at the slope the subject had:
+    // add c·u(1−u)², which is 0 at both ends, flat at the end, and fixes the slope at the start.
+    if (slope === undefined || lo - 1 >= o)
+        return value;
+    const len = b.at - aAt;
+    const e0 = b.ease ? b.ease(1e-6) / 1e-6 : 1;
+    const bend = (s, a, z) => (s * len - (z - a) * e0) * u * (1 - u) * (1 - u);
+    if (typeof value === 'number' && typeof slope === 'number')
+        return value + bend(slope, aValue, b.value);
+    if (Array.isArray(value) && Array.isArray(slope))
+        return value.map((v, i) => typeof v === 'number' && typeof slope[i] === 'number'
+            ? v +
+                bend(slope[i], aValue[i], b.value[i])
+            : v);
+    return value;
 }
-/** Evaluates built stops into `out`; a channel with nothing to read at this phase is left undefined. */
-export function readKeys(built, phase, out, base) {
+/**
+ * Evaluates built stops into `out`; a channel with nothing to read at this phase is left undefined.
+ * `lerps` holds the mix's channel `lerp` per track, in `writes` order, for a track the patch did not
+ * give one.
+ */
+export function readKeys(built, phase, out, base, lerps, 
+/** Per channel, how fast a retargeted subject was moving, units per ms. */
+slopes) {
     const period = built.period;
-    for (const track of built.tracks) {
+    for (let i = 0; i < built.tracks.length; i++) {
+        const track = built.tracks[i];
         const delay = track.delay;
         const shifted = delay === 0 || period === 0 ? phase : Math.max(0, (phase * period - delay) / period);
-        const value = read(track, shifted, base?.[track.channel]);
+        const perMs = slopes?.[track.channel];
+        const slope = perMs === undefined || period === 0
+            ? undefined
+            : typeof perMs === 'number'
+                ? perMs * period
+                : perMs.map((s) => s * period);
+        const value = read(track, shifted, base?.[track.channel], lerps?.[i], slope);
         if (value !== undefined)
             out[track.channel] = value;
         else if (out[track.channel] !== undefined)

package/dist/types.d.ts

@@ -227,7 +227,14 @@ export interface Handle<I = unknown> {
     readonly state: 'pending' | 'live' | 'fading' | 'done';
     /** Live. Writes land on the next sync. */
     weight: number;
+    /** Playback rate now. Setting it changes speed at once; `ramp` eases into a new one. */
     rate: number;
+    /**
+     * Moves the rate to `rate` linearly over `over` mix ms, so a pause or a slow-motion eases in
+     * rather than snapping. The voice clock integrates the ramp, so its position stays continuous and
+     * its speed does too. A later `rate` write or `ramp` replaces it; `seek` keeps it.
+     */
+    ramp(rate: number, over: number): void;
     /**
      * Moves this voice's clock, forward or back. Phase is computed from the reading rather than
      * accumulated into, so state is left where it is and never run forward to meet the new position.

package/docs/schema.html

@@ -398,6 +398,8 @@ interface Handle<I> {
      into, so nothing has to unwind: state is left where it is and is never run forward to meet the new
      position. Mix time is not addressable this way, and nothing outside this voice moves. */</span>
   seek(elapsed: number): void;
+  <span class="cm">/** Moves the rate to `rate` linearly over `over` mix ms. The voice clock integrates it, so speed eases too. */</span>
+  ramp(rate: number, over: number): void;
   <span class="cm">/** Ramps out over `fade.out` unless given a fade here; `at: 'rest'` waits per subject for a resting pose first. */</span>
   fade(opts?: { over?: number; at?: 'rest'; deadline?: number }): void;
   <span class="cm">/** The weight this voice gave `subject` the last frame it was probed: after fades and its signal, before a
@@ -499,7 +501,7 @@ function gate&lt;I&gt;(of: Signal&lt;I&gt;, at: number): Signal&lt;I&gt;;
   <tr><td>Crossfade at a phase seam</td><td>Two voices in one <code>locus</code>, one fading out as the other fades in. The locus folds them by the channel's <code>lerp</code> at their weight ratio, which on <code>sum</code> is the lurch guard klieg's timeline applies when a hold is shorter than the blend, and on every other channel is the crossfade that guard was standing in for.</td><td>enter → active → exit as three voices.</td></tr>
   <tr><td>Handover at rest</td><td><code>fade({ at: 'rest', deadline })</code> removes the voice per subject at the first frame its pose equals rest, or at the deadline. The next voice was cued already and simply becomes the only contributor.</td><td><code>turns</code>' handover rule, made available to any pair.</td></tr>
   <tr><td>Blend between alternatives</td><td><code>mix.blend([a, b, c], by: k)</code> cues three voices whose weights are the hat functions of k at 0, ½, 1. Continuous, no rebuild, and hinge's quantization goes away for patches whose channels have rest.</td><td><code>hinge</code>'s stops mode. Its blend mode is just <code>weight: signal</code>.</td></tr>
-  <tr><td>Retarget on interruption</td><td><code>from: 'current'</code> on a <code>keys</code> voice takes stop 0 from the subject's pose in the frame before it first contributes &mdash; every other voice folded in, itself excluded &mdash; and lerps from there through the channel's <code>lerp</code>.</td><td>wod's base-sampling. New to klieg: a regroup could tween from mid-float instead of carrying it away.</td></tr>
+  <tr><td>Retarget on interruption</td><td><code>from: 'current'</code> on a <code>keys</code> voice takes stop 0 from the subject's pose in the frame before it first contributes &mdash; every other voice folded in, itself excluded &mdash; and lerps from there through the channel's <code>lerp</code>. It also leaves at the velocity the subject had, taken from its last two probed poses: the first segment gains <code>c·u(1−u)²</code>, which is zero at both ends and flat at the end, so the segment's own curve still lands on its stop while the start matches the subject's speed. A subject that was still leaves at rest. With fewer than two poses on record, as on a mix whose host probes into its own object before any retarget is cued, it starts on the segment's own curve.</td><td>wod's base-sampling. New to klieg: a regroup could tween from mid-float instead of carrying it away.</td></tr>
 </table></div>
 
 <p><b>A locus is folded by <code>lerp</code>, not by scaling and merging.</b> Voices sharing a <code>locus</code> are alternatives in time, so the mix combines them into one influence first: each member weighted by its share of the locus's summed weight, through the channel's own <code>lerp</code>, in cue order. That one influence then contributes at weight <code>min(1, &Sigma;w)</code> and is scaled toward rest like any other. On a <code>sum</code> channel this is exactly <code>w&#8321;a + w&#8322;b</code>, the arithmetic klieg's timeline already runs, so the cap it was written as is a special case of the fold rather than a rule of its own. On <code>mul</code>, <code>max</code> and <code>last</code> it is the difference between an alternative and a pile-up: two voices halfway through a handover, both holding a gain of 0.06, fold to 0.06 &mdash; which is what one alternative means &mdash; where scaling and merging reads 0.28, the product of two half-scaled copies. A grouped voice may write only channels that have a <code>lerp</code>, which every stock channel does. Cue order is visible only to a <code>lerp</code> that is not linear, such as a hue taking the short way round.</p>
@@ -509,6 +511,23 @@ function gate&lt;I&gt;(of: Signal&lt;I&gt;, at: number): Signal&lt;I&gt;;
   <p>A weight scales an influence toward its channel's rest. A lerp moves between two values. Every blend is one or the other, chosen by the channel. A consumer that needs a third arithmetic adds a channel, not a mix option.</p>
 </div>
 
+<h2 id="motion">Springs and glides</h2>
+<p>Motion that has momentum is not a curve over a known duration, so it is neither <code>keys</code> nor <code>Easing</code>. Two patches carry it, each solved in closed form per subject, so where a subject is at a given moment does not depend on how the frames that sample it were spaced. Each keeps one stretch per subject: released at a voice time from a position and a velocity, heading somewhere. A change mid-flight ends the stretch and starts the next from where the subject is <em>and how fast it is moving</em>, which is what keeps a retarget from kinking.</p>
+<pre><code>const s = spring&lt;Node, Pose&gt;('x', { from: 0, to: 100, stiffness: 170, damping: 26 });
+mix.cue({ patch: s });
+s.to(node, 40);              <span class="cm">// heads elsewhere from wherever it is, keeping its velocity</span>
+s.push(node, 600);           <span class="cm">// a kick: same target, new velocity</span>
+s.read(node);                <span class="cm">// { value, velocity }, for handing the motion to another patch</span>
+
+const g = glide&lt;Node, Pose&gt;('x', { from: 0, velocity: 1200, ms: 325 });  <span class="cm">// a fling: rests 390 past the start</span></code></pre>
+<ul>
+  <li><b>Time is the voice's</b>, so <code>rate</code> and <code>seek</code> apply. A change takes effect at the voice time it names, or at the subject's next read; naming one is what makes a retarget land the same at any frame rate.</li>
+  <li><b>History is one stretch.</b> A read earlier than the latest change evaluates the latest stretch backward, not what happened. Keeping more waits on the history horizon in <code>NOTES-ON-SCRUBBING.md</code>.</li>
+  <li><b>A value settles.</b> Within <code>settle</code> (1e-4) of where it heads, and that slow, it lands there exactly, so <code>atRest</code> sees it. <code>settle: 0</code> keeps the curve exact.</li>
+  <li><b>The state is the patch's own</b>, per subject, rather than the mix's, because the host retargets through the patch. Cue each one on one voice.</li>
+  <li><b>Handing motion between patches</b> is <code>read</code> on the old one and <code>from</code> plus <code>velocity</code> on the new: a fling that ends in a spring starts the spring at the glide's velocity.</li>
+</ul>
+
 <h2 id="state">Patch state</h2>
 <p>klieg built three stateful patches in one week, <code>power</code>, <code>kicks</code> and <code>dwell</code>, and each rediscovered the same three rules: key state by the subject object, step once per frame by the gap in the timestamp, snap under infinite <code>dt</code>. Those rules are the package's, applied by the mix, and a patch declares only what its state is and how it advances.</p>
 
@@ -609,7 +628,7 @@ export const mixer: Engine;   <span class="cm">// the one that ships</span></cod
 
 <h2 id="open">Open</h2>
 <ul>
-  <li><b>The shared channel list.</b> Channels a second package might write onto another's subject, fixed with a kind, a unit and a rest so that hosts and packages agree past what <code>kind</code> checks. Candidates, names unpicked: <code>opacity</code> mul 0..1; <code>scale</code> mul factor; <code>position</code> vec(3, sum) world units; <code>rotation</code> vec(3, sum) radians; <code>bump</code> vec(2, sum) CSS px, picked on 2026-09-30 over <code>offset</code>, which blits already split into delta and pose; <code>turn</code> sum radians, the flat rotation; <code>color</code> hex sRGB. Undecided too: whether wod's radial push takes a shared name, and whether sherpa's <code>clip</code> and wod's <code>aperture</code> are one shared <code>reveal</code>.</li>
+  <li><b>The shared channel list.</b> Channels a second package might write onto another's subject, fixed with a kind, a unit and a rest so that hosts and packages agree past what <code>kind</code> checks. Candidates, names unpicked: <code>opacity</code> mul 0..1; <code>scale</code> mul factor; <code>position</code> vec(3, sum) world units; <code>rotation</code> vec(3, sum) radians; <code>bump</code> vec(2, sum) CSS px, picked on 2026-09-30 over <code>offset</code>, which blits already split into delta and pose; <code>turn</code> sum radians, the flat rotation, counting past 2π so a wheel can spin many times, which is why it blends in a straight line &mdash; an orientation that wraps, where 350° and 10° must meet at 0°, needs its own channel with a <code>lerp</code> the short way round, and weasel's rig plans one; <code>color</code> hex sRGB. Undecided too: whether wod's radial push takes a shared name, and whether sherpa's <code>clip</code> and wod's <code>aperture</code> are one shared <code>reveal</code>.</li>
   <li><b>How the score comes inside.</b> Decided 2026-09-29: it comes inside, provided it depends on no implementation. It places voices from any number of unrelated sources and knows when each plays, for how long, at what weight and relative to which other voice &mdash; never what a voice contributes. Meaning stays in the patches and the kit&rsquo;s channels, which is the line the fold already draws. Scores compose dynamically, favored where it holds up: each source keeps its own, the mix reads every score it holds the way a DAW plays every track, and a source joins or leaves without touching anyone else&rsquo;s plan. One shared score is the case with one source. Until now a score was a word for a seam blits does not own: blits takes timing as given and reads only what has been cued, so it sees no further ahead than its pending voices, and a host that knows what is coming does the arithmetic itself &mdash; to be faded in by <code>T</code>, it cues with <code>start: T − fade.in</code>. A score inside blits would be data: voices placed on the mix clock, at a time or relative to one another (after, with, before, fully in by), which the mix plays by reading it at the current timestamp, the way a DAW plays its arrangement at the playhead. The fold does not change, since the mix already folds any number of voices at a time. What changes is that the whole plan can be read at any time: <code>mix.project(at)</code> for what is coming, and, because the plan is kept rather than used up, a way back that the mix&rsquo;s lack of history rules out today. A series, voices that hand over in order, is one arrangement a score can hold rather than an object of its own. Reading at another time is where state gets in the way, and the approach is for the mix to own all of it. Signals keep their state in the mix through <code>setting.keep</code> rather than in a closure (built 2026-09-29), so a read at another time copies it instead of moving the live signal. A read ahead copies the state (<code>structuredClone</code> by default, a <code>clone</code> on the patch or signal where the state is not plain data), steps it to <code>at</code>, probes, and throws the copy away. It takes one <code>step</code> per interval between the events the score already knows &mdash; a voice starting, a fade ending, a loop running out &mdash; since any of them can change what a stateful signal follows, and each step covers its whole interval, however long. That leans on a contract the whole-gap rule already assumes and nothing states: one step across an interval is as good as any number of steps across it. Steps need not be uniform or frame by frame. An answer is exact across known events. An input the clock drives continuously, such as a slew following a sine, is exact only to the length of the step, which is an error of stepping rather than of knowledge: a finer split, or a patch or signal that gives its own closed form for a long gap, removes it. An input from outside the clock &mdash; a <code>level</code> the host sets, a pointer &mdash; has no known future, so it is held where it is and the answer says <code>held</code>. Reading back is the same read from an earlier start: the nearest state known before <code>t</code>, stepped forward to it. Voices without state need none, since the score keeps the plan. Stateful ones start from a checkpoint where history holds one, and otherwise from the voice&rsquo;s own start, where its state was made fresh, exact where only the clock drove it. An outside input&rsquo;s past is known where history recorded it and <code>held</code> where it did not, the same label as the future. So how much history the mix keeps, checkpoints and recorded inputs and the voices that have left, is a cost to tune and not a design question: it moves where answers turn <code>held</code>, never whether a read works. The proposed shape of a placement, unbuilt: a voice has four marks on the mix clock &mdash; <code>start</code> (fade-in begins), <code>in</code> (full weight), <code>out</code> (fade-out begins) and <code>end</code> (gone) &mdash; and a cue anchors at most one mark on each side, <code>start</code> or <code>in</code> and <code>out</code> or <code>end</code>, to a time or to another voice&rsquo;s mark with an offset: <code>anchor: { in: 12_400 }</code> is fully in by 12.4&nbsp;s, <code>anchor: { start: { after: 'intro' } }</code> starts once <code>intro</code> is gone. A voice is named by a <code>name</code> its source gives it, a label blits never reads. Names are namespaced by score: a bare name names a voice in the same score, and <code>{ score, name }</code> one in another, so a score carries a name of its own. A mix-wide namespace can come later for convenience, if placing across scores feels awkward without it. What an anchor takes is a query over the merged score that answers with a time, rerun while it is bound: a selector (name, score, the channels a voice <code>writes</code>, and tags a source attaches), a mark, and, where more than one voice matches, a resolver (<code>next</code>, <code>first</code>, <code>last</code>, <code>earliest</code>, <code>latest</code>). A name is the simplest selector; <code>anchor: { in: { before: { writes: 'gain', next: true }, by: 200 } }</code> is fully in 200&nbsp;ms before the next voice that writes <code>gain</code>. A selector reads only what the score knows &mdash; never a channel&rsquo;s value, so &ldquo;when gain crosses 0.5&rdquo; is refused rather than searched for. The same queries answer what is playing at a time and where the next event is, which is where a read ahead splits its steps. A read ahead is a projection: <code>m.project(t)</code> returns one with <code>probe(subject, out?)</code> and <code>assess(subject)</code>, which says per channel whether the answer is <code>exact</code>, <code>stepped</code> or <code>held</code>, the least sure voice that fed the channel deciding. A projection at an earlier timestamp throws until reading back exists. A patch or signal that says nothing is taken as driven by the clock; one that reads outside input declares it, as <code>level</code> and anything built on host input do. Decided 2026-09-29: the other default would read every existing <code>fn</code> patch as <code>held</code>, and an assessment is only as honest as the declarations either way. A locus and a tag are the same thing twice over &mdash; a string several voices share to make a set &mdash; and differ only in what the mix does with the set, so they become one: a voice carries tags, and a tag can be declared to fold its voices as alternatives, through each channel&rsquo;s <code>lerp</code> by share, which is what <code>locus</code> does today. A voice blends in at most one such tag; <code>blend</code> declares one for its voices, so a crossfade stays one call. Proposed 2026-09-29, unbuilt: <code>VoiceSpec.locus</code> is still what runs. An anchor can also target an <b>event</b>: a named instant a source raises, which blits never interprets, only times. One scheduled in a score is known ahead, so a read ahead sees it and a voice can arrive by it; one the host fires when something happens, such as a click or a reply, is unknown until it fires, so a voice anchored to it waits pending and a read ahead answers <code>held</code> for whatever depends on it. Marks and events are one concept (decided 2026-09-29): a voice is a source that raises four events about itself, its <code>start</code>, <code>in</code>, <code>out</code> and <code>end</code>, so an anchor has one kind of target and one query selects events whoever raised them. A mark placed on a voice, such as the hit 340&nbsp;ms in, is one more event that voice raises. The <code>out</code> of a voice that loops for good is unknown until something fades it, and waits exactly as an event the host has not fired yet does. What fires an event on a condition is a <b>trigger</b>, and a trigger on a channel&rsquo;s value belongs to the host: blits does not read values, so the host watches the condition and fires the event. Proposed 2026-09-29, unbuilt. An anchor whose query has no answer yet &mdash; a name not cued, no voice matching, the <code>out</code> of a voice that loops for good &mdash; leaves the voice <code>pending</code> until it resolves; a cycle is refused at <code>cue</code>; and an anchored mark already past starts the voice partway through, the way playback starts in the middle of a region. A voice placed relative to another resolves against the mix&rsquo;s merged view of every score it holds: it follows its target while that voice is there, however it is sought, faded or retimed, and keeps the time it last resolved to once the target leaves, whichever score the target belonged to.</li>
   <li><b>The package name.</b> Published as <code>@msb235/blits</code> for now, decided 2026-09-30, while npm answers a request for the bare <code>blits</code>, which the registry 404s. Moving to <code>blits</code> later changes every import. <code>@lightningjs/blits</code> is a live TV app framework with its own animation plugin, so searches for the name land there first.</li>
   <li><b>Color's lerp.</b> The stock <code>hex</code> channel ships sRGB, which is what klieg's light channel assumes and what keeps the port's arithmetic identical. OKLCH reads better for a crossfade between hues and would replace it rather than join it; the choice waits on seeing a hue crossfade in the port.</li>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@msb235/blits",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Concurrent effects: each on its own clock with its own state and weight, folded into one value per subject per frame",
   "keywords": [
     "animation",