@msb235/blits 0.4.0 → 0.5.0

package/dist/store.js

@@ -1,22 +1,47 @@
+/** What every store reads before its first write: never written, so always empty. */
+const noWeak = new WeakMap();
+const noStrong = new Map();
 /**
  * Per-subject storage keyed by identity. Objects go in a WeakMap and are forgotten when the host
  * drops them; anything else — a string id, the unit subject of a mix with no subject dimension —
  * goes in a Map that only `drop` and `clear` empty, which is why a host keying by value should
- * call `drop`.
+ * call `drop`. Each map is made when first written, since a mix holds a store per voice and patch;
+ * until then it is a shared empty one, so the field always holds a map.
  */
 export class Store {
-    weak = new WeakMap();
-    strong = new Map();
+    weak = noWeak;
+    strong = noStrong;
+    /**
+     * The first key that is not an object, and its value, held here until a second comes: a voice of
+     * one subject keyed by id would otherwise spend a Map's smallest table on it.
+     */
+    oneKey = none;
+    oneValue = undefined;
     get(key) {
-        return typeof key === 'object' && key !== null
-            ? this.weak.get(key)
-            : this.strong.get(key);
+        if (typeof key === 'object' && key !== null)
+            return this.weak.get(key);
+        return same(this.oneKey, key) ? this.oneValue : this.strong.get(key);
     }
     set(key, value) {
-        if (typeof key === 'object' && key !== null)
+        if (typeof key === 'object' && key !== null) {
+            if (this.weak === noWeak)
+                this.weak = new WeakMap();
             this.weak.set(key, value);
-        else
-            this.strong.set(key, value);
+            return;
+        }
+        if (this.strong === noStrong && (this.oneKey === none || same(this.oneKey, key))) {
+            this.oneKey = key;
+            this.oneValue = value;
+            return;
+        }
+        if (this.strong === noStrong)
+            this.strong = new Map();
+        if (this.oneKey !== none) {
+            this.strong.set(this.oneKey, this.oneValue);
+            this.oneKey = none;
+            this.oneValue = undefined;
+        }
+        this.strong.set(key, value);
     }
     has(key) {
         return this.get(key) !== undefined;
@@ -24,10 +49,20 @@ export class Store {
     delete(key) {
         if (typeof key === 'object' && key !== null)
             this.weak.delete(key);
+        else if (same(this.oneKey, key)) {
+            this.oneKey = none;
+            this.oneValue = undefined;
+        }
         else
             this.strong.delete(key);
     }
     clear() {
+        this.oneKey = none;
+        this.oneValue = undefined;
         this.strong.clear();
     }
 }
+/** No key held inline. */
+const none = Symbol('none');
+/** A Map's key equality, SameValueZero: NaN finds NaN. */
+const same = (a, b) => a === b || Object.is(a, b);

package/dist/strays.d.ts

@@ -0,0 +1,21 @@
+import type { Mixer } from './mixer.js';
+import type { MotionOwner, Motions } from './motion.js';
+import type { Voice } from './voice.js';
+/** Notes a motion patch that may hold state for a subject no voice playing it reaches. */
+export declare function stray<I, O>(mix: Mixer<I, O>, motion: Motions<I>, subject: I): void;
+/** A motion voice left the list: if its patch plays on, its subjects' state there may stray. */
+export declare function unplay<I, O>(mix: Mixer<I, O>, voice: Voice<I, O>): void;
+/**
+ * What a motion patch asks of the mix playing it, by its voice's id. It holds the mix weakly, so a
+ * patch the host keeps does not keep a mix it has let go of alive; a retired voice's patch no
+ * longer asks.
+ */
+export declare function motionOwner<I, O>(mix: WeakRef<Mixer<I, O>>): MotionOwner;
+/** The voice in the list with this id, which is in id order. */
+export declare function cuedById<I, O>(mix: Mixer<I, O>, id: number): Voice<I, O> | undefined;
+/**
+ * A subject's voice time at the latest frame, where a motion patch places an untimed change and a
+ * `read` with no time; NaN until the voice has started and met the subject, and while the
+ * subject's own time is still short of its stagger. A retired voice's patch no longer asks.
+ */
+export declare function frameOf<I, O>(mix: Mixer<I, O>, voice: Voice<I, O>, subject: I): number;

package/dist/strays.js

@@ -0,0 +1,84 @@
+import { unpart } from './fade.js';
+/** Notes a motion patch that may hold state for a subject no voice playing it reaches. */
+export function stray(mix, motion, subject) {
+    const list = mix.strays.get(subject);
+    if (list === undefined)
+        mix.strays.set(subject, [motion]);
+    else if (!list.includes(motion))
+        list.push(motion);
+}
+/** A motion voice left the list: if its patch plays on, its subjects' state there may stray. */
+export function unplay(mix, voice) {
+    const motion = voice.motion;
+    if (motion === undefined)
+        return;
+    const left = (mix.playing.get(motion) ?? 1) - 1;
+    if (left <= 0) {
+        mix.playing.delete(motion);
+        mix.strayAll.delete(motion);
+        return;
+    }
+    mix.playing.set(motion, left);
+    if (voice.named === null)
+        mix.strayAll.add(motion);
+    else
+        for (const subject of voice.named)
+            stray(mix, motion, subject);
+}
+/**
+ * What a motion patch asks of the mix playing it, by its voice's id. It holds the mix weakly, so a
+ * patch the host keeps does not keep a mix it has let go of alive; a retired voice's patch no
+ * longer asks.
+ */
+export function motionOwner(mix) {
+    return {
+        frame(id, subject) {
+            const m = mix.deref();
+            const v = m === undefined ? undefined : cuedById(m, id);
+            return m === undefined || v === undefined ? Number.NaN : frameOf(m, v, subject);
+        },
+        revive(id, subject) {
+            const m = mix.deref();
+            if (m === undefined)
+                return;
+            m.stir();
+            const v = cuedById(m, id);
+            if (v === undefined)
+                return;
+            if (v.motion !== undefined && v.named !== null && !v.named.has(subject))
+                stray(m, v.motion, subject);
+            unpart(m, v, subject);
+        },
+    };
+}
+/** The voice in the list with this id, which is in id order. */
+export function cuedById(mix, id) {
+    const cued = mix.cued;
+    let lo = 0;
+    let hi = cued.length - 1;
+    while (lo <= hi) {
+        const mid = (lo + hi) >> 1;
+        const v = cued[mid];
+        if (v.id === id)
+            return v;
+        if (v.id < id)
+            lo = mid + 1;
+        else
+            hi = mid - 1;
+    }
+    return undefined;
+}
+/**
+ * A subject's voice time at the latest frame, where a motion patch places an untimed change and a
+ * `read` with no time; NaN until the voice has started and met the subject, and while the
+ * subject's own time is still short of its stagger. A retired voice's patch no longer asks.
+ */
+export function frameOf(mix, voice, subject) {
+    if (Number.isNaN(mix.now) || voice.state === 'pending')
+        return Number.NaN;
+    const held = voice.subjects.get(subject);
+    if (held === undefined || !held.reaches)
+        return Number.NaN;
+    const t = voice.elapsedAt(mix.now) - held.delay;
+    return t < 0 ? Number.NaN : t;
+}

package/dist/tweened.d.ts

@@ -0,0 +1,11 @@
+import type { Curve } from './easing.js';
+/** Turns the velocity `eased` works out on or off. */
+export declare function sloped(on: boolean): void;
+/** How far through a stretch released at `at` and lasting `ms` voice time `t` is, from 0. */
+export declare function progress(t: number, at: number, ms: number): number;
+/** The share of a tween's way left to go at `u`, 0 once it has arrived. */
+export declare function left(ease: Curve, u: number): number;
+/** An axis of a tween from `x0` to `goal` with `share` of the way left. */
+export declare function between(x0: number, goal: number, share: number): number;
+/** A tween's stretch at `u` into `xo` and `vo`: true once it has arrived. */
+export declare function eased(ease: Curve, n: number, u: number, ms: number, x0: ArrayLike<number>, x: number, to: ArrayLike<number>, g: number, xo: Float64Array, vo: Float64Array): boolean;

package/dist/tweened.js

@@ -0,0 +1,48 @@
+/** 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` asks for 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 = { u: Number.NaN, ease: undefined, left: 0 };
+/** Turns the velocity `eased` works out on or off. */
+export function sloped(on) {
+    slope = on;
+}
+/** How far through a stretch released at `at` and lasting `ms` voice time `t` is, from 0. */
+export function progress(t, at, ms) {
+    return Math.max(0, t - at) / ms;
+}
+/** The share of a tween's way left to go at `u`, 0 once it has arrived. */
+export function left(ease, u) {
+    // 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);
+    }
+    return memo.left;
+}
+/** An axis of a tween from `x0` to `goal` with `share` of the way left. */
+export function between(x0, goal, share) {
+    return share === 0 ? goal : goal + (x0 - goal) * share;
+}
+/** A tween's stretch at `u` into `xo` and `vo`: true once it has arrived. */
+export function eased(ease, n, u, ms, x0, x, to, g, xo, vo) {
+    const share = left(ease, u);
+    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 a = x0[x + i];
+        const goal = to[g + i];
+        xo[i] = between(a, goal, share);
+        vo[i] = -(a - goal) * rate;
+    }
+    return share === 0;
+}

package/dist/types.d.ts

@@ -67,10 +67,10 @@ export interface Keyframe<O> {
  *
  * @category state
  */
-export interface Setting<S = void> {
+export interface Setting<S = void, H = unknown> {
     /**
-     * The mix clock at this frame: the host's timestamp less any time `rebase` took out. Identical
-     * for every probe in the frame.
+     * The mix clock at this frame: the host's timestamp less any time `rebase` took out, run at the
+     * mix's `rate`. Identical for every probe in the frame.
      */
     timestamp: number;
     /**
@@ -88,14 +88,15 @@ export interface Setting<S = void> {
     weight: number;
     /** This subject's state, when the patch declares one. */
     state: S;
-    /** Anything the host adds for its own patches. */
-    host: unknown;
+    /** Anything the host adds for its own patches: the mix's `host`, typed as its `H`. */
+    host: H;
     /**
      * The state `owner` keeps for this voice and this subject, made by `init` on first ask. The mix
      * holds it, so a read at another time can copy it instead of moving it. A stateful signal keeps
-     * its state here and nowhere else. With lanes on, a patch that first calls it partway through
-     * playing can have that state advanced once for one subject not probed on the frame it starts; a
-     * patch that keeps state from its first call, or declares `state`, never does.
+     * its state here and nowhere else. With lanes on, a patch or weight signal that first calls it
+     * partway through playing can have that state advanced once for one subject not probed on the
+     * frame it starts; one that keeps state from its first call, or a patch that declares `state`,
+     * never does.
      */
     keep<K>(owner: object, init: () => K): K;
     /**
@@ -103,7 +104,7 @@ export interface Setting<S = void> {
      * host drains it, and never calls back. Meant for `step`, where under `stepMs` the timestamp is
      * the interval the event happened in rather than the frame that sampled it. Sent from a stateless
      * patch's `at` while it runs on a lane, it goes out for every subject the mix has met, probed that
-     * frame or not.
+     * frame or not; `at` is not asked for a subject at weight 0, so nothing is sent from it there.
      */
     send(event: unknown): void;
 }
@@ -153,14 +154,16 @@ export type MotionSpec = {
  *
  * @category patch
  */
-export interface Patch<I, O, S = void> {
+export interface Patch<I, O, S = void, H = unknown> {
     /**
      * Which authoring form built it: `'fn'` from `patch`, `'keys'` from `keys`, `'motion'` from
      * `spring`, `glide` or `tween`. An engine declares which forms it runs.
      */
     readonly form: 'fn' | 'keys' | 'motion';
-    /** Milliseconds one pass lasts. 0 is aperiodic: phase and pass stay 0. */
-    readonly period: number;
+    /** Milliseconds one pass lasts, whether or not the voice loops. 0 has no passes: phase and pass stay 0. */
+    readonly duration: number;
+    /** @deprecated Use `duration`. A patch that sets only `period` still plays. */
+    readonly period?: number;
     /** The channels this patch contributes to. Every key `at` sets, and no others. */
     readonly writes: readonly (keyof O)[];
     /**
@@ -170,15 +173,18 @@ export interface Patch<I, O, S = void> {
     readonly kit?: Partial<Kit<O>>;
     /** The fields of `setting.host` this patch reads. `cue` refuses a mix whose host lacks one. */
     readonly reads?: readonly string[];
-    /** `phase` is 0..1 across one period, wrapping. */
-    at(phase: number, subject: I, setting: Setting<S>): Partial<O>;
+    /**
+     * `phase` is 0..1 across one pass, wrapping. Not asked for a subject its voice gives no weight, unless the voice is fading to rest;
+     * `step` still runs.
+     */
+    at(phase: number, subject: I, setting: Setting<S, H>): Partial<O>;
     /** Per-subject state, created on the first frame this patch sees a subject. */
     state?(subject: I): S;
     /**
      * Advances state once per subject per sampled frame, by the whole gap since it last advanced; or,
      * where the mix sets `stepMs`, once per whole interval of that length.
      */
-    step?(state: S, dt: number, subject: I, setting: Setting<S>): void;
+    step?(state: S, dt: number, subject: I, setting: Setting<S, H>): void;
     /** Present when the patch was authored as keyframes, so an engine that reads data can. */
     readonly keys?: readonly Keyframe<O>[];
     /** Present on a `'motion'` patch: its kind and constants, for an engine that reads data. */
@@ -197,7 +203,7 @@ export interface Patch<I, O, S = void> {
  *
  * @category signal
  */
-export type Signal<I> = ((subject: I, setting: Setting) => number) & {
+export type Signal<I, H = unknown> = ((subject: I, setting: Setting<void, H>) => number) & {
     readonly input?: boolean;
 };
 /**
@@ -286,19 +292,91 @@ export interface Marked {
     name: string | undefined;
     tags: readonly string[];
 }
+/**
+ * An event at a time on a voice's own clock, which `book` hands a host ahead of time. It plays once
+ * per pass, for the voice and not per subject, so `stagger` does not spread it.
+ *
+ * @category score
+ */
+export interface Hit<E = unknown> {
+    /** Voice ms into each pass: 0 up to the patch's `duration`, or any time at all for a patch with none. */
+    at: number;
+    event: E;
+}
+/**
+ * One pass of one hit, as `book` takes it.
+ *
+ * @category score
+ */
+export interface BookedHit<E = unknown> {
+    /** On the host's clock. */
+    timestamp: number;
+    voice: number;
+    /** Which of the voice's `hits`, by index. */
+    hit: number;
+    /** Which pass, 0 first. */
+    pass: number;
+    event: E;
+    score: string | undefined;
+    name: string | undefined;
+    tags: readonly string[];
+}
+/**
+ * What `book` takes: an outside clock, how far ahead to book on it, and what to do with each item.
+ *
+ * @category score
+ */
+export interface BookOptions<E = unknown> {
+    /**
+     * The outside clock, in ms: `audio.currentTime * 1000`, `performance.now()`, or whatever the host
+     * schedules against. Read once a sync. The mix maps its host time onto it by an offset that folds
+     * in 5% of each frame's difference, and starts over from the clock's own reading on a jump past
+     * 50 ms, such as a suspended context or a hidden tab.
+     */
+    clock: () => number;
+    /** How far ahead to book, host ms. It has to cover the longest gap between two syncs. */
+    ahead: number;
+    /** How far past an item first seen late may be and still be taken, host ms. */
+    late: number;
+    /**
+     * Called once per item: a mark as `marks` lists it, or a hit. `when` is on the outside clock;
+     * `lateBy` is how many host ms past the item was when first seen, 0 for one booked ahead, which
+     * is then taken at the clock's now. Return a `stop` to hear about a booking whose time moved by
+     * more than 1 ms or that went away (a seek, a rate or ramp on the voice or the mix, a fade, a
+     * `rebase`, an anchor's target moving, the voice leaving); the item is then booked again, at its
+     * new time, at the same sync.
+     */
+    take(item: Marked | BookedHit<E>, when: number, lateBy: number): {
+        stop(): void;
+    } | undefined;
+    /** Book only the voices, and announced marks, carrying this tag. */
+    tag?: string;
+    /** Book only this score's voices and marks. */
+    score?: string;
+}
+/**
+ * A running booker, returned by `book`.
+ *
+ * @category score
+ */
+export interface Booker {
+    /** Stops every booking still ahead, and books nothing more. */
+    stop(): void;
+}
 /**
  * What `cue` takes: a patch, and the clock, weight and reach it plays with.
  *
  * @category voice
  */
-export interface VoiceSpec<I, O> {
-    patch: Patch<I, O, unknown>;
+export interface VoiceSpec<I, O, H = unknown> {
+    patch: Patch<I, O, unknown, H>;
     /**
      * Which subjects this voice reaches. Default: all of them. The predicate is fixed at `cue`; it
      * runs per subject the first time the mix sees that subject, and the answer is kept. Every
      * voice's predicate meets every subject, so voices that each reach a known few cost the square
-     * of their number, in time and in memory (a record per voice per subject asked: about 800 MB for
-     * 1,000 such voices); name those with `subjects` instead.
+     * of their number in time; name those with `subjects` instead. A no is kept as a bit by the
+     * number lanes give the subject, but with `lanes: false` as a map entry per voice per subject
+     * asked (about 37 MB for 1,000 such voices over 1,000 subjects).
      */
     target?: (subject: I) => boolean;
     /**
@@ -336,14 +414,14 @@ export interface VoiceSpec<I, O> {
      */
     hold?: 'before' | 'after' | 'both';
     /** Steady weight, or a signal read per subject per frame. Default 1. */
-    weight?: number | Signal<I>;
+    weight?: number | Signal<I, H>;
     /** Ramp in and out, ms. Out applies on `fade()` and when a finite loop ends. */
     fade?: FadeSpec;
     /** Voices sharing a locus are alternatives: the mix folds them through each channel's `lerp`. */
     locus?: string;
     /** A `keys` voice whose first stop reads wherever this subject is now. */
     from?: 'current';
-    /** Words a source attaches to this voice, so its events can be drained as a set. */
+    /** Words a source attaches to this voice, so its events and its handle can be taken as a set. */
     tags?: readonly string[];
     /** What other voices call this one by. A label blits never reads. */
     name?: string;
@@ -355,6 +433,52 @@ export interface VoiceSpec<I, O> {
     score?: string;
     /** Where it sits relative to the clock or to other voices, in place of `start`. */
     anchor?: Placement;
+    /**
+     * Events at times on this voice's clock, which `book` hands a host ahead of time. Patch-sent
+     * events are not known ahead, so they stay drain-only; these are the plan.
+     */
+    hits?: readonly Hit[];
+    /**
+     * The owner this voice plays under, a handle `owns` returned. Its `start` and `anchor` are then on
+     * the owner's clock, in ms from when the owner starts, and default to where that clock is now; a
+     * bare name in an anchor means a sibling, another voice the owner holds. Its clock runs on the
+     * owner's, so the owner's rate, ramp and seeks move it, and its weight is multiplied by the
+     * owner's weight and fade. Without a `hold` of its own it takes the owner's.
+     */
+    owner?: Handle<I>;
+}
+/**
+ * What `owns` takes: an owner has no patch, and plays only through the voices it holds.
+ *
+ * @category voice
+ */
+export interface OwnerSpec<I, H = unknown> {
+    /**
+     * When the owner starts, on its own owner's clock: the host's for an owner on the mix, as a
+     * voice's `start` is. Default: now.
+     */
+    start?: number;
+    /** Its clock's rate, multiplied into every child's own. Default 1. */
+    rate?: number;
+    /**
+     * Multiplied into every child's weight per subject, as the child's own fade is, before the child's
+     * locus folds it: a number, or a signal read per subject per frame. Default 1.
+     */
+    weight?: number | Signal<I, H>;
+    /** One ramp in and out over every child, multiplied into their weights as `weight` is. */
+    fade?: FadeSpec;
+    /** The hold every child without one of its own takes. */
+    hold?: 'before' | 'after' | 'both';
+    /** Words a source attaches to it, as a voice's. */
+    tags?: readonly string[];
+    /** What other voices call it by, among its siblings. */
+    name?: string;
+    /** The plan it belongs to, as a voice's. */
+    score?: string;
+    /** Where it sits relative to its own owner's clock or to other voices, in place of `start`. */
+    anchor?: Placement;
+    /** The owner it plays under, so owners nest. */
+    owner?: Handle<I>;
 }
 /**
  * How a voice leaves when it is faded: the whole voice, or one subject.
@@ -388,6 +512,8 @@ export interface Handle<I = unknown> {
     readonly id: number;
     /** `held`: a voice holding after has played every pass and shows its last frame until faded. */
     readonly state: 'pending' | 'live' | 'held' | 'fading' | 'done';
+    /** The handle of the owner this voice plays under; undefined for one on the mix clock. */
+    readonly owner: Handle<I> | undefined;
     /** Live. Writes land on the next sync. */
     weight: number;
     /** Playback rate now. Setting it changes speed at once; `ramp` eases into a new one. */
@@ -425,12 +551,12 @@ export interface Handle<I = unknown> {
  *
  * @category mix
  */
-export interface MixOptions {
+export interface MixOptions<H = unknown> {
     engine?: Engine;
     /** Reduced motion: fades and warm-ups snap, `dt` reads Infinity. */
     reduce?: boolean | (() => boolean);
-    /** Merged into every `setting.host`. */
-    host?: unknown;
+    /** Merged into every `setting.host`. Its type is the mix's `H`, which every patch and signal it cues reads. */
+    host?: H;
     /**
      * The band a rest-less channel's influence switches on and off across. It has to clear the frame
      * noise in a real signal; these are placeholders until the klieg port measures one.
@@ -514,11 +640,26 @@ export type Columns<O> = {
  *
  * @category mix
  */
-export interface Mix<I, O> {
+export interface Mix<I, O, H = unknown> {
     /** Cues a voice. Throws when the engine cannot run the patch's form, or the kit lacks a channel. */
-    cue(spec: VoiceSpec<I, O>): Handle<I>;
-    /** N voices whose weights split one signal, cued into one locus so they fold as alternatives. */
-    blend(patches: readonly Patch<I, O, unknown>[], by: Signal<I>, spec?: Omit<VoiceSpec<I, O>, 'patch' | 'weight' | 'locus'>): Handle<I>[];
+    cue(spec: VoiceSpec<I, O, H>): Handle<I>;
+    /**
+     * N voices whose weights split one signal, cued into one locus so they fold as alternatives. The
+     * signal is read once per subject per frame, with the first member's setting, and every member
+     * takes its share of that one reading; a signal keeping state keeps it once, not per member.
+     */
+    blend(patches: readonly Patch<I, O, unknown, H>[], by: Signal<I, H>, spec?: Omit<VoiceSpec<I, O, H>, 'patch' | 'weight' | 'locus'>): Handle<I>[];
+    /**
+     * Cues an owner: a voice with no patch that holds the voices cued with `owner` set to its handle,
+     * and plays them on its own clock, so they can be placed, timed and faded as one. Its handle acts
+     * on all of them: `rate` and `ramp` multiply into theirs, `seek` moves their clocks with its own
+     * and leaves their state where it is, and `weight` and `fade()` multiply into their weights, by
+     * what its `weightOf` reports; it fades as a whole, not by subject or at rest. It is
+     * `played` once every voice it held has finished its passes, and leaves, `done`, with its last; a
+     * fade that ends takes the rest with it. One that never holds a voice stays until faded. Owners
+     * nest. Throws for a `loop`: a pass would have to restart its children.
+     */
+    owns(spec: OwnerSpec<I, H>): Handle<I>;
     /** The host reports the clock, once a frame. Nothing advances at the call. */
     sync(timestamp: number): void;
     /**
@@ -526,7 +667,30 @@ export interface Mix<I, O> {
      * hidden tab comes back. Every voice, fade and subject resumes where it was left.
      */
     rebase(): void;
-    /** The merged pose for one subject at the synced frame. */
+    /**
+     * The mix's own playback rate, multiplied into every voice's: 1 is real time and 0 pauses the
+     * whole mix. A negative rate throws, since the mix only goes forward. Setting it changes speed at
+     * once; `ramp` eases into a new one. It scales mix time, which everything a voice owns runs on:
+     * its clock, its fades and a handle's ramp, `stagger`, an anchor's `by`, `stepMs`, `maxDt`,
+     * `history.ms`, every `dt`, and `setting.timestamp`. Timestamps on the host's clock name the same
+     * moment whatever the rate does: a `start`, an anchor given as a number, an announced mark, what
+     * `marks` reports and the time `project` reads, so a start ahead of a paused mix waits for the
+     * host's clock to reach it. A weight signal is still asked at every probe, so one reading host
+     * input follows it while the mix is paused.
+     */
+    rate: number;
+    /**
+     * Moves the mix's rate to `rate` linearly over `over` ms of the host's clock, as `Handle.ramp`
+     * moves a voice's. Mix time integrates the ramp and a voice's clock integrates mix time, so a ramp
+     * on both multiplies and every position stays continuous. A later `rate` write or `ramp` replaces
+     * it.
+     */
+    ramp(rate: number, over: number): void;
+    /**
+     * The merged pose for one subject at the synced frame, written into `out` when given. Without
+     * it, each call makes a new object, so a host reading every subject every frame passes `out` or
+     * reads by `pull`.
+     */
     probe(subject: I, out?: O): O;
     /**
      * Writes each subject's pose into arrays, one per channel, subject by subject in the order given:
@@ -544,14 +708,24 @@ export interface Mix<I, O> {
      * older than the history reaches.
      */
     project(timestamp: number): Projection<I, O>;
-    /** Every channel at rest for this subject this frame, so a host can skip the write. */
+    /**
+     * Every channel at rest for this subject this frame, so a host can skip the write. After a probe
+     * of the subject this frame, it answers for the pose that probe gave, without folding again.
+     */
     atRest(subject: I): boolean;
+    /**
+     * A handle on every voice still in the mix, pending, live, held or fading, in the order they were
+     * cued; given a tag, only the voices whose `tags` carry it. Each is the handle `cue` returned for
+     * that voice, so a listed handle is `===` the cued one.
+     */
+    voices(tag?: string): Handle<I>[];
     /** 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.
+     * at a plain weight, or a motion whose every subject has landed on its target. At rate 0 it is
+     * enough that every voice not done has started, at a plain weight, with no anchor. A change made
+     * since the last sync, a retarget or a rate 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. */
@@ -588,6 +762,15 @@ export interface Mix<I, O> {
      * whoever drains them.
      */
     drain<E = unknown>(tag?: string): Sent<I, E>[];
+    /**
+     * Hands the host each mark and hit before it comes, against a clock of its own, so it can schedule
+     * the thing itself: a sound on an `AudioContext`, a MIDI message with a timestamp, a video loaded
+     * before the voice that shows it starts. Booking runs at each `sync`, `ahead` ms out, and a
+     * booking whose time moves is stopped and taken again. Nothing is booked twice: a mark is known by
+     * its voice and which mark, a hit by its voice, index and pass. `project` books nothing, and
+     * nothing about booking is replayed under `history`. A mix with no booker pays nothing for it.
+     */
+    book<E = unknown>(opts: BookOptions<E>): Booker;
 }
 /**
  * The implementation behind a mix: which patch forms it runs, and how it makes one.
@@ -598,5 +781,5 @@ export interface Engine {
     readonly name: string;
     /** Which patch forms this engine can run. A voice it cannot run is refused at `cue`, by name. */
     readonly runs: ReadonlySet<'fn' | 'keys' | 'motion'>;
-    create<I, O>(kit: Kit<O>, opts: MixOptions): Mix<I, O>;
+    create<I, O, H = unknown>(kit: Kit<O>, opts: MixOptions<H>): Mix<I, O, H>;
 }

package/dist/unreached.d.ts

@@ -0,0 +1,5 @@
+import type { Voice } from './voice.js';
+/** Whether the voice's shared unreached record stands for the subject numbered `slot`. */
+export declare function unreached<I, O>(voice: Voice<I, O>, slot: number): boolean;
+/** Marks or clears the subject numbered `slot` as one the voice does not reach. */
+export declare function unreach<I, O>(voice: Voice<I, O>, slot: number, on: boolean): void;