@msb235/blits 0.8.1 → 0.10.0

package/dist/project.js

@@ -68,7 +68,9 @@ export function projectAll(transport, t) {
         else
             copyStanding(mix, copy, t, cut);
     }
-    if (ahead)
+    // A read at the mix's own time lands nothing, as a probe does not: what the host has done since
+    // the last sync shows at the next one.
+    if (ahead && t !== transport.now)
         for (const copy of copies.values())
             move(copy, t);
     const read = (f) => {
@@ -131,7 +133,7 @@ function copyBack(mix, c, t, cut) {
         .sort((a, b) => a.id - b.id)
         .map((v) => {
         const log = v.log;
-        const copy = v.copy((subject) => recall(mix, v, subject, t, cut), lastWithin(log, cut) ?? log[0]);
+        const copy = v.copy((subject) => recall(mix, v, subject, t, cut, c, copy), lastWithin(log, cut) ?? log[0]);
         if (then !== undefined)
             copy.setting.host = then;
         return copy;
@@ -199,7 +201,7 @@ function carry(mix, voice, subject, c, copy) {
  * A projection back starts each subject from the latest copy kept at or before `t`, else from its
  * voice's start with fresh state, which is exact for a voice stepped at a fixed interval.
  */
-export function recall(mix, voice, subject, t, cut) {
+export function recall(mix, voice, subject, t, cut, c, copy) {
     const live = voice.left?.at(subject, cut) ?? recordOf(mix, voice, subject);
     if (live === undefined)
         return undefined;
@@ -210,13 +212,16 @@ export function recall(mix, voice, subject, t, cut) {
         h.replay = live.inputs;
         return h;
     }
-    const stepped = live.since < t ? live.since : t;
+    // Its origin by the controls the voice had then: a seek or an anchor has moved a waiting
+    // voice's since.
+    const since = c === undefined || copy === undefined ? live.since : c.sinceOf(copy, live.delay);
+    const stepped = since < t ? since : t;
     const h = record(voice, live.reaches, live.reaches && voice.patch.state
         ? voice.patch.state(subject)
         : undefined);
     h.delay = live.delay;
-    h.since = live.since;
-    h.shown = live.shown;
+    h.since = since;
+    h.shown = c === undefined || copy === undefined ? live.shown : c.shownOf(copy, since);
     h.stepped = stepped;
     h.rebuilt = voice.rebuilds;
     h.from = stepped;

package/dist/record.js

@@ -15,7 +15,8 @@ export function record(voice, reaches, state) {
         rested: false,
         bands: null,
         state,
-        stepped: 0,
+        // -0, not 0: a field first given a small integer is boxed on every later write of a double.
+        stepped: -0,
         ticks: 0,
         probed: Number.NaN,
         delta: null,

package/dist/revive.d.ts

@@ -33,6 +33,8 @@ interface PackedVoice {
     opened: number;
     pinned: number;
     latest: number;
+    /** Absent from a store written before a voice kept it. */
+    soonest?: number;
     keeping: boolean;
     first: Controls | null;
     log: Controls[] | null;

package/dist/revive.js

@@ -92,6 +92,7 @@ function packVoice(voice, keys) {
         opened: voice.opened,
         pinned: voice.pinned,
         latest: voice.latest,
+        soonest: voice.soonest,
         keeping: voice.keeping,
         first: voice.first,
         log: voice.log,
@@ -128,6 +129,7 @@ export function reviveVoice(mix, id, d) {
     voice.opened = d.opened;
     voice.pinned = d.pinned;
     voice.latest = d.latest;
+    voice.soonest = d.soonest ?? 0;
     voice.keeping = d.keeping;
     voice.first = d.first;
     voice.log = d.log;

package/dist/seek.js

@@ -143,7 +143,7 @@ export function seek(transport, t) {
         throw new RangeError('blits: a mix seeks to a finite time');
     if (!(t >= transport.born))
         throw new Error(`blits: ${t} is older than this mix's history reaches`);
-    const unpaged = cover(transport, t);
+    cover(transport, t);
     if (t >= transport.now) {
         // Ahead, under the rate the recorded calls up to `t` set, past any frames rate 0 held at `t`.
         const last = replay(transport, (at) => (transport.pace === null ? at : transport.pace.reading(at)) <= t);
@@ -176,7 +176,7 @@ export function seek(transport, t) {
         transport.now = t;
         for (const m of transport.members)
             back(m, t, seq, frame.at < t);
-        cut(transport, seq, unpaged);
+        cut(transport, seq);
     }
     transport.tick(t);
     // The host's clock reads on from here: its next sync reads `t` plus its time since its last.

package/dist/spans.d.ts

@@ -16,11 +16,12 @@ export declare class Fitting {
 /** Refuses a voice a span cannot fit: one it would not own the timing of, or one with no end. */
 export declare function checkChild<I, O>(spec: VoiceSpec<I, O>, child: Voice<I, O>): void;
 /**
- * Lays out a span's children and fits them into what is left of its budget, from its clock now.
- * Only what is still to come moves: a playing child keeps its place and may change rate, a
- * pending one is placed. A span held by a span is fitted again by its own span after.
+ * Lays out a span's children and fits them into what is left of its budget, from its clock at mix
+ * time `from`, default now. Only what is still to come moves: a playing child keeps its place and
+ * may change rate, a pending one is placed. A span held by a span is fitted again by its own span
+ * after.
  */
-export declare function refit<I, O>(mix: Mixer<I, O>, span: Voice<I, O>): void;
+export declare function refit<I, O>(mix: Mixer<I, O>, span: Voice<I, O>, from?: number): void;
 /** Whether a span whose last child just left at mix time `at` stays, its budget not yet out. */
 export declare function lingers<I, O>(span: Voice<I, O>, at: number): boolean;
 /** Lets the spans that are empty and out of budget leave, at the moment their budget ran out. */

package/dist/spans.js

@@ -46,11 +46,11 @@ export function checkChild(spec, child) {
     else if (!Number.isFinite(child.span))
         throw new Error('blits: a span cannot fit a voice that never ends');
 }
-/** A span's own clock at the mix's now, from 0 while it has not started. */
-function clockOf(mix, span) {
-    if (Number.isNaN(mix.now))
+/** A span's own clock at mix time `at`, from 0 while it has not started. */
+function clockOf(span, at) {
+    if (Number.isNaN(at))
         return 0;
-    const t = ownerReading(span, mix.now);
+    const t = ownerReading(span, at);
     return Number.isFinite(t) ? Math.max(0, t) : 0;
 }
 /** What a child's own clock reads at its span's `local`, 0 while it waits. */
@@ -63,15 +63,16 @@ function leftOf(child, local) {
     return Math.max(0, length - elapsedIn(child, local));
 }
 /**
- * Lays out a span's children and fits them into what is left of its budget, from its clock now.
- * Only what is still to come moves: a playing child keeps its place and may change rate, a
- * pending one is placed. A span held by a span is fitted again by its own span after.
+ * Lays out a span's children and fits them into what is left of its budget, from its clock at mix
+ * time `from`, default now. Only what is still to come moves: a playing child keeps its place and
+ * may change rate, a pending one is placed. A span held by a span is fitted again by its own span
+ * after.
  */
-export function refit(mix, span) {
+export function refit(mix, span, from = mix.now) {
     const fitting = span.fitting;
     if (mix.projecting || span.state === 'done')
         return;
-    const local = clockOf(mix, span);
+    const local = clockOf(span, from);
     const kids = (span.holding?.children ?? []).filter((c) => c.state !== 'done' && c.state !== 'frozen' && c.state !== 'fading' && leftOf(c, local) > 0);
     const claims = kids.map((c) => {
         const s = c.spec;
@@ -143,7 +144,7 @@ export function refit(mix, span) {
         fitting.end = end;
         noted(mix, span);
         if (span.owner?.fitting)
-            refit(mix, span.owner);
+            refit(mix, span.owner, from);
     }
 }
 /** Whether a span whose last child just left at mix time `at` stays, its budget not yet out. */

package/dist/strays.js

@@ -64,14 +64,18 @@ export function motionOwner(mix) {
         revive(id, subject) {
             const m = mix.deref();
             if (m === undefined)
-                return;
+                return Number.NaN;
             m.stir();
             const v = cuedById(m, id);
             if (v === undefined)
-                return;
+                return Number.NaN;
             if (v.motion !== undefined && v.named !== null && !v.named.has(subject))
                 stray(m, v.motion, subject);
+            if (v.parted?.has(subject) !== true)
+                return Number.NaN;
             unpart(m, v, subject);
+            // Its record is gone until it is next read, so its stagger is asked here as it will be there.
+            return timeIn(m, v, v.spec.stagger ? v.spec.stagger(subject) : 0);
         },
     };
 }
@@ -98,11 +102,15 @@ export function cuedById(mix, id) {
  * 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 timeIn(mix, voice, held.delay);
+}
+/** The voice time at the latest frame of a subject staggered by `delay`; NaN before it has any. */
+function timeIn(mix, voice, delay) {
+    if (Number.isNaN(mix.now) || voice.state === 'pending')
+        return Number.NaN;
+    const t = voice.elapsedAt(mix.now) - delay;
     return t < 0 ? Number.NaN : t;
 }

package/dist/transport.js

@@ -7,7 +7,7 @@ import { pin } from './place.js';
 import { projectAll } from './project.js';
 import { scoredDrop, scoredJoin } from './scored.js';
 import { seek } from './seek.js';
-import { record, replay, tapeOf } from './tape.js';
+import { hostAt, record, replay, tapeOf } from './tape.js';
 /** How far the tape's reach moves before it is pruned again, ms of mix time. */
 const TAPE_STEP_MS = 1000;
 /** Whether a change made in frame `seq` falls inside `cut`; `early` for one made before the frame was read. */
@@ -216,7 +216,9 @@ export class Transport {
         // In steps: the tape shifts every entry it keeps to let go of the oldest, and one a second
         // behind reach is never played again.
         if (this.tape !== undefined && history !== undefined && !(reach - this.taped < TAPE_STEP_MS)) {
-            this.tape.prune(reach);
+            const from = hostAt(this, reach);
+            if (from < Number.POSITIVE_INFINITY)
+                this.tape.prune(from);
             this.taped = reach;
         }
         if (history !== undefined && this.dropped.length > 0)

package/dist/types/mix.d.ts

@@ -192,8 +192,9 @@ export interface Mix<I, O, H = unknown> {
      */
     pull(subjects: Iterable<I>, into: Columns<O>): void;
     /**
-     * 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
+     * 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`
      * 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.
@@ -238,6 +239,8 @@ export interface Mix<I, O, H = unknown> {
      * sync. Host time at the mix's rate, less what `rebase` took out and `seek` moved.
      */
     readonly now: number;
+    /** The host's timestamp at the last sync; NaN before the first. */
+    readonly timestamp: number;
     /** The tape `history.tape` made, undefined without one. */
     readonly tape: Tape | undefined;
     /**
@@ -321,7 +324,7 @@ export interface Mix<I, O, H = unknown> {
      * 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;
+    book<E = unknown>(opts: BookOptions<E, I>): Booker;
 }
 /**
  * The implementation behind a mix: which patch forms it runs, and how it makes one.

package/dist/types/patch.d.ts

@@ -39,12 +39,16 @@ export interface Setting<S = void, H = unknown> {
      * The gap this subject is catching up by: milliseconds since it last advanced, which is the gap
      * since the previous sync only for a subject sampled every frame. Infinity under reduced motion;
      * no more than `maxDt` where the mix sets one. Inside a `step` under `stepMs`, it is `stepMs`, and
-     * `timestamp` is the end of that interval.
+     * `timestamp` is the end of that interval. A lane samples a subject for one frame after its last
+     * probe. A read by `project` is one sample, so its gap is not the gap a frame of play has.
      */
     dt: number;
-    /** Milliseconds this voice has been playing, rate applied. */
+    /**
+     * Milliseconds this voice has been playing, rate applied. Below 0 only for a voice with no end
+     * cued backward, which plays into the passes before its first.
+     */
     elapsed: number;
-    /** Which pass this is, 0 first. */
+    /** Which pass this is, 0 first; below 0 where `elapsed` is. */
     pass: number;
     /** This voice's weight for this subject this frame, after fades, signals and any locus. */
     weight: number;

package/dist/types/place.d.ts

@@ -55,7 +55,10 @@ export type Anchor = {
  * Where a voice sits on the mix clock: at most one of `start` and `in`, and at most one of `out`
  * and `end`, each a timestamp on the host's clock or an anchor to another voice. A voice whose
  * anchor has no answer yet waits pending; one whose anchored mark is already past starts partway
- * through, as playback does from the middle of a region.
+ * through, as playback does from the middle of a region. A fade out begins no earlier than the
+ * voice starts: an `end` that leaves less room than `fade.out` shortens the fade to fit, and one
+ * before the start makes the voice an instant, which starts and ends at its start and shows
+ * nothing.
  *
  * @category score
  */
@@ -100,7 +103,7 @@ export interface Hit<E = unknown> {
  *
  * @category score
  */
-export interface BookedHit<E = unknown> {
+export interface BookedHit<E = unknown, I = unknown> {
     /** On the host's clock. */
     timestamp: number;
     voice: number;
@@ -112,13 +115,15 @@ export interface BookedHit<E = unknown> {
     score: string | undefined;
     name: string | undefined;
     tags: readonly string[];
+    /** The subjects its voice names with `subjects`; undefined for a voice that names none. */
+    subjects: readonly I[] | undefined;
 }
 /**
  * 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> {
+export interface BookOptions<E = unknown, I = 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
@@ -133,13 +138,13 @@ export interface BookOptions<E = unknown> {
     /**
      * 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, which is then taken at the
-     * clock's now; it is 0 for one booked ahead. Return a `stop` to hear about a booking whose time moved by
+     * clock's now; it is 0 for one booked ahead. Return a `cancel` 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;
+    take(item: Marked | BookedHit<E, I>, when: number, lateBy: number): {
+        cancel(): void;
     } | undefined;
     /** Book only the voices, and announced marks, carrying this tag. */
     tag?: string;
@@ -152,6 +157,11 @@ export interface BookOptions<E = unknown> {
  * @category score
  */
 export interface Booker {
-    /** Stops every booking still ahead, and books nothing more. */
-    stop(): void;
+    /** Cancels every booking still ahead, and books nothing more. */
+    cancel(): void;
+    /**
+     * Where host `timestamp` falls on the outside clock, by the offset as the last sync left it;
+     * NaN before the first sync.
+     */
+    at(timestamp: number): number;
 }

package/dist/types/voice.d.ts

@@ -61,15 +61,30 @@ export interface VoiceSpec<I, O, H = unknown> extends SpanHints {
     subjects?: readonly I[];
     /**
      * When the voice starts, in ms on the host's clock, the one it passes `sync`: a rAF timestamp and
-     * `performance.now()` share an origin, `Date.now()` does not. Default: the next sync.
+     * `performance.now()` share an origin, `Date.now()` does not. Default: the time the mix last
+     * synced to, and 0 for a voice cued before the first sync, which that sync finds already as far
+     * in as its timestamp.
      */
     start?: number;
-    /** Playback rate. 1 is real time; 0 freezes. */
+    /**
+     * Playback rate. 1 is real time; 0 freezes; below 0 plays backward, to end where the voice
+     * starts as a voice playing forward ends where its last pass does: `played` resolves, and it
+     * leaves over `fade.out` or, freezing before, holds its first frame.
+     */
     rate?: number;
+    /**
+     * Where in itself the voice starts, in voice ms, as `seek` on its handle sets. Default 0, or
+     * for a voice cued backward its end: `duration` times its passes. A voice with no end cued
+     * backward (a loop for good, or a patch with no duration) starts at 0 and has no first pass
+     * either: it plays into the pass before, `setting.pass` and `setting.elapsed` below 0, for
+     * every subject from the voice's start whatever its stagger. A motion's stretches begin at 0,
+     * so one cued backward with no `seek` has ended as it starts.
+     */
+    seek?: number;
     /**
      * 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.
+     * set, at once where none is — unless it freezes after. Default: true.
      */
     loop?: boolean | number;
     /**
@@ -249,7 +264,8 @@ export interface Handle<I = unknown> {
     weight: number;
     /**
      * Playback rate now. Setting it changes speed at once; `ramp` eases into a new one. On a voice
-     * still pending, a rate above 0 applies from the voice's start, which stays where it is.
+     * still pending, a rate or a ramp applies from the voice's start, which stays where it is: at
+     * rate 0 it starts on time and holds its first frame.
      */
     rate: number;
     /**
@@ -265,6 +281,8 @@ export interface Handle<I = unknown> {
      * it was. Answers how sure the state now is: `exact` for a voice with none, or rebuilt under
      * `stepMs` with no `maxDt`; `stepped` where it was caught up in one step or holds signal state;
      * `held` where it was kept, or depends on host fields or an input weight the rebuild cannot know.
+     * A voice still pending starts on time, already at `elapsed`, and one that freezes before shows
+     * that frame while it waits.
      */
     seek(elapsed: number, opts?: SeekOptions): Doubt;
     /**

package/dist/unpage.d.ts

@@ -5,4 +5,4 @@ import type { Transport } from './transport.js';
  */
 export declare function cover(transport: Transport, t: number): boolean;
 /** 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, unpaged: boolean): void;
+export declare function cut(transport: Transport, seq: number): void;

package/dist/unpage.js

@@ -30,12 +30,11 @@ export function cover(transport, t) {
     return true;
 }
 /** 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, unpaged) {
+export function cut(transport, seq) {
     const pager = transport.pager;
     if (pager === null)
         return;
-    if (unpaged)
-        pager.store.cut(seq);
+    pager.store.cut(seq);
     const loaded = pager.loaded;
     if (loaded !== null)
         loaded.records = loaded.records.filter((r) => r.seq <= seq);

package/dist/voice.d.ts

@@ -127,6 +127,8 @@ export interface Ramp {
     over: number;
     rest: boolean;
     deadline?: number;
+    /** Begun where the voice ran back to its start, whose first frame it holds through the fade. */
+    back?: boolean;
 }
 /**
  * A climb back from a fade out that was turned around: from `from`, the place along the fade's
@@ -224,6 +226,12 @@ export declare class Voice<I, O> {
     readonly span: number;
     /** The state behind a motion patch, undefined for any other. */
     readonly motion: Motions<I> | undefined;
+    /**
+     * Whether it has no first pass: cued backward with no end to start from, it plays from 0 into
+     * the pass before, so no time on its clock is before its start. Never a motion, whose stretches
+     * begin at 0.
+     */
+    readonly beginless: boolean;
     /** Its `freeze`, for a patch it applies to: motion keeps its target already. */
     readonly freezesBefore: boolean;
     readonly freezesAfter: boolean;
@@ -244,6 +252,8 @@ export declare class Voice<I, O> {
     seen: number;
     /** The longest stagger of any subject seen, so a finite loop waits for the last of them. */
     latest: number;
+    /** The least stagger of any subject seen, 0 or below, which a voice running back ends at. */
+    soonest: number;
     restedCount: number;
     /** The mix time it was cued at; -Infinity before the first sync. */
     cuedAt: number;
@@ -253,6 +263,10 @@ export declare class Voice<I, O> {
     doneAt: number;
     /** The frame its leaving was decided in, which a seek or read back partitions by. */
     doneSeq: number;
+    /** The mix time of that frame, later than `doneAt` for a leaving put behind now. */
+    decidedAt: number;
+    /** The latest mix time a seek or read back to finds it still playing. */
+    get reachedTo(): number;
     /** Under `history`, its controls after each change, oldest first. */
     log: Controls[] | null;
     /** Under `history`, its controls as `cue` left them, which a voice parked by a seek takes back. */
@@ -361,6 +375,44 @@ export declare class Voice<I, O> {
     elapsedAt(now: number): number;
     /** The mix time its clock reads `elapsed`, inverting `elapsedAt`; Infinity where it never will. */
     timeAt(elapsed: number): number;
+    /**
+     * Whether its clock runs back by its controls: at a rate below 0, or on a ramp between rates
+     * neither of which is above it. A ramp through 0 says neither way until it has turned.
+     */
+    get backs(): boolean;
+    /** Whether its ramp takes its rate through 0, which turns its clock around partway. */
+    get turns(): boolean;
+    /**
+     * The mix time its passes run out by its controls now: its last pass's end running forward, its
+     * first pass's start running back. Infinity where they never do, and while a ramp has yet to
+     * turn it around.
+     */
+    endsAt(): number;
+    /**
+     * The mix time its clock ran back to `elapsed` by `now`, by its controls now: where a subject
+     * `elapsed` into it reached its start. NaN where it has not, and for a voice an owner holds.
+     */
+    ranBackTo(elapsed: number, now: number): number;
+    /** Whether it has yet to start at mix time `now`: pending, or fading out from before its start. */
+    unstarted(now: number): boolean;
+    /**
+     * A subject's voice time at mix time `now`, `delay` into the voice, before its freezes apply. A
+     * voice yet to start reads where it will: its clock is anchored there, and read at any time
+     * before would have a voice sought ahead, or running back, play before its start.
+     */
+    rawAt(now: number, delay: number): number;
+    /**
+     * Whether a subject at `raw` is before its start at mix time `now`: it shows nothing, or its
+     * first frame frozen.
+     */
+    before(raw: number, now: number): boolean;
+    /**
+     * Whether a subject before its start shows its first frame: the voice freezes before, or is
+     * fading out from where it ran back to its start, as one fading from its end shows its last.
+     */
+    get holdsFirst(): boolean;
+    /** A subject's voice time at `raw` once the voice's freezes apply; NaN where it shows nothing. */
+    shownAt(raw: number): number;
     /** Records this voice's controls as they stand, from mix time `at` in frame `seq`. */
     note(at: number, seq: number, sync?: boolean): void;
     /**