@msb235/blits 0.14.0 → 0.15.1

package/dist/numbers.js

@@ -66,6 +66,10 @@ export class Numbers {
             this.release(dead);
         return slot;
     }
+    /** Whether `slot` is a number in use, its subject perhaps collected and not yet released. */
+    has(slot) {
+        return this.refs[slot] !== undefined;
+    }
     subject(slot) {
         const ref = this.refs[slot];
         if (ref === undefined)
@@ -78,6 +82,35 @@ export class Numbers {
         }
         return ref;
     }
+    /**
+     * Hands the subject numbered `from` the free number `to`, and frees `from` without telling the
+     * owner, whose stores the caller moves; false, changing nothing, where either does not hold.
+     */
+    move(from, to) {
+        const ref = this.refs[from];
+        const free = this.free;
+        if (ref === undefined || to >= this.next || this.refs[to] !== undefined || free === null)
+            return false;
+        const at = free.lastIndexOf(to);
+        if (at < 0)
+            return false;
+        if (ref instanceof WeakRef) {
+            const subject = ref.deref();
+            if (subject === undefined)
+                return false;
+            if (ref === this.lone)
+                this.loneSlot = to;
+            else if (this.registry !== null) {
+                this.registry.unregister(ref);
+                this.registry.register(subject, to, ref);
+            }
+        }
+        free.splice(at, 1);
+        free.push(from);
+        this.refs[to] = ref;
+        this.refs[from] = undefined;
+        return true;
+    }
     release(slot) {
         const ref = this.refs[slot];
         if (ref === undefined)

package/dist/owed.d.ts

@@ -13,6 +13,8 @@ export declare class Owed {
     begin(fill: number): void;
     /** Makes room for subject numbers below `cap`. */
     grow(cap: number): void;
+    /** Whether any subject owes a laned voice this fill. */
+    any(): boolean;
     /** Whether the subject at `slot` owes some laned voice this fill. */
     owes(slot: number): boolean;
     /** Whether the subject at `slot` owes voice `id` this fill. */

package/dist/owed.js

@@ -23,6 +23,10 @@ export class Owed {
         at.set(this.at);
         this.at = at;
     }
+    /** Whether any subject owes a laned voice this fill. */
+    any() {
+        return this.lists.length > 0;
+    }
     /** Whether the subject at `slot` owes some laned voice this fill. */
     owes(slot) {
         return this.lists.length > 0 && this.fill[slot] === this.now;

package/dist/pack.d.ts

@@ -1,4 +1,5 @@
-import type { Subject, Voice } from './voice.js';
+import type { Subject } from './subject.js';
+import type { Voice } from './voice.js';
 /** A subject's record as plain data, for a history store. */
 export interface PackedRecord {
     reaches: boolean;

package/dist/pack.js

@@ -1,5 +1,5 @@
 import { clone } from './clone.js';
-import { record } from './record.js';
+import { isRested, record } from './record.js';
 /** A voice's record of one subject as plain data, its patch's `pack` taking its state. */
 export function packHeld(voice, h) {
     const patch = voice.patch;
@@ -10,7 +10,7 @@ export function packHeld(voice, h) {
         since: h.since,
         shown: h.shown,
         weight: h.weight,
-        rested: h.rested,
+        rested: isRested(h),
         restedAt: h.restedAt,
         bands: h.bands === null ? null : Array.from(h.bands),
         state: h.state === undefined ? undefined : patch.pack ? patch.pack(h.state) : clone(h.state),
@@ -40,7 +40,6 @@ export function unpackHeld(voice, p) {
     h.since = p.since;
     h.shown = p.shown;
     h.weight = p.weight;
-    h.rested = p.rested;
     h.restedAt = p.restedAt;
     h.bands = bands;
     h.stepped = p.stepped;

package/dist/patch.d.ts

@@ -15,12 +15,14 @@ export interface PatchOptions<I, O, S, H = unknown> {
     reads?: readonly string[];
     state?(subject: I): S;
     step?(state: S, dt: number, subject: I, setting: Setting<S, H>): void;
-    /** `state` as plain data and back, for a history store: see `Patch.pack`. */
+    /** `state` as plain data and back, for a history store. See `Patch.pack`. */
     pack?(state: S): unknown;
     unpack?(data: unknown): S;
 }
 /**
- * The procedural form. Flicker, roving, a hash walk, a starter strike.
+ * A patch whose function computes its output from phase, subject and setting each frame.
+ *
+ * The procedural form, for flicker, roving, a hash walk, a starter strike.
  *
  * @category patch
  */
@@ -137,7 +139,9 @@ export declare function builtOf<I, O, S>(p: Patch<I, O, S>): Built;
 /** Evaluates a stop list into a fresh delta. */
 export declare function evalKeys<O>(stops: readonly Keyframe<O>[], writes: readonly (keyof O)[], phase: number, duration: number, opts: KeysOptions<O>, base?: Partial<O>): Partial<O>;
 /**
- * The declarative form. klieg's transition sugar and wod's keyframes.
+ * A patch that interpolates between keyframes over its duration.
+ *
+ * The declarative form, as klieg's transition sugar and wod's keyframes use.
  *
  * @category patch
  */

package/dist/patch.js

@@ -1,7 +1,9 @@
 import { lerpInto, lerpNumber } from './channels.js';
 import { curve, startSlope } from './easing.js';
 /**
- * The procedural form. Flicker, roving, a hash walk, a starter strike.
+ * A patch whose function computes its output from phase, subject and setting each frame.
+ *
+ * The procedural form, for flicker, roving, a hash walk, a starter strike.
  *
  * @category patch
  */
@@ -326,7 +328,9 @@ export function evalKeys(stops, writes, phase, duration, opts, base) {
     return readKeys(build(stops, writes, duration, opts), phase, {}, base);
 }
 /**
- * The declarative form. klieg's transition sugar and wod's keyframes.
+ * A patch that interpolates between keyframes over its duration.
+ *
+ * The declarative form, as klieg's transition sugar and wod's keyframes use.
  *
  * @category patch
  */

package/dist/places.d.ts

@@ -0,0 +1,53 @@
+import { Grid } from './grid.js';
+import { Store } from './store.js';
+/**
+ * The index the host gives each subject, by `place` or by its place in the list `plot` was given,
+ * and where the host says each one is, over `Grid`. Subjects are held as the rest of the mix holds
+ * them: an object weakly, anything else until `drop`. An index a subject leaves, by `drop` or by
+ * being collected, is handed out again.
+ */
+export declare class Places<I> extends Grid {
+    private readonly slotOf;
+    private readonly keepRefs;
+    /** By subject, its index. */
+    at: Store<I, number>;
+    /** By index, its subject's lane number, -1 for one with none or a subject let go. */
+    slots: Int32Array<ArrayBuffer>;
+    /** By lane number, the index it was put in `slots` at, -1 for none. */
+    placeOf: Int32Array<ArrayBuffer>;
+    /** Outside production, by index, its subject, for the check that a bound does not clip a signal. */
+    refs: (WeakRef<object> | I | undefined)[] | null;
+    /** While a bounded fill reads the subject at an index, that index, so `around` need not look it up; else -1. */
+    cur: number;
+    /** Indices a subject left, for `place` to hand out again. */
+    free: number[];
+    /** Whether `xy` is the mix's own, grown as `place` hands out indices, rather than the array `plot` was given. */
+    owned: boolean;
+    /**
+     * By index, the token its object subject is registered under: a reused index never hears of an
+     * old subject's collection.
+     */
+    private tokens;
+    private registry;
+    constructor(slotOf: (subject: I) => number, keepRefs: boolean);
+    /** Takes the host's subjects and positions; `xy` is read in place, so a move needs only `moved`. */
+    set(list: readonly I[], xy: Float64Array, cell: number): void;
+    /** `subject`'s index: the one it has, or a new one, a freed index first. */
+    place(subject: I): number;
+    private hold;
+    /** Room for indices below `n`; the mix's own positions start as no position, NaN. */
+    private room;
+    /** The lanes numbered `subject`: its place, if it has one, reads the number from now on. */
+    number(subject: I, slot: number): void;
+    private numbered;
+    /** The lanes let lane number `slot` go. */
+    forgot(slot: number): void;
+    /** The host dropped `subject`: its index is freed. */
+    drop(subject: I): void;
+    /** Frees index `i`, its subject dropped or collected. */
+    private release;
+    /** The subject at index `i`, where it is still held; only outside production. */
+    subjectAt(i: number): I | undefined;
+    /** Whether `subject` is within `r` of (`cx`, `cy`), by the same test `query` makes. */
+    inside(subject: I, cx: number, cy: number, r2: number): boolean;
+}

package/dist/places.js

@@ -0,0 +1,171 @@
+import { Grid } from './grid.js';
+import { Store } from './store.js';
+/**
+ * The index the host gives each subject, by `place` or by its place in the list `plot` was given,
+ * and where the host says each one is, over `Grid`. Subjects are held as the rest of the mix holds
+ * them: an object weakly, anything else until `drop`. An index a subject leaves, by `drop` or by
+ * being collected, is handed out again.
+ */
+export class Places extends Grid {
+    slotOf;
+    keepRefs;
+    /** By subject, its index. */
+    at = new Store();
+    /** By index, its subject's lane number, -1 for one with none or a subject let go. */
+    slots = new Int32Array(0);
+    /** By lane number, the index it was put in `slots` at, -1 for none. */
+    placeOf = new Int32Array(0);
+    /** Outside production, by index, its subject, for the check that a bound does not clip a signal. */
+    refs = null;
+    /** While a bounded fill reads the subject at an index, that index, so `around` need not look it up; else -1. */
+    cur = -1;
+    /** Indices a subject left, for `place` to hand out again. */
+    free = [];
+    /** Whether `xy` is the mix's own, grown as `place` hands out indices, rather than the array `plot` was given. */
+    owned = true;
+    /**
+     * By index, the token its object subject is registered under: a reused index never hears of an
+     * old subject's collection.
+     */
+    tokens = [];
+    registry = null;
+    constructor(slotOf, keepRefs) {
+        super();
+        this.slotOf = slotOf;
+        this.keepRefs = keepRefs;
+        this.refs = keepRefs ? [] : null;
+    }
+    /** Takes the host's subjects and positions; `xy` is read in place, so a move needs only `moved`. */
+    set(list, xy, cell) {
+        const n = list.length;
+        this.at = new Store();
+        for (let i = 0; i < n; i++)
+            this.at.set(list[i], i);
+        this.slots = new Int32Array(Math.max(n, 16)).fill(-1);
+        this.placeOf.fill(-1);
+        this.refs = this.keepRefs ? [] : null;
+        this.tokens = [];
+        this.free = [];
+        for (let i = 0; i < n; i++) {
+            const subject = list[i];
+            // A subject listed twice is at its last index.
+            if (this.at.get(subject) !== i)
+                continue;
+            this.hold(subject, i);
+        }
+        this.n = n;
+        this.xy = xy;
+        this.owned = false;
+        this.cell = cell;
+        this.dirty = true;
+    }
+    /** `subject`'s index: the one it has, or a new one, a freed index first. */
+    place(subject) {
+        const had = this.at.get(subject);
+        if (had !== undefined)
+            return had;
+        const i = this.free.pop() ?? this.n++;
+        this.room(i + 1);
+        this.at.set(subject, i);
+        this.hold(subject, i);
+        if (this.owned)
+            this.put(i, Number.NaN, Number.NaN);
+        return i;
+    }
+    hold(subject, i) {
+        const slot = this.slotOf(subject);
+        if (slot >= 0)
+            this.numbered(slot, i);
+        const object = typeof subject === 'object' && subject !== null;
+        if (this.refs !== null)
+            this.refs[i] = object ? new WeakRef(subject) : subject;
+        if (!object)
+            return;
+        const token = { i };
+        this.tokens[i] = token;
+        this.registry ??= new FinalizationRegistry((t) => {
+            if (this.tokens[t.i] === t)
+                this.release(t.i);
+        });
+        this.registry.register(subject, token, token);
+    }
+    /** Room for indices below `n`; the mix's own positions start as no position, NaN. */
+    room(n) {
+        if (this.slots.length < n) {
+            const slots = new Int32Array(Math.max(n, this.slots.length * 2)).fill(-1);
+            slots.set(this.slots);
+            this.slots = slots;
+        }
+        if (this.owned && this.xy.length < 2 * n) {
+            const xy = new Float64Array(Math.max(2 * n, this.xy.length * 2, 32)).fill(Number.NaN);
+            xy.set(this.xy);
+            this.xy = xy;
+        }
+    }
+    /** The lanes numbered `subject`: its place, if it has one, reads the number from now on. */
+    number(subject, slot) {
+        const i = this.at.get(subject);
+        if (i !== undefined)
+            this.numbered(slot, i);
+    }
+    numbered(slot, i) {
+        if (slot >= this.placeOf.length) {
+            const grown = new Int32Array(Math.max(slot + 1, this.placeOf.length * 2, 64)).fill(-1);
+            grown.set(this.placeOf);
+            this.placeOf = grown;
+        }
+        this.placeOf[slot] = i;
+        this.slots[i] = slot;
+    }
+    /** The lanes let lane number `slot` go. */
+    forgot(slot) {
+        if (slot >= this.placeOf.length)
+            return;
+        const i = this.placeOf[slot];
+        if (i < 0)
+            return;
+        this.placeOf[slot] = -1;
+        if (this.slots[i] === slot)
+            this.slots[i] = -1;
+    }
+    /** The host dropped `subject`: its index is freed. */
+    drop(subject) {
+        const i = this.at.get(subject);
+        if (i === undefined)
+            return;
+        this.at.delete(subject);
+        const token = this.tokens[i];
+        if (token !== undefined)
+            this.registry?.unregister(token);
+        this.release(i);
+    }
+    /** Frees index `i`, its subject dropped or collected. */
+    release(i) {
+        this.tokens[i] = undefined;
+        if (this.refs !== null)
+            this.refs[i] = undefined;
+        const slot = this.slots[i];
+        if (slot >= 0)
+            this.placeOf[slot] = -1;
+        this.slots[i] = -1;
+        // The host's own array is the host's: a reused index reads whatever it holds there.
+        if (this.owned)
+            this.put(i, Number.NaN, Number.NaN);
+        this.free.push(i);
+    }
+    /** The subject at index `i`, where it is still held; only outside production. */
+    subjectAt(i) {
+        const ref = this.refs?.[i];
+        const s = ref instanceof WeakRef ? ref.deref() : ref;
+        return s !== undefined && this.at.get(s) === i ? s : undefined;
+    }
+    /** Whether `subject` is within `r` of (`cx`, `cy`), by the same test `query` makes. */
+    inside(subject, cx, cy, r2) {
+        const i = this.at.get(subject);
+        if (i === undefined || 2 * i + 1 >= this.xy.length)
+            return false;
+        const dx = this.xy[2 * i] - cx;
+        const dy = this.xy[2 * i + 1] - cy;
+        return dx * dx + dy * dy <= r2;
+    }
+}

package/dist/plot.d.ts

@@ -0,0 +1,12 @@
+import type { Mixer } from './mixer.js';
+/** `Mix.plot`: the mix's subjects and their positions, `x` then `y` side by side in `xy`, read in place. */
+export declare function plot<I, O>(this: Mixer<I, O>, subjects: readonly I[], xy: Float64Array, cell?: number): void;
+/** `Mix.place`: the subject's index, its own or a new one, which a `within` finder names it by. */
+export declare function place<I, O>(this: Mixer<I, O>, subject: I): number;
+/** `Mix.moved`: the host wrote new positions into the `xy` it gave `plot`. */
+export declare function moved<I, O>(this: Mixer<I, O>): void;
+/**
+ * `Mix.put`: moves one subject, writing into the `xy` `plot` gave or the mix's own. The grid is built
+ * again only once a sixteenth of the indices have left their cells.
+ */
+export declare function put<I, O>(this: Mixer<I, O>, subject: I, x: number, y: number): void;

package/dist/plot.js

@@ -0,0 +1,52 @@
+import { bind } from './bound.js';
+import { Places } from './places.js';
+import { production } from './warn.js';
+/** `Mix.plot`: the mix's subjects and their positions, `x` then `y` side by side in `xy`, read in place. */
+export function plot(subjects, xy, cell) {
+    if (xy.length < 2 * subjects.length)
+        throw new RangeError(`blits: plot takes two numbers a subject, x then y: ${subjects.length} subjects need ${2 * subjects.length}, not ${xy.length}`);
+    if (cell !== undefined && !(cell > 0 && cell < Number.POSITIVE_INFINITY))
+        throw new RangeError(`blits: plot's cell is a size above 0, not ${cell}`);
+    placesOf(this).set(subjects, xy, cell ?? Number.NaN);
+    this.moved();
+}
+/** `Mix.place`: the subject's index, its own or a new one, which a `within` finder names it by. */
+export function place(subject) {
+    return placesOf(this).place(subject);
+}
+/**
+ * The mix's indices, made at the first `place` or `plot`. An `around` voice cued before then read 0
+ * everywhere, so it takes its circle with nothing to undo.
+ */
+function placesOf(mix) {
+    if (mix.places !== null)
+        return mix.places;
+    const places = new Places((s) => mix.chains.get(s)?.slot ?? -1, !production());
+    mix.places = places;
+    for (const voice of mix.cued)
+        if (voice.bound === null)
+            bind(mix, voice);
+    return places;
+}
+/** `Mix.moved`: the host wrote new positions into the `xy` it gave `plot`. */
+export function moved() {
+    if (this.places !== null)
+        this.places.dirty = true;
+    this.lanes?.refill();
+    this.stir();
+}
+/**
+ * `Mix.put`: moves one subject, writing into the `xy` `plot` gave or the mix's own. The grid is built
+ * again only once a sixteenth of the indices have left their cells.
+ */
+export function put(subject, x, y) {
+    const places = this.places;
+    const i = places === null ? undefined : places.at.get(subject);
+    if (places === null || i === undefined)
+        throw new Error('blits: put takes a subject with an index: place or plot it first');
+    if (2 * i + 1 >= places.xy.length)
+        throw new RangeError(`blits: put's subject is at index ${i}, past the positions plot was given: plot again with room for it`);
+    places.put(i, x, y);
+    this.lanes?.refill();
+    this.stir();
+}

package/dist/project.d.ts

@@ -1,7 +1,9 @@
+import { type Cut } from './cut.js';
 import { Mixer } from './mixer.js';
-import { type Cut, Transport } from './transport.js';
+import type { Subject } from './subject.js';
+import { Transport } from './transport.js';
 import type { TransportProjection } from './types.js';
-import type { Subject, Voice } from './voice.js';
+import type { Voice } from './voice.js';
 /**
  * Every mix on a transport read at mix time `t`, through copies of them on a transport of their
  * own, moved together so an anchor across mixes answers as it would live. Ahead, they stop at each
@@ -12,8 +14,6 @@ export declare function projectAll(transport: Transport, at: number | {
 }): TransportProjection;
 /** Sets each copied voice's state to what its clock and fade make it at `t`. */
 export declare function stateAt<I, O>(c: Mixer<I, O>, t: number): void;
-/** Gives a projection's copy what it reads of the live mix as it is, before its voices are copied. */
-export declare function mirror<I, O>(mix: Mixer<I, O>, c: Mixer<I, O>): void;
 /**
  * A projection back starts each subject from the latest copy kept at or before `t`, else from its
  * voice's start with fresh state, which is exact for a voice stepped at a fixed interval.