@msb235/blits 0.3.0 → 0.5.0

package/dist/keyrows.js

@@ -0,0 +1,138 @@
+import { foldNumber, lerpNumber } from './channels.js';
+import { fraction, locate, shift } from './patch.js';
+/** A row's header: its length in `data`, its offset in `eases`, its duration, its stop count. */
+const HEAD = 4;
+/**
+ * The stops of a crowd's `keys` rows, copied into one array as a row joins, so a fill reads each
+ * row's stops in place rather than through its voice, its built tracks and every stop's own array.
+ * Per row: its header, then per track its stop count, its delay, and per stop its phase and its
+ * value on each of the channel's axes, a missing axis read as rest as `vec`'s lerp reads it. Each
+ * stop's easing is in `eases`.
+ */
+export class KeyRows {
+    data = new Float64Array(64);
+    used = 0;
+    eases = [];
+    /**
+     * Copies a voice's stops for channels `chans` and returns the row's offset; -1 where a stop's
+     * value is not one a lane folds as a number per axis, so the row reads its voice's stops instead.
+     */
+    add(built, chans) {
+        let len = HEAD;
+        let stops = 0;
+        for (let i = 0; i < built.tracks.length; i++) {
+            const track = built.tracks[i];
+            const ch = chans[i];
+            if (track === undefined || ch === undefined)
+                return -1;
+            for (const pt of track.all)
+                if (!flat(pt.value, ch))
+                    return -1;
+            len += 2 + track.all.length * (1 + ch.axes);
+            stops += track.all.length;
+        }
+        const off = this.reserve(len);
+        const d = this.data;
+        d[off] = len;
+        d[off + 1] = this.eases.length;
+        d[off + 2] = built.duration;
+        d[off + 3] = stops;
+        let o = off + HEAD;
+        for (let i = 0; i < built.tracks.length; i++) {
+            const track = built.tracks[i];
+            const ch = chans[i];
+            d[o++] = track.all.length;
+            d[o++] = track.delay;
+            for (const pt of track.all) {
+                d[o++] = pt.at;
+                if (ch.scalar)
+                    d[o++] = pt.value;
+                else {
+                    const arr = pt.value;
+                    for (let a = 0; a < ch.axes; a++)
+                        d[o++] = arr[a] ?? ch.rest;
+                }
+                this.eases.push(pt.ease);
+            }
+        }
+        return off;
+    }
+    /** Copies another pool's row at `off` into this one, returning its offset here. */
+    copy(from, off) {
+        const len = from.data[off];
+        const at = this.reserve(len);
+        this.data.set(from.data.subarray(off, off + len), at);
+        const e = from.data[off + 1];
+        const stops = from.data[off + 3];
+        this.data[at + 1] = this.eases.length;
+        for (let s = 0; s < stops; s++)
+            this.eases.push(from.eases[e + s]);
+        return at;
+    }
+    /**
+     * Folds the row at `off` at `phase` into subject `slot`'s values at weight `w`: what `segment`
+     * and the stock lerp and fold give for each track, read from this pool.
+     */
+    fold(off, phase, chans, slot, w) {
+        const d = this.data;
+        const duration = d[off + 2];
+        let e = d[off + 1];
+        let o = off + HEAD;
+        const end = off + d[off];
+        for (let i = 0; o < end; i++) {
+            const ch = chans[i];
+            const axes = ch.axes;
+            const stride = 1 + axes;
+            const n = d[o];
+            const ph = shift(d[o + 1], phase, duration);
+            const first = o + 2;
+            o = first + n * stride;
+            const k = locate(d, first, stride, n, ph);
+            const stops = e;
+            e += n;
+            if (k === -2)
+                continue;
+            const values = ch.values;
+            const base = slot * axes;
+            if (k === -1 || k === n) {
+                const at = first + (k === -1 ? 0 : n - 1) * stride + 1;
+                for (let a = 0; a < axes; a++)
+                    values[base + a] = foldNumber(ch.op, values[base + a], d[at + a], w);
+                continue;
+            }
+            const b = first + k * stride;
+            const before = b - stride;
+            const u = fraction(ph, d[before], d[b]);
+            const ease = this.eases[stops + k];
+            const eased = ease ? ease(u) : u;
+            for (let a = 0; a < axes; a++) {
+                const v = lerpNumber(d[before + 1 + a], d[b + 1 + a], eased);
+                values[base + a] = foldNumber(ch.op, values[base + a], v, w);
+            }
+        }
+    }
+    reserve(len) {
+        const at = this.used;
+        if (at + len > this.data.length) {
+            const data = new Float64Array(Math.max(at + len, this.data.length * 2));
+            data.set(this.data.subarray(0, at));
+            this.data = data;
+        }
+        this.used = at + len;
+        return at;
+    }
+}
+/** Whether a stop's value folds on a lane as numbers: a number on a number, an array on an array. */
+function flat(value, ch) {
+    if (ch.scalar)
+        return typeof value === 'number';
+    if (!(Array.isArray(value) || ArrayBuffer.isView(value)))
+        return false;
+    const arr = value;
+    for (let a = 0; a < ch.axes; a++) {
+        const x = arr[a];
+        if (x !== undefined && typeof x !== 'number')
+            return false;
+    }
+    return true;
+}

package/dist/lane.d.ts

@@ -0,0 +1,210 @@
+import type { Numeric } from './channels.js';
+import { type Motions } from './motion.js';
+import type { Scratch } from './patch.js';
+import type { Subject, Voice } from './voice.js';
+/** One laned channel: its arithmetic, and every numbered subject's folded value, `axes` per subject. */
+export interface Laned {
+    name: string;
+    /** Its value is a number, its rest a number; otherwise an array, which `vec(1)` is too. */
+    scalar: boolean;
+    op: Numeric['op'];
+    rest: number;
+    axes: number;
+    values: Float64Array;
+    /** An array channel's rest, which a copy starts from as the general path's does. */
+    start: readonly number[];
+    /** Its place among the laned channels. */
+    index: number;
+}
+/**
+ * The laned voices sharing one locus, in voice order, and what a fill gathers from them for each
+ * subject before folding it in at the subject's first member: their summed weight, and per laned
+ * channel the members' values lerped by share of weight and the weight taken into each.
+ */
+export interface Locus<I, O> {
+    readonly members: Lane<I, O>[];
+    /** By subject number: the fill that last met it, the member it met first then, the summed weight. */
+    met: Float64Array;
+    first: Float64Array;
+    sum: Float64Array;
+    /** By laned channel, then subject number (times axes for `values`). */
+    values: (Float64Array | undefined)[];
+    taken: (Float64Array | undefined)[];
+}
+/**
+ * Where each of a lane position's or crowd row's `STRIDE` numbers sits. The layouts are const
+ * enums so tsc writes each member in as a number: V8 reads a const imported from another module on
+ * every use, which cost the fills 10-20%.
+ */
+export declare const enum Row {
+    STRIDE = 8,
+    DELAY = 0,
+    SINCE = 1,
+    /** The weight the last fill gave the subject. */
+    WEIGHT = 2,
+    /** The weight a fill gave it the last time a probe read it from the lane. */
+    PROBED = 3,
+    MSLOT = 4,
+    /** For a motion voice, the last fill that sampled the subject, and the voice's seeks then. */
+    SAMPLED = 5,
+    SEEKS = 6,
+    /** 1 once the general path has made the voice's first call for the subject, which never undoes. */
+    MET = 7
+}
+/** What `begin` found: the general path, or lanes filled. */
+export declare const enum Begin {
+    GENERAL = 0,
+    READY = 1
+}
+/** Where each of a subject's `SLOT` numbers in `Lanes.per` sits. */
+export declare const enum Per {
+    SLOT = 6,
+    FILLED = 0,
+    /**
+     * The latest epoch a probe has checked the subject against; or, as `-1 - e`, that a voice naming
+     * it started after epoch `e`, so its next probe checks it against everything since `e`.
+     */
+    SEEN = 1,
+    IDLE = 2,
+    LANE_PROBE = 3,
+    GENERAL_PROBE = 4,
+    LANE_FILL = 5
+}
+/**
+ * Below what share of its subjects probed last frame a lane stops filling, and above what share it
+ * fills again; between the two it keeps doing what it did, so a host near the line does not flip
+ * every frame. Measured at 10k and 1k subjects (2026-10-02, one local machine): filling breaks even
+ * with probing through the general path at about 19% probed for keys at both sizes, 71-77% for a
+ * spring, and 63% (1k) to about 100% (10k) for a stateless fn.
+ */
+export declare const SPARSE: {
+    keys: {
+        stop: number;
+        start: number;
+    };
+    other: {
+        stop: number;
+        start: number;
+    };
+};
+/** What pacing reads and sets: a lane's or a crowd's subjects, idle state and per-position numbers. */
+export interface Paced {
+    list: number[];
+    idle: boolean;
+    readonly line: {
+        stop: number;
+        start: number;
+    };
+    data: Float64Array;
+}
+/**
+ * Where a motion voice's per-subject numbers live, by position: a lane of one voice, or the crowd
+ * of single-subject motion voices, whose positions each belong to a voice of their own.
+ */
+export interface Positions<I, O> {
+    /** `STRIDE` numbers per position. */
+    data: Float64Array;
+    /** Each position's last delta, built from its kept sample only when asked. */
+    deltas: (Record<string, unknown> | null)[];
+    /** Keeps a position's sample, `n` numbers from `xs`. */
+    keep(p: number, xs: Float64Array, n: number): void;
+    /** Reads a position's kept sample back into `xs`. */
+    kept(p: number, xs: Float64Array): void;
+    chans: Laned[];
+    voiceAt(p: number): Voice<I, O>;
+    /** Makes position `p`'s sample and its stamps hold what its last fill gave it. */
+    fix(p: number): void;
+    /** Position `p`'s subject has number `ms` in its voice's motion patch. */
+    numbered(p: number, ms: number): void;
+    motionAt(p: number): Motions<I> | undefined;
+}
+/**
+ * What one laned voice keeps per subject it reaches, by position in `list`. A subject gets a
+ * position when a probe of it first finds the voice playing, which is when the general path first
+ * sees it too.
+ */
+export declare class Lane<I, O> implements Positions<I, O> {
+    readonly voice: Voice<I, O>;
+    /** The subject number at each position. */
+    readonly list: number[];
+    /** By subject number, its position plus one, 0 where it has none. */
+    private at;
+    /** Whether too few of its subjects were probed lately to fill it: theirs take the general path. */
+    idle: boolean;
+    /** The lines it goes idle and busy at, by its patch form. */
+    readonly line: {
+        stop: number;
+        start: number;
+    };
+    /**
+     * When the voice started playing on its lane, in the order lanes did; 0 while it waits. A subject
+     * checked against every lane up to some epoch has met this one if this one's is no later.
+     */
+    epoch: number;
+    /**
+     * Per position, `STRIDE` numbers side by side, so one subject's are one read from memory: its
+     * delay, its `since`, its weight at the last fill, its weight at the last fill a probe read, a
+     * motion patch's own number for it (-1 until asked), and the fill and seeks of its last sample.
+     */
+    data: Float64Array<ArrayBuffer>;
+    records: (Subject<unknown> | undefined)[];
+    /**
+     * For a motion voice, per position, the delta its last sample made; null where that sample was
+     * kept only in `samples`, until a probe asks for it.
+     */
+    deltas: (Record<string, unknown> | null)[];
+    /** For a motion voice, per position, its last sample's value on each of `axes` axes. */
+    samples: Float64Array<ArrayBuffer>;
+    axes: number;
+    /** What a keys read writes into, reused across subjects. */
+    readonly delta: Record<string, unknown>;
+    /** The arrays keyed reads interpolate into: the lane's own, so a probe mid-fill cannot move them. */
+    readonly scratch: Scratch;
+    /** The laned channel of each channel the voice writes, in `writes` order. */
+    chans: Laned[];
+    /** The value read for each of `chans`, for the subject being folded. */
+    values: unknown[];
+    /**
+     * Within one fill, the last elapsed placed and the last `since` weighed, with what they gave, so
+     * subjects sharing a delay or a start share the arithmetic: the same inputs give the same bits.
+     */
+    placed: boolean;
+    placedAt: number;
+    phase: number;
+    pass: number;
+    read: boolean;
+    readAt: number;
+    weighed: boolean;
+    weighedSince: number;
+    fade: number;
+    /** Whether the voice has no fade in or out this fill, so its envelope is 1 for every subject. */
+    flat: boolean;
+    /** A motion patch's state, which the lane samples in place of calling the patch. */
+    readonly motion: Motions<I> | undefined;
+    /** By the motion patch's number for a subject, its position plus one, 0 where it has none. */
+    private byMotion;
+    /** The last fill `runMotion` ran, and its voice time and seeks, which a `Sampled.BARE` position was sampled at. */
+    bareFill: number;
+    bareElapsed: number;
+    bareSeeks: number;
+    /** The locus its voice shares, gathered before the voices are folded in order. */
+    group: Locus<I, O> | null;
+    voiceAt(): Voice<I, O>;
+    fix(p: number): void;
+    numbered(p: number, ms: number): void;
+    positionOfMotion(ms: number): number;
+    keep(p: number, xs: Float64Array, n: number): void;
+    kept(p: number, xs: Float64Array): void;
+    motionAt(): Motions<I> | undefined;
+    constructor(voice: Voice<I, O>);
+    positionOf(slot: number): number;
+    /** Gives a subject the voice reaches a position, from what its record fixed on first sight. */
+    add(slot: number, held: Subject<unknown>): void;
+    /** A subject lost its number: the last position moves into its place. */
+    remove(slot: number): void;
+}
+/**
+ * A subject's voice time once its voice's holds apply: held at 0 before it starts and at the end of
+ * its passes after, and NaN where it shows nothing.
+ */
+export declare function held<I, O>(voice: Voice<I, O>, elapsed: number): number;

package/dist/lane.js

@@ -0,0 +1,187 @@
+import { unbareLane } from './bare.js';
+import { heldTime } from './clock.js';
+import { motionOf } from './motion.js';
+/**
+ * Below what share of its subjects probed last frame a lane stops filling, and above what share it
+ * fills again; between the two it keeps doing what it did, so a host near the line does not flip
+ * every frame. Measured at 10k and 1k subjects (2026-10-02, one local machine): filling breaks even
+ * with probing through the general path at about 19% probed for keys at both sizes, 71-77% for a
+ * spring, and 63% (1k) to about 100% (10k) for a stateless fn.
+ */
+export const SPARSE = { keys: { stop: 0.15, start: 0.25 }, other: { stop: 0.6, start: 0.8 } };
+/**
+ * What one laned voice keeps per subject it reaches, by position in `list`. A subject gets a
+ * position when a probe of it first finds the voice playing, which is when the general path first
+ * sees it too.
+ */
+export class Lane {
+    voice;
+    /** The subject number at each position. */
+    list = [];
+    /** By subject number, its position plus one, 0 where it has none. */
+    at = new Int32Array(0);
+    /** Whether too few of its subjects were probed lately to fill it: theirs take the general path. */
+    idle = false;
+    /** The lines it goes idle and busy at, by its patch form. */
+    line;
+    /**
+     * When the voice started playing on its lane, in the order lanes did; 0 while it waits. A subject
+     * checked against every lane up to some epoch has met this one if this one's is no later.
+     */
+    epoch = 0;
+    /**
+     * Per position, `STRIDE` numbers side by side, so one subject's are one read from memory: its
+     * delay, its `since`, its weight at the last fill, its weight at the last fill a probe read, a
+     * motion patch's own number for it (-1 until asked), and the fill and seeks of its last sample.
+     */
+    data = new Float64Array(0);
+    records = [];
+    /**
+     * For a motion voice, per position, the delta its last sample made; null where that sample was
+     * kept only in `samples`, until a probe asks for it.
+     */
+    deltas = [];
+    /** For a motion voice, per position, its last sample's value on each of `axes` axes. */
+    samples = new Float64Array(0);
+    axes = 0;
+    /** What a keys read writes into, reused across subjects. */
+    delta = {};
+    /** The arrays keyed reads interpolate into: the lane's own, so a probe mid-fill cannot move them. */
+    scratch = [];
+    /** The laned channel of each channel the voice writes, in `writes` order. */
+    chans = [];
+    /** The value read for each of `chans`, for the subject being folded. */
+    values = [];
+    /**
+     * Within one fill, the last elapsed placed and the last `since` weighed, with what they gave, so
+     * subjects sharing a delay or a start share the arithmetic: the same inputs give the same bits.
+     */
+    placed = false;
+    placedAt = 0;
+    phase = 0;
+    pass = 0;
+    read = false;
+    readAt = 0;
+    weighed = false;
+    weighedSince = 0;
+    fade = 1;
+    /** Whether the voice has no fade in or out this fill, so its envelope is 1 for every subject. */
+    flat = false;
+    /** A motion patch's state, which the lane samples in place of calling the patch. */
+    motion;
+    /** By the motion patch's number for a subject, its position plus one, 0 where it has none. */
+    byMotion = new Int32Array(0);
+    /** The last fill `runMotion` ran, and its voice time and seeks, which a `Sampled.BARE` position was sampled at. */
+    bareFill = -1;
+    bareElapsed = Number.NaN;
+    bareSeeks = Number.NaN;
+    /** The locus its voice shares, gathered before the voices are folded in order. */
+    group = null;
+    voiceAt() {
+        return this.voice;
+    }
+    fix(p) {
+        unbareLane(this, p);
+    }
+    numbered(p, ms) {
+        if (ms >= this.byMotion.length) {
+            const at = new Int32Array(Math.max(ms + 1, this.byMotion.length * 2, 64));
+            at.set(this.byMotion);
+            this.byMotion = at;
+        }
+        this.byMotion[ms] = p + 1;
+    }
+    positionOfMotion(ms) {
+        return ms < this.byMotion.length ? this.byMotion[ms] - 1 : -1;
+    }
+    keep(p, xs, n) {
+        if (this.axes !== n) {
+            this.axes = n;
+            this.samples = new Float64Array(0);
+        }
+        if ((p + 1) * n > this.samples.length) {
+            const grown = new Float64Array(Math.max(p + 1, (this.samples.length / n) * 2, 4) * n);
+            grown.set(this.samples);
+            this.samples = grown;
+        }
+        for (let a = 0; a < n; a++)
+            this.samples[p * n + a] = xs[a];
+    }
+    kept(p, xs) {
+        const n = this.axes;
+        for (let a = 0; a < n; a++)
+            xs[a] = this.samples[p * n + a];
+    }
+    motionAt() {
+        return this.motion;
+    }
+    constructor(voice) {
+        this.voice = voice;
+        this.motion = motionOf(voice.patch);
+        this.line = voice.built !== null ? SPARSE.keys : SPARSE.other;
+    }
+    positionOf(slot) {
+        return slot < this.at.length ? this.at[slot] - 1 : -1;
+    }
+    /** Gives a subject the voice reaches a position, from what its record fixed on first sight. */
+    add(slot, held) {
+        const p = this.list.length;
+        this.list.push(slot);
+        if (slot >= this.at.length) {
+            const at = new Int32Array(Math.max(slot + 1, this.at.length * 2, 64));
+            at.set(this.at);
+            this.at = at;
+        }
+        this.at[slot] = p + 1;
+        if ((p + 1) * 8 /* Row.STRIDE */ > this.data.length) {
+            const data = new Float64Array(Math.max(p + 1, (this.data.length / 8 /* Row.STRIDE */) * 2, 4) * 8 /* Row.STRIDE */);
+            data.set(this.data);
+            this.data = data;
+        }
+        const o = p * 8 /* Row.STRIDE */;
+        this.data[o + 0 /* Row.DELAY */] = held.delay;
+        this.data[o + 1 /* Row.SINCE */] = held.shown;
+        this.data[o + 2 /* Row.WEIGHT */] = 0;
+        this.data[o + 3 /* Row.PROBED */] = 0;
+        this.data[o + 4 /* Row.MSLOT */] = -1;
+        this.data[o + 5 /* Row.SAMPLED */] = -1;
+        this.data[o + 7 /* Row.MET */] = 0;
+        this.records[p] = held;
+        this.deltas[p] = null;
+    }
+    /** A subject lost its number: the last position moves into its place. */
+    remove(slot) {
+        const p = this.positionOf(slot);
+        if (p < 0)
+            return;
+        const last = this.list.length - 1;
+        const ms = this.data[p * 8 /* Row.STRIDE */ + 4 /* Row.MSLOT */];
+        if (ms >= 0)
+            this.byMotion[ms] = 0;
+        if (p !== last) {
+            const number = this.data[last * 8 /* Row.STRIDE */ + 4 /* Row.MSLOT */];
+            if (number >= 0)
+                this.byMotion[number] = p + 1;
+            const moved = this.list[last];
+            this.list[p] = moved;
+            this.at[moved] = p + 1;
+            this.data.copyWithin(p * 8 /* Row.STRIDE */, last * 8 /* Row.STRIDE */, (last + 1) * 8 /* Row.STRIDE */);
+            this.records[p] = this.records[last];
+            this.deltas[p] = this.deltas[last] ?? null;
+            const n = this.axes;
+            if (n > 0)
+                this.samples.copyWithin(p * n, last * n, (last + 1) * n);
+        }
+        this.list.pop();
+        this.at[slot] = 0;
+        this.records[last] = undefined;
+        this.deltas[last] = null;
+    }
+}
+/**
+ * A subject's voice time once its voice's holds apply: held at 0 before it starts and at the end of
+ * its passes after, and NaN where it shows nothing.
+ */
+export function held(voice, elapsed) {
+    return heldTime(elapsed, voice.holdsBefore, voice.holdsAfter, voice.span);
+}