@msb235/blits 0.3.0 → 0.5.0

package/dist/types.d.ts

@@ -67,10 +67,10 @@ export interface Keyframe<O> {
  *
  * @category state
  */
-export interface Setting<S = void> {
+export interface Setting<S = void, H = unknown> {
     /**
-     * The mix clock at this frame: the host's timestamp less any time `rebase` took out. Identical
-     * for every probe in the frame.
+     * The mix clock at this frame: the host's timestamp less any time `rebase` took out, run at the
+     * mix's `rate`. Identical for every probe in the frame.
      */
     timestamp: number;
     /**
@@ -88,14 +88,15 @@ export interface Setting<S = void> {
     weight: number;
     /** This subject's state, when the patch declares one. */
     state: S;
-    /** Anything the host adds for its own patches. */
-    host: unknown;
+    /** Anything the host adds for its own patches: the mix's `host`, typed as its `H`. */
+    host: H;
     /**
      * The state `owner` keeps for this voice and this subject, made by `init` on first ask. The mix
      * holds it, so a read at another time can copy it instead of moving it. A stateful signal keeps
-     * its state here and nowhere else. With lanes on, a patch that first calls it partway through
-     * playing can have that state advanced once for one subject not probed on the frame it starts; a
-     * patch that keeps state from its first call, or declares `state`, never does.
+     * its state here and nowhere else. With lanes on, a patch or weight signal that first calls it
+     * partway through playing can have that state advanced once for one subject not probed on the
+     * frame it starts; one that keeps state from its first call, or a patch that declares `state`,
+     * never does.
      */
     keep<K>(owner: object, init: () => K): K;
     /**
@@ -103,7 +104,7 @@ export interface Setting<S = void> {
      * host drains it, and never calls back. Meant for `step`, where under `stepMs` the timestamp is
      * the interval the event happened in rather than the frame that sampled it. Sent from a stateless
      * patch's `at` while it runs on a lane, it goes out for every subject the mix has met, probed that
-     * frame or not.
+     * frame or not; `at` is not asked for a subject at weight 0, so nothing is sent from it there.
      */
     send(event: unknown): void;
 }
@@ -144,8 +145,8 @@ export type MotionSpec = {
     readonly settle: number;
 } | {
     readonly kind: 'tween';
-    /** How long a stretch takes. */
-    readonly ms: number;
+    /** How long a stretch takes; undefined where it varies by subject, kept on the patch then. */
+    readonly ms: number | undefined;
     readonly ease: Easing;
 };
 /**
@@ -153,14 +154,16 @@ export type MotionSpec = {
  *
  * @category patch
  */
-export interface Patch<I, O, S = void> {
+export interface Patch<I, O, S = void, H = unknown> {
     /**
      * Which authoring form built it: `'fn'` from `patch`, `'keys'` from `keys`, `'motion'` from
      * `spring`, `glide` or `tween`. An engine declares which forms it runs.
      */
     readonly form: 'fn' | 'keys' | 'motion';
-    /** Milliseconds one pass lasts. 0 is aperiodic: phase and pass stay 0. */
-    readonly period: number;
+    /** Milliseconds one pass lasts, whether or not the voice loops. 0 has no passes: phase and pass stay 0. */
+    readonly duration: number;
+    /** @deprecated Use `duration`. A patch that sets only `period` still plays. */
+    readonly period?: number;
     /** The channels this patch contributes to. Every key `at` sets, and no others. */
     readonly writes: readonly (keyof O)[];
     /**
@@ -170,15 +173,18 @@ export interface Patch<I, O, S = void> {
     readonly kit?: Partial<Kit<O>>;
     /** The fields of `setting.host` this patch reads. `cue` refuses a mix whose host lacks one. */
     readonly reads?: readonly string[];
-    /** `phase` is 0..1 across one period, wrapping. */
-    at(phase: number, subject: I, setting: Setting<S>): Partial<O>;
+    /**
+     * `phase` is 0..1 across one pass, wrapping. Not asked for a subject its voice gives no weight, unless the voice is fading to rest;
+     * `step` still runs.
+     */
+    at(phase: number, subject: I, setting: Setting<S, H>): Partial<O>;
     /** Per-subject state, created on the first frame this patch sees a subject. */
     state?(subject: I): S;
     /**
      * Advances state once per subject per sampled frame, by the whole gap since it last advanced; or,
      * where the mix sets `stepMs`, once per whole interval of that length.
      */
-    step?(state: S, dt: number, subject: I, setting: Setting<S>): void;
+    step?(state: S, dt: number, subject: I, setting: Setting<S, H>): void;
     /** Present when the patch was authored as keyframes, so an engine that reads data can. */
     readonly keys?: readonly Keyframe<O>[];
     /** Present on a `'motion'` patch: its kind and constants, for an engine that reads data. */
@@ -197,7 +203,7 @@ export interface Patch<I, O, S = void> {
  *
  * @category signal
  */
-export type Signal<I> = ((subject: I, setting: Setting) => number) & {
+export type Signal<I, H = unknown> = ((subject: I, setting: Setting<void, H>) => number) & {
     readonly input?: boolean;
 };
 /**
@@ -286,19 +292,91 @@ export interface Marked {
     name: string | undefined;
     tags: readonly string[];
 }
+/**
+ * An event at a time on a voice's own clock, which `book` hands a host ahead of time. It plays once
+ * per pass, for the voice and not per subject, so `stagger` does not spread it.
+ *
+ * @category score
+ */
+export interface Hit<E = unknown> {
+    /** Voice ms into each pass: 0 up to the patch's `duration`, or any time at all for a patch with none. */
+    at: number;
+    event: E;
+}
+/**
+ * One pass of one hit, as `book` takes it.
+ *
+ * @category score
+ */
+export interface BookedHit<E = unknown> {
+    /** On the host's clock. */
+    timestamp: number;
+    voice: number;
+    /** Which of the voice's `hits`, by index. */
+    hit: number;
+    /** Which pass, 0 first. */
+    pass: number;
+    event: E;
+    score: string | undefined;
+    name: string | undefined;
+    tags: readonly string[];
+}
+/**
+ * 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> {
+    /**
+     * 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
+     * in 5% of each frame's difference, and starts over from the clock's own reading on a jump past
+     * 50 ms, such as a suspended context or a hidden tab.
+     */
+    clock: () => number;
+    /** How far ahead to book, host ms. It has to cover the longest gap between two syncs. */
+    ahead: number;
+    /** How far past an item first seen late may be and still be taken, host ms. */
+    late: number;
+    /**
+     * 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, 0 for one booked ahead, which
+     * is then taken at the clock's now. Return a `stop` 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;
+    } | undefined;
+    /** Book only the voices, and announced marks, carrying this tag. */
+    tag?: string;
+    /** Book only this score's voices and marks. */
+    score?: string;
+}
+/**
+ * A running booker, returned by `book`.
+ *
+ * @category score
+ */
+export interface Booker {
+    /** Stops every booking still ahead, and books nothing more. */
+    stop(): void;
+}
 /**
  * What `cue` takes: a patch, and the clock, weight and reach it plays with.
  *
  * @category voice
  */
-export interface VoiceSpec<I, O> {
-    patch: Patch<I, O, unknown>;
+export interface VoiceSpec<I, O, H = unknown> {
+    patch: Patch<I, O, unknown, H>;
     /**
      * Which subjects this voice reaches. Default: all of them. The predicate is fixed at `cue`; it
      * runs per subject the first time the mix sees that subject, and the answer is kept. Every
      * voice's predicate meets every subject, so voices that each reach a known few cost the square
-     * of their number, in time and in memory (a record per voice per subject asked: about 800 MB for
-     * 1,000 such voices); name those with `subjects` instead.
+     * of their number in time; name those with `subjects` instead. A no is kept as a bit by the
+     * number lanes give the subject, but with `lanes: false` as a map entry per voice per subject
+     * asked (about 37 MB for 1,000 such voices over 1,000 subjects).
      */
     target?: (subject: I) => boolean;
     /**
@@ -317,7 +395,7 @@ export interface VoiceSpec<I, O> {
     /**
      * 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.
+     * set, at once where none is — unless it holds after.
      */
     loop?: boolean | number;
     /**
@@ -325,15 +403,25 @@ export interface VoiceSpec<I, O> {
      * Like `target`, it runs once per subject on first sight, and the answer is kept.
      */
     stagger?: (subject: I) => number;
+    /**
+     * Show a subject the first frame before it starts — while the voice is pending and while the
+     * subject waits out its `stagger` — the last frame of the last pass after a finite loop plays
+     * out, or both. A held subject's clock stands still: `at` is asked for the edge frame and `step`
+     * does not run, past one last step to the end of the last pass. `fade.in` counts from the first
+     * frame the voice shows. A voice holding after stays, `held`, until `fade()` or an anchored `out`
+     * takes it out, so every one cued must be faded or it stays in the mix for good. Does nothing to
+     * a motion patch, which holds its target already. Default: neither.
+     */
+    hold?: 'before' | 'after' | 'both';
     /** Steady weight, or a signal read per subject per frame. Default 1. */
-    weight?: number | Signal<I>;
+    weight?: number | Signal<I, H>;
     /** Ramp in and out, ms. Out applies on `fade()` and when a finite loop ends. */
     fade?: FadeSpec;
     /** Voices sharing a locus are alternatives: the mix folds them through each channel's `lerp`. */
     locus?: string;
     /** A `keys` voice whose first stop reads wherever this subject is now. */
     from?: 'current';
-    /** Words a source attaches to this voice, so its events can be drained as a set. */
+    /** Words a source attaches to this voice, so its events and its handle can be taken as a set. */
     tags?: readonly string[];
     /** What other voices call this one by. A label blits never reads. */
     name?: string;
@@ -345,20 +433,76 @@ export interface VoiceSpec<I, O> {
     score?: string;
     /** Where it sits relative to the clock or to other voices, in place of `start`. */
     anchor?: Placement;
+    /**
+     * Events at times on this voice's clock, which `book` hands a host ahead of time. Patch-sent
+     * events are not known ahead, so they stay drain-only; these are the plan.
+     */
+    hits?: readonly Hit[];
+    /**
+     * 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
+     * bare name in an anchor means a sibling, another voice the owner holds. Its clock runs on the
+     * owner's, so the owner's rate, ramp and seeks move it, and its weight is multiplied by the
+     * owner's weight and fade. Without a `hold` of its own it takes the owner's.
+     */
+    owner?: Handle<I>;
+}
+/**
+ * What `owns` takes: an owner has no patch, and plays only through the voices it holds.
+ *
+ * @category voice
+ */
+export interface OwnerSpec<I, H = unknown> {
+    /**
+     * When the owner starts, on its own owner's clock: the host's for an owner on the mix, as a
+     * voice's `start` is. Default: now.
+     */
+    start?: number;
+    /** Its clock's rate, multiplied into every child's own. Default 1. */
+    rate?: 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.
+     */
+    weight?: number | Signal<I, H>;
+    /** One ramp in and out over every child, multiplied into their weights as `weight` is. */
+    fade?: FadeSpec;
+    /** The hold every child without one of its own takes. */
+    hold?: 'before' | 'after' | 'both';
+    /** Words a source attaches to it, as a voice's. */
+    tags?: readonly string[];
+    /** What other voices call it by, among its siblings. */
+    name?: string;
+    /** The plan it belongs to, as a voice's. */
+    score?: string;
+    /** Where it sits relative to its own owner's clock or to other voices, in place of `start`. */
+    anchor?: Placement;
+    /** The owner it plays under, so owners nest. */
+    owner?: Handle<I>;
 }
 /**
- * How a voice leaves when it is faded.
+ * How a voice leaves when it is faded: the whole voice, or one subject.
  *
  * @category blending
  */
-export interface FadeOptions {
+export type FadeOptions<I = unknown> = {
     /** The ramp, ms. Defaults to the voice's own `fade.out`. */
     over?: number;
     /** Leave per subject at the first frame that subject's contribution is at rest. */
     at?: 'rest';
     /** Ms after which the voice leaves whether or not it rested. */
     deadline?: number;
-}
+    subject?: never;
+} | {
+    /**
+     * The one subject to fade out of this voice, which plays on for the rest. Once the ramp ends
+     * the voice forgets the subject and reaches it no more, until a motion patch's `to` brings it
+     * back, met afresh: `from`, `target` and `stagger` asked again.
+     */
+    subject: I;
+    /** The ramp, ms. Defaults to the voice's own `fade.out`; 0 takes the subject out at once. */
+    over?: number;
+};
 /**
  * The live controls on one voice, returned by `cue`.
  *
@@ -366,7 +510,10 @@ export interface FadeOptions {
  */
 export interface Handle<I = unknown> {
     readonly id: number;
-    readonly state: 'pending' | 'live' | 'fading' | 'done';
+    /** `held`: a voice holding after has played every pass and shows its last frame until faded. */
+    readonly state: 'pending' | 'live' | 'held' | 'fading' | 'done';
+    /** The handle of the owner this voice plays under; undefined for one on the mix clock. */
+    readonly owner: Handle<I> | undefined;
     /** Live. Writes land on the next sync. */
     weight: number;
     /** Playback rate now. Setting it changes speed at once; `ramp` eases into a new one. */
@@ -382,28 +529,34 @@ export interface Handle<I = unknown> {
      * accumulated into, so state is left where it is and never run forward to meet the new position.
      */
     seek(elapsed: number): void;
-    fade(opts?: FadeOptions): void;
+    fade(opts?: FadeOptions<I>): void;
     /**
      * The weight this voice gave `subject` the last frame that subject was probed: after its fades
      * and its weight signal, before a locus folds it with its alternatives. 0 for a subject it does
-     * not reach, has not started on, has left at rest, or has never been probed for; 0 once done.
+     * not reach, has not started on and does not hold before, has left at rest, or has never been
+     * probed for; 0 once done.
      * Costs nothing until it is asked.
      */
     weightOf(subject: I): number;
     /** Resolves when the voice has been removed from the mix, however that happened. */
     readonly done: Promise<void>;
+    /**
+     * Resolves true when a finite loop's last pass ends, for the latest-staggered subject it has
+     * seen, and false if the voice leaves before that. Never rejects.
+     */
+    readonly played: Promise<boolean>;
 }
 /**
  * How a mix is built: its engine, reduced motion, the host, and its limits.
  *
  * @category mix
  */
-export interface MixOptions {
+export interface MixOptions<H = unknown> {
     engine?: Engine;
     /** Reduced motion: fades and warm-ups snap, `dt` reads Infinity. */
     reduce?: boolean | (() => boolean);
-    /** Merged into every `setting.host`. */
-    host?: unknown;
+    /** Merged into every `setting.host`. Its type is the mix's `H`, which every patch and signal it cues reads. */
+    host?: H;
     /**
      * The band a rest-less channel's influence switches on and off across. It has to clear the frame
      * noise in a real signal; these are placeholders until the klieg port measures one.
@@ -487,11 +640,26 @@ export type Columns<O> = {
  *
  * @category mix
  */
-export interface Mix<I, O> {
+export interface Mix<I, O, H = unknown> {
     /** Cues a voice. Throws when the engine cannot run the patch's form, or the kit lacks a channel. */
-    cue(spec: VoiceSpec<I, O>): Handle<I>;
-    /** N voices whose weights split one signal, cued into one locus so they fold as alternatives. */
-    blend(patches: readonly Patch<I, O, unknown>[], by: Signal<I>, spec?: Omit<VoiceSpec<I, O>, 'patch' | 'weight' | 'locus'>): Handle<I>[];
+    cue(spec: VoiceSpec<I, O, H>): Handle<I>;
+    /**
+     * 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.
+     */
+    blend(patches: readonly Patch<I, O, unknown, 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
+     * on all of them: `rate` and `ramp` multiply into theirs, `seek` moves their clocks with its own
+     * and leaves their state where it is, and `weight` and `fade()` multiply into their weights, by
+     * what its `weightOf` reports; it fades as a whole, not by subject or at rest. It is
+     * `played` once every voice it held has finished its passes, and leaves, `done`, with its last; a
+     * fade that ends takes the rest with it. One that never holds a voice stays until faded. Owners
+     * nest. Throws for a `loop`: a pass would have to restart its children.
+     */
+    owns(spec: OwnerSpec<I, H>): Handle<I>;
     /** The host reports the clock, once a frame. Nothing advances at the call. */
     sync(timestamp: number): void;
     /**
@@ -499,13 +667,39 @@ export interface Mix<I, O> {
      * hidden tab comes back. Every voice, fade and subject resumes where it was left.
      */
     rebase(): void;
-    /** The merged pose for one subject at the synced frame. */
+    /**
+     * The mix's own playback rate, multiplied into every voice's: 1 is real time and 0 pauses the
+     * whole mix. A negative rate throws, since the mix only goes forward. Setting it changes speed at
+     * once; `ramp` eases into a new one. It scales mix time, which everything a voice owns runs on:
+     * its clock, its fades and a handle's ramp, `stagger`, an anchor's `by`, `stepMs`, `maxDt`,
+     * `history.ms`, every `dt`, and `setting.timestamp`. Timestamps on the host's clock name the same
+     * moment whatever the rate does: a `start`, an anchor given as a number, an announced mark, what
+     * `marks` reports and the time `project` reads, so a start ahead of a paused mix waits for the
+     * host's clock to reach it. A weight signal is still asked at every probe, so one reading host
+     * input follows it while the mix is paused.
+     */
+    rate: number;
+    /**
+     * Moves the mix's rate to `rate` linearly over `over` ms of the host's clock, as `Handle.ramp`
+     * moves a voice's. Mix time integrates the ramp and a voice's clock integrates mix time, so a ramp
+     * on both multiplies and every position stays continuous. A later `rate` write or `ramp` replaces
+     * it.
+     */
+    ramp(rate: number, over: number): void;
+    /**
+     * The merged pose for one subject at the synced frame, written into `out` when given. Without
+     * it, each call makes a new object, so a host reading every subject every frame passes `out` or
+     * reads by `pull`.
+     */
     probe(subject: I, out?: O): O;
     /**
      * Writes each subject's pose into arrays, one per channel, subject by subject in the order given:
      * what `probe(subject, out)` gives, without a pose object per subject. A channel of `n` numbers
      * takes `n` places per subject, side by side; one with no value for a subject writes NaN there.
-     * Fastest while every voice runs on a lane. Throws when an array is too short for the subjects.
+     * Fastest while every voice runs on a lane, and when `subjects` is an array read again in the
+     * same order: the mix remembers the last array's subjects by position, holding them until the
+     * next `pull`, and skips looking up any still in its place. Throws when an array is too short for
+     * the subjects.
      */
     pull(subjects: Iterable<I>, into: Columns<O>): void;
     /**
@@ -514,10 +708,26 @@ export interface Mix<I, O> {
      * older than the history reaches.
      */
     project(timestamp: number): Projection<I, O>;
-    /** Every channel at rest for this subject this frame, so a host can skip the write. */
+    /**
+     * Every channel at rest for this subject this frame, so a host can skip the write. After a probe
+     * of the subject this frame, it answers for the pose that probe gave, without folding again.
+     */
     atRest(subject: I): boolean;
+    /**
+     * A handle on every voice still in the mix, pending, live, held or fading, in the order they were
+     * cued; given a tag, only the voices whose `tags` carry it. Each is the handle `cue` returned for
+     * that voice, so a listed handle is `===` the cued one.
+     */
+    voices(tag?: string): Handle<I>[];
     /** Anything still contributing, fading, or pending. */
     readonly live: boolean;
+    /**
+     * Another frame would change no pose, so a host's frame loop may sleep: every voice is done, held
+     * at a plain weight, or a motion whose every subject has landed on its target. At rate 0 it is
+     * enough that every voice not done has started, at a plain weight, with no anchor. A change made
+     * since the last sync, a retarget or a rate included, makes it false until the next.
+     */
+    readonly inert: boolean;
     /** Fades every voice out: over `over` when given, over each voice's own `fade.out` otherwise. */
     mute(opts?: {
         over?: number;
@@ -552,6 +762,15 @@ export interface Mix<I, O> {
      * whoever drains them.
      */
     drain<E = unknown>(tag?: string): Sent<I, E>[];
+    /**
+     * Hands the host each mark and hit before it comes, against a clock of its own, so it can schedule
+     * the thing itself: a sound on an `AudioContext`, a MIDI message with a timestamp, a video loaded
+     * before the voice that shows it starts. Booking runs at each `sync`, `ahead` ms out, and a
+     * booking whose time moves is stopped and taken again. Nothing is booked twice: a mark is known by
+     * 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;
 }
 /**
  * The implementation behind a mix: which patch forms it runs, and how it makes one.
@@ -562,5 +781,5 @@ export interface Engine {
     readonly name: string;
     /** Which patch forms this engine can run. A voice it cannot run is refused at `cue`, by name. */
     readonly runs: ReadonlySet<'fn' | 'keys' | 'motion'>;
-    create<I, O>(kit: Kit<O>, opts: MixOptions): Mix<I, O>;
+    create<I, O, H = unknown>(kit: Kit<O>, opts: MixOptions<H>): Mix<I, O, H>;
 }

package/dist/unreached.d.ts

@@ -0,0 +1,5 @@
+import type { Voice } from './voice.js';
+/** Whether the voice's shared unreached record stands for the subject numbered `slot`. */
+export declare function unreached<I, O>(voice: Voice<I, O>, slot: number): boolean;
+/** Marks or clears the subject numbered `slot` as one the voice does not reach. */
+export declare function unreach<I, O>(voice: Voice<I, O>, slot: number, on: boolean): void;

package/dist/unreached.js

@@ -0,0 +1,24 @@
+/** Whether the voice's shared unreached record stands for the subject numbered `slot`. */
+export function unreached(voice, slot) {
+    const bits = voice.unreachedBits;
+    if (bits === null || slot < 0)
+        return false;
+    const word = slot >>> 5;
+    return word < bits.length && (bits[word] & (1 << (slot & 31))) !== 0;
+}
+/** Marks or clears the subject numbered `slot` as one the voice does not reach. */
+export function unreach(voice, slot, on) {
+    let bits = voice.unreachedBits;
+    const word = slot >>> 5;
+    if (bits === null || word >= bits.length) {
+        if (!on)
+            return;
+        const grown = new Uint32Array(Math.max(word + 1, (bits?.length ?? 0) * 2, 2));
+        if (bits !== null)
+            grown.set(bits);
+        voice.unreachedBits = grown;
+        bits = grown;
+    }
+    const bit = 1 << (slot & 31);
+    bits[word] = on ? bits[word] | bit : bits[word] & ~bit;
+}