@msb235/blits 0.7.1 → 0.8.0

package/dist/transport.js

@@ -1,7 +1,7 @@
 import { listedAll } from './marks.js';
 import { move, nextFrame, waits } from './move.js';
 import { Pace } from './pace.js';
-import { Pager, prepare } from './paging.js';
+import { Pager, pageTransport, prepare } from './paging.js';
 import { pin } from './place.js';
 import { projectAll } from './project.js';
 import { scoredDrop, scoredJoin } from './scored.js';
@@ -9,6 +9,10 @@ import { seek } from './seek.js';
 import { record, replay, tapeOf } from './tape.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
@@ -29,6 +33,13 @@ export class Transport {
     woken = false;
     /** The mix clock at the last sync or seek. */
     now = Number.NaN;
+    /**
+     * The number of the frame being played: each sync and seek begins one, and so does each host
+     * time the tape plays calls again at.
+     */
+    seq = 0;
+    /** Under history, the frames a seek or read back may reach, oldest first. */
+    frames = [];
     /** Host time at the last sync: the host's timestamp less every gap `rebase` took out. */
     u = Number.NaN;
     offset = 0;
@@ -42,6 +53,20 @@ export class Transport {
     taped = Number.NEGATIVE_INFINITY;
     /** The rate; null while it has never been set, when mix time is host time. */
     pace = null;
+    /** The latest mix time a voice any mix on it let go of from `gone` had left at. */
+    forgotTo = Number.NEGATIVE_INFINITY;
+    /**
+     * The latest mix time a host changed a mix on it, or a voice or a subject left one: without
+     * history, the earliest time a read back still finds the mixes as they stand now.
+     */
+    settled = Number.NEGATIVE_INFINITY;
+    /** Records a change or a leaving at the mix time now; before the first sync, nothing. */
+    settle() {
+        if (this.now > this.settled)
+            this.settled = this.now;
+    }
+    /** The frame the rate was first set in, which a seek or read back to before it finds unset. */
+    pacedSeq = Number.POSITIVE_INFINITY;
     /** True while the tape makes a recorded call again, so it is not recorded twice. */
     replaying = false;
     announced = [];
@@ -64,7 +89,7 @@ export class Transport {
     get projecting() {
         return this.members.some((m) => m.projecting);
     }
-    /** Takes a mix on, after every mix that joined before it; `slot` keeps a copy's in place. */
+    /** Takes a mix on, after every mix that joined before it; `slot` keeps one a seek puts back in place. */
     join(mix, slot = this.slots++) {
         mix.slot = slot;
         const i = this.members.findIndex((m) => m.slot > slot);
@@ -83,16 +108,16 @@ export class Transport {
         scoredDrop(m);
         m.dropped = true;
         if (this.history !== undefined) {
-            this.dropped.push({ mix: m, at: this.now });
+            this.dropped.push({ mix: m, at: this.now, seq: this.seq });
             record(this, 'drop', () => this.drop(mix));
         }
     }
-    /** A seek back to `t`: every mix dropped after it is back on, as it stood then. */
-    undrop(t) {
-        const back = this.dropped.filter((d) => d.at > t);
+    /** A seek back to frame `seq`: every mix dropped after it is back on, as it stood then. */
+    undrop(seq) {
+        const back = this.dropped.filter((d) => d.seq > seq);
         if (back.length === 0)
             return;
-        this.dropped = this.dropped.filter((d) => d.at <= t);
+        this.dropped = this.dropped.filter((d) => d.seq <= seq);
         for (const d of back) {
             d.mix.dropped = false;
             this.join(d.mix, d.mix.slot);
@@ -151,6 +176,8 @@ export class Transport {
         }
     }
     syncAt(timestamp) {
+        if (Number.isNaN(timestamp))
+            throw new RangeError('blits: sync was given NaN; it takes the host clock as a number');
         if (timestamp < this.last && !this.rebasing)
             throw new RangeError(`blits: sync went back from ${this.last} to ${timestamp}; the host's clock only goes forward, and seek moves the mix`);
         if (this.rebasing && !Number.isNaN(this.last))
@@ -167,17 +194,21 @@ export class Transport {
             this.born = now;
         // Calls the host made before, played again where a seek went back past them; one may set the
         // rate, which moves where this sync lands.
-        if (this.tape !== undefined && now > this.now) {
-            const reading = () => (this.pace === null ? u : this.pace.reading(u));
-            replay(this, reading);
+        // A call played again at this sync's own host time began its frame, moved there before it.
+        let begun = false;
+        if (this.tape !== undefined && later) {
+            begun = replay(this, (at) => at <= u) === u;
             pace = this.pace;
-            now = reading();
+            now = pace === null ? u : pace.reading(u);
+        }
+        if (!begun) {
+            this.tick(now);
+            // Host time moving while the mix clock stands still lands what waits on host time or the host.
+            const moved = now !== this.now;
+            for (const m of this.members)
+                if (moved || (later && pace !== null && waits(m)))
+                    move(m, now);
         }
-        // Host time moving while the mix clock stands still lands what waits on host time or the host.
-        const moved = now !== this.now;
-        for (const m of this.members)
-            if (moved || (later && pace !== null && waits(m)))
-                move(m, now);
         const history = this.history;
         this.kept();
         const reach = this.keepsFrom();
@@ -189,6 +220,13 @@ export class Transport {
         }
         if (history !== undefined && this.dropped.length > 0)
             this.dropped = this.dropped.filter((d) => d.at >= reach);
+        const frames = this.frames;
+        let n = 0;
+        while (n + 1 < frames.length && frames[n + 1].at <= reach)
+            n++;
+        if (n > 0)
+            frames.splice(0, n);
+        pageTransport(this);
         this.woken = false;
         // It is a frame too, which asks every weight signal again, so one reading input follows it.
         if (still)
@@ -203,8 +241,38 @@ export class Transport {
                     b.sync();
         }
     }
+    /** Begins a frame at mix time `at` and the host time the transport stands at. */
+    tick(at) {
+        const seq = ++this.seq;
+        if (this.history !== undefined)
+            this.frames.push({ seq, at, u: this.u });
+        for (const m of this.members)
+            m.looked = false;
+    }
+    /**
+     * The frame a seek or read to mix time `t` lands on: the last one standing at or before `t`,
+     * since rate 0 can hold the clock at `t` for many.
+     */
+    frameAt(t) {
+        const frames = this.frames;
+        let lo = 0;
+        let hi = frames.length - 1;
+        let found;
+        while (lo <= hi) {
+            const mid = (lo + hi) >> 1;
+            const f = frames[mid];
+            if (f.at <= t) {
+                found = f;
+                lo = mid + 1;
+            }
+            else
+                hi = mid - 1;
+        }
+        return found;
+    }
     rebase() {
         this.rebasing = true;
+        this.settle();
     }
     /**
      * Moves `floor` past what the mix clock standing at `now` has let go of. With a store nothing is
@@ -242,6 +310,7 @@ export class Transport {
             throw new RangeError(`blits: a mix's rate is a finite number, 0 or more, not ${rate}`);
         if (this.pace === null) {
             this.pace = new Pace(this.history !== undefined);
+            this.pacedSeq = this.seq;
             // Until now mix time was host time, so a pending voice's start is the host time it was given.
             for (const m of this.members)
                 for (const v of m.cued)
@@ -249,7 +318,7 @@ export class Transport {
                         pin(m, v, v.start);
         }
         const reach = this.history === undefined ? Number.NEGATIVE_INFINITY : this.keepsFrom();
-        this.pace.change(this.u, rate, over, reach);
+        this.pace.change(this.u, rate, over, reach, this.seq);
         for (const m of this.members)
             m.stir();
         record(this, 'rate', () => this.ramp(rate, over));
@@ -263,14 +332,15 @@ export function announce(transport, name, opts, slot, mix) {
         score: opts.score,
         tags: opts.tags ?? [],
         at,
-        made: Number.isNaN(transport.now) ? Number.NEGATIVE_INFINITY : transport.now,
         order: transport.nextId++,
+        seq: transport.seq,
         slot,
         mix,
     };
     transport.announced.push(mark);
+    transport.settle();
     record(transport, 'announce', () => {
-        transport.announced.push({ ...mark });
+        transport.announced.push({ ...mark, seq: transport.seq });
     });
 }
 /**

package/dist/turns.d.ts

@@ -0,0 +1,18 @@
+import type { Laned } from './lane.js';
+/** `d` less whole turns, so within half a turn of 0: the short way round a circle of `turn`. */
+export declare function shortWay(d: number, turn: number): number;
+/**
+ * Folds a rotation's value into a subject's numbers at `base`, at weight `w`, in the channel's own
+ * arithmetic: an angle the short way round and then as a sum, anything else through the channel's
+ * `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. */
+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.
+ */
+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. */
+export declare function rested(ch: Laned, size: number): void;

package/dist/turns.js

@@ -0,0 +1,72 @@
+import { doubles } from './channels.js';
+/** `d` less whole turns, so within half a turn of 0: the short way round a circle of `turn`. */
+export function shortWay(d, turn) {
+    return d - turn * Math.round(d / turn);
+}
+let held = doubles(4, 0);
+let other = doubles(4, 0);
+/** A subject's numbers on a lane as an array a channel's own functions take: `to`, or one as long. */
+function lift(values, base, axes, to) {
+    const out = to.length === axes ? to : doubles(axes, 0);
+    for (let a = 0; a < axes; a++)
+        out[a] = values[base + a];
+    return out;
+}
+/**
+ * Folds a rotation's value into a subject's numbers at `base`, at weight `w`, in the channel's own
+ * arithmetic: an angle the short way round and then as a sum, anything else through the channel's
+ * `fold`, which takes its axes as one value.
+ */
+export function turnInto(ch, values, base, value, w) {
+    if (ch.turn > 0) {
+        values[base] = values[base] + shortWay(value, ch.turn) * w;
+        return;
+    }
+    const axes = ch.axes;
+    held = lift(values, base, axes, held);
+    const out = ch.channel.fold(held, 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. */
+export function turnFrom(ch, values, base, source, from, w) {
+    if (ch.turn > 0) {
+        turnInto(ch, values, base, source[from], w);
+        return;
+    }
+    other = lift(source, from, ch.axes, other);
+    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.
+ */
+export function turnToward(ch, values, base, value, taken, u) {
+    if (ch.turn > 0) {
+        const was = values[base];
+        const v = value;
+        values[base] = taken === 0 ? v : was + shortWay(v - was, ch.turn) * u;
+        return;
+    }
+    const axes = ch.axes;
+    let out = value;
+    if (taken !== 0) {
+        held = lift(values, base, axes, held);
+        out = ch.channel.lerp(held, value, u);
+    }
+    for (let a = 0; a < axes; a++)
+        values[base + a] = out[a];
+}
+/** Sets every numbered subject's values on a lane to the channel's rest, as a fill starts from. */
+export function rested(ch, size) {
+    const values = ch.values;
+    const axes = ch.axes;
+    if (ch.op !== 'own') {
+        values.fill(ch.rest, 0, size * axes);
+        return;
+    }
+    const start = ch.start;
+    for (let i = 0; i < size * axes; i += axes)
+        for (let a = 0; a < axes; a++)
+            values[i + a] = start[a];
+}

package/dist/tweened.js

@@ -5,7 +5,7 @@ const SPAN = 1e-4;
  * `read` asks for it; a mix and a retarget never use it.
  */
 let slope = false;
-/** The last tween sample's time, curve and length, and the share of the way it had left to go. */
+/** The last tween sample's progress and curve, and the share of the way it had left to go. */
 const memo = { u: Number.NaN, ease: undefined, left: 0 };
 /** Turns the velocity `eased` works out on or off. */
 export function sloped(on) {

package/dist/types/channel.d.ts

@@ -0,0 +1,46 @@
+/**
+ * One field of a delta, with its own arithmetic.
+ *
+ * @category channel
+ */
+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.
+     */
+    kind?: string;
+    /**
+     * The range a numeric value means anything in, such as 0..1 for an opacity. The mix clamps the
+     * folded value to it, axis by axis for an array, so neither stacked voices nor a retarget that
+     * 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. */
+    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. */
+    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.
+     */
+    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
+     * 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.
+     */
+    copy?(v: V): V;
+}
+/**
+ * The channel set for one kind of delta.
+ *
+ * @category channel
+ */
+export type Kit<O> = {
+    readonly [K in keyof O]-?: Channel<NonNullable<O[K]>>;
+};

package/dist/types/channel.js

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

package/dist/types/history.d.ts

@@ -0,0 +1,139 @@
+import type { VoiceSpec } from './voice.js';
+/**
+ * What a mix or transport remembers, for `seek` and `project` to read back: see
+ * `MixOptions.history`.
+ *
+ * @category mix
+ */
+export interface HistoryOptions {
+    /** How much stays in memory, ms of mix time. With a `store`, the rest is paged out, not dropped. */
+    ms: number;
+    every?: number;
+    inputs?: boolean;
+    tape?: TapeMaker;
+    /**
+     * Where history older than `ms` goes instead of being dropped. A `seek` or `project` reaching
+     * past memory needs `prepare` first, or throws `HistoryMiss`. With a store, blits never prunes
+     * 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. */
+    revive?(d: Described): VoiceSpec<any, any>;
+}
+/**
+ * A voice as plain data: `kind` names what built it, and `data` survives `structuredClone`.
+ *
+ * @category mix
+ */
+export interface Described {
+    kind: string;
+    data: unknown;
+}
+/**
+ * Where a history `store` keeps what memory let go of. blits decides what is kept and when it is
+ * read back; the store decides where it lives.
+ *
+ * @category mix
+ */
+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.
+     */
+    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.
+     */
+    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.
+ *
+ * @category mix
+ */
+export type PagedStream = 'voice' | 'snap' | 'input' | 'left' | 'released' | 'stretch' | 'host' | 'controls' | 'mark' | 'pace' | 'frame';
+/**
+ * One history record leaving memory, as plain data.
+ *
+ * @category mix
+ */
+export interface Paged {
+    /** The mix's `name`; '' 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. */
+    subject?: string | number;
+    /** Mix time. */
+    at: number;
+    /**
+     * The transport's frame it was made in. Rate 0 holds mix time still across frames, and a fade
+     * given a time already passed is filed behind the frame that decided it, so a cut goes by this.
+     */
+    seq: number;
+    data: unknown;
+}
+/**
+ * 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
+ */
+export interface TapeOp {
+    apply(adapter: unknown): void;
+    invert(): 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.
+ *
+ * @category mix
+ */
+export interface TapeBranch {
+    /** Its first entry's id, which `switchBranch` takes. */
+    id: number;
+    label: string;
+    timestamp: number;
+    /** How many entries run along it from here. */
+    length: number;
+    /** Whether the mix plays it on from here. */
+    current: boolean;
+}
+/**
+ * Where a mix keeps the host's calls, by host time, for `seek`. weasel-history's `History`
+ * (`@weasel-js/history`) has this shape. A host reads `branches` and calls `switchBranch` to pick
+ * which recorded future plays on; moving it any other way is the mix's job.
+ *
+ * @category mix
+ */
+export interface Tape {
+    recordEntry(ops: TapeOp[], label: string): void;
+    undoDepth(): number;
+    timestampAt(i: number): number | undefined;
+    depthAt(t: number): number;
+    goto(n: number): void;
+    redo(): void;
+    prune(t: number): void;
+    branches(): readonly TapeBranch[];
+    switchBranch(id: number): void;
+}
+/**
+ * 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: {
+    now: () => number;
+    branching: boolean;
+    coalesceWindowMs: number;
+}) => Tape;

package/dist/types/history.js

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