@msb235/blits 0.5.0 → 0.7.0

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import type { Fit, Order, Strength } from './fit.js';
 /**
  * One field of a delta, with its own arithmetic.
  *
@@ -18,7 +19,7 @@ export interface Channel<V> {
     bounds?: readonly [min: number, max: number];
     /** Identity. Absent means the channel has none: it replaces rather than contributes. */
     rest?: V;
-    /** Fold two influences into one. */
+    /** Fold two contributions into one. */
     merge(a: V, b: V): V;
     /** Fade toward `rest` by weight 0..1. Required when `rest` is set; absent otherwise. */
     scale?(v: V, w: number): V;
@@ -26,7 +27,7 @@ export interface Channel<V> {
     lerp(a: V, b: V, u: number): V;
     /**
      * Optional: `merge(into, scale(v, w))`, written into `into` and returned, so a channel whose
-     * values are objects need not allocate per influence. The mix only hands it a value it made.
+     * values are objects need not allocate per contribution. The mix only hands it a value it made.
      */
     fold?(into: V, v: V, w: number): V;
 }
@@ -94,17 +95,18 @@ export interface Setting<S = void, H = unknown> {
      * 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 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.
+     * partway through playing can have that state advanced once for one subject probed the frame
+     * before it starts and not on that frame; one that keeps state from its first call, or a patch
+     * that declares `state`, never does.
      */
     keep<K>(owner: object, init: () => K): K;
     /**
      * Reports an event at `timestamp`, for this voice and this subject. The mix queues it until the
      * 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; `at` is not asked for a subject at weight 0, so nothing is sent from it there.
+     * patch's `at` while it runs on a lane, it goes out for every subject the lane fills, probed that
+     * frame or not: each probed that frame or the last; `at` is not asked for a subject at weight 0,
+     * so nothing is sent from it there.
      */
     send(event: unknown): void;
 }
@@ -175,7 +177,7 @@ export interface Patch<I, O, S = void, H = unknown> {
     readonly reads?: readonly string[];
     /**
      * `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.
+     * `step` still runs. A `keys` patch's stops are not read there either, unless its voice is in a locus.
      */
     at(phase: number, subject: I, setting: Setting<S, H>): Partial<O>;
     /** Per-subject state, created on the first frame this patch sees a subject. */
@@ -195,6 +197,13 @@ export interface Patch<I, O, S = void, H = unknown> {
      * function needs its own.
      */
     clone?(state: S): S;
+    /**
+     * `state` as data that survives `structuredClone`, for a history `store` to keep; `unpack` makes
+     * a state from it again. With a store, a patch with `state` or `step` needs both, or `cue`
+     * refuses it.
+     */
+    pack?(state: S): unknown;
+    unpack?(data: unknown): S;
 }
 /**
  * A 0..1 scalar resolved per subject per frame from something outside the clock. `input` is set
@@ -217,12 +226,15 @@ export interface FadeSpec {
     ease?: Easing;
 }
 /**
- * The four times a voice is known by on the mix clock: when its fade in begins (`start`), when it is
- * fully in (`in`), when its fade out begins (`out`), and when it is gone (`end`).
+ * The times a voice is known by on the mix clock: when its fade in begins (`start`), when it is
+ * fully in (`in`), when its last pass ends (`coast`), when its fade out begins (`out`), and when it
+ * is gone (`end`). A voice coasts when `played` resolves true, for its latest-staggered subject: at
+ * its `out` where it does not freeze, and where it starts showing its last frame where it does. A
+ * voice that loops for good, or fades before its last pass ends, never coasts.
  *
  * @category score
  */
-export type Mark = 'start' | 'in' | 'out' | 'end';
+export type Mark = 'start' | 'in' | 'coast' | 'out' | 'end';
 /**
  * Selects voices by what the plan knows of them, never by a channel's value, within the asking
  * voice's own score unless it names another. Where several match,
@@ -243,7 +255,8 @@ export interface Query {
 /**
  * A time given by another voice: `mark` of the voice `of` selects, moved by `by` ms. `after` is
  * sugar for that voice's `end`, `with` for its `start`, and `before` for its start less `by`. A
- * string selects by name.
+ * string selects by name. `all` is the latest of its anchors, known once every one is; `any` the
+ * earliest, known once one has passed or every one is known.
  *
  * @category score
  */
@@ -260,6 +273,10 @@ export type Anchor = {
 } | {
     before: string | Query;
     by?: number;
+} | {
+    all: readonly Anchor[];
+} | {
+    any: readonly Anchor[];
 };
 /**
  * Where a voice sits on the mix clock: at most one of `start` and `in`, and at most one of `out`
@@ -276,21 +293,23 @@ export interface Placement {
     end?: number | Anchor;
 }
 /**
- * One mark as `marks` lists it: one of a voice's four, or one the host announced on a score, which
- * has a name and no voice.
+ * One mark as `marks` lists it: one of a voice's, or one the host announced on a score, which has a
+ * name and no voice.
  *
  * @category score
  */
 export interface Marked {
     /** On the host's clock. */
     timestamp: number;
-    /** Which of a voice's four this is; undefined for an announced mark. */
+    /** Which of a voice's this is; undefined for an announced mark. */
     mark: Mark | undefined;
     /** The voice it belongs to; undefined for an announced mark. */
     voice: number | undefined;
     score: string | undefined;
     name: string | undefined;
     tags: readonly string[];
+    /** The `name` of the mix the voice is in, or that announced the mark; undefined for none. */
+    mix: string | undefined;
 }
 /**
  * An event at a time on a voice's own clock, which `book` hands a host ahead of time. It plays once
@@ -368,8 +387,31 @@ export interface Booker {
  *
  * @category voice
  */
-export interface VoiceSpec<I, O, H = unknown> {
+/**
+ * How a voice or owner held by a span may give way so the span keeps its budget, which the span's
+ * fit reads. Anything it does not allow, it will not do. Read only under a span.
+ *
+ * @category score
+ */
+export interface SpanHints {
+    /** How many times faster than its own rate it may play. Default 1: no faster. */
+    faster?: number;
+    /** How many times slower than its own rate it may play. Default 1: no slower. */
+    slower?: number;
+    /** Whether it may start before the one before it ends, where the span's order would not. */
+    overlap?: boolean;
+    /** Whether it may jump to its end instead of playing. A span held by a span is never skipped. */
+    ballast?: boolean;
+    /** How hard its own length holds against the span's budget. Default `weak`. */
+    priority?: Strength;
+}
+export interface VoiceSpec<I, O, H = unknown> extends SpanHints {
     patch: Patch<I, O, unknown, H>;
+    /**
+     * What `history.revive` rebuilds this spec from, so a history `store` can page the voice out once
+     * it has left. A voice cued without it stays in memory for as long as history reaches it.
+     */
+    as?: Described;
     /**
      * 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
@@ -395,7 +437,7 @@ export interface VoiceSpec<I, O, H = unknown> {
     /**
      * 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 — unless it holds after.
+     * set, at once where none is — unless it freezes after.
      */
     loop?: boolean | number;
     /**
@@ -406,12 +448,14 @@ export interface VoiceSpec<I, O, H = unknown> {
     /**
      * 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`
+     * out, or both. A frozen 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.
+     * frame the voice shows. A voice freezing after stays, `frozen`, 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 keeps its target already. Default: neither.
      */
+    freeze?: 'before' | 'after' | 'both';
+    /** @deprecated Use `freeze`. A voice that sets only `hold` still freezes; `freeze` wins over it. */
     hold?: 'before' | 'after' | 'both';
     /** Steady weight, or a signal read per subject per frame. Default 1. */
     weight?: number | Signal<I, H>;
@@ -443,7 +487,7 @@ export interface VoiceSpec<I, O, H = unknown> {
      * 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's weight and fade. Without a `freeze` of its own it takes the owner's.
      */
     owner?: Handle<I>;
 }
@@ -452,7 +496,7 @@ export interface VoiceSpec<I, O, H = unknown> {
  *
  * @category voice
  */
-export interface OwnerSpec<I, H = unknown> {
+export interface OwnerSpec<I, H = unknown> extends SpanHints {
     /**
      * 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.
@@ -467,7 +511,9 @@ export interface OwnerSpec<I, H = unknown> {
     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. */
+    /** The freeze every child without one of its own takes. */
+    freeze?: 'before' | 'after' | 'both';
+    /** @deprecated Use `freeze`. An owner that sets only `hold` still freezes; `freeze` wins over it. */
     hold?: 'before' | 'after' | 'both';
     /** Words a source attaches to it, as a voice's. */
     tags?: readonly string[];
@@ -480,6 +526,58 @@ export interface OwnerSpec<I, H = unknown> {
     /** The owner it plays under, so owners nest. */
     owner?: Handle<I>;
 }
+/**
+ * What `span` takes: an owner with a budget, which lays out the voices it holds in an order and
+ * fits them into the budget.
+ *
+ * @category score
+ */
+export interface SpanSpec<I, H = unknown> extends OwnerSpec<I, H> {
+    /** Its budget, ms on its own clock. Default: none, so its children only keep their order. */
+    duration?: number;
+    /** How hard the budget holds against its children's own lengths. Default `strong`. */
+    priority?: Strength;
+    /** How its children are laid out, in the order they were cued. Default `queue`. */
+    order?: Order;
+    /** How far through the one before a child starts under `stagger`, 0..1. Default 0.5. */
+    share?: number;
+    /**
+     * How the children are fitted once they are retimed toward the budget, faster or slower as
+     * their hints allow. Default `pipe(condense(), shed())`.
+     */
+    fit?: Fit;
+    /**
+     * What happens where the fit leaves them too long for a span at least `strong`: `instant` jumps
+     * every child weaker than the span to its end at once, and `overrun` lets them run long.
+     * Default `instant`.
+     */
+    spill?: 'instant' | 'overrun';
+}
+/**
+ * How a span's last fit came out.
+ *
+ * @category score
+ */
+export interface FitResult {
+    /** Its budget, ms on its own clock; Infinity for none. */
+    budget: number;
+    /** Where its children end, ms on its own clock from its start. */
+    length: number;
+    /** How far `length` runs past the budget, 0 where it does not. */
+    over: number;
+    /** How many children it jumps to their end. */
+    skipped: number;
+    /** Whether the fit failed and `spill` decided. */
+    fell: boolean;
+}
+/**
+ * A span's handle: an owner's, and how its children were last fitted.
+ *
+ * @category score
+ */
+export interface SpanHandle<I = unknown> extends Handle<I> {
+    readonly result: FitResult;
+}
 /**
  * How a voice leaves when it is faded: the whole voice, or one subject.
  *
@@ -488,8 +586,13 @@ export interface OwnerSpec<I, H = unknown> {
 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';
+    /**
+     * When the fade begins. A mix time: ahead, the voice plays untouched until then and begins
+     * its fade exactly there, its `out` mark fixed from now, and `rise` before then takes it
+     * back with nothing changed; at or behind now, the fade began then and is partway. `'rest'`:
+     * leave per subject at the first frame that subject's contribution is at rest. Default now.
+     */
+    at?: number | 'rest';
     /** Ms after which the voice leaves whether or not it rested. */
     deadline?: number;
     subject?: never;
@@ -510,8 +613,8 @@ export type FadeOptions<I = unknown> = {
  */
 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';
+    /** `frozen`: a voice freezing after has played every pass and shows its last frame until faded. */
+    readonly state: 'pending' | 'live' | 'frozen' | '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. */
@@ -530,10 +633,19 @@ export interface Handle<I = unknown> {
      */
     seek(elapsed: number): void;
     fade(opts?: FadeOptions<I>): void;
+    /**
+     * Turns a fade out around: the voice climbs back from where its fade had got to, up the same
+     * curve, over `over` ms for the whole curve (default its `fade.in`, else its `fade.out`), and
+     * plays on as if never faded. A fade waiting for rest is taken back at once; a voice not fading
+     * is left as it is. A voice whose own end began the fade starts it again at its next frame.
+     */
+    rise(opts?: {
+        over?: number;
+    }): 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 and does not hold before, has left at rest, or has never been
+     * not reach, has not started on and does not freeze before, has left at rest, or has never been
      * probed for; 0 once done.
      * Costs nothing until it is asked.
      */
@@ -558,7 +670,7 @@ export interface MixOptions<H = 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
+     * The band a rest-less channel's contribution 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.
      */
     band?: {
@@ -584,23 +696,232 @@ export interface MixOptions<H = unknown> {
      * read back restores the nearest copy and steps forward from it. Off by default, and a mix without
      * it keeps nothing. With `inputs`, it also keeps what each input signal on a voice's weight read
      * per subject, and the host fields patches `reads`, each time they changed, so a read back over a
-     * `level` or a pointer is known rather than held.
+     * `level` or a pointer is known rather than held. With `tape`, the mix also records every call
+     * the host makes on it, its handles and its motion patches, so `seek` can move it and play those
+     * calls again.
      */
-    history?: {
-        ms: number;
-        every?: number;
-        inputs?: boolean;
-    };
+    history?: HistoryOptions;
+    /**
+     * A subject's key, for a history `store`: unique among this mix's subjects for the session. A
+     * string or number subject is its own key; with a store, an object subject needs this.
+     */
+    keyOf?(subject: never): string | number;
     /**
      * Whether a channel may run as a lane: computed for every subject at once in flat arrays, when
      * every voice writing it can run that way. On by default; the pose is the same either way, so
      * turning it off is for ruling a lane out, or for comparing against. Two things differ: a
-     * stateless patch's `setting.send` from `at` sends for every subject a lane fills, probed or not,
-     * and a patch that first calls `setting.keep` partway through playing can advance that state once
-     * more for one unprobed subject (see `Setting.keep`).
+     * stateless patch's `setting.send` from `at` sends for every subject a lane fills, those probed
+     * this frame or the last, and a patch that first calls `setting.keep` partway through playing can
+     * advance that state once more for one subject probed the frame before (see `Setting.keep`).
      */
     lanes?: boolean;
+    /**
+     * The transport this mix plays on, shared with other mixes, so they keep one clock and a query
+     * naming a score looks in all of them. The transport's `sync`, `rebase`, `rate`, `ramp` and
+     * `seek` move it, and the mix's own throw. Its history is the transport's, so the mix takes no
+     * `history` of its own.
+     */
+    transport?: Transport;
+    /** What `Marked.mix` and errors call this mix. */
+    name?: string;
 }
+/**
+ * What a mix or transport remembers, for `seek` and `project` to read back: see
+ * `MixOptions.history`.
+ *
+ * @category mix
+ */
+export interface HistoryOptions {
+    /** How much stays in memory, ms of mix time. With a `store`, the rest is paged out, not dropped. */
+    ms: number;
+    every?: number;
+    inputs?: boolean;
+    tape?: TapeMaker;
+    /**
+     * Where history older than `ms` goes instead of being dropped. A `seek` or `project` reaching
+     * past memory needs `prepare` first, or throws `HistoryMiss`. With a store, blits never prunes
+     * the tape: the host bounds it.
+     */
+    store?: HistoryStore;
+    /** Rebuilds a cued voice's spec from the descriptor it was cued with, so the voice can be paged out. */
+    revive?(d: Described): VoiceSpec<any, any>;
+}
+/**
+ * A voice as plain data: `kind` names what built it, and `data` survives `structuredClone`.
+ *
+ * @category mix
+ */
+export interface Described {
+    kind: string;
+    data: unknown;
+}
+/**
+ * Where a history `store` keeps what memory let go of. blits decides what is kept and when it is
+ * read back; the store decides where it lives.
+ *
+ * @category mix
+ */
+export interface HistoryStore {
+    /** Records leaving memory. One brought back by a seek may be paged again: keep one per key and `at`. */
+    page(out: readonly Paged[]): void;
+    /**
+     * What a restore to mix time `t` needs, for every mix: from each stream, per voice and subject,
+     * the latest record at or before `t` and every record after it. Returning everything is fine.
+     */
+    load(t: number): Promise<readonly Paged[]>;
+    /** A seek went back to `t`: every record after it is from a future the tape makes again. Forget them. */
+    cut(t: number): void;
+}
+/**
+ * What a history record holds: a voice's `controls`, a stateful record's `snap`, an `input`
+ * signal's reading, a subject's record when it `left` a voice, a motion subject's `released` run
+ * or older `stretch`, the `host` fields patches read, or a whole `voice` that has left.
+ *
+ * @category mix
+ */
+export type PagedStream = 'voice' | 'snap' | 'input' | 'left' | 'released' | 'stretch' | 'host' | 'controls';
+/**
+ * One history record leaving memory, as plain data.
+ *
+ * @category mix
+ */
+export interface Paged {
+    /** The mix's `name`; '' for a mix made alone without one. */
+    mix: string;
+    stream: PagedStream;
+    /** The voice's id, for every stream but `host`. */
+    voice?: number;
+    /** The subject's key, for a record of one subject. */
+    subject?: string | number;
+    /** Mix time. */
+    at: number;
+    data: unknown;
+}
+/**
+ * How a transport is made: what history it keeps for every mix on it.
+ *
+ * @category mix
+ */
+export interface TransportOptions {
+    history?: MixOptions['history'];
+}
+/**
+ * Every mix on a transport read at another mix time, with nothing live moved: `of` gives one mix's
+ * reading. Valid until the transport is next synced or a mix on it cued.
+ *
+ * @category mix
+ */
+export interface TransportProjection {
+    readonly timestamp: number;
+    of<I, O, H>(mix: Mix<I, O, H>): Projection<I, O>;
+}
+/**
+ * One clock several mixes play on, each over its own kit: one sync, one rate, one seek and one
+ * tape for all of them, and a score that spans them, so an anchor in one mix waits on a voice in
+ * another by naming the score they share. A query naming no score stays in its own mix.
+ *
+ * @category mix
+ */
+export interface Transport {
+    /** The host reports the clock once a frame, after the frame's cues, as `Mix.sync` does. */
+    sync(timestamp: number): void;
+    /** As `Mix.rebase`, for every mix on it. */
+    rebase(): void;
+    /** As `Mix.rate`, multiplied into every voice of every mix on it. */
+    rate: number;
+    ramp(rate: number, over: number): void;
+    /**
+     * As `Mix.seek`, for every mix on it at once: back, each mix restores itself; forward, the one
+     * tape plays every mix's calls again in the order they were made, so an anchor across mixes
+     * answers as it did. A mix dropped after the moment sought is back on the transport.
+     */
+    seek(time: number): void;
+    /**
+     * Loads from the history `store` what `seek(time)` and `project(time)` will need, where that
+     * reaches past memory. Without a store, or within memory, it loads nothing.
+     */
+    prepare(time: number): Promise<void>;
+    readonly now: number;
+    readonly tape: Tape | undefined;
+    /** Puts a named mark on a score every mix on it sees. Throws without a `score`. */
+    announce(name: string, opts: {
+        at?: number;
+        score: string;
+        tags?: readonly string[];
+    }): void;
+    /** Every mark of every mix on it, and every mark announced on it, earliest first. */
+    marks(from: number, to: number): Marked[];
+    /** Every mix on it read at mix time `time`, together, so anchors across them answer. */
+    project(time: number): TransportProjection;
+    /** Any mix on it live. */
+    readonly live: boolean;
+    /** Every mix on it inert. */
+    readonly inert: boolean;
+    /** Calls `fn` when any mix on it needs frames again after a sync, once until the next sync. */
+    onWake(fn: () => void): () => void;
+    /**
+     * Takes a mix off: it is no longer synced and takes no more calls. With history, a seek back
+     * before the drop puts it back as it was then; without, it is let go.
+     */
+    drop<I, O, H>(mix: Mix<I, O, H>): void;
+}
+/**
+ * One host call a mix recorded on its tape: `apply` makes it again, and `invert` does nothing,
+ * since a mix goes back by restoring what it kept rather than by undoing calls.
+ *
+ * @category mix
+ */
+export interface TapeOp {
+    apply(adapter: unknown): void;
+    invert(): TapeOp;
+    label?: string;
+}
+/**
+ * One future a tape keeps at its current entry: the calls the host made after the mix last went
+ * back here, before it made new ones.
+ *
+ * @category mix
+ */
+export interface TapeBranch {
+    /** Its first entry's id, which `switchBranch` takes. */
+    id: number;
+    label: string;
+    timestamp: number;
+    /** How many entries run along it from here. */
+    length: number;
+    /** Whether the mix plays it on from here. */
+    current: boolean;
+}
+/**
+ * Where a mix keeps the host's calls, by mix time, for `seek`. weasel-history's `History`
+ * (`@weasel-js/history`) has this shape. A host reads `branches` and calls `switchBranch` to pick
+ * which recorded future plays on; moving it any other way is the mix's job.
+ *
+ * @category mix
+ */
+export interface Tape {
+    recordEntry(ops: TapeOp[], label: string): void;
+    undoDepth(): number;
+    timestampAt(i: number): number | undefined;
+    depthAt(t: number): number;
+    goto(n: number): void;
+    redo(): void;
+    prune(t: number): void;
+    branches(): readonly TapeBranch[];
+    switchBranch(id: number): void;
+}
+/**
+ * Makes a mix's tape: weasel-history's `createHistory` is one. The mix passes the clock it stamps
+ * calls with, branching on, so a call made after going back keeps the old future as a branch, and
+ * coalescing off.
+ *
+ * @category mix
+ */
+export type TapeMaker = (adapter: unknown, opts: {
+    now: () => number;
+    branching: boolean;
+    coalesceWindowMs: number;
+}) => Tape;
 /**
  * How sure a projection is of one channel: `exact` where only the clock and known changes drove
  * it; `stepped` where state was advanced across a gap in one go, which is as good as the patch's
@@ -617,7 +938,7 @@ export type Doubt = 'exact' | 'stepped' | 'held';
  * @category mix
  */
 export interface Projection<I, O> {
-    /** The timestamp it reads at, on the host's clock. */
+    /** The mix time it reads at. */
     readonly timestamp: number;
     /** The merged pose for one subject at this projection's timestamp. */
     probe(subject: I, out?: O): O;
@@ -660,7 +981,20 @@ export interface Mix<I, O, H = unknown> {
      * 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. */
+    /**
+     * Cues a span: an owner that lays out the voices it holds in `order` and fits them into its
+     * `duration`, again each time one joins or leaves early. A child's start and rate are the
+     * span's to set, so it takes neither `start` nor an anchored start; its `SpanHints` say how it
+     * may give way. A span with a budget stays until the budget has passed, though its children
+     * finish sooner, so late ones can still join, and its `end` mark is where its children end or
+     * its budget does, whichever is later. A voice that loops for good cannot join one.
+     */
+    span(spec: SpanSpec<I, H>): SpanHandle<I>;
+    /**
+     * The host reports the clock, once a frame. Nothing advances at the call. Throws for a timestamp
+     * earlier than the last sync's, short of a `rebase`: the host's clock only goes forward, and
+     * `seek` moves the mix.
+     */
     sync(timestamp: number): void;
     /**
      * The time between the last sync and the next one is not to count: a host calls it when a
@@ -669,7 +1003,7 @@ export interface Mix<I, O, H = unknown> {
     rebase(): void;
     /**
      * 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
+     * whole mix. A negative rate throws: the mix plays only forward, and `seek` moves it back. 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
@@ -703,18 +1037,54 @@ export interface Mix<I, O, H = unknown> {
      */
     pull(subjects: Iterable<I>, into: Columns<O>): void;
     /**
-     * Reads the mix at another timestamp, on the host's clock, without moving it. Ahead of the last
-     * sync it plays what is cued forward; behind it, it needs `history`, and throws for a timestamp
-     * older than the history reaches.
+     * Reads the mix at another mix time, without moving it. Ahead of the mix it plays what is cued
+     * forward, and throws for a time past a call the tape will play again after a `seek` back, which
+     * only a seek there makes; behind it, it needs `history`, and throws for a time older than the
+     * history reaches. On a transport it reads every mix on it together, so anchors across them
+     * answer.
+     */
+    project(time: number): Projection<I, O>;
+    /**
+     * Moves the mix to mix time `time`, as it stood at the end of that frame, and plays on from
+     * there. Needs `history` with a `tape`, which records the host's calls by mix time.
+     *
+     * Back, the mix restores itself: controls, records, voices and marks as they stood then. Voices
+     * that left after it are back on the handles the host holds, their `done` and `played` starting
+     * over where they had settled since. Voices cued after it wait as `pending` until the mix plays
+     * their cue again. Stateful voices restart from the copy `history` kept nearest before it and
+     * step once to it, exact under `stepMs`. A subject faded out of a voice or dropped after it comes
+     * back with the record it had, a motion patch's state included. Recorded input and host fields
+     * after it are let go: after a seek back, signals and host fields read live again, and `assess`
+     * reports what they fed as `held`.
+     *
+     * Forward, through a sync or a later seek, the mix plays the recorded calls again at the mix
+     * times they were made: cues, handle writes, fades, retargets and pushes, its rate, marks,
+     * `mute` and `drop`. A call the host makes while there are recorded calls ahead starts a new
+     * branch, and the tape keeps the old future beside it; `tape.switchBranch` picks one back.
+     * Playing past a time again sends its events and books its marks and hits again.
+     *
+     * The host goes on passing its own clock: the next `sync` reads the moment sought plus the
+     * host's time since its last sync. Throws for a time older than history reaches, and before
+     * the first sync. With a history `store`, a time older than memory needs `prepare` first, or
+     * throws `HistoryMiss` before anything moves.
      */
-    project(timestamp: number): Projection<I, O>;
+    seek(time: number): void;
+    /** As `Transport.prepare`, for a mix made alone. */
+    prepare(time: number): Promise<void>;
+    /**
+     * The mix clock at the last sync or seek, which `seek` and `project` take; NaN before the first
+     * sync. Host time at the mix's rate, less what `rebase` took out and `seek` moved.
+     */
+    readonly now: number;
+    /** The tape `history.tape` made, undefined without one. */
+    readonly tape: Tape | undefined;
     /**
      * 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
+     * A handle on every voice still in the mix, pending, live, frozen 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.
      */
@@ -722,12 +1092,19 @@ export interface Mix<I, O, H = unknown> {
     /** 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
+     * Another frame would change no pose, so a host's frame loop may sleep: every voice is done, frozen
      * 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;
+    /**
+     * Calls `fn` when a host call makes the mix need frames again after a sync: a cue, a fade, a
+     * handle's or the mix's rate, a seek, a `drop`, a motion retargeted. It fires once until the next
+     * sync clears the change, and never during `sync`. Returns a function that unsubscribes `fn`.
+     * A frame loop sleeping on `inert` subscribes here to wake.
+     */
+    onWake(fn: () => void): () => void;
     /** Fades every voice out: over `over` when given, over each voice's own `fade.out` otherwise. */
     mute(opts?: {
         over?: number;
@@ -755,8 +1132,8 @@ export interface Mix<I, O, H = unknown> {
      * Every event patches have sent since the last drain, earliest first, in the order they were sent
      * where two share a timestamp. A subject's events are made while it catches up, which is when it is
      * probed, so one nobody probes has sent nothing yet: promptness is the host's, by probing. A
-     * stateless patch's `at` on a lane is the exception: it runs for every subject the mix has met, at
-     * the frame's first probe. Under `stepMs` each carries the end of the interval it happened in, so
+     * stateless patch's `at` on a lane is the exception: it runs at the frame's first probe for every
+     * subject probed that frame or the last. Under `stepMs` each carries the end of the interval it happened in, so
      * what is sent and when does not depend on how the host spaces its probes. Time `rebase` took out
      * sends nothing. Given a tag, it takes only the events of voices carrying it and leaves the rest for
      * whoever drains them.