@msb235/blits 0.3.0 → 0.4.0

package/dist/mixer.js

@@ -1,7 +1,7 @@
 import { clampWeight, envelope, passAt, passesOf, phaseAt } from './clock.js';
 import { curve } from './easing.js';
 import { clampRun, Lanes } from './lanes.js';
-import { motionOf, noFrame } from './motion.js';
+import { motionOf, noFrame, noRevive } from './motion.js';
 import { builtOf, intosOf, readKeys } from './patch.js';
 import { reading } from './reading.js';
 import { Store } from './store.js';
@@ -21,6 +21,7 @@ function stub() {
         reaches: false,
         delay: 0,
         since: 0,
+        shown: 0,
         weight: 0,
         rested: false,
         bands: new Uint8Array(0),
@@ -171,9 +172,28 @@ export class Voice {
     keeping = false;
     /** For a motion patch, the hook it was given to ask the mix for its subjects' voice time. */
     frame = null;
+    /** For a motion patch, the hook it was given to bring a subject faded out of this voice back. */
+    revive = null;
+    /** Subjects fading out of this voice alone, by the ramp each started; null while none are. */
+    parts = null;
+    /** Subjects faded out of this voice, by the mix time each left at; null while none have. */
+    parted = null;
     ease;
     /** How many passes its `loop` plays, worked out once. */
     passes;
+    /** Voice ms its passes last, Infinity for an aperiodic patch or a loop for good. */
+    span;
+    /** The state behind a motion patch, undefined for any other. */
+    motion;
+    /** Its `hold`, for a patch it applies to: motion holds its target already. */
+    holdsBefore;
+    holdsAfter;
+    /** The mix time it first showed: when it was cued, or the first sync after. */
+    opened = Number.NaN;
+    /** Which of its entries in the mix's due queue is current; older ones are skipped when popped. */
+    dueToken = 0;
+    /** Records made while it was pending, whose `since` its start may since have moved. */
+    early = null;
     /** Reused for every call this voice makes, so it is valid only during the call. */
     setting;
     /** Every subject this voice has been asked about, so a handover knows when it is finished. */
@@ -193,6 +213,8 @@ export class Voice {
     placing = false;
     resolve;
     done;
+    play;
+    played;
     constructor(id, spec, patch, fade, now, start, slotOf, channels, host, send) {
         this.id = id;
         this.spec = spec;
@@ -208,6 +230,14 @@ export class Voice {
             : undefined;
         this.ease = fade.ease === undefined ? undefined : curve(fade.ease);
         this.passes = passesOf(spec.loop);
+        this.span =
+            patch.period > 0 && Number.isFinite(this.passes)
+                ? patch.period * this.passes
+                : Number.POSITIVE_INFINITY;
+        this.motion = motionOf(patch);
+        const holds = this.motion === undefined ? spec.hold : undefined;
+        this.holdsBefore = holds === 'before' || holds === 'both';
+        this.holdsAfter = holds === 'after' || holds === 'both';
         this.setting = {
             timestamp: 0,
             dt: 0,
@@ -225,6 +255,9 @@ export class Voice {
         this.done = new Promise((r) => {
             this.resolve = r;
         });
+        this.played = new Promise((r) => {
+            this.play = r;
+        });
         if (now >= start)
             this.state = 'live';
     }
@@ -283,6 +316,7 @@ export class Voice {
         v.holder = null;
         v.laned = false;
         v.log = null;
+        v.early = null;
         if (controls) {
             v.anchorNow = controls.anchorNow;
             v.anchorElapsed = controls.anchorElapsed;
@@ -294,6 +328,7 @@ export class Voice {
             v.outAt = controls.outAt;
         }
         v.resolve = noSend;
+        v.play = noSend;
         return v;
     }
     rateAt(now) {
@@ -349,8 +384,25 @@ class Mixer {
     wantsPose = false;
     /** The pose `pull` folds a subject into where it cannot read straight from the lanes. */
     scratch;
+    /** The last array `pull` read, by position, with each subject's chain head, to skip the lookup. */
+    /** Live voices by the earliest mix time `moveTo` would change each, a binary heap. */
+    due = [];
+    /** Voices retired since `moveTo` last pruned them. */
+    retired = 0;
+    /** Visit every voice each sync, as before the due queue; for tests that compare the two. */
+    walkAll = false;
+    pulled = [];
+    pulledHeads = [];
+    /** Each remembered head's lane slot, and the `version` and `relinks` they were all current at. */
+    pulledSlots = new Int32Array(0);
+    pulledVersion = Number.NaN;
+    pulledRelinks = -1;
+    /** Counts chains made stale one subject at a time, which `version` does not. */
+    relinks = 0;
     /** Read once a sync, so a `reduce` function is not called per voice per subject. */
     reducedNow = false;
+    /** Something was changed since the last sync, so the next frame may differ from this one. */
+    stirred = false;
     /**
      * Per subject, the first record of the chain through every live voice that reaches it, or a stub
      * where none does. Relinked when `version` moves, which is whenever the list or a voice's pending
@@ -360,6 +412,17 @@ class Mixer {
     version = 0;
     /** Per subject, the voices whose `subjects` name it, in voice order. */
     named = new Store();
+    /** Voices a subject has been faded out of, which `drop` looks in besides those that reach it. */
+    parters = new Set();
+    /**
+     * Motion patches that may hold state for a subject no voice still reaching it plays, which `drop`
+     * frees besides those voices' own: per subject, a patch a voice naming it left while another
+     * voice plays on, or that the host retargeted it on; and any patch a voice over every subject
+     * left while another plays on. How many live voices play each motion patch says which.
+     */
+    strays = new Store();
+    strayAll = new Set();
+    playing = new Map();
     /** How many voices in the list carry `subjects`. */
     naming = 0;
     /** The voices in the list that name no subjects, in voice order. */
@@ -447,17 +510,23 @@ class Mixer {
                     ? 0
                     : this.now;
         const voice = new Voice(this.nextId++, spec, patch, spec.fade ?? {}, this.now, start, this.slotOf, this.channels, this.opts.host, this.send);
-        if (!Number.isNaN(this.now))
+        if (!Number.isNaN(this.now)) {
             voice.cuedAt = this.now;
+            voice.opened = this.now;
+        }
         voice.placing = anchored;
-        const motion = motionOf(patch);
+        const motion = voice.motion;
         if (motion !== undefined) {
+            this.playing.set(motion, (this.playing.get(motion) ?? 0) + 1);
             voice.frame = Mixer.frameHook(new WeakRef(this), new WeakRef(voice));
             motion.frame = voice.frame;
+            voice.revive = Mixer.reviveHook(new WeakRef(this), new WeakRef(voice));
+            motion.revive = voice.revive;
         }
         this.voices.push(voice);
         this.index(voice);
-        this.version++;
+        this.changed(voice);
+        this.stirred = true;
         if (spec.locus !== undefined)
             this.loci++;
         if (spec.from === 'current')
@@ -467,7 +536,8 @@ class Mixer {
             this.place();
             if (!Number.isNaN(this.now) && voice.state === 'pending' && this.now >= voice.start) {
                 voice.state = 'live';
-                this.version++;
+                this.started(voice);
+                this.changed(voice);
             }
         }
         // After placing, so the controls it starts with are where its anchors put it at the cue.
@@ -475,6 +545,7 @@ class Mixer {
             voice.log = [];
             voice.note(Number.NEGATIVE_INFINITY);
         }
+        this.schedule(voice);
         return this.handle(voice);
     }
     blend(patches, by, spec = {}) {
@@ -523,24 +594,41 @@ class Mixer {
             const reach = now - (this.opts.history?.ms ?? 0);
             this.announced = this.announced.filter((a) => a.at >= reach);
         }
-        for (const voice of this.voices) {
+        // A live mix visits only the voices due by now; a projection, which copies few, visits all.
+        const visit = this.projecting || this.walkAll ? this.voices : this.popDue(now);
+        for (const voice of visit) {
             if (voice.state === 'done')
                 continue;
-            if (voice.state === 'live' && voice.outAt <= now)
+            if (Number.isNaN(voice.opened))
+                voice.opened = now;
+            if ((voice.state === 'live' || voice.state === 'held') && voice.outAt <= now)
                 this.beginFade(voice, {}, Math.max(voice.start, voice.outAt));
             if (voice.state === 'pending' && now >= voice.start) {
                 voice.state = 'live';
-                this.version++;
+                this.started(voice);
+                this.changed(voice);
             }
-            const period = voice.patch.period;
-            const passes = voice.passes;
-            if (voice.state === 'live' && period > 0 && Number.isFinite(passes)) {
-                const end = period * passes + voice.latest;
-                // The fade starts when the last pass ended, not at the frame that noticed, so it plays the
-                // same at any frame rate and a read at another time can find it.
-                if (voice.elapsedAt(now) >= end)
-                    this.beginFade(voice, {}, Math.max(voice.start, Math.min(now, voice.timeAt(end))));
+            if (voice.state !== 'pending' && Number.isFinite(voice.span)) {
+                const end = voice.span + voice.latest;
+                if (voice.elapsedAt(now) >= end) {
+                    voice.play(true);
+                    // The fade starts when the last pass ended, not at the frame that noticed, so it plays
+                    // the same at any frame rate and a read at another time can find it.
+                    if (voice.state === 'live') {
+                        if (voice.holdsAfter)
+                            voice.state = 'held';
+                        else
+                            this.beginFade(voice, {}, Math.max(voice.start, Math.min(now, voice.timeAt(end))));
+                    }
+                }
+                else if (voice.state === 'held')
+                    voice.state = 'live';
             }
+            // A projection reads a finished ramp as weight 0, and leaves the live voice's subjects be.
+            if (voice.parts !== null && !this.projecting)
+                for (const [subject, r] of voice.parts)
+                    if (now - r.at >= r.over)
+                        this.part(voice, subject, r.at + r.over);
             if (voice.state === 'fading' && voice.out) {
                 const { at, over, rest, deadline } = voice.out;
                 const spent = now - at;
@@ -555,33 +643,144 @@ class Mixer {
                 else if (spent >= over)
                     this.retire(voice, at + over);
             }
+            if (!this.projecting)
+                this.schedule(voice);
         }
+        this.stirred = false;
+        if (this.retired === 0) {
+            this.forget(now);
+            return;
+        }
+        this.retired = 0;
         let pruned = false;
-        for (let i = this.voices.length - 1; i >= 0; i--) {
-            const voice = this.voices[i];
-            if (voice.state === 'done') {
-                this.voices.splice(i, 1);
-                if (this.opts.history)
-                    this.gone.push(voice);
-                this.version++;
-                if (voice.named === null)
-                    pruned = true;
-                else
-                    this.unindex(voice);
-                if (voice.spec.locus !== undefined)
-                    this.loci--;
-                if (voice.spec.anchor !== undefined)
-                    this.anchored--;
+        let kept = 0;
+        const voices = this.voices;
+        for (let i = 0; i < voices.length; i++) {
+            const voice = voices[i];
+            if (voice.state !== 'done') {
+                voices[kept++] = voice;
+                continue;
             }
+            if (this.opts.history)
+                this.gone.push(voice);
+            else
+                this.parters.delete(voice);
+            this.unplay(voice);
+            this.changed(voice);
+            if (voice.named === null)
+                pruned = true;
+            else
+                this.unindex(voice);
+            if (voice.spec.locus !== undefined)
+                this.loci--;
+            if (voice.spec.anchor !== undefined)
+                this.anchored--;
         }
+        voices.length = kept;
         if (pruned)
             this.general = this.general.filter((v) => v.state !== 'done');
+        this.forget(now);
+    }
+    /** Lets go of the voices that have left and that history no longer reaches. */
+    forget(now) {
         const history = this.opts.history;
         if (history && this.gone.length > 0) {
             const reach = now - history.ms;
             this.gone = this.gone.filter((v) => v.doneAt >= reach);
         }
     }
+    /**
+     * The earliest mix time `moveTo` would change a voice: its start, its anchored out, the end of
+     * its last pass, the end of its fade or of a subject's ramp out; -Infinity where it must be
+     * visited every frame, Infinity where nothing will happen until a handle or anchor changes it.
+     * Early is safe, since a visit that finds nothing due schedules again; late is not, so anything
+     * that can bring it earlier calls `schedule`.
+     */
+    dueOf(voice) {
+        if (voice.state === 'done')
+            return Number.POSITIVE_INFINITY;
+        if (Number.isNaN(voice.opened))
+            return Number.NEGATIVE_INFINITY;
+        let due = Number.POSITIVE_INFINITY;
+        if (voice.parts !== null)
+            for (const r of voice.parts.values())
+                due = Math.min(due, r.at + r.over);
+        if (voice.state === 'pending')
+            return Math.min(due, Number.isNaN(voice.start) ? due : voice.start);
+        if (voice.state === 'fading') {
+            const out = voice.out;
+            if (out === null || out.rest)
+                return Number.NEGATIVE_INFINITY;
+            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 held 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 === 'held') {
+                if (voice.rate <= 0 || voice.ramp !== null)
+                    return Number.NEGATIVE_INFINITY;
+                if (!Number.isNaN(this.now) && voice.elapsedAt(this.now) < end)
+                    return Number.NEGATIVE_INFINITY;
+            }
+            if (voice.state === 'live')
+                due = Math.min(due, voice.timeAt(end));
+        }
+        return due;
+    }
+    /** Files a voice in the due queue at its current due, replacing any entry it had. */
+    schedule(voice) {
+        if (this.projecting)
+            return;
+        this.lanes?.voiceChanged(voice.id);
+        const token = ++voice.dueToken;
+        const due = this.dueOf(voice);
+        if (due === Number.POSITIVE_INFINITY)
+            return;
+        const heap = this.due;
+        heap.push({ at: Number.isNaN(due) ? Number.NEGATIVE_INFINITY : due, voice, token });
+        let i = heap.length - 1;
+        while (i > 0) {
+            const up = (i - 1) >> 1;
+            if (heap[up].at <= heap[i].at)
+                break;
+            [heap[up], heap[i]] = [heap[i], heap[up]];
+            i = up;
+        }
+    }
+    /** Takes every current entry due by `now` off the queue, in cue order. */
+    popDue(now) {
+        const heap = this.due;
+        const at = (k) => k < heap.length ? heap[k].at : Number.POSITIVE_INFINITY;
+        const out = [];
+        while (heap.length > 0 && heap[0].at <= now) {
+            const top = heap[0];
+            const last = heap.pop();
+            if (heap.length > 0) {
+                heap[0] = last;
+                let i = 0;
+                for (;;) {
+                    const l = 2 * i + 1;
+                    const r = l + 1;
+                    const m0 = at(l) < at(i) ? l : i;
+                    const m = at(r) < at(m0) ? r : m0;
+                    if (m === i)
+                        break;
+                    [heap[m], heap[i]] = [heap[i], heap[m]];
+                    i = m;
+                }
+            }
+            if (top.token === top.voice.dueToken && top.voice.state !== 'done') {
+                top.voice.dueToken++;
+                out.push(top.voice);
+            }
+        }
+        if (out.length > 1)
+            out.sort((a, b) => a.id - b.id);
+        return out;
+    }
     probe(subject, out) {
         const pose = this.fold(subject, out);
         this.keep(subject, pose, out);
@@ -632,24 +831,81 @@ class Mixer {
                 tightest = c.key;
             }
         }
-        let n = 0;
-        for (const subject of subjects) {
-            if (n >= room)
-                throw new RangeError(`blits: pull's array for ${tightest} has room for ${room} subjects, and was given more`);
-            const head = Number.isNaN(now) ? null : this.chain(subject, now);
-            const laned = head !== null && lanes?.prepare(head.slot, subject, now, this.version) === true;
-            if (laned && lanes.whole && !this.wantsPose) {
-                lanes.write(head.slot, columns, n);
-            }
-            else {
+        // Any other iterable is read into an array first, no further than one past the room there is.
+        let list;
+        if (Array.isArray(subjects))
+            list = subjects;
+        else {
+            const taken = [];
+            for (const subject of subjects)
+                if (taken.push(subject) > room)
+                    break;
+            list = taken;
+        }
+        if (list.length > room)
+            throw new RangeError(`blits: pull's array for ${tightest} has room for ${room} subjects, and was given more`);
+        const whole = lanes !== null && !this.wantsPose;
+        // An array read again in the same order reuses each position's chain head while it is current:
+        // all of them at once while nothing has relinked since the last pull, else one by one.
+        const was = this.pulled;
+        const heads = this.pulledHeads;
+        was.length = list.length;
+        heads.length = list.length;
+        if (this.pulledSlots.length < list.length) {
+            const slots = new Int32Array(Math.max(64, list.length));
+            slots.set(this.pulledSlots);
+            this.pulledSlots = slots;
+        }
+        const slots = this.pulledSlots;
+        const version = this.version;
+        const relinks = this.relinks;
+        const live = !Number.isNaN(now);
+        const current = live && this.pulledVersion === version && this.pulledRelinks === relinks;
+        // Every subject read from the lanes, at the positions it had last time, goes in one run.
+        const runs = live && whole;
+        try {
+            for (let n = 0; n < list.length; n++) {
+                if (runs) {
+                    n = lanes.pullRun(slots, list, was, current ? null : heads, n, columns, now, this.version);
+                    if (n === list.length)
+                        break;
+                }
+                const subject = list[n];
+                let slot = -1;
+                if (live) {
+                    if (current && was[n] === subject)
+                        slot = slots[n];
+                    else {
+                        const kept = heads[n];
+                        const head = was[n] === subject && kept !== undefined && kept.version === version
+                            ? kept
+                            : this.chain(subject, now);
+                        was[n] = subject;
+                        heads[n] = head;
+                        slot = head.slot;
+                        slots[n] = slot;
+                    }
+                }
+                const laned = live && lanes?.prepare(slot, subject, now, this.version) === true;
+                if (laned && whole && lanes.whole) {
+                    lanes.writeLater(slot, columns, n);
+                    continue;
+                }
+                const head = live ? heads[n] : null;
                 const folded = this.foldWith(subject, scratch, head, laned, false);
                 const pose = (this.bounded.length === 0 ? folded : this.clamp(folded));
                 this.keep(subject, pose, scratch);
                 for (const c of columns)
                     writeValue(c, pose[c.key], n);
             }
-            n++;
         }
+        finally {
+            lanes?.flush();
+        }
+        // Every head is current only if nothing relinked or changed version while they were read.
+        const unchanged = live && this.version === version && this.relinks === relinks;
+        this.pulledVersion = unchanged ? version : Number.NaN;
+        this.pulledRelinks = relinks;
     }
     /** The kit slot, width, rest and bounds of every channel `pull` was handed an array for. */
     columnsOf(into) {
@@ -716,7 +972,14 @@ class Mixer {
                 .map((v) => {
                 const log = v.log;
                 const copy = v.copy((subject) => this.recall(v, subject, t), last(log, t, (e) => e.sync) ?? log[0]);
-                copy.state = t < v.start ? 'pending' : copy.out && copy.out.at <= t ? 'fading' : 'live';
+                copy.state =
+                    t < v.start
+                        ? 'pending'
+                        : copy.out && copy.out.at <= t
+                            ? 'fading'
+                            : copy.holdsAfter && copy.elapsedAt(t) >= copy.span + copy.latest
+                                ? 'held'
+                                : 'live';
                 if (then !== undefined)
                     copy.setting.host = then;
                 return copy;
@@ -806,20 +1069,99 @@ class Mixer {
     get live() {
         return this.voices.some((v) => v.state !== 'done');
     }
+    get inert() {
+        return !this.stirred && this.voices.every((v) => this.still(v, this.now));
+    }
+    /** Whether a voice will change no pose from `now` on, short of a change made to it. */
+    still(voice, now) {
+        if (voice.state === 'done')
+            return true;
+        if (voice.state !== 'held' && voice.state !== 'live')
+            return false;
+        if (typeof voice.spec.weight === 'function' || voice.parts !== null)
+            return false;
+        const fadeIn = this.reducedNow ? 0 : (voice.fade.in ?? 0);
+        if (fadeIn > 0 && now - this.sinceOf(voice, voice.latest) < fadeIn)
+            return false;
+        if (voice.state === 'held')
+            return true;
+        const motion = voice.motion;
+        return motion !== undefined && voice.elapsedAt(now) >= voice.latest && motion.landed();
+    }
     mute(opts) {
         for (const voice of this.voices)
             this.beginFade(voice, { over: opts?.over });
     }
     drop(subject) {
         const head = this.chains.get(subject);
+        // Nothing that kept this head, such as `pull`'s remembered list, may take it as current again.
+        if (head !== undefined) {
+            head.version = Number.NaN;
+            this.relinks++;
+        }
         if (head !== undefined && head.slot >= 0 && this.lanes !== null)
             this.lanes.release(head.slot);
         this.pose.delete(subject);
         this.chains.delete(subject);
-        for (const voice of [...this.voices, ...this.gone]) {
+        this.stirred = true;
+        // 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 forget = (voice) => {
             voice.subjects.delete(subject);
-            motionOf(voice.patch)?.release(subject);
+            voice.motion?.release(subject);
+            voice.parts?.delete(subject);
+            voice.parted?.delete(subject);
+        };
+        for (const voice of this.general)
+            forget(voice);
+        const named = this.named.get(subject);
+        if (named !== undefined)
+            for (const voice of [...named])
+                forget(voice);
+        for (const voice of this.gone)
+            forget(voice);
+        for (const voice of this.parters) {
+            forget(voice);
+            if (voice.parts?.size === 0)
+                voice.parts = null;
+            if (voice.parted?.size === 0)
+                voice.parted = null;
+            if (voice.parts === null && voice.parted === null)
+                this.parters.delete(voice);
+        }
+        const strays = this.strays.get(subject);
+        if (strays !== undefined)
+            for (const motion of strays)
+                motion.release(subject);
+        this.strays.delete(subject);
+        for (const motion of this.strayAll)
+            motion.release(subject);
+    }
+    /** Notes a motion patch that may hold state for a subject no voice playing it reaches. */
+    stray(motion, subject) {
+        const list = this.strays.get(subject);
+        if (list === undefined)
+            this.strays.set(subject, [motion]);
+        else if (!list.includes(motion))
+            list.push(motion);
+    }
+    /** A motion voice left the list: if its patch plays on, its subjects' state there may stray. */
+    unplay(voice) {
+        const motion = voice.motion;
+        if (motion === undefined)
+            return;
+        const left = (this.playing.get(motion) ?? 1) - 1;
+        if (left <= 0) {
+            this.playing.delete(motion);
+            this.strayAll.delete(motion);
+            return;
         }
+        this.playing.set(motion, left);
+        if (voice.named === null)
+            this.strayAll.add(motion);
+        else
+            for (const subject of voice.named)
+                this.stray(motion, subject);
     }
     drain(tag) {
         const all = this.sent;
@@ -848,7 +1190,9 @@ class Mixer {
             fits: (voice) => mix.fits(voice),
             meet: (voice, subject) => mix.held(voice, subject, mix.now),
             naming: (subject) => (mix.naming === 0 ? undefined : mix.named.get(subject)),
+            slotOf: (subject) => mix.chains.get(subject)?.slot ?? -1,
             envelope: (voice, since) => mix.envelope(voice, mix.now, since),
+            parting: (voice, subject) => mix.parting(voice, subject, mix.now),
             ready: (voice, subject, held, elapsed, pass, weight) => {
                 mix.prime(voice, held, mix.now, elapsed, pass);
                 voice.setting.weight = weight;
@@ -874,6 +1218,8 @@ class Mixer {
         const patch = voice.patch;
         if (voice.keeping)
             return false;
+        if (voice.state === 'pending' && voice.holdsBefore)
+            return false;
         if (typeof spec.weight === 'function')
             return false;
         if (spec.locus !== undefined || spec.from === 'current')
@@ -899,6 +1245,20 @@ class Mixer {
      * What a motion patch asks for its subjects' voice time at the latest frame. It holds the mix and
      * the voice weakly, so a patch the host keeps does not keep a mix it has let go of alive.
      */
+    static reviveHook(mix, voice) {
+        return (subject) => {
+            const m = mix.deref();
+            if (m === undefined)
+                return;
+            m.stirred = true;
+            const v = voice.deref();
+            if (v === undefined)
+                return;
+            if (v.motion !== undefined && v.named !== null && !v.named.has(subject))
+                m.stray(v.motion, subject);
+            m.unpart(v, subject);
+        };
+    }
     static frameHook(mix, voice) {
         return (subject) => {
             const m = mix.deref();
@@ -924,19 +1284,18 @@ class Mixer {
     prime(voice, held, now, elapsed, pass) {
         const setting = voice.setting;
         setting.timestamp = now;
-        const gap = now - held.stepped;
-        const cap = this.opts.maxDt;
-        setting.dt = this.reducedNow
-            ? Number.POSITIVE_INFINITY
-            : cap !== undefined && gap > cap
-                ? cap
-                : gap;
+        setting.dt = this.capped(now - held.stepped);
         setting.elapsed = elapsed;
         setting.pass = pass;
         setting.weight = 0;
         setting.state = held.state;
         setting.keep = held.keep;
     }
+    /** A gap as a `dt`: Infinity under reduced motion, and no more than `maxDt`. */
+    capped(gap) {
+        const cap = this.opts.maxDt;
+        return this.reducedNow ? Number.POSITIVE_INFINITY : cap !== undefined && gap > cap ? cap : gap;
+    }
     /** The earliest voice time a read may still ask for, for a subject delayed `delay`. */
     horizonFor(voice, delay, now) {
         const history = this.opts.history;
@@ -1102,14 +1461,10 @@ class Mixer {
             outAt = out.at;
         else if (Number.isFinite(voice.outAt))
             outAt = voice.outAt;
-        else {
-            const period = voice.patch.period;
-            const passes = voice.passes;
-            if (period > 0 && Number.isFinite(passes)) {
-                const t = voice.timeAt(period * passes + voice.latest);
-                if (Number.isFinite(t))
-                    outAt = Math.max(start, t);
-            }
+        else if (!voice.holdsAfter && Number.isFinite(voice.span)) {
+            const t = voice.timeAt(voice.span + voice.latest);
+            if (Number.isFinite(t))
+                outAt = Math.max(start, t);
         }
         if (mark === 'out')
             return voice.state === 'done' && outAt === undefined ? voice.doneAt : outAt;
@@ -1130,6 +1485,8 @@ class Mixer {
     }
     /** Records a change to a voice's controls under `history`, and lets go of what it no longer reaches. */
     noted(voice) {
+        this.stirred = true;
+        this.schedule(voice);
         const log = voice.log;
         if (log === null)
             return;
@@ -1212,6 +1569,7 @@ class Mixer {
             reaches: live.reaches,
             delay: live.delay,
             since: live.since,
+            shown: live.shown,
             weight: 0,
             rested: false,
             bands: new Uint8Array(voice.slots.length),
@@ -1355,6 +1713,7 @@ class Mixer {
             get state() {
                 return voice.state;
             },
+            played: voice.played,
             get weight() {
                 return voice.weight;
             },
@@ -1390,7 +1749,10 @@ class Mixer {
                 mix.lanes?.refill();
             },
             fade(opts) {
-                mix.beginFade(voice, opts ?? {});
+                if (opts !== undefined && 'subject' in opts)
+                    mix.fadeSubject(voice, opts.subject, opts.over);
+                else
+                    mix.beginFade(voice, opts ?? {});
             },
             weightOf(subject) {
                 if (voice.state === 'done')
@@ -1405,13 +1767,85 @@ class Mixer {
             done: voice.done,
         };
     }
+    /** Starts one subject's ramp out of a voice, or takes it out at once for a ramp of 0. */
+    fadeSubject(voice, subject, over) {
+        if (voice.state === 'done' || voice.parted?.has(subject) || voice.parts?.has(subject))
+            return;
+        this.stirred = true;
+        const ms = this.reduced ? 0 : (over ?? voice.fade.out ?? 0);
+        const at = Number.isNaN(this.now) ? voice.start : this.now;
+        if (ms === 0) {
+            this.part(voice, subject, at);
+            return;
+        }
+        voice.parts ??= new Map();
+        voice.parts.set(subject, { at, over: ms });
+        this.parters.add(voice);
+        this.schedule(voice);
+        this.lanes?.refill();
+    }
+    /** What a subject's own ramp out of a voice leaves of its weight this frame, 0..1. */
+    parting(voice, subject, now) {
+        const r = voice.parts?.get(subject);
+        if (r === undefined)
+            return 1;
+        return envelope(0, { at: r.at, over: r.over, rest: false }, voice.ease, this.reducedNow, now, 0);
+    }
+    /**
+     * Takes a subject out of one voice for good, as of mix time `at`: the voice forgets its record,
+     * its lane position and a motion patch's state for it, and reaches it no more.
+     */
+    part(voice, subject, at) {
+        voice.parts?.delete(subject);
+        if (voice.parts?.size === 0)
+            voice.parts = null;
+        voice.parted ??= new Map();
+        voice.parted.set(subject, at);
+        this.parters.add(voice);
+        this.forgetIn(voice, subject);
+        const motion = voice.motion;
+        if (motion !== undefined && motion.frame === voice.frame)
+            motion.release(subject);
+    }
+    /** Brings a subject faded out of a voice back, to be met afresh on its next probe. */
+    unpart(voice, subject) {
+        if (voice.parted?.delete(subject) !== true)
+            return;
+        if (voice.parted.size === 0)
+            voice.parted = null;
+        this.forgetIn(voice, subject);
+        const slot = this.chains.get(subject)?.slot ?? -1;
+        if (slot >= 0)
+            this.lanes?.rejoin(slot);
+    }
+    /** Drops a voice's record of a subject and relinks the subject's chain without it. */
+    forgetIn(voice, subject) {
+        const held = voice.subjects.get(subject);
+        if (held !== undefined) {
+            voice.subjects.delete(subject);
+            if (held.reaches)
+                voice.seen--;
+            if (held.rested)
+                voice.restedCount--;
+            if (voice.holder === held)
+                voice.holder = null;
+        }
+        const head = this.chains.get(subject);
+        if (head === undefined)
+            return;
+        head.version = Number.NaN;
+        this.relinks++;
+        if (voice.laned && head.slot >= 0)
+            this.lanes?.part(voice.id, head.slot);
+        this.lanes?.refill();
+    }
     beginFade(voice, opts, at) {
         if (voice.state === 'done' || voice.state === 'fading')
             return;
         const over = this.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')
-            this.version++;
+            this.changed(voice);
         voice.state = 'fading';
         voice.out = {
             from: 1,
@@ -1430,13 +1864,18 @@ class Mixer {
     }
     /** Removes a voice, recording that it left at `at`, default now. */
     retire(voice, at) {
-        this.lanes?.invalidate();
-        const motion = motionOf(voice.patch);
+        this.lanes?.touch(voice);
+        const motion = voice.motion;
         if (motion !== undefined && motion.frame === voice.frame)
             motion.frame = noFrame;
+        if (motion !== undefined && motion.revive === voice.revive)
+            motion.revive = noRevive;
         voice.frame = null;
+        voice.revive = null;
         voice.state = 'done';
+        this.retired++;
         voice.doneAt = at ?? (Number.isNaN(this.now) ? Number.NEGATIVE_INFINITY : this.now);
+        voice.play(false);
         voice.resolve();
     }
     /** The ramp a voice's own fade envelope applies this frame, 0..1. */
@@ -1450,16 +1889,13 @@ class Mixer {
             return held;
         const reaches = this.aims(voice, subject);
         const delay = reaches && voice.spec.stagger ? voice.spec.stagger(subject) : 0;
-        // When the voice clock reads `delay`, from where it is anchored now; during a ramp this assumes
-        // the rate it is ramping to.
-        const since = voice.rate > 0
-            ? voice.anchorNow + (delay - voice.anchorElapsed) / voice.rate
-            : voice.start + delay;
+        const since = this.sinceOf(voice, delay);
         const kept = new Map();
         held = {
             reaches,
             delay,
             since,
+            shown: this.shownOf(voice, since),
             weight: 0,
             rested: false,
             bands: new Uint8Array(voice.slots.length),
@@ -1485,12 +1921,43 @@ class Mixer {
             held.unknown = this.backward && voice.spec.from === 'current';
         }
         voice.subjects.set(subject, held);
+        if (voice.state === 'pending') {
+            voice.early ??= [];
+            voice.early.push(held);
+        }
         if (reaches)
             voice.seen++;
-        if (delay > voice.latest)
+        if (delay > voice.latest) {
             voice.latest = delay;
+            // A later end can take a held voice live again.
+            if (voice.state === 'held')
+                this.schedule(voice);
+        }
         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.
+     */
+    sinceOf(voice, delay) {
+        return voice.rate > 0
+            ? voice.anchorNow + (delay - voice.anchorElapsed) / voice.rate
+            : voice.start + delay;
+    }
+    shownOf(voice, since) {
+        return voice.holdsBefore && voice.opened < since ? voice.opened : since;
+    }
+    /** A voice has gone live: the records it made while pending count from where it started. */
+    started(voice) {
+        const early = voice.early;
+        if (early === null)
+            return;
+        voice.early = null;
+        for (const held of early) {
+            held.since = this.sinceOf(voice, held.delay);
+            held.shown = this.shownOf(voice, held.since);
+        }
+    }
     /** The weight a voice gives a subject this frame, with the setting already filled in. */
     weigh(voice, subject, now, held) {
         this.sending.voice = voice;
@@ -1503,7 +1970,8 @@ class Mixer {
             if (signal.input && !was)
                 this.record(held, base);
         }
-        return clampWeight(base * this.envelope(voice, now, held.since));
+        const fade = this.envelope(voice, now, held.shown);
+        return clampWeight(base * (voice.parts === null ? fade : fade * this.parting(voice, subject, now)));
     }
     /**
      * One live voice's delta for one subject this frame, through its record for the subject, or null
@@ -1515,9 +1983,19 @@ class Mixer {
             return null;
         if (voice.out?.rest && held.rested)
             return null;
-        const elapsed = voice.elapsedAt(now) - held.delay;
-        if (elapsed < 0)
-            return null;
+        let elapsed = voice.elapsedAt(now) - held.delay;
+        // A held subject's clock stands still at the edge it holds: -1 before, 1 after, 0 playing.
+        let still = 0;
+        if (elapsed < 0) {
+            if (!voice.holdsBefore)
+                return null;
+            elapsed = 0;
+            still = -1;
+        }
+        else if (voice.holdsAfter && elapsed > voice.span) {
+            elapsed = voice.span;
+            still = 1;
+        }
         const period = voice.patch.period;
         const phase = phaseAt(elapsed, period, voice.passes);
         const pass = passAt(elapsed, period, voice.passes);
@@ -1538,12 +2016,16 @@ class Mixer {
             this.recordHost(now);
         reading.horizon = this.horizonFor(voice, held.delay, now);
         const tick = this.opts.stepMs;
-        if (voice.patch.step && held.probed !== now) {
+        if (voice.patch.step && held.probed !== now && still >= 0) {
+            // Held 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 (tick !== undefined && tick > 0 && !this.reducedNow)
-                this.tick(voice, subject, held, tick);
-            else if (now !== held.stepped) {
+                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 = now;
+                held.stepped = to;
             }
         }
         let delta;
@@ -1591,13 +2073,13 @@ class Mixer {
      * counted from when its delay ran out, and leaves the remainder for the next sample. Counting
      * rather than adding keeps the grid where it is however many samples it is reached through.
      */
-    tick(voice, subject, held, tick) {
+    tick(voice, subject, held, tick, to) {
         const now = this.now;
         const setting = voice.setting;
         const frameDt = setting.dt;
         let n = held.ticks;
         // The epsilon keeps an interval like 1000 / 120 from landing a hair short of a whole count.
-        const due = Math.floor((now - held.since) / tick + 1e-9);
+        const due = Math.floor((to - held.since) / tick + 1e-9);
         const cap = this.opts.maxDt;
         if (cap !== undefined) {
             const most = Math.floor(cap / tick);
@@ -1714,7 +2196,8 @@ class Mixer {
     /**
      * The first of this subject's records, linked through every live voice that reaches it. A voice
      * is asked once, through the record it keeps for the subject anyway; a pending one is linked when
-     * it goes live, since `target` is asked on first sight, and sight only comes once a voice plays.
+     * it goes live, since `target` is asked on first sight, and sight only comes once a voice plays
+     * or holds before.
      */
     chain(subject, now) {
         const was = this.chains.get(subject);
@@ -1723,7 +2206,8 @@ class Mixer {
         let first = null;
         let prev = null;
         const link = (voice) => {
-            if (voice.state !== 'live' && voice.state !== 'fading')
+            const state = voice.state;
+            if (state === 'done' || (state === 'pending' && !voice.holdsBefore))
                 return;
             const held = this.held(voice, subject, now);
             if (!held.reaches)
@@ -1761,10 +2245,32 @@ class Mixer {
     }
     /** Whether a voice reaches a subject by what its spec says: the subjects it names, or its `target`. */
     aims(voice, subject) {
+        // A read back to before a subject left still finds it reached.
+        const left = voice.parted?.get(subject);
+        if (left !== undefined && !(this.now < left))
+            return false;
         if (voice.named !== null)
             return voice.named.has(subject);
         return voice.spec.target ? voice.spec.target(subject) : true;
     }
+    /**
+     * A voice joined or left the list, or started or stopped waiting: the chains it is linked into
+     * are relinked, every subject's for a voice over all of them and only its own for one naming
+     * its subjects, and lanes take it on or off.
+     */
+    changed(voice) {
+        this.lanes?.touch(voice);
+        if (voice.named === null) {
+            this.version++;
+            return;
+        }
+        for (const subject of voice.named) {
+            const head = this.chains.get(subject);
+            if (head !== undefined)
+                head.version = Number.NaN;
+        }
+        this.relinks++;
+    }
     /** Files a voice under each subject it names, or among the voices that name none. */
     index(voice) {
         if (voice.named === null) {