@msb235/blits 0.14.0 → 0.15.1

package/dist/strays.js

@@ -1,6 +1,7 @@
+import { delayOf } from './delay.js';
 import { unpart } from './fade.js';
 import { pageOut } from './paging.js';
-import { record, unplayable } from './tape.js';
+import { record, taping, unplayable } from './tape.js';
 /** Notes a motion patch that may hold state for a subject no voice playing it reaches. */
 export function stray(mix, motion, subject) {
     const list = mix.strays.get(subject);
@@ -24,7 +25,7 @@ export function unplay(mix, voice) {
     if (voice.named === null)
         mix.strayAll.add(motion);
     else
-        for (const subject of voice.named)
+        for (const subject of voice.named.list)
             stray(mix, motion, subject);
 }
 /**
@@ -45,19 +46,14 @@ export function motionOwner(mix) {
         seq() {
             return mix.deref()?.transport.seq ?? Number.NaN;
         },
+        early() {
+            const m = mix.deref();
+            return m !== undefined && (m.syncing || !m.looked);
+        },
         changed(id, motion, subject, change) {
             const m = mix.deref();
-            if (m === undefined)
-                return;
-            record(m, 'motion', (stage) => {
-                const to = stage.mix(m);
-                if (to === undefined)
-                    return;
-                if (to !== m)
-                    return changeAhead(to, id, motion, subject, change);
-                const v = cuedById(m, id) ?? m.gone.find((g) => g.id === id);
-                (v?.motion ?? motion).change(subject, { ...change });
-            });
+            if (m !== undefined && taping(m))
+                recordChange(m, id, motion, subject, change);
         },
         page(id, stream, subject, out) {
             const m = mix.deref();
@@ -80,10 +76,22 @@ export function motionOwner(mix) {
                 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);
+            return timeIn(m, v, delayOf(v, subject));
         },
     };
 }
+// Apart from `changed`, whose body would otherwise make this closure's context on every change.
+function recordChange(m, id, motion, subject, change) {
+    record(m, 'motion', (stage) => {
+        const to = stage.mix(m);
+        if (to === undefined)
+            return;
+        if (to !== m)
+            return changeAhead(to, id, motion, subject, change);
+        const v = cuedById(m, id) ?? m.gone.find((g) => g.id === id);
+        (v?.motion ?? motion).change(subject, { ...change });
+    });
+}
 /**
  * A retarget or push the tape holds, made for a read ahead: kept on its transport for the patch
  * to apply as it reads, since the patch's own state is the live mix's.
@@ -100,7 +108,7 @@ function changeAhead(to, id, motion, given, change) {
             unpart(to, v, subject);
         if (at === undefined) {
             const frame = frameOf(to, v, subject);
-            const back = parted ? timeIn(to, v, v.spec.stagger ? v.spec.stagger(subject) : 0) : frame;
+            const back = parted ? timeIn(to, v, delayOf(v, subject)) : frame;
             if (!Number.isNaN(frame))
                 at = frame;
             else if (!Number.isNaN(back))

package/dist/stretch.d.ts

@@ -0,0 +1,112 @@
+import type { Curve } from './easing.js';
+import type { Motions } from './motions.js';
+import type { MotionSpec } from './types.js';
+/**
+ * One closed-form stretch: released at `at` (voice ms) from `x0` moving at `v0`, toward `to`, over
+ * `ms` for a tween (0 for any other shape).
+ */
+export interface Segment {
+    at: number;
+    ms: number;
+    x0: number[];
+    v0: number[];
+    to: number[];
+    /** The change that released it; undefined for a subject's first stretch. */
+    change?: Change;
+}
+export interface Change {
+    /**
+     * Voice ms it takes effect at; absent, until the subject's next read stamps it with that read's
+     * time, for one made while no frame had met the subject.
+     */
+    at?: number;
+    to?: number[];
+    /** Where it moves from, in place of where its stretch has it then. */
+    x?: number[];
+    v?: number[];
+    /** The mix clock when it was made, NaN where no mix was playing the patch. */
+    made?: number;
+    /** The frame it was made in, which a rewind partitions by; NaN where no mix was playing the patch. */
+    seq?: number;
+    /** Whether it was made before its frame was read, so a read of what that frame showed has it. */
+    early?: boolean;
+}
+/** A record of a motion patch's history leaving memory, at a mix time and frame. */
+export interface Paging {
+    at: number;
+    seq: number;
+    data: unknown;
+}
+/** A subject's run as plain data: its flags, its stretches oldest first, and changes still to apply. */
+export interface Run {
+    flags: number;
+    stretches: Segment[];
+    pending: Change[] | undefined;
+}
+/** `n` numbers of `from` from `at`, as an array of their own. */
+export declare function numbers(from: Float64Array, at: number, n: number): number[];
+/**
+ * A subject's flags: its value is a number; it has changes pending; it has older stretches; the
+ * stretch it is playing was found landed, which holds until another replaces it.
+ */
+export declare const enum RunFlag {
+    SCALAR = 1,
+    PENDING = 2,
+    OLDER = 4,
+    LANDED = 8
+}
+/**
+ * The mix playing a patch, asked with its voice's id: an owner and an id, where a pair of closures
+ * cost two functions, their contexts and a weak reference per voice.
+ */
+export interface MotionOwner {
+    /** The subject's voice time at the mix's latest frame; NaN where no frame of the voice met it. */
+    frame(id: number, subject: unknown): number;
+    /**
+     * Brings a subject the voice faded out back to it, so a change is not made for nothing: its
+     * voice time now, which a change bringing it back is made at; NaN for any other subject.
+     */
+    revive(id: number, subject: unknown): number;
+    /** The mix clock at its latest frame; NaN before the first. */
+    now(): number;
+    /** The number of the frame the mix is playing. */
+    seq(): number;
+    /** Whether a change made now comes before anything read the frame. */
+    early(): boolean;
+    /**
+     * The host made a change, already given its time, which a seek makes again on the patch its
+     * voice plays then: a voice a history store paged out comes back with a patch of its own.
+     */
+    changed<I>(id: number, motion: Motions<I>, subject: I, change: Change): void;
+    /** History leaving memory for a subject, which a mix with a history store pages out. */
+    page(id: number, stream: 'released' | 'stretch', subject: unknown, out: Paging[]): void;
+}
+/**
+ * What a mix keeping copies of a patch's stretches is told, with its id and the subject's number,
+ * before one changes.
+ */
+export interface Watcher {
+    stretchChanged(id: number, s: number): void;
+}
+export interface Shape<I> {
+    from: (subject: I) => number[];
+    /** How fast each axis starts moving, given where it starts: still unless the options say. */
+    velocity: (subject: I, x: number[]) => number[];
+    /**
+     * Where it heads when released from `x` at `v`, given where it was heading; `put` for a stretch a
+     * `set` released.
+     */
+    aim: (x: number[], v: number[], was: number[] | null, subject: I, put: boolean) => number[];
+    /** `[form, settle, k1, k2, k3]`. */
+    law: readonly number[];
+    /** Whether a subject's value is a number rather than an array. */
+    scalar: (subject: I) => boolean;
+    /** Whether every subject's value is a number; undefined where that depends on the subject. */
+    scalarEvery(): boolean | undefined;
+    /** A tween's easing, which its law cannot hold; undefined, but present, on every other shape. */
+    ease: Curve | undefined;
+    /** A tween's ms for a stretch the subject starts now; undefined, but present, on the rest. */
+    ms: ((subject: I) => number) | undefined;
+    /** The patch's kind and constants, as `Patch.motion` reports them. */
+    spec(): MotionSpec;
+}

package/dist/stretch.js

@@ -0,0 +1,9 @@
+/** Where `numbers` gathers what it copies, kept an array of doubles so every copy is one too. */
+const gathered = [0.5];
+/** `n` numbers of `from` from `at`, as an array of their own. */
+export function numbers(from, at, n) {
+    // `Array.from` walks a typed array by its iterator: about 500 B a call for three axes.
+    for (let i = 0; i < n; i++)
+        gathered[i] = from[at + i];
+    return gathered.slice(0, n);
+}

package/dist/subject.d.ts

@@ -0,0 +1,142 @@
+import type { Stamp } from './restored.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 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;
+    at: number;
+    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;
+}
+/**
+ * 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. */
+    reaches: boolean;
+    /** The voice's `stagger` answer in voice ms, fixed on first sight. */
+    delay: number;
+    /** The mix timestamp this subject's delay ran out at, which its step grid counts from. */
+    since: number;
+    /** The mix timestamp its fade in counts from: `since`, or earlier for a voice freezing before. */
+    shown: number;
+    /** The weight this voice gave this subject the last frame it was probed, 0 where it gave none. */
+    weight: number;
+    /**
+     * The mix time it was left at rest during a handover, so it stops contributing, and which a seek
+     * reads to know whether it had by then; NaN while it has not (`isRested`).
+     */
+    restedAt: number;
+    /**
+     * Per written channel, whether a rest-less contribution is on: 0 unknown, 1 on, 2 off; null until
+     * a rest-less channel asks.
+     */
+    bands: Uint8Array | null;
+    state: S;
+    /** The `now` this subject last caught up to, for this voice. */
+    stepped: number;
+    /** Under `stepMs`, how many intervals have run since `since`; `stepped` is where that lands. */
+    ticks: number;
+    /** The `now` this subject was last probed at, so twelve probes in a frame step once. */
+    probed: number;
+    /** The last delta computed this frame, handed back to a repeat probe unchanged. */
+    delta: Record<string, unknown> | null;
+    /** The phase `delta` was read at, to read it again once its voice's scratch has moved on. */
+    phase: number;
+    /** The voice's `seeks` when `delta` was read, so a seek later in the frame reads it again. */
+    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. */
+    slope?: Record<string, unknown>;
+    /** What `setting.keep` holds for this voice and subject, by owner; null until it holds any. */
+    kept: Map<object, unknown> | null;
+    /** 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?: Snap<S>[];
+    /** In a projection: where this record started from, and whether nothing known could be. */
+    from?: number;
+    unknown?: boolean;
+    /** Under `history` with `inputs`, what an input weight signal read for this subject, when it changed. */
+    inputs?: {
+        at: number;
+        seq: number;
+        value: number;
+    }[];
+    /** In a projection reading back: that record, to read in place of the signal. */
+    replay?: {
+        at: number;
+        value: number;
+    }[];
+    /** The voice this is the record of; null on a subject's stub. */
+    voice: object | null;
+    /** The next voice's record for this subject, in voice order, among those that reach it. */
+    next: Subject<unknown> | null;
+    /**
+     * On the first record, which the mix keeps per subject so a probe makes one lookup: the `version`
+     * the chain was linked at, and per role, by channel slot, whether a rest-less contribution is on:
+     * 0 never decided, 1 on, 2 off.
+     */
+    version: number;
+    roles: Map<string, Uint8Array> | null;
+    /** On the first record: the number lanes index this subject by, -1 without one. */
+    slot: number;
+    /** 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;
+}

package/dist/subject.js

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

package/dist/tape.d.ts

@@ -18,15 +18,18 @@ export declare function unplayable(what: string): never;
  * at: rate 0 holds mix time still across frames, and host time tells them apart.
  */
 export declare function tapeOf(transport: Transport): Tape | undefined;
+interface Recorder {
+    readonly tape: Tape | undefined;
+    readonly replaying: boolean;
+    readonly projecting: boolean;
+}
+/** Whether `record` keeps a call made on `on` now, so a caller can skip making one it would drop. */
+export declare function taping(on: Recorder): boolean;
 /**
  * Records a host call, which `again` makes once more when the mix plays past it after a seek, or
  * when a read ahead does, on the stage it is given.
  */
-export declare function record(on: {
-    readonly tape: Tape | undefined;
-    readonly replaying: boolean;
-    readonly projecting: boolean;
-}, label: string, again: (stage: Stage) => void): void;
+export declare function record(on: Recorder, label: string, again: (stage: Stage) => void): void;
 /** The host time at which the mix clock reads `t`, under the rate it has now. */
 export declare function hostAt(clock: {
     readonly pace: Pace | null;
@@ -47,3 +50,4 @@ export declare function hostAhead(clock: {
  * stage of its copies, it makes them on those, and the caller puts the tape back.
  */
 export declare function replay(transport: Transport, due: (u: number) => boolean, onto?: Transport, on?: Stage): number;
+export {};

package/dist/tape.js

@@ -24,13 +24,17 @@ export function tapeOf(transport) {
         coalesceWindowMs: 0,
     });
 }
+/** Whether `record` keeps a call made on `on` now, so a caller can skip making one it would drop. */
+export function taping(on) {
+    return on.tape !== undefined && !on.replaying && !on.projecting;
+}
 /**
  * Records a host call, which `again` makes once more when the mix plays past it after a seek, or
  * when a read ahead does, on the stage it is given.
  */
 export function record(on, label, again) {
     const tape = on.tape;
-    if (tape === undefined || on.replaying || on.projecting)
+    if (tape === undefined || !taping(on))
         return;
     const op = {
         label,

package/dist/then.d.ts

@@ -0,0 +1,9 @@
+import { type Cut } from './cut.js';
+import type { Motions } from './motions.js';
+/**
+ * `subject`'s position and velocity at voice time `t`, into the patch's `xs` and `vs`, as frame `cut` left it:
+ * in the run it had then, with only the changes made by then, as a seek back there plays it. A run
+ * with none made since reads as it stands; one with some plays from its earliest stretch kept,
+ * the rest applied again in the order they take effect. Commits nothing, and gives the run's flags.
+ */
+export declare function sampleThen<I>(motions: Motions<I>, subject: I, t: number, cut: Cut): number;

package/dist/then.js

@@ -0,0 +1,57 @@
+import { within } from './cut.js';
+/** Whether `c` was made by frame `cut`; one made with no mix playing its patch was. */
+const madeBy = (c, cut) => c.seq === undefined || Number.isNaN(c.seq) || within(cut, c.seq, c.early === true);
+/** The stretch playing at voice time `t` of a run's, oldest first: the latest released by then, else the first. */
+function playingIn(list, t) {
+    const last = list[list.length - 1];
+    if (t >= last.at || list.length === 1)
+        return last;
+    if (list[0].at > t)
+        return list[0];
+    let lo = 0;
+    let hi = list.length - 2;
+    while (lo < hi) {
+        const mid = (lo + hi + 1) >> 1;
+        if (list[mid].at <= t)
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    return list[lo];
+}
+/**
+ * `subject`'s position and velocity at voice time `t`, into the patch's `xs` and `vs`, as frame `cut` left it:
+ * in the run it had then, with only the changes made by then, as a seek back there plays it. A run
+ * with none made since reads as it stands; one with some plays from its earliest stretch kept,
+ * the rest applied again in the order they take effect. Commits nothing, and gives the run's flags.
+ */
+export function sampleThen(motions, subject, t, cut) {
+    const run = motions.runThen(subject, cut) ?? motions.freshRun(subject);
+    let stretches = run.stretches;
+    let pending = run.pending ?? [];
+    const kept = [];
+    let since = false;
+    for (const c of [...stretches.slice(1).map((seg) => seg.change), ...pending])
+        if (c === undefined || madeBy(c, cut)) {
+            if (c !== undefined)
+                kept.push(c);
+        }
+        else
+            since = true;
+    if (since) {
+        stretches = [stretches[0]];
+        pending = kept
+            .filter((c) => c.at !== undefined)
+            .sort((a, b) => a.at - b.at);
+    }
+    let seg = playingIn(stretches, t);
+    for (const c of pending) {
+        const a = c.at;
+        if (a === undefined || !(a <= t))
+            break;
+        if (a >= seg.at)
+            seg = motions.applied(subject, seg, c, a);
+    }
+    motions.evaluateSegment(seg, t, motions.xs, motions.vs);
+    return run.flags;
+}

package/dist/ticker.d.ts

@@ -1,5 +1,5 @@
 /**
- * What a ticker runs: a mix, or anything that syncs, sleeps on `inert` and wakes by `onWake`.
+ * What a ticker runs. A mix, or anything that syncs, sleeps on `inert` and wakes by `onWake`.
  *
  * @category mix
  */
@@ -21,9 +21,9 @@ export interface TickerOptions {
      */
     fps?: number;
     /**
-     * Where frames come from: `'frame'`, `requestAnimationFrame`, or `'timer'`, `setTimeout`. By
-     * default animation frames where they exist, and a timer where they don't, as in a worker
-     * without them or in Node.
+     * Where frames come from. `'frame'` is `requestAnimationFrame`, and `'timer'` is `setTimeout`. By
+     * default animation frames where they exist, and a timer where they don't, as in a worker without
+     * them or in Node.
      */
     grain?: 'frame' | 'timer';
     /**

package/dist/trace.d.ts

@@ -0,0 +1,4 @@
+import type { Mixer } from './mixer.js';
+import type { Trace, TraceOptions } from './types.js';
+/** `mix.trace`: see `Mix.trace`. */
+export declare function traceMix<I, O>(mix: Mixer<I, O>, from: number, to: number, opts?: TraceOptions): Trace<I, O>;