@msb235/blits 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -4,6 +4,101 @@ This package follows [semver](https://semver.org). Below 1.0.0, a breaking chang
 version and everything else the patch. Each release lists its changes as **Breaking**, **Added** and
 **Fixed**, and the release workflow refuses a tag with no section here.
 
+## 0.9.0
+
+### Breaking
+
+- A stock `last()` channel in a locus takes its heaviest member's value, and the later cued of
+  two as heavy. It stepped through its members in cue order, so three voices at weights 0.3,
+  0.3, and 0.4 showed the second. Two members read as before.
+- A placement whose `end` comes before its start is an instant: the voice starts and ends at its
+  start, shows nothing, and warns once outside production. Its `end` mark was reported ahead of
+  its `start`, so a voice anchored after it started before it did, and with a `fade.out` it
+  showed a whole fade from its start. An `end` that leaves less room than `fade.out` now
+  shortens the fade to finish when asked, where the fade ran its whole length past it, and an
+  `out` before the start is reported at the start, where its fade always began.
+- A `to` or `push` that brings back a subject faded out of its voice is made at the frame of
+  the call, as one for a subject never faded is. It was made at the subject's next read, so how
+  far the motion had got depended on when the host next probed the subject.
+- A handle `seek` on a pending voice holds: the voice starts on time, already at the sought
+  position, and one freezing before shows that frame while it waits. The seek was taken from
+  the moment of the call, and lost outright when an anchor or the mix's rate moved the start.
+- A rate of 0, a negative rate, or a ramp set on a pending voice applies from its start, as a
+  rate above 0 always did. At rate 0 the voice starts on time and holds its first frame, where
+  it stopped its clock short of its start for good and never showed.
+
+- A voice playing backward ends where it starts. When its clock runs back to 0, `played`
+  resolves and it leaves over `fade.out`, showing its first frame through the fade, or holds
+  that frame where it freezes before; its `coast`, `out`, and `end` marks are there. A voice at
+  a rate below 0 showed nothing once past its start and never left the mix. A stateful patch
+  steps once more to the moment its subject reached its start.
+- A voice cued at a rate below 0 with no `seek` starts at its end, where it started at 0 and
+  was over at once.
+- A fade in counts from no earlier than its voice's start. A subject whose delay had already run
+  out when the voice started (a negative `stagger`, or a seek made in the frame of the cue)
+  came in with its fade partway or done.
+
+### Added
+
+- `seek` on a cue: where in itself the voice starts, in voice ms.
+- A voice with no end cued backward, a loop for good or a patch with no duration, plays from 0
+  into the pass before, with `setting.pass` and `setting.elapsed` below 0. It runs on the
+  general path.
+- `handle.ramp` through 0 eases a voice into reverse, or out of it.
+- `@msb235/blits-tone`, a package in `packages/tone` that drives Tone.js from a mix on the audio
+  clock. Its own changelog has what it does.
+
+### Fixed
+
+- `project(mix.now)` reads what `probe` does. It landed what the next sync would, so after a
+  handle `seek` past a voice's end it showed the voice gone while the mix still showed its last
+  frame, and after a fade it placed a voice anchored on the faded one a frame early.
+- A read back of a voice that was pending counts each subject's origin from the controls the
+  voice had then, not from where a later seek, rate, or anchor has since put it.
+
+- A seek back inside `history.ms` plays the host's calls again when the mix's rate is above 1.
+  The tape was let go of by mix time while its calls are stamped in host time, so at rate 2 a call
+  made 250 ms of host time before a seek back was already gone and never played again.
+- A voice taken out with a time already older than history reaches, such as `fade({ at })` given
+  a moment long past, comes back for a seek or a read back to before that call. It was forgotten
+  at the next sync, so `seek` and `project` to the frame before the call found no voice.
+- A `HistoryStore` is told of every seek back through `cut`, as its doc says. It was told only
+  when the seek read records from the store, so a mark announced with a past `at`, paged at once,
+  stayed in the store after a seek back to before it was announced.
+- A `color(last())` channel on a lane switches off when its voice's weight falls to 0, as it does
+  off lanes. A lane left it on, so a weight coming back inside the band (0.4 to 0.6 by default)
+  showed the color where a mix with `lanes: false` showed none.
+
+- A span's children play from where the one before each ended, not from the frame that noticed
+  it. Each child leaving fitted the rest again from the sync's time, so the next started up to a
+  frame late and the rest sped up to make room: 200 children of 10 ms in a 2000 ms span, fitted
+  with none skipped at cue, had 199 skipped once synced every 16 ms. A read ahead never fitted
+  again, so `project` showed a child retimed by `faster` up to a frame ahead of the mix.
+
+- A voice whose owner runs backward leaves over its `fade.out` from where it reached its start,
+  as one turned back by its own handle does. An owner run back to its start left at once and
+  took every voice it held with it, so a child with a 100 ms `fade.out` vanished in one frame
+  and listed no `coast`, `out`, or `end` mark. An owner at its start now stays for what it
+  holds and leaves with its last child.
+
+- `setting.dt` is the gap since the subject was last sampled for a patch with no `step`, and for
+  a weight signal, as its doc says. It was the time since the subject's origin, growing every
+  frame: a mix synced at 16, 48, and 64 handed such a patch 16, 48, and 64, and now hands it 16,
+  32, and 16.
+
+## 0.8.1
+
+### Fixed
+
+- A frame under `history` costs what it did in 0.7.1 again. 0.8.0 added two costs to every frame:
+  a sync shifted the whole list of frames history can reach to let go of the oldest, 7,200 of
+  them at 60 fps under the default 120 s; and an object a voice gave a channel with no `rest` to
+  fold into, such as `last<Row>()`, was copied for every subject on every frame. The frames now
+  leave from the front without a shift, and such a channel's pose holds the patch's own object, as
+  in 0.7.1; an array is still copied. astv's motion bench on one machine, mean µs a frame over
+  two runs, 0.7.1, 0.8.0, then this: one window landing 6 text changes of 5 rows, 19.6, 28.8,
+  19.5; its busy stage, 354.6, 402.2, 340.7; 10 flights a second, 6.4, 8.0, 6.6.
+
 ## 0.8.0
 
 ### Breaking

package/README.md

@@ -116,9 +116,14 @@ state shared between subjects, a `step` that lands differently from the same sta
 [three.quarks](https://github.com/Alchemist0823/three.quarks) particles. It is published separately
 so the engine keeps no dependencies; its README says how it works.
 
+`packages/tone` is `@msb235/blits-tone`, a driver that schedules a mix on the audio clock through
+[Tone.js](https://tonejs.github.io): channels as parameter curves read ahead, and hits and marks at
+their sample. It is published separately for the same reason, and its README says what it does not
+do yet.
+
 ## Status
 
-v0.8.0, with five consumers. magicsmoke runs every fault on it, wod its wheel, tricks and
+v0.9.0, with five consumers. magicsmoke runs every fault on it, wod its wheel, tricks and
 transitions, weasel its animator's tweens, sherpa its seams, and
 [klieg](https://github.com/orochi235/klieg) composes all three of its systems — letter motion,
 part effects, and the environment a sign is lit by — on a mix each.
@@ -135,7 +140,12 @@ Zero runtime dependencies, ESM only, types included.
 
 ```
 npm install
-npm run check   # lint, typecheck, test
+npm run check          # lint, typecheck, test
+npm run test:general   # the tests again with lanes off
 ```
 
+A lane is a channel the mix computes for every subject at once, and the general path is the same
+fold made subject by subject. `test:general` turns lanes off in every mix that does not set `lanes`
+itself, so the whole suite runs on the general path.
+
 MIT.

package/dist/clock.d.ts

@@ -69,6 +69,16 @@ export interface Clock {
 export declare function elapsedWith(c: Clock, now: number): number;
 /** The time a clock reads `elapsed`, inverting `elapsedWith`; Infinity where it never will. */
 export declare function timeWith(c: Clock, elapsed: number): number;
+/**
+ * The time a clock running back reads `elapsed`: `timeWith` for the clock that reads the negative
+ * of this one, which runs forward where this runs back.
+ */
+export declare function backWith(c: Clock, elapsed: number): number;
+/**
+ * The phase of a time before 0, for a loop with no first pass: where the pass before 0, and each
+ * one before that, would read it.
+ */
+export declare function phaseBefore(elapsed: number, duration: number): number;
 /** A clock's rate at `now`. */
 export declare function rateWith(c: Clock, now: number): number;
 /** Moves a clock's anchor to `now`, carrying what is left of a ramp. */

package/dist/clock.js

@@ -125,6 +125,29 @@ export function timeWith(c, elapsed) {
         return Number.POSITIVE_INFINITY;
     return c.anchorNow + r.over + (elapsed - atEnd) / r.to;
 }
+/**
+ * The time a clock running back reads `elapsed`: `timeWith` for the clock that reads the negative
+ * of this one, which runs forward where this runs back.
+ */
+export function backWith(c, elapsed) {
+    const r = c.ramp;
+    return timeWith({
+        anchorNow: c.anchorNow,
+        anchorElapsed: -c.anchorElapsed,
+        rate: -c.rate,
+        ramp: r === null ? null : { from: -r.from, to: -r.to, over: r.over },
+    }, -elapsed);
+}
+/**
+ * The phase of a time before 0, for a loop with no first pass: where the pass before 0, and each
+ * one before that, would read it.
+ */
+export function phaseBefore(elapsed, duration) {
+    if (!(duration > 0))
+        return 0;
+    const into = elapsed % duration;
+    return (into < 0 ? into + duration : into) / duration;
+}
 /** A clock's rate at `now`. */
 export function rateWith(c, now) {
     const r = c.ramp;

package/dist/clone.d.ts

@@ -6,5 +6,10 @@
 export declare function clone<T>(v: T): T;
 /** A copy a fold may write into: arrays, typed arrays and plain objects copied, the rest as is. */
 export declare function copy(v: unknown): unknown;
+/**
+ * A value that starts a channel no fold writes into: only `merged` touches it after, and that
+ * writes into arrays alone, so an object is the patch's own, not a copy made each frame.
+ */
+export declare function first(v: unknown): unknown;
 /** Whether `copy` can copy `v` faithfully, when it is an object. */
 export declare function copyable(v: object): boolean;

package/dist/clone.js

@@ -62,6 +62,13 @@ export function copy(v) {
         return v.slice();
     return plainObject(v) ? clone(v) : v;
 }
+/**
+ * A value that starts a channel no fold writes into: only `merged` touches it after, and that
+ * writes into arrays alone, so an object is the patch's own, not a copy made each frame.
+ */
+export function first(v) {
+    return Array.isArray(v) ? [...v] : v;
+}
 /** Whether `copy` can copy `v` faithfully, when it is an object. */
 export function copyable(v) {
     return Array.isArray(v) || ArrayBuffer.isView(v) || plainObject(v);

package/dist/cue.js

@@ -4,7 +4,7 @@ import { copyable } from './clone.js';
 import { schedule } from './due.js';
 import { shares } from './everyone.js';
 import { finiteRate, plainWeight, VoiceHandle } from './handle.js';
-import { reorigin } from './held.js';
+import { begin } from './held.js';
 import { handle } from './hosts.js';
 import { motionOf } from './motion.js';
 import { adopt, ownerPatch, ownerReading } from './owner.js';
@@ -76,6 +76,8 @@ export function playable(mix, spec) {
         throw new RangeError(`blits: loop takes true, false or a whole number of passes, not ${loop}`);
     if (spec.rate !== undefined)
         finiteRate(spec.rate);
+    if (spec.seek !== undefined && !Number.isFinite(spec.seek))
+        throw new RangeError(`blits: a voice's seek is a finite number of ms, not ${spec.seek}`);
     if (typeof spec.weight === 'number')
         plainWeight(spec.weight);
     fitsKit(patch, mix.kit);
@@ -150,13 +152,8 @@ function enter(mix, voice) {
         mix.wantsPose = true;
     if (anchor) {
         place(mix);
-        if (!Number.isNaN(mix.now) &&
-            voice.state === 'pending' &&
-            localNow(mix, voice) >= voice.start) {
-            voice.state = 'live';
-            reorigin(mix, voice, mix.now);
-            changed(mix, voice);
-        }
+        if (!Number.isNaN(mix.now) && voice.state === 'pending' && localNow(mix, voice) >= voice.start)
+            begin(mix, voice, mix.now);
     }
     if (owner?.fitting)
         refit(mix, owner);

package/dist/due.js

@@ -20,6 +20,9 @@ function dueOf(mix, voice) {
         due = Math.min(due, back.at + (1 - back.from) * back.over);
     if (voice.state === 'pending')
         return Math.min(due, Number.isNaN(voice.start) ? due : voice.start);
+    // A ramp through 0 turns the clock around, which is looked for each frame until it has.
+    if (voice.turns)
+        return Number.NEGATIVE_INFINITY;
     if (voice.state === 'fading') {
         const out = voice.out;
         if (out === null || out.rest)
@@ -27,20 +30,24 @@ function dueOf(mix, voice) {
         return Math.min(due, out.at + out.over);
     }
     due = Math.min(due, voice.outAt);
-    if (Number.isFinite(voice.span)) {
-        const end = voice.span + voice.latest;
-        // A frozen voice goes live again once its clock is back before its end: by a seek, by a
-        // subject staggered later than any before, or by running backwards, which is checked each
-        // frame while it can.
-        if (voice.state === 'frozen') {
-            if (voice.rate <= 0 || voice.ramp !== null)
-                return Number.NEGATIVE_INFINITY;
-            if (!Number.isNaN(mix.now) && voice.elapsedAt(mix.now) < end)
-                return Number.NEGATIVE_INFINITY;
-        }
-        if (voice.state === 'live')
-            due = Math.min(due, voice.timeAt(end));
+    if (voice.state === 'frozen') {
+        const at = Number.isNaN(mix.now) ? Number.NaN : voice.elapsedAt(mix.now);
+        // Frozen at its start, having run back to it, it stays while its rate is never above 0,
+        // until a handle or a subject staggered ahead of every other moves it.
+        const r = voice.ramp;
+        const never = r === null ? voice.rate <= 0 : r.from <= 0 && r.to <= 0;
+        if (never && !voice.beginless && at <= voice.soonest)
+            return due;
+        // Frozen at its end, it goes live again once its clock is back before it: by a seek, by a
+        // subject staggered later than any before, or by running back, which is checked each frame
+        // while it can.
+        if (voice.rate <= 0 || r !== null)
+            return Number.NEGATIVE_INFINITY;
+        if (at < voice.span + voice.latest)
+            return Number.NEGATIVE_INFINITY;
     }
+    if (voice.state === 'live')
+        due = Math.min(due, voice.endsAt());
     return due;
 }
 /** Files a voice in the due queue at its current due, replacing any entry it had. */

package/dist/everyone.js

@@ -32,6 +32,7 @@ export function shares(mix, voice) {
         voice.holding === null &&
         voice.blend === null &&
         !voice.freezesBefore &&
+        !voice.beginless &&
         voice.slots.every((s) => {
             const channel = mix.channels[s];
             return channel.rest !== undefined && numericOf(channel)?.op !== 'last';
@@ -113,6 +114,8 @@ export function open(voice, rec, slot) {
         return;
     const stamps = voice.stamps;
     const o = slot * 2 /* Stamp.SIZE */;
+    // A subject never read counts its `dt` from the voice's origin, not another subject's last call.
+    rec.stepped = rec.since;
     if (stamps === null || o >= stamps.length) {
         rec.probed = Number.NaN;
         rec.seeks = 0;

package/dist/fade.d.ts

@@ -21,6 +21,7 @@ export declare function beginFade<I, O>(mix: Mixer<I, O>, voice: Voice<I, O>, op
     over?: number;
     at?: 'rest';
     deadline?: number;
+    back?: boolean;
 }, at?: number): void;
 /**
  * Turns a fading voice around: it climbs back from where its fade out had got to, up the same

package/dist/fade.js

@@ -104,7 +104,8 @@ export function beginFade(mix, voice, opts, at) {
         return;
     const over = mix.reduced ? 0 : (opts.over ?? voice.fade.out ?? 0);
     // A voice is linked into its subjects' chains once it plays, and a fading one plays.
-    if (voice.state === 'pending')
+    const waiting = voice.state === 'pending';
+    if (waiting)
         changed(mix, voice);
     // A fade at rest marks each subject's record as it comes to rest, at its next read: one already
     // read this frame is read again, as after `touch`.
@@ -120,8 +121,11 @@ export function beginFade(mix, voice, opts, at) {
         rest: opts.at === 'rest',
         deadline: opts.deadline,
     };
+    if (opts.back)
+        voice.out.back = true;
     noted(mix, voice);
-    if (opts.at === 'rest')
+    // A fade at rest, from a voice's start, or of a voice yet to start takes it off its lane.
+    if (opts.at === 'rest' || opts.back || waiting)
         mix.lanes?.invalidate();
     else
         mix.lanes?.refill();
@@ -190,7 +194,9 @@ export function retire(mix, voice, at) {
     // The record its setting last wrote to, which a retired voice no longer calls for.
     voice.keepOn = null;
     mix.retired.push(voice);
-    voice.doneAt = at ?? (Number.isNaN(mix.now) ? Number.NEGATIVE_INFINITY : mix.now);
+    const now = Number.isNaN(mix.now) ? Number.NEGATIVE_INFINITY : mix.now;
+    voice.doneAt = at ?? now;
+    voice.decidedAt = now;
     voice.doneSeq = mix.transport.seq;
     // The frames up to this one showed it, though its fade ended before: it leaves the list now.
     mix.transport.settle();
@@ -209,6 +215,6 @@ export function retire(mix, voice, at) {
         // A child the fit skipped had no time in it, so the rest of the fit stands: fitting again
         // between siblings skipped together would play the ones still to leave.
         else if (span.fitting !== null && span.state !== 'done' && !voice.skipped)
-            refit(mix, span);
+            refit(mix, span, voice.doneAt);
     }
 }

package/dist/fill.js

@@ -3,6 +3,7 @@ import { passAt, phaseAt, same, silent, weighed } from './clock.js';
 import { flush } from './columns.js';
 import { crowdsUpTo, freshen } from './crowd.js';
 import { open as openRecord, shut as shutRecord } from './everyone.js';
+import { unband } from './fold.js';
 import { foldLocus, gatherLocus } from './gather.js';
 import { runKeys } from './keyfill.js';
 import { frozenAt } from './lane.js';
@@ -301,6 +302,7 @@ export function one(lane, p, slot) {
     const elapsed = frozenAt(voice, elapsedNow - delay);
     if (!(elapsed >= 0)) {
         data[o + 2 /* Row.WEIGHT */] = 0;
+        unband(lane.records[p]);
         return false;
     }
     if (!lane.placed || !same(elapsed, lane.placedAt)) {
@@ -322,6 +324,7 @@ export function one(lane, p, slot) {
         arg[5 /* Arg.FADE */] = lane.fade;
         if (!this.signalled(voice, slot, lane.records[p])) {
             data[o + 2 /* Row.WEIGHT */] = 0;
+            unband(lane.records[p]);
             return false;
         }
         w = arg[0 /* Arg.WEIGHT */];
@@ -329,6 +332,8 @@ export function one(lane, p, slot) {
     else
         w = weighed(voice.weight, lane.fade, this.parting(voice, slot));
     data[o + 2 /* Row.WEIGHT */] = w;
+    if (!(w > 0))
+        unband(lane.records[p]);
     this.folding = lane;
     this.rec = lane.records[p] ?? null;
     if (voice.built !== null) {

package/dist/fold.js

@@ -1,5 +1,5 @@
-import { frozenTime, passAt, phaseAt, silent } from './clock.js';
-import { copy as copyValue } from './clone.js';
+import { passAt, phaseAt, phaseBefore, silent } from './clock.js';
+import { copy as copyValue, first } from './clone.js';
 import { open as openRecord, shut as shutRecord, weighAt } from './everyone.js';
 import { recordHost, remember } from './history.js';
 import { stateful } from './hosts.js';
@@ -69,16 +69,15 @@ export function contribution(voice, subject, now, held) {
         return null;
     if (held.rebuilt !== voice.rebuilds)
         rebuild(this, voice, subject, now, held);
-    const raw = voice.elapsedAt(now) - held.delay;
-    // Not `raw < 0`: see `frozenTime` for the clock that reads NaN before its start.
-    const early = !(raw >= 0);
-    if (early && !voice.freezesBefore)
+    const raw = voice.rawAt(now, held.delay);
+    const early = voice.before(raw, now);
+    if (early && !voice.holdsFirst)
         return null;
-    const elapsed = frozenTime(raw, voice.freezesBefore, voice.freezesAfter, voice.span);
+    const elapsed = voice.shownAt(raw);
     // A frozen subject's clock stands still at the edge it freezes at: -1 before, 1 after, 0 playing.
     const still = early ? -1 : voice.freezesAfter && raw > voice.span ? 1 : 0;
     const duration = voice.duration;
-    const phase = phaseAt(elapsed, duration, voice.passes);
+    const phase = elapsed < 0 ? phaseBefore(elapsed, duration) : phaseAt(elapsed, duration, voice.passes);
     const pass = passAt(elapsed, duration, voice.passes);
     this.prime(voice, held, now, elapsed, pass);
     const setting = voice.setting;
@@ -102,20 +101,27 @@ export function contribution(voice, subject, now, held) {
         recordHost(this, now);
     reading.horizon = this.horizonFor(voice, held.delay, now);
     const tick = this.opts.stepMs;
-    if (voice.patch.step && held.probed !== now && still >= 0) {
-        // Frozen after, it steps once more to where its last pass ended, and no further.
-        const to = still === 1 ? voice.timeAt(held.delay + voice.span) : now;
-        if (held.stepped < held.since) {
-            held.stepped = held.since;
-            setting.dt = this.capped(now - held.since);
-        }
-        if (tick !== undefined && tick > 0 && !this.reducedNow)
-            this.tick(voice, subject, held, tick, to);
-        else if (still === 0 ? now !== held.stepped : to > held.stepped) {
-            if (still === 1)
-                setting.dt = this.capped(to - held.stepped);
-            voice.patch.step(held.state, setting.dt, subject, setting);
-            held.stepped = to;
+    if (voice.patch.step && held.probed !== now) {
+        // Frozen after, it steps once more to where its last pass ended, and no further; run back
+        // past its start, to where it reached it. Before a start it has yet to reach, it does not step.
+        const to = still === 0
+            ? now
+            : still === 1
+                ? voice.timeAt(held.delay + voice.span)
+                : voice.ranBackTo(held.delay, now);
+        if (!Number.isNaN(to)) {
+            if (held.stepped < held.since) {
+                held.stepped = held.since;
+                setting.dt = this.capped(now - held.since);
+            }
+            if (tick !== undefined && tick > 0 && !this.reducedNow)
+                this.tick(voice, subject, held, tick, to);
+            else if (still === 0 ? now !== held.stepped : to > held.stepped) {
+                if (still !== 0)
+                    setting.dt = this.capped(to - held.stepped);
+                voice.patch.step(held.state, setting.dt, subject, setting);
+                held.stepped = to;
+            }
         }
     }
     let delta = null;
@@ -298,7 +304,7 @@ export function apply(pose, voice, held, delta, weight) {
         const on = this.passes(band === 0 ? undefined : band === 1, weight);
         bands[i] = on ? 1 : 2;
         if (on)
-            pose[key] = pose[key] === undefined ? copy(value) : merged(channel, pose[key], value);
+            pose[key] = pose[key] === undefined ? first(value) : merged(channel, pose[key], value);
     }
 }
 /** Clamps every bounded channel of a folded pose into its range, in place. */
@@ -617,7 +623,7 @@ export function foldLoci(subject, pose, head, laned, dry, except, owed) {
                 const passes = this.passes(band === 0 ? undefined : band === 1, w);
                 on[slot] = passes ? 1 : 2;
                 if (passes)
-                    pose[key] = pose[key] === undefined ? copy(value) : merged(channel, pose[key], value);
+                    pose[key] = pose[key] === undefined ? first(value) : merged(channel, pose[key], value);
             }
         }
         return pose;
@@ -648,7 +654,7 @@ export function read(voice, subject, now, dry, held) {
         if (held.reaches && held.probed === now && held.delta && held.seeks === voice.seeks) {
             const setting = voice.setting;
             // The setting the probe that read the delta had, but for `dt`: a dry read advances nothing.
-            const elapsed = frozenTime(voice.elapsedAt(now) - held.delay, voice.freezesBefore, voice.freezesAfter, voice.span);
+            const elapsed = voice.shownAt(voice.rawAt(now, held.delay));
             setting.timestamp = now;
             setting.dt = 0;
             setting.elapsed = elapsed;

package/dist/frames.d.ts

@@ -0,0 +1,21 @@
+import type { Frame } from './transport.js';
+/**
+ * The frames a transport's history can still reach, oldest first. A frame leaves the front on
+ * most syncs, so the front is an index that moves and the array closes up only now and then.
+ */
+export declare class Frames {
+    private list;
+    private head;
+    get length(): number;
+    push(frame: Frame): void;
+    /** Lets go of every frame before the last one at or before `reach`, giving each to `each`. */
+    shed(reach: number, each?: (frame: Frame) => void): void;
+    /**
+     * The frame a seek or read to mix time `t` lands on: the last one standing at or before `t`,
+     * since rate 0 can hold the clock at `t` for many.
+     */
+    at(t: number): Frame | undefined;
+    /** Every frame held, oldest first. */
+    all(): Frame[];
+    set(frames: Frame[]): void;
+}

package/dist/frames.js

@@ -0,0 +1,59 @@
+/** Past this many frames let go of at the front, the list is closed up, once they are half of it. */
+const SLACK = 512;
+/**
+ * The frames a transport's history can still reach, oldest first. A frame leaves the front on
+ * most syncs, so the front is an index that moves and the array closes up only now and then.
+ */
+export class Frames {
+    list = [];
+    head = 0;
+    get length() {
+        return this.list.length - this.head;
+    }
+    push(frame) {
+        this.list.push(frame);
+    }
+    /** Lets go of every frame before the last one at or before `reach`, giving each to `each`. */
+    shed(reach, each) {
+        const list = this.list;
+        let head = this.head;
+        while (head + 1 < list.length && list[head + 1].at <= reach) {
+            each?.(list[head]);
+            head++;
+        }
+        if (head >= SLACK && head * 2 >= list.length) {
+            list.splice(0, head);
+            head = 0;
+        }
+        this.head = head;
+    }
+    /**
+     * The frame a seek or read to mix time `t` lands on: the last one standing at or before `t`,
+     * since rate 0 can hold the clock at `t` for many.
+     */
+    at(t) {
+        const list = this.list;
+        let lo = this.head;
+        let hi = list.length - 1;
+        let found;
+        while (lo <= hi) {
+            const mid = (lo + hi) >> 1;
+            const f = list[mid];
+            if (f.at <= t) {
+                found = f;
+                lo = mid + 1;
+            }
+            else
+                hi = mid - 1;
+        }
+        return found;
+    }
+    /** Every frame held, oldest first. */
+    all() {
+        return this.list.slice(this.head);
+    }
+    set(frames) {
+        this.list = frames;
+        this.head = 0;
+    }
+}

package/dist/gone.d.ts

@@ -13,7 +13,7 @@ export declare class GoneIndex<I, O> {
     count: number;
     general: Voice<I, O>[];
     named: Store<I, Voice<I, O>[]>;
-    /** The latest `doneAt` in `of`, and how far any voice finished before one listed ahead of it. */
+    /** The latest `reachedTo` in `of`, and how far any voice's falls before one listed ahead of it. */
     latest: number;
     slack: number;
 }
@@ -25,8 +25,8 @@ export declare function goneIndex<I, O>(mix: Mixer<I, O>): GoneIndex<I, O>;
  */
 export declare function keepGone<I, O>(mix: Mixer<I, O>, keep: (v: Voice<I, O>) => boolean): void;
 /**
- * Lets go of the gone voices that finished before `reach`. Voices go in about the order they
- * finish, so only the front can hold one: past the point where a voice finished `slack` after
- * `reach`, none behind it finished before `reach`.
+ * Lets go of the gone voices no seek or read back to `reach` finds playing: those that finished
+ * before it, in a frame before it. Voices go in about that order, so only the front can hold one:
+ * past the point where a voice is reached `slack` after `reach`, none behind it falls before.
  */
 export declare function expireGone<I, O>(mix: Mixer<I, O>, reach: number): void;