@msb235/blits 0.6.0 → 0.7.1

package/dist/move.d.ts

@@ -6,4 +6,4 @@ export declare function waits<I, O>(mix: Mixer<I, O>): boolean;
 /** Moves the mix clock to `now`: voices start, finite loops end, and fades finish. */
 export declare function move<I, O>(mix: Mixer<I, O>, now: number): void;
 /** Lets go of the voices that have left and that history no longer reaches. */
-export declare function forget<I, O>(mix: Mixer<I, O>, now: number): void;
+export declare function forget<I, O>(mix: Mixer<I, O>): void;

package/dist/move.js

@@ -1,9 +1,13 @@
 import { changed, unindex } from './chain.js';
 import { popDue, schedule } from './due.js';
 import { beginFade, part, retire } from './fade.js';
+import { expireGone, keepGone } from './gone.js';
 import { started } from './held.js';
 import { ownerReading } from './owner.js';
 import { mixAt, place, repin, startOf } from './place.js';
+import { pageVoice } from './revive.js';
+import { scoredLeft, scoredRemove } from './scored.js';
+import { lapse } from './spans.js';
 import { unplay } from './strays.js';
 /** Numbers every mix's frames apart, so a blend's read is never taken for another mix's or frame's. */
 let frames = 0;
@@ -38,7 +42,7 @@ function moveTo(mix, now) {
         place(mix);
     if (mix.announced.length > 0) {
         // Kept while still ahead, or while history reaches it; anchors waiting on one were placed above.
-        const reach = now - (mix.opts.history?.ms ?? 0);
+        const reach = mix.opts.history === undefined ? now : mix.transport.keepsFrom();
         mix.announced = mix.announced.filter((a) => mixAt(mix, a.at) >= reach);
     }
     // A live mix visits only the voices due by now; a projection, which copies few, visits all.
@@ -49,7 +53,7 @@ function moveTo(mix, now) {
         if (Number.isNaN(voice.opened))
             voice.opened = now;
         if ((voice.state === 'live' || voice.state === 'frozen') && voice.outAt <= now)
-            beginFade(mix, voice, {}, Math.max(startOf(voice), voice.outAt));
+            beginFade(mix, voice, { over: Number.isNaN(voice.outOver) ? undefined : voice.outOver }, Math.max(startOf(voice), voice.outAt));
         if (voice.state === 'pending' &&
             (voice.owner === null ? now : ownerReading(voice.owner, now)) >= voice.start) {
             voice.state = 'live';
@@ -59,7 +63,7 @@ function moveTo(mix, now) {
         if (voice.state !== 'pending' && Number.isFinite(voice.span)) {
             const end = voice.span + voice.latest;
             if (voice.elapsedAt(now) >= end) {
-                voice.play(true);
+                voice.play(true, now);
                 // The fade starts when the last pass ended, not at the frame that noticed, so it plays
                 // the same at any frame rate and a read at another time can find it.
                 if (voice.state === 'live') {
@@ -77,6 +81,11 @@ function moveTo(mix, now) {
             for (const [subject, r] of voice.parts)
                 if (now - r.at >= r.over)
                     part(mix, voice, subject, r.at + r.over);
+        const back = voice.back;
+        if (back !== null && now >= back.at + (1 - back.from) * back.over && !mix.projecting) {
+            voice.back = null;
+            mix.lanes?.refill();
+        }
         if (voice.state === 'fading' && voice.out) {
             const { at, over, rest, deadline } = voice.out;
             const spent = now - at;
@@ -94,10 +103,12 @@ function moveTo(mix, now) {
         if (!mix.projecting)
             schedule(mix, voice);
     }
+    if (mix.owners !== null)
+        lapse(mix, now);
     mix.stirred = false;
     if (mix.retired.length > 0)
         prune(mix);
-    forget(mix, now);
+    forget(mix);
 }
 /** Past this many voices retiring in one frame, one pass over the list beats a search for each. */
 const SEARCHED = 8;
@@ -164,8 +175,11 @@ function indexOf(voices, voice) {
 }
 /** Lets go of a retired voice's place in the mix; whether it was among the voices naming no subject. */
 function leave(mix, voice) {
-    if (mix.opts.history)
+    scoredRemove(mix, [voice]);
+    if (mix.opts.history) {
         mix.gone.push(voice);
+        scoredLeft(mix, voice);
+    }
     else
         mix.parters.delete(voice);
     unplay(mix, voice);
@@ -181,10 +195,16 @@ function leave(mix, voice) {
     return voice.named === null;
 }
 /** Lets go of the voices that have left and that history no longer reaches. */
-export function forget(mix, now) {
+export function forget(mix) {
     const history = mix.opts.history;
     if (history && mix.gone.length > 0) {
-        const reach = now - history.ms;
-        mix.gone = mix.gone.filter((v) => v.doneAt >= reach);
+        // With a store a voice that has left pages out where it can, and stays where it cannot.
+        if (mix.transport.pager !== null) {
+            const reach = mix.now - history.ms;
+            keepGone(mix, (v) => v.doneAt >= reach || !pageVoice(mix, v, reach));
+        }
+        else {
+            expireGone(mix, mix.transport.keepsFrom());
+        }
     }
 }

package/dist/owner.d.ts

@@ -24,7 +24,7 @@ export declare function adopt<I, O>(owner: Voice<I, O>, child: Voice<I, O>): voi
 /** A child left: its owner, where that was its last child and it should leave too. */
 export declare function orphan<I, O>(child: Voice<I, O>): Voice<I, O> | null;
 /** A child finished its passes: its owner has played once every child it held has. */
-export declare function childPlayed<I, O>(owner: Voice<I, O>): void;
+export declare function childPlayed<I, O>(owner: Voice<I, O>, at: number): void;
 /** Every voice an owner holds, its children's children included. */
 export declare function descendants<I, O>(owner: Voice<I, O>, visit: (v: Voice<I, O>) => void): void;
 /** Whether any owner above a voice reads a signal for its weight, which lanes cannot fill. */

package/dist/owner.js

@@ -48,10 +48,10 @@ export function orphan(child) {
     return h.children.length === 0 && owner.state !== 'done' ? owner : null;
 }
 /** A child finished its passes: its owner has played once every child it held has. */
-export function childPlayed(owner) {
+export function childPlayed(owner, at) {
     const h = owner.holding;
     if (++h.played === h.kids)
-        owner.play(true);
+        owner.play(true, at);
 }
 /** Every voice an owner holds, its children's children included. */
 export function descendants(owner, visit) {
@@ -86,7 +86,7 @@ export function ownWeight(owner, now, reduced, base) {
     const b = typeof owner.spec.weight === 'function' ? base(owner) : owner.weight;
     const start = owner.owner === null ? owner.start : mixTime(owner.owner, owner.start);
     const since = owner.freezesBefore && owner.opened < start ? owner.opened : start;
-    return clampWeight(b * envelope(owner.fade.in ?? 0, owner.out, owner.ease, reduced, now, since));
+    return clampWeight(b * envelope(owner.fade.in ?? 0, owner.out, owner.ease, reduced, now, since, owner.back));
 }
 /** What every owner above a voice multiplies into its weight. */
 export function ownersWeight(voice, now, reduced, base) {

package/dist/pace.d.ts

@@ -35,6 +35,8 @@ export declare class Pace {
      * time `reach`.
      */
     change(u: number, rate: number, over: number, reach: number): void;
+    /** Lets go of the clocks set after host time `u`, for a seek back to then. */
+    cut(u: number): void;
     /** A copy holding the clocks that took effect before host time `u`, for a read back to then. */
     until(u: number): Pace;
 }

package/dist/pace.js

@@ -102,6 +102,14 @@ export class Pace {
         if (drop > 0)
             log.splice(0, drop);
     }
+    /** Lets go of the clocks set after host time `u`, for a seek back to then. */
+    cut(u) {
+        const log = this.log;
+        let n = 1;
+        while (n < log.length && log[n].anchorNow <= u)
+            n++;
+        log.length = n;
+    }
     /** A copy holding the clocks that took effect before host time `u`, for a read back to then. */
     until(u) {
         const log = this.log;

package/dist/pack.d.ts

@@ -0,0 +1,31 @@
+import type { Subject, Voice } from './voice.js';
+/** A subject's record as plain data, for a history store. */
+export interface PackedRecord {
+    reaches: boolean;
+    delay: number;
+    since: number;
+    shown: number;
+    weight: number;
+    rested: boolean;
+    bands: number[] | null;
+    state: unknown;
+    stepped: number;
+    ticks: number;
+    /**
+     * What `setting.keep` held, in the order its owners first kept it. An owner is code, which no
+     * store keeps, and a voice revived from a descriptor has new ones; the same code keeps in the same
+     * order, so each owner takes the next value on its first keep.
+     */
+    kept: unknown[] | null;
+    base?: Record<string, unknown>;
+    slope?: Record<string, unknown>;
+    snaps?: [at: number, held: PackedRecord][];
+    inputs?: {
+        at: number;
+        value: number;
+    }[];
+}
+/** A voice's record of one subject as plain data, its patch's `pack` taking its state. */
+export declare function packHeld<I, O>(voice: Voice<I, O>, h: Subject<unknown>): PackedRecord;
+/** A record made again from `packHeld`'s data, for `voice`. */
+export declare function unpackHeld<I, O>(voice: Voice<I, O>, p: PackedRecord): Subject<unknown>;

package/dist/pack.js

@@ -0,0 +1,65 @@
+import { clone } from './clone.js';
+/** A voice's record of one subject as plain data, its patch's `pack` taking its state. */
+export function packHeld(voice, h) {
+    const patch = voice.patch;
+    const kept = [...(h.kept?.values() ?? []), ...(h.unkept ?? [])];
+    const p = {
+        reaches: h.reaches,
+        delay: h.delay,
+        since: h.since,
+        shown: h.shown,
+        weight: h.weight,
+        rested: h.rested,
+        bands: h.bands === null ? null : Array.from(h.bands),
+        state: h.state === undefined ? undefined : patch.pack ? patch.pack(h.state) : clone(h.state),
+        stepped: h.stepped,
+        ticks: h.ticks,
+        kept: kept.length === 0 ? null : kept.map(clone),
+    };
+    if (h.base !== undefined)
+        p.base = clone(h.base);
+    if (h.slope !== undefined)
+        p.slope = clone(h.slope);
+    if (h.snaps !== undefined)
+        p.snaps = h.snaps.map((s) => [s.at, packHeld(voice, s.held)]);
+    if (h.inputs !== undefined)
+        p.inputs = h.inputs.map((e) => ({ ...e }));
+    return p;
+}
+/** A record made again from `packHeld`'s data, for `voice`. */
+export function unpackHeld(voice, p) {
+    const patch = voice.patch;
+    const h = {
+        reaches: p.reaches,
+        delay: p.delay,
+        since: p.since,
+        shown: p.shown,
+        weight: p.weight,
+        rested: p.rested,
+        bands: p.bands === null ? null : Uint8Array.from(p.bands),
+        state: p.state === undefined ? undefined : patch.unpack ? patch.unpack(p.state) : p.state,
+        stepped: p.stepped,
+        ticks: p.ticks,
+        probed: Number.NaN,
+        delta: null,
+        phase: 0,
+        seeks: 0,
+        kept: null,
+        voice,
+        next: null,
+        version: Number.NaN,
+        loci: null,
+        slot: -1,
+    };
+    if (p.kept !== null)
+        h.unkept = p.kept;
+    if (p.base !== undefined)
+        h.base = p.base;
+    if (p.slope !== undefined)
+        h.slope = p.slope;
+    if (p.snaps !== undefined)
+        h.snaps = p.snaps.map(([at, held]) => ({ at, held: unpackHeld(voice, held) }));
+    if (p.inputs !== undefined)
+        h.inputs = p.inputs;
+    return h;
+}

package/dist/paging.d.ts

@@ -0,0 +1,63 @@
+import type { Mixer } from './mixer.js';
+import type { Transport } from './transport.js';
+import type { HistoryStore, Paged, PagedStream } from './types.js';
+/**
+ * A `seek` or `project` reached past memory into records `prepare` had not loaded. Thrown before
+ * anything moves, so a restore is never partial: `await prepare(at)` and ask again.
+ *
+ * @category mix
+ */
+export declare class HistoryMiss extends Error {
+    /** The mix whose records were missing, by `name`. */
+    readonly mix: string;
+    readonly stream: string;
+    /** The mix time asked for. */
+    readonly at: number;
+    constructor(
+    /** The mix whose records were missing, by `name`. */
+    mix: string, stream: string, 
+    /** The mix time asked for. */
+    at: number);
+}
+/** A transport's history store: what left memory, and what `prepare` loaded back. */
+export declare class Pager {
+    readonly store: HistoryStore;
+    /** What the last `prepare` loaded, and every record paged since, until a seek or read takes it. */
+    loaded: {
+        t: number;
+        records: Paged[];
+    } | null;
+    /** The latest record paged, which a miss names. */
+    last: {
+        mix: string;
+        stream: PagedStream;
+    } | null;
+    constructor(store: HistoryStore);
+}
+/** A subject's key in history records; undefined for the unit subject. */
+export type Key = string | number | undefined;
+/**
+ * Object subjects by key, for a mix with a store, held weakly: a subject the host has let go of
+ * can never be probed again, so nothing it kept is put back.
+ */
+export declare class Keys {
+    private readonly of;
+    private readonly refs;
+    private readonly gone;
+    constructor(of: ((subject: never) => string | number) | undefined);
+    /** The key a subject is paged under; throws for an object subject without `keyOf`. */
+    key(subject: unknown): Key;
+    /** The subject a key stands for: an object the mix met under it, else the key itself. */
+    subject(key: Key): unknown;
+}
+/**
+ * Hands records leaving memory to the store, the last of any that share a time, which is the one
+ * a read finds. `reach` is how far back memory still reaches.
+ */
+export declare function pageOut<I, O, E extends {
+    at: number;
+}>(mix: Mixer<I, O>, stream: PagedStream, voice: number | undefined, subject: Key, out: readonly E[], data: (e: E) => unknown, reach: number): void;
+/** Gives records to the store; memory now reaches back no further than `reach`. */
+export declare function page(transport: Transport, records: Paged[], reach: number): void;
+/** Loads what a seek or read to `t` needs where it reaches past memory. */
+export declare function prepare(transport: Transport, t: number): Promise<void>;

package/dist/paging.js

@@ -0,0 +1,110 @@
+/**
+ * A `seek` or `project` reached past memory into records `prepare` had not loaded. Thrown before
+ * anything moves, so a restore is never partial: `await prepare(at)` and ask again.
+ *
+ * @category mix
+ */
+export class HistoryMiss extends Error {
+    mix;
+    stream;
+    at;
+    constructor(
+    /** The mix whose records were missing, by `name`. */
+    mix, stream, 
+    /** The mix time asked for. */
+    at) {
+        super(`blits: ${at} reaches past memory into ${stream} records of ${mix === '' ? 'the mix' : mix} that were not loaded; await prepare(${at}) first`);
+        this.mix = mix;
+        this.stream = stream;
+        this.at = at;
+        this.name = 'HistoryMiss';
+    }
+}
+/** A transport's history store: what left memory, and what `prepare` loaded back. */
+export class Pager {
+    store;
+    /** What the last `prepare` loaded, and every record paged since, until a seek or read takes it. */
+    loaded = null;
+    /** The latest record paged, which a miss names. */
+    last = null;
+    constructor(store) {
+        this.store = store;
+    }
+}
+/**
+ * Object subjects by key, for a mix with a store, held weakly: a subject the host has let go of
+ * can never be probed again, so nothing it kept is put back.
+ */
+export class Keys {
+    of;
+    refs = new Map();
+    gone = new FinalizationRegistry((key) => {
+        const ref = this.refs.get(key);
+        if (ref !== undefined && ref.deref() === undefined)
+            this.refs.delete(key);
+    });
+    constructor(of) {
+        this.of = of;
+    }
+    /** The key a subject is paged under; throws for an object subject without `keyOf`. */
+    key(subject) {
+        if (subject === undefined || typeof subject === 'string' || typeof subject === 'number')
+            return subject;
+        const of = this.of;
+        if (of === undefined || typeof subject !== 'object' || subject === null)
+            throw new Error('blits: a mix whose history has a store pages its subjects by key; give it keyOf for subjects that are not strings or numbers');
+        const key = of(subject);
+        if (this.refs.get(key)?.deref() !== subject) {
+            this.refs.set(key, new WeakRef(subject));
+            this.gone.register(subject, key);
+        }
+        return key;
+    }
+    /** The subject a key stands for: an object the mix met under it, else the key itself. */
+    subject(key) {
+        if (key === undefined)
+            return undefined;
+        return this.refs.get(key)?.deref() ?? key;
+    }
+}
+/**
+ * Hands records leaving memory to the store, the last of any that share a time, which is the one
+ * a read finds. `reach` is how far back memory still reaches.
+ */
+export function pageOut(mix, stream, voice, subject, out, data, reach) {
+    const pager = mix.transport.pager;
+    if (pager === null || out.length === 0)
+        return;
+    const name = mix.name ?? '';
+    const records = [];
+    for (let i = 0; i < out.length; i++) {
+        const e = out[i];
+        if (i + 1 < out.length && out[i + 1].at === e.at)
+            continue;
+        const r = { mix: name, stream, at: e.at, data: data(e) };
+        if (voice !== undefined)
+            r.voice = voice;
+        if (subject !== undefined)
+            r.subject = subject;
+        records.push(r);
+    }
+    page(mix.transport, records, reach);
+}
+/** Gives records to the store; memory now reaches back no further than `reach`. */
+export function page(transport, records, reach) {
+    const pager = transport.pager;
+    pager.store.page(records);
+    pager.loaded?.records.push(...records);
+    const last = records[records.length - 1];
+    pager.last = { mix: last.mix, stream: last.stream };
+    if (reach > transport.floor)
+        transport.floor = reach;
+}
+/** Loads what a seek or read to `t` needs where it reaches past memory. */
+export async function prepare(transport, t) {
+    const pager = transport.pager;
+    if (pager === null || transport.reaches(t))
+        return;
+    const records = await pager.store.load(t);
+    pager.loaded = { t, records: [...records] };
+}

package/dist/patch.d.ts

@@ -15,6 +15,9 @@ export interface PatchOptions<I, O, S, H = unknown> {
     reads?: readonly string[];
     state?(subject: I): S;
     step?(state: S, dt: number, subject: I, setting: Setting<S, H>): void;
+    /** `state` as plain data and back, for a history store: see `Patch.pack`. */
+    pack?(state: S): unknown;
+    unpack?(data: unknown): S;
 }
 /**
  * The procedural form. Flicker, roving, a hash walk, a starter strike.

package/dist/patch.js

@@ -19,6 +19,8 @@ export function patch(duration, at, opts) {
         at,
         state: opts.state,
         step: opts.step,
+        pack: opts.pack,
+        unpack: opts.unpack,
     };
 }
 const options = new WeakMap();