@msb235/blits 0.11.0 → 0.12.1

package/dist/transport.js

@@ -8,6 +8,7 @@ import { projectAll } from './project.js';
 import { scoredDrop, scoredJoin } from './scored.js';
 import { seek } from './seek.js';
 import { hostAt, record, replay, tapeOf } from './tape.js';
+import { gave, historyFor } from './watch.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. */
@@ -337,5 +338,9 @@ export function announce(transport, name, opts, slot, mix) {
  * @category mix
  */
 export function transport(opts = {}) {
-    return new Transport(opts.history, true);
+    const { history, added } = historyFor(opts);
+    const t = new Transport(history, true);
+    if (added)
+        gave(t);
+    return t;
 }

package/dist/types/arc.d.ts

@@ -0,0 +1,55 @@
+import type { Handle, OwnerSpec, VoiceSpec } from './voice.js';
+/**
+ * One voice of an arc's part: a voice's spec, less what the arc sets for it. The arc places it,
+ * fades it across each boundary by `blend`, and holds its first and last frames for the blend.
+ *
+ * @category score
+ */
+export interface ArcVoice<I, O, H = unknown> extends Omit<VoiceSpec<I, O, H>, 'owner' | 'start' | 'anchor' | 'freeze' | 'fade' | 'faster' | 'slower' | 'overlap' | 'ballast' | 'priority' | 'earliest' | 'rank'> {
+    /**
+     * How long the part holds the arc, ms on the arc's clock. Default: the patch's duration times
+     * its passes, which leaves out a `stagger`, so a part whose last subject lands later says so here.
+     */
+    duration?: number;
+}
+/**
+ * One part of an arc: a voice, or several layered together that play as one and last as long as
+ * the longest.
+ *
+ * @category score
+ */
+export type ArcPart<I, O, H = unknown> = ArcVoice<I, O, H> | readonly ArcVoice<I, O, H>[];
+/**
+ * What `arc` takes: an owner over three parts that hand over in order, `enter`, `active` and
+ * `exit`, any of which may be left out.
+ *
+ * @category score
+ */
+export interface ArcSpec<I, O, H = unknown> extends Omit<OwnerSpec<I, H>, 'freeze'> {
+    /** What plays as it arrives. Its end is the arc's `in` mark. */
+    enter?: ArcPart<I, O, H>;
+    /** What plays between the two, over the hold. Its end is the arc's `coast` mark. */
+    active?: ArcPart<I, O, H>;
+    /** What plays as it leaves. Its start is the arc's `out` mark, and its end the arc's `end`. */
+    exit?: ArcPart<I, O, H>;
+    /**
+     * How long `active` plays, ms on the arc's clock, looping for it unless its `loop` says how many
+     * passes; or `'open'`, until `release`. Default: `active`'s own length, held open where it loops
+     * for good, and 0 with no `active`.
+     */
+    hold?: number | 'open';
+    /** A crossfade across each boundary, ms, half before it and half after. Default 0. */
+    blend?: number;
+}
+/**
+ * An arc's handle: an owner's, and the release of its hold. `fade` takes it out with no exit.
+ *
+ * @category score
+ */
+export interface ArcHandle<I = unknown> extends Handle<I> {
+    /**
+     * Ends the hold now and plays the exit, its blend starting here; where the enter is still
+     * playing, the exit follows it. Nothing once the exit has begun or the arc is fading.
+     */
+    release(): void;
+}

package/dist/types/arc.js

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

package/dist/types/mix.d.ts

@@ -1,3 +1,4 @@
+import type { ArcHandle, ArcSpec } from './arc.js';
 import type { Kit } from './channel.js';
 import type { HistoryOptions, Tape } from './history.js';
 import type { Patch, Sent, Signal } from './patch.js';
@@ -52,6 +53,11 @@ export interface MixOptions<H = unknown> {
      * string or number subject is its own key; with a store, an object subject needs this.
      */
     keyOf?(subject: never): string | number;
+    /**
+     * What a debugger calls a subject (see `watched`); where it gives nothing, the subject's own
+     * `name` or `id`, a DOM element's tag, id and classes, or its class and a number.
+     */
+    labelOf?(subject: never): string | undefined;
     /**
      * 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; what a host reads is the same either
@@ -146,6 +152,18 @@ export interface Mix<I, O, H = unknown> {
      * turns it once it plays.
      */
     span(spec: SpanSpec<I, H>): SpanHandle<I>;
+    /**
+     * Cues an arc: an owner holding three parts that hand over in order on its clock, `enter`, then
+     * `active` for the `hold`, then `exit`, each a voice or several layered. Its marks are its own:
+     * `start` as the enter begins, `in` as it ends, `coast` as the hold ends and `out` as the exit
+     * begins, which are one time, and `end` as the exit ends, where it leaves and `done` resolves.
+     * While the hold is open, `coast`, `out` and `end` are unknown until `release` fixes them. Each
+     * part shows its first and last frames through the blends either side of it, and a part left
+     * out leaves its time to the one before it. Its `fade` takes it out with no exit. An arc with a
+     * finite hold may sit in a span. Throws for a `rate` below 0, a hold below 0, and an `enter` or
+     * `exit` that never ends.
+     */
+    arc(spec: ArcSpec<I, O, H>): ArcHandle<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
@@ -295,6 +313,12 @@ export interface Mix<I, O, H = unknown> {
      * A frame loop sleeping on `inert` subscribes here to wake.
      */
     onWake(fn: () => void): () => void;
+    /**
+     * Takes the mix off the list debuggers read (see `watched`), for a host done with it, where it
+     * would otherwise stay until collected. Stops every watcher, and frees a hold no other listed mix
+     * on its transport shares. It still plays if synced.
+     */
+    close(): void;
     /** Fades every voice out: over `over` when given, over each voice's own `fade.out` otherwise. */
     mute(opts?: {
         over?: number;

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.

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/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,6 +8,7 @@ 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';
@@ -54,6 +56,21 @@ export interface Ahead<S> {
     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> {
@@ -100,12 +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>;
-        ahead?: Ahead<S>;
-    }[];
+    snaps?: Snap<S>[];
     /** In a projection: where this record started from, and whether nothing known could be. */
     from?: number;
     unknown?: boolean;
@@ -136,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 {
@@ -152,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. */
@@ -236,6 +252,8 @@ 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. */
@@ -330,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. */
@@ -356,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.

package/dist/voice.js

@@ -143,6 +143,8 @@ export class Voice {
     rebuilds = 0;
     /** Whether its span's last fit jumped it to its end, which leaves it no time in that fit. */
     skipped = false;
+    /** What its `earliest` answered at its span's last fit, span ms; NaN while unknown or absent. */
+    floorSeen = Number.NaN;
     /** Whether its patch has kept state on a record through `setting.keep`, which makes it stateful. */
     keeping = false;
     /** Subjects fading out of this voice alone, by the ramp each started; null while none are. */
@@ -236,12 +238,19 @@ export class Voice {
     ownKept = null;
     /** The blend it is a member of, and which. */
     blend = 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 = null;
     /** The one record of every subject it does not reach. */
     unreached = null;
     /** By subject number, a bit set where `unreached` stands for the subject; null until one is. */
     unreachedBits = null;
     /** Whether one record stands for every subject: see `shares` in `everyone.ts`. */
     sharing = false;
+    /** The frames it has played sharing it. */
+    shared = 0;
     /** That record, null until a chain first asks and once the voice shares no more. */
     everyone = null;
     /** While sharing, by subject number: a bit where a chain has asked about the subject. */
@@ -262,6 +271,12 @@ export class Voice {
     holding;
     /** For a span, its budget and how its children were last fitted; null for any other voice. */
     fitting = null;
+    /** For an arc, how its parts are laid out; null for any other voice. */
+    arc = null;
+    /** For an arc, how long its hold lasts, ms on its clock: Infinity while open. */
+    hold = 0;
+    /** For a voice an arc holds, which part it plays: 0 enter, 1 active, 2 exit; -1 for any other. */
+    part = -1;
     /**
      * `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.
@@ -365,6 +380,7 @@ export class Voice {
         this.outOver = c.outOver;
         this.outSet = c.outSet;
         this.rebuilds = c.rebuilds;
+        this.hold = c.hold;
         const clocks = this.clocks;
         if (clocks !== null && clocks.length !== c.past)
             this.clocks = c.past === 0 ? null : clocks.slice(0, c.past);
@@ -578,6 +594,7 @@ export class Voice {
             outOver: this.outOver,
             outSet: this.outSet,
             rebuilds: this.rebuilds,
+            hold: this.hold,
             past: this.clocks?.length ?? 0,
         });
     }

package/dist/watch.d.ts

@@ -0,0 +1,28 @@
+import type { Mixer } from './mixer.js';
+import type { MixOptions, Registry } from './types.js';
+type Any = Mixer<unknown, unknown>;
+/**
+ * Every mix made on the page, shared by every copy of blits loaded: what a debugger reads to find
+ * them. See `Registry`.
+ *
+ * @category mix
+ */
+export declare function watched(): Registry;
+/**
+ * The history a mix or transport made with `opts` keeps: its own, or with none named and no
+ * transport, the registry's default. Reads the registry only where one was made.
+ */
+export declare function historyFor(opts: {
+    history?: MixOptions['history'];
+    transport?: unknown;
+}): {
+    history: MixOptions['history'];
+    added: boolean;
+};
+/** Marks a transport whose history the registry's default gave. */
+export declare function gave(transport: object): void;
+/** Lists a mix the host made, under an entry this copy builds. */
+export declare function register(mix: Any): void;
+/** Unlists a mix, telling every listener it is gone; one not listed is left alone. */
+export declare function unregister(mix: Any): void;
+export {};