@msb235/blits 0.14.0 → 0.15.1

package/dist/trace.js

@@ -0,0 +1,255 @@
+import { straight } from './easing.js';
+/**
+ * How far inside a sampled stretch its ends are read, ms, but for the window's own: a stretch ends
+ * where a voice may jump, and its end is read on its own side of the jump.
+ */
+const NUDGE = 1e-6;
+/** Two values at one time this close are one point, not a jump. */
+const close = (a, b) => Math.abs(a - b) <= 1e-6 * Math.max(1, Math.abs(a), Math.abs(b));
+/** `mix.trace`: see `Mix.trace`. */
+export function traceMix(mix, from, to, opts = {}) {
+    if (!(from <= to) || !Number.isFinite(from) || !Number.isFinite(to))
+        throw new RangeError(`blits: a trace runs from a time to one no earlier, not ${from} to ${to}`);
+    const grid = opts.grid ?? 5;
+    if (!(grid > 0 && grid < Number.POSITIVE_INFINITY))
+        throw new RangeError(`blits: a trace's grid is a finite number of ms above 0, not ${grid}`);
+    const known = knowable(mix, from);
+    const projections = new Map();
+    const poses = new Map();
+    const plans = new Map();
+    const poseAt = (subject, t) => {
+        let mine = poses.get(subject);
+        if (mine === undefined) {
+            mine = new Map();
+            poses.set(subject, mine);
+        }
+        let pose = mine.get(t);
+        if (pose === undefined) {
+            let p = projections.get(t);
+            if (p === undefined) {
+                p = mix.project(t);
+                projections.set(t, p);
+            }
+            pose = p.probe(subject, mix.pose());
+            mine.set(t, pose);
+        }
+        return pose;
+    };
+    return {
+        from,
+        to,
+        of(subject, channel) {
+            const name = channel;
+            const slot = mix.slotOf.get(name);
+            if (slot === undefined)
+                throw new Error(`blits: the mix has no channel ${name}`);
+            const value = (t) => {
+                const v = poseAt(subject, t)[name];
+                return typeof v === 'number' ? v : Number.NaN;
+            };
+            let plan = plans.get(subject);
+            if (plan === undefined) {
+                plan = planOf(mix, subject, from, to);
+                plans.set(subject, plan);
+            }
+            const op = mix.scalars[slot];
+            const shaped = known &&
+                !plan.unknown.has(slot) &&
+                !mix.bounded.includes(slot) &&
+                (op === 'sum' || (op === 'mul' && (plan.writers.get(slot) ?? 0) <= 1));
+            const bent = plan.bent.get(slot);
+            const straightOver = (a, b) => shaped && (bent === undefined || bent.every(([lo, hi]) => !(lo < b && hi > a)));
+            if (from === to)
+                return { at: [from], value: [value(from)], exact: shaped };
+            const at = [];
+            const values = [];
+            let exact = true;
+            const add = (t, v) => {
+                const n = at.length;
+                if (n > 0 && at[n - 1] === t && close(values[n - 1], v))
+                    values[n - 1] = v;
+                else {
+                    at.push(t);
+                    values.push(v);
+                }
+            };
+            const knots = [from, ...(plan.knots.get(slot) ?? []), to];
+            for (let i = 0; i + 1 < knots.length; i++) {
+                const a = knots[i];
+                const b = knots[i + 1];
+                if (straightOver(a, b)) {
+                    // Read inside, so a jump at either end is not read; the line reaches each end exactly.
+                    const t1 = a + (b - a) / 3;
+                    const t2 = b - (b - a) / 3;
+                    const v1 = value(t1);
+                    const slope = (value(t2) - v1) / (t2 - t1);
+                    add(a, v1 - slope * (t1 - a));
+                    add(b, v1 + slope * (b - t1));
+                    continue;
+                }
+                exact = false;
+                const e = Math.min(NUDGE, (b - a) / 4);
+                add(a, value(a === from ? a : a + e));
+                for (let k = Math.max(0, Math.ceil((a - from) / grid));; k++) {
+                    const g = from + k * grid;
+                    if (g >= b - e)
+                        break;
+                    if (g > a + e)
+                        add(g, value(g));
+                }
+                add(b, value(b === to ? b : b - e));
+            }
+            return { at, value: values, exact };
+        },
+    };
+}
+/**
+ * Whether the mix's own state lets a trace know any shape: a window at or after the mix's time,
+ * with no recorded call ahead.
+ */
+function knowable(mix, from) {
+    const transport = mix.transport;
+    if (!(from >= mix.now))
+        return false;
+    const tape = transport.tape;
+    return tape === undefined || tape.timestampAt(tape.undoDepth()) === undefined;
+}
+function planOf(mix, subject, from, to) {
+    const plan = { knots: new Map(), bent: new Map(), unknown: new Set(), writers: new Map() };
+    for (const voice of mix.cued) {
+        if (voice.state === 'done' || !mix.aims(voice, subject))
+            continue;
+        if (shapeOf(mix, voice, subject, from, to, plan))
+            continue;
+        for (const slot of voice.slots)
+            plan.unknown.add(slot);
+    }
+    for (const [slot, knots] of plan.knots)
+        plan.knots.set(slot, knots.sort((a, b) => a - b).filter((t, i, all) => i === 0 || t !== all[i - 1]));
+    return plan;
+}
+/** The most breakpoints one voice may add to a window before it is read on the grid instead. */
+const MOST = 4096;
+/**
+ * Adds a voice's breakpoints for one subject to `plan`, and returns true, where its shape is known
+ * through the window: a `keys` voice on its own clock at a steady rate and a number weight. Returns
+ * false, adding nothing, for any other.
+ */
+function shapeOf(mix, voice, subject, from, to, plan) {
+    const spec = voice.spec;
+    const built = voice.built;
+    const patch = voice.patch;
+    if (patch.form !== 'keys' || built === null || patch.step !== undefined)
+        return false;
+    if (typeof spec.weight === 'function' || voice.owner !== null || voice.holding !== null)
+        return false;
+    if (voice.fitting !== null || voice.arc !== null || voice.blend !== null)
+        return false;
+    if (spec.anchor !== undefined || spec.role !== undefined || spec.within !== undefined)
+        return false;
+    if (spec.stepMs !== undefined || spec.from !== undefined)
+        return false;
+    if (voice.ramp !== null || !(voice.rate > 0) || voice.out !== null || voice.back !== null)
+        return false;
+    if (voice.parts !== null || voice.parted !== null || voice.left !== null)
+        return false;
+    if (Number.isFinite(voice.outAt) || voice.state === 'fading')
+        return false;
+    // Under a mix rate, a waiting voice's start is pinned to the host's clock, where a ramp moves it.
+    if (voice.state === 'pending' && mix.transport.pace !== null)
+        return false;
+    const knots = [];
+    const bent = [];
+    const bentBy = new Map();
+    const at = (t) => {
+        if (t > from && t < to)
+            knots.push(t);
+    };
+    const reduced = mix.reduced;
+    const held = voice.sharing ? undefined : voice.subjects.get(subject);
+    const delay = held?.delay ?? (spec.stagger ? spec.stagger(subject) : 0);
+    const time = (raw) => voice.timeAt(raw + delay);
+    const fadeIn = reduced ? 0 : (voice.fade.in ?? 0);
+    if (fadeIn > 0) {
+        // Where its fade in counts from is known only once the subject has met the voice.
+        if (held === undefined)
+            return false;
+        if (held.shown + fadeIn > from) {
+            bent.push([held.shown, held.shown + fadeIn]);
+            at(held.shown);
+            at(held.shown + fadeIn);
+        }
+    }
+    const duration = voice.duration;
+    const span = voice.span;
+    at(voice.start);
+    at(time(0));
+    if (Number.isFinite(span))
+        at(time(span));
+    const ends = voice.endsAt();
+    at(ends);
+    if (!voice.freezesAfter && Number.isFinite(ends)) {
+        const over = reduced ? 0 : Number.isNaN(voice.outOver) ? (voice.fade.out ?? 0) : voice.outOver;
+        if (over > 0) {
+            bent.push([ends, ends + over]);
+            at(ends + over);
+        }
+        // It leaves when its latest subject ends, which a subject first met later can move.
+        if (spec.stagger !== undefined)
+            bent.push([time(span), Number.POSITIVE_INFINITY]);
+    }
+    if (duration > 0) {
+        const first = Math.max(0, Math.floor((voice.elapsedAt(from) - delay) / duration));
+        const last = Math.min(Math.ceil(voice.passes) - 1, Math.floor((voice.elapsedAt(to) - delay) / duration));
+        let stops = 0;
+        for (const track of built.tracks)
+            stops += track.all.length + 1;
+        if ((last - first + 1) * stops > MOST)
+            return false;
+        for (let pass = first; pass <= last; pass++) {
+            const base = pass * duration;
+            at(time(base));
+            at(time(base + duration));
+            for (const track of built.tracks) {
+                const slot = mix.slotOf.get(track.channel);
+                if (track.numbers === null)
+                    return false;
+                const wait = track.delay;
+                if (wait >= duration)
+                    continue;
+                if (wait > 0)
+                    at(time(base + wait));
+                let before = Number.NaN;
+                for (const pt of track.all) {
+                    const t = time(base + wait + Math.min(1, Math.max(0, pt.at)) * (duration - wait));
+                    at(t);
+                    if (!Number.isNaN(before) && !straight(pt.ease)) {
+                        const list = bentBy.get(slot);
+                        if (list === undefined)
+                            bentBy.set(slot, [[before, t]]);
+                        else
+                            list.push([before, t]);
+                    }
+                    before = t;
+                }
+            }
+        }
+    }
+    for (const slot of voice.slots) {
+        const times = plan.knots.get(slot);
+        if (times === undefined)
+            plan.knots.set(slot, [...knots]);
+        else
+            times.push(...knots);
+        plan.writers.set(slot, (plan.writers.get(slot) ?? 0) + 1);
+        const mine = [...bent, ...(bentBy.get(slot) ?? [])];
+        if (mine.length === 0)
+            continue;
+        const list = plan.bent.get(slot);
+        if (list === undefined)
+            plan.bent.set(slot, mine);
+        else
+            list.push(...mine);
+    }
+    return true;
+}

package/dist/transport.d.ts

@@ -31,14 +31,6 @@ export interface Frame {
     at: number;
     u: number;
 }
-/** Where history is cut for a seek or read: what frame `seq` made, and before it, is kept. */
-export interface Cut {
-    seq: number;
-    /** For a read of what a frame showed: of that frame's own changes, only those made before it was read. */
-    strict: boolean;
-}
-/** Whether a change made in frame `seq` falls inside `cut`; `early` for one made before the frame was read. */
-export declare function within(cut: Cut, seq: number, early?: boolean): boolean;
 /**
  * The clock its mixes play on: host time less what `rebase` took out, at the rate its `pace`
  * sets, moved by `sync` and `seek`, and the tape of calls a seek plays again. A mix made alone

package/dist/transport.js

@@ -11,10 +11,6 @@ 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. */
-export function within(cut, seq, early = false) {
-    return seq < cut.seq || (seq === cut.seq && (!cut.strict || early));
-}
 /**
  * The clock its mixes play on: host time less what `rebase` took out, at the rate its `pace`
  * sets, moved by `sync` and `seek`, and the tape of calls a seek plays again. A mix made alone

package/dist/turns.d.ts

@@ -7,11 +7,12 @@ export declare function shortWay(d: number, turn: number): number;
  * `fold`, which takes its axes as one value.
  */
 export declare function turnInto(ch: Laned, values: Float64Array, base: number, value: unknown, w: number): void;
-/** `turnInto` for a value held as numbers at `from` in `source`, as a locus holds what it gathered. */
+/** `turnInto` for a value held as numbers at `from` in `source`, as a role holds what it gathered. */
 export declare function turnFrom(ch: Laned, values: Float64Array, base: number, source: Float64Array, from: number, w: number): void;
 /**
- * A locus member's rotation lerped by `u` into what the members before it left at `base`, through
- * the channel's own `lerp`; the first member's value as it is, where `taken` is 0.
+ * A role member's value for a channel not lerped straight across, lerped by `u` into what the
+ * members before it left at `base` through the channel's own `lerp`, or an angle's short way round;
+ * the first member's value as it is, where `taken` is 0.
  */
 export declare function turnToward(ch: Laned, values: Float64Array, base: number, value: unknown, taken: number, u: number): void;
 /** Sets every numbered subject's values on a lane to the channel's rest, as a fill starts from. */

package/dist/turns.js

@@ -28,7 +28,7 @@ export function turnInto(ch, values, base, value, w) {
     for (let a = 0; a < axes; a++)
         values[base + a] = out[a];
 }
-/** `turnInto` for a value held as numbers at `from` in `source`, as a locus holds what it gathered. */
+/** `turnInto` for a value held as numbers at `from` in `source`, as a role holds what it gathered. */
 export function turnFrom(ch, values, base, source, from, w) {
     if (ch.turn > 0) {
         turnInto(ch, values, base, source[from], w);
@@ -38,8 +38,9 @@ export function turnFrom(ch, values, base, source, from, w) {
     turnInto(ch, values, base, other, w);
 }
 /**
- * A locus member's rotation lerped by `u` into what the members before it left at `base`, through
- * the channel's own `lerp`; the first member's value as it is, where `taken` is 0.
+ * A role member's value for a channel not lerped straight across, lerped by `u` into what the
+ * members before it left at `base` through the channel's own `lerp`, or an angle's short way round;
+ * the first member's value as it is, where `taken` is 0.
  */
 export function turnToward(ch, values, base, value, taken, u) {
     if (ch.turn > 0) {

package/dist/types/arc.d.ts

@@ -1,7 +1,7 @@
 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.
+ * One voice of an arc's part. It is 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
  */
@@ -13,15 +13,15 @@ export interface ArcVoice<I, O, H = unknown> extends Omit<VoiceSpec<I, O, H>, 'o
     duration?: number;
 }
 /**
- * One part of an arc: a voice, or several layered together that play as one and last as long as
- * the longest.
+ * One part of an arc. It is 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.
+ * What `arc` takes. It is an owner over three parts that hand over in order, `enter`, `active`
+ * and `exit`, any of which may be left out.
  *
  * @category score
  */
@@ -33,22 +33,23 @@ export interface ArcSpec<I, O, H = unknown> extends Omit<OwnerSpec<I, H>, 'freez
     /** 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`.
+     * How long `active` plays, ms on the arc's clock, or `'open'`. A number loops `active` for it
+     * unless its `loop` says how many passes; `'open'` plays it 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.
+ * An arc's handle, which can release its hold. It is an owner's handle, and `release` ends the
+ * 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
+     * Ends the hold now and plays the exit. Its blend starts 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/channel.d.ts

@@ -5,9 +5,9 @@
  */
 export interface Channel<V> {
     /**
-     * Names this channel's arithmetic, so a patch written against one channel can be checked against
-     * another of the same name. Two channels of one kind must fold identically; the stock ones set it,
-     * as `'sum'` or `'vec(3, sum)'`. Absent, a channel matches only itself.
+     * Names this channel's arithmetic. A patch written against one channel can then be checked
+     * against another of the same name. Two channels of one kind must fold identically; the stock
+     * ones set it, as `'sum'` or `'vec(3, sum)'`. Absent, a channel matches only itself.
      */
     kind?: string;
     /**
@@ -16,21 +16,25 @@ export interface Channel<V> {
      * carries speed can push it out; overshoot stops flat at the bound.
      */
     bounds?: readonly [min: number, max: number];
-    /** Identity. Absent means the channel has none: it replaces rather than contributes. */
+    /**
+     * The value that changes nothing when folded in, such as 0 for `sum` or 1 for `mul`. Absent means
+     * the channel has none: it replaces rather than contributes.
+     */
     rest?: V;
     /** Fold two contributions into one. */
     merge(a: V, b: V): V;
     /** Fade toward `rest` by weight 0..1. Required when `rest` is set; absent otherwise. */
     scale?(v: V, w: number): V;
-    /** Interpolate, for retargeting, for blending alternatives, and for folding a locus. */
+    /** Interpolate, for retargeting, for blending alternatives, and for folding a role. */
     lerp(a: V, b: V, u: number): V;
     /**
-     * Optional: `merge(into, scale(v, w))`, written into `into` and returned, so a channel whose
-     * values are objects need not allocate per contribution. The mix only hands it a value it made.
+     * Folds a weighted contribution into `into` in place. Optional. It computes
+     * `merge(into, scale(v, w))`, written into `into` and returned, so a channel whose values are
+     * objects need not allocate per contribution. The mix only hands it a value it made.
      */
     fold?(into: V, v: V, w: number): V;
     /**
-     * Optional: a fresh copy of `v`, which the mix makes of `rest` for `fold` to write into. The mix
+     * A fresh copy of `v`. Optional. The mix makes one of `rest` for `fold` to write into. The mix
      * copies arrays, typed arrays and plain objects itself; a channel whose `rest` is anything else,
      * such as a class instance, and that has `fold`, needs this or `cue` refuses it.
      */

package/dist/types/history.d.ts

@@ -1,6 +1,6 @@
 import type { VoiceSpec } from './voice.js';
 /**
- * What a mix or transport remembers, for `seek` and `project` to read back: see
+ * What a mix or transport remembers, for `seek` and `project` to read back. See
  * `MixOptions.history`.
  *
  * @category mix
@@ -17,11 +17,11 @@ export interface HistoryOptions {
      * the tape: the host bounds it.
      */
     store?: HistoryStore;
-    /** Rebuilds a cued voice's spec from the descriptor it was cued with, so the voice can be paged out. */
+    /** Rebuilds a cued voice's spec from its descriptor. That lets the voice be paged out. */
     revive?(d: Described): VoiceSpec<any, any>;
 }
 /**
- * A voice as plain data: `kind` names what built it, and `data` survives `structuredClone`.
+ * A voice as plain data. `kind` names what built it, and `data` survives `structuredClone`.
  *
  * @category mix
  */
@@ -39,21 +39,23 @@ export interface HistoryStore {
     /** Records leaving memory. One brought back by a seek may be paged again: keep one per key and `seq`. */
     page(out: readonly Paged[]): void;
     /**
-     * What a restore to mix time `t` needs, for every mix: from each stream, per voice and subject,
-     * the latest record at or before `t` and every record after it. Returning everything is fine.
+     * Loads what a restore to mix time `t` needs, for every mix. That is, from each stream, per voice
+     * and subject, the latest record at or before `t` and every record after it. Returning
+     * everything is fine.
      */
     load(t: number): Promise<readonly Paged[]>;
     /**
-     * A seek went back to frame `seq`: every record whose `seq` is greater is from a future the tape
-     * makes again. Forget them.
+     * Forgets every record after frame `seq`, which a seek went back to. Every record whose `seq` is
+     * greater is from a future the tape makes again.
      */
     cut(seq: number): void;
 }
 /**
- * What a history record holds: a voice's `controls`, a stateful record's `snap`, an `input`
- * signal's reading, a subject's record when it `left` a voice, a motion subject's `released` run
- * or older `stretch`, the `host` fields patches read, a whole `voice` that has left, or the
- * transport's own: a `mark` announced on it, a change of its `pace`, and a `frame` it played.
+ * Which kind of thing a history record holds. It is a voice's `controls`, a stateful record's
+ * `snap`, an `input` signal's reading, a subject's record when it `left` a voice, a motion
+ * subject's `released` run or older `stretch`, the `host` fields patches read, a whole `voice`
+ * that has left, or the transport's own: a `mark` announced on it, a change of its `pace`, and a
+ * `frame` it played.
  *
  * @category mix
  */
@@ -64,12 +66,17 @@ export type PagedStream = 'voice' | 'snap' | 'input' | 'left' | 'released' | 'st
  * @category mix
  */
 export interface Paged {
-    /** The mix's `name`; '' for a mix made alone without one, and for the transport's own records. */
+    /**
+     * The mix's `name`. It is '' for a mix made alone without one, and for the transport's own
+     * records.
+     */
     mix: string;
     stream: PagedStream;
     /** The voice's id, for every stream but `host` and the transport's own. */
     voice?: number;
-    /** The subject's key, for a record of one subject; for a `mark`, the number it was announced as. */
+    /**
+     * The subject's key, for a record of one subject. For a `mark`, the number it was announced as.
+     */
     subject?: string | number;
     /** Mix time. */
     at: number;
@@ -81,7 +88,7 @@ export interface Paged {
     data: unknown;
 }
 /**
- * One host call a mix recorded on its tape: `apply` makes it again, and `invert` does nothing,
+ * One host call a mix recorded on its tape. `apply` makes it again, and `invert` does nothing,
  * since a mix goes back by restoring what it kept rather than by undoing calls.
  *
  * @category mix
@@ -92,8 +99,8 @@ export interface TapeOp {
     label?: string;
 }
 /**
- * One future a tape keeps at its current entry: the calls the host made after the mix last went
- * back here, before it made new ones.
+ * One future a tape keeps at its current entry. It holds the calls the host made after the mix
+ * last went back here, before it made new ones.
  *
  * @category mix
  */
@@ -126,14 +133,23 @@ export interface Tape {
     switchBranch(id: number): void;
 }
 /**
- * Makes a mix's tape: weasel-history's `createHistory` is one. The mix passes the clock it stamps
+ * Makes a mix's tape. weasel-history's `createHistory` is one. The mix passes the clock it stamps
  * calls with, branching on, so a call made after going back keeps the old future as a branch, and
  * coalescing off.
  *
  * @category mix
  */
-export type TapeMaker = (adapter: unknown, opts: {
+export type TapeMaker = (adapter: unknown, opts: TapeOptions) => Tape;
+/**
+ * What a mix passes its `TapeMaker` besides the adapter.
+ *
+ * @category mix
+ */
+export interface TapeOptions {
+    /** The clock the tape stamps calls with. */
     now: () => number;
+    /** Always `true`, so a call made after going back keeps the old future as a branch. */
     branching: boolean;
+    /** Always `0`, which turns coalescing off. */
     coalesceWindowMs: number;
-}) => Tape;
+}