@msb235/blits 0.7.1 → 0.8.1

package/dist/gather.js

@@ -1,4 +1,5 @@
 import { foldNumber, lerpNumber } from './channels.js';
+import { shortWay, turnFrom, turnInto, turnToward } from './turns.js';
 /** `xs`, or a copy at least `n` long where it is shorter. */
 function sized(xs, n) {
     if (xs.length >= n)
@@ -37,13 +38,11 @@ export function gatherLocus(lanes, g) {
                 continue;
             lanes.intoId = voice.id;
             lanes.reset(lane);
-            const elapsed = voice.elapsedAt(lanes.now);
-            const duration = voice.duration;
-            const passes = voice.passes;
+            lane.elapsedNow = voice.elapsedAt(lanes.now);
             const list = lane.list;
             for (let p = 0; p < list.length; p++) {
                 const slot = list[p];
-                if (lanes.one(lane, p, slot, elapsed, duration, passes)) {
+                if (lanes.one(lane, p, slot)) {
                     meetLocus(lanes, g, slot);
                     g.sum[slot] =
                         g.sum[slot] + lane.data[p * 8 /* Row.STRIDE */ + 2 /* Row.WEIGHT */];
@@ -68,8 +67,12 @@ function meetLocus(lanes, g, slot) {
         if (taken !== undefined)
             taken[slot] = 0;
 }
-/** A member's value for one channel of a subject, lerped into its locus: `foldLocus`'s step. */
-function gatherInto(lanes, g, ch, slot, value, w) {
+/**
+ * A member's value for one channel of a subject, lerped into its locus: the step of the general
+ * path's `foldLocus`.
+ */
+function gatherInto(lanes, g, ch, slot, value) {
+    const w = lanes.arg[0 /* Arg.WEIGHT */];
     meetLocus(lanes, g, slot);
     const k = ch.index;
     let values = g.values[k];
@@ -83,7 +86,9 @@ function gatherInto(lanes, g, ch, slot, value, w) {
     const taken = takenAt[slot];
     const total = taken + w;
     const u = w / total;
-    if (ch.scalar) {
+    if (!ch.plain)
+        turnToward(ch, values, slot * ch.axes, value, taken, u);
+    else if (ch.scalar) {
         values[slot] =
             taken === 0 ? value : lerpNumber(values[slot], value, u);
     }
@@ -110,15 +115,21 @@ export function foldLocus(lanes, lane, g) {
         const sum = g.sum[slot];
         if (sum <= 0)
             continue;
-        const w = sum > 1 ? 1 : sum;
         for (let k = 0; k < g.values.length; k++) {
             const takenAt = g.taken[k];
-            if (takenAt === undefined || !(takenAt[slot] > 0))
+            const taken = takenAt === undefined ? 0 : takenAt[slot];
+            if (!(taken > 0))
                 continue;
+            // A channel folds at the weight of the members that wrote it, not the whole locus.
+            const w = taken > 1 ? 1 : taken;
             const ch = lanes.laned[k];
             const values = g.values[k];
             const into = ch.values;
             const base = slot * ch.axes;
+            if (!ch.plain) {
+                turnFrom(ch, into, base, values, base, w);
+                continue;
+            }
             for (let a = 0; a < ch.axes; a++)
                 into[base + a] = foldNumber(ch.op, into[base + a], values[base + a], w);
         }
@@ -130,49 +141,56 @@ export function gather(lane, delta) {
     for (let i = 0; i < chans.length; i++)
         lane.values[i] = delta[chans[i].name];
 }
-/** Folds what `gather` read into a subject's laned values. */
-export function fold(lane, slot, w) {
+/** Folds what `gather` read into a subject's laned values, at `Arg.WEIGHT`. */
+export function fold(lane, slot) {
     const chans = lane.chans;
     for (let i = 0; i < chans.length; i++)
-        this.foldInto(chans[i], slot, lane.values[i], w);
+        this.foldInto(chans[i], slot, lane.values[i]);
 }
 /**
- * Folds a delta a patch returned into a subject's laned values. The first few channels are read
- * at a site of their own, which in most mixes sees one channel name and stays fast, where one
- * site reading every name in turn slows every read.
+ * Folds a delta a patch returned into a subject's laned values, at `Arg.WEIGHT`. The first few
+ * channels are read at a site of their own, which in most mixes sees one channel name and stays
+ * fast, where one site reading every name in turn slows every read.
  */
-export function foldDelta(chans, slot, delta, w) {
+export function foldDelta(chans, slot, delta) {
     const n = chans.length;
     let ch = chans[0];
     if (n > 0)
-        this.foldInto(ch, slot, delta[ch.name], w);
+        this.foldInto(ch, slot, delta[ch.name]);
     ch = chans[1];
     if (n > 1)
-        this.foldInto(ch, slot, delta[ch.name], w);
+        this.foldInto(ch, slot, delta[ch.name]);
     ch = chans[2];
     if (n > 2)
-        this.foldInto(ch, slot, delta[ch.name], w);
+        this.foldInto(ch, slot, delta[ch.name]);
     for (let i = 3; i < n; i++) {
         ch = chans[i];
-        this.foldInto(ch, slot, delta[ch.name], w);
+        this.foldInto(ch, slot, delta[ch.name]);
     }
 }
 /** Folds a motion sample's axes, kept apart from `foldInto` so neither reads two array kinds. */
-export function foldRun(ch, slot, xs, w) {
+export function foldRun(ch, slot, xs) {
+    if (!ch.plain) {
+        this.unplain(ch, slot, ch.scalar ? xs[0] : xs);
+        return;
+    }
+    const w = this.arg[0 /* Arg.WEIGHT */];
     const values = ch.values;
     const base = slot * ch.axes;
     for (let a = 0; a < ch.axes; a++)
         values[base + a] = foldNumber(ch.op, values[base + a], xs[a], w);
 }
-export function foldInto(ch, slot, value, w) {
+/** Folds one channel's value into a subject's laned values, or its locus, at `Arg.WEIGHT`. */
+export function foldInto(ch, slot, value) {
     if (value === undefined)
         return;
     if (this.into !== null) {
-        gatherInto(this, this.into, ch, slot, value, w);
+        gatherInto(this, this.into, ch, slot, value);
         return;
     }
-    if (ch.op === 'last' && !this.gate(ch, w))
+    if (!ch.plain && !this.unplain(ch, slot, value))
         return;
+    const w = this.arg[0 /* Arg.WEIGHT */];
     const values = ch.values;
     if (ch.scalar) {
         values[slot] = foldNumber(ch.op, values[slot], value, w);
@@ -191,7 +209,8 @@ export function foldInto(ch, slot, value, w) {
  * general path's `apply` decides it from the same band state on the same record, so a subject
  * moving between the paths carries it.
  */
-export function gate(ch, w) {
+export function gate(ch) {
+    const w = this.arg[0 /* Arg.WEIGHT */];
     const lane = this.folding;
     const rec = this.rec;
     const i = lane.chans.indexOf(ch);
@@ -202,3 +221,19 @@ export function gate(ch, w) {
     bands[i] = on ? 1 : 2;
     return on;
 }
+/**
+ * `foldInto` for a channel that is not plain, at `Arg.WEIGHT`. A rest-less one asks its band, and
+ * true is a pass, which `foldInto` then folds; a rotation is folded here, so false.
+ */
+export function unplain(ch, slot, value) {
+    if (ch.op === 'last')
+        return this.gate(ch);
+    const w = this.arg[0 /* Arg.WEIGHT */];
+    const values = ch.values;
+    // An angle here and not through `turnInto`, where its weight would cross a call as a boxed double.
+    if (ch.turn > 0)
+        values[slot] = values[slot] + shortWay(value, ch.turn) * w;
+    else
+        turnInto(ch, values, slot * ch.axes, value, w);
+    return false;
+}

package/dist/gone.js

@@ -73,6 +73,14 @@ export function goneIndex(mix) {
     ix.count = list.length;
     return ix;
 }
+/** Hands voices let go of from `gone` to the departed index, noting the latest that left. */
+function forgot(mix, out) {
+    for (const v of out) {
+        mix.departed.add(mix, v);
+        if (v.doneAt > mix.transport.forgotTo)
+            mix.transport.forgotTo = v.doneAt;
+    }
+}
 /**
  * Keeps the gone voices `keep` says yes to, asking it once each, and takes the rest out of the
  * index one by one. Leaves `gone` as it was when every one stays.
@@ -92,6 +100,7 @@ export function keepGone(mix, keep) {
         (keep(v) ? kept : out).push(v);
     }
     remove(ix, out);
+    forgot(mix, out);
     mix.gone = kept;
     scoredCut(mix, list, out);
     ix.of = kept;
@@ -129,6 +138,7 @@ export function expireGone(mix, reach) {
     }
     list.splice(0, end, ...kept);
     remove(ix, out);
+    forgot(mix, out);
     scoredCut(mix, list, out);
     ix.count = list.length;
 }

package/dist/handle.d.ts

@@ -1,13 +1,17 @@
-import type { FadeOptions, FitResult, Handle } from './types.js';
+import { type Motion, type Value } from './motion.js';
+import type { Doubt, FadeOptions, FitResult, Handle, SeekOptions } from './types.js';
 import type { Voice } from './voice.js';
 /** What a voice's handle asks of the mix that cued it: one per mix, shared by every handle. */
 export interface HandleHost<I, O> {
-    /** The mix clock, or the voice's start before the first sync. */
+    /** The mix clock, or its owner's for a voice one holds; the voice's start before either reads. */
     nowFor(voice: Voice<I, O>): number;
     /** A handle write changed the voice: reschedule it, and refill the lanes. */
     changed(voice: Voice<I, O>): void;
-    /** The voice's clock jumped: for an owner, so did every clock it holds. */
-    sought(voice: Voice<I, O>): void;
+    /**
+     * The voice's clock jumped: for an owner, so did every clock it holds. With `rebuild`, their
+     * state is made again for where they now are. How sure that leaves it.
+     */
+    sought(voice: Voice<I, O>, rebuild: boolean): Doubt;
     fade(voice: Voice<I, O>, opts: FadeOptions<I> | undefined): void;
     rise(voice: Voice<I, O>, opts: {
         over?: number;
@@ -16,6 +20,10 @@ export interface HandleHost<I, O> {
     /** Records a write the host made, which `again` makes once more where a seek replays it. */
     record(label: string, again: () => void): void;
 }
+/** Refuses a voice rate no clock can run at. */
+export declare function finiteRate(rate: number): void;
+/** Refuses a voice weight that is no number: NaN would fold into every channel the voice writes. */
+export declare function plainWeight(weight: number): void;
 /** What a handle answers for a voice a history store paged out, which left long ago. */
 export interface Gone {
     weight: number;
@@ -47,10 +55,13 @@ export declare class VoiceHandle<I, O> implements Handle<I> {
     get rate(): number;
     set rate(r: number);
     ramp(r: number, over: number): void;
-    seek(elapsed: number): void;
+    seek(elapsed: number, opts?: SeekOptions): Doubt;
     fade(opts?: FadeOptions<I>): void;
     rise(opts?: {
         over?: number;
     }): void;
     weightOf(subject: I): number;
+    to(subject: I, target: Value, at?: number): void;
+    push(subject: I, velocity: Value, at?: number): void;
+    read(subject: I, at?: number): Motion<Value> | undefined;
 }

package/dist/handle.js

@@ -1,4 +1,16 @@
 import { retime } from './clock.js';
+import { motionOf } from './motion.js';
+import { leave } from './origin.js';
+/** Refuses a voice rate no clock can run at. */
+export function finiteRate(rate) {
+    if (!Number.isFinite(rate))
+        throw new RangeError(`blits: a voice's rate is a finite number, not ${rate}`);
+}
+/** Refuses a voice weight that is no number: NaN would fold into every channel the voice writes. */
+export function plainWeight(weight) {
+    if (Number.isNaN(weight))
+        throw new RangeError('blits: a voice’s weight is a number, not NaN');
+}
 /**
  * A voice's handle: the host's only way to control a voice once cued. A voice a history store
  * pages out is let go of here too, so the handle answers as a gone voice's does, and a seek that
@@ -49,9 +61,11 @@ export class VoiceHandle {
     }
     // A write to a paged voice changes nothing: it had left when the host made it, as it has on replay.
     set weight(w) {
+        plainWeight(w);
         const voice = this.#voice;
         if (voice === null)
             return;
+        voice.written = true;
         voice.weight = w;
         this.#host.changed(voice);
         this.#host.record('weight', () => {
@@ -66,28 +80,40 @@ export class VoiceHandle {
         this.ramp(r, 0);
     }
     ramp(r, over) {
+        finiteRate(r);
         const voice = this.#voice;
         if (voice === null)
             return;
-        retime(voice, this.#host.nowFor(voice), r, over);
+        voice.written = true;
+        const now = this.#host.nowFor(voice);
+        // A pending voice's clock reads 0 at its start, and a rate taken from now would cross 0 sooner:
+        // a subject it freezes before would play, and step, ahead of a voice that has not started.
+        const u = voice.state === 'pending' && voice.start > now && r > 0 ? voice.start : now;
+        leave(voice, u);
+        retime(voice, u, r, over);
         this.#host.changed(voice);
         this.#host.record('rate', () => this.ramp(r, over));
     }
-    seek(elapsed) {
+    seek(elapsed, opts) {
         const voice = this.#voice;
         if (voice === null)
-            return;
-        voice.rebase(this.#host.nowFor(voice));
+            return 'exact';
+        voice.written = true;
+        const u = this.#host.nowFor(voice);
+        leave(voice, u);
+        voice.rebase(u);
         voice.anchorElapsed = elapsed;
         voice.seeks++;
-        this.#host.sought(voice);
+        const doubt = this.#host.sought(voice, opts?.state !== 'keep');
         this.#host.changed(voice);
-        this.#host.record('seek', () => this.seek(elapsed));
+        this.#host.record('seek', () => this.seek(elapsed, opts));
+        return doubt;
     }
     fade(opts) {
         const voice = this.#voice;
         if (voice === null)
             return;
+        voice.written = true;
         this.#host.fade(voice, opts);
         this.#host.record('fade', () => this.fade(opts));
     }
@@ -95,6 +121,7 @@ export class VoiceHandle {
         const voice = this.#voice;
         if (voice === null)
             return;
+        voice.written = true;
         this.#host.rise(voice, opts);
         this.#host.record('rise', () => this.rise(opts));
     }
@@ -102,4 +129,27 @@ export class VoiceHandle {
         const voice = this.#voice;
         return voice === null ? 0 : this.#host.weightOf(voice, subject);
     }
+    // The patch records each of these itself, so a seek plays them again without the handle.
+    to(subject, target, at) {
+        const voice = this.#voice;
+        if (voice !== null)
+            moves(voice.patch, 'to', 'a spring or a tween').to(subject, target, at);
+    }
+    push(subject, velocity, at) {
+        const voice = this.#voice;
+        if (voice !== null)
+            moves(voice.patch, 'push', 'a spring or a glide').push(subject, velocity, at);
+    }
+    read(subject, at) {
+        const voice = this.#voice;
+        if (voice === null || motionOf(voice.patch) === undefined)
+            return undefined;
+        return voice.patch.read(subject, at);
+    }
+}
+/** A voice's patch as a motion that takes `verb`, or a throw naming the kinds that do. */
+function moves(patch, verb, kinds) {
+    if (motionOf(patch) === undefined || typeof patch[verb] !== 'function')
+        throw new Error(`blits: ${verb} needs a voice playing ${kinds}`);
+    return patch;
 }

package/dist/held.d.ts

@@ -3,12 +3,15 @@ import type { Subject, Voice } from './voice.js';
 /** The record a voice gives every subject it does not reach. */
 export declare function unreachedOf<I, O>(this: Mixer<I, O>, voice: Voice<I, O>, now: number): Subject<unknown>;
 /** What this voice holds for this subject, made on first sight with `target` and `stagger` asked once. */
-export declare function held<I, O>(this: Mixer<I, O>, voice: Voice<I, O>, subject: I, now: number, slot: number): Subject<unknown>;
+export declare function held<I, O>(this: Mixer<I, O>, voice: Voice<I, O>, subject: I, slot: number): Subject<unknown>;
 /**
- * When the voice clock reads `delay`, from where it is anchored now; during a ramp this assumes
- * the rate it is ramping to.
+ * The mix time the voice clock first read `delay`, or will by its controls now. A stateful voice
+ * counts from its last seek that rebuilt state, as its records do.
  */
 export declare function sinceOf<I, O>(this: Mixer<I, O>, voice: Voice<I, O>, delay: number): number;
 export declare function shownOf<I, O>(this: Mixer<I, O>, voice: Voice<I, O>, since: number): number;
-/** A voice has gone live: the records it made while pending count from where it started. */
-export declare function started<I, O>(mix: Mixer<I, O>, voice: Voice<I, O>): void;
+/**
+ * A voice's start or clock moved, or it went live at `now`: the records whose `since` was still
+ * ahead count from where its clock now puts them.
+ */
+export declare function reorigin<I, O>(mix: Mixer<I, O>, voice: Voice<I, O>, now: number): void;

package/dist/held.js

@@ -1,41 +1,32 @@
 import { schedule } from './due.js';
-import { mixTime } from './owner.js';
+import { everyoneOf, inherit, sighted } from './everyone.js';
+import { originOf } from './origin.js';
+import { record } from './record.js';
 import { unreach, unreached } from './unreached.js';
 /** The record a voice gives every subject it does not reach. */
 export function unreachedOf(voice, now) {
     const since = this.sinceOf(voice, 0);
-    const none = {
-        reaches: false,
-        delay: 0,
-        since,
-        shown: this.shownOf(voice, since),
-        weight: 0,
-        rested: false,
-        bands: null,
-        state: undefined,
-        stepped: now,
-        ticks: 0,
-        probed: Number.NaN,
-        delta: null,
-        phase: 0,
-        seeks: 0,
-        kept: null,
-        voice,
-        next: null,
-        version: Number.NaN,
-        loci: null,
-        slot: -1,
-    };
+    const none = record(voice, false, undefined);
+    none.since = since;
+    none.shown = this.shownOf(voice, since);
+    none.stepped = now;
+    none.rebuilt = voice.rebuilds;
     voice.unreached = none;
     return none;
 }
 /** What this voice holds for this subject, made on first sight with `target` and `stagger` asked once. */
-export function held(voice, subject, now, slot) {
+export function held(voice, subject, slot) {
+    if (voice.sharing) {
+        const all = everyoneOf(this, voice);
+        if (all !== null)
+            return all;
+    }
     if (unreached(voice, slot))
         return voice.unreached;
     let held = voice.subjects.get(subject);
     if (held !== undefined)
         return held;
+    const now = this.now;
     const reaches = this.aims(voice, subject);
     if (!reaches) {
         // Nothing is kept for a subject the voice does not reach, so one record stands for them all:
@@ -55,38 +46,36 @@ export function held(voice, subject, now, slot) {
     }
     const delay = voice.spec.stagger ? voice.spec.stagger(subject) : 0;
     const since = this.sinceOf(voice, delay);
-    held = {
-        reaches: true,
-        delay,
-        since,
-        shown: this.shownOf(voice, since),
-        weight: 0,
-        rested: false,
-        bands: null,
-        state: voice.patch.state ? voice.patch.state(subject) : undefined,
-        stepped: this.backward && since < now ? since : now,
-        ticks: 0,
-        probed: Number.NaN,
-        delta: null,
-        phase: 0,
-        seeks: 0,
-        kept: null,
-        voice,
-        next: null,
-        version: Number.NaN,
-        loci: null,
-        slot: -1,
-    };
+    const shown = this.shownOf(voice, since);
+    held = record(voice, true, voice.patch.state ? voice.patch.state(subject) : undefined);
+    held.delay = delay;
+    held.since = since;
+    held.shown = shown;
+    held.stepped = since < now ? since : now;
+    held.rebuilt = voice.rebuilds;
     if (this.projecting) {
         held.from = held.stepped;
         held.unknown = this.backward && voice.spec.from === 'current';
     }
     voice.subjects.set(subject, held);
-    if (voice.state === 'pending') {
+    if (!(since <= now)) {
         voice.early ??= [];
-        voice.early.push(held);
+        const early = voice.early;
+        // Prunes at each doubling, so records whose origin has passed are not kept to the voice's end.
+        if (early.length >= 64 && (early.length & (early.length - 1)) === 0) {
+            let kept = 0;
+            for (const h of early)
+                if (!(h.since <= now))
+                    early[kept++] = h;
+            early.length = kept;
+        }
+        early.push(held);
     }
-    voice.seen++;
+    // A subject a voice saw while it shared one record was counted then.
+    if (sighted(voice, slot))
+        inherit(voice, held, slot);
+    else
+        voice.seen++;
     if (delay > voice.latest) {
         voice.latest = delay;
         // A later end can take a frozen voice live again.
@@ -96,26 +85,35 @@ export function held(voice, subject, now, slot) {
     return held;
 }
 /**
- * When the voice clock reads `delay`, from where it is anchored now; during a ramp this assumes
- * the rate it is ramping to.
+ * The mix time the voice clock first read `delay`, or will by its controls now. A stateful voice
+ * counts from its last seek that rebuilt state, as its records do.
  */
 export function sinceOf(voice, delay) {
-    const t = voice.rate > 0
-        ? voice.anchorNow + (delay - voice.anchorElapsed) / voice.rate
-        : voice.start + delay;
-    return voice.owner === null ? t : mixTime(voice.owner, t);
+    const p = voice.patch;
+    return originOf(voice, delay, p.state !== undefined || p.step !== undefined || voice.keeping);
 }
 export function shownOf(voice, since) {
     return voice.freezesBefore && voice.opened < since ? voice.opened : since;
 }
-/** A voice has gone live: the records it made while pending count from where it started. */
-export function started(mix, voice) {
+/**
+ * A voice's start or clock moved, or it went live at `now`: the records whose `since` was still
+ * ahead count from where its clock now puts them.
+ */
+export function reorigin(mix, voice, now) {
     const early = voice.early;
     if (early === null)
         return;
-    voice.early = null;
+    let kept = 0;
     for (const held of early) {
         held.since = mix.sinceOf(voice, held.delay);
         held.shown = mix.shownOf(voice, held.since);
+        if (held.ticks === 0 && held.stepped > held.since)
+            held.stepped = held.since;
+        if (!(held.since <= now))
+            early[kept++] = held;
     }
+    early.length = kept;
+    if (kept === 0)
+        voice.early = null;
+    mix.lanes?.reshown(voice.id);
 }

package/dist/history.d.ts

@@ -1,13 +1,20 @@
 import type { Mixer } from './mixer.js';
+import { type Cut } from './transport.js';
 import { type Subject, type Voice } from './voice.js';
-/**
- * The last entry taken before `t`, or at it where `inclusive` says so, as it does for a change a
- * sync made. A host's change between frames is taken strictly: it shows from the next frame on, as
- * it did live.
- */
+/** The last entry taken before `t`, or at it where `inclusive` says so. */
 export declare function last<T extends {
     at: number;
 }>(list: readonly T[], t: number, inclusive: boolean | ((e: T) => boolean)): T | undefined;
+/**
+ * The last entry of a list kept in the order it was made that falls inside `cut`, an entry made
+ * before its frame was read counting as `early`.
+ */
+export declare function lastWithin<T extends {
+    seq: number;
+    sync?: boolean;
+}>(list: readonly T[], cut: Cut): T | undefined;
+/** Deep equality over plain data, for telling whether a host field changed. */
+export declare function same(a: unknown, b: unknown): boolean;
 /** A voice's elapsed at an earlier mix time, by the controls it had then. */
 export declare function elapsedThen<I, O>(mix: Mixer<I, O>, voice: Voice<I, O>, t: number): number;
 /** Records a change to a voice's controls under `history`, and lets go of what it no longer reaches. */
@@ -25,11 +32,8 @@ export declare function remember<I, O>(mix: Mixer<I, O>, voice: Voice<I, O>, sub
  * for a seek or a read back to before then; without history, keeps nothing.
  */
 export declare function leave<I, O>(mix: Mixer<I, O>, voice: Voice<I, O>, subject: I, held: Subject<unknown> | undefined): void;
-/** The record a subject had at mix time `t` and left a voice with after it, if it left after `t`. */
-export declare function leftAt<I>(left: readonly {
-    subject: I;
-    at: number;
-    held: Subject<unknown>;
-}[] | null, subject: I, t: number): Subject<unknown> | undefined;
-/** The mix time a motion patch keeps a released subject from, and how far back, under history. */
-export declare function releasing<I, O>(mix: Mixer<I, O>): [at?: number, reach?: number];
+/**
+ * The mix time a motion patch keeps a released subject from, how far back, and the frame, under
+ * history.
+ */
+export declare function releasing<I, O>(mix: Mixer<I, O>): [at?: number, reach?: number, seq?: number];