@msb235/blits 0.13.0 → 0.15.0

package/dist/blend.d.ts

@@ -1,7 +1,8 @@
 import type { Mixer } from './mixer.js';
 import { Store } from './store.js';
+import type { Subject } from './subject.js';
 import type { Signal } from './types.js';
-import type { Subject, Voice } from './voice.js';
+import type { Voice } from './voice.js';
 /** A `mix.blend`'s one signal, read once for all its members. */
 export interface Blend<I, O> {
     by: Signal<I>;

package/dist/blend.js

@@ -42,12 +42,7 @@ export function blended(voice, subject, held, slot) {
         if (cell?.frame === frame)
             return shareOf(cell.value, i, of.stops);
     }
-    else if (slot < of.frames.length) {
-        const read = this.laneRead(voice, slot);
-        if (!Number.isNaN(read))
-            return read;
-    }
-    else {
+    else if (slot >= of.frames.length) {
         const size = Math.max(slot + 1, of.frames.length * 2, 64);
         const frames = new Float64Array(size);
         const values = new Float64Array(size);

package/dist/bound.d.ts

@@ -0,0 +1,70 @@
+import { type Lane } from './lane.js';
+import type { Lanes } from './lanes.js';
+import type { Mixer } from './mixer.js';
+import type { Circle, Finder, VoiceSpec } from './types.js';
+import type { Voice } from './voice.js';
+export declare class Bound<I, O> {
+    readonly mix: Mixer<I, O>;
+    readonly voice: Voice<I, O>;
+    readonly area: Circle | Finder;
+    /** The host's finder, or null for a circle. */
+    readonly finder: Finder | null;
+    /** By index, the `marks` stamp of the last time the general path found it within: see `marked`. */
+    hitAt: Float64Array<ArrayBuffer>;
+    marks: number;
+    /** The frame `hitAt` was last marked in. */
+    markedIn: number;
+    /** The indices a finder's check reads the signal for. */
+    missed: Int32Array<ArrayBuffer>;
+    /** Outside production, until it has warned: whether it checks a finder's indices. */
+    vets: boolean;
+    /** The frame `x`, `y` and `r` were read from `area` in. */
+    frame: number;
+    x: number;
+    y: number;
+    r: number;
+    r2: number;
+    /**
+     * Subject numbers whose lane weight or probed weight may not be 0: those the last fill found
+     * within, those it zeroed and a probe has yet to read 0 from, and those the general path paid.
+     */
+    lit: number[];
+    spare: number[];
+    /**
+     * By subject number, the fill that last found it within (negated where that fill let it go), and
+     * the fill that last put it in `lit`.
+     */
+    inAt: Float64Array<ArrayBuffer>;
+    litAt: Float64Array<ArrayBuffer>;
+    /** Outside production until it has warned: whether it checks the bound clips no signal. */
+    checks: boolean;
+    frames: number;
+    /** The `frames` count a finder's check last ran at. */
+    checkedAt: number;
+    constructor(mix: Mixer<I, O>, voice: Voice<I, O>, area: Circle | Finder);
+}
+/** Refuses a cue's `within` where the mix has handed out no indices, or on a voice with no signal. */
+export declare function checkWithin<I, O>(mix: Mixer<I, O>, spec: VoiceSpec<I, O>): void;
+/**
+ * Bounds a voice just made to its cue's `within`, or to the circle its `around` weight carries once
+ * the mix has indices. A carried circle is the signal's own edge, so it is not checked.
+ */
+export declare function bind<I, O>(mix: Mixer<I, O>, voice: Voice<I, O>): void;
+/** Whether `subject` is within the voice's bound, on the general path. */
+export declare function inBound<I, O>(mix: Mixer<I, O>, b: Bound<I, O>, subject: I): boolean;
+/** Notes that the subject at `slot` may hold a weight other than 0 on the voice's lane. */
+export declare function lit<I, O>(b: Bound<I, O>, slot: number, fills: number): void;
+/**
+ * `run`'s loop for a bounded voice: `one` for the subjects within the bound, and for those that
+ * were lit and are not, their lane weight set to 0 as a read at weight 0 leaves it.
+ */
+export declare function runBounded<I, O>(lanes: Lanes<I, O>, lane: Lane<I, O>, b: Bound<I, O>): void;
+/**
+ * For a role member's bound, before its role's loop: marks the subjects within it this fill, which
+ * `inside` then reads.
+ */
+export declare function meetBound<I, O>(lanes: Lanes<I, O>, b: Bound<I, O>): void;
+/** Whether `meetBound` found the subject at `slot` within the bound this fill. */
+export declare const inside: <I, O>(b: Bound<I, O>, slot: number, fills: number) => boolean;
+/** A role member's subject outside its bound: its lane weight set to 0, as a read at weight 0 leaves it. */
+export declare function leave<I, O>(lanes: Lanes<I, O>, lane: Lane<I, O>, p: number, slot: number): void;

package/dist/bound.js

@@ -0,0 +1,351 @@
+import { carried } from './around.js';
+import { unband } from './fold.js';
+import { keepProbed } from './lane.js';
+import { production, warnOnce } from './warn.js';
+/**
+ * A voice's signal declared 0 outside a bound (`within` on the cue): a circle around a point the host
+ * moves, over positions the host gives the mix (`plot`, `put`), or a finder the host answers with the
+ * indices `place` gave. Outside it the voice is not read at all, which is what lets a lane fill visit
+ * only the subjects within it.
+ */
+/** How many frames apart, outside production, a bound reads its signal just beyond the circle. */
+const CHECK_EVERY = 8;
+/** How many subjects beyond the circle each such check reads. */
+const CHECK_SUBJECTS = 4;
+export class Bound {
+    mix;
+    voice;
+    area;
+    /** The host's finder, or null for a circle. */
+    finder;
+    /** By index, the `marks` stamp of the last time the general path found it within: see `marked`. */
+    hitAt = new Float64Array(0);
+    marks = 0;
+    /** The frame `hitAt` was last marked in. */
+    markedIn = Number.NaN;
+    /** The indices a finder's check reads the signal for. */
+    missed = new Int32Array(CHECK_SUBJECTS);
+    /** Outside production, until it has warned: whether it checks a finder's indices. */
+    vets;
+    /** The frame `x`, `y` and `r` were read from `area` in. */
+    frame = Number.NaN;
+    x = 0;
+    y = 0;
+    r = 0;
+    r2 = 0;
+    /**
+     * Subject numbers whose lane weight or probed weight may not be 0: those the last fill found
+     * within, those it zeroed and a probe has yet to read 0 from, and those the general path paid.
+     */
+    lit = [];
+    spare = [];
+    /**
+     * By subject number, the fill that last found it within (negated where that fill let it go), and
+     * the fill that last put it in `lit`.
+     */
+    inAt = new Float64Array(0);
+    litAt = new Float64Array(0);
+    /** Outside production until it has warned: whether it checks the bound clips no signal. */
+    checks;
+    frames = 0;
+    /** The `frames` count a finder's check last ran at. */
+    checkedAt = -1;
+    constructor(mix, voice, area) {
+        this.mix = mix;
+        this.voice = voice;
+        this.area = area;
+        this.finder = isFinder(area) ? area : null;
+        this.checks = !production();
+        this.vets = this.checks && this.finder !== null;
+    }
+}
+const isFinder = (area) => typeof area.find === 'function';
+/** Refuses a cue's `within` where the mix has handed out no indices, or on a voice with no signal. */
+export function checkWithin(mix, spec) {
+    const area = spec.within;
+    if (area === undefined)
+        return;
+    if (typeof area !== 'object' || area === null)
+        throw new TypeError('blits: within takes a circle, { x, y, r }, or a finder, { find(out) }');
+    if (mix.places === null)
+        throw new Error('blits: within needs indices: call mix.place or mix.plot first');
+    if (typeof spec.weight !== 'function')
+        throw new Error("blits: within needs a signal weight; for a hard-edged disk use weight: mix.around(circle, { steps: 1, jump: 'start' })");
+}
+/**
+ * Bounds a voice just made to its cue's `within`, or to the circle its `around` weight carries once
+ * the mix has indices. A carried circle is the signal's own edge, so it is not checked.
+ */
+export function bind(mix, voice) {
+    const spec = voice.spec;
+    const own = carried(spec.weight);
+    const area = spec.within ?? (own !== undefined && mix.places !== null ? own : undefined);
+    if (area === undefined)
+        return;
+    voice.bound = new Bound(mix, voice, area);
+    if (area === own)
+        voice.bound.checks = false;
+}
+function snap(b, mix) {
+    if (b.frame === mix.frame)
+        return;
+    b.frame = mix.frame;
+    if (b.checks)
+        b.frames++;
+    if (b.finder === null) {
+        const a = b.area;
+        b.x = a.x;
+        b.y = a.y;
+        b.r = a.r;
+        b.r2 = a.r * a.r;
+        if (b.checks && b.frames % CHECK_EVERY === 0) {
+            const places = mix.places;
+            check(b, places.found, places.ring(b.x, b.y, b.r));
+        }
+    }
+}
+/**
+ * Leaves in `places.found` the indices the bound finds this frame, and returns how many: the grid's
+ * for a circle, the host's for a finder. An index no subject holds reads as no lane number.
+ */
+function findAll(b) {
+    const places = b.mix.places;
+    snap(b, b.mix);
+    const finder = b.finder;
+    if (finder === null)
+        return places.query(b.x, b.y, b.r, b.r2);
+    if (places.found.length < places.n)
+        places.found = new Int32Array(Math.max(places.n, places.found.length * 2));
+    const out = places.found;
+    const count = finder.find(out);
+    if (!(Number.isInteger(count) && count >= 0 && count <= out.length))
+        throw new RangeError(`blits: within's find returned ${count}, not a count of the indices it wrote, 0 to ${out.length}`);
+    places.count = count;
+    if (b.vets)
+        vet(b, out, count, places.n);
+    // Once a frame, though a frame may find more than once.
+    if (b.checks && b.frames % CHECK_EVERY === 0 && b.checkedAt !== b.frames) {
+        b.checkedAt = b.frames;
+        check(b, b.missed, miss(b, places, count));
+    }
+    return count;
+}
+/** Warns once if a finder wrote an index `place` never handed out. */
+function vet(b, out, count, n) {
+    for (let k = 0; k < count; k++) {
+        const i = out[k];
+        if (i >= 0 && i < n)
+            continue;
+        b.vets = false;
+        const voice = b.voice;
+        warnOnce(voice, `${voice.spec.name ?? `voice ${voice.id}`}'s within finder found index ${i}, which place never handed out: it is skipped`);
+        return;
+    }
+}
+/**
+ * Reads the signal, as at a first sight, for a few subjects just outside the bound, and warns once
+ * if any is above 0: the bound is cutting off part of the signal. Just beyond a circle's edge; for a
+ * finder, a few indices it did not find, taken in turn.
+ */
+function check(b, list, n) {
+    if (n === 0)
+        return;
+    const places = b.mix.places;
+    const voice = b.voice;
+    const signal = voice.spec.weight;
+    const now = b.mix.now;
+    const setting = {
+        timestamp: now,
+        dt: 0,
+        elapsed: voice.elapsedAt(now),
+        pass: voice.setting.pass,
+        weight: 0,
+        state: undefined,
+        host: voice.setting.host,
+        keep: (_owner, init) => init(),
+        send: () => { },
+    };
+    const step = Math.max(1, Math.floor(n / CHECK_SUBJECTS));
+    const from = (b.frames / CHECK_EVERY) % step;
+    const found = list.slice(0, n);
+    const named = voice.named;
+    for (let k = from; k < n; k += step) {
+        const subject = places.subjectAt(found[k]);
+        if (subject === undefined || (named !== null && !named.has(subject)))
+            continue;
+        const w = signal(subject, setting);
+        if (w > 0) {
+            b.checks = false;
+            warnOnce(voice, b.finder === null
+                ? `${voice.spec.name ?? `voice ${voice.id}`}'s weight signal reads ${w} just outside its within circle (r ${b.r}), which cuts it off there: widen r to where the signal falls to 0`
+                : `${voice.spec.name ?? `voice ${voice.id}`}'s weight signal reads ${w} for a subject its within finder did not find, which cuts it off there: find every subject the signal is above 0 for`);
+            return;
+        }
+    }
+}
+/**
+ * Marks the `count` indices a finder just found, and leaves in `missed` up to `CHECK_SUBJECTS` it did
+ * not, from where the last check left off; returns how many.
+ */
+function miss(b, places, count) {
+    const stamp = mark(b, places, count);
+    const n = places.n;
+    const hitAt = b.hitAt;
+    const from = n === 0 ? 0 : ((b.frames / CHECK_EVERY) * CHECK_SUBJECTS) % n;
+    let m = 0;
+    for (let k = 0; k < n && m < CHECK_SUBJECTS; k++) {
+        const i = (from + k) % n;
+        if (hitAt[i] !== stamp && places.subjectAt(i) !== undefined)
+            b.missed[m++] = i;
+    }
+    return m;
+}
+/** Marks in `hitAt` the first `count` of `places.found`, as this frame's, and returns their stamp. */
+function mark(b, places, count) {
+    b.markedIn = b.mix.frame;
+    if (b.hitAt.length < places.n)
+        b.hitAt = new Float64Array(Math.max(places.n, b.hitAt.length * 2));
+    const stamp = ++b.marks;
+    const found = places.found;
+    const hitAt = b.hitAt;
+    for (let k = 0; k < count; k++) {
+        const i = found[k];
+        if (i >= 0 && i < hitAt.length)
+            hitAt[i] = stamp;
+    }
+    return stamp;
+}
+/** The stamp `hitAt` carries for the indices a finder finds this frame, marked once a frame. */
+function marked(b) {
+    if (b.markedIn === b.mix.frame)
+        return b.marks;
+    const count = findAll(b);
+    // A check in `findAll` may have marked them already.
+    return b.markedIn === b.mix.frame ? b.marks : mark(b, b.mix.places, count);
+}
+/** Whether `subject` is within the voice's bound, on the general path. */
+export function inBound(mix, b, subject) {
+    const places = mix.places;
+    if (places === null)
+        return false;
+    if (b.finder !== null) {
+        const i = places.at.get(subject);
+        if (i === undefined)
+            return false;
+        const stamp = marked(b);
+        return b.hitAt[i] === stamp;
+    }
+    if (mix.projecting) {
+        const a = b.area;
+        return places.inside(subject, a.x, a.y, a.r * a.r);
+    }
+    snap(b, mix);
+    return places.inside(subject, b.x, b.y, b.r2);
+}
+/** Notes that the subject at `slot` may hold a weight other than 0 on the voice's lane. */
+export function lit(b, slot, fills) {
+    if (slot >= b.litAt.length)
+        grow(b, slot + 1);
+    if (b.litAt[slot] === fills)
+        return;
+    b.litAt[slot] = fills;
+    b.lit.push(slot);
+}
+function grow(b, cap) {
+    if (cap <= b.inAt.length)
+        return;
+    const size = Math.max(cap, b.inAt.length * 2, 64);
+    const inAt = new Float64Array(size);
+    inAt.set(b.inAt);
+    b.inAt = inAt;
+    const litAt = new Float64Array(size);
+    litAt.set(b.litAt);
+    b.litAt = litAt;
+}
+/**
+ * `run`'s loop for a bounded voice: `one` for the subjects within the bound, and for those that
+ * were lit and are not, their lane weight set to 0 as a read at weight 0 leaves it.
+ */
+export function runBounded(lanes, lane, b) {
+    const places = b.mix.places;
+    const n = findAll(b);
+    const fills = lanes.fills;
+    grow(b, lanes.cap);
+    const old = b.lit;
+    b.lit = b.spare;
+    b.lit.length = 0;
+    b.spare = old;
+    const voice = lane.voice;
+    const inAt = b.inAt;
+    const found = places.found;
+    const slots = places.slots;
+    for (let k = 0; k < n; k++) {
+        const slot = slots[found[k]] ?? -1;
+        if (slot < 0 || inAt[slot] === fills)
+            continue;
+        inAt[slot] = fills;
+        const p = lane.positionOf(slot);
+        if (p < 0)
+            continue;
+        lit(b, slot, fills);
+        places.cur = found[k];
+        try {
+            lanes.one(lane, p, slot);
+        }
+        finally {
+            places.cur = -1;
+        }
+        if (voice.keeping)
+            return;
+    }
+    const data = lane.data;
+    const per = lanes.per;
+    for (let k = 0; k < old.length; k++) {
+        const slot = old[k];
+        // Within, or already let go of this fill: a second `keepProbed` would copy the 0 just written.
+        if (inAt[slot] === fills || inAt[slot] === -fills)
+            continue;
+        inAt[slot] = -fills;
+        const p = lane.positionOf(slot);
+        if (p < 0)
+            continue;
+        const o = p * 8 /* Row.STRIDE */;
+        keepProbed(data, o, per, slot * 6 /* Per.SLOT */, fills);
+        if (data[o + 2 /* Row.WEIGHT */] !== 0) {
+            data[o + 2 /* Row.WEIGHT */] = 0;
+            unband(lane.records[p]);
+        }
+        if (data[o + 3 /* Row.PROBED */] !== 0)
+            lit(b, slot, fills);
+    }
+}
+/**
+ * For a role member's bound, before its role's loop: marks the subjects within it this fill, which
+ * `inside` then reads.
+ */
+export function meetBound(lanes, b) {
+    const places = b.mix.places;
+    const n = findAll(b);
+    const fills = lanes.fills;
+    grow(b, lanes.cap);
+    const inAt = b.inAt;
+    const found = places.found;
+    const slots = places.slots;
+    for (let k = 0; k < n; k++) {
+        const slot = slots[found[k]] ?? -1;
+        if (slot >= 0)
+            inAt[slot] = fills;
+    }
+}
+/** Whether `meetBound` found the subject at `slot` within the bound this fill. */
+export const inside = (b, slot, fills) => b.inAt[slot] === fills;
+/** A role member's subject outside its bound: its lane weight set to 0, as a read at weight 0 leaves it. */
+export function leave(lanes, lane, p, slot) {
+    const data = lane.data;
+    const o = p * 8 /* Row.STRIDE */;
+    keepProbed(data, o, lanes.per, slot * 6 /* Per.SLOT */, lanes.fills);
+    if (data[o + 2 /* Row.WEIGHT */] !== 0) {
+        data[o + 2 /* Row.WEIGHT */] = 0;
+        unband(lane.records[p]);
+    }
+}

package/dist/chain.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';
 /**
  * The first of this subject's records, linked through every live voice that reaches it. A voice
  * is asked once, through the record it keeps for the subject anyway; a pending one is linked when

package/dist/chain.js

@@ -18,6 +18,8 @@ export function chain(subject) {
 export function relink(subject, was) {
     const lanes = this.lanes;
     const slot = was !== undefined ? was.slot : lanes !== null ? lanes.number(subject) : -1;
+    if (was === undefined && slot >= 0)
+        this.places?.number(subject, slot);
     // A chain a seek kept for its number alone links afresh, as a subject first seen does.
     const sought = was !== undefined && slot >= 0 && lanes?.renew(slot) === true;
     // Where only voices over every subject changed since, those alone are taken off or put on.
@@ -30,8 +32,8 @@ export function relink(subject, was) {
     head.version = this.version;
     if (was !== undefined && was !== head) {
         if (!sought)
-            head.loci = was.loci;
-        was.loci = null;
+            head.roles = was.roles;
+        was.roles = null;
         was.slot = -1;
     }
     head.slot = slot;
@@ -143,7 +145,7 @@ export function changed(mix, voice) {
         mix.steps.push(voice, ++mix.version);
         return;
     }
-    for (const subject of voice.named) {
+    for (const subject of voice.named.list) {
         const head = headOf(mix, subject);
         if (head !== undefined)
             unlink(mix, head);
@@ -176,7 +178,7 @@ export function index(mix, voice) {
         return;
     }
     mix.naming++;
-    for (const subject of voice.named) {
+    for (const subject of voice.named.list) {
         const list = mix.named.get(subject);
         if (list === undefined)
             mix.named.set(subject, [voice]);
@@ -186,7 +188,7 @@ export function index(mix, voice) {
 }
 export function unindex(mix, voice) {
     mix.naming--;
-    for (const subject of voice.named) {
+    for (const subject of voice.named.list) {
         const list = mix.named.get(subject);
         if (list === undefined)
             continue;

package/dist/changes.d.ts

@@ -0,0 +1,24 @@
+import type { Motions } from './motions.js';
+import { absent } from './numbers.js';
+import { type Change, type Segment } from './stretch.js';
+/**
+ * Queues a retarget, set or push, untimed at the latest frame, for `subject`'s next read past its time.
+ * The queue keeps the changes with a time in time order, ahead of any still waiting for one.
+ */
+export declare function change<I>(this: Motions<I>, subject: I, c: Change): void;
+/** Files a change with a time after every one due by then, ahead of those still waiting for one. */
+export declare function queue<I>(this: Motions<I>, list: Change[], c: Change, at: number): void;
+/** Every change due by `t` applied to a copy of the stretch playing then, committing nothing. */
+export declare function peek<I>(this: Motions<I>, s: number, t: number, xo: Float64Array, vo: Float64Array): void;
+/** Subject `s`'s changes waiting, with those a read ahead's tape made filed among them by time. */
+export declare function dueTo<I>(this: Motions<I>, s: number): readonly Change[] | undefined;
+/**
+ * Takes back every change made after frame `seq`: each subject plays from its earliest stretch
+ * kept, with the changes made by then queued to be applied again.
+ */
+export declare function rewind<I>(this: Motions<I>, seq: number): void;
+export declare function cut<I>(this: Motions<I>, s: number, seq: number): void;
+/** The stretch `change` releases from `seg` at `at`, for `subject` or one no longer numbered. */
+export declare function applied<I>(this: Motions<I>, subject: I | typeof absent, seg: Segment, change: Change, at: number): Segment;
+export declare function commit<I>(this: Motions<I>, s: number, t: number): void;
+export declare function insert<I>(this: Motions<I>, s: number, seg: Segment): void;