@msb235/blits 0.10.0 → 0.12.0

package/dist/types/voice.d.ts

@@ -3,7 +3,7 @@ import type { Motion, Value } from '../motion.js';
 import type { Described } from './history.js';
 import type { Doubt } from './mix.js';
 import type { Easing, Patch, Signal } from './patch.js';
-import type { Hit, Placement } from './place.js';
+import type { Anchor, Hit, Placement } from './place.js';
 /**
  * A voice's own ramps in and out, in ms, and the curve both take.
  *
@@ -31,6 +31,15 @@ export interface SpanHints {
     ballast?: boolean;
     /** How hard its own length holds against the span's budget. Default `weak`. */
     priority?: Strength;
+    /**
+     * The soonest it may start: a time on the span's clock, or an anchor. The fit never places it
+     * sooner, and the children after it are laid out from where it starts. One already past when it is
+     * cued places it there, partway through. One whose anchor has no answer yet waits, and under `queue` or
+     * `stagger` so does every child after it.
+     */
+    earliest?: number | Anchor;
+    /** Where it plays among the span's children still to start: lower first, ties as cued. Default 0. */
+    rank?: number;
 }
 /**
  * What `cue` takes: a patch, and the clock, weight and reach it plays with.
@@ -81,10 +90,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 +150,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 +167,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 +194,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 +224,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 +360,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 +370,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/types/watch.d.ts

@@ -0,0 +1,126 @@
+import type { HistoryOptions } from './history.js';
+import type { Mix } from './mix.js';
+import type { Sent } from './patch.js';
+import type { Handle } from './voice.js';
+/**
+ * Every mix made on the page, for a debugger: shared by every copy of blits loaded, so a mix one
+ * copy made is listed by another. `watched()` returns it.
+ *
+ * @category mix
+ */
+export interface Registry {
+    /** The mixes still alive, in the order they were made. */
+    entries(): Watched[];
+    /** Hears each mix made, and each one collected, by its entry's `id`. Returns an unsubscribe. */
+    on(fn: (change: {
+        kind: 'add';
+        entry: Watched;
+    } | {
+        kind: 'gone';
+        id: number;
+    }) => void): () => void;
+    /**
+     * The history a mix made from now on keeps when its options name none and it is on no
+     * transport, so a debugger present before the page's mixes can scrub them. Undefined by default.
+     */
+    history: HistoryOptions | undefined;
+}
+/**
+ * One mix as a debugger sees it. Built by the copy of blits that made the mix, so a debugger
+ * reads mixes from other releases through it alike.
+ *
+ * @category mix
+ */
+export interface Watched<I = unknown, O = unknown> {
+    /** Numbers mixes in the order they were made, across copies; what a `gone` change names. */
+    readonly id: number;
+    /** The release of the copy that made it. */
+    readonly release: string;
+    readonly name: string | undefined;
+    readonly mix: Mix<I, O>;
+    /** What history it keeps, and whether the registry's `history` gave it; undefined for none. */
+    readonly history: {
+        readonly ms: number;
+        readonly tape: boolean;
+        readonly added: boolean;
+    } | undefined;
+    /** The earliest mix time `read` reaches back to: `mix.now` without history. */
+    readonly reach: number;
+    /** The kit's channel names, in kit order. */
+    readonly channels: readonly string[];
+    /** What a voice was cued with that its handle does not carry; undefined for a handle not on this mix. */
+    voice(handle: Handle<I>): {
+        readonly name: string | undefined;
+        readonly tags: readonly string[];
+    } | undefined;
+    /** What to call a subject: the mix's `labelOf`, else a guess from the subject itself. */
+    label(subject: I): string;
+    /**
+     * Calls `fn` with each frame the host read, once the next one begins. While anyone watches, the
+     * mix records what `probe`, `pull` and `drain` give the host, and nothing else changes. Returns
+     * a function that stops watching.
+     */
+    watch(fn: (frame: WatchedFrame<I, O>) => void): () => void;
+    /** The subjects its voices still playing name, and those the host read in the last two frames while watched. */
+    subjects(): I[];
+    /**
+     * One subject's pose at mix time `at`, default now, read through `project`, which moves nothing:
+     * never a probe. A time behind now needs history that reaches it.
+     */
+    read(subject: I, at?: number): O;
+    /** Takes the clock from the host: see `Hold`. Throws while another hold has it. */
+    hold(): Hold;
+}
+/**
+ * What the host read in one frame.
+ *
+ * @category mix
+ */
+export interface WatchedFrame<I, O> {
+    seq: number;
+    /** The mix clock the frame stood at. */
+    now: number;
+    /** The host's timestamp at the frame's sync. */
+    timestamp: number;
+    /** Each probe, in order, with a copy of the pose it returned. */
+    probed: {
+        subject: I;
+        pose: O;
+    }[];
+    /** Each pull, with copies of the columns it wrote. */
+    pulled: {
+        subjects: I[];
+        columns: Record<string, Float64Array>;
+    }[];
+    /** What `drain` handed the host. */
+    sent: Sent<I, unknown>[];
+    voices: Handle<I>[];
+}
+/**
+ * A mix's clock in a debugger's hands, and every mix's on the same transport. The host's `sync`
+ * still begins each frame, but the frame's gap counts at `rate`, so the mix moves at `rate` times
+ * its own rate; the host's own clock calls (`seek`, `rate`, `ramp`, `rebase`) wait for `free`.
+ * Nothing done through a hold is recorded on the tape or in the mix's rate, and each change wakes
+ * a host sleeping on `inert`.
+ *
+ * @category mix
+ */
+export interface Hold {
+    readonly mixes: Mix<unknown, unknown>[];
+    /** The mix clock. */
+    readonly now: number;
+    /** The earliest mix time `seek` reaches: `now` without history and a tape. */
+    readonly reach: number;
+    /** How much of each of the host's frames the held mix plays; 0 pauses it. Starts at 0. */
+    rate: number;
+    /** Moves the mixes to mix time `to`, back within `reach` or ahead. */
+    seek(to: number): void;
+    /** Plays the mixes `ms` of mix time further on, in one frame. */
+    step(ms: number): void;
+    /**
+     * Gives the clock back: the host's next sync carries on from where the hold left the mix, and
+     * its clock calls made meanwhile are made, in order. A call made while the tape holds later
+     * calls acts on the mix but is not recorded, so those calls still play.
+     */
+    free(): void;
+}

package/dist/types/watch.js

@@ -0,0 +1 @@
+export {};

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+export type * from './types/arc.js';
 export type * from './types/channel.js';
 export type * from './types/history.js';
 export type * from './types/mix.js';
@@ -5,3 +6,4 @@ export type * from './types/patch.js';
 export type * from './types/place.js';
 export type * from './types/transport.js';
 export type * from './types/voice.js';
+export type * from './types/watch.js';

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);

package/dist/voice.d.ts

@@ -1,3 +1,4 @@
+import type { Arc } from './arcs.js';
 import type { Blend } from './blend.js';
 import { type Clock } from './clock.js';
 import { type Curve } from './easing.js';
@@ -7,12 +8,14 @@ import { Named } from './named.js';
 import type { Past } from './origin.js';
 import { Holding } from './owner.js';
 import { type Built, intosOf, type Scratch } from './patch.js';
+import type { Stamp } from './restored.js';
 import type { Fitting } from './spans.js';
 import { Store } from './store.js';
 import type { Anchor, Channel, FadeSpec, Handle, Patch, Setting, VoiceSpec } from './types.js';
 /**
  * A subject's record as it left a voice, faded out of it or dropped: the mix time and frame it
- * left at, and `sync` where the frame's sync made it, before the frame was read.
+ * left at, and `sync` where it shows in its own frame: left in the frame's sync, or before anything
+ * read the mix that frame.
  */
 export interface Left<I> {
     subject: I;
@@ -20,8 +23,55 @@ export interface Left<I> {
     seq: number;
     sync: boolean;
     held: Subject<unknown>;
+    /**
+     * The voice's fade of the subject as it stood on leaving, which a seek or read back to before
+     * puts back: its ramp out, while running, or its having faded out.
+     */
+    ramp: Parting | null;
+    parted: Parted | null;
+}
+/** A subject's ramp out of one voice: when it began, how long it runs, and the frame it was asked in. */
+export interface Parting {
+    at: number;
+    over: number;
+    seq: number;
+}
+export interface Parted {
+    at: number;
+    seq: number;
+    ramp: Parting | undefined;
 }
 export declare const none: readonly string[];
+/**
+ * What a copy of a record keeps for the seeks that put a record back from it: the copy's state
+ * stepped on to `ticks`, as it stood near `at`, a moment one of them sought.
+ */
+export interface Ahead<S> {
+    /** The record the last seek put back, and the moment it sought, until that record steps. */
+    put: Subject<S> | null;
+    sought: number;
+    /** The `since` of the record put back, which the steps in `state` were counted from. */
+    since: number;
+    at: number;
+    ticks: number;
+    /** Undefined until a record has stepped on from the copy. */
+    state: S | undefined;
+    /**
+     * The state the record a seek replaced had stepped on to from the copy, at `leftTicks`; undefined
+     * until one had.
+     */
+    leftTicks: number;
+    left: S | undefined;
+}
+/** A copy of a record kept under `history`, by the mix time and frame it was taken at. */
+export interface Snap<S> {
+    at: number;
+    seq: number;
+    held: Subject<S>;
+    ahead?: Ahead<S>;
+    /** Set where another record's list holds it too, so a seek cutting it from one lets go of it. */
+    shared?: true;
+}
 /** Everything one voice holds for one subject, chained through the next voice that reaches it. */
 export interface Subject<S> {
     /** The voice's `target` answer, fixed on first sight. */
@@ -56,6 +106,8 @@ export interface Subject<S> {
     seeks: number;
     /** The voice's `rebuilds` when its state was last made, so a seek's rebuild reaches it once. */
     rebuilt: number;
+    /** Its kept signal state was stepped on in one go from a copy history kept, by a seek. */
+    copied: boolean;
     /** Stop 0 for a `from: 'current'` voice, taken the first frame this subject is seen. */
     base?: Record<string, unknown>;
     /** The pose's velocity per channel at that moment, units per ms, so the first segment leaves at it. */
@@ -65,11 +117,7 @@ export interface Subject<S> {
     /** Kept state a history store gave back, which each owner takes in turn on its first keep. */
     unkept?: unknown[];
     /** Under `history`, copies of this record by the mix time they were taken, oldest first. */
-    snaps?: {
-        at: number;
-        seq: number;
-        held: Subject<S>;
-    }[];
+    snaps?: Snap<S>[];
     /** In a projection: where this record started from, and whether nothing known could be. */
     from?: number;
     unknown?: boolean;
@@ -100,6 +148,8 @@ export interface Subject<S> {
     /** A motion voice's number for this subject in its patch, good while `freed` is the patch's own. */
     run: number;
     freed: number;
+    /** In a voice's store once a seek has gone back, the stamp of the seek it was last put back or written at. */
+    restored: Stamp | null;
 }
 /** A voice's clock, weight and fade from one mix time on, kept under `history`. */
 export interface Controls extends Clock {
@@ -116,6 +166,8 @@ export interface Controls extends Clock {
     outOver: number;
     outSet: boolean;
     rebuilds: number;
+    /** An arc's hold. */
+    hold: number;
     /** How many of the voice's past clocks it had then. */
     past: number;
     /** Shows in its own frame: made by a sync, or before anything read the mix that frame. */
@@ -200,19 +252,17 @@ export declare class Voice<I, O> {
     rebuilds: number;
     /** Whether its span's last fit jumped it to its end, which leaves it no time in that fit. */
     skipped: boolean;
+    /** What its `earliest` answered at its span's last fit, span ms; NaN while unknown or absent. */
+    floorSeen: number;
     /** Whether its patch has kept state on a record through `setting.keep`, which makes it stateful. */
     keeping: boolean;
     /** Subjects fading out of this voice alone, by the ramp each started; null while none are. */
-    parts: Map<I, {
-        at: number;
-        over: number;
-        seq: number;
-    }> | null;
-    /** Subjects faded out of this voice, by the mix time and frame each left at; null while none have. */
-    parted: Map<I, {
-        at: number;
-        seq: number;
-    }> | null;
+    parts: Map<I, Parting> | null;
+    /**
+     * Subjects faded out of this voice, by the mix time and frame each left at, and the ramp that
+     * took it out, which a seek or a read back into it puts back; null while none have.
+     */
+    parted: Map<I, Parted> | null;
     /**
      * Under history, the records of subjects that left this voice, by the mix time and frame each
      * left at, while a seek or a read back may reach them; null while none have.
@@ -237,6 +287,8 @@ export declare class Voice<I, O> {
     readonly freezesAfter: boolean;
     /** The mix time it first showed: when it was cued, or the first sync after. */
     opened: number;
+    /** Whether no delta its patch's `at` returned has been checked against `writes` yet. */
+    unchecked: boolean;
     /** Which of its entries in the mix's due queue is current; older ones are skipped when popped. */
     dueToken: number;
     /**
@@ -255,6 +307,8 @@ export declare class Voice<I, O> {
     /** The least stagger of any subject seen, 0 or below, which a voice running back ends at. */
     soonest: number;
     restedCount: number;
+    /** Whether a seek back to before its cue has it out of the mix, until the mix plays the cue again. */
+    parked: boolean;
     /** The mix time it was cued at; -Infinity before the first sync. */
     cuedAt: number;
     /** The frame it was cued in. */
@@ -294,12 +348,19 @@ export declare class Voice<I, O> {
         of: Blend<I, O>;
         i: number;
     } | null;
+    /**
+     * Copies the latest seek back cut from its records' lists that no other list holds, for the
+     * copies its probes keep next to be written over; null until a seek cuts one.
+     */
+    spares: Snap<unknown>[] | null;
     /** The one record of every subject it does not reach. */
     unreached: Subject<unknown> | null;
     /** By subject number, a bit set where `unreached` stands for the subject; null until one is. */
     unreachedBits: Uint32Array | null;
     /** Whether one record stands for every subject: see `shares` in `everyone.ts`. */
     sharing: boolean;
+    /** The frames it has played sharing it. */
+    shared: number;
     /** That record, null until a chain first asks and once the voice shares no more. */
     everyone: Subject<unknown> | null;
     /** While sharing, by subject number: a bit where a chain has asked about the subject. */
@@ -320,6 +381,12 @@ export declare class Voice<I, O> {
     holding: Holding<Voice<I, O>> | null;
     /** For a span, its budget and how its children were last fitted; null for any other voice. */
     fitting: Fitting | null;
+    /** For an arc, how its parts are laid out; null for any other voice. */
+    arc: Arc | null;
+    /** For an arc, how long its hold lasts, ms on its clock: Infinity while open. */
+    hold: number;
+    /** For a voice an arc holds, which part it plays: 0 enter, 1 active, 2 exit; -1 for any other. */
+    part: number;
     /**
      * `done` and `played`, made when first asked for, already settled if the voice is: most hosts
      * never await either, and a mix may hold tens of thousands of voices.
@@ -411,6 +478,11 @@ export declare class Voice<I, O> {
      * fading out from where it ran back to its start, as one fading from its end shows its last.
      */
     get holdsFirst(): boolean;
+    /**
+     * Whether a subject past the end of its passes shows nothing: its clock runs back, so it has yet
+     * to reach them, and it does not freeze after.
+     */
+    get hidesPast(): 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`. */
@@ -426,3 +498,8 @@ export declare class Voice<I, O> {
     /** Moves the anchor to `now`, carrying what is left of a ramp. */
     rebase(now: number): void;
 }
+/**
+ * Warns, once a patch outside production, of a key the first delta `voice` read returns outside its
+ * patch's `writes`, which the mix drops.
+ */
+export declare function checkWrites<I, O>(voice: Voice<I, O>, delta: object | null): void;