@msb235/blits 0.11.0 → 0.12.1

package/dist/watch.js

@@ -0,0 +1,467 @@
+import { seek } from './seek.js';
+import { release } from './shared.js';
+import { hostAhead } from './tape.js';
+const KEY = Symbol.for('@msb235/blits/watch/1');
+const slot = globalThis;
+/**
+ * Every mix made on the page, shared by every copy of blits loaded: what a debugger reads to find
+ * them. See `Registry`.
+ *
+ * @category mix
+ */
+export function watched() {
+    return registry();
+}
+function registry() {
+    let r = slot[KEY];
+    if (r !== undefined)
+        return r;
+    const refs = new Map();
+    const fns = new Set();
+    const entries_ = new WeakMap();
+    r = {
+        refs,
+        entries_,
+        fns,
+        labels: new WeakMap(),
+        next: 1,
+        counted: 0,
+        history: undefined,
+        gone: new FinalizationRegistry((id) => {
+            refs.delete(id);
+            for (const fn of [...fns])
+                fn({ kind: 'gone', id });
+        }),
+        entries() {
+            const out = [];
+            for (const ref of refs.values()) {
+                const mix = ref.deref();
+                const entry = mix === undefined ? undefined : entries_.get(mix);
+                if (entry !== undefined)
+                    out.push(entry);
+            }
+            return out;
+        },
+        on(fn) {
+            fns.add(fn);
+            return () => {
+                fns.delete(fn);
+            };
+        },
+    };
+    slot[KEY] = r;
+    return r;
+}
+/** The transports whose history the registry's default gave. */
+const added = new WeakSet();
+/**
+ * The history a mix or transport made with `opts` keeps: its own, or with none named and no
+ * transport, the registry's default. Reads the registry only where one was made.
+ */
+export function historyFor(opts) {
+    const fallback = slot[KEY]?.history;
+    if (opts.history !== undefined || opts.transport !== undefined || fallback === undefined)
+        return { history: opts.history, added: false };
+    return { history: fallback, added: true };
+}
+/** Marks a transport whose history the registry's default gave. */
+export function gave(transport) {
+    added.add(transport);
+}
+/** Lists a mix the host made, under an entry this copy builds. */
+export function register(mix) {
+    const r = registry();
+    const id = r.next++;
+    const transport = mix.transport;
+    const entry = {
+        id,
+        release,
+        name: mix.name,
+        mix,
+        get history() {
+            const h = transport.history;
+            return h === undefined
+                ? undefined
+                : { ms: h.ms, tape: transport.tape !== undefined, added: added.has(transport) };
+        },
+        get reach() {
+            return reachOf(transport, false);
+        },
+        channels: mix.names,
+        voice: (handle) => {
+            const v = mix.cued.find((c) => c.handle === handle) ?? mix.gone.find((c) => c.handle === handle);
+            return v === undefined ? undefined : { name: v.spec.name, tags: v.spec.tags ?? [] };
+        },
+        label: (subject) => labelOf(mix, subject),
+        watch: (fn) => tap(mix, fn),
+        subjects: () => subjectsOf(mix),
+        read: (subject, at = mix.now) => mix.project(at).probe(subject),
+        hold: () => hold(transport),
+    };
+    r.entries_.set(mix, entry);
+    r.refs.set(id, new WeakRef(mix));
+    r.gone.register(mix, id, mix);
+    for (const fn of [...r.fns])
+        fn({ kind: 'add', entry });
+}
+/** Unlists a mix, telling every listener it is gone; one not listed is left alone. */
+export function unregister(mix) {
+    const r = registry();
+    const entry = r.entries_.get(mix);
+    if (entry === undefined || !r.refs.has(entry.id))
+        return;
+    r.refs.delete(entry.id);
+    r.gone.unregister(mix);
+    untap(mix);
+    const t = mix.transport;
+    const held = ctlOf(t).held;
+    const listed = (m) => r.refs.has(r.entries_.get(m)?.id ?? -1);
+    if (held !== null && !t.members.some(listed))
+        held.free();
+    for (const fn of [...r.fns])
+        fn({ kind: 'gone', id: entry.id });
+}
+function labelOf(mix, subject) {
+    const own = mix.opts.labelOf?.(subject);
+    return own ?? guess(subject);
+}
+/** A name for a subject from the subject itself, numbered by class where nothing names it. */
+function guess(subject) {
+    if (typeof subject !== 'object' || subject === null)
+        return typeof subject === 'function' ? subject.name || 'function' : String(subject);
+    const Element = globalThis.Element;
+    if (Element !== undefined && subject instanceof Element) {
+        const id = subject.id ? `#${subject.id}` : '';
+        const classes = [...subject.classList].map((c) => `.${c}`).join('');
+        return `${subject.tagName.toLowerCase()}${id}${classes}`;
+    }
+    const o = subject;
+    for (const k of ['name', 'id']) {
+        const v = o[k];
+        if ((typeof v === 'string' && v !== '') || typeof v === 'number')
+            return String(v);
+    }
+    const r = registry();
+    let label = r.labels.get(subject);
+    if (label === undefined) {
+        label = `${subject.constructor?.name || 'Object'} #${++r.counted}`;
+        r.labels.set(subject, label);
+    }
+    return label;
+}
+function subjectsOf(mix) {
+    const t = taps.get(mix);
+    const out = new Set(t?.was);
+    for (const s of t?.seen ?? [])
+        out.add(s);
+    for (const v of mix.cued)
+        if (v.state !== 'done')
+            for (const s of v.spec.subjects ?? [])
+                out.add(s);
+    return [...out];
+}
+const ctls = new WeakMap();
+function ctlOf(t) {
+    let c = ctls.get(t);
+    if (c === undefined) {
+        c = { tapped: 0, held: null, unsync: null };
+        ctls.set(t, c);
+    }
+    return c;
+}
+/** Puts `sync` on the transport while anything needs it, and takes it off when nothing does. */
+function fit(t) {
+    const c = ctlOf(t);
+    const wants = c.tapped > 0 || c.held !== null;
+    if (wants && c.unsync === null) {
+        const sync = proto(t).sync;
+        c.unsync = swap(t, 'sync', (ts) => {
+            for (const m of t.members)
+                flush(m);
+            const held = c.held;
+            if (held === null)
+                sync.call(t, ts);
+            else
+                held.sync(ts);
+        });
+    }
+    else if (!wants && c.unsync !== null) {
+        c.unsync();
+        c.unsync = null;
+    }
+}
+/**
+ * Sets `key` on `on` itself, and returns what puts back the function it had. That stays an own
+ * property: deleting one added before another drops the mix or transport into dictionary mode
+ * for good, which slows every later call on it.
+ */
+function swap(on, key, fn) {
+    const o = on;
+    const was = o[key];
+    o[key] = fn;
+    return () => {
+        o[key] = was;
+    };
+}
+function proto(o) {
+    return Object.getPrototypeOf(o);
+}
+const taps = new WeakMap();
+function tap(mix, fn) {
+    let t = taps.get(mix);
+    if (t === undefined) {
+        const p = proto(mix);
+        const probe = p.probe;
+        const pull = p.pull;
+        const drain = p.drain;
+        const puts = [
+            swap(mix, 'probe', (subject, out) => {
+                const pose = probe.call(mix, subject, out);
+                const f = frameOf(mix);
+                f.probed.push({ subject, pose: copy(pose) });
+                taps.get(mix).seen.add(subject);
+                return pose;
+            }),
+            swap(mix, 'pull', (subjects, into) => {
+                const list = Array.isArray(subjects) ? subjects : [...subjects];
+                pull.call(mix, list, into);
+                const columns = {};
+                for (const [k, v] of Object.entries(into))
+                    if (v !== undefined)
+                        columns[k] = v.slice();
+                frameOf(mix).pulled.push({ subjects: [...list], columns });
+                const seen = taps.get(mix).seen;
+                for (const s of list)
+                    seen.add(s);
+            }),
+            swap(mix, 'drain', (tag) => {
+                const out = drain.call(mix, tag);
+                if (out.length > 0)
+                    frameOf(mix).sent.push(...out);
+                return out;
+            }),
+        ];
+        t = {
+            fns: new Set(),
+            frame: null,
+            seen: new Set(),
+            was: new Set(),
+            untap: () => {
+                for (const put of puts)
+                    put();
+            },
+        };
+        taps.set(mix, t);
+        ctlOf(mix.transport).tapped++;
+        fit(mix.transport);
+    }
+    t.fns.add(fn);
+    return stopper(new WeakRef(mix), fn);
+}
+/**
+ * What stops one watcher, holding the mix weakly so a debugger that keeps it does not keep the
+ * mix alive. Made out here: a closure made inside `tap` would share the scope that holds the mix.
+ */
+function stopper(ref, fn) {
+    return () => {
+        const m = ref.deref();
+        const own = m === undefined ? undefined : taps.get(m);
+        if (m === undefined || own === undefined || !own.fns.delete(fn) || own.fns.size > 0)
+            return;
+        untap(m);
+    };
+}
+/** Puts back what watching `mix` swapped, whoever is still watching. */
+function untap(mix) {
+    const own = taps.get(mix);
+    if (own === undefined)
+        return;
+    own.untap();
+    taps.delete(mix);
+    ctlOf(mix.transport).tapped--;
+    fit(mix.transport);
+}
+/** The frame a read lands in, handing the last one over where the mix has moved on since. */
+function frameOf(mix) {
+    const t = taps.get(mix);
+    if (t.frame !== null && t.frame.seq === mix.transport.seq)
+        return t.frame;
+    flush(mix);
+    t.was = t.seen;
+    t.seen = new Set();
+    t.frame = {
+        seq: mix.transport.seq,
+        now: mix.now,
+        timestamp: mix.timestamp,
+        probed: [],
+        pulled: [],
+        sent: [],
+        voices: mix.voices(),
+    };
+    return t.frame;
+}
+function flush(mix) {
+    const t = taps.get(mix);
+    const frame = t?.frame;
+    if (t === undefined || frame == null)
+        return;
+    t.frame = null;
+    for (const fn of [...t.fns])
+        fn(frame);
+}
+function copy(pose) {
+    try {
+        return globalThis.structuredClone(pose);
+    }
+    catch {
+        return { ...pose };
+    }
+}
+/** The earliest mix time history reaches back to; a seek needs a tape besides. */
+function reachOf(t, seeking) {
+    const h = t.history;
+    if (h === undefined || (seeking && t.tape === undefined))
+        return t.now;
+    const kept = t.pager !== null ? Number.NEGATIVE_INFINITY : t.now - h.ms;
+    return Math.max(t.born, t.floor, kept);
+}
+function hold(t) {
+    const c = ctlOf(t);
+    if (c.held !== null)
+        throw new Error('blits: that mix is held already; free it first');
+    const p = proto(t);
+    const ramp = p.ramp;
+    const rebase = p.rebase;
+    const sync = p.sync;
+    const seekT = p.seek;
+    const queue = [];
+    let rate = 0;
+    let quiet = false;
+    let freed = false;
+    // The host time the hold syncs the transport at, moved by the host's gaps at `rate`; the
+    // transport's own rate is left alone, so nothing the hold does lands in its history.
+    let line = t.last;
+    let host = t.last;
+    const hushed = (fn) => {
+        const was = quiet;
+        quiet = true;
+        try {
+            fn();
+        }
+        finally {
+            quiet = was;
+        }
+    };
+    const later = (fn) => {
+        if (t.replaying || quiet)
+            fn();
+        else
+            queue.push(fn);
+    };
+    /** Syncs at `line`, where a rebase the host asked for before the hold takes out no time of it. */
+    const at = () => {
+        if (t.rebasing && !Number.isNaN(t.last))
+            sync.call(t, t.last);
+        sync.call(t, line);
+    };
+    const puts = [];
+    const tape = t.tape;
+    if (tape !== undefined) {
+        const record = tape.recordEntry;
+        // Behind the tape's last call, a call the host makes would cut the calls after it; it acts
+        // on the mix but goes unrecorded, so they play on.
+        puts.push(swap(tape, 'recordEntry', (...args) => {
+            if (quiet || tape.timestampAt(tape.undoDepth()) !== undefined)
+                return;
+            record.apply(tape, args);
+        }));
+    }
+    puts.push(swap(t, 'ramp', (r, over) => {
+        if (!(r >= 0 && r < Number.POSITIVE_INFINITY))
+            throw new RangeError(`blits: a mix's rate is a finite number, 0 or more, not ${r}`);
+        later(() => ramp.call(t, r, over));
+    }), swap(t, 'rebase', () => later(() => rebase.call(t))), swap(t, 'seek', (to) => later(() => seekT.call(t, to))));
+    for (const m of t.members) {
+        const mixSeek = proto(m).seek;
+        puts.push(swap(m, 'seek', (to) => {
+            if (t.shared)
+                mixSeek.call(m, to);
+            else
+                later(() => mixSeek.call(m, to));
+        }));
+    }
+    c.held = {
+        sync(ts) {
+            if (Number.isNaN(line))
+                line = ts;
+            else if (!Number.isNaN(host) && ts > host)
+                line += (ts - host) * rate;
+            host = ts;
+            at();
+        },
+        free: () => handle.free(),
+    };
+    fit(t);
+    t.woke();
+    const live = () => {
+        if (freed)
+            throw new Error('blits: that hold was freed');
+    };
+    const handle = {
+        get mixes() {
+            return [...t.members];
+        },
+        get now() {
+            return t.now;
+        },
+        get reach() {
+            return reachOf(t, true);
+        },
+        get rate() {
+            return rate;
+        },
+        set rate(r) {
+            live();
+            if (!(r >= 0 && r < Number.POSITIVE_INFINITY))
+                throw new RangeError(`blits: a hold's rate is a finite number, 0 or more, not ${r}`);
+            rate = r;
+        },
+        seek(to) {
+            live();
+            hushed(() => seek(t, to));
+        },
+        step(ms) {
+            live();
+            if (!(ms > 0))
+                return;
+            if (Number.isNaN(line))
+                throw new Error('blits: a mix that has never synced has nothing to step');
+            const u = hostAhead(t, t.now + ms);
+            if (!Number.isFinite(u))
+                throw new RangeError("blits: the mix's own rate is 0, so it never moves");
+            line = Math.max(line, u + t.offset);
+            at();
+            for (const m of t.members)
+                m.stir();
+        },
+        free() {
+            if (freed)
+                return;
+            freed = true;
+            try {
+                rebase.call(t);
+                // Still behind the guard on the tape, so a call made behind its last one cuts nothing.
+                for (const fn of queue)
+                    fn();
+            }
+            finally {
+                for (const put of puts.reverse())
+                    put();
+                c.held = null;
+                fit(t);
+                t.woke();
+            }
+        },
+    };
+    return handle;
+}

package/dist/weigh.d.ts

@@ -1,7 +1,18 @@
 import type { Mixer } from './mixer.js';
 import type { Subject, Voice } from './voice.js';
-/** Fills a voice's setting for a call to its patch, the weight aside. */
-export declare function prime<I, O>(this: Mixer<I, O>, voice: Voice<I, O>, held: Subject<unknown>, now: number, elapsed: number, pass: number): void;
+/**
+ * Where `prime` reads its numbers in `Mixer.primed`: as arguments, each would be boxed wherever V8
+ * does not inline the call, which turns on the order its compiles ran (bench/frame.mjs `glow`,
+ * 2026-10-20).
+ */
+export declare const enum Primed {
+    NOW = 0,
+    ELAPSED = 1,
+    PASS = 2,
+    SIZE = 3
+}
+/** Fills a voice's setting for a call to its patch, the weight aside, from `primed`. */
+export declare function prime<I, O>(this: Mixer<I, O>, voice: Voice<I, O>, held: Subject<unknown>): void;
 /** A gap as a `dt`: Infinity under reduced motion, and no more than `maxDt`. */
 export declare function capped<I, O>(this: Mixer<I, O>, gap: number): number;
 /** The earliest voice time a read may still ask for, for a subject delayed `delay`. */

package/dist/weigh.js

@@ -2,8 +2,11 @@ import { envelope, weighed } from './clock.js';
 import { elapsedThen, last, record } from './history.js';
 import { ownersWeight } from './owner.js';
 import { reading } from './reading.js';
-/** Fills a voice's setting for a call to its patch, the weight aside. */
-export function prime(voice, held, now, elapsed, pass) {
+/** Fills a voice's setting for a call to its patch, the weight aside, from `primed`. */
+export function prime(voice, held) {
+    const now = this.primed[0 /* Primed.NOW */];
+    const elapsed = this.primed[1 /* Primed.ELAPSED */];
+    const pass = this.primed[2 /* Primed.PASS */];
     const setting = voice.setting;
     setting.timestamp = now;
     // With no step to move it, `stepped` follows the call before this frame's.
@@ -48,7 +51,11 @@ export function ownerBase(owner, subject) {
     const kept = reading.kept;
     // An owner's record keeps a frame in `probed`, not a time, so `prime` leaves its `stepped` be.
     held.probed = Number.NaN;
-    this.prime(owner, held, now, owner.elapsedAt(now), 0);
+    const primed = this.primed;
+    primed[0 /* Primed.NOW */] = now;
+    primed[1 /* Primed.ELAPSED */] = owner.elapsedAt(now);
+    primed[2 /* Primed.PASS */] = 0;
+    this.prime(owner, held);
     const base = this.base(owner, subject, now, held);
     reading.kept = kept;
     held.stepped = now;

package/docs/schema.html

@@ -404,7 +404,7 @@ interface Setting<S = void, H = unknown> {
 <h2 id="voices">Voices</h2>
 <p>A voice is a patch given a clock and a volume knob. This is the unit that answers "independent state and timeframe": two voices of the same patch are two clocks, two states, two weights.</p>
 
-<pre><code><span class="cm">/** `SpanHints` are `faster`, `slower`, `overlap`, `ballast`, and `priority`, read only under a span. See Spans. */</span>
+<pre><code><span class="cm">/** `SpanHints` are `faster`, `slower`, `overlap`, `ballast`, `priority`, `earliest` and `rank`, read only under a span. See Spans. */</span>
 interface VoiceSpec&lt;I, O, H = unknown&gt; extends SpanHints {
   patch: Patch&lt;I, O, unknown, H&gt;;
   <span class="cm">/** What `history.revive` builds this spec from again, so a history `store` can page the voice out once it has
@@ -830,7 +830,7 @@ phase.result;   <span class="cm">// { budget, length, over, skipped, fell }</spa
   <div class="tbl"><table>
     <tr><th>On the span</th><th>Means</th></tr>
     <tr><td><code>duration</code></td><td>Its budget, ms on its own clock. Without one the span only keeps its children's order, which makes it a sequencer for voices that arrive late.</td></tr>
-    <tr><td><code>order</code>, <code>share</code></td><td><code>queue</code> starts each child once the one before ends, <code>stagger</code> starts it <code>share</code> of the way through (0.5), <code>together</code> starts them all at once. Children are laid out in the order they were cued.</td></tr>
+    <tr><td><code>order</code>, <code>share</code></td><td><code>queue</code> starts each child once the one before ends, <code>stagger</code> starts it <code>share</code> of the way through (0.5), <code>together</code> starts them all at once. Children still to start are laid out by their <code>rank</code>, ties in the order they were cued.</td></tr>
     <tr><td><code>fit</code></td><td>A strategy, a plain function from the span's claim and its children's claims to a rate and a skip per child. It starts from the children already retimed: before any fit, the span moves every child's rate by one factor toward its budget, faster where they run past it and slower where they leave room, each as far as its <code>faster</code> or <code>slower</code> allows. Default <code>pipe(condense(), shed())</code>.</td></tr>
     <tr><td><code>priority</code></td><td>How hard its length holds, <code>weak</code>, <code>strong</code> (default) or <code>required</code>: against its children here, and against its own span when it is held by one.</td></tr>
     <tr><td><code>spill</code></td><td>What happens when the fit leaves the children too long for a span at least <code>strong</code>: <code>instant</code> (default) jumps every child weaker than the span to its end at once, so the budget holds; <code>overrun</code> lets them run long. A <code>weak</code> span runs long and does not count it as falling back.</td></tr>
@@ -841,6 +841,8 @@ phase.result;   <span class="cm">// { budget, length, over, skipped, fell }</spa
     <tr><td><code>overlap</code></td><td>It may start before the one before it ends where the order would not have it.</td></tr>
     <tr><td><code>ballast</code></td><td>It may jump to its end instead of playing. A span held by a span is never skipped.</td></tr>
     <tr><td><code>priority</code></td><td>How hard its own length holds against the span's budget. Default <code>weak</code>.</td></tr>
+    <tr><td><code>earliest</code></td><td>The soonest it may start: a time on the span's clock, or an anchor, as a placement's <code>start</code> takes. The fit never places it sooner, and the children after it are laid out from where it starts, so in a <code>queue</code> they follow it. An anchor with no answer yet holds it unplaced, and under <code>queue</code> or <code>stagger</code> every child after it too; the span fits again once the anchor answers. One already past when it is cued places it there, partway through, as an anchored start already past does, though never ahead of a child already playing; once it has waited a frame it starts no sooner than now; an anchor that answered before the span began is no bound. An anchor on a voice that has left never answers, as for any anchor, so a host that knows the time passes the number. A floor that puts the children past the budget is spilled as any overrun is.</td></tr>
+    <tr><td><code>rank</code></td><td>Where it plays among the children still to start: lower first, ties as cued. Default 0. A child already playing keeps its place at the front, so one cued later with a lower rank goes after it, ahead of the pending children ranked above it.</td></tr>
   </table></div>
   <div class="tbl"><table>
     <tr><th>Strategy</th><th>Does</th></tr>
@@ -851,7 +853,39 @@ phase.result;   <span class="cm">// { budget, length, over, skipped, fell }</spa
     <tr><td><code>pipe(...fits)</code></td><td>Tries each in turn, handing the plan on, until the children fit.</td></tr>
     <tr><td><code>lax({ cap })</code></td><td><code>pipe(condense(), shed(), overrun({ cap }))</code>: every way of giving way, running long only once the rest are spent.</td></tr>
   </table></div>
-  A strategy of the host's own takes the same arguments; <code>layout</code> says where a plan puts each child and how long they take, and <code>plain</code> is the plan before any fit. A child's start and rate are the span's: it takes no <code>start</code> or anchored start, a rate the host writes on its handle lasts until the next fit, and a voice that loops for good or a plain owner is refused. The span fits again when a child joins and when one leaves, and after a seek. Only what is still to come moves: a playing child keeps its place and changes rate without a jump, as a handle's <code>rate</code> write does, and a pending one is placed. A fit sees only the children that have arrived, so late ones are squeezed into what is left. A skipped child lands on its final state at that moment and its <code>end</code> mark is there, but the events its patch would have sent on the way are not sent. A span with a budget stays until the budget has passed, though its children finish sooner, so a late child can still join, and its <code>end</code> mark is wherever its children end or its budget does, whichever is later. A span held by a span is fitted through its own rate. A <code>seek</code> on its spec starts it that far into its budget. <code>span</code> refuses a rate below 0, since a fit lays the children out forward from the span's clock; a span turned back by its handle runs its children back as an owner does. A fit is made on the live mix and logged as the children's control changes, so a read back, a seek and its replay all see it, and the tape records nothing for it. Designed and built 2026-10-07.</li>
+  A strategy of the host's own takes the same arguments; <code>layout</code> says where a plan puts each child and how long they take, and <code>plain</code> is the plan before any fit. A child's start and rate are the span's: it takes no <code>start</code> or anchored start, only an <code>earliest</code>, a rate the host writes on its handle lasts until the next fit, and a voice that loops for good or a plain owner is refused. The span fits again when a child joins and when one leaves, and after a seek. Only what is still to come moves: a playing child keeps its place and changes rate without a jump, as a handle's <code>rate</code> write does, and a pending one is placed. A fit sees only the children that have arrived, so late ones are squeezed into what is left. A skipped child lands on its final state at that moment and its <code>end</code> mark is there, but the events its patch would have sent on the way are not sent. A span with a budget stays until the budget has passed, though its children finish sooner, so a late child can still join, and its <code>end</code> mark is wherever its children end or its budget does, whichever is later. A span held by a span is fitted through its own rate. A <code>seek</code> on its spec starts it that far into its budget. <code>span</code> refuses a rate below 0, since a fit lays the children out forward from the span's clock; a span turned back by its handle runs its children back as an owner does. A fit is made on the live mix and logged as the children's control changes, so a read back, a seek and its replay all see it, and the tape records nothing for it. Designed and built 2026-10-07; <code>earliest</code> and <code>rank</code> built 2026-10-22 for astv's change order, which sorts its changes by line and starts each no sooner than its orb lands:
+<pre><code>const phase = mix.span({ name: 'phase', order: 'queue', duration: 2000 });
+mix.cue({ patch: writeChange(change), owner: phase, rank: change.line,
+          earliest: { of: { name: `orb ${change.id}`, score: 'orbs' }, mark: 'end' } });</code></pre></li>
+  <li id="arcs"><b>Arcs.</b> <code>mix.arc(spec)</code> cues an owner holding an ordered chain of three parts that hand over on its clock: <code>enter</code>, then <code>active</code> for the <code>hold</code>, then <code>exit</code>. It is klieg's <code>fire(text, { enter, active, exit, hold, blendMs })</code> as a blits primitive, with the same part names so the two line up, and it replaces a host adding up starts by hand: bree's marquee runs its program as a span queueing arcs. Built 2026-10-22.
+<pre><code>const word = mix.arc({
+  name: 'JACKPOT',
+  enter: { patch: rise, stagger: byLetter, duration: 600 },   <span class="cm">// a voice's spec, or several layered</span>
+  active: [{ patch: float }, { patch: shimmer }],
+  exit: { patch: scatter },
+  hold: 'open',      <span class="cm">// or ms; default: active's own length</span>
+  blend: 120,        <span class="cm">// a crossfade across each boundary, ms</span>
+});
+mix.cue({ patch: flash, anchor: { start: { of: 'JACKPOT', mark: 'in' } } });
+word.release();      <span class="cm">// klieg's click: the exit plays now</span>
+word.fade({ over: 0 });   <span class="cm">// klieg's abort: gone with no exit; done still resolves</span>
+
+const program = mix.span({ name: 'program', order: 'queue' });
+for (const step of steps) mix.arc({ owner: program, active: stage(step), hold: 4000 });</code></pre>
+  <div class="tbl"><table>
+    <tr><th>Mark</th><th>On an arc</th><th>klieg</th></tr>
+    <tr><td><code>start</code></td><td>The enter begins.</td><td></td></tr>
+    <tr><td><code>in</code></td><td>The enter has ended: the word has landed.</td><td><code>active</code> event</td></tr>
+    <tr><td><code>coast</code></td><td>The hold ends: active's last pass.</td><td></td></tr>
+    <tr><td><code>out</code></td><td>The exit begins: the same time as <code>coast</code>, or where a <code>fade</code> cut it short.</td><td><code>exit</code> event</td></tr>
+    <tr><td><code>end</code></td><td>The exit has ended. The arc leaves, <code>played</code> true, and <code>done</code> resolves.</td><td>promise</td></tr>
+  </table></div>
+  <ul>
+    <li><b>Parts.</b> Each is a voice's spec less what the arc sets (owner, start, anchor, freeze, fade and the span hints), or an array of them layered, lasting as long as the longest. A part lasts its patch's duration times its passes, or its own <code>duration</code>, which a part with a <code>stagger</code> gives so its last subject lands inside it. The arc holds each part's first and last frames through the blends either side, so every voice in it freezes both ways. A part left out leaves its time to the one before it, which holds its last frame there. An <code>enter</code> or <code>exit</code> that loops for good is refused.</li>
+    <li><b>Hold.</b> A number is ms of <code>active</code> on the arc's clock, looping for it unless its <code>loop</code> gives a count. <code>'open'</code> loops until <code>release()</code>, and while open, <code>coast</code>, <code>out</code> and <code>end</code> are unknown: <code>marks</code> leaves them out, anchors on them wait, and <code>book</code> books them once the release fixes them. With no <code>hold</code> the active plays its own length, held open where it loops for good. <code>release()</code> ends the hold so the exit begins half a blend later and the blend starts at the call, klieg's rule; during the enter, the exit follows the enter; on a finite hold it cuts the hold short; once the exit has begun it does nothing. The tape records it, so a seek back plays it again. An arc held open cannot sit in a span, which has to know its length.</li>
+    <li><b>Blend.</b> Each part's weight ramps up over the <code>blend</code> centered on where it starts and down over the one centered on where it ends, as klieg's timeline does, except at the arc's own start and end, where it holds full weight. A hold shorter than the blend overlaps all three ramps, so the arc scales them to sum to 1. The ramp multiplies into each voice's weight beside the owner's own, on lanes and off. Under reduced motion the blend is 0. A part's voices leave once the blend after them is over.</li>
+    <li><b>Not yet.</b> klieg's <code>stages</code>, several holds in one arc, are left for later; a stage list would be more boundaries on the same clock, each with its own hold and release, so nothing here rules it out.</li>
+  </ul></li>
   <li><b>What comes next.</b> <code>mix.marks(from, to)</code> lists every mark the plan has fixed in a range, a voice's five and those placed inside it, with each voice's id, name and tags. One nothing has fixed is left out.</li>
   <li><b>Reading another time.</b> <code>mix.project(t)</code> copies what each subject holds and reads it at <code>t</code>, sending nothing and committing nothing, so the live mix plays on exactly as if it had not been read. Ahead, it plays what is cued forward, stopping at each known event on the way (see <b>Reading ahead at known events</b> below). Behind, it reads from <code>history</code>: the mix keeps every voice's control changes with when they landed, the voices that have left, and a copy of each stateful record per subject every <code>every</code> ms, and a read back restores the nearest copy at or before <code>t</code> and steps forward. A subject it kept nothing for starts from its voice's start with fresh state. Without <code>history</code> a read back works only where how the mix stands now says what it showed then: every voice plays as it was cued and reads by its clock alone, the mix's rate was never set, and <code>t</code> is no earlier than the last cue, <code>drop</code>, <code>touch</code>, <code>announce</code>, or <code>rebase</code>, or the last frame a voice left in; anywhere else it throws and says why. A patch's own <code>clone</code> copies state that <code>structuredClone</code> cannot. With <code>inputs</code>, history also keeps what each input signal on a voice's weight read per subject, and a copy of the host fields patches <code>reads</code>, each time they changed, and a read back uses those instead of asking the signal or the host. Where anchors fixed a voice's start or out after the time read, it reads back as it stood then.</li>
   <li id="seek"><b>Seeking.</b> <code>mix.seek(t)</code> moves the live mix to mix time <code>t</code>, as it stood at the end of that frame, and it plays on from there. It needs <code>history</code> with a <code>tape</code>, and reaches back as far as a read back does. <code>history.tape</code> takes weasel-history's <code>createHistory</code> from <code>@weasel-js/history</code>, or anything of the <code>Tape</code> shape, and the mix records on it every call the host makes on the mix, its handles and its motion patches: cues, weight, rate, seeks and fades, retargets and pushes, the mix's rate, marks, <code>mute</code> and <code>drop</code>, each at the host time it was made, so the frames rate 0 holds at one mix time stay apart. Where it held the clock at <code>t</code> for several frames, a seek or read back to <code>t</code> lands on the last of them; <code>mix.seq</code> numbers the frame being played, higher with each sync and seek, and <code>seek({ frame })</code> and <code>project({ frame })</code> take that number to reach an earlier one. A frame history no longer holds, through age or because an earlier seek went back before it, throws, and one a store paged needs <code>prepare</code> of its mix time first. What history keeps is filed by the frame a change was decided in, so a fade given a time already passed, or a handle seek past a voice's end, comes back with a seek to before the call even though its time is earlier. The tape lives as long as the mix and is never saved.
@@ -994,6 +1028,7 @@ export const mixer: Engine;   <span class="cm">// the one that ships</span></cod
   <li><b>Keyframes as the only form.</b> The platform's shape and wod's. It cannot carry a hash-driven flicker or a permutation walk without an escape hatch that is the procedural form under another name. Both forms are first-class instead.</li>
   <li><b>Adopting a tweening library.</b> GSAP, anime.js and Motion own a property and write absolute values, so concurrent writers conflict. anime.js v4's additive mode is the closest and still has no rest rule per channel. three's <code>AnimationMixer</code> has the right model and is keyframe-only over object property paths.</li>
   <li><b>Subject registration.</b> A <code>mix.subjects(list)</code> call would let the mix step every state eagerly. It puts a second source of truth about the pool in the host. Lazy state keyed by identity, stepped by the gap in the timestamp, needs nothing from the host and is the rule klieg already proved.</li>
+  <li><b>Subject aliases.</b> A <code>subjectOf(obj)</code> option mapping several host objects to one subject, so the fold runs once for all of them: every third bulb of a chase, LEDs sharing one value. What a fold makes depends on the subject wherever a voice reads it &mdash; <code>target</code>, <code>subjects</code>, <code>stagger</code>, a weight signal, <code>at</code> and <code>step</code> &mdash; so only the host knows two objects are interchangeable, and once it knows, it already has the saving: the subject is the logical cell, not the lamp. Probe one subject per cell and paint every lamp in it. In the mix the option would cost a lookup on every probe, need answers for <code>drop</code>, history and a voice's <code>subjects</code> naming one lamp of a group, and silently collapse a voice that staggers by lamp. Decided 2026-10-22.</li>
   <li><b>A slew in place of the band.</b> Smoothing a gate's input instead of giving it two edges. It delays the crossing without deciding it, so an input that rests on the threshold chatters anyway, and the rate needed to help at all costs visible lag.</li>
   <li><b>Normalizing a locus's weights per channel.</b> The other way to make a crossfade hold its value on <code>mul</code>: keep the scale-and-merge fold and pick a per-channel divisor. It costs the property the mixer's fold order rests on &mdash; that weights are scalars resolved for the subject before any channel is touched &mdash; and it has no answer for <code>last</code>, which has no arithmetic to normalize. The <code>lerp</code> fold gets the same result from the rule the package already has.</li>
   <li><b>Removing a frozen voice once another covers it.</b> WAAPI drops a finished, filling animation when a later one replaces every property it sets. In a mix, &ldquo;covers&rdquo; depends on weights, loci and each channel&rsquo;s fold, and a voice leaving on its own would change the pose with no call to point at. The host fades it.</li>
@@ -1029,6 +1064,7 @@ export const mixer: Engine;   <span class="cm">// the one that ships</span></cod
   <li><b>The package name.</b> Published as <code>@msb235/blits</code> for now, decided 2026-09-30, while npm answers a request for the bare <code>blits</code>, which the registry 404s. Moving to <code>blits</code> later changes every import. <code>@lightningjs/blits</code> is a live TV app framework with its own animation plugin, so searches for the name land there first.</li>
   <li><b>Whether <code>at</code> writes into a buffer: no, it returns.</b> A patch allocates one partial delta per subject per frame, and <code>writes</code> plus the fold order would let the mix hand it one scratch object instead. The port measured what that would buy: a frame of klieg&rsquo;s motion — 12 letters through four voices — costs 0.017&nbsp;ms, and a frame of its effects — 60 parts under three effects — costs 0.134&nbsp;ms, against a 16.7&nbsp;ms budget. Under 1% of a frame is not worth the nicest property <code>at</code> has, which is being a pure function a test calls once. The p99 of the effects frame is 1.3&nbsp;ms, which is the collector catching up on exactly these allocations, so a subject count an order of magnitude past klieg&rsquo;s would reopen it. <code>packages/core/test/bench/frame-cost.bench.ts</code> in klieg is the measurement</li>
   <li><b>A subject brought back, read back to while it was out.</b> Under <code>history</code> a voice keeps the record a subject left with, faded out or dropped, and a motion patch keeps its stretches, so a <code>seek</code> or <code>project</code> back to before it left finds both (built 2026-10-07). Untested: a read back to a moment between the subject leaving and a motion's <code>to</code> bringing it back, which may read it as never having left. Found 2026-10-02 while building subject fades.</li>
+  <li><b>Layered subjects.</b> A lamp that is part of a cell and also reached on its own, as a sparkle on one bulb of a chase, is its own subject and folds every voice of the cell again. Starting its fold from the cell's pose and adding only the voices that reach the lamp would save that, and only the mix knows which voices reach what. Unbuilt until a host needs it; the saving matters at thousands of subjects (<code>named N=10000 V=1</code> is 1.592&nbsp;ms a frame on teitou, 2026-10-21). Raised 2026-10-22.</li>
   <li><b>The stock band's width.</b> Whether <code>gate</code>'s default band is symmetric around <code>at</code> and how wide it is. It has to clear the frame noise in a real signal, so it is a measurement from klieg's <code>near</code> and <code>dwell</code>, not a guess.</li>
 </ul>
 </main>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@msb235/blits",
-  "version": "0.11.0",
+  "version": "0.12.1",
   "description": "Concurrent effects: each on its own clock with its own state and weight, folded into one value per subject per frame",
   "keywords": [
     "animation",
@@ -38,6 +38,7 @@
   },
   "files": [
     "dist",
+    "!dist/.tsbuildinfo",
     "docs/schema.html",
     "CHANGELOG.md"
   ],
@@ -46,10 +47,10 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:general": "BLITS_LANES=off vitest run",
-    "typecheck": "tsc -b && tsc -p tsconfig.test.json && tsc -b packages/quarks && tsc -p packages/quarks/tsconfig.test.json && tsc -b packages/tone && tsc -p packages/tone/tsconfig.test.json",
+    "typecheck": "tsc -b && tsc -p tsconfig.test.json && tsc -b packages/quarks && tsc -p packages/quarks/tsconfig.test.json && tsc -b packages/tone && tsc -p packages/tone/tsconfig.test.json && tsc -b packages/panel && tsc -p packages/panel/tsconfig.test.json",
     "lint": "biome check .",
     "check": "npm run lint && npm run typecheck && npm run test",
-    "prepack": "rm -rf dist .tsbuildinfo && npm run build",
+    "prepack": "rm -rf dist && npm run build",
     "prepublishOnly": "npm run check",
     "bench": "npm run build && node bench/frame.mjs",
     "site": "npm run dev -w site",
@@ -62,7 +63,7 @@
   "devDependencies": {
     "@biomejs/biome": "^2.5.8",
     "@types/node": "^26.2.0",
-    "@weasel-js/history": "1.11.0",
+    "@weasel-js/history": "1.12.0",
     "esbuild": "^0.28.2",
     "typescript": "^7.0.2",
     "vitest": "^4.1.10"