@msb235/blits 0.10.0 → 0.12.0

package/dist/seek.js

@@ -1,7 +1,9 @@
+import { heldAt } from './chain.js';
 import { schedule } from './due.js';
-import { copyHeld, last, lastWithin } from './history.js';
+import { fadesAt } from './fade.js';
+import { origin } from './held.js';
+import { apart, copyHeld, copyHeldInto, lastIndex, lastWithin, unread } from './history.js';
 import { laneHost } from './hosts.js';
-import { Lanes } from './lanes.js';
 import { Leavings } from './leavings.js';
 import { move, nextFrame } from './move.js';
 import { ownerReading } from './owner.js';
@@ -11,34 +13,112 @@ import { Restored } from './restored.js';
 import { recount } from './roster.js';
 import { refitAll } from './spans.js';
 import { Store } from './store.js';
-import { hostAt, replay } from './tape.js';
-import { cover, cut } from './unpage.js';
+import { hostAhead, hostAt, replay } from './tape.js';
+import { cover, coverFrame, cut } from './unpage.js';
 /**
  * A voice's record of one subject as it stood at mix time `t`, from the latest copy kept by then;
  * undefined for a stateful record first made after `t`, which is met afresh. A stateless record
- * holds nothing that moves with time, so it is copied whenever it was made.
+ * holds nothing that moves with time, so it is copied whenever it was made. The weight its last
+ * probe by `t` read is not kept, and a lane holds it apart from the record, so the record reads 0
+ * until the next probe.
  */
-function restore(voice, live, t) {
+function restore(mix, voice, live, at, every, mine) {
+    // Read here, not passed: a double passed to a call is boxed, once per record put back.
+    const t = at.t;
     const inputs = live.inputs?.filter((e) => e.at <= t);
     const snaps = live.snaps;
     if (snaps === undefined) {
-        // Nothing a step or `setting.keep` holds: what it keeps does not move with time.
-        const h = copyHeld(voice, live);
+        // Nothing a step or `setting.keep` holds: what it keeps does not move with time. One record
+        // stands for every subject a voice does not reach, so that one is copied.
+        const h = mine && live.reaches ? unread(live) : copyHeld(voice, live);
         if (h.stepped > t)
             h.stepped = t;
         // Whether it had rested by `t` is not kept; the next probe finds it again.
         h.rested = false;
+        h.weight = 0;
         h.inputs = inputs;
+        if (!(h.since <= t))
+            origin(mix, voice, h);
         return h;
     }
-    const snap = last(snaps, t, true);
-    if (snap === undefined)
+    // A seek back to just before now finds its copy among the newest, looked at before searching.
+    const n = snaps.length;
+    const i = n > 0 && snaps[n - 1].at <= t
+        ? n - 1
+        : n > 1 && snaps[n - 2].at <= t
+            ? n - 2
+            : lastIndex(snaps, t, true);
+    if (i < 0)
         return undefined;
-    const h = copyHeld(voice, snap.held);
-    h.snaps = snaps.slice(0, snaps.indexOf(snap) + 1);
+    const snap = snaps[i];
+    // What the record replaced held, which a record put back over it would lose.
+    const { ticks, since, rebuilt, state, slot, restored } = live;
+    let h;
+    if (mine && live.reaches) {
+        // Its chain may still read its number from it, and its store has just stamped it.
+        h = copyHeldInto(voice, snap.held, live, true);
+        h.slot = slot;
+        h.restored = restored;
+    }
+    else
+        h = copyHeld(voice, snap.held, true);
+    h.weight = 0;
+    if (snap.at < t)
+        h.copied = true;
+    const kept = i + 1;
+    // The record replaced is let go, so its list is cut where it stands.
+    if (mine)
+        trim(voice, snaps, kept);
+    else
+        for (let i = 0; i < kept; i++)
+            snaps[i].shared = true;
+    h.snaps = mine ? snaps : snaps.slice(0, kept);
     h.inputs = inputs;
+    // A start still ahead when the copy was kept may have moved before `t`, with no copy between.
+    if (!(h.since <= snap.at))
+        origin(mix, voice, h);
+    // The record a seek replaces, stepped on from this copy with nothing since rebuilding or moving
+    // its start, holds the copy's state at its own `ticks`, which a probe there need not step to.
+    const was = mine && ticks > h.ticks && since === h.since && rebuilt === h.rebuilt;
+    if (voice.patch.step !== undefined && (snap.ahead !== undefined || t - snap.at >= every || was)) {
+        let ahead = snap.ahead;
+        // Steps counted from a start that has moved since are not this record's.
+        if (ahead === undefined || ahead.since !== h.since) {
+            ahead = {
+                put: h,
+                sought: t,
+                since: h.since,
+                at: snap.at,
+                ticks: h.ticks,
+                state: undefined,
+                leftTicks: 0,
+                left: undefined,
+            };
+            snap.ahead = ahead;
+        }
+        else {
+            ahead.put = h;
+            ahead.sought = t;
+        }
+        if (was) {
+            // Nothing else holds the record replaced, so its state is taken, not copied.
+            ahead.leftTicks = ticks;
+            ahead.left = state;
+        }
+    }
     return h;
 }
+/** Cuts a record's list of copies to its first `kept`, keeping those no other list holds as spares. */
+function trim(voice, snaps, kept) {
+    while (snaps.length > kept) {
+        const snap = snaps.pop();
+        if (snap.shared)
+            continue;
+        snap.ahead = undefined;
+        voice.spares ??= [];
+        voice.spares.push(snap);
+    }
+}
 /** Takes a voice cued after the moment sought out of the mix, until the tape cues it again. */
 function park(mix, voice) {
     const owner = voice.owner;
@@ -71,9 +151,15 @@ function restoreVoice(mix, voice, t, seq) {
             voice.parts = null;
     }
     if (voice.parted !== null) {
-        for (const [subject, p] of voice.parted)
-            if (p.seq > seq)
-                voice.parted.delete(subject);
+        for (const [subject, p] of voice.parted) {
+            if (p.seq <= seq)
+                continue;
+            voice.parted.delete(subject);
+            if (p.ramp === undefined || p.ramp.seq > seq)
+                continue;
+            voice.parts ??= new Map();
+            voice.parts.set(subject, p.ramp);
+        }
         if (voice.parted.size === 0)
             voice.parted = null;
     }
@@ -86,32 +172,31 @@ function restoreVoice(mix, voice, t, seq) {
     voice.unreached = null;
     voice.unreachedBits = null;
     voice.seeks++;
+    voice.spares = null;
     const left = voice.left?.all() ?? [];
+    if (voice.left !== null)
+        fadesAt(voice, voice.left.after(cut), seq);
     voice.left = Leavings.from(left.filter((e) => e.seq <= seq));
     const future = Leavings.from(left.filter((e) => e.seq > seq));
     let records = voice.subjects;
     if (!(records instanceof Restored)) {
-        records = new Restored(records, (live, least, top) => {
-            const h = restore(voice, live, least);
+        const every = apart(mix.opts.history);
+        const now = (subject, held, at) => heldAt(voice, subject, held, at.t, at.seq);
+        const restored = new Restored(records, now, (live, at, mine) => {
+            const h = restore(mix, voice, live, at, every, mine);
             if (h === undefined)
                 return h;
             if (h.reaches)
                 voice.seen++;
             if (h.rested)
                 voice.restedCount++;
-            if (!(h.since <= least)) {
-                // Kept while its origin was still ahead: where the controls put back place it now.
-                h.since = mix.sinceOf(voice, h.delay);
-                h.shown = mix.shownOf(voice, h.since);
-                if (h.ticks === 0 && h.stepped > h.since)
-                    h.stepped = h.since;
-            }
-            if (!(h.since <= top)) {
+            if (!(h.since <= restored.top)) {
                 voice.early ??= [];
                 voice.early.push(h);
             }
             return h;
         });
+        records = restored;
         voice.subjects = records;
     }
     records.back(t, cut, future);
@@ -127,8 +212,11 @@ function stateAt(voice, t) {
         return 'frozen';
     return 'live';
 }
-/** Moves every mix on the transport to mix time `t`, as it stood at the end of that frame. */
-export function seek(transport, t) {
+/**
+ * Moves every mix on the transport to mix time `to`, as it stood at the end of that frame, or to
+ * the end of the frame numbered `to.frame`.
+ */
+export function seek(transport, to) {
     if (transport.projecting)
         throw new Error('blits: a projection does not seek');
     const history = transport.history;
@@ -139,25 +227,42 @@ export function seek(transport, t) {
         throw new Error('blits: seeking needs history.tape, which keeps the calls a seek plays again');
     if (Number.isNaN(transport.now))
         throw new Error('blits: a mix that has never synced has nothing to seek');
-    if (t === Number.POSITIVE_INFINITY)
-        throw new RangeError('blits: a mix seeks to a finite time');
-    if (!(t >= transport.born))
-        throw new Error(`blits: ${t} is older than this mix's history reaches`);
-    cover(transport, t);
-    if (t >= transport.now) {
+    let t;
+    let frame;
+    if (typeof to === 'number') {
+        t = to;
+        if (t === Number.POSITIVE_INFINITY)
+            throw new RangeError('blits: a mix seeks to a finite time');
+        if (!(t >= transport.born))
+            throw new Error(`blits: ${t} is older than this mix's history reaches`);
+        cover(transport, t);
+        if (t < transport.now) {
+            frame = transport.frames.at(t);
+            if (frame === undefined)
+                throw new Error(`blits: ${t} is older than this mix's history reaches`);
+        }
+    }
+    else {
+        const f = coverFrame(transport, to.frame);
+        t = f.at;
+        // The frame being played is where the mix stands; any other is behind it, whatever its time.
+        if (f.seq !== transport.seq)
+            frame = f;
+    }
+    if (frame === undefined) {
         // Ahead, under the rate the recorded calls up to `t` set, past any frames rate 0 held at `t`.
         const last = replay(transport, (at) => (transport.pace === null ? at : transport.pace.reading(at)) <= t);
-        const u = Number.isNaN(last) ? hostAt(transport, t) : Math.max(last, hostAt(transport, t));
+        const at = hostAhead(transport, t);
+        const u = Number.isNaN(last) ? at : Math.max(last, at);
         if (!Number.isFinite(u))
             throw new RangeError(`blits: the mix's rate never reaches ${t}`);
         transport.u = u;
-        for (const m of transport.members)
-            move(m, t);
+        // A call played at `t` itself moved the mixes there before it, as a sync does.
+        if (Number.isNaN(last) || transport.now !== t)
+            for (const m of transport.members)
+                move(m, t);
     }
     else {
-        const frame = transport.frames.at(t);
-        if (frame === undefined)
-            throw new Error(`blits: ${t} is older than this mix's history reaches`);
         // On the frame itself, its own host time: rate 0 may have held the clock there for several.
         const u = frame.at === t ? frame.u : hostAt(transport, t);
         const seq = frame.seq;
@@ -219,13 +324,17 @@ function back(mix, t, seq, on) {
     mix.retired = [];
     // Owners hold what is back; a voice that went live again counts its place in its owner anew.
     for (const voice of kept)
-        if (voice.holding !== null)
+        if (voice.holding !== null) {
             voice.holding.children = kept.filter((v) => v.owner === voice);
+            voice.holding.back(seq);
+        }
     // Rebuilt from the voices that are back: the lanes, the chains and every count the fold reads.
+    // Subject numbers carry over, and with them the chains that hold them, each linked afresh.
     const oldLanes = mix.lanes;
-    if (oldLanes !== null)
-        mix.lanes = new Lanes(laneHost(mix));
-    mix.chains = new Store();
+    if (oldLanes !== null && mix.lanesOf !== null)
+        mix.lanes = new mix.lanesOf(laneHost(mix), oldLanes);
+    else
+        mix.chains = new Store();
     mix.owners = kept.some((v) => v.holding !== null) ? kept.filter((v) => v.holding !== null) : null;
     recount(mix);
     mix.parters.clear();

package/dist/shared.d.ts

@@ -1,3 +1,8 @@
+/**
+ * The package version, for a fact whose shape follows the code too closely to version by hand:
+ * copies of different releases keep apart. `test/copies.test.ts` holds it to `package.json`.
+ */
+export declare const release = "0.12.0";
 /**
  * A WeakMap every copy of blits loaded in one realm shares, so a fact one copy records about a
  * patch or channel it made is read by another copy's mix. The name carries a version, bumped when

package/dist/shared.js

@@ -1,3 +1,8 @@
+/**
+ * The package version, for a fact whose shape follows the code too closely to version by hand:
+ * copies of different releases keep apart. `test/copies.test.ts` holds it to `package.json`.
+ */
+export const release = '0.12.0';
 /**
  * A WeakMap every copy of blits loaded in one realm shares, so a fact one copy records about a
  * patch or channel it made is read by another copy's mix. The name carries a version, bumped when

package/dist/signals.d.ts

@@ -7,6 +7,16 @@ export declare const heard: (signal: object) => boolean;
  * @category signal
  */
 export declare function peak<I, H = unknown>(...signals: readonly Signal<I, H>[]): Signal<I, H>;
+/** A blend member's share of its signal's read `k`: the members' stops sit evenly along 0..1. */
+export declare function shareOf(k: number, i: number, stops: number): number;
+/**
+ * Member `i` of `n`'s share of `by`, as `mix.blend` weighs it: the hat of `by`'s read at the
+ * member's stop, the stops spaced evenly from 0 to 1. Weights a voice outside a blend as one of
+ * its members, such as one member played alone.
+ *
+ * @category signal
+ */
+export declare function share<I, H = unknown>(by: Signal<I, H>, i: number, n: number): Signal<I, H>;
 /**
  * Marks `read` as a signal driven from outside the clock, which a host's own signal has to be for
  * `assess` and a history's `inputs` to treat it as one. Two uses:

package/dist/signals.js

@@ -27,6 +27,23 @@ export function peak(...signals) {
         return out;
     }, signals);
 }
+/** A blend member's share of its signal's read `k`: the members' stops sit evenly along 0..1. */
+export function shareOf(k, i, stops) {
+    const d = stops === 0 ? 0 : Math.abs(k * stops - i);
+    return d >= 1 ? 0 : 1 - d;
+}
+/**
+ * Member `i` of `n`'s share of `by`, as `mix.blend` weighs it: the hat of `by`'s read at the
+ * member's stop, the stops spaced evenly from 0 to 1. Weights a voice outside a blend as one of
+ * its members, such as one member played alone.
+ *
+ * @category signal
+ */
+export function share(by, i, n) {
+    if (!Number.isInteger(n) || n < 1 || !Number.isInteger(i) || i < 0 || i >= n)
+        throw new Error(`blits: share wants a member 0 to ${n - 1}, not ${i}`);
+    return marked((subject, setting) => shareOf(by(subject, setting), i, n - 1), [by]);
+}
 const touch = () => {
     reading.inputs++;
 };

package/dist/spans.d.ts

@@ -22,6 +22,11 @@ export declare function checkChild<I, O>(spec: VoiceSpec<I, O>, child: Voice<I,
  * after.
  */
 export declare function refit<I, O>(mix: Mixer<I, O>, span: Voice<I, O>, from?: number): void;
+/**
+ * Fits again each span with a child still to start whose anchored `earliest` answers differently
+ * than at its last fit: an anchor that has come to have an answer, or moved.
+ */
+export declare function refloor<I, O>(mix: Mixer<I, O>): void;
 /** Whether a span whose last child just left at mix time `at` stays, its budget not yet out. */
 export declare function lingers<I, O>(span: Voice<I, O>, at: number): boolean;
 /** Lets the spans that are empty and out of budget leave, at the moment their budget ran out. */

package/dist/spans.js

@@ -1,3 +1,4 @@
+import { arcEnd } from './arcs.js';
 import { elapsedWith, retime } from './clock.js';
 import { retire } from './fade.js';
 import { defaultFit, layout, settle } from './fit.js';
@@ -6,6 +7,7 @@ import { noted } from './history.js';
 import { nextFrame } from './move.js';
 import { leave } from './origin.js';
 import { ownerReading } from './owner.js';
+import { resolve } from './place.js';
 /** What a span keeps beside its owner: its claim, its fit, and how the last fit came out. */
 export class Fitting {
     budget;
@@ -39,9 +41,13 @@ export class Fitting {
 export function checkChild(spec, child) {
     if (spec.start !== undefined || spec.anchor?.start !== undefined || spec.anchor?.in !== undefined)
         throw new Error('blits: a span places the voices it holds, so one takes no start of its own');
-    if (child.holding !== null) {
+    if (child.arc !== null) {
+        if (!Number.isFinite(arcEnd(child)))
+            throw new Error('blits: a span cannot fit an arc held open, which never ends');
+    }
+    else if (child.holding !== null) {
         if (child.fitting === null)
-            throw new Error('blits: a span holds voices and spans, not owners');
+            throw new Error('blits: a span holds voices, spans and arcs, not owners');
     }
     else if (!Number.isFinite(child.span))
         throw new Error('blits: a span cannot fit a voice that never ends');
@@ -59,7 +65,7 @@ function elapsedIn(child, local) {
 }
 /** How much of a child is left, voice ms at its own clock: what its span still has to fit. */
 function leftOf(child, local) {
-    const length = child.fitting !== null ? child.fitting.end : child.span;
+    const length = child.fitting !== null ? child.fitting.end : child.arc !== null ? arcEnd(child) : child.span;
     return Math.max(0, length - elapsedIn(child, local));
 }
 /**
@@ -73,10 +79,11 @@ export function refit(mix, span, from = mix.now) {
     if (mix.projecting || span.state === 'done')
         return;
     const local = clockOf(span, from);
-    const kids = (span.holding?.children ?? []).filter((c) => c.state !== 'done' && c.state !== 'frozen' && c.state !== 'fading' && leftOf(c, local) > 0);
-    const claims = kids.map((c) => {
+    const { kids, floors, waiting } = lineUp(mix, span, local);
+    const claims = kids.map((c, i) => {
         const s = c.spec;
         return {
+            floor: floors[i],
             natural: leftOf(c, local) / (s.rate ?? 1),
             state: c.state === 'pending' ? 'pending' : 'playing',
             faster: Math.max(1, s.faster ?? 1),
@@ -127,6 +134,17 @@ export function refit(mix, span, from = mix.now) {
             noted(mix, c);
         }
     });
+    for (const c of waiting) {
+        if (c.start === Number.POSITIVE_INFINITY)
+            continue;
+        c.start = Number.POSITIVE_INFINITY;
+        c.anchorNow = Number.POSITIVE_INFINITY;
+        c.anchorElapsed = 0;
+        c.clocks = null;
+        mix.frame = nextFrame();
+        reorigin(mix, c, mix.now);
+        noted(mix, c);
+    }
     if (kids.length > 0)
         mix.lanes?.refill();
     const reach = local + length;
@@ -147,6 +165,58 @@ export function refit(mix, span, from = mix.now) {
             refit(mix, span.owner, from);
     }
 }
+/**
+ * A span's children still to fit, in the order it lays them out: those playing first, as cued, then
+ * those still to start by rank. Each pending one's floor is where its `earliest` answers, span ms
+ * from `local`, and before `local` only in the frame it was cued. One whose anchor has no answer yet waits unplaced, and under `queue` or `stagger`
+ * so does every child after it, since each is laid out from the one before.
+ */
+function lineUp(mix, span, local) {
+    const live = (span.holding?.children ?? []).filter((c) => c.state !== 'done' && c.state !== 'frozen' && c.state !== 'fading' && leftOf(c, local) > 0);
+    const kids = live.filter((c) => c.state !== 'pending');
+    const floors = kids.map(() => undefined);
+    const waiting = [];
+    const pending = live
+        .filter((c) => c.state === 'pending')
+        .sort((a, b) => (a.spec.rank ?? 0) - (b.spec.rank ?? 0));
+    const chained = span.fitting.claim.order !== 'together';
+    for (const c of pending) {
+        const e = c.spec.earliest;
+        const t = e === undefined ? undefined : resolve(mix, e, c, Number.NEGATIVE_INFINITY);
+        c.floorSeen = t ?? Number.NaN;
+        if ((e !== undefined && t === undefined) || (chained && waiting.length > 0)) {
+            waiting.push(c);
+            continue;
+        }
+        kids.push(c);
+        // An anchor that answered before the span began has no time on its clock: no bound.
+        const floor = t === undefined || t === Number.NEGATIVE_INFINITY ? undefined : t - local;
+        // A past floor places a child only as it is cued: one waiting since waits on those before it.
+        floors.push(floor === undefined || c.cuedSeq === mix.transport.seq ? floor : Math.max(0, floor));
+    }
+    return { kids, floors, waiting };
+}
+/**
+ * Fits again each span with a child still to start whose anchored `earliest` answers differently
+ * than at its last fit: an anchor that has come to have an answer, or moved.
+ */
+export function refloor(mix) {
+    if (mix.projecting)
+        return;
+    for (const span of mix.owners ?? []) {
+        if (span.fitting === null || span.state === 'done')
+            continue;
+        const moved = (span.holding?.children ?? []).some((c) => {
+            const e = c.spec.earliest;
+            if (c.state !== 'pending' || e === undefined || typeof e === 'number')
+                return false;
+            const t = resolve(mix, e, c, Number.NEGATIVE_INFINITY) ?? Number.NaN;
+            return !Object.is(t, c.floorSeen);
+        });
+        if (moved)
+            refit(mix, span);
+    }
+}
 /** Whether a span whose last child just left at mix time `at` stays, its budget not yet out. */
 export function lingers(span, at) {
     const f = span.fitting;

package/dist/store.d.ts

@@ -16,7 +16,20 @@ export declare class Store<K, V> {
     private oneValue;
     get(key: K): V | undefined;
     set(key: K, value: V): void;
+    /** As `get`, where `guess` may be the value for `key`, which a store that can tell spares a lookup. */
+    find(key: K, _guess: V): V | undefined;
     has(key: K): boolean;
     delete(key: K): void;
     clear(): void;
 }
+/**
+ * A store over another, for a copy that must not write the one it reads: what is set or deleted
+ * here stays here, and a key deleted here is no longer read from the one under it.
+ */
+export declare class Masked<K, V> extends Store<K, V> {
+    private readonly under;
+    private readonly hidden;
+    constructor(under: Store<K, V>);
+    get(key: K): V | undefined;
+    delete(key: K): void;
+}

package/dist/store.js

@@ -43,6 +43,10 @@ export class Store {
         }
         this.strong.set(key, value);
     }
+    /** As `get`, where `guess` may be the value for `key`, which a store that can tell spares a lookup. */
+    find(key, _guess) {
+        return this.get(key);
+    }
     has(key) {
         return this.get(key) !== undefined;
     }
@@ -62,6 +66,25 @@ export class Store {
         this.strong.clear();
     }
 }
+/**
+ * A store over another, for a copy that must not write the one it reads: what is set or deleted
+ * here stays here, and a key deleted here is no longer read from the one under it.
+ */
+export class Masked extends Store {
+    under;
+    hidden = new Store();
+    constructor(under) {
+        super();
+        this.under = under;
+    }
+    get(key) {
+        return super.get(key) ?? (this.hidden.get(key) ? undefined : this.under.get(key));
+    }
+    delete(key) {
+        super.delete(key);
+        this.hidden.set(key, true);
+    }
+}
 /** No key held inline. */
 const none = Symbol('none');
 /** A Map's key equality, SameValueZero: NaN finds NaN. */

package/dist/strays.js

@@ -1,6 +1,6 @@
 import { unpart } from './fade.js';
 import { pageOut } from './paging.js';
-import { record } from './tape.js';
+import { record, unplayable } from './tape.js';
 /** Notes a motion patch that may hold state for a subject no voice playing it reaches. */
 export function stray(mix, motion, subject) {
     const list = mix.strays.get(subject);
@@ -49,7 +49,12 @@ export function motionOwner(mix) {
             const m = mix.deref();
             if (m === undefined)
                 return;
-            record(m, 'motion', () => {
+            record(m, 'motion', (stage) => {
+                const to = stage.mix(m);
+                if (to === undefined)
+                    return;
+                if (to !== m)
+                    return changeAhead(to, id, motion, subject, change);
                 const v = cuedById(m, id) ?? m.gone.find((g) => g.id === id);
                 (v?.motion ?? motion).change(subject, { ...change });
             });
@@ -79,6 +84,49 @@ export function motionOwner(mix) {
         },
     };
 }
+/**
+ * A retarget or push the tape holds, made for a read ahead: kept on its transport for the patch
+ * to apply as it reads, since the patch's own state is the live mix's.
+ */
+function changeAhead(to, id, motion, given, change) {
+    const subject = given;
+    const v = cuedById(to, id);
+    let at = change.at;
+    if (v !== undefined) {
+        // As the patch asks its mix live: a subject faded out of the voice is back, and a change with
+        // no time takes the voice's at this frame, or the subject's own where it is yet to be met.
+        const parted = v.parted?.has(subject) === true;
+        if (parted)
+            unpart(to, v, subject);
+        if (at === undefined) {
+            const frame = frameOf(to, v, subject);
+            const back = parted ? timeIn(to, v, v.spec.stagger ? v.spec.stagger(subject) : 0) : frame;
+            if (!Number.isNaN(frame))
+                at = frame;
+            else if (!Number.isNaN(back))
+                at = back;
+        }
+    }
+    if (at === undefined)
+        unplayable('a change to a motion made before its voice met the subject');
+    const stamped = at;
+    const made = to.transport.ahead;
+    let bySubject = made.get(motion);
+    if (bySubject === undefined) {
+        bySubject = new Map();
+        made.set(motion, bySubject);
+    }
+    const list = bySubject.get(subject);
+    const c = { at, to: change.to, v: change.v };
+    if (list === undefined)
+        bySubject.set(subject, [c]);
+    else {
+        let i = list.length;
+        while (i > 0 && list[i - 1].at > stamped)
+            i--;
+        list.splice(i, 0, c);
+    }
+}
 /** The voice in the list with this id, which is in id order. */
 export function cuedById(mix, id) {
     const cued = mix.cued;

package/dist/tape.d.ts

@@ -1,24 +1,49 @@
+import type { Mixer } from './mixer.js';
 import type { Pace } from './pace.js';
 import type { Transport } from './transport.js';
 import type { Tape } from './types.js';
+/**
+ * Where a recorded call is made again: on the mixes the host made it on, or, for a read ahead, on
+ * its copies of them.
+ */
+export interface Stage {
+    transport(of: Transport): Transport;
+    /** The mix standing for `of`; undefined where a read ahead has no copy of it. */
+    mix<I, O>(of: Mixer<I, O>): Mixer<I, O> | undefined;
+}
+/** Refuses a recorded call a read ahead's copies cannot take. */
+export declare function unplayable(what: string): never;
 /**
  * The tape `history.tape` makes for a transport, stamping each call with the host time it was made
  * at: rate 0 holds mix time still across frames, and host time tells them apart.
  */
 export declare function tapeOf(transport: Transport): Tape | undefined;
-/** Records a host call, which `again` makes once more when the mix plays past it after a seek. */
+/**
+ * Records a host call, which `again` makes once more when the mix plays past it after a seek, or
+ * when a read ahead does, on the stage it is given.
+ */
 export declare function record(on: {
     readonly tape: Tape | undefined;
     readonly replaying: boolean;
     readonly projecting: boolean;
-}, label: string, again: () => void): void;
+}, label: string, again: (stage: Stage) => void): void;
 /** The host time at which the mix clock reads `t`, under the rate it has now. */
 export declare function hostAt(clock: {
     readonly pace: Pace | null;
 }, t: number): number;
+/**
+ * The host time a move ahead to mix time `t` lands at: never behind the clock's own, since rate 0
+ * reads `t` at every host time from the earliest `hostAt` gives, and a call stamped earlier than
+ * one already on the tape would cut it out of order.
+ */
+export declare function hostAhead(clock: {
+    readonly pace: Pace | null;
+    readonly u: number;
+}, t: number): number;
 /**
  * Makes the recorded calls `due` by the host time each was made at again, each host time's in a
  * frame of its own with every mix on the transport moved to where it stood then, as the host made
- * them. Answers the host time of the last frame it played, NaN for none.
+ * them. Answers the host time of the last frame it played, NaN for none. Given `onto` and the
+ * stage of its copies, it makes them on those, and the caller puts the tape back.
  */
-export declare function replay(transport: Transport, due: (u: number) => boolean): number;
+export declare function replay(transport: Transport, due: (u: number) => boolean, onto?: Transport, on?: Stage): number;