@msb235/blits 0.6.0 → 0.7.0

package/dist/unpage.js

@@ -0,0 +1,163 @@
+import { unpackHeld } from './pack.js';
+import { HistoryMiss } from './paging.js';
+import { reviveVoice } from './revive.js';
+/**
+ * Makes memory reach mix time `t` for a seek or read there, from what `prepare` loaded; true where
+ * it took records from the store. Throws before anything moves where it cannot.
+ */
+export function cover(transport, t) {
+    if (transport.reaches(t))
+        return false;
+    const pager = transport.pager;
+    if (pager === null)
+        throw new Error(`blits: ${t} is older than this mix's history reaches`);
+    const loaded = pager.loaded;
+    if (loaded === null || loaded.t > t) {
+        const last = pager.last;
+        throw new HistoryMiss(last?.mix ?? '', last?.stream ?? 'history', t);
+    }
+    for (const m of [...transport.members, ...transport.dropped.map((d) => d.mix)]) {
+        const name = m.name ?? '';
+        const id = m.outs?.missing(loaded.t, (v) => loaded.records.some((r) => r.stream === 'voice' && r.voice === v && r.mix === name));
+        if (id !== undefined)
+            throw new HistoryMiss(name, 'voice', t);
+    }
+    pager.loaded = null;
+    unpage(transport, loaded.records);
+    transport.floor = loaded.t;
+    return true;
+}
+/** A seek back to `t`: what the store and `prepare` hold after it is from a future the tape makes again. */
+export function cut(transport, t, unpaged) {
+    const pager = transport.pager;
+    if (pager === null)
+        return;
+    if (unpaged)
+        pager.store.cut(t);
+    const loaded = pager.loaded;
+    if (loaded !== null)
+        loaded.records = loaded.records.filter((r) => r.at <= t);
+}
+/** Puts records a store gave back into memory ahead of what it still holds, as if never paged. */
+function unpage(transport, records) {
+    const mixes = new Map();
+    for (const m of [...transport.members, ...transport.dropped.map((d) => d.mix)])
+        mixes.set(m.name ?? '', m);
+    const by = new Map();
+    for (const r of [...records].sort((a, b) => a.at - b.at)) {
+        const m = mixes.get(r.mix);
+        if (m === undefined)
+            continue;
+        const list = by.get(m);
+        if (list === undefined)
+            by.set(m, [r]);
+        else
+            list.push(r);
+    }
+    for (const [m, list] of by)
+        unpageMix(m, list);
+}
+function unpageMix(mix, records) {
+    const voices = new Map();
+    for (const v of [...mix.cued, ...mix.gone])
+        voices.set(v.id, v);
+    for (const r of records)
+        if (r.stream === 'voice' && r.voice !== undefined && !voices.has(r.voice)) {
+            const v = reviveVoice(mix, r.voice, r.data);
+            voices.set(v.id, v);
+            mix.gone.push(v);
+        }
+    const host = records.filter((r) => r.stream === 'host');
+    mix.hostLog = before(host.map((r) => ({ at: r.at, fields: r.data })), mix.hostLog);
+    const byVoice = new Map();
+    for (const r of records) {
+        if (r.voice === undefined)
+            continue;
+        const list = byVoice.get(r.voice);
+        if (list === undefined)
+            byVoice.set(r.voice, [r]);
+        else
+            list.push(r);
+    }
+    const keys = mix.keys;
+    for (const [id, list] of byVoice) {
+        const voice = voices.get(id);
+        if (voice !== undefined)
+            unpageVoice(voice, list, keys);
+    }
+}
+function unpageVoice(voice, records, keys) {
+    const of = (stream) => records.filter((r) => r.stream === stream);
+    if (voice.log !== null)
+        voice.log = before(of('controls').map((r) => r.data), voice.log);
+    const left = voice.left ?? [];
+    for (const r of of('left')) {
+        const subject = keys.subject(r.subject);
+        if (!left.some((e) => e.at === r.at && Object.is(e.subject, subject)))
+            left.push({ subject, at: r.at, held: unpackHeld(voice, r.data) });
+    }
+    left.sort((a, b) => a.at - b.at);
+    voice.left = left.length === 0 ? null : left;
+    for (const [key, list] of bySubject(of('snap'))) {
+        const subject = keys.subject(key);
+        for (const [held, snaps] of lives(voice, subject, list))
+            held.snaps = before(snaps.map((r) => ({ at: r.at, held: unpackHeld(voice, r.data) })), held.snaps ?? []);
+    }
+    for (const [key, list] of bySubject(of('input'))) {
+        const subject = keys.subject(key);
+        for (const [held, inputs] of lives(voice, subject, list))
+            held.inputs = before(inputs.map((r) => ({ at: r.at, value: r.data })), held.inputs ?? []);
+    }
+    const motion = voice.motion;
+    if (motion === undefined)
+        return;
+    for (const r of of('released'))
+        motion.reclaim(keys.subject(r.subject), r.at, r.data);
+    for (const [key, list] of bySubject(of('stretch')))
+        motion.restretch(keys.subject(key), list);
+}
+function bySubject(records) {
+    const out = new Map();
+    for (const r of records) {
+        const list = out.get(r.subject);
+        if (list === undefined)
+            out.set(r.subject, [r]);
+        else
+            list.push(r);
+    }
+    return out;
+}
+/**
+ * A subject's records in a voice, each with the paged entries from its life: one ends when the
+ * subject leaves the voice, and the record it has now began after its last leaving.
+ */
+function lives(voice, subject, records) {
+    const left = (voice.left ?? []).filter((e) => Object.is(e.subject, subject));
+    const out = [];
+    let from = Number.NEGATIVE_INFINITY;
+    for (const e of left) {
+        out.push([e.held, records.filter((r) => r.at > from && r.at <= e.at)]);
+        from = e.at;
+    }
+    const live = voice.subjects.get(subject);
+    if (live?.reaches)
+        out.push([live, records.filter((r) => r.at > from)]);
+    return out;
+}
+/**
+ * `loaded`, in time order, ahead of `list`: those older than its first entry, the last of any that
+ * share a time, which is the one a read finds.
+ */
+function before(loaded, list) {
+    const first = list[0]?.at ?? Number.POSITIVE_INFINITY;
+    const out = [];
+    for (const e of loaded) {
+        if (!(e.at < first))
+            continue;
+        if (out.length > 0 && out[out.length - 1].at === e.at)
+            out[out.length - 1] = e;
+        else
+            out.push(e);
+    }
+    return out.length === 0 ? list : [...out, ...list];
+}

package/dist/voice.d.ts

@@ -1,12 +1,13 @@
 import type { Blend } from './blend.js';
 import { type Clock } from './clock.js';
 import { type Curve } from './easing.js';
-import { type Motions } from './motion.js';
+import type { Motions } from './motions.js';
 import { Named } from './named.js';
 import { Holding } from './owner.js';
 import { type Built, intosOf, type Scratch } from './patch.js';
+import type { Fitting } from './spans.js';
 import { Store } from './store.js';
-import type { Channel, FadeSpec, Handle, Patch, Setting, VoiceSpec } from './types.js';
+import type { Anchor, Channel, FadeSpec, Handle, Patch, Setting, VoiceSpec } from './types.js';
 export declare const none: readonly string[];
 /** Everything one voice holds for one subject, chained through the next voice that reaches it. */
 export interface Subject<S> {
@@ -23,7 +24,7 @@ export interface Subject<S> {
     /** Left at rest during a handover, so it stops contributing. */
     rested: boolean;
     /**
-     * Per written channel, whether a rest-less influence is on: 0 unknown, 1 on, 2 off; null until
+     * 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;
@@ -46,6 +47,8 @@ export interface Subject<S> {
     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?: {
         at: number;
@@ -70,7 +73,7 @@ export interface Subject<S> {
     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 locus, by channel slot, whether a rest-less influence is on:
+     * the chain was linked at, and per locus, by channel slot, whether a rest-less contribution is on:
      * 0 never decided, 1 on, 2 off.
      */
     version: number;
@@ -83,9 +86,13 @@ export interface Controls extends Clock {
     at: number;
     weight: number;
     out: Ramp | null;
+    back: Rise | null;
     /** Where its anchors had placed it then: start, and the start of an anchored fade out. */
     start: number;
     outAt: number;
+    /** A fade the host set for `outAt`: its ramp, NaN for the voice's own `fade.out`. */
+    outOver: number;
+    outSet: boolean;
     /** Made by a sync, so it shows in that frame; a host's change between frames shows from the next. */
     sync: boolean;
 }
@@ -96,6 +103,15 @@ export interface Ramp {
     rest: boolean;
     deadline?: number;
 }
+/**
+ * A climb back from a fade out that was turned around: from `from`, the place along the fade's
+ * curve it had reached, at mix time `at`, rising at the whole curve per `over` ms.
+ */
+export interface Rise {
+    from: number;
+    at: number;
+    over: number;
+}
 export declare class Voice<I, O> {
     readonly id: number;
     readonly spec: VoiceSpec<I, O>;
@@ -120,7 +136,9 @@ export declare class Voice<I, O> {
         over: number;
     } | null;
     out: Ramp | null;
-    readonly subjects: Store<I, Subject<unknown>>;
+    /** A fade out turned around, still climbing back; null once back in, or never turned. */
+    back: Rise | null;
+    subjects: Store<I, Subject<unknown>>;
     /** The subjects its spec names, or null where it names none. */
     readonly named: Named<I> | null;
     /** Kit slot of each channel the patch writes, in `writes` order. */
@@ -151,6 +169,15 @@ export declare class Voice<I, O> {
     }> | null;
     /** Subjects faded out of this voice, by the mix time each left at; null while none have. */
     parted: Map<I, number> | null;
+    /**
+     * Under history, the records of subjects that left this voice, by the mix time each left at,
+     * while a seek or a read back may reach them; null while none have.
+     */
+    left: {
+        subject: I;
+        at: number;
+        held: Subject<unknown>;
+    }[] | null;
     readonly ease: Curve | undefined;
     /** How many passes its `loop` plays, worked out once. */
     readonly passes: number;
@@ -181,10 +208,20 @@ export declare class Voice<I, O> {
     doneAt: number;
     /** Under `history`, its controls after each change, oldest first. */
     log: Controls[] | null;
+    /** Under `history`, its controls as `cue` left them, which a voice parked by a seek takes back. */
+    first: Controls | null;
     /** Where an anchored `out` or `end` puts its fade's start, mix time; Infinity until known. */
     outAt: number;
+    /** The ramp of a fade the host set for `outAt` with `fade({ at })`; NaN for the voice's own. */
+    outOver: number;
+    /** Whether the host set `outAt` with `fade({ at })`, which no anchor moves. */
+    outSet: boolean;
+    /** The host time a pinned start was given at, NaN for none: a seek back pins it again. */
+    pinned: number;
     /** Whether its start is still to be fixed by an anchor, so it waits pending. */
     placing: boolean;
+    /** What each member of a join last answered, kept for once its target has left. */
+    answers: Map<Anchor, number> | null;
     /** The record `setting.keep` writes to: the one its patch or signal is being called for. */
     keepOn: Subject<unknown> | null;
     /** What `setting.keep` holds when called before any record is. */
@@ -200,14 +237,20 @@ export declare class Voice<I, O> {
     unreachedBits: Uint32Array | null;
     /** The handle `cue` returned, which `voices` hands back too. */
     handle: Handle<I> | null;
+    /** With a history store, the key of every subject it has a record of; null without one. */
+    keyed: Set<string | number | undefined> | null;
     /** For an owner, the voices it holds; null for any other voice. */
     holding: Holding<Voice<I, O>> | null;
+    /** For a span, its budget and how its children were last fitted; null for any other voice. */
+    fitting: Fitting | null;
     /**
      * `done` and `played`, made when first asked for, already settled if the voice is: most hosts
      * never await either, and a mix may hold tens of thousands of voices.
      */
     private finished;
     private playedAs;
+    /** The mix time `played` was settled at, so a seek back to before it can open it again. */
+    private playedAt;
     private donePromise;
     private doneSettle;
     private playedPromise;
@@ -218,8 +261,31 @@ export declare class Voice<I, O> {
     get played(): Promise<boolean>;
     /** The voice has left: `done` resolves. */
     resolve(): void;
-    /** Its finite loop ended (true) or it left first (false), whichever comes first: `played` resolves. */
-    play(played: boolean): void;
+    /**
+     * Its finite loop ended (true) or it left first (false), whichever comes first, noticed at mix
+     * time `at`: `played` resolves.
+     */
+    play(played: boolean, at: number): void;
+    /** How `played` settled, and the mix time it did; undefined while it has not. */
+    get settled(): {
+        played: boolean | undefined;
+        at: number;
+    };
+    /** Whether `played` settled true, which its owner counted. */
+    get passed(): boolean;
+    /** Whether `played` settled false: it left before its last pass ended. */
+    get unplayed(): boolean;
+    /**
+     * A seek back to mix time `t`: `done` and `played`, where they settled after it, start over with
+     * fresh promises. True where `played` had settled true, which its owner counted.
+     */
+    reopen(t: number): boolean;
+    /**
+     * A seek back to before its cue: out of the mix, as `cue` left it, until the mix plays the cue
+     * again. What it played since is forgotten, and `done` and `played` start over where they had
+     * settled.
+     */
+    park(): void;
     constructor(id: number, spec: VoiceSpec<I, O>, patch: Patch<I, O, unknown>, fade: FadeSpec, now: number, start: number, slotOf: Map<string, number>, channels: readonly Channel<unknown>[], host: unknown, send: (event: unknown) => void, 
     /** The owner whose clock it runs on, its start included; null for one on the mix clock. */
     owner: Voice<I, O> | null);

package/dist/voice.js

@@ -24,7 +24,10 @@ function keeping(voice) {
         }
         if (kept.has(owner))
             return kept.get(owner);
-        const made = init();
+        const unkept = held?.unkept;
+        const made = unkept === undefined ? init() : unkept.shift();
+        if (unkept?.length === 0 && held !== null)
+            held.unkept = undefined;
         kept.set(owner, made);
         reading.kept++;
         return made;
@@ -93,6 +96,8 @@ export class Voice {
     anchorElapsed = 0;
     ramp = null;
     out = null;
+    /** A fade out turned around, still climbing back; null once back in, or never turned. */
+    back = null;
     subjects = new Store();
     /** The subjects its spec names, or null where it names none. */
     named;
@@ -121,6 +126,11 @@ export class Voice {
     parts = null;
     /** Subjects faded out of this voice, by the mix time each left at; null while none have. */
     parted = null;
+    /**
+     * Under history, the records of subjects that left this voice, by the mix time each left at,
+     * while a seek or a read back may reach them; null while none have.
+     */
+    left = null;
     ease;
     /** How many passes its `loop` plays, worked out once. */
     passes;
@@ -151,10 +161,20 @@ export class Voice {
     doneAt = Number.POSITIVE_INFINITY;
     /** Under `history`, its controls after each change, oldest first. */
     log = null;
+    /** Under `history`, its controls as `cue` left them, which a voice parked by a seek takes back. */
+    first = null;
     /** Where an anchored `out` or `end` puts its fade's start, mix time; Infinity until known. */
     outAt = Number.POSITIVE_INFINITY;
+    /** The ramp of a fade the host set for `outAt` with `fade({ at })`; NaN for the voice's own. */
+    outOver = Number.NaN;
+    /** Whether the host set `outAt` with `fade({ at })`, which no anchor moves. */
+    outSet = false;
+    /** The host time a pinned start was given at, NaN for none: a seek back pins it again. */
+    pinned = Number.NaN;
     /** Whether its start is still to be fixed by an anchor, so it waits pending. */
     placing = false;
+    /** What each member of a join last answered, kept for once its target has left. */
+    answers = null;
     /** The record `setting.keep` writes to: the one its patch or signal is being called for. */
     keepOn = null;
     /** What `setting.keep` holds when called before any record is. */
@@ -167,14 +187,20 @@ export class Voice {
     unreachedBits = null;
     /** The handle `cue` returned, which `voices` hands back too. */
     handle = null;
+    /** With a history store, the key of every subject it has a record of; null without one. */
+    keyed = null;
     /** For an owner, the voices it holds; null for any other voice. */
     holding;
+    /** For a span, its budget and how its children were last fitted; null for any other voice. */
+    fitting = null;
     /**
      * `done` and `played`, made when first asked for, already settled if the voice is: most hosts
      * never await either, and a mix may hold tens of thousands of voices.
      */
     finished = false;
     playedAs = undefined;
+    /** The mix time `played` was settled at, so a seek back to before it can open it again. */
+    playedAt = Number.NaN;
     donePromise = null;
     doneSettle = null;
     playedPromise = null;
@@ -209,14 +235,94 @@ export class Voice {
         this.finished = true;
         this.doneSettle?.();
     }
-    /** Its finite loop ended (true) or it left first (false), whichever comes first: `played` resolves. */
-    play(played) {
+    /**
+     * Its finite loop ended (true) or it left first (false), whichever comes first, noticed at mix
+     * time `at`: `played` resolves.
+     */
+    play(played, at) {
         if (this.quiet || this.playedAs !== undefined)
             return;
         this.playedAs = played;
+        this.playedAt = at;
         this.playedSettle?.(played);
         if (played && this.owner !== null)
-            childPlayed(this.owner);
+            childPlayed(this.owner, at);
+    }
+    /** How `played` settled, and the mix time it did; undefined while it has not. */
+    get settled() {
+        return { played: this.playedAs, at: this.playedAt };
+    }
+    /** Whether `played` settled true, which its owner counted. */
+    get passed() {
+        return this.playedAs === true;
+    }
+    /** Whether `played` settled false: it left before its last pass ended. */
+    get unplayed() {
+        return this.playedAs === false;
+    }
+    /**
+     * A seek back to mix time `t`: `done` and `played`, where they settled after it, start over with
+     * fresh promises. True where `played` had settled true, which its owner counted.
+     */
+    reopen(t) {
+        let unplayed = false;
+        if (this.playedAs !== undefined && !(this.playedAt <= t)) {
+            unplayed = this.playedAs;
+            this.playedAs = undefined;
+            this.playedPromise = null;
+            this.playedSettle = null;
+        }
+        if (this.finished && !(this.doneAt <= t)) {
+            this.finished = false;
+            this.donePromise = null;
+            this.doneSettle = null;
+        }
+        return unplayed;
+    }
+    /**
+     * A seek back to before its cue: out of the mix, as `cue` left it, until the mix plays the cue
+     * again. What it played since is forgotten, and `done` and `played` start over where they had
+     * settled.
+     */
+    park() {
+        this.reopen(Number.NEGATIVE_INFINITY);
+        const c = this.first;
+        this.anchorNow = c.anchorNow;
+        this.anchorElapsed = c.anchorElapsed;
+        this.rate = c.rate;
+        this.ramp = c.ramp;
+        this.weight = c.weight;
+        this.out = c.out;
+        this.start = c.start;
+        this.outAt = c.outAt;
+        this.outOver = c.outOver;
+        this.outSet = c.outSet;
+        this.log = null;
+        this.state = 'pending';
+        this.subjects = new Store();
+        this.scratch = [];
+        this.holder = null;
+        this.laned = false;
+        this.seeks++;
+        this.keeping = false;
+        this.parts = null;
+        this.parted = null;
+        this.opened = Number.NaN;
+        this.dueToken++;
+        this.early = null;
+        this.seen = 0;
+        this.latest = 0;
+        this.restedCount = 0;
+        this.cuedAt = Number.NEGATIVE_INFINITY;
+        this.doneAt = Number.POSITIVE_INFINITY;
+        this.placing = false;
+        this.answers = null;
+        this.keepOn = null;
+        this.ownKept = null;
+        this.unreached = null;
+        this.unreachedBits = null;
+        if (this.holding !== null)
+            this.holding = new Holding();
     }
     constructor(id, spec, patch, fade, now, start, slotOf, channels, host, send, 
     /** The owner whose clock it runs on, its start included; null for one on the mix clock. */
@@ -277,8 +383,11 @@ export class Voice {
             ramp: this.ramp,
             weight: this.weight,
             out: this.out,
+            back: this.back,
             start: this.start,
             outAt: this.outAt,
+            outOver: this.outOver,
+            outSet: this.outSet,
         });
     }
     /**
@@ -306,8 +415,11 @@ export class Voice {
             v.ramp = controls.ramp;
             v.weight = controls.weight;
             v.out = controls.out;
+            v.back = controls.back;
             v.start = controls.start;
             v.outAt = controls.outAt;
+            v.outOver = controls.outOver;
+            v.outSet = controls.outSet;
         }
         v.quiet = true;
         v.unreached = null;

package/dist/weigh.js

@@ -27,7 +27,7 @@ export function horizonFor(voice, delay, now) {
 }
 /** The ramp a voice's own fade envelope applies this frame, 0..1. */
 export function fadeOf(voice, now, since) {
-    return envelope(voice.fade.in ?? 0, voice.out, voice.ease, this.reducedNow, now, since);
+    return envelope(voice.fade.in ?? 0, voice.out, voice.ease, this.reducedNow, now, since, voice.back);
 }
 /** What every owner above a voice multiplies into its weight for a subject this frame. */
 export function ownedBy(voice, subject) {
@@ -84,6 +84,6 @@ export function base(voice, subject, now, held, slot = -1) {
             ? signal(subject, voice.setting)
             : this.blended(voice, subject, held, slot);
     if (signal.input && !was)
-        record(this, held, base);
+        record(this, voice, subject, held, base);
     return base;
 }