@msb235/blits 0.0.0-stage → 0.1.1

package/dist/patch.d.ts

@@ -0,0 +1,75 @@
+import { type Curve } from './easing.js';
+import type { Easing, Keyframe, Kit, Patch, Setting } from './types.js';
+/**
+ * What `patch` takes besides its period and its function.
+ *
+ * @category patch
+ */
+export interface PatchOptions<I, O, S> {
+    /** The channels this patch contributes to. Every key `at` sets, and no others. Default: `kit`'s. */
+    writes?: readonly (keyof O)[];
+    /** The channels this patch was written against, which `cue` checks a mix's kit against. */
+    kit?: Partial<Kit<O>>;
+    /** The fields of `setting.host` this patch reads, which `cue` checks the mix's host for. */
+    reads?: readonly string[];
+    state?(subject: I): S;
+    step?(state: S, dt: number, subject: I, setting: Setting<S>): void;
+}
+/**
+ * The procedural form. Flicker, roving, a hash walk, a starter strike.
+ *
+ * @category patch
+ */
+export declare function patch<I, O, S = void>(period: number, at: (phase: number, subject: I, setting: Setting<S>) => Partial<O>, opts: PatchOptions<I, O, S>): Patch<I, O, S>;
+/**
+ * What `keys` takes besides its period and its stops.
+ *
+ * @category patch
+ */
+export interface KeysOptions<O> {
+    /** The curve every segment takes unless a stop or `easeBy` overrides it. */
+    ease?: Easing;
+    /** A curve for one channel, where it differs from the rest. */
+    easeBy?: (channel: keyof O) => Easing | undefined;
+    /** Milliseconds one channel waits before it starts moving, within the period. */
+    delayBy?: (channel: keyof O) => number;
+    /** How one channel interpolates, where its values are not numbers or number arrays. */
+    lerpBy?: (channel: keyof O) => ((a: never, b: never, u: number) => unknown) | undefined;
+    /** The channels these stops were written against, which `cue` checks a mix's kit against. */
+    kit?: Partial<Kit<O>>;
+}
+/** The options a `keys` patch was built with, for an engine reading its stops rather than calling it. */
+export declare function keysOptionsOf<I, O, S>(p: Patch<I, O, S>): KeysOptions<O> | undefined;
+interface Point {
+    at: number;
+    value: unknown;
+    /** The curve into this point from the one before: the stop's own, else the channel's. */
+    ease: Curve | undefined;
+}
+/** One channel of a stop list, sorted and resolved once, so a read is a binary search. */
+interface Track {
+    channel: string;
+    /** Every stop carrying this channel, by phase. */
+    all: Point[];
+    /** The same without stops at 0, which a `from: 'current'` base replaces. */
+    tail: Point[];
+    delay: number;
+    lerp: ((a: never, b: never, u: number) => unknown) | undefined;
+}
+export interface Built {
+    tracks: Track[];
+    period: number;
+}
+/** Evaluates built stops into `out`; a channel with nothing to read at this phase is left undefined. */
+export declare function readKeys(built: Built, phase: number, out: Record<string, unknown>, base?: Record<string, unknown>): 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. */
+export declare function evalKeys<O>(stops: readonly Keyframe<O>[], writes: readonly (keyof O)[], phase: number, period: number, opts: KeysOptions<O>, base?: Partial<O>): Partial<O>;
+/**
+ * The declarative form. klieg's transition sugar and wod's keyframes.
+ *
+ * @category patch
+ */
+export declare function keys<I, O>(period: number, stops: readonly Keyframe<O>[], opts?: KeysOptions<O>): Patch<I, O, void>;
+export {};

package/dist/patch.js

@@ -0,0 +1,149 @@
+import { curve } from './easing.js';
+/**
+ * The procedural form. Flicker, roving, a hash walk, a starter strike.
+ *
+ * @category patch
+ */
+export function patch(period, at, opts) {
+    const writes = opts.writes ?? (opts.kit ? Object.keys(opts.kit) : undefined);
+    if (writes === undefined)
+        throw new Error('blits: a patch needs writes, or a kit to take them from');
+    return {
+        form: 'fn',
+        period,
+        writes,
+        kit: opts.kit,
+        reads: opts.reads,
+        at,
+        state: opts.state,
+        step: opts.step,
+    };
+}
+const options = new WeakMap();
+/** The options a `keys` patch was built with, for an engine reading its stops rather than calling it. */
+export function keysOptionsOf(p) {
+    return options.get(p);
+}
+const linear = (a, b, u) => a + (b - a) * u;
+function interpolate(a, b, u) {
+    if (typeof a === 'number' && typeof b === 'number')
+        return linear(a, b, u);
+    if (Array.isArray(a) && Array.isArray(b)) {
+        const out = new Array(a.length);
+        for (let i = 0; i < a.length; i++)
+            out[i] = interpolate(a[i], b[i], u);
+        return out;
+    }
+    return u < 0.5 ? a : b;
+}
+function build(stops, writes, period, opts) {
+    const fallback = opts.ease === undefined ? undefined : curve(opts.ease);
+    const tracks = [];
+    for (const channel of writes) {
+        const own = opts.easeBy?.(channel);
+        const trackEase = own === undefined ? fallback : curve(own);
+        const all = [];
+        for (const stop of stops) {
+            const value = stop.delta[channel];
+            if (value === undefined)
+                continue;
+            all.push({
+                at: stop.at,
+                value,
+                ease: stop.ease === undefined ? trackEase : curve(stop.ease),
+            });
+        }
+        all.sort((x, y) => x.at - y.at);
+        tracks.push({
+            channel: channel,
+            all,
+            tail: all.filter((pt) => pt.at !== 0),
+            delay: opts.delayBy?.(channel) ?? 0,
+            lerp: opts.lerpBy?.(channel),
+        });
+    }
+    return { tracks, period };
+}
+/**
+ * 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) {
+    const pts = base === undefined ? track.all : track.tail;
+    const o = base === undefined ? 0 : 1;
+    const n = pts.length + o;
+    if (n === 0)
+        return undefined;
+    const firstAt = o === 1 ? 0 : pts[0].at;
+    if (phase <= firstAt)
+        return o === 1 ? base : pts[0].value;
+    const last = pts[pts.length - 1];
+    if (last === undefined || phase >= last.at)
+        return last === undefined ? base : last.value;
+    // The first point at or past phase; the segment ends there.
+    let lo = 1;
+    let hi = n - 1;
+    while (lo < hi) {
+        const mid = (lo + hi) >> 1;
+        if (pts[mid - o].at >= phase)
+            hi = mid;
+        else
+            lo = mid + 1;
+    }
+    const b = pts[lo - o];
+    const aAt = lo - 1 < o ? 0 : pts[lo - 1 - o].at;
+    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;
+    return track.lerp
+        ? track.lerp(aValue, b.value, eased)
+        : interpolate(aValue, b.value, eased);
+}
+/** Evaluates built stops into `out`; a channel with nothing to read at this phase is left undefined. */
+export function readKeys(built, phase, out, base) {
+    const period = built.period;
+    for (const track of built.tracks) {
+        const delay = track.delay;
+        const shifted = delay === 0 || period === 0 ? phase : Math.max(0, (phase * period - delay) / period);
+        const value = read(track, shifted, base?.[track.channel]);
+        if (value !== undefined)
+            out[track.channel] = value;
+        else if (out[track.channel] !== undefined)
+            out[track.channel] = undefined;
+    }
+    return out;
+}
+const cache = new WeakMap();
+/** The built form of a patch's stops, made on first ask for a patch `keys()` did not build. */
+export function builtOf(p) {
+    let held = cache.get(p);
+    if (held === undefined) {
+        held = build(p.keys, p.writes, p.period, keysOptionsOf(p) ?? {});
+        cache.set(p, held);
+    }
+    return held;
+}
+/** Evaluates a stop list into a fresh delta. */
+export function evalKeys(stops, writes, phase, period, opts, base) {
+    return readKeys(build(stops, writes, period, opts), phase, {}, base);
+}
+/**
+ * The declarative form. klieg's transition sugar and wod's keyframes.
+ *
+ * @category patch
+ */
+export function keys(period, stops, opts = {}) {
+    const writes = [...new Set(stops.flatMap((s) => Object.keys(s.delta)))];
+    const made = build(stops, writes, period, opts);
+    const p = {
+        form: 'keys',
+        period,
+        writes,
+        kit: opts.kit,
+        keys: stops,
+        at: (phase) => readKeys(made, phase, {}),
+    };
+    options.set(p, opts);
+    cache.set(p, made);
+    return p;
+}

package/dist/signals.d.ts

@@ -0,0 +1,50 @@
+import type { Signal } from './types.js';
+/**
+ * The loudest of several signals.
+ *
+ * @category signal
+ */
+export declare function peak<I>(...signals: readonly Signal<I>[]): Signal<I>;
+/**
+ * A signal the host writes. klieg's `level`.
+ *
+ * @category signal
+ */
+export declare function level<I>(initial?: number): Signal<I> & {
+    set(v: number): void;
+};
+/**
+ * The package's one decay primitive: follows its input at a rate limit, no faster than `riseMs` per
+ * unit climbing or `fallMs` draining. The mix keeps its state per voice and subject, so two voices
+ * handed the same slew each follow on their own.
+ *
+ * @category signal
+ */
+export declare function slew<I>(of: Signal<I>, { riseMs, fallMs }: {
+    riseMs?: number;
+    fallMs?: number;
+}): Signal<I>;
+/**
+ * The exponential counterpart to `slew`: closes the same fraction of the distance to its input in
+ * every equal stretch of time, `1 − exp(−gap / ms)`, so it reads the same however the frames that
+ * sample it are spaced while the input holds still. `riseMs` and `fallMs` are time constants: after
+ * one, 63% of the way is covered. 0 follows at once. Within `floor` of its input it lands on it, so a
+ * subject can reach rest; pass 0 to keep the curve exact. The mix keeps its state per voice and subject.
+ *
+ * @category signal
+ */
+export declare function lag<I>(of: Signal<I>, { riseMs, fallMs, floor }: {
+    riseMs?: number;
+    fallMs?: number;
+    floor?: number;
+}): Signal<I>;
+/**
+ * The other half of the pair: a band, not an edge. It drops at `off`, passes at `on`, and between
+ * the two it holds whatever it last did, so an input resting on a threshold cannot chatter.
+ *
+ * @category signal
+ */
+export declare function gate<I>(of: Signal<I>, band: {
+    on: number;
+    off: number;
+} | number): Signal<I>;

package/dist/signals.js

@@ -0,0 +1,111 @@
+const inputOf = (signals) => signals.some((s) => s.input);
+const marked = (read, input) => (input ? Object.assign(read, { input: true }) : read);
+/**
+ * The loudest of several signals.
+ *
+ * @category signal
+ */
+export function peak(...signals) {
+    return marked((subject, setting) => {
+        let out = 0;
+        for (const s of signals) {
+            const v = s(subject, setting);
+            if (v > out)
+                out = v;
+        }
+        return out;
+    }, inputOf(signals));
+}
+/**
+ * A signal the host writes. klieg's `level`.
+ *
+ * @category signal
+ */
+export function level(initial = 0) {
+    let value = initial;
+    return Object.assign(() => value, {
+        input: true,
+        set(v) {
+            value = v;
+        },
+    });
+}
+/**
+ * The package's one decay primitive: follows its input at a rate limit, no faster than `riseMs` per
+ * unit climbing or `fallMs` draining. The mix keeps its state per voice and subject, so two voices
+ * handed the same slew each follow on their own.
+ *
+ * @category signal
+ */
+export function slew(of, { riseMs = 0, fallMs = 0 }) {
+    const read = (subject, setting) => {
+        const target = of(subject, setting);
+        const held = setting.keep(read, () => ({ value: target, seen: Number.NaN }));
+        if (setting.timestamp === held.seen)
+            return held.value;
+        let next = target;
+        if (!Number.isNaN(held.seen) && Number.isFinite(setting.dt)) {
+            const gap = target - held.value;
+            const ms = gap > 0 ? riseMs : fallMs;
+            if (ms > 0) {
+                const step = (setting.timestamp - held.seen) / ms;
+                next = gap > 0 ? Math.min(target, held.value + step) : Math.max(target, held.value - step);
+            }
+        }
+        held.value = next;
+        held.seen = setting.timestamp;
+        return next;
+    };
+    return marked(read, inputOf([of]));
+}
+/**
+ * The exponential counterpart to `slew`: closes the same fraction of the distance to its input in
+ * every equal stretch of time, `1 − exp(−gap / ms)`, so it reads the same however the frames that
+ * sample it are spaced while the input holds still. `riseMs` and `fallMs` are time constants: after
+ * one, 63% of the way is covered. 0 follows at once. Within `floor` of its input it lands on it, so a
+ * subject can reach rest; pass 0 to keep the curve exact. The mix keeps its state per voice and subject.
+ *
+ * @category signal
+ */
+export function lag(of, { riseMs = 0, fallMs = 0, floor = 1e-6 }) {
+    const read = (subject, setting) => {
+        const target = of(subject, setting);
+        const held = setting.keep(read, () => ({ value: target, seen: Number.NaN }));
+        if (setting.timestamp === held.seen)
+            return held.value;
+        let next = target;
+        if (!Number.isNaN(held.seen) && Number.isFinite(setting.dt)) {
+            const ms = target > held.value ? riseMs : fallMs;
+            if (ms > 0) {
+                const gap = setting.timestamp - held.seen;
+                next = held.value + (target - held.value) * (1 - Math.exp(-gap / ms));
+                if (Math.abs(target - next) <= floor)
+                    next = target;
+            }
+        }
+        held.value = next;
+        held.seen = setting.timestamp;
+        return next;
+    };
+    return marked(read, inputOf([of]));
+}
+/**
+ * The other half of the pair: a band, not an edge. It drops at `off`, passes at `on`, and between
+ * the two it holds whatever it last did, so an input resting on a threshold cannot chatter.
+ *
+ * @category signal
+ */
+export function gate(of, band) {
+    const on = typeof band === 'number' ? band : band.on;
+    const off = typeof band === 'number' ? band : band.off;
+    const read = (subject, setting) => {
+        const input = of(subject, setting);
+        const held = setting.keep(read, () => ({ on: input >= on, seen: Number.NaN }));
+        if (setting.timestamp !== held.seen) {
+            held.on = input >= on ? true : input <= off ? false : held.on;
+            held.seen = setting.timestamp;
+        }
+        return held.on ? 1 : 0;
+    };
+    return marked(read, inputOf([of]));
+}

package/dist/store.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Per-subject storage keyed by identity. Objects go in a WeakMap and are forgotten when the host
+ * drops them; anything else — a string id, the unit subject of a mix with no subject dimension —
+ * goes in a Map that only `drop` and `clear` empty, which is why a host keying by value should
+ * call `drop`.
+ */
+export declare class Store<K, V> {
+    private readonly weak;
+    private readonly strong;
+    get(key: K): V | undefined;
+    set(key: K, value: V): void;
+    has(key: K): boolean;
+    delete(key: K): void;
+    clear(): void;
+}

package/dist/store.js

@@ -0,0 +1,33 @@
+/**
+ * Per-subject storage keyed by identity. Objects go in a WeakMap and are forgotten when the host
+ * drops them; anything else — a string id, the unit subject of a mix with no subject dimension —
+ * goes in a Map that only `drop` and `clear` empty, which is why a host keying by value should
+ * call `drop`.
+ */
+export class Store {
+    weak = new WeakMap();
+    strong = new Map();
+    get(key) {
+        return typeof key === 'object' && key !== null
+            ? this.weak.get(key)
+            : this.strong.get(key);
+    }
+    set(key, value) {
+        if (typeof key === 'object' && key !== null)
+            this.weak.set(key, value);
+        else
+            this.strong.set(key, value);
+    }
+    has(key) {
+        return this.get(key) !== undefined;
+    }
+    delete(key) {
+        if (typeof key === 'object' && key !== null)
+            this.weak.delete(key);
+        else
+            this.strong.delete(key);
+    }
+    clear() {
+        this.strong.clear();
+    }
+}