@msb235/blits 0.10.0 → 0.11.0

package/dist/tape.js

@@ -1,4 +1,13 @@
 import { move } from './move.js';
+const live = { transport: (of) => of, mix: (of) => of };
+/** The stage the tape is playing calls on; the live one outside a read ahead's replay. */
+let stage = live;
+/** What a call threw on a read ahead's stage, for `replay` to throw once the tape has the entry back. */
+let failed;
+/** Refuses a recorded call a read ahead's copies cannot take. */
+export function unplayable(what) {
+    throw new Error(`blits: the tape holds ${what}, which a read ahead cannot play; seek there to see it`);
+}
 /** What a recorded call's `invert` gives: a mix goes back by restoring, never by undoing a call. */
 const undone = { apply() { }, invert: () => undone };
 /**
@@ -15,7 +24,10 @@ export function tapeOf(transport) {
         coalesceWindowMs: 0,
     });
 }
-/** Records a host call, which `again` makes once more when the mix plays past it after a seek. */
+/**
+ * Records a host call, which `again` makes once more when the mix plays past it after a seek, or
+ * when a read ahead does, on the stage it is given.
+ */
 export function record(on, label, again) {
     const tape = on.tape;
     if (tape === undefined || on.replaying || on.projecting)
@@ -23,7 +35,16 @@ export function record(on, label, again) {
     const op = {
         label,
         apply() {
-            again();
+            if (stage === live)
+                again(stage);
+            // Thrown inside the tape's `redo`, it would leave the tape without the entry.
+            else
+                try {
+                    again(stage);
+                }
+                catch (e) {
+                    failed ??= { error: e };
+                }
         },
         invert: () => undone,
     };
@@ -33,16 +54,26 @@ export function record(on, label, again) {
 export function hostAt(clock, t) {
     return clock.pace === null ? t : clock.pace.timeOf(t);
 }
+/**
+ * The host time a move ahead to mix time `t` lands at: never behind the clock's own, since rate 0
+ * reads `t` at every host time from the earliest `hostAt` gives, and a call stamped earlier than
+ * one already on the tape would cut it out of order.
+ */
+export function hostAhead(clock, t) {
+    const at = hostAt(clock, t);
+    return clock.u > at ? clock.u : at;
+}
 /**
  * Makes the recorded calls `due` by the host time each was made at again, each host time's in a
  * frame of its own with every mix on the transport moved to where it stood then, as the host made
- * them. Answers the host time of the last frame it played, NaN for none.
+ * them. Answers the host time of the last frame it played, NaN for none. Given `onto` and the
+ * stage of its copies, it makes them on those, and the caller puts the tape back.
  */
-export function replay(transport, due) {
+export function replay(transport, due, onto = transport, on = live) {
     const tape = transport.tape;
     if (tape === undefined)
         return Number.NaN;
-    const u = transport.u;
+    const u = onto.u;
     let last = Number.NaN;
     try {
         for (;;) {
@@ -51,23 +82,30 @@ export function replay(transport, due) {
                 return last;
             if (at !== last) {
                 last = at;
-                transport.u = at;
-                const now = transport.pace === null ? at : transport.pace.reading(at);
-                if (now > transport.now)
-                    for (const m of transport.members)
+                onto.u = at;
+                const now = onto.pace === null ? at : onto.pace.reading(at);
+                if (now > onto.now)
+                    for (const m of onto.members)
                         move(m, now);
-                transport.tick(transport.now);
+                onto.tick(onto.now);
             }
             transport.replaying = true;
+            stage = on;
             try {
                 tape.redo();
             }
             finally {
                 transport.replaying = false;
+                stage = live;
+            }
+            if (failed !== undefined) {
+                const { error } = failed;
+                failed = undefined;
+                throw error;
             }
         }
     }
     finally {
-        transport.u = u;
+        onto.u = u;
     }
 }

package/dist/transport.d.ts

@@ -94,6 +94,11 @@ export declare class Transport implements TransportApi {
     settle(): void;
     /** The frame the rate was first set in, which a seek or read back to before it finds unset. */
     pacedSeq: number;
+    /**
+     * On a read ahead's own transport, the retargets and pushes its tape's calls made, which
+     * `reading.ahead` hands the motion patches while it reads.
+     */
+    ahead: Map<object, Map<unknown, unknown[]>>;
     /** True while the tape makes a recorded call again, so it is not recorded twice. */
     replaying: boolean;
     announced: Announced[];
@@ -114,7 +119,9 @@ export declare class Transport implements TransportApi {
     drop<I, O, H>(mix: Mix<I, O, H>): void;
     /** A seek back to frame `seq`: every mix dropped after it is back on, as it stood then. */
     undrop(seq: number): void;
-    seek(time: number): void;
+    seek(to: number | {
+        readonly frame: number;
+    }): void;
     prepare(time: number): Promise<void>;
     announce(name: string, opts: {
         at?: number;
@@ -122,7 +129,9 @@ export declare class Transport implements TransportApi {
         tags?: readonly string[];
     }): void;
     marks(from: number, to: number): Marked[];
-    project(time: number): TransportProjection;
+    project(at: number | {
+        readonly frame: number;
+    }): TransportProjection;
     get live(): boolean;
     get inert(): boolean;
     onWake(fn: () => void): () => void;

package/dist/transport.js

@@ -68,6 +68,11 @@ export class Transport {
     }
     /** The frame the rate was first set in, which a seek or read back to before it finds unset. */
     pacedSeq = Number.POSITIVE_INFINITY;
+    /**
+     * On a read ahead's own transport, the retargets and pushes its tape's calls made, which
+     * `reading.ahead` hands the motion patches while it reads.
+     */
+    ahead = new Map();
     /** True while the tape makes a recorded call again, so it is not recorded twice. */
     replaying = false;
     announced = [];
@@ -110,7 +115,11 @@ export class Transport {
         m.dropped = true;
         if (this.history !== undefined) {
             this.dropped.push({ mix: m, at: this.now, seq: this.seq });
-            record(this, 'drop', () => this.drop(mix));
+            record(this, 'drop', (stage) => {
+                const to = stage.mix(m);
+                if (to !== undefined)
+                    stage.transport(this).drop(to);
+            });
         }
     }
     /** A seek back to frame `seq`: every mix dropped after it is back on, as it stood then. */
@@ -124,8 +133,8 @@ export class Transport {
             this.join(d.mix, d.mix.slot);
         }
     }
-    seek(time) {
-        seek(this, time);
+    seek(to) {
+        seek(this, to);
     }
     prepare(time) {
         return prepare(this, time);
@@ -138,8 +147,8 @@ export class Transport {
     marks(from, to) {
         return listedAll(this, from, to).map(({ order: _, ...m }) => m);
     }
-    project(time) {
-        return projectAll(this, time);
+    project(at) {
+        return projectAll(this, at);
     }
     get live() {
         return this.members.some((m) => m.live);
@@ -286,7 +295,8 @@ export class Transport {
         if (!(rate >= 0 && rate < Number.POSITIVE_INFINITY))
             throw new RangeError(`blits: a mix's rate is a finite number, 0 or more, not ${rate}`);
         if (this.pace === null) {
-            this.pace = new Pace(this.history !== undefined);
+            // A read ahead keeps every clock too: it moves once across calls a mix met frame by frame.
+            this.pace = new Pace(this.history !== undefined || this.projecting);
             this.pacedSeq = this.seq;
             // Until now mix time was host time, so a pending voice's start is the host time it was given.
             for (const m of this.members)
@@ -298,7 +308,7 @@ export class Transport {
         this.pace.change(this.u, rate, over, reach, this.seq);
         for (const m of this.members)
             m.stir();
-        record(this, 'rate', () => this.ramp(rate, over));
+        record(this, 'rate', (stage) => stage.transport(this).ramp(rate, over));
     }
 }
 /** Puts a mark on a score: one the transport announced, or a mix on it, `slot`. */
@@ -316,8 +326,9 @@ export function announce(transport, name, opts, slot, mix) {
     };
     transport.announced.push(mark);
     transport.settle();
-    record(transport, 'announce', () => {
-        transport.announced.push({ ...mark, seq: transport.seq });
+    record(transport, 'announce', (stage) => {
+        const to = stage.transport(transport);
+        to.announced.push({ ...mark, seq: to.seq });
     });
 }
 /**

package/dist/types/mix.d.ts

@@ -3,7 +3,7 @@ import type { HistoryOptions, Tape } from './history.js';
 import type { Patch, Sent, Signal } from './patch.js';
 import type { Booker, BookOptions, Marked } from './place.js';
 import type { Transport } from './transport.js';
-import type { Handle, OwnerSpec, SpanHandle, SpanSpec, VoiceSpec } from './voice.js';
+import type { BlendMember, Handle, OwnerSpec, SpanHandle, SpanSpec, VoiceSpec } from './voice.js';
 /**
  * How a mix is built: its engine, reduced motion, the host, and its limits.
  *
@@ -77,7 +77,7 @@ export interface MixOptions<H = unknown> {
 /**
  * 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
- * step makes it; `held` where it depends on input from outside the clock, whose value at that time
+ * step makes it, or a signal's state was read back from a copy; `held` where it depends on input from outside the clock, whose value at that time
  * is not known, so the value it had is held.
  *
  * @category mix
@@ -119,9 +119,11 @@ export interface Mix<I, O, H = unknown> {
     /**
      * 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.
+     * takes its share of that one reading, which `share` reads outside the blend; a signal keeping
+     * state keeps it once, not per member. One `spec` cues them all, and a member given as a
+     * `BlendMember` carries its own `name`, `tags` and `hits` in place of the spec's.
      */
-    blend(patches: readonly Patch<I, O, unknown, H>[], by: Signal<I, H>, spec?: Omit<VoiceSpec<I, O, H>, 'patch' | 'weight' | 'locus'>): Handle<I>[];
+    blend(members: readonly (Patch<I, O, unknown, H> | BlendMember<I, O, 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
@@ -139,7 +141,9 @@ export interface Mix<I, O, H = unknown> {
      * 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.
+     * its budget does, whichever is later. A voice that loops for good cannot join one. Throws for
+     * a `rate` below 0: a span lays its children out forward from its start, and its handle's `rate`
+     * turns it once it plays.
      */
     span(spec: SpanSpec<I, H>): SpanHandle<I>;
     /**
@@ -194,8 +198,11 @@ export interface Mix<I, O, H = unknown> {
     /**
      * Reads the mix at another mix time, without moving it. At the mix's own time it reads what
      * `probe` does: what the host has done since the last sync lands at the next. 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, with `history`, it reads the last frame at or before `time`
+     * it plays what is cued forward, with the calls the tape holds after a `seek` back, and while a
+     * voice could carry state (a patch that steps, a signal weight) it reads each subject asked about
+     * at every known event on the way: each call, and each mark `marks` would list. It throws
+     * for the two a copy cannot take: a `drop` of a subject a motion patch holds, and a retarget or
+     * push made before its voice met the subject. Behind it, with `history`, it reads the last frame at or before `time`
      * as that frame showed, 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.
      *
@@ -204,8 +211,13 @@ export interface Mix<I, O, H = unknown> {
      * alone: no state, motion, `from: 'current'`, anchor or owner, no write to its handle, and no channel without a rest
      * at a weight that moves. The mix's rate has never been set. And `time` is no earlier than the
      * last cue, `drop`, `touch`, `announce` or `rebase`, or the last frame a voice left in.
+     *
+     * Given `{ frame }`, a number `seq` read, it reads that frame as it showed, as `seek` does; it
+     * needs `history`.
      */
-    project(time: number): Projection<I, O>;
+    project(at: number | {
+        readonly frame: 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; where rate 0 held the clock at `time` for several frames, the last of them. Needs
@@ -214,11 +226,12 @@ export interface Mix<I, O, H = unknown> {
      * 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`.
+     * their cue again, and a write to the handle of one waiting changes nothing. 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 in the frames
      * they were made in: cues, handle writes, fades, retargets and pushes, its rate, marks,
@@ -230,8 +243,15 @@ export interface Mix<I, O, H = unknown> {
      * 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.
+     *
+     * Given `{ frame }`, a number `seq` read, it moves to the end of that frame instead, which is
+     * how a host reaches an earlier one of several frames rate 0 held at one mix time. The frame has
+     * to be one history still holds: not let go with age, and not after a moment an earlier seek went
+     * back to. With a store, one older than memory needs `prepare` of its mix time first.
      */
-    seek(time: number): void;
+    seek(to: number | {
+        readonly frame: number;
+    }): void;
     /** As `Transport.prepare`, for a mix made alone. */
     prepare(time: number): Promise<void>;
     /**
@@ -241,6 +261,11 @@ export interface Mix<I, O, H = unknown> {
     readonly now: number;
     /** The host's timestamp at the last sync; NaN before the first. */
     readonly timestamp: number;
+    /**
+     * The number of the frame being played, which `seek({ frame })` and `project({ frame })` take:
+     * each sync and seek begins a frame with a higher one, so two frames at one mix time differ.
+     */
+    readonly seq: number;
     /** The tape `history.tape` made, undefined without one. */
     readonly tape: Tape | undefined;
     /**

package/dist/types/patch.d.ts

@@ -129,7 +129,11 @@ export interface Patch<I, O, S = void, H = unknown> {
     readonly form: 'fn' | 'keys' | 'motion';
     /** Milliseconds one pass lasts, whether or not the voice loops. 0 has no passes: phase and pass stay 0. */
     readonly duration: number;
-    /** The channels this patch contributes to. Every key `at` sets, and no others. */
+    /**
+     * The channels this patch contributes to. Every key `at` sets, and no others: a mix drops any
+     * other key, and warns once per patch outside production when it finds one in the first delta a
+     * voice's `at` returns.
+     */
     readonly writes: readonly (keyof O)[];
     /**
      * The channels this patch was written against. `cue` refuses a mix whose channel of the same name

package/dist/types/place.d.ts

@@ -8,6 +8,12 @@
  * @category score
  */
 export type Mark = 'start' | 'in' | 'coast' | 'out' | 'end';
+/**
+ * A mark by name: one of a voice's own five, or one it places inside itself with `marks`.
+ *
+ * @category score
+ */
+export type MarkName = Mark | (string & {});
 /**
  * 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,
@@ -26,7 +32,8 @@ export interface Query {
     resolver?: 'last' | 'first' | 'next' | 'earliest' | 'latest';
 }
 /**
- * A time given by another voice: `mark` of the voice `of` selects, moved by `by` ms. `after` is
+ * A time given by another voice: `mark` of the voice `of` selects, moved by `by` ms, where `mark`
+ * is one of its five or one it places inside itself with `marks`. `after` is
  * sugar for that voice's `end`, `with` for its `start`, and `before` for its start less `by`. A
  * 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.
@@ -35,7 +42,7 @@ export interface Query {
  */
 export type Anchor = {
     of: string | Query;
-    mark: Mark;
+    mark: MarkName;
     by?: number;
 } | {
     after: string | Query;
@@ -77,8 +84,8 @@ export interface Placement {
 export interface Marked {
     /** On the host's clock. */
     timestamp: number;
-    /** Which of a voice's this is; undefined for an announced mark. */
-    mark: Mark | undefined;
+    /** Which of a voice's this is, one of its five or one it placed inside itself; undefined for an announced mark. */
+    mark: MarkName | undefined;
     /** The voice it belongs to; undefined for an announced mark. */
     voice: number | undefined;
     score: string | undefined;

package/dist/types/transport.d.ts

@@ -39,13 +39,17 @@ export interface Transport {
      * 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;
+    seek(to: number | {
+        readonly frame: 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;
+    /** As `Mix.seq`: the number of the frame being played, the same for every mix on it. */
+    readonly seq: 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: {
@@ -55,8 +59,13 @@ export interface Transport {
     }): 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;
+    /**
+     * Every mix on it read at mix time `at`, or at the frame `{ frame }` names, together, so anchors
+     * across them answer.
+     */
+    project(at: number | {
+        readonly frame: number;
+    }): TransportProjection;
     /** Any mix on it live. */
     readonly live: boolean;
     /** Every mix on it inert. */

package/dist/types/voice.d.ts

@@ -81,10 +81,24 @@ export interface VoiceSpec<I, O, H = unknown> extends SpanHints {
      * so one cued backward with no `seek` has ended as it starts.
      */
     seek?: number;
+    /**
+     * The interval this voice's `step` runs at, in ms of mix time, in place of the mix's `stepMs`.
+     * 0 steps it once a frame by the frame's gap, whatever the mix sets. Default: the mix's.
+     */
+    stepMs?: number;
+    /**
+     * How a stateful subject first probed after its delay ran out starts stepping. `exact` steps it
+     * from that origin, in one step capped by `maxDt` or every `stepMs` interval since, so its state
+     * is the same however late the host looked. `fresh` starts it from the probe that first meets it,
+     * with fresh state and no catch-up, on the `stepMs` grid counted from the origin: cheaper for a
+     * subject met long after its voice started, and probe-dependent by design. A subject met on time,
+     * and a handle `seek`'s rebuild, step the same either way. Default: `exact`.
+     */
+    catchUp?: 'exact' | 'fresh';
     /**
      * 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 freezes after. Default: true.
+     * set, at once where none is — unless it freezes after. Default: false.
      */
     loop?: boolean | number;
     /**
@@ -127,6 +141,14 @@ export interface VoiceSpec<I, O, H = unknown> extends SpanHints {
      * events are not known ahead, so they stay drain-only; these are the plan.
      */
     hits?: readonly Hit[];
+    /**
+     * Named marks inside the voice, beside its five, each at voice ms into a pass as a hit's `at` is:
+     * `{ drop: 340 }`. An anchor names one as it names the five, `{ of: 'lead', mark: 'drop' }`, and
+     * `marks` lists it and `book` books it under its name. Each is reached once: on the first pass
+     * that reaches it from where the voice starts, while its clock runs forward and before it ends.
+     * A name cannot be one of the five.
+     */
+    marks?: Readonly<Record<string, number>>;
     /**
      * 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
@@ -136,6 +158,22 @@ export interface VoiceSpec<I, O, H = unknown> extends SpanHints {
      */
     owner?: Handle<I>;
 }
+/**
+ * One of `mix.blend`'s members, with the labels it carries in place of the spec's: each set here
+ * replaces the spec's for this member alone. The rest of the spec times and places every member
+ * alike, so they stay one blend.
+ *
+ * @category blending
+ */
+export interface BlendMember<I, O, H = unknown> {
+    patch: Patch<I, O, unknown, H>;
+    /** What other voices call this member by. Default: the spec's `name`. */
+    name?: string;
+    /** Default: the spec's `tags`. */
+    tags?: readonly string[];
+    /** Events at times on this member's clock, as a voice's `hits`. Default: the spec's. */
+    hits?: readonly Hit[];
+}
 /**
  * What `owns` takes: an owner has no patch, and plays only through the voices it holds.
  *
@@ -147,8 +185,19 @@ export interface OwnerSpec<I, H = unknown> extends SpanHints {
      * voice's `start` is. Default: now.
      */
     start?: number;
-    /** Its clock's rate, multiplied into every child's own. Default 1. */
+    /**
+     * Its clock's rate, multiplied into every child's own. Default 1. Below 0 its clock runs back,
+     * and so does every child's: a child plays backward to its start and leaves there, as a voice cued
+     * backward does, and the owner leaves with its last child. A span is not cued backward, since it
+     * lays out its children forward from its start; its handle's `rate` turns it once it plays.
+     */
     rate?: number;
+    /**
+     * Where its clock starts, ms, as `seek` on its handle sets: its children play as far in as that
+     * puts them. Default 0, cued backward too, since an owner has no end of its own to start from; one
+     * cued at a rate below 0 with no seek runs back from 0, before any child placed on its clock.
+     */
+    seek?: 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.
@@ -166,6 +215,14 @@ export interface OwnerSpec<I, H = unknown> extends SpanHints {
     score?: string;
     /** Where it sits relative to its own owner's clock or to other voices, in place of `start`. */
     anchor?: Placement;
+    /**
+     * Events at times on its own clock, the one its children's `start` counts on, which `book`
+     * hands a host ahead of time with its `score` and `tags`. An owner does not loop, so each is
+     * booked once, while it plays: none past where it leaves, and none while its clock runs back.
+     */
+    hits?: readonly Hit[];
+    /** Named marks at times on its own clock, as a voice's `marks`. */
+    marks?: Readonly<Record<string, number>>;
     /** The owner it plays under, so owners nest. */
     owner?: Handle<I>;
 }
@@ -294,7 +351,8 @@ export interface Handle<I = unknown> {
      * 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.
+     * is left as it is. A voice whose own end began the fade starts it again at its next frame. A
+     * voice faded before its start goes back to `pending` and starts on time.
      */
     rise(opts?: {
         over?: number;
@@ -303,7 +361,7 @@ export interface Handle<I = unknown> {
      * 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 freeze before, has left at rest, or has never been
-     * probed for; 0 once done.
+     * probed for; 0 once done, and 0 after `mix.seek` goes back until the subject is probed again.
      * Costs nothing until it is asked.
      */
     weightOf(subject: I): number;

package/dist/unpage.d.ts

@@ -1,8 +1,13 @@
-import type { Transport } from './transport.js';
+import type { Frame, Transport } from './transport.js';
 /**
  * Makes memory reach mix time `t` for a seek or read there, from what `prepare` loaded; true where
  * it took records from the store. Throws before anything moves where it cannot.
  */
 export declare function cover(transport: Transport, t: number): boolean;
+/**
+ * The frame numbered `seq` for a seek or read to it, memory made to reach it from what `prepare`
+ * loaded. Throws before anything moves for a frame history does not hold.
+ */
+export declare function coverFrame(transport: Transport, seq: number): Frame;
 /** A seek back to frame `seq`: what the store and `prepare` hold after it is from a future the tape makes again. */
 export declare function cut(transport: Transport, seq: number): void;

package/dist/unpage.js

@@ -29,6 +29,29 @@ export function cover(transport, t) {
     transport.floor = loaded.t;
     return true;
 }
+/**
+ * The frame numbered `seq` for a seek or read to it, memory made to reach it from what `prepare`
+ * loaded. Throws before anything moves for a frame history does not hold.
+ */
+export function coverFrame(transport, seq) {
+    if (!Number.isInteger(seq))
+        throw new RangeError(`blits: a frame is a number \`seq\` read, not ${seq}`);
+    let frame = transport.frames.numbered(seq);
+    const pager = transport.pager;
+    if (frame === undefined && pager !== null && seq <= transport.seq) {
+        const paged = pager.loaded?.records.find((r) => r.stream === 'frame' && r.mix === '' && r.seq === seq);
+        if (paged !== undefined) {
+            cover(transport, paged.at);
+            frame = transport.frames.numbered(seq);
+        }
+        else if (seq < (transport.frames.all()[0]?.seq ?? Number.POSITIVE_INFINITY))
+            throw new Error(`blits: frame ${seq} reaches past memory; await prepare with its mix time first`);
+    }
+    if (frame === undefined)
+        throw new Error(`blits: frame ${seq} is not one this mix's history holds: not played yet, let go, or after a moment a seek went back to`);
+    cover(transport, frame.at);
+    return frame;
+}
 /** A seek back to frame `seq`: what the store and `prepare` hold after it is from a future the tape makes again. */
 export function cut(transport, seq) {
     const pager = transport.pager;
@@ -117,8 +140,17 @@ function unpageVoice(voice, records, keys) {
             const subject = keys.subject(r.subject);
             if (left.some((e) => e.seq === r.seq && Object.is(e.subject, subject)))
                 continue;
-            const [p, sync] = r.data;
-            left.push({ subject, at: r.at, seq: r.seq, sync, held: unpackHeld(voice, p) });
+            // A store written before a leaving kept its fades holds two.
+            const [p, sync, ramp = null, parted = null] = r.data;
+            left.push({
+                subject,
+                at: r.at,
+                seq: r.seq,
+                sync,
+                held: unpackHeld(voice, p),
+                ramp,
+                parted,
+            });
         }
         left.sort((a, b) => a.seq - b.seq);
         voice.left = Leavings.from(left);