@msb235/blits 0.6.0 → 0.7.0

package/dist/mixer.js

@@ -1,22 +1,27 @@
 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 { 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 { 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
@@ -37,31 +42,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 +88,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 +146,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 +156,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 +174,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 +193,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 +271,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 +293,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 +321,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 +377,7 @@ export class Mixer {
         return true;
     }
     rebase() {
-        this.rebasing = true;
+        this.own('rebase').rebase();
     }
     voices(tag) {
         const out = [];
@@ -341,25 +402,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 +429,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 +447,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);
@@ -427,10 +479,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 +544,7 @@ const methods = {
     owedBy,
     foldLoci,
     read,
-    influence,
+    contribution,
     keyed,
     tick,
     apply,
@@ -514,6 +567,7 @@ const methods = {
     shareKept,
     parting,
     chain,
+    relink,
     linkable,
     aims,
     held,
@@ -525,6 +579,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.
  *

package/dist/motion.d.ts

@@ -1,5 +1,5 @@
-import { type Curve } from './easing.js';
-import type { Easing, MotionSpec, Patch } from './types.js';
+import { Motions } from './motions.js';
+import type { Easing, Patch } from './types.js';
 /**
  * A number, or one number per axis.
  *
@@ -22,32 +22,6 @@ export interface Motion<V extends Value = number> {
     /** Units per second. */
     velocity: V;
 }
-interface Change {
-    /**
-     * Voice ms it takes effect at; absent, until the subject's next read stamps it with that read's
-     * time, for one made while no frame had met the subject.
-     */
-    at?: number;
-    to?: number[];
-    v?: number[];
-}
-/**
- * The mix playing a patch, asked with its voice's id: an owner and an id, where a pair of closures
- * cost two functions, their contexts and a weak reference per voice.
- */
-export interface MotionOwner {
-    /** The subject's voice time at the mix's latest frame; NaN where no frame of the voice met it. */
-    frame(id: number, subject: unknown): number;
-    /** Brings a subject the voice faded out back to it, so a change is not made for nothing. */
-    revive(id: number, subject: unknown): void;
-}
-/**
- * What a mix keeping copies of a patch's stretches is told, with its id and the subject's number,
- * before one changes.
- */
-export interface Watcher {
-    stretchChanged(id: number, s: number): void;
-}
 /**
  * A patch whose motion is a closed form per subject, so it lands in the same place at any frame
  * rate, and whose changes mid-flight start from where the subject is and how fast it moves.
@@ -68,177 +42,6 @@ export type Moving<I, O, V extends Value> = Patch<I, O, void> & {
      */
     push(subject: I, velocity: V, at?: number): void;
 };
-interface Shape<I> {
-    from: (subject: I) => number[];
-    /** How fast each axis starts moving, given where it starts: still unless the options say. */
-    velocity: (subject: I, x: number[]) => number[];
-    /** Where it heads when released from `x` at `v`, given where it was heading. */
-    aim: (x: number[], v: number[], was: number[] | null, subject: I) => number[];
-    /** `[form, settle, k1, k2, k3]`. */
-    law: readonly number[];
-    /** Whether a subject's value is a number rather than an array. */
-    scalar: (subject: I) => boolean;
-    /** Whether every subject's value is a number; undefined where that depends on the subject. */
-    scalarEvery(): boolean | undefined;
-    /** A tween's easing, which its law cannot hold; undefined, but present, on every other shape. */
-    ease: Curve | undefined;
-    /** A tween's seconds for a stretch the subject starts now; undefined, but present, on the rest. */
-    ms: ((subject: I) => number) | undefined;
-    /** The patch's kind and constants, as `Patch.motion` reports them. */
-    spec(): MotionSpec;
-}
-/**
- * A motion patch's subjects: the stretch each is playing, in one flat array by a number the patch
- * gives it, with earlier stretches a read back may reach and changes not yet applied beside them.
- * The one copy, read by `at` and by a mix's lane alike.
- *
- * After the law, each subject's run of `stride` numbers is its release time, its flags, a tween's
- * seconds for the stretch, then `x0`, `v0` and `to` per axis. A live sample reads this one buffer and nothing else the patch owns: at
- * 10k springs of one subject each, a buffer per field, a map lookup per sample and the law in an
- * object of its own took a call from 130 ns to 490.
- */
-export declare class Motions<I> {
-    private readonly shape;
-    private readonly numbers;
-    /** Numbers by subject once a second is numbered: till then the one subject is found by `numbers`. */
-    private readonly slots;
-    /** Axes per subject; -1 until the first subject sets it. */
-    n: number;
-    private cap;
-    private stride;
-    /**
-     * The law, then each subject's run; empty until the first subject, the law read from `shape`.
-     * Read outside, at `bareAt`, and written only here.
-     */
-    runs: Float64Array<ArrayBuffer>;
-    /**
-     * Where `sample` leaves a subject's position and velocity, per axis. Shared by every patch, so
-     * read it before the next sample.
-     */
-    xs: Float64Array<ArrayBuffer>;
-    vs: Float64Array<ArrayBuffer>;
-    /**
-     * By subject number, changes not yet applied and earlier stretches a read back may reach: null
-     * until a subject first has one, since many patches are never changed. Each starts with room for
-     * one: an empty array written at 0 reserves 17, and most patches have one subject.
-     */
-    private pending;
-    private older;
-    /**
-     * The mix playing the patch and its voice's id, which an untimed change and a `read` with no time
-     * ask for the latest frame. Set by the mix that cues the patch, and cleared when its voice retires.
-     */
-    owner: MotionOwner | null;
-    ownerId: number;
-    /** Whether the channel it was cued on holds a number; undefined until it is cued. */
-    private holdsNumber;
-    private channel;
-    /**
-     * Records what the channel the patch is cued on holds, refusing a value of the other kind: at once
-     * where every subject's value is one kind, else on the first sample of a subject whose value is not.
-     */
-    cuedOn(channel: string, holdsNumber: boolean): void;
-    private frame;
-    constructor(shape: Shape<I>);
-    /** The patch's number for `subject`, made with its first stretch on first ask. */
-    slot(subject: I): number;
-    /** The patch's number for `subject`, undefined where it has none. */
-    private known;
-    /** Forgets a subject, so a later ask starts it afresh from `from`. */
-    release(subject: I): void;
-    /**
-     * Told, with `watchId`, whenever a subject's stretch or what is pending for it changes, so a mix
-     * keeping a copy of it knows to read it again. Set by the mix, cleared when its voice retires. An
-     * owner and an id, where a callback cost a closure and its context per patch.
-     */
-    watcher: Watcher | null;
-    watchId: number;
-    /** The easing a tween's stretches follow; undefined for every other shape. */
-    get ease(): Curve | undefined;
-    /** The patch's kind and constants. */
-    spec(): MotionSpec;
-    /** A copy of the patch's law, `[form, settle, k1, k2, k3]`. */
-    law(): Float64Array;
-    /** Whether `law` holds this patch's law, number for number, as `Object.is` compares them. */
-    hasLaw(law: Float64Array): boolean;
-    /**
-     * Copies subject `s`'s current stretch into `out` from `o` as its release time, its seconds, then
-     * `x0`, `v0` and `to` per axis; false, copying nothing, while it has a change pending or an
-     * earlier stretch kept, which only `sample` handles.
-     */
-    stretchInto(s: number, out: Float64Array, o: number): boolean;
-    /** Whether subject `s`'s value is a number rather than an array. */
-    scalar(s: number): boolean;
-    /** The value `at` hands the mix: the first axis for a number, a fresh array otherwise. */
-    value(s: number, xs: Float64Array): number | number[];
-    /**
-     * Position and velocity at voice time `t` into `xo` and `vo`, a tween's velocity left at 0. A live
-     * read stamps every untimed change with `t` and commits every change due by then, in time order;
-     * a projection's read applies the timed ones to a copy and commits nothing.
-     */
-    sample(s: number, t: number, xo: Float64Array, vo: Float64Array): void;
-    /**
-     * Where subject `s`'s run starts in `runs` (its release time, then flags, seconds, `x0`, `v0`
-     * and `to`) while it has nothing pending and no earlier stretch kept; -1 for any other.
-     */
-    bareAt(s: number): number;
-    /**
-     * A live `sample` at `t` for a subject with nothing pending and no earlier stretch kept, true
-     * then; false, writing nothing, for any other, which `quiet` and `sample` take instead.
-     */
-    sampleBare(s: number, t: number, xo: Float64Array, vo: Float64Array): boolean;
-    /**
-     * Whether every subject has landed on its target at its voice time at the latest frame, as a
-     * sample there would find; one with a change waiting has not. Commits nothing.
-     */
-    landed(): boolean;
-    /**
-     * Whether a live `sample` at `t` would leave the subject's state as it is: nothing to stamp or
-     * commit by then, and nothing older than `reading.horizon` to let go of.
-     */
-    quiet(s: number, t: number): boolean;
-    /** Position and velocity at `at`, default the latest frame; undefined until there is one. */
-    read(subject: I, at?: number): {
-        x: Float64Array;
-        v: Float64Array;
-        s: number;
-    } | undefined;
-    /**
-     * Queues a retarget or push, untimed at the latest frame, for `subject`'s next read past its time.
-     * The queue keeps the changes with a time in time order, ahead of any still waiting for one.
-     */
-    change(subject: I, c: Change): void;
-    /** Files a change with a time after every one due by then, ahead of those still waiting for one. */
-    private queue;
-    /** Every change due by `t` applied to a copy of the stretch playing then, committing nothing. */
-    private peek;
-    private check;
-    private flag;
-    forget(s: number): void;
-    /** Where subject `s`'s run starts in `runs`. */
-    base(s: number): number;
-    private grow;
-    private write;
-    /** The stretch subject `s` is playing now, as an object. */
-    private latest;
-    /** The stretch playing at voice time `t`: the latest released by then, else the first. */
-    private playing;
-    private applied;
-    private commit;
-    private insert;
-    /** Lets go of stretches older than the one in force at `reading.horizon`. */
-    private prune;
-    private evaluateSegment;
-    private evaluate;
-}
-/**
- * A stretch `t` voice ms into it, released at `at` from `x0` moving at `v0` toward `to` (each read
- * from its offset), into `xo` and `vo`: the one copy of the closed forms, which `law` (a patch's
- * `[form, settle, k1, k2, k3]`, the head of a patch's buffer or a copy of it) picks between. A tween reads `ease` and
- * `ms`, the stretch's length, dividing in milliseconds so a boundary lands exactly; every other
- * form ignores them.
- */
-export declare function closed(law: Float64Array, ease: Curve | undefined, n: number, at: number, ms: number, x0: ArrayLike<number>, x: number, v0: ArrayLike<number>, v: number, to: ArrayLike<number>, g: number, t: number, xo: Float64Array, vo: Float64Array): boolean;
 /** The state behind a `'motion'` patch, for an engine that reads it directly. */
 export declare function motionOf<I>(p: object): Motions<I> | undefined;
 interface Common<I, V extends Value> {