@msb235/blits 0.5.0 → 0.7.0

package/dist/tape.js

@@ -0,0 +1,65 @@
+import { move } from './move.js';
+/** What a recorded call's `invert` gives: a mix goes back by restoring, never by undoing a call. */
+const undone = { apply() { }, invert: () => undone };
+/** The tape `history.tape` makes for a transport, stamping each call with the mix time it was made at. */
+export function tapeOf(transport) {
+    const make = transport.history?.tape;
+    if (make === undefined)
+        return undefined;
+    return make(transport, {
+        now: () => (Number.isNaN(transport.now) ? Number.NEGATIVE_INFINITY : transport.now),
+        branching: true,
+        coalesceWindowMs: 0,
+    });
+}
+/** Records a host call, which `again` makes once more when the mix plays past it after a seek. */
+export function record(on, label, again) {
+    const tape = on.tape;
+    if (tape === undefined || on.replaying || on.projecting)
+        return;
+    const op = {
+        label,
+        apply() {
+            again();
+        },
+        invert: () => undone,
+    };
+    tape.recordEntry([op], label);
+}
+/** The host time at which the mix clock reads `t`, under the rate it has now. */
+export function hostAt(clock, t) {
+    return clock.pace === null ? t : clock.pace.timeOf(t);
+}
+/**
+ * Makes the recorded calls due by mix time `to()` again, each with every mix on the transport
+ * moved to the time it was made at, as the host made it then. `to` is asked again after every
+ * call, since a call may change the rate and so where a host time lands.
+ */
+export function replay(transport, to) {
+    const tape = transport.tape;
+    if (tape === undefined)
+        return;
+    const u = transport.u;
+    try {
+        for (;;) {
+            const at = tape.timestampAt(tape.undoDepth());
+            if (at === undefined || !(at <= to()))
+                return;
+            if (at > transport.now) {
+                transport.u = hostAt(transport, at);
+                for (const m of transport.members)
+                    move(m, at);
+            }
+            transport.replaying = true;
+            try {
+                tape.redo();
+            }
+            finally {
+                transport.replaying = false;
+            }
+        }
+    }
+    finally {
+        transport.u = u;
+    }
+}

package/dist/ticker.d.ts

@@ -0,0 +1,73 @@
+/**
+ * What a ticker runs: a mix, or anything that syncs, sleeps on `inert` and wakes by `onWake`.
+ *
+ * @category mix
+ */
+export interface Ticked {
+    sync(timestamp: number): void;
+    readonly inert: boolean;
+    onWake(fn: () => void): () => void;
+}
+/**
+ * How a ticker paces its frames and reads its clock.
+ *
+ * @category mix
+ */
+export interface TickerOptions {
+    /**
+     * The most frames a second it syncs. Under animation frames it skips a frame that comes sooner
+     * than that, on a grid, so a 60 Hz display capped at 30 runs every other frame. Under a timer it
+     * is the timer's rate, 60 unless given.
+     */
+    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.
+     */
+    grain?: 'frame' | 'timer';
+    /**
+     * The clock every mix is synced by. By default an animation frame's own timestamp, or
+     * `performance.now()` under a timer. A worker's `performance.now()` counts from its own origin,
+     * not the page's.
+     */
+    now?: () => number;
+    /** Stands in for `requestAnimationFrame`, as in a test. */
+    raf?: (callback: (timestamp: number) => void) => number;
+    /** Stands in for `cancelAnimationFrame`. */
+    caf?: (id: number) => void;
+}
+/**
+ * One frame loop that syncs the mixes added to it.
+ *
+ * @category mix
+ */
+export interface Ticker {
+    /**
+     * Syncs `mix` every frame from now on, and wakes the loop on its `onWake`. Asks for a frame, even
+     * for a mix it already holds. Returns a remove.
+     */
+    add(mix: Ticked): () => void;
+    /** Calls `fn` each frame, after every mix has synced, with the frame's timestamp. Returns an unsubscribe. */
+    after(fn: (timestamp: number) => void): () => void;
+    /** Keeps frames coming whatever the mixes say, until the returned release is called. */
+    hold(): () => void;
+    /** Cancels the waiting frame; `wake`, a mix waking, `hold` or `add` starts the loop again. */
+    stop(): void;
+    /**
+     * Asks for a frame, after which the loop runs or sleeps as the mixes say. A mix changed before
+     * `stop` and not synced since does not wake the loop by itself, since it fires `onWake` once
+     * between syncs.
+     */
+    wake(): void;
+    /** What the ticker's clock reads now. */
+    now(): number;
+}
+/**
+ * One frame loop for any number of mixes. It runs while a mix would still change or something
+ * holds it, and sleeps otherwise, until a mix wakes it. A mix or `after` callback that throws stops
+ * neither the loop nor the others: its error is thrown again on a microtask.
+ *
+ * @category mix
+ */
+export declare function ticker(opts?: TickerOptions): Ticker;

package/dist/ticker.js

@@ -0,0 +1,115 @@
+/** Slack under the interval that still counts as due, for a display whose frames jitter. */
+const SLACK = 1;
+/**
+ * One frame loop for any number of mixes. It runs while a mix would still change or something
+ * holds it, and sleeps otherwise, until a mix wakes it. A mix or `after` callback that throws stops
+ * neither the loop nor the others: its error is thrown again on a microtask.
+ *
+ * @category mix
+ */
+export function ticker(opts = {}) {
+    const g = globalThis;
+    const perfNow = () => (g.performance === undefined ? Date.now() : g.performance.now());
+    const byFrame = opts.raf !== undefined ||
+        (opts.grain !== 'timer' && typeof g.requestAnimationFrame === 'function');
+    const fps = opts.fps ?? (byFrame ? undefined : 60);
+    if (fps !== undefined && !(fps > 0 && fps < Number.POSITIVE_INFINITY))
+        throw new RangeError(`blits: a ticker's fps is a finite number above 0, not ${fps}`);
+    const interval = fps === undefined ? 0 : 1000 / fps;
+    const mixes = [];
+    const unwakes = new Map();
+    const fns = [];
+    let holds = 0;
+    let pending = null;
+    let last = Number.NaN;
+    const now = opts.now ?? perfNow;
+    const later = (err) => g.queueMicrotask(() => {
+        throw err;
+    });
+    const request = byFrame
+        ? (opts.raf ??
+            ((cb) => g.requestAnimationFrame(cb)))
+        : (cb) => g.setTimeout(() => cb(now()), Number.isNaN(last) ? 0 : Math.max(0, last + interval - now()));
+    const cancel = byFrame
+        ? (opts.caf ?? ((id) => g.cancelAnimationFrame?.(id)))
+        : (id) => g.clearTimeout(id);
+    const schedule = () => {
+        if (pending === null)
+            pending = request(frame);
+    };
+    function frame(stamp) {
+        pending = null;
+        const t = opts.now === undefined ? stamp : opts.now();
+        // A capped loop skips a frame that comes early, and steps a grid so its rate does not drift
+        // with the display's or with a timer's rounding. A long gap, as after sleeping, starts it again.
+        if (interval > 0 && !Number.isNaN(last)) {
+            const gap = t - last;
+            if (gap < interval - SLACK) {
+                pending = request(frame);
+                return;
+            }
+            last = gap >= 2 * interval ? t : last + interval;
+        }
+        else
+            last = t;
+        for (const mix of [...mixes])
+            try {
+                mix.sync(t);
+            }
+            catch (err) {
+                later(err);
+            }
+        for (const fn of [...fns])
+            try {
+                fn(t);
+            }
+            catch (err) {
+                later(err);
+            }
+        if (holds > 0 || mixes.some((mix) => !mix.inert))
+            schedule();
+    }
+    return {
+        add(mix) {
+            if (!unwakes.has(mix)) {
+                mixes.push(mix);
+                unwakes.set(mix, mix.onWake(schedule));
+            }
+            schedule();
+            return () => {
+                const unwake = unwakes.get(mix);
+                if (unwake === undefined)
+                    return;
+                unwake();
+                unwakes.delete(mix);
+                mixes.splice(mixes.indexOf(mix), 1);
+            };
+        },
+        after(fn) {
+            fns.push(fn);
+            return () => {
+                const i = fns.indexOf(fn);
+                if (i >= 0)
+                    fns.splice(i, 1);
+            };
+        },
+        hold() {
+            holds++;
+            schedule();
+            let released = false;
+            return () => {
+                if (released)
+                    return;
+                released = true;
+                holds--;
+            };
+        },
+        stop() {
+            if (pending !== null)
+                cancel(pending);
+            pending = null;
+        },
+        wake: schedule,
+        now,
+    };
+}

package/dist/transport.d.ts

@@ -0,0 +1,121 @@
+import type { Mixer } from './mixer.js';
+import { Pace } from './pace.js';
+import { Pager } from './paging.js';
+import type { Marked, Mix, MixOptions, Tape, Transport as TransportApi, TransportOptions, TransportProjection } from './types.js';
+/**
+ * A mark the host announced on a score: `at` in host time, so the rate never moves one, and NaN
+ * until the next sync for one announced as now before any sync; `made` is the mix time it was
+ * announced, for a read back to know what was known.
+ */
+export interface Announced {
+    name: string;
+    score: string | undefined;
+    tags: readonly string[];
+    at: number;
+    made: number;
+    order: number;
+    /** The slot of the mix that announced it, -1 for the transport; only it sees an unnamed score. */
+    slot: number;
+    /** That mix's name, for `Marked.mix`. */
+    mix: string | undefined;
+}
+type Member = Mixer<unknown, unknown>;
+/**
+ * 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
+ * gets one holding only itself.
+ */
+export declare class Transport implements TransportApi {
+    readonly history: MixOptions['history'];
+    readonly shared: boolean;
+    /** The mixes on it, in the order they joined. */
+    members: Member[];
+    /** Under history, mixes dropped while a seek back may still reach them, by when. */
+    dropped: {
+        mix: Member;
+        at: number;
+    }[];
+    /** Numbers the mixes as they join, for their order and for whose unnamed score a mark is on. */
+    slots: number;
+    private wakeFns;
+    /** Whether it has woken since the last sync, so it wakes once. */
+    private woken;
+    /** The mix clock at the last sync or seek. */
+    now: number;
+    /** Host time at the last sync: the host's timestamp less every gap `rebase` took out. */
+    u: number;
+    offset: number;
+    /** The mix time of the first sync. */
+    born: number;
+    /** The earliest mix time what history keeps in memory restores exactly. */
+    floor: number;
+    last: number;
+    rebasing: boolean;
+    /** The rate; null while it has never been set, when mix time is host time. */
+    pace: Pace | null;
+    /** True while the tape makes a recorded call again, so it is not recorded twice. */
+    replaying: boolean;
+    announced: Announced[];
+    /** Numbers voices and announced marks across every member, in the order they were made. */
+    nextId: number;
+    readonly tape: Tape | undefined;
+    /** With a history store, what left memory for it; null without one. */
+    readonly pager: Pager | null;
+    /**
+     * `shared` for one the host made, whose mixes may not move it themselves; a mix made alone makes
+     * one that is not.
+     */
+    constructor(history: MixOptions['history'], shared: boolean);
+    /** Whether this is a projection's own transport, which records and seeks nothing. */
+    get projecting(): boolean;
+    /** Takes a mix on, after every mix that joined before it; `slot` keeps a copy's in place. */
+    join(mix: Member, slot?: number): void;
+    drop<I, O, H>(mix: Mix<I, O, H>): void;
+    /** A seek back to `t`: every mix dropped after it is back on, as it stood then. */
+    undrop(t: number): void;
+    seek(time: number): void;
+    prepare(time: number): Promise<void>;
+    announce(name: string, opts: {
+        at?: number;
+        score: string;
+        tags?: readonly string[];
+    }): void;
+    marks(from: number, to: number): Marked[];
+    project(time: number): TransportProjection;
+    get live(): boolean;
+    get inert(): boolean;
+    onWake(fn: () => void): () => void;
+    /** A mix on it was changed outside a sync: wakes whoever sleeps on the transport, once. */
+    woke(): void;
+    sync(timestamp: number): void;
+    private syncAt;
+    rebase(): void;
+    /**
+     * Moves `floor` past what the mix clock standing at `now` has let go of. With a store nothing is
+     * let go: what leaves memory is paged, which moves it.
+     */
+    kept(): void;
+    /** Whether history reaches back to mix time `t`, from memory. */
+    reaches(t: number): boolean;
+    /**
+     * The earliest mix time it keeps what no store pages, the tape, dropped mixes, rate changes and
+     * announced marks among them: with a store, all of it, since the host bounds the tape.
+     */
+    keepsFrom(): number;
+    get rate(): number;
+    set rate(r: number);
+    ramp(rate: number, over: number): void;
+}
+/** Puts a mark on a score: one the transport announced, or a mix on it, `slot`. */
+export declare function announce(transport: Transport, name: string, opts: {
+    at?: number;
+    score?: string;
+    tags?: readonly string[];
+}, slot: number, mix: string | undefined): void;
+/**
+ * Makes a transport several mixes can share, each made with `transport` in its options.
+ *
+ * @category mix
+ */
+export declare function transport(opts?: TransportOptions): TransportApi;
+export {};

package/dist/transport.js

@@ -0,0 +1,271 @@
+import { listedAll } from './marks.js';
+import { move, nextFrame, waits } from './move.js';
+import { Pace } from './pace.js';
+import { Pager, prepare } from './paging.js';
+import { pin } from './place.js';
+import { projectAll } from './project.js';
+import { seek } from './seek.js';
+import { record, replay, tapeOf } from './tape.js';
+/**
+ * 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
+ * gets one holding only itself.
+ */
+export class Transport {
+    history;
+    shared;
+    /** The mixes on it, in the order they joined. */
+    members = [];
+    /** Under history, mixes dropped while a seek back may still reach them, by when. */
+    dropped = [];
+    /** Numbers the mixes as they join, for their order and for whose unnamed score a mark is on. */
+    slots = 0;
+    wakeFns = [];
+    /** Whether it has woken since the last sync, so it wakes once. */
+    woken = false;
+    /** The mix clock at the last sync or seek. */
+    now = Number.NaN;
+    /** Host time at the last sync: the host's timestamp less every gap `rebase` took out. */
+    u = Number.NaN;
+    offset = 0;
+    /** The mix time of the first sync. */
+    born = Number.NaN;
+    /** The earliest mix time what history keeps in memory restores exactly. */
+    floor = Number.NEGATIVE_INFINITY;
+    last = Number.NaN;
+    rebasing = false;
+    /** The rate; null while it has never been set, when mix time is host time. */
+    pace = null;
+    /** True while the tape makes a recorded call again, so it is not recorded twice. */
+    replaying = false;
+    announced = [];
+    /** Numbers voices and announced marks across every member, in the order they were made. */
+    nextId = 1;
+    tape;
+    /** With a history store, what left memory for it; null without one. */
+    pager;
+    /**
+     * `shared` for one the host made, whose mixes may not move it themselves; a mix made alone makes
+     * one that is not.
+     */
+    constructor(history, shared) {
+        this.history = history;
+        this.shared = shared;
+        this.tape = tapeOf(this);
+        this.pager = history?.store === undefined ? null : new Pager(history.store);
+    }
+    /** Whether this is a projection's own transport, which records and seeks nothing. */
+    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. */
+    join(mix, slot = this.slots++) {
+        mix.slot = slot;
+        const i = this.members.findIndex((m) => m.slot > slot);
+        if (i < 0)
+            this.members.push(mix);
+        else
+            this.members.splice(i, 0, mix);
+    }
+    drop(mix) {
+        const m = mix;
+        const i = this.members.indexOf(m);
+        if (i < 0)
+            throw new Error(`blits: ${m.name ?? 'that mix'} is not on this transport`);
+        this.members.splice(i, 1);
+        m.dropped = true;
+        if (this.history !== undefined) {
+            this.dropped.push({ mix: m, at: this.now });
+            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);
+        if (back.length === 0)
+            return;
+        this.dropped = this.dropped.filter((d) => d.at <= t);
+        for (const d of back) {
+            d.mix.dropped = false;
+            this.join(d.mix, d.mix.slot);
+        }
+    }
+    seek(time) {
+        seek(this, time);
+    }
+    prepare(time) {
+        return prepare(this, time);
+    }
+    announce(name, opts) {
+        if (opts?.score === undefined)
+            throw new Error('blits: a transport announces on a named score, which every mix on it sees');
+        announce(this, name, opts, -1, undefined);
+    }
+    marks(from, to) {
+        return listedAll(this, from, to).map(({ order: _, ...m }) => m);
+    }
+    project(time) {
+        return projectAll(this, time);
+    }
+    get live() {
+        return this.members.some((m) => m.live);
+    }
+    get inert() {
+        return this.members.every((m) => m.inert);
+    }
+    onWake(fn) {
+        const fns = this.wakeFns;
+        fns.push(fn);
+        return () => {
+            const i = fns.indexOf(fn);
+            if (i >= 0)
+                fns.splice(i, 1);
+        };
+    }
+    /** A mix on it was changed outside a sync: wakes whoever sleeps on the transport, once. */
+    woke() {
+        if (this.woken)
+            return;
+        this.woken = true;
+        for (const fn of [...this.wakeFns])
+            fn();
+    }
+    sync(timestamp) {
+        const members = this.members;
+        for (const m of members)
+            m.syncing = true;
+        try {
+            this.syncAt(timestamp);
+        }
+        finally {
+            for (const m of members)
+                m.syncing = false;
+        }
+    }
+    syncAt(timestamp) {
+        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))
+            this.offset += timestamp - this.last;
+        this.rebasing = false;
+        this.last = timestamp;
+        const u = timestamp - this.offset;
+        let pace = this.pace;
+        let now = pace === null ? u : pace.sync(u);
+        const later = u !== this.u;
+        const still = later && now === this.now;
+        this.u = u;
+        if (Number.isNaN(this.born))
+            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);
+            pace = this.pace;
+            now = reading();
+        }
+        // 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();
+        if (this.tape !== undefined && history !== undefined)
+            this.tape.prune(reach);
+        if (history !== undefined && this.dropped.length > 0)
+            this.dropped = this.dropped.filter((d) => d.at >= reach);
+        this.woken = false;
+        // It is a frame too, which asks every weight signal again, so one reading input follows it.
+        if (still)
+            for (const m of this.members) {
+                m.frame = nextFrame();
+                m.lanes?.refill();
+            }
+        for (const m of this.members) {
+            const bookers = m.bookers;
+            if (bookers !== null)
+                for (const b of bookers)
+                    b.sync();
+        }
+    }
+    rebase() {
+        this.rebasing = true;
+    }
+    /**
+     * Moves `floor` past what the mix clock standing at `now` has let go of. With a store nothing is
+     * let go: what leaves memory is paged, which moves it.
+     */
+    kept() {
+        const history = this.history;
+        if (history !== undefined && this.pager === null && this.now - history.ms > this.floor)
+            this.floor = this.now - history.ms;
+    }
+    /** Whether history reaches back to mix time `t`, from memory. */
+    reaches(t) {
+        if (this.pager !== null)
+            return t >= this.floor;
+        return t >= this.floor && t >= this.now - (this.history?.ms ?? 0);
+    }
+    /**
+     * The earliest mix time it keeps what no store pages, the tape, dropped mixes, rate changes and
+     * announced marks among them: with a store, all of it, since the host bounds the tape.
+     */
+    keepsFrom() {
+        const history = this.history;
+        if (history === undefined)
+            return Number.POSITIVE_INFINITY;
+        return this.pager === null ? this.now - history.ms : Number.NEGATIVE_INFINITY;
+    }
+    get rate() {
+        return this.pace === null ? 1 : this.pace.rateAt(this.u);
+    }
+    set rate(r) {
+        this.ramp(r, 0);
+    }
+    ramp(rate, over) {
+        if (!(rate >= 0 && rate < Number.POSITIVE_INFINITY))
+            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);
+            // 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)
+                    if (v.state === 'pending' && !v.placing && v.owner === null && v.spec.start !== undefined)
+                        pin(m, v, v.start);
+        }
+        const reach = this.history === undefined ? Number.NEGATIVE_INFINITY : this.keepsFrom();
+        this.pace.change(this.u, rate, over, reach);
+        for (const m of this.members)
+            m.stir();
+        record(this, 'rate', () => this.ramp(rate, over));
+    }
+}
+/** Puts a mark on a score: one the transport announced, or a mix on it, `slot`. */
+export function announce(transport, name, opts, slot, mix) {
+    const at = opts.at !== undefined ? opts.at - transport.offset : transport.u;
+    const mark = {
+        name,
+        score: opts.score,
+        tags: opts.tags ?? [],
+        at,
+        made: Number.isNaN(transport.now) ? Number.NEGATIVE_INFINITY : transport.now,
+        order: transport.nextId++,
+        slot,
+        mix,
+    };
+    transport.announced.push(mark);
+    record(transport, 'announce', () => {
+        transport.announced.push({ ...mark });
+    });
+}
+/**
+ * Makes a transport several mixes can share, each made with `transport` in its options.
+ *
+ * @category mix
+ */
+export function transport(opts = {}) {
+    return new Transport(opts.history, true);
+}