@msb235/blits 0.6.0 → 0.7.1

package/dist/mixer.d.ts

@@ -1,20 +1,26 @@
 import { blended, laneRead, shareKept } from './blend.js';
 import type { Book } from './book.js';
-import { aims, chain, linkable } from './chain.js';
+import { aims, chain, linkable, relink } from './chain.js';
 import { type LerpInto } from './channels.js';
 import type { Due } from './due.js';
 import { parting } from './fade.js';
-import { apply, baseFor, clamp, fold, folded, foldLoci, foldWith, influence, isRest, type Key, keyed, linked, owedBy, passes, read, slopeFor, tick } from './fold.js';
+import { apply, baseFor, clamp, contribution, fold, folded, foldLoci, foldWith, isRest, type Key, keyed, linked, owedBy, passes, read, slopeFor, tick } from './fold.js';
+import { GoneIndex } from './gone.js';
 import type { HandleHost } from './handle.js';
 import { held, shownOf, sinceOf, unreachedOf } from './held.js';
 import { Lanes } from './lanes.js';
 import { foldLocus, type LocusScratch } from './locus.js';
-import type { MotionOwner, Motions } from './motion.js';
-import { Pace } from './pace.js';
+import type { MotionOwner, Motions } from './motions.js';
+import type { Pace } from './pace.js';
+import { Keys } from './paging.js';
 import { keep } from './pull.js';
 import { Steps } from './relink.js';
+import { Outs } from './revive.js';
+import { ScoreIndex } from './scored.js';
+import { Fitting } from './spans.js';
 import { Store } from './store.js';
-import type { Booker, BookOptions, Channel, Columns, Engine, Handle, Kit, Marked, Mix, MixOptions, OwnerSpec, Patch, Projection, Sent, Signal, VoiceSpec } from './types.js';
+import { type Announced, Transport } from './transport.js';
+import type { Booker, BookOptions, Channel, Columns, Engine, Handle, Kit, Marked, Mix, MixOptions, OwnerSpec, Patch, Projection, Sent, Signal, SpanHandle, SpanSpec, Tape, VoiceSpec } from './types.js';
 import { type Subject, type Voice } from './voice.js';
 import { base, capped, fadeOf, horizonFor, ownedBy, ownerBase, prime, weigh, weighOwned } from './weigh.js';
 export declare class Mixer<I, O> implements Mix<I, O> {
@@ -23,6 +29,8 @@ export declare class Mixer<I, O> implements Mix<I, O> {
     cued: Voice<I, O>[];
     /** Under `history`, voices that have left but that a read back may still reach. */
     gone: Voice<I, O>[];
+    goneIx: GoneIndex<I, O>;
+    scored: ScoreIndex<I, O>;
     /** Set on a projection's own mixer: it sends nothing, keeps no history, and reads without committing. */
     projecting: boolean;
     /** Set on a projection reading back: a subject it has nothing on starts from its voice's start. */
@@ -37,19 +45,6 @@ export declare class Mixer<I, O> implements Mix<I, O> {
         at: number;
         fields: Record<string, unknown>;
     }[];
-    /**
-     * Marks the host announced on a score: `at` in host time, so the mix's 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.
-     */
-    announced: {
-        name: string;
-        score: string | undefined;
-        tags: readonly string[];
-        at: number;
-        made: number;
-        order: number;
-    }[];
     hostThen: {
         fields: Record<string, unknown>;
     } | undefined;
@@ -60,22 +55,17 @@ export declare class Mixer<I, O> implements Mix<I, O> {
         prev: O | undefined;
         prevAt: number;
     }>;
-    nextId: number;
-    /**
-     * The mix clock: host time at the mix's rate. Host time is the host's timestamp less every gap
-     * `rebase` has taken out, `u` at the last sync.
-     */
-    now: number;
-    u: number;
+    /** The clock this mix plays on, which also holds its tape and the marks announced on it. */
+    readonly transport: Transport;
+    /** Its place among the mixes on its transport, in the order they joined. */
+    slot: number;
+    /** Taken off its transport, so it takes no more calls until a seek puts it back. */
+    dropped: boolean;
+    readonly name: string | undefined;
     /** This mix's frame among every mix's: moved by a sync, and by a control change or drop within one. */
     frame: number;
-    offset: number;
-    /** The mix's own rate; null while it has never been set, when mix time is host time. */
-    pace: Pace | null;
     /** Pending voices whose start the host gave, by its host time, kept where the rate puts it. */
     pins: Map<Voice<I, O>, number> | null;
-    last: number;
-    rebasing: boolean;
     wantsPose: boolean;
     /** The pose `pull` folds a subject into where it cannot read straight from the lanes. */
     scratch: O | undefined;
@@ -110,7 +100,7 @@ export declare class Mixer<I, O> implements Mix<I, O> {
      * where none does. Relinked when `version` moves, which is whenever the list or a voice's pending
      * state changes.
      */
-    readonly chains: Store<I, Subject<unknown>>;
+    chains: Store<I, Subject<unknown>>;
     version: number;
     readonly steps: Steps<Voice<I, O>>;
     /** Per subject, the voices whose `subjects` name it, in voice order. */
@@ -143,7 +133,9 @@ export declare class Mixer<I, O> implements Mix<I, O> {
         subject: I;
     };
     readonly send: (event: unknown) => void;
-    /** The weight `influence` found besides the delta, read by the caller at once. */
+    /** The moment a seek went back to: what is stepped again up to it was sent the first time. */
+    sentTo: number;
+    /** The weight `contribution` found besides the delta, read by the caller at once. */
     w: number;
     readonly names: Key<O>[];
     readonly channels: Channel<unknown>[];
@@ -155,13 +147,36 @@ export declare class Mixer<I, O> implements Mix<I, O> {
     readonly locusScratch: LocusScratch<I, O>[];
     locusDepth: number;
     readonly slotOf: Map<string, number>;
-    readonly lanes: Lanes<I, O> | null;
+    lanes: Lanes<I, O> | null;
     handles: HandleHost<I, O> | null;
     /** What `book` made, still booking; null while there is none. */
     bookers: Book<I, O>[] | null;
+    /** The fit a span being cued takes, which `cue` hands its voice. */
+    fitting: Fitting | null;
     /** Every owner still in the mix, null until one is cued. */
     owners: Voice<I, O>[] | null;
+    /** With a history store, the key each subject is paged under; null without one. */
+    keys: Keys | null;
+    /** With a history store, the voices it paged out whose handles are still held; null without one. */
+    outs: Outs | null;
     constructor(kit: Kit<O>, opts: MixOptions);
+    /** Throws where the clock is a shared transport's, which only the transport moves. */
+    private own;
+    get now(): number;
+    set now(v: number);
+    get u(): number;
+    set u(v: number);
+    get offset(): number;
+    set offset(v: number);
+    get pace(): Pace | null;
+    set pace(v: Pace | null);
+    get announced(): Announced[];
+    set announced(v: Announced[]);
+    get nextId(): number;
+    set nextId(v: number);
+    get last(): number;
+    get tape(): Tape | undefined;
+    get replaying(): boolean;
     get reduced(): boolean;
     get band(): {
         on: number;
@@ -170,17 +185,21 @@ export declare class Mixer<I, O> implements Mix<I, O> {
     cue(spec: VoiceSpec<I, O>): Handle<I>;
     blend(patches: readonly Patch<I, O, unknown>[], by: Signal<I>, spec?: Omit<VoiceSpec<I, O>, 'patch' | 'weight' | 'locus'>): Handle<I>[];
     owns(spec: OwnerSpec<I>): Handle<I>;
+    span(spec: SpanSpec<I>): SpanHandle<I>;
     sync(timestamp: number): void;
-    private syncAt;
     book(opts: BookOptions): Booker;
     probe(subject: I, out?: O): O;
     pull(subjects: Iterable<I>, into: Columns<O>): void;
-    project(timestamp: number): Projection<I, O>;
+    seek(time: number): void;
+    prepare(time: number): Promise<void>;
+    project(time: number): Projection<I, O>;
     announce(name: string, opts?: {
         at?: number;
         score?: string;
         tags?: readonly string[];
     }): void;
+    /** Throws for a mix taken off its transport. */
+    attached(): void;
     marks(from: number, to: number): Marked[];
     atRest(subject: I): boolean;
     rests(pose: O): boolean;
@@ -225,7 +244,7 @@ declare const methods: {
     owedBy: typeof owedBy;
     foldLoci: typeof foldLoci;
     read: typeof read;
-    influence: typeof influence;
+    contribution: typeof contribution;
     keyed: typeof keyed;
     tick: typeof tick;
     apply: typeof apply;
@@ -248,6 +267,7 @@ declare const methods: {
     shareKept: typeof shareKept;
     parting: typeof parting;
     chain: typeof chain;
+    relink: typeof relink;
     linkable: typeof linkable;
     aims: typeof aims;
     held: typeof held;

package/dist/mixer.js

@@ -1,22 +1,29 @@
 import { blended, blendOf, laneRead, shareKept } from './blend.js';
-import { aims, chain, linkable } from './chain.js';
+import { aims, chain, linkable, relink } from './chain.js';
 import { lerpInto } from './channels.js';
 import { cue } from './cue.js';
 import { beginFade, parting } from './fade.js';
-import { apply, baseFor, clamp, fold, folded, foldLoci, foldWith, influence, isRest, keyed, linked, near, owedBy, passes, read, slopeFor, tick, } from './fold.js';
+import { apply, baseFor, clamp, contribution, fold, folded, foldLoci, foldWith, isRest, keyed, linked, near, owedBy, passes, read, slopeFor, tick, } from './fold.js';
+import { GoneIndex, goneIndex } from './gone.js';
 import { held, shownOf, sinceOf, unreachedOf } from './held.js';
+import { leave, releasing } from './history.js';
 import { book, laneHost } from './hosts.js';
 import { Lanes } from './lanes.js';
 import { foldLocus } from './locus.js';
 import { listed } from './marks.js';
-import { move, nextFrame, waits } from './move.js';
+import { nextFrame } from './move.js';
 import { ownerPatch } from './owner.js';
-import { Pace } from './pace.js';
-import { pin } from './place.js';
-import { project } from './project.js';
+import { Keys } from './paging.js';
+import { projectAll } from './project.js';
 import { keep, pull } from './pull.js';
 import { Steps } from './relink.js';
+import { Outs } from './revive.js';
+import { ScoreIndex } from './scored.js';
+import { seek } from './seek.js';
+import { Fitting, refit } from './spans.js';
 import { Store } from './store.js';
+import { record } from './tape.js';
+import { announce, Transport } from './transport.js';
 import { none } from './voice.js';
 import { base, capped, fadeOf, horizonFor, ownedBy, ownerBase, prime, weigh, weighOwned, } from './weigh.js';
 // biome-ignore lint/suspicious/noUnsafeDeclarationMerging: every member of `Methods` is installed below
@@ -26,6 +33,8 @@ export class Mixer {
     cued = [];
     /** Under `history`, voices that have left but that a read back may still reach. */
     gone = [];
+    goneIx = new GoneIndex();
+    scored = new ScoreIndex();
     /** Set on a projection's own mixer: it sends nothing, keeps no history, and reads without committing. */
     projecting = false;
     /** Set on a projection reading back: a subject it has nothing on starts from its voice's start. */
@@ -37,31 +46,20 @@ export class Mixer {
      * a projection reading back, the copy in force then.
      */
     hostLog = [];
-    /**
-     * Marks the host announced on a score: `at` in host time, so the mix's 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.
-     */
-    announced = [];
     hostThen;
     /** Each subject's last two poses and when they were probed, for `from: 'current'`. */
     pose = new Store();
-    nextId = 1;
-    /**
-     * The mix clock: host time at the mix's rate. Host time is the host's timestamp less every gap
-     * `rebase` has taken out, `u` at the last sync.
-     */
-    now = Number.NaN;
-    u = Number.NaN;
+    /** The clock this mix plays on, which also holds its tape and the marks announced on it. */
+    transport;
+    /** Its place among the mixes on its transport, in the order they joined. */
+    slot = -1;
+    /** Taken off its transport, so it takes no more calls until a seek puts it back. */
+    dropped = false;
+    name;
     /** This mix's frame among every mix's: moved by a sync, and by a control change or drop within one. */
     frame = nextFrame();
-    offset = 0;
-    /** The mix's own rate; null while it has never been set, when mix time is host time. */
-    pace = null;
     /** Pending voices whose start the host gave, by its host time, kept where the rate puts it. */
     pins = null;
-    last = Number.NaN;
-    rebasing = false;
     wantsPose = false;
     /** The pose `pull` folds a subject into where it cannot read straight from the lanes. */
     scratch;
@@ -94,10 +92,13 @@ export class Mixer {
         if (this.stirred)
             return;
         this.stirred = true;
+        if (this.syncing)
+            return;
         const fns = this.stirFns;
-        if (fns !== null && !this.syncing)
+        if (fns !== null)
             for (const fn of [...fns])
                 fn();
+        this.transport.woke();
     }
     onWake(fn) {
         if (this.stirFns === null)
@@ -149,7 +150,7 @@ export class Mixer {
     };
     send = (event) => {
         const { voice, subject } = this.sending;
-        if (voice === null || this.projecting)
+        if (voice === null || this.projecting || voice.setting.timestamp <= this.sentTo)
             return;
         this.sent.push({
             timestamp: voice.setting.timestamp,
@@ -159,7 +160,9 @@ export class Mixer {
             event,
         });
     };
-    /** The weight `influence` found besides the delta, read by the caller at once. */
+    /** The moment a seek went back to: what is stepped again up to it was sent the first time. */
+    sentTo = Number.NEGATIVE_INFINITY;
+    /** The weight `contribution` found besides the delta, read by the caller at once. */
     w = 0;
     names;
     channels;
@@ -175,8 +178,14 @@ export class Mixer {
     handles = null;
     /** What `book` made, still booking; null while there is none. */
     bookers = null;
+    /** The fit a span being cued takes, which `cue` hands its voice. */
+    fitting = null;
     /** Every owner still in the mix, null until one is cued. */
     owners = null;
+    /** With a history store, the key each subject is paged under; null without one. */
+    keys = null;
+    /** With a history store, the voices it paged out whose handles are still held; null without one. */
+    outs = null;
     constructor(kit, opts) {
         this.kit = kit;
         this.opts = opts;
@@ -188,6 +197,75 @@ export class Mixer {
             this.slotOf.set(k, i);
         });
         this.lanes = opts.lanes === false ? null : new Lanes(laneHost(this));
+        this.name = opts.name;
+        const shared = opts.transport;
+        if (shared !== undefined) {
+            if (opts.history !== undefined)
+                throw new Error('blits: a mix on a transport keeps the history the transport keeps, not its own');
+            this.opts = { ...opts, history: shared.history };
+            this.transport = shared;
+        }
+        else
+            this.transport = new Transport(opts.history, false);
+        if (this.transport.pager !== null) {
+            this.keys = new Keys(opts.keyOf);
+            this.outs = new Outs();
+            if (shared !== undefined)
+                named(shared, opts.name);
+        }
+        this.transport.join(this);
+    }
+    /** Throws where the clock is a shared transport's, which only the transport moves. */
+    own(what) {
+        if (this.transport.shared)
+            throw new Error(`blits: ${this.name ?? 'this mix'} plays on a transport, so ${what} goes to the transport`);
+        return this.transport;
+    }
+    // The transport's clock, read and written as the mix's own by every module that moves it.
+    get now() {
+        return this.transport.now;
+    }
+    set now(v) {
+        this.transport.now = v;
+    }
+    get u() {
+        return this.transport.u;
+    }
+    set u(v) {
+        this.transport.u = v;
+    }
+    get offset() {
+        return this.transport.offset;
+    }
+    set offset(v) {
+        this.transport.offset = v;
+    }
+    get pace() {
+        return this.transport.pace;
+    }
+    set pace(v) {
+        this.transport.pace = v;
+    }
+    get announced() {
+        return this.transport.announced;
+    }
+    set announced(v) {
+        this.transport.announced = v;
+    }
+    get nextId() {
+        return this.transport.nextId;
+    }
+    set nextId(v) {
+        this.transport.nextId = v;
+    }
+    get last() {
+        return this.transport.last;
+    }
+    get tape() {
+        return this.transport.tape;
+    }
+    get replaying() {
+        return this.transport.replaying;
     }
     get reduced() {
         const r = this.opts.reduce;
@@ -197,6 +275,7 @@ export class Mixer {
         return this.opts.band ?? { on: 0.6, off: 0.4 };
     }
     cue(spec) {
+        this.attached();
         const engine = this.opts.engine ?? mixer;
         if (!engine.runs.has(spec.patch.form))
             throw new Error(`blits: engine ${engine.name} does not run ${spec.patch.form} patches`);
@@ -218,38 +297,19 @@ export class Mixer {
             throw new Error('blits: an owner does not loop: a pass would have to restart its children');
         return this.cue({ ...spec, patch: ownerPatch });
     }
-    sync(timestamp) {
-        this.syncing = true;
+    span(spec) {
+        this.fitting = new Fitting(spec);
         try {
-            this.syncAt(timestamp);
+            const handle = this.owns(spec);
+            refit(this, this.owners?.find((v) => v.handle === handle));
+            return handle;
         }
         finally {
-            this.syncing = false;
+            this.fitting = null;
         }
     }
-    syncAt(timestamp) {
-        if (this.rebasing && !Number.isNaN(this.last))
-            this.offset += timestamp - this.last;
-        this.rebasing = false;
-        this.last = timestamp;
-        const u = timestamp - this.offset;
-        const pace = this.pace;
-        const now = pace === null ? u : pace.sync(u);
-        const later = u !== this.u;
-        const still = later && now === this.now;
-        this.u = u;
-        // Host time moving while the mix clock stands still lands what waits on host time or the host.
-        if (now !== this.now || (later && pace !== null && waits(this)))
-            move(this, now);
-        // It is a frame too, which asks every weight signal again, so one reading input follows it.
-        if (still) {
-            this.frame = nextFrame();
-            this.lanes?.refill();
-        }
-        const bookers = this.bookers;
-        if (bookers !== null)
-            for (const b of bookers)
-                b.sync();
+    sync(timestamp) {
+        this.own('sync').sync(timestamp);
     }
     book(opts) {
         return book(this, opts);
@@ -265,20 +325,25 @@ export class Mixer {
     pull(subjects, into) {
         pull(this, subjects, into);
     }
-    project(timestamp) {
-        const c = new Mixer(this.kit, { ...this.opts, history: undefined, lanes: false });
-        return project(this, c, timestamp);
+    seek(time) {
+        if (this.projecting)
+            throw new Error('blits: a projection does not seek');
+        seek(this.own('seek'), time);
+    }
+    prepare(time) {
+        return this.own('prepare').prepare(time);
+    }
+    project(time) {
+        return projectAll(this.transport, time).of(this);
     }
     announce(name, opts = {}) {
-        const at = opts.at !== undefined ? opts.at - this.offset : this.u;
-        this.announced.push({
-            name,
-            score: opts.score,
-            tags: opts.tags ?? none,
-            at,
-            made: Number.isNaN(this.now) ? Number.NEGATIVE_INFINITY : this.now,
-            order: this.nextId++,
-        });
+        this.attached();
+        announce(this.transport, name, opts, this.slot, this.name);
+    }
+    /** Throws for a mix taken off its transport. */
+    attached() {
+        if (this.dropped)
+            throw new Error(`blits: ${this.name ?? 'this mix'} was dropped from its transport`);
     }
     marks(from, to) {
         return listed(this, from, to).map(({ order: _, ...m }) => m);
@@ -316,7 +381,7 @@ export class Mixer {
         return true;
     }
     rebase() {
-        this.rebasing = true;
+        this.own('rebase').rebase();
     }
     voices(tag) {
         const out = [];
@@ -341,25 +406,13 @@ export class Mixer {
         return this.cued.every((v) => this.still(v, this.now));
     }
     get rate() {
-        return this.pace === null ? 1 : this.pace.rateAt(this.u);
+        return this.transport.rate;
     }
     set rate(r) {
-        this.ramp(r, 0);
+        this.own('rate').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.opts.history !== undefined);
-            // Until now mix time was host time, so a pending voice's start is the host time it was given.
-            for (const v of this.cued)
-                if (v.state === 'pending' && !v.placing && v.owner === null && v.spec.start !== undefined)
-                    pin(this, v, v.start);
-        }
-        const history = this.opts.history;
-        const reach = history === undefined ? Number.NEGATIVE_INFINITY : this.now - history.ms;
-        this.pace.change(this.u, rate, over, reach);
-        this.stir();
+        this.own('ramp').ramp(rate, over);
     }
     /** Whether a voice will change no pose from `now` on, short of a change made to it. */
     still(voice, now) {
@@ -380,6 +433,7 @@ export class Mixer {
     mute(opts) {
         for (const voice of this.cued)
             beginFade(this, voice, { over: opts?.over });
+        record(this, 'mute', () => this.mute(opts));
     }
     drop(subject) {
         this.frame = nextFrame();
@@ -397,9 +451,11 @@ export class Mixer {
         this.stir();
         // A record of it is only in a voice over every subject, one naming it, or one gone; a ramp out
         // of a voice that does not name it is in `parters`, and a patch's own state in `motions`.
+        const kept = releasing(this);
         const forget = (voice) => {
+            leave(this, voice, subject, voice.subjects.get(subject));
             voice.subjects.delete(subject);
-            voice.motion?.release(subject);
+            voice.motion?.release(subject, ...kept);
             voice.parts?.delete(subject);
             voice.parted?.delete(subject);
             voice.blend?.of.reads.delete(subject);
@@ -410,8 +466,13 @@ export class Mixer {
         if (named !== undefined)
             for (const voice of [...named])
                 forget(voice);
-        for (const voice of this.gone)
+        const gone = goneIndex(this);
+        for (const voice of gone.general)
             forget(voice);
+        const goneNaming = gone.named.get(subject);
+        if (goneNaming !== undefined)
+            for (const voice of goneNaming)
+                forget(voice);
         if (this.owners !== null)
             for (const voice of this.owners)
                 forget(voice);
@@ -427,10 +488,11 @@ export class Mixer {
         const strays = this.strays.get(subject);
         if (strays !== undefined)
             for (const motion of strays)
-                motion.release(subject);
+                motion.release(subject, ...kept);
         this.strays.delete(subject);
         for (const motion of this.strayAll)
-            motion.release(subject);
+            motion.release(subject, ...kept);
+        record(this, 'drop', () => this.drop(subject));
     }
     drain(tag) {
         const all = this.sent;
@@ -491,7 +553,7 @@ const methods = {
     owedBy,
     foldLoci,
     read,
-    influence,
+    contribution,
     keyed,
     tick,
     apply,
@@ -514,6 +576,7 @@ const methods = {
     shareKept,
     parting,
     chain,
+    relink,
     linkable,
     aims,
     held,
@@ -525,6 +588,14 @@ const methods = {
 };
 for (const [name, value] of Object.entries(methods))
     Object.defineProperty(Mixer.prototype, name, { value, writable: true, configurable: true });
+/** Refuses a mix joining a transport with a store unnamed, or under a name history still keys records by. */
+function named(transport, name) {
+    if (name === undefined)
+        throw new Error('blits: a mix on a transport whose history has a store needs a name, which its records are keyed by');
+    const taken = [...transport.members, ...transport.dropped.map((d) => d.mix)];
+    if (taken.some((m) => m.name === name))
+        throw new Error(`blits: a mix named ${name} is already on this transport, or a seek could bring it back`);
+}
 /**
  * The one that ships: every form on the CPU, probed per subject on demand.
  *