@msb235/blits 0.2.1 → 0.4.0

package/dist/numbers.d.ts

@@ -0,0 +1,22 @@
+/** What a number's subject is once it has none: released, or let go by the host. */
+export declare const absent: unique symbol;
+/**
+ * Hands each subject a small number to index flat arrays by, and takes it back when the subject is
+ * released or, for an object, when the host lets it go. Objects are held weakly, as `Store` holds
+ * them, so numbering one never keeps it alive.
+ */
+export declare class Numbers<I> {
+    private readonly gone;
+    private next;
+    private readonly free;
+    private readonly refs;
+    private live;
+    private readonly tokens;
+    private readonly registry;
+    constructor(gone: (slot: number) => void);
+    /** One past the highest number handed out, so a loop over 0..size meets every live one. */
+    get size(): number;
+    take(subject: I): number;
+    subject(slot: number): I | typeof absent;
+    release(slot: number): void;
+}

package/dist/numbers.js

@@ -0,0 +1,64 @@
+/** What a number's subject is once it has none: released, or let go by the host. */
+export const absent = Symbol('absent');
+/**
+ * Hands each subject a small number to index flat arrays by, and takes it back when the subject is
+ * released or, for an object, when the host lets it go. Objects are held weakly, as `Store` holds
+ * them, so numbering one never keeps it alive.
+ */
+export class Numbers {
+    gone;
+    next = 0;
+    free = [];
+    refs = [];
+    live = new Uint8Array(0);
+    tokens = [];
+    registry = new FinalizationRegistry((slot) => this.release(slot));
+    constructor(gone) {
+        this.gone = gone;
+    }
+    /** One past the highest number handed out, so a loop over 0..size meets every live one. */
+    get size() {
+        return this.next;
+    }
+    take(subject) {
+        const slot = this.free.pop() ?? this.next++;
+        if (slot >= this.live.length) {
+            const grown = new Uint8Array(Math.max(64, this.live.length * 2, slot + 1));
+            grown.set(this.live);
+            this.live = grown;
+        }
+        this.live[slot] = 1;
+        if (typeof subject === 'object' && subject !== null) {
+            this.refs[slot] = new WeakRef(subject);
+            const token = {};
+            this.tokens[slot] = token;
+            this.registry.register(subject, slot, token);
+        }
+        else
+            this.refs[slot] = subject;
+        return slot;
+    }
+    subject(slot) {
+        if (this.live[slot] !== 1)
+            return absent;
+        const ref = this.refs[slot];
+        if (ref instanceof WeakRef) {
+            const s = ref.deref();
+            return s === undefined ? absent : s;
+        }
+        return ref;
+    }
+    release(slot) {
+        if (this.live[slot] !== 1)
+            return;
+        this.live[slot] = 0;
+        const token = this.tokens[slot];
+        if (token !== undefined) {
+            this.registry.unregister(token);
+            this.tokens[slot] = undefined;
+        }
+        this.refs[slot] = undefined;
+        this.gone(slot);
+        this.free.push(slot);
+    }
+}

package/dist/patch.d.ts

@@ -1,5 +1,6 @@
+import { type LerpInto } from './channels.js';
 import { type Curve } from './easing.js';
-import type { Easing, Keyframe, Kit, Patch, Setting } from './types.js';
+import type { Channel, Easing, Keyframe, Kit, Patch, Setting } from './types.js';
 /**
  * What `patch` takes besides its period and its function.
  *
@@ -64,6 +65,16 @@ export interface Built {
     tracks: Track[];
     period: number;
 }
+/**
+ * Arrays a reader lets keyed reads interpolate into, by track. Each only ever holds what a read made,
+ * never a stop's or a base's, and a delta read through it is good until the next read through it.
+ */
+export type Scratch = (unknown[] | undefined)[];
+/**
+ * Per track, the in-place form of the `lerp` a read takes, where it is the mix channel's own and the
+ * channel has one. `channels` holds the mix's channel per track, in `writes` order.
+ */
+export declare function intosOf(built: Built, channels: readonly Channel<unknown>[]): (LerpInto | undefined)[];
 /**
  * Evaluates built stops into `out`; a channel with nothing to read at this phase is left undefined.
  * `lerps` holds the mix's channel `lerp` per track, in `writes` order, for a track the patch did not
@@ -71,7 +82,7 @@ export interface Built {
  */
 export declare function readKeys(built: Built, phase: number, out: Record<string, unknown>, base?: Record<string, unknown>, lerps?: readonly (Lerp | undefined)[], 
 /** Per channel, how fast a retargeted subject was moving, units per ms. */
-slopes?: Record<string, unknown>): Record<string, unknown>;
+slopes?: Record<string, unknown>, intos?: readonly (LerpInto | undefined)[], scratch?: Scratch): Record<string, unknown>;
 /** The built form of a patch's stops, made on first ask for a patch `keys()` did not build. */
 export declare function builtOf<I, O, S>(p: Patch<I, O, S>): Built;
 /** Evaluates a stop list into a fresh delta. */

package/dist/patch.js

@@ -1,3 +1,4 @@
+import { lerpInto } from './channels.js';
 import { curve } from './easing.js';
 /**
  * The procedural form. Flicker, roving, a hash walk, a starter strike.
@@ -68,7 +69,9 @@ function build(stops, writes, period, opts) {
  * Reads one track at a phase. `base` stands in for the value at phase 0, which is how
  * `from: 'current'` starts a voice wherever the subject already is.
  */
-function read(track, phase, base, lerp, slope) {
+function read(track, phase, base, lerp, 
+/** Units per ms, for a retarget's first segment. */
+slope, period, into, reuse) {
     const pts = base === undefined ? track.all : track.tail;
     const o = base === undefined ? 0 : 1;
     const n = pts.length + o;
@@ -95,26 +98,50 @@ function read(track, phase, base, lerp, slope) {
     const aValue = lo - 1 < o ? base : pts[lo - 1 - o].value;
     const u = (phase - aAt) / (b.at - aAt);
     const eased = b.ease ? b.ease(u) : u;
-    const by = track.lerp ?? lerp;
-    const value = by
-        ? by(aValue, b.value, eased)
-        : interpolate(aValue, b.value, eased);
+    let value;
+    if (into !== undefined) {
+        value = into(reuse, aValue, b.value, eased);
+        lastRead.wrote = value;
+    }
+    else {
+        const by = track.lerp ?? lerp;
+        value = by ? by(aValue, b.value, eased) : interpolate(aValue, b.value, eased);
+    }
     // Leaving a retarget's base, bend the first segment so it starts at the slope the subject had:
     // add c·u(1−u)², which is 0 at both ends, flat at the end, and fixes the slope at the start.
     if (slope === undefined || lo - 1 >= o)
         return value;
     const len = b.at - aAt;
     const e0 = b.ease ? b.ease(1e-6) / 1e-6 : 1;
-    const bend = (s, a, z) => (s * len - (z - a) * e0) * u * (1 - u) * (1 - u);
+    const bend = (s, a, z) => (s * period * len - (z - a) * e0) * u * (1 - u) * (1 - u);
     if (typeof value === 'number' && typeof slope === 'number')
         return value + bend(slope, aValue, b.value);
-    if (Array.isArray(value) && Array.isArray(slope))
-        return value.map((v, i) => typeof v === 'number' && typeof slope[i] === 'number'
-            ? v +
-                bend(slope[i], aValue[i], b.value[i])
-            : v);
+    if (Array.isArray(value) && Array.isArray(slope)) {
+        const out = value === lastRead.wrote ? value : new Array(value.length);
+        for (let i = 0; i < value.length; i++) {
+            const v = value[i];
+            const s = slope[i];
+            out[i] =
+                typeof v === 'number' && typeof s === 'number'
+                    ? v + bend(s, aValue[i], b.value[i])
+                    : v;
+        }
+        return out;
+    }
     return value;
 }
+/** The array the last `read` interpolated into, which only its caller's record holds. */
+const lastRead = { wrote: undefined };
+/**
+ * Per track, the in-place form of the `lerp` a read takes, where it is the mix channel's own and the
+ * channel has one. `channels` holds the mix's channel per track, in `writes` order.
+ */
+export function intosOf(built, channels) {
+    return built.tracks.map((track, i) => {
+        const channel = channels[i];
+        return track.lerp === undefined || track.lerp === channel.lerp ? lerpInto(channel) : undefined;
+    });
+}
 /**
  * Evaluates built stops into `out`; a channel with nothing to read at this phase is left undefined.
  * `lerps` holds the mix's channel `lerp` per track, in `writes` order, for a track the patch did not
@@ -122,19 +149,18 @@ function read(track, phase, base, lerp, slope) {
  */
 export function readKeys(built, phase, out, base, lerps, 
 /** Per channel, how fast a retargeted subject was moving, units per ms. */
-slopes) {
+slopes, intos, scratch) {
     const period = built.period;
     for (let i = 0; i < built.tracks.length; i++) {
         const track = built.tracks[i];
         const delay = track.delay;
         const shifted = delay === 0 || period === 0 ? phase : Math.max(0, (phase * period - delay) / period);
         const perMs = slopes?.[track.channel];
-        const slope = perMs === undefined || period === 0
-            ? undefined
-            : typeof perMs === 'number'
-                ? perMs * period
-                : perMs.map((s) => s * period);
-        const value = read(track, shifted, base?.[track.channel], lerps?.[i], slope);
+        const into = scratch === undefined ? undefined : intos?.[i];
+        lastRead.wrote = undefined;
+        const value = read(track, shifted, base?.[track.channel], lerps?.[i], period === 0 ? undefined : perMs, period, into, into === undefined ? undefined : scratch[i]);
+        if (into !== undefined && value === lastRead.wrote)
+            scratch[i] = value;
         if (value !== undefined)
             out[track.channel] = value;
         else if (out[track.channel] !== undefined)

package/dist/reading.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Internal: what kind of read the mix is making right now, for patches that keep state of their own
+ * outside the mix. Not exported from the package.
+ */
+export declare const reading: {
+    /** False while a projection reads: a patch must not commit anything then. */
+    live: boolean;
+    /**
+     * The earliest voice time a read may still ask for; a patch keeping a history may drop what is
+     * older. Infinity where the mix keeps none, so only what plays now is kept.
+     */
+    horizon: number;
+    /**
+     * How many entries `setting.keep` has made in any mix, so a patch call that made one shows
+     * without looking into the record it was made on.
+     */
+    kept: number;
+    /**
+     * How many retargets and pushes any motion patch has taken, so a mix can tell one came mid-frame.
+     * One count for every mix: a change to a spring in one mix refills the lanes of all of them.
+     */
+    moved: number;
+};

package/dist/reading.js

@@ -0,0 +1,23 @@
+/**
+ * Internal: what kind of read the mix is making right now, for patches that keep state of their own
+ * outside the mix. Not exported from the package.
+ */
+export const reading = {
+    /** False while a projection reads: a patch must not commit anything then. */
+    live: true,
+    /**
+     * The earliest voice time a read may still ask for; a patch keeping a history may drop what is
+     * older. Infinity where the mix keeps none, so only what plays now is kept.
+     */
+    horizon: Number.POSITIVE_INFINITY,
+    /**
+     * How many entries `setting.keep` has made in any mix, so a patch call that made one shows
+     * without looking into the record it was made on.
+     */
+    kept: 0,
+    /**
+     * How many retargets and pushes any motion patch has taken, so a mix can tell one came mid-frame.
+     * One count for every mix: a change to a spring in one mix refills the lanes of all of them.
+     */
+    moved: 0,
+};