@msb235/blits 0.10.0 → 0.12.0

package/dist/voice.js

@@ -6,6 +6,7 @@ import { childPlayed, Holding, mixTime, ownedElapsed, ownerPatch, ownerReading,
 import { builtOf, intosOf } from './patch.js';
 import { reading } from './reading.js';
 import { Store } from './store.js';
+import { warnOnce } from './warn.js';
 export const none = Object.freeze([]);
 /**
  * A voice's `setting.keep`, one per voice: a setting is valid only during its call, so the state
@@ -62,19 +63,26 @@ class VoiceSetting {
 /** A store that fills a missing entry from `make` on first ask. */
 class Filled extends Store {
     make;
+    /** Keys deleted here, which are made afresh by whoever asks and never again by `make`. */
+    gone = null;
     constructor(make) {
         super();
         this.make = make;
     }
     get(key) {
         let v = super.get(key);
-        if (v === undefined) {
+        if (v === undefined && this.gone?.get(key) !== true) {
             v = this.make(key);
             if (v !== undefined)
                 super.set(key, v);
         }
         return v;
     }
+    delete(key) {
+        super.delete(key);
+        this.gone ??= new Store();
+        this.gone.set(key, true);
+    }
 }
 const noSend = () => { };
 export class Voice {
@@ -135,11 +143,16 @@ export class Voice {
     rebuilds = 0;
     /** Whether its span's last fit jumped it to its end, which leaves it no time in that fit. */
     skipped = false;
+    /** What its `earliest` answered at its span's last fit, span ms; NaN while unknown or absent. */
+    floorSeen = Number.NaN;
     /** Whether its patch has kept state on a record through `setting.keep`, which makes it stateful. */
     keeping = false;
     /** 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 and frame each left at; null while none have. */
+    /**
+     * Subjects faded out of this voice, by the mix time and frame each left at, and the ramp that
+     * took it out, which a seek or a read back into it puts back; null while none have.
+     */
     parted = null;
     /**
      * Under history, the records of subjects that left this voice, by the mix time and frame each
@@ -165,6 +178,8 @@ export class Voice {
     freezesAfter;
     /** The mix time it first showed: when it was cued, or the first sync after. */
     opened = Number.NaN;
+    /** Whether no delta its patch's `at` returned has been checked against `writes` yet. */
+    unchecked = true;
     /** Which of its entries in the mix's due queue is current; older ones are skipped when popped. */
     dueToken = 0;
     /**
@@ -183,6 +198,8 @@ export class Voice {
     /** The least stagger of any subject seen, 0 or below, which a voice running back ends at. */
     soonest = 0;
     restedCount = 0;
+    /** Whether a seek back to before its cue has it out of the mix, until the mix plays the cue again. */
+    parked = false;
     /** The mix time it was cued at; -Infinity before the first sync. */
     cuedAt = Number.NEGATIVE_INFINITY;
     /** The frame it was cued in. */
@@ -221,12 +238,19 @@ export class Voice {
     ownKept = null;
     /** The blend it is a member of, and which. */
     blend = null;
+    /**
+     * Copies the latest seek back cut from its records' lists that no other list holds, for the
+     * copies its probes keep next to be written over; null until a seek cuts one.
+     */
+    spares = null;
     /** The one record of every subject it does not reach. */
     unreached = null;
     /** By subject number, a bit set where `unreached` stands for the subject; null until one is. */
     unreachedBits = null;
     /** Whether one record stands for every subject: see `shares` in `everyone.ts`. */
     sharing = false;
+    /** The frames it has played sharing it. */
+    shared = 0;
     /** That record, null until a chain first asks and once the voice shares no more. */
     everyone = null;
     /** While sharing, by subject number: a bit where a chain has asked about the subject. */
@@ -247,6 +271,12 @@ export class Voice {
     holding;
     /** For a span, its budget and how its children were last fitted; null for any other voice. */
     fitting = null;
+    /** For an arc, how its parts are laid out; null for any other voice. */
+    arc = null;
+    /** For an arc, how long its hold lasts, ms on its clock: Infinity while open. */
+    hold = 0;
+    /** For a voice an arc holds, which part it plays: 0 enter, 1 active, 2 exit; -1 for any other. */
+    part = -1;
     /**
      * `done` and `played`, made when first asked for, already settled if the voice is: most hosts
      * never await either, and a mix may hold tens of thousands of voices.
@@ -350,6 +380,7 @@ export class Voice {
         this.outOver = c.outOver;
         this.outSet = c.outSet;
         this.rebuilds = c.rebuilds;
+        this.hold = c.hold;
         const clocks = this.clocks;
         if (clocks !== null && clocks.length !== c.past)
             this.clocks = c.past === 0 ? null : clocks.slice(0, c.past);
@@ -362,6 +393,7 @@ export class Voice {
     park() {
         this.reopen(Number.NEGATIVE_INFINITY);
         this.take(this.first);
+        this.parked = true;
         this.log = null;
         this.state = 'pending';
         this.subjects = new Store();
@@ -529,9 +561,20 @@ export class Voice {
     get holdsFirst() {
         return this.freezesBefore || this.out?.back === true;
     }
+    /**
+     * Whether a subject past the end of its passes shows nothing: its clock runs back, so it has yet
+     * to reach them, and it does not freeze after.
+     */
+    get hidesPast() {
+        return !this.freezesAfter && this.backs !== (this.owner !== null && turnedBack(this));
+    }
     /** A subject's voice time at `raw` once the voice's freezes apply; NaN where it shows nothing. */
     shownAt(raw) {
-        return this.beginless ? raw : frozenTime(raw, this.holdsFirst, this.freezesAfter, this.span);
+        if (this.beginless)
+            return raw;
+        if (raw > this.span && this.hidesPast)
+            return Number.NaN;
+        return frozenTime(raw, this.holdsFirst, this.freezesAfter, this.span);
     }
     /** Records this voice's controls as they stand, from mix time `at` in frame `seq`. */
     note(at, seq, sync = false) {
@@ -551,6 +594,7 @@ export class Voice {
             outOver: this.outOver,
             outSet: this.outSet,
             rebuilds: this.rebuilds,
+            hold: this.hold,
             past: this.clocks?.length ?? 0,
         });
     }
@@ -600,3 +644,16 @@ export class Voice {
         rebaseWith(this, now);
     }
 }
+/**
+ * Warns, once a patch outside production, of a key the first delta `voice` read returns outside its
+ * patch's `writes`, which the mix drops.
+ */
+export function checkWrites(voice, delta) {
+    voice.unchecked = false;
+    if (delta === null || typeof delta !== 'object')
+        return;
+    const writes = voice.patch.writes;
+    for (const key in delta)
+        if (!writes.includes(key))
+            warnOnce(voice.patch, `${voice.spec.name ?? `voice ${voice.id}`}'s patch returns ${key} from at(), which is not in its writes, so the mix drops it`);
+}

package/dist/watch.d.ts

@@ -0,0 +1,26 @@
+import type { Mixer } from './mixer.js';
+import type { MixOptions, Registry } from './types.js';
+type Any = Mixer<unknown, unknown>;
+/**
+ * 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 declare function watched(): Registry;
+/**
+ * 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 declare function historyFor(opts: {
+    history?: MixOptions['history'];
+    transport?: unknown;
+}): {
+    history: MixOptions['history'];
+    added: boolean;
+};
+/** Marks a transport whose history the registry's default gave. */
+export declare function gave(transport: object): void;
+/** Lists a mix the host made, under an entry this copy builds. */
+export declare function register(mix: Any): void;
+export {};

package/dist/watch.js

@@ -0,0 +1,441 @@
+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);
+    for (const fn of [...r.fns])
+        fn({ kind: 'add', entry });
+}
+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;
+        own.untap();
+        taps.delete(m);
+        ctlOf(m.transport).tapped--;
+        fit(m.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();
+        },
+    };
+    fit(t);
+    t.woke();
+    const live = () => {
+        if (freed)
+            throw new Error('blits: that hold was freed');
+    };
+    return {
+        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();
+            }
+        },
+    };
+}

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;