@msb235/blits 0.3.0 → 0.4.0

package/dist/motion.d.ts

@@ -33,6 +33,8 @@ interface Change {
 }
 /** A motion patch's `frame` while no mix plays it: no subject has a latest frame. */
 export declare const noFrame: () => number;
+export declare const noRevive: () => void;
+export declare const noTouch: () => void;
 /**
  * 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.
@@ -64,14 +66,16 @@ interface Shape<I> {
     scalar: (subject: I) => boolean;
     /** A tween's easing, which its law cannot hold; undefined, but present, on every other shape. */
     ease: Curve | undefined;
+    /** A tween's seconds for a stretch the subject starts now; undefined, but present, on the rest. */
+    ms: ((subject: I) => number) | undefined;
 }
 /**
  * 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
+ * After the law, each subject's run of `stride` numbers is its release time, its flags, a tween's
+ * seconds for the stretch, 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.
  */
@@ -98,11 +102,31 @@ export declare class Motions<I> {
      * cues the patch, and put back when its voice retires.
      */
     frame: (subject: I) => number;
+    /**
+     * Brings a subject its voice faded out back to it, so a change is not made for nothing. Set by
+     * the mix that cues the patch, and put back when its voice retires.
+     */
+    revive: (subject: I) => void;
     constructor(shape: Shape<I>);
     /** The patch's number for `subject`, made with its first stretch on first ask. */
     slot(subject: I): number;
     /** Forgets a subject, so a later ask starts it afresh from `from`. */
     release(subject: I): void;
+    /**
+     * Called with a subject's number whenever its stretch or what is pending for it changes, so a
+     * mix keeping a copy of it knows to read it again. Set by the mix, put back when its voice retires.
+     */
+    touched: (s: number) => void;
+    /** The easing a tween's stretches follow; undefined for every other shape. */
+    get ease(): Curve | undefined;
+    /** A copy of the patch's law, `[form, settle, k1, k2, k3]`. */
+    law(): Float64Array;
+    /**
+     * Copies subject `s`'s current stretch into `out` from `o` as its release time, its seconds, then
+     * `x0`, `v0` and `to` per axis; false, copying nothing, while it has a change pending or an
+     * earlier stretch kept, which only `sample` handles.
+     */
+    stretchInto(s: number, out: Float64Array, o: number): boolean;
     /** Whether subject `s`'s value is a number rather than an array. */
     scalar(s: number): boolean;
     /** The value `at` hands the mix: the first axis for a number, a fresh array otherwise. */
@@ -113,6 +137,16 @@ export declare class Motions<I> {
      * a projection's read applies the timed ones to a copy and commits nothing.
      */
     sample(s: number, t: number, xo: Float64Array, vo: Float64Array): void;
+    /**
+     * A live `sample` at `t` for a subject with nothing pending and no earlier stretch kept, true
+     * then; false, writing nothing, for any other, which `quiet` and `sample` take instead.
+     */
+    sampleBare(s: number, t: number, xo: Float64Array, vo: Float64Array): boolean;
+    /**
+     * Whether every subject has landed on its target at its voice time at the latest frame, as a
+     * sample there would find; one with a change waiting has not. Commits nothing.
+     */
+    landed(): boolean;
     /**
      * 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.
@@ -151,9 +185,15 @@ export declare class Motions<I> {
     private prune;
     private evaluateSegment;
     private evaluate;
-    /** A tween's stretch, `dt` seconds after release, kept out of `evaluate` so a spring's stays small. */
-    private eased;
 }
+/**
+ * A stretch `t` voice ms into it, released at `at` from `x0` moving at `v0` toward `to` (each read
+ * from its offset), into `xo` and `vo`: the one copy of the closed forms, which `law` (a patch's
+ * `[form, settle, k1, k2, k3]`, the head of a patch's buffer or a copy of it) picks between. A tween reads `ease` and
+ * `ms`, the stretch's length, dividing in milliseconds so a boundary lands exactly; every other
+ * form ignores them.
+ */
+export declare function closed(law: Float64Array, ease: Curve | undefined, n: number, at: number, ms: number, x0: ArrayLike<number>, x: number, v0: ArrayLike<number>, v: number, to: ArrayLike<number>, g: number, t: number, xo: Float64Array, vo: Float64Array): boolean;
 /** The state behind a `'motion'` patch, for an engine that reads it directly. */
 export declare function motionOf<I>(p: object): Motions<I> | undefined;
 interface Common<I, V extends Value> {
@@ -217,8 +257,8 @@ export declare function tween<I, O, V extends Value = number>(writes: keyof O, o
     from: PerSubject<I, V>;
     /** Where each subject ends. */
     to: PerSubject<I, V>;
-    /** How long a stretch takes, ms. */
-    ms: number;
+    /** How long a stretch takes, ms: asked per subject each time one of its stretches starts. */
+    ms: PerSubject<I, number>;
     /** The curve from `from` to `to`. Default `'ease'`, as CSS's. */
     ease?: Easing;
 }): Omit<Moving<I, O, V>, 'push'> & {

package/dist/motion.js

@@ -15,13 +15,19 @@ const EASED = 4;
 const HEAD = 5;
 /** A motion patch's `frame` while no mix plays it: no subject has a latest frame. */
 export const noFrame = () => Number.NaN;
+export const noRevive = () => { };
+export const noTouch = () => { };
 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. */
+/**
+ * A subject's flags: its value is a number; it has changes pending; it has older stretches; the
+ * stretch it is playing was found landed, which holds until another replaces it.
+ */
 const SCALAR = 1;
 const PENDING = 2;
 const OLDER = 4;
+const LANDED = 8;
 /**
  * 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.
@@ -35,7 +41,7 @@ const SPAN = 1e-4;
  */
 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 };
+const memo = { u: Number.NaN, ease: undefined, left: 0 };
 /** `t` seconds after release, the terms every axis shares, into `timed`. */
 function prepare(law, t) {
     switch (law[0]) {
@@ -118,8 +124,8 @@ const per = (p, subject) => typeof p === 'function' ? p(subject) : p;
  * 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
+ * After the law, each subject's run of `stride` numbers is its release time, its flags, a tween's
+ * seconds for the stretch, 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.
  */
@@ -146,6 +152,11 @@ export class Motions {
      * cues the patch, and put back when its voice retires.
      */
     frame = noFrame;
+    /**
+     * Brings a subject its voice faded out back to it, so a change is not made for nothing. Set by
+     * the mix that cues the patch, and put back when its voice retires.
+     */
+    revive = noRevive;
     constructor(shape) {
         this.shape = shape;
         this.runs = Float64Array.from(shape.law);
@@ -163,7 +174,7 @@ export class Motions {
             this.check(a, n);
         if (this.n < 0) {
             this.n = n;
-            this.stride = 2 + 3 * n;
+            this.stride = 3 + 3 * n;
             if (shared.xs.length < n)
                 shared = { xs: new Float64Array(n), vs: new Float64Array(n) };
             this.xs = shared.xs;
@@ -173,7 +184,7 @@ export class Motions {
         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 });
+        this.write(s, { at: 0, ms: this.shape.ms?.(subject) ?? 0, x0: x, v0: v, to });
         return s;
     }
     /** Forgets a subject, so a later ask starts it afresh from `from`. */
@@ -184,6 +195,36 @@ export class Motions {
         this.slots.delete(subject);
         this.numbers.release(s);
     }
+    /**
+     * Called with a subject's number whenever its stretch or what is pending for it changes, so a
+     * mix keeping a copy of it knows to read it again. Set by the mix, put back when its voice retires.
+     */
+    touched = noTouch;
+    /** The easing a tween's stretches follow; undefined for every other shape. */
+    get ease() {
+        return this.shape.ease;
+    }
+    /** A copy of the patch's law, `[form, settle, k1, k2, k3]`. */
+    law() {
+        return this.runs.slice(0, HEAD);
+    }
+    /**
+     * Copies subject `s`'s current stretch into `out` from `o` as its release time, its seconds, then
+     * `x0`, `v0` and `to` per axis; false, copying nothing, while it has a change pending or an
+     * earlier stretch kept, which only `sample` handles.
+     */
+    stretchInto(s, out, o) {
+        const runs = this.runs;
+        const b = this.base(s);
+        if ((runs[b + 1] & (PENDING | OLDER)) !== 0)
+            return false;
+        out[o] = runs[b];
+        out[o + 1] = runs[b + 2];
+        const n3 = 3 * this.n;
+        for (let i = 0; i < n3; i++)
+            out[o + 2 + i] = runs[b + 3 + i];
+        return true;
+    }
     /** Whether subject `s`'s value is a number rather than an array. */
     scalar(s) {
         return (this.runs[this.base(s) + 1] & SCALAR) !== 0;
@@ -215,13 +256,57 @@ export class Motions {
             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);
+                const x = b + 3;
+                const ms = runs[b + 2];
+                this.evaluate(at, ms, runs, x, runs, x + this.n, runs, x + 2 * this.n, t, xo, vo);
             }
             return;
         }
         this.peek(s, t, xo, vo);
     }
+    /**
+     * A live `sample` at `t` for a subject with nothing pending and no earlier stretch kept, true
+     * then; false, writing nothing, for any other, which `quiet` and `sample` take instead.
+     */
+    sampleBare(s, t, xo, vo) {
+        const runs = this.runs;
+        const b = this.base(s);
+        if ((runs[b + 1] & (PENDING | OLDER)) !== 0)
+            return false;
+        const x = b + 3;
+        const n = this.n;
+        this.evaluate(runs[b], runs[b + 2], runs, x, runs, x + n, runs, x + 2 * n, t, xo, vo);
+        return true;
+    }
+    /**
+     * Whether every subject has landed on its target at its voice time at the latest frame, as a
+     * sample there would find; one with a change waiting has not. Commits nothing.
+     */
+    landed() {
+        const runs = this.runs;
+        const n = this.n;
+        for (let s = 0; s < this.numbers.size; s++) {
+            const b = this.base(s);
+            const flags = runs[b + 1];
+            if ((flags & (LANDED | PENDING)) === LANDED)
+                continue;
+            const subject = this.numbers.subject(s);
+            if (subject === absent)
+                continue;
+            if (flags & PENDING)
+                return false;
+            const at = runs[b];
+            const t = this.frame(subject);
+            if (!(t >= at))
+                return false;
+            const x = b + 3;
+            const ms = runs[b + 2];
+            if (!this.evaluate(at, ms, runs, x, runs, x + n, runs, x + 2 * n, t, this.xs, this.vs))
+                return false;
+            runs[b + 1] = flags | LANDED;
+        }
+        return true;
+    }
     /**
      * 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.
@@ -268,6 +353,7 @@ export class Motions {
      * The queue keeps the changes with a time in time order, ahead of any still waiting for one.
      */
     change(subject, c) {
+        this.revive(subject);
         const s = this.slot(subject);
         this.check(c.to, this.n);
         this.check(c.v, this.n);
@@ -317,6 +403,7 @@ export class Motions {
             throw new Error('blits: a motion patch moves every subject on the same number of axes');
     }
     flag(s, bit, on) {
+        this.touched(s);
         const i = this.base(s) + 1;
         const flags = this.runs[i];
         this.runs[i] = on ? flags | bit : flags & ~bit;
@@ -341,19 +428,23 @@ export class Motions {
     write(s, seg) {
         const n = this.n;
         const b = this.base(s);
+        this.touched(s);
         this.runs[b] = seg.at;
+        this.runs[b + 1] = this.runs[b + 1] & ~LANDED;
+        this.runs[b + 2] = seg.ms;
         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];
+            this.runs[b + 3 + i] = seg.x0[i];
+            this.runs[b + 3 + n + i] = seg.v0[i];
+            this.runs[b + 3 + 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;
+        const x = this.base(s) + 3;
         return {
             at: this.runs[this.base(s)],
+            ms: this.runs[this.base(s) + 2],
             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)),
@@ -384,8 +475,10 @@ export class Motions {
         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 };
+        const known = subject === absent ? undefined : subject;
+        const to = this.shape.aim(xs, vs, change.to ?? seg.to, known);
+        const ms = subject === absent ? seg.ms : (this.shape.ms?.(known) ?? 0);
+        return { at, ms, x0: xs, v0: vs, to };
     }
     commit(s, t) {
         const list = this.pending.get(s);
@@ -449,58 +542,63 @@ export class Motions {
         }
     }
     evaluateSegment(seg, t, xo, vo) {
-        this.evaluate(seg.at, seg.x0, 0, seg.v0, 0, seg.to, 0, t, xo, vo);
+        this.evaluate(seg.at, seg.ms, 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);
+    evaluate(at, ms, x0, x, v0, v, to, g, t, xo, vo) {
+        return closed(this.runs, this.shape.ease, this.n, at, ms, x0, x, v0, v, to, g, t, xo, vo);
+    }
+}
+/**
+ * A stretch `t` voice ms into it, released at `at` from `x0` moving at `v0` toward `to` (each read
+ * from its offset), into `xo` and `vo`: the one copy of the closed forms, which `law` (a patch's
+ * `[form, settle, k1, k2, k3]`, the head of a patch's buffer or a copy of it) picks between. A tween reads `ease` and
+ * `ms`, the stretch's length, dividing in milliseconds so a boundary lands exactly; every other
+ * form ignores them.
+ */
+export function closed(law, ease, n, at, ms, x0, x, v0, v, to, g, t, xo, vo) {
+    if (law[0] === EASED)
+        return eased(ease, n, Math.max(0, t - at) / ms, ms, x0, x, to, g, xo, vo);
+    const dt = Math.max(0, t - at) / 1000;
+    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)
         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;
+            xo[i] = to[g + i];
+            vo[i] = 0;
         }
-        if (still)
-            for (let i = 0; i < n; i++) {
-                xo[i] = to[g + i];
-                vo[i] = 0;
-            }
+    return still;
+}
+/** A tween's stretch, `dt` seconds after release, kept out of `closed` so a spring's stays small. */
+function eased(ease, n, u, ms, x0, x, to, g, xo, vo) {
+    // Subjects released together share `u`, so a frame reads a bezier once, not once each.
+    if (u !== memo.u || ease !== memo.ease) {
+        memo.u = u;
+        memo.ease = ease;
+        memo.left = u >= 1 ? 0 : 1 - ease(u);
     }
-    /** 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);
-        }
-        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 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)) * (1000 / ms);
+    }
+    for (let i = 0; i < 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;
     }
+    return left === 0;
 }
 const states = new WeakMap();
 /** The state behind a `'motion'` patch, for an engine that reads it directly. */
@@ -562,6 +660,7 @@ export function spring(writes, opts) {
         law,
         scalar: (s) => typeof per(opts.to, s) === 'number',
         ease: undefined,
+        ms: undefined,
     });
     return Object.assign(patch, {
         push,
@@ -588,6 +687,7 @@ export function glide(writes, opts) {
         law: [COAST, settle, tau, 0, 0],
         scalar: (s) => typeof per(opts.from, s) === 'number',
         ease: undefined,
+        ms: undefined,
     });
     return Object.assign(patch, { push });
 }
@@ -601,17 +701,25 @@ export function glide(writes, opts) {
  * @category patch
  */
 export function tween(writes, opts) {
-    if (!(opts.ms > 0))
-        throw new Error('blits: a tween takes a positive ms');
+    const fixed = typeof opts.ms === 'number';
+    const ms = (subject) => {
+        const length = per(opts.ms, subject);
+        if (!(length > 0))
+            throw new Error('blits: a tween takes a positive ms');
+        return length;
+    };
+    if (fixed)
+        ms(undefined);
     const ease = opts.ease ?? 'ease';
     const target = (subject) => axes(per(opts.to, subject));
-    const { patch, state } = moving(writes, { kind: 'tween', ms: opts.ms, ease }, {
+    const { patch, state } = moving(writes, { kind: 'tween', ms: fixed ? opts.ms : undefined, 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],
+        law: [EASED, 0, 0, 0, 0],
         scalar: (s) => typeof per(opts.to, s) === 'number',
         ease: curve(ease),
+        ms,
     });
     return Object.assign(patch, {
         to: (subject, goal, at) => state.change(subject, { at, to: axes(goal) }),

package/dist/types.d.ts

@@ -144,8 +144,8 @@ export type MotionSpec = {
     readonly settle: number;
 } | {
     readonly kind: 'tween';
-    /** How long a stretch takes. */
-    readonly ms: number;
+    /** How long a stretch takes; undefined where it varies by subject, kept on the patch then. */
+    readonly ms: number | undefined;
     readonly ease: Easing;
 };
 /**
@@ -317,7 +317,7 @@ export interface VoiceSpec<I, O> {
     /**
      * true loops for good, false plays one pass, n plays n passes. A finite loop leaves when its
      * passes are done for the latest-staggered subject it has seen — over `fade.out` where one is
-     * set, at once where none is.
+     * set, at once where none is — unless it holds after.
      */
     loop?: boolean | number;
     /**
@@ -325,6 +325,16 @@ export interface VoiceSpec<I, O> {
      * Like `target`, it runs once per subject on first sight, and the answer is kept.
      */
     stagger?: (subject: I) => number;
+    /**
+     * Show a subject the first frame before it starts — while the voice is pending and while the
+     * subject waits out its `stagger` — the last frame of the last pass after a finite loop plays
+     * out, or both. A held subject's clock stands still: `at` is asked for the edge frame and `step`
+     * does not run, past one last step to the end of the last pass. `fade.in` counts from the first
+     * frame the voice shows. A voice holding after stays, `held`, until `fade()` or an anchored `out`
+     * takes it out, so every one cued must be faded or it stays in the mix for good. Does nothing to
+     * a motion patch, which holds its target already. Default: neither.
+     */
+    hold?: 'before' | 'after' | 'both';
     /** Steady weight, or a signal read per subject per frame. Default 1. */
     weight?: number | Signal<I>;
     /** Ramp in and out, ms. Out applies on `fade()` and when a finite loop ends. */
@@ -347,18 +357,28 @@ export interface VoiceSpec<I, O> {
     anchor?: Placement;
 }
 /**
- * How a voice leaves when it is faded.
+ * How a voice leaves when it is faded: the whole voice, or one subject.
  *
  * @category blending
  */
-export interface FadeOptions {
+export type FadeOptions<I = unknown> = {
     /** The ramp, ms. Defaults to the voice's own `fade.out`. */
     over?: number;
     /** Leave per subject at the first frame that subject's contribution is at rest. */
     at?: 'rest';
     /** Ms after which the voice leaves whether or not it rested. */
     deadline?: number;
-}
+    subject?: never;
+} | {
+    /**
+     * The one subject to fade out of this voice, which plays on for the rest. Once the ramp ends
+     * the voice forgets the subject and reaches it no more, until a motion patch's `to` brings it
+     * back, met afresh: `from`, `target` and `stagger` asked again.
+     */
+    subject: I;
+    /** The ramp, ms. Defaults to the voice's own `fade.out`; 0 takes the subject out at once. */
+    over?: number;
+};
 /**
  * The live controls on one voice, returned by `cue`.
  *
@@ -366,7 +386,8 @@ export interface FadeOptions {
  */
 export interface Handle<I = unknown> {
     readonly id: number;
-    readonly state: 'pending' | 'live' | 'fading' | 'done';
+    /** `held`: a voice holding after has played every pass and shows its last frame until faded. */
+    readonly state: 'pending' | 'live' | 'held' | '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. */
@@ -382,16 +403,22 @@ export interface Handle<I = unknown> {
      * accumulated into, so state is left where it is and never run forward to meet the new position.
      */
     seek(elapsed: number): void;
-    fade(opts?: FadeOptions): void;
+    fade(opts?: FadeOptions<I>): void;
     /**
      * The weight this voice gave `subject` the last frame that subject was probed: after its fades
      * and its weight signal, before a locus folds it with its alternatives. 0 for a subject it does
-     * not reach, has not started on, has left at rest, or has never been probed for; 0 once done.
+     * not reach, has not started on and does not hold before, has left at rest, or has never been
+     * probed for; 0 once done.
      * Costs nothing until it is asked.
      */
     weightOf(subject: I): number;
     /** Resolves when the voice has been removed from the mix, however that happened. */
     readonly done: Promise<void>;
+    /**
+     * Resolves true when a finite loop's last pass ends, for the latest-staggered subject it has
+     * seen, and false if the voice leaves before that. Never rejects.
+     */
+    readonly played: Promise<boolean>;
 }
 /**
  * How a mix is built: its engine, reduced motion, the host, and its limits.
@@ -505,7 +532,10 @@ export interface Mix<I, O> {
      * Writes each subject's pose into arrays, one per channel, subject by subject in the order given:
      * what `probe(subject, out)` gives, without a pose object per subject. A channel of `n` numbers
      * takes `n` places per subject, side by side; one with no value for a subject writes NaN there.
-     * Fastest while every voice runs on a lane. Throws when an array is too short for the subjects.
+     * Fastest while every voice runs on a lane, and when `subjects` is an array read again in the
+     * same order: the mix remembers the last array's subjects by position, holding them until the
+     * next `pull`, and skips looking up any still in its place. Throws when an array is too short for
+     * the subjects.
      */
     pull(subjects: Iterable<I>, into: Columns<O>): void;
     /**
@@ -518,6 +548,12 @@ export interface Mix<I, O> {
     atRest(subject: I): boolean;
     /** Anything still contributing, fading, or pending. */
     readonly live: boolean;
+    /**
+     * Another frame would change no pose, so a host's frame loop may sleep: every voice is done, held
+     * at a plain weight, or a motion whose every subject has landed on its target. A change made since
+     * the last sync, a retarget included, makes it false until the next.
+     */
+    readonly inert: boolean;
     /** Fades every voice out: over `over` when given, over each voice's own `fade.out` otherwise. */
     mute(opts?: {
         over?: number;