@msb235/blits 0.13.0 → 0.15.0

package/dist/cue.js

@@ -1,5 +1,6 @@
 import { blendOf } from './blend.js';
 import { checkHits } from './book.js';
+import { bind, checkWithin } from './bound.js';
 import { changed } from './chain.js';
 import { copyable } from './clone.js';
 import { schedule } from './due.js';
@@ -15,10 +16,11 @@ import { enlist } from './roster.js';
 import { scoredAdd } from './scored.js';
 import { checkChild, refit } from './spans.js';
 import { cuedById, motionOwner } from './strays.js';
-import { record, unplayable } from './tape.js';
+import { record, taping, unplayable } from './tape.js';
 import { Voice } from './voice.js';
+import { warnOnce } from './warn.js';
 export function cue(mix, given) {
-    const spec = locusOf(mix, given);
+    const spec = roleOf(mix, given);
     const patch = spec.patch;
     playable(mix, spec);
     if (spec.from === 'current' && patch.form !== 'keys')
@@ -33,6 +35,7 @@ export function cue(mix, given) {
         checkHits(spec.hits, patch.duration);
     if (spec.marks !== undefined)
         checkMarks(spec.marks, patch.duration);
+    checkWithin(mix, spec);
     const anchored = anchor !== undefined && (anchor.start !== undefined || anchor.in !== undefined);
     // A voice an owner holds is placed on the owner's clock: ms from when it starts.
     const local = owner === null ? mix.now : ownerReading(owner, mix.now);
@@ -44,7 +47,10 @@ export function cue(mix, given) {
                 ? mixAt(mix, spec.start - mix.offset)
                 : Number.isNaN(mix.now)
                     ? 0
-                    : mix.now;
+                    : // A loop asleep on an inert mix syncs next when it wakes, which is the cue's "now".
+                        mix.asleep
+                            ? Number.POSITIVE_INFINITY
+                            : mix.now;
     const voice = new Voice(mix.nextId++, spec, patch, spec.fade ?? noFade, local, start, mix.slotOf, mix.channels, mix.opts.host, mix.send, owner);
     if (patch === ownerPatch && mix.fitting !== null)
         voice.fitting = mix.fitting;
@@ -56,10 +62,16 @@ export function cue(mix, given) {
         checkChild(spec, voice);
     if (mix.pace !== null && owner === null && spec.start !== undefined && voice.state === 'pending')
         voice.pinned = spec.start - mix.offset;
+    if (start === Number.POSITIVE_INFINITY && !anchored && !owner?.fitting) {
+        voice.waking = true;
+        mix.waking = true;
+    }
+    bind(mix, voice);
     enter(mix, voice);
     const h = handle(mix, voice);
     voice.handle = h;
-    recordCue(mix, h);
+    if (taping(mix))
+        recordCue(mix, h);
     return h;
 }
 const noFade = Object.freeze({});
@@ -89,21 +101,42 @@ export function fitsKit(patch, kit) {
             throw new Error(`blits: channel ${String(channel)} is ${here.kind ?? 'a custom channel'} in this kit, but the patch was written for ${wanted.kind ?? 'a custom channel'}`);
     }
 }
-/** The spec with its `locus` set from a tag the mix declares one, where it carries one. */
-function locusOf(mix, spec) {
-    const loci = mix.opts.loci;
+/**
+ * The spec with its `role` set from `locus`, the name `role` had before, or from a tag the mix
+ * declares a role, where it carries one.
+ */
+export function roleOf(mix, given) {
+    let spec = given;
+    if (spec.locus !== undefined) {
+        if (spec.role !== undefined && spec.role !== spec.locus)
+            throw new Error(`blits: a voice plays one role, not both role ${spec.role} and locus ${spec.locus}; locus is role's old name`);
+        warnOnce(mix, 'locus is renamed role; cue the voice with role');
+        const { locus, ...rest } = spec;
+        spec = { ...rest, role: locus };
+    }
+    const roles = mix.roleTags;
     const tags = spec.tags;
-    if (loci === undefined || tags === undefined)
+    if (roles === undefined || tags === undefined)
         return spec;
-    let locus = spec.locus;
+    let role = spec.role;
     for (const tag of tags) {
-        if (!loci.includes(tag) || tag === locus)
+        if (!roles.includes(tag) || tag === role)
             continue;
-        if (locus !== undefined)
-            throw new Error(`blits: a voice folds in one locus, not both ${locus} and ${tag}`);
-        locus = tag;
+        if (role !== undefined)
+            throw new Error(`blits: a voice plays one role, not both ${role} and ${tag}`);
+        role = tag;
     }
-    return locus === spec.locus ? spec : { ...spec, locus };
+    return role === spec.role ? spec : { ...spec, role };
+}
+/** The tags `opts` declares roles, from `roles` or `loci`, the name `roles` had before. */
+export function roleTags(opts) {
+    const { roles, loci } = opts;
+    if (loci === undefined)
+        return roles;
+    if (roles !== undefined && (roles.length !== loci.length || roles.some((r, i) => r !== loci[i])))
+        throw new Error("blits: a mix takes roles or loci, not both; loci is roles' old name");
+    warnOnce(opts, 'the mix option loci is renamed roles; make the mix with roles');
+    return loci;
 }
 /** Refuses a spec whose patch the mix cannot play, or whose state its history cannot keep. */
 export function playable(mix, spec) {

package/dist/cut.d.ts

@@ -0,0 +1,8 @@
+/** Where history is cut for a seek or read: what frame `seq` made, and before it, is kept. */
+export interface Cut {
+    seq: number;
+    /** For a read of what a frame showed: of that frame's own changes, only those made before it was read. */
+    strict: boolean;
+}
+/** Whether a change made in frame `seq` falls inside `cut`; `early` for one made before the frame was read. */
+export declare function within(cut: Cut, seq: number, early?: boolean): boolean;

package/dist/cut.js

@@ -0,0 +1,4 @@
+/** Whether a change made in frame `seq` falls inside `cut`; `early` for one made before the frame was read. */
+export function within(cut, seq, early = false) {
+    return seq < cut.seq || (seq === cut.seq && (!cut.strict || early));
+}

package/dist/drop.d.ts

@@ -0,0 +1,9 @@
+import { releasing } from './history.js';
+import type { Mixer } from './mixer.js';
+import type { Motions } from './motions.js';
+import type { Voice } from './voice.js';
+export declare function drop<I, O>(this: Mixer<I, O>, subject: I): void;
+/** Lets `voice` go of a dropped subject. Methods rather than closures, so a drop makes neither. */
+export declare function forgetIn<I, O>(this: Mixer<I, O>, voice: Voice<I, O>, subject: I, kept: ReturnType<typeof releasing>): void;
+export declare function releaseIn<I, O>(this: Mixer<I, O>, motion: Motions<I>, subject: I, kept: ReturnType<typeof releasing>): void;
+export declare function recordDrop<I, O>(this: Mixer<I, O>, subject: I): void;

package/dist/drop.js

@@ -0,0 +1,84 @@
+import { headOf, unlink } from './chain.js';
+import { leaveVoice } from './fade.js';
+import { goneIndex } from './gone.js';
+import { releasing } from './history.js';
+import { nextFrame } from './move.js';
+import { Masked } from './store.js';
+import { record, taping, unplayable } from './tape.js';
+export function drop(subject) {
+    this.frame = nextFrame();
+    const head = headOf(this, subject);
+    // Nothing that kept this head, such as `pull`'s remembered list, may take it as current again.
+    if (head !== undefined)
+        unlink(this, head);
+    // A number a seek carried over is released even where its chain is not linked since.
+    const slot = this.chains.get(subject)?.slot ?? -1;
+    if (slot >= 0 && this.lanes !== null)
+        this.lanes.release(slot);
+    // A read ahead's copy reads the live mix's poses, and so hides one where the mix deletes it.
+    if (this.projecting && !(this.lastPoses instanceof Masked))
+        this.lastPoses = new Masked(this.lastPoses);
+    if (!this.projecting)
+        this.places?.drop(subject);
+    this.lastPoses.delete(subject);
+    this.restStamps?.delete(subject);
+    this.chains.delete(subject);
+    this.stir();
+    // 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 kept = releasing(this);
+    for (const voice of this.general)
+        this.forgetIn(voice, subject, kept);
+    const named = this.named.get(subject);
+    if (named !== undefined)
+        for (const voice of [...named])
+            this.forgetIn(voice, subject, kept);
+    const gone = goneIndex(this);
+    for (const voice of gone.general)
+        this.forgetIn(voice, subject, kept);
+    const goneNaming = gone.named.get(subject);
+    if (goneNaming !== undefined)
+        for (const voice of goneNaming)
+            this.forgetIn(voice, subject, kept);
+    if (this.owners !== null)
+        for (const voice of this.owners)
+            this.forgetIn(voice, subject, kept);
+    for (const voice of this.parters) {
+        this.forgetIn(voice, subject, kept);
+        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)
+            this.releaseIn(motion, subject, kept);
+    this.strays.delete(subject);
+    for (const motion of this.strayAll)
+        this.releaseIn(motion, subject, kept);
+    if (taping(this))
+        this.recordDrop(subject);
+}
+/** Lets `voice` go of a dropped subject. Methods rather than closures, so a drop makes neither. */
+export function forgetIn(voice, subject, kept) {
+    leaveVoice(this, voice, subject);
+    voice.subjects.delete(subject);
+    if (voice.motion !== undefined)
+        this.releaseIn(voice.motion, subject, kept);
+    voice.parts?.delete(subject);
+    voice.parted?.delete(subject);
+    voice.blend?.of.reads.delete(subject);
+}
+// A motion patch's state is the live mix's alone: a read ahead cannot start a subject afresh in it.
+export function releaseIn(motion, subject, kept) {
+    if (!this.projecting)
+        motion.release(subject, kept[0], kept[1], kept[2], kept[3]);
+    else if (motion.holds(subject))
+        unplayable('a drop of a subject a motion patch holds');
+}
+export function recordDrop(subject) {
+    record(this, 'drop', (stage) => stage.mix(this)?.drop(subject));
+}

package/dist/due.d.ts

@@ -1,10 +1,29 @@
 import type { Mixer } from './mixer.js';
 import type { Voice } from './voice.js';
-/** One entry in a mix's due queue; stale once its voice has been scheduled again. */
-export interface Due<I, O> {
-    at: number;
-    voice: Voice<I, O>;
-    token: number;
+/**
+ * Live voices by the earliest mix time `moveTo` would change each, a binary heap. The times sit in
+ * one flat array, so a sift reads no voice: at 40,000 voices a stop's sift to the top missed the
+ * cache at each of its levels. An entry is stale once its voice has been scheduled again.
+ */
+export declare class DueQueue<I, O> {
+    size: number;
+    private at;
+    private tokens;
+    private voices;
+    /** The size past which stale entries are pruned, so a voice rescheduled often cannot grow it. */
+    private limit;
+    push(at: number, voice: Voice<I, O>, token: number): void;
+    /** The earliest entry's time, Infinity while empty. */
+    first(): number;
+    /** Takes off the earliest entry, giving its voice where it is current and undefined where stale. */
+    pop(): Voice<I, O> | undefined;
+    clear(): void;
+    private move;
+    /** Puts an entry in the hole at `i` and sifts it down to where it belongs. */
+    private sink;
+    private grow;
+    /** Drops the entries made stale by a later one and heapifies what is left. */
+    private prune;
 }
 /** Files a voice in the due queue at its current due, replacing any entry it had. */
 export declare function schedule<I, O>(mix: Mixer<I, O>, voice: Voice<I, O>): void;

package/dist/due.js

@@ -1,3 +1,108 @@
+/**
+ * Live voices by the earliest mix time `moveTo` would change each, a binary heap. The times sit in
+ * one flat array, so a sift reads no voice: at 40,000 voices a stop's sift to the top missed the
+ * cache at each of its levels. An entry is stale once its voice has been scheduled again.
+ */
+export class DueQueue {
+    size = 0;
+    at = new Float64Array(64);
+    tokens = new Float64Array(64);
+    voices = [];
+    /** The size past which stale entries are pruned, so a voice rescheduled often cannot grow it. */
+    limit = 64;
+    push(at, voice, token) {
+        if (this.size >= this.limit)
+            this.prune();
+        if (this.size === this.at.length)
+            this.grow();
+        const ats = this.at;
+        let i = this.size++;
+        while (i > 0) {
+            const up = (i - 1) >> 1;
+            if (ats[up] <= at)
+                break;
+            this.move(up, i);
+            i = up;
+        }
+        ats[i] = at;
+        this.tokens[i] = token;
+        this.voices[i] = voice;
+    }
+    /** The earliest entry's time, Infinity while empty. */
+    first() {
+        return this.size > 0 ? this.at[0] : Number.POSITIVE_INFINITY;
+    }
+    /** Takes off the earliest entry, giving its voice where it is current and undefined where stale. */
+    pop() {
+        const voice = this.voices[0];
+        const token = this.tokens[0];
+        const last = --this.size;
+        if (last > 0)
+            this.sink(0, this.at[last], this.tokens[last], this.voices[last]);
+        this.voices[last] = undefined;
+        return token === voice.dueToken && voice.state !== 'done' ? voice : undefined;
+    }
+    clear() {
+        this.size = 0;
+        this.voices = [];
+        this.limit = 64;
+    }
+    move(from, to) {
+        this.at[to] = this.at[from];
+        this.tokens[to] = this.tokens[from];
+        this.voices[to] = this.voices[from];
+    }
+    /** Puts an entry in the hole at `i` and sifts it down to where it belongs. */
+    sink(i, at, token, voice) {
+        const ats = this.at;
+        const n = this.size;
+        for (;;) {
+            const l = 2 * i + 1;
+            const r = l + 1;
+            let m = i;
+            let least = at;
+            if (l < n && ats[l] < least) {
+                m = l;
+                least = ats[l];
+            }
+            if (r < n && ats[r] < least)
+                m = r;
+            if (m === i)
+                break;
+            this.move(m, i);
+            i = m;
+        }
+        ats[i] = at;
+        this.tokens[i] = token;
+        this.voices[i] = voice;
+    }
+    grow() {
+        const at = new Float64Array(this.at.length * 2);
+        at.set(this.at);
+        this.at = at;
+        const tokens = new Float64Array(this.tokens.length * 2);
+        tokens.set(this.tokens);
+        this.tokens = tokens;
+    }
+    /** Drops the entries made stale by a later one and heapifies what is left. */
+    prune() {
+        let n = 0;
+        for (let k = 0; k < this.size; k++) {
+            const voice = this.voices[k];
+            if (this.tokens[k] !== voice.dueToken)
+                continue;
+            if (n !== k)
+                this.move(k, n);
+            n++;
+        }
+        for (let k = n; k < this.size; k++)
+            this.voices[k] = undefined;
+        this.size = n;
+        for (let k = (n >> 1) - 1; k >= 0; k--)
+            this.sink(k, this.at[k], this.tokens[k], this.voices[k]);
+        this.limit = Math.max(64, 2 * n);
+    }
+}
 /**
  * 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
@@ -59,43 +164,18 @@ export function schedule(mix, voice) {
     const due = dueOf(mix, voice);
     if (due === Number.POSITIVE_INFINITY)
         return;
-    const heap = mix.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;
-    }
+    mix.due.push(Number.isNaN(due) ? Number.NEGATIVE_INFINITY : due, voice, token);
 }
 /** Takes every current entry due by `now` off the queue, in cue order. */
 export function popDue(mix, now) {
-    const heap = mix.due;
-    const at = (k) => k < heap.length ? heap[k].at : Number.POSITIVE_INFINITY;
+    const queue = mix.due;
     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);
-        }
+    while (queue.first() <= now) {
+        const voice = queue.pop();
+        if (voice === undefined)
+            continue;
+        voice.dueToken++;
+        out.push(voice);
     }
     return byId(out);
 }

package/dist/easing.d.ts

@@ -1,6 +1,6 @@
 import type { Easing } from './types.js';
 /**
- * A curve on 0..1: the function an easing stands for.
+ * The function an easing stands for, a curve on 0..1.
  *
  * @category patch
  */
@@ -11,9 +11,9 @@ export type Curve = (u: number) => number;
  */
 export declare function startSlope(c: Curve): number;
 /**
- * The function an easing names: a CSS name, a `bezier` or `steps`, or a function, which comes back
- * as it is. Call it once where a curve is built, not per frame; the same name or easing object
- * gives the same function each time.
+ * The function an easing names. The easing is a CSS name, a `bezier` or `steps`, or a function,
+ * which comes back as it is. Call it once where a curve is built, not per frame; the same name or
+ * easing object gives the same function each time.
  *
  * @category patch
  */

package/dist/easing.js

@@ -72,9 +72,9 @@ export function startSlope(c) {
     return v > 1e-3 ? Number.POSITIVE_INFINITY : v / h;
 }
 /**
- * The function an easing names: a CSS name, a `bezier` or `steps`, or a function, which comes back
- * as it is. Call it once where a curve is built, not per frame; the same name or easing object
- * gives the same function each time.
+ * The function an easing names. The easing is a CSS name, a `bezier` or `steps`, or a function,
+ * which comes back as it is. Call it once where a curve is built, not per frame; the same name or
+ * easing object gives the same function each time.
  *
  * @category patch
  */

package/dist/everyone.d.ts

@@ -1,5 +1,6 @@
 import type { Mixer } from './mixer.js';
-import type { Subject, Voice } from './voice.js';
+import type { Subject } from './subject.js';
+import type { Voice } from './voice.js';
 /**
  * Whether a voice can keep one record for every subject, decided when it is cued. A record holds
  * what a voice knows of one subject; where the voice is over every subject with no stagger, keeps
@@ -60,7 +61,7 @@ export declare function unsight<I, O>(voice: Voice<I, O>, slot: number): void;
  */
 export declare function unshare<I, O>(mix: Mixer<I, O>, voice: Voice<I, O>, kept?: boolean, keeper?: I): void;
 /**
- * Counts what makes a mix's fold more than a walk of each chain: a locus, a voice sharing one
+ * Counts what makes a mix's fold more than a walk of each chain: a role, a voice sharing one
  * record, a voice that stopped sharing this frame. Called wherever one of the three changes, so
  * `foldWith` asks one number.
  */

package/dist/everyone.js

@@ -22,7 +22,7 @@ export function shares(mix, voice) {
         voice.named === null &&
         spec.target === undefined &&
         spec.stagger === undefined &&
-        spec.locus === undefined &&
+        spec.role === undefined &&
         spec.anchor === undefined &&
         spec.from !== 'current' &&
         typeof spec.weight !== 'function' &&
@@ -234,12 +234,12 @@ export function unshare(mix, voice, kept = false, keeper) {
     mix.lanes?.refill();
 }
 /**
- * Counts what makes a mix's fold more than a walk of each chain: a locus, a voice sharing one
+ * Counts what makes a mix's fold more than a walk of each chain: a role, a voice sharing one
  * record, a voice that stopped sharing this frame. Called wherever one of the three changes, so
  * `foldWith` asks one number.
  */
 export function detour(mix) {
-    mix.detours = mix.loci + mix.sharers.length + (mix.unshared ? 1 : 0);
+    mix.detours = mix.roleVoices + mix.sharers.length + (mix.unshared ? 1 : 0);
 }
 /** Gives a record just made for a subject a sharing voice had seen what the voice kept for it. */
 export function inherit(voice, held, slot) {

package/dist/fade.d.ts

@@ -1,5 +1,6 @@
 import type { Mixer } from './mixer.js';
-import type { Left, Parted, Parting, Voice } from './voice.js';
+import type { Left, Parted, Parting } from './subject.js';
+import type { Voice } from './voice.js';
 /** Starts one subject's ramp out of a voice, or takes it out at once for a ramp of 0. */
 export declare function fadeSubject<I, O>(mix: Mixer<I, O>, voice: Voice<I, O>, subject: I, over?: number): void;
 /** What a subject's own ramp out of a voice leaves of its weight this frame, 0..1. */

package/dist/fade.js

@@ -6,6 +6,7 @@ import { leave, noted, releasing } from './history.js';
 import { markOf } from './marks.js';
 import { orphan, ownerReading } from './owner.js';
 import { startOf } from './place.js';
+import { isRested } from './record.js';
 import { scoreTouched } from './scored.js';
 import { lingers, refit } from './spans.js';
 import { unreach } from './unreached.js';
@@ -111,7 +112,7 @@ function forgetIn(mix, voice, subject) {
         voice.subjects.delete(subject);
         if (held.reaches)
             voice.seen--;
-        if (held.rested)
+        if (isRested(held))
             voice.restedCount--;
         if (voice.holder === held)
             voice.holder = null;

package/dist/fill.d.ts

@@ -2,7 +2,8 @@ import { type Lane, type Laned, type Paced } from './lane.js';
 import type { Lanes } from './lanes.js';
 import { absent } from './numbers.js';
 import { type Scratch } from './patch.js';
-import type { Subject, Voice } from './voice.js';
+import type { Subject } from './subject.js';
+import type { Voice } from './voice.js';
 export declare function fillAll<I, O>(lanes: Lanes<I, O>, now: number, version: number): void;
 /** Leaves a lane's subjects to the general path until it wakes, keeping what `weightOf` reports. */
 export declare function rest<I, O>(lanes: Lanes<I, O>, lane: Paced): void;
@@ -31,7 +32,7 @@ export declare function runEveryone<I, O>(this: Lanes<I, O>, lane: Lane<I, O>):
 /**
  * One subject's contribution from a lane's voice. True where the voice gave the subject a delta,
  * as the general path's `contribution` does where it returns one, which is what makes a voice in a
- * locus one of its members for the subject.
+ * role one of its members for the subject.
  */
 export declare function one<I, O>(this: Lanes<I, O>, lane: Lane<I, O>, p: number, slot: number): boolean;
 /**