@msb235/blits 0.13.0 → 0.15.0

package/dist/types.d.ts

@@ -2,6 +2,7 @@ export type * from './types/arc.js';
 export type * from './types/channel.js';
 export type * from './types/history.js';
 export type * from './types/mix.js';
+export type * from './types/motion.js';
 export type * from './types/patch.js';
 export type * from './types/place.js';
 export type * from './types/transport.js';

package/dist/voice.d.ts

@@ -1,5 +1,6 @@
 import type { Arc } from './arcs.js';
 import type { Blend } from './blend.js';
+import type { Bound } from './bound.js';
 import { type Clock } from './clock.js';
 import { type Curve } from './easing.js';
 import type { Leavings } from './leavings.js';
@@ -8,149 +9,12 @@ import { Named } from './named.js';
 import type { Past } from './origin.js';
 import { Holding } from './owner.js';
 import { type Built, intosOf, type Scratch } from './patch.js';
-import type { Stamp } from './restored.js';
+import { VoiceSetting } from './setting.js';
 import type { Fitting } from './spans.js';
 import { Store } from './store.js';
-import type { Anchor, Channel, FadeSpec, Handle, Patch, Setting, VoiceSpec } from './types.js';
-/**
- * A subject's record as it left a voice, faded out of it or dropped: the mix time and frame it
- * left at, and `sync` where it shows in its own frame: left in the frame's sync, or before anything
- * read the mix that frame.
- */
-export interface Left<I> {
-    subject: I;
-    at: number;
-    seq: number;
-    sync: boolean;
-    held: Subject<unknown>;
-    /**
-     * The voice's fade of the subject as it stood on leaving, which a seek or read back to before
-     * puts back: its ramp out, while running, or its having faded out.
-     */
-    ramp: Parting | null;
-    parted: Parted | null;
-}
-/** A subject's ramp out of one voice: when it began, how long it runs, and the frame it was asked in. */
-export interface Parting {
-    at: number;
-    over: number;
-    seq: number;
-}
-export interface Parted {
-    at: number;
-    seq: number;
-    ramp: Parting | undefined;
-}
+import type { Parted, Parting, Snap, Subject } from './subject.js';
+import type { Anchor, Channel, FadeSpec, Handle, Patch, VoiceSpec } from './types.js';
 export declare const none: readonly string[];
-/**
- * What a copy of a record keeps for the seeks that put a record back from it: the copy's state
- * stepped on to `ticks`, as it stood near `at`, a moment one of them sought.
- */
-export interface Ahead<S> {
-    /** The record the last seek put back, and the moment it sought, until that record steps. */
-    put: Subject<S> | null;
-    sought: number;
-    /** The `since` of the record put back, which the steps in `state` were counted from. */
-    since: number;
-    at: number;
-    ticks: number;
-    /** Undefined until a record has stepped on from the copy. */
-    state: S | undefined;
-    /**
-     * The state the record a seek replaced had stepped on to from the copy, at `leftTicks`; undefined
-     * until one had.
-     */
-    leftTicks: number;
-    left: S | undefined;
-}
-/** A copy of a record kept under `history`, by the mix time and frame it was taken at. */
-export interface Snap<S> {
-    at: number;
-    seq: number;
-    held: Subject<S>;
-    ahead?: Ahead<S>;
-    /** Set where another record's list holds it too, so a seek cutting it from one lets go of it. */
-    shared?: true;
-}
-/** Everything one voice holds for one subject, chained through the next voice that reaches it. */
-export interface Subject<S> {
-    /** The voice's `target` answer, fixed on first sight. */
-    reaches: boolean;
-    /** The voice's `stagger` answer in voice ms, fixed on first sight. */
-    delay: number;
-    /** The mix timestamp this subject's delay ran out at, which its step grid counts from. */
-    since: number;
-    /** The mix timestamp its fade in counts from: `since`, or earlier for a voice freezing before. */
-    shown: number;
-    /** The weight this voice gave this subject the last frame it was probed, 0 where it gave none. */
-    weight: number;
-    /** Left at rest during a handover, so it stops contributing. */
-    rested: boolean;
-    /**
-     * Per written channel, whether a rest-less contribution is on: 0 unknown, 1 on, 2 off; null until
-     * a rest-less channel asks.
-     */
-    bands: Uint8Array | null;
-    state: S;
-    /** The `now` this subject last caught up to, for this voice. */
-    stepped: number;
-    /** Under `stepMs`, how many intervals have run since `since`; `stepped` is where that lands. */
-    ticks: number;
-    /** The `now` this subject was last probed at, so twelve probes in a frame step once. */
-    probed: number;
-    /** The last delta computed this frame, handed back to a repeat probe unchanged. */
-    delta: Record<string, unknown> | null;
-    /** The phase `delta` was read at, to read it again once its voice's scratch has moved on. */
-    phase: number;
-    /** The voice's `seeks` when `delta` was read, so a seek later in the frame reads it again. */
-    seeks: number;
-    /** The voice's `rebuilds` when its state was last made, so a seek's rebuild reaches it once. */
-    rebuilt: number;
-    /** Its kept signal state was stepped on in one go from a copy history kept, by a seek. */
-    copied: boolean;
-    /** Stop 0 for a `from: 'current'` voice, taken the first frame this subject is seen. */
-    base?: Record<string, unknown>;
-    /** The pose's velocity per channel at that moment, units per ms, so the first segment leaves at it. */
-    slope?: Record<string, unknown>;
-    /** What `setting.keep` holds for this voice and subject, by owner; null until it holds any. */
-    kept: Map<object, unknown> | null;
-    /** Kept state a history store gave back, which each owner takes in turn on its first keep. */
-    unkept?: unknown[];
-    /** Under `history`, copies of this record by the mix time they were taken, oldest first. */
-    snaps?: Snap<S>[];
-    /** In a projection: where this record started from, and whether nothing known could be. */
-    from?: number;
-    unknown?: boolean;
-    /** Under `history` with `inputs`, what an input weight signal read for this subject, when it changed. */
-    inputs?: {
-        at: number;
-        seq: number;
-        value: number;
-    }[];
-    /** In a projection reading back: that record, to read in place of the signal. */
-    replay?: {
-        at: number;
-        value: number;
-    }[];
-    /** The voice this is the record of; null on a subject's stub. */
-    voice: object | null;
-    /** The next voice's record for this subject, in voice order, among those that reach it. */
-    next: Subject<unknown> | null;
-    /**
-     * On the first record, which the mix keeps per subject so a probe makes one lookup: the `version`
-     * the chain was linked at, and per locus, by channel slot, whether a rest-less contribution is on:
-     * 0 never decided, 1 on, 2 off.
-     */
-    version: number;
-    loci: Map<string, Uint8Array> | null;
-    /** On the first record: the number lanes index this subject by, -1 without one. */
-    slot: number;
-    /** A motion voice's number for this subject in its patch, good while `freed` is the patch's own. */
-    run: number;
-    freed: number;
-    /** In a voice's store once a seek has gone back, the stamp of the seek it was last put back or written at. */
-    restored: Stamp | null;
-}
 /** A voice's clock, weight and fade from one mix time on, kept under `history`. */
 export interface Controls extends Clock {
     at: number;
@@ -299,7 +163,7 @@ export declare class Voice<I, O> {
     /** The clocks it ran on before its current one, where a subject's origin may lie; null for none. */
     clocks: Past[] | null;
     /** Reused for every call this voice makes, so it is valid only during the call. */
-    readonly setting: Setting<unknown>;
+    readonly setting: VoiceSetting<I, O>;
     /** Every subject this voice has been asked about, so a handover knows when it is finished. */
     seen: number;
     /** The longest stagger of any subject seen, so a finite loop waits for the last of them. */
@@ -333,6 +197,8 @@ export declare class Voice<I, O> {
     outSet: boolean;
     /** The host time a pinned start was given at, NaN for none: a seek back pins it again. */
     pinned: number;
+    /** Cued with no start while its mix slept, so the next sync sets its start. */
+    waking: boolean;
     /** Whether its start is still to be fixed by an anchor, so it waits pending. */
     placing: boolean;
     /** What each member of a join last answered, kept for once its target has left. */
@@ -359,6 +225,8 @@ export declare class Voice<I, O> {
     unreachedBits: Uint32Array | null;
     /** Whether one record stands for every subject: see `shares` in `everyone.ts`. */
     sharing: boolean;
+    /** Where its signal is declared 0, its cue's `within`, so it is not read there: see `bound.ts`. */
+    bound: Bound<I, O> | null;
     /** The frames it has played sharing it. */
     shared: number;
     /** That record, null until a chain first asks and once the voice shares no more. */

package/dist/voice.js

@@ -4,87 +4,33 @@ import { motionOf } from './motion.js';
 import { Named } from './named.js';
 import { childPlayed, Holding, mixTime, ownedElapsed, ownerPatch, ownerReading, turnedBack, } from './owner.js';
 import { builtOf, intosOf } from './patch.js';
-import { reading } from './reading.js';
-import { Store } from './store.js';
+import { keeping, VoiceSetting } from './setting.js';
+import { Filled, Store } from './store.js';
 import { warnOnce } from './warn.js';
 export const none = Object.freeze([]);
-/**
- * A voice's `setting.keep`, one per voice: a setting is valid only during its call, so the state
- * goes on the record of the subject being called for, `keepOn`, or on the voice before any is.
- */
-function keeping(voice) {
-    return function keep(owner, init) {
-        const held = voice.keepOn;
-        let kept = held === null ? voice.ownKept : held.kept;
-        if (kept === null) {
-            kept = new Map();
-            if (held === null)
-                voice.ownKept = kept;
-            else
-                held.kept = kept;
-        }
-        if (kept.has(owner))
-            return kept.get(owner);
-        const unkept = held?.unkept;
-        const made = unkept === undefined ? init() : unkept.shift();
-        if (unkept?.length === 0 && held !== null)
-            held.unkept = undefined;
-        kept.set(owner, made);
-        reading.kept++;
-        return made;
-    };
-}
-/**
- * A voice's setting. `keep` is made on first read: most patches keep no state, and a closure and
- * its context per voice cost a one-subject tween voice about 100 bytes.
- */
-class VoiceSetting {
-    host;
-    send;
-    voice;
-    timestamp = 0;
-    dt = 0;
-    elapsed = 0;
-    pass = 0;
-    weight = 0;
-    state = undefined;
-    kept = null;
-    constructor(host, send, voice) {
-        this.host = host;
-        this.send = send;
-        this.voice = voice;
-    }
-    get keep() {
-        if (this.kept === null)
-            this.kept = keeping(this.voice);
-        return this.kept;
-    }
+const noSend = () => { };
+/** By a mix's `slotOf`, the slots and lerps of a patch writing one channel, shared by its voices. */
+const writings = new WeakMap();
+function writing(writes, slotOf, channels) {
+    if (writes.length !== 1)
+        return written(writes, slotOf, channels);
+    let known = writings.get(slotOf);
+    if (known === undefined) {
+        known = new Map();
+        writings.set(slotOf, known);
+    }
+    const key = writes[0];
+    let found = known.get(key);
+    if (found === undefined) {
+        found = written(writes, slotOf, channels);
+        known.set(key, found);
+    }
+    return found;
 }
-/** A store that fills a missing entry from `make` on first ask. */
-class Filled extends Store {
-    make;
-    /** Keys deleted here, which are made afresh by whoever asks and never again by `make`. */
-    gone = null;
-    constructor(make) {
-        super();
-        this.make = make;
-    }
-    get(key) {
-        let v = super.get(key);
-        if (v === undefined && this.gone?.get(key) !== true) {
-            v = this.make(key);
-            if (v !== undefined)
-                super.set(key, v);
-        }
-        return v;
-    }
-    delete(key) {
-        super.delete(key);
-        this.gone ??= new Store();
-        this.gone.set(key, true);
-    }
+function written(writes, slotOf, channels) {
+    const slots = writes.map((k) => slotOf.get(k));
+    return { slots, lerps: slots.map((slot) => channels[slot].lerp) };
 }
-const noSend = () => { };
 export class Voice {
     id;
     spec;
@@ -226,6 +172,8 @@ export class Voice {
     outSet = false;
     /** The host time a pinned start was given at, NaN for none: a seek back pins it again. */
     pinned = Number.NaN;
+    /** Cued with no start while its mix slept, so the next sync sets its start. */
+    waking = false;
     /** Whether its start is still to be fixed by an anchor, so it waits pending. */
     placing = false;
     /** What each member of a join last answered, kept for once its target has left. */
@@ -249,6 +197,8 @@ export class Voice {
     unreachedBits = null;
     /** Whether one record stands for every subject: see `shares` in `everyone.ts`. */
     sharing = false;
+    /** Where its signal is declared 0, its cue's `within`, so it is not read there: see `bound.ts`. */
+    bound = null;
     /** The frames it has played sharing it. */
     shared = 0;
     /** That record, null until a chain first asks and once the voice shares no more. */
@@ -441,10 +391,11 @@ export class Voice {
         this.start = start;
         this.owner = owner;
         this.holding = patch === ownerPatch ? new Holding() : null;
-        this.slots = patch.writes.map((k) => slotOf.get(k));
+        const wrote = writing(patch.writes, slotOf, channels);
+        this.slots = wrote.slots;
         this.named = spec.subjects ? new Named(spec.subjects) : null;
         this.built = patch.form === 'keys' && patch.keys ? builtOf(patch) : null;
-        this.lerps = this.slots.map((slot) => channels[slot].lerp);
+        this.lerps = wrote.lerps;
         this.intos = this.built
             ? intosOf(this.built, this.slots.map((slot) => channels[slot]))
             : undefined;

package/dist/warn.d.ts

@@ -1,2 +1,4 @@
+/** Whether this is a production build: a bundler's `NODE_ENV`, or Node's; false where neither is. */
+export declare function production(): boolean;
 /** Warns outside production, once for each `about`. */
 export declare function warnOnce(about: object, message: string): void;

package/dist/warn.js

@@ -1,5 +1,5 @@
 /** Whether this is a production build: a bundler's `NODE_ENV`, or Node's; false where neither is. */
-function production() {
+export function production() {
     try {
         return process.env.NODE_ENV === 'production';
     }

package/dist/watch.d.ts

@@ -2,8 +2,8 @@ import type { Mixer } from './mixer.js';
 import type { MixOptions, Registry } from './types.js';
 type Any = Mixer<unknown, unknown>;
 /**
- * Every mix made on the page, shared by every copy of blits loaded: what a debugger reads to find
- * them. See `Registry`.
+ * The registry a debugger reads to find every mix made on the page. It is shared by every copy of
+ * blits loaded. See `Registry`.
  *
  * @category mix
  */

package/dist/watch.js

@@ -4,8 +4,8 @@ import { hostAhead } from './tape.js';
 const KEY = Symbol.for('@msb235/blits/watch/1');
 const slot = globalThis;
 /**
- * Every mix made on the page, shared by every copy of blits loaded: what a debugger reads to find
- * them. See `Registry`.
+ * The registry a debugger reads to find every mix made on the page. It is shared by every copy of
+ * blits loaded. See `Registry`.
  *
  * @category mix
  */
@@ -90,7 +90,9 @@ export function register(mix) {
         channels: mix.names,
         voice: (handle) => {
             const v = mix.cued.find((c) => c.handle === handle) ?? mix.gone.find((c) => c.handle === handle);
-            return v === undefined ? undefined : { name: v.spec.name, tags: v.spec.tags ?? [] };
+            return v === undefined
+                ? undefined
+                : { name: v.spec.name, tags: v.spec.tags ?? [], within: v.bound?.area };
         },
         label: (subject) => labelOf(mix, subject),
         watch: (fn) => tap(mix, fn),

package/dist/wave.d.ts

@@ -11,7 +11,7 @@ export type WaveShape = 'sine' | 'triangle' | 'saw' | 'square';
  * @category patch
  */
 export interface WaveOptions<O> {
-    /** Default 'sine'. */
+    /** The wave's form: 'sine', 'triangle', 'saw' or 'square'. Default 'sine'. */
     shape?: WaveShape;
     /** Whole or fractional cycles per pass of the patch's duration. Default 1. */
     cycles?: number;
@@ -27,13 +27,14 @@ export interface WaveOptions<O> {
     kit?: Partial<Kit<O>>;
 }
 /**
- * The unit wave: -1..1 at `x` cycles, starting at 0 and rising (square: +1 for the first half).
+ * The unit wave's value at `x` cycles, from -1 to 1. It starts at 0 and rises (square: +1 for the
+ * first half).
  *
  * @category patch
  */
 export declare function waveAt(shape: WaveShape, x: number): number;
 /**
- * A periodic swing on each channel `depth` names, around its rest: an LFO for a bob, a sway or a
+ * A periodic swing on each channel `depth` names, around its rest. An LFO for a bob, a sway or a
  * pulse. An `fn` patch that keeps its options on `patch.wave`, for an engine reading the wave
  * rather than calling it.
  *

package/dist/wave.js

@@ -1,6 +1,7 @@
 import { patch } from './patch.js';
 /**
- * The unit wave: -1..1 at `x` cycles, starting at 0 and rising (square: +1 for the first half).
+ * The unit wave's value at `x` cycles, from -1 to 1. It starts at 0 and rises (square: +1 for the
+ * first half).
  *
  * @category patch
  */
@@ -39,7 +40,7 @@ function planOf(opts) {
     return plan;
 }
 /**
- * A periodic swing on each channel `depth` names, around its rest: an LFO for a bob, a sway or a
+ * A periodic swing on each channel `depth` names, around its rest. An LFO for a bob, a sway or a
  * pulse. An `fn` patch that keeps its options on `patch.wave`, for an engine reading the wave
  * rather than calling it.
  *

package/dist/weigh.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';
 /**
  * Where `prime` reads its numbers in `Mixer.primed`: as arguments, each would be boxed wherever V8
  * does not inline the call, which turns on the order its compiles ran (bench/frame.mjs `glow`,
@@ -13,6 +14,11 @@ export declare const enum Primed {
 }
 /** Fills a voice's setting for a call to its patch, the weight aside, from `primed`. */
 export declare function prime<I, O>(this: Mixer<I, O>, voice: Voice<I, O>, held: Subject<unknown>): void;
+/**
+ * `prime` for a lane's call, from `arg`: the per-lane fields only where the setting was not
+ * already filled under `Arg.MARK`, since nothing but the engine writes a setting.
+ */
+export declare function primeLaned<I, O>(this: Mixer<I, O>, voice: Voice<I, O>, held: Subject<unknown>, arg: Float64Array): void;
 /** A gap as a `dt`: Infinity under reduced motion, and no more than `maxDt`. */
 export declare function capped<I, O>(this: Mixer<I, O>, gap: number): number;
 /** The earliest voice time a read may still ask for, for a subject delayed `delay`. */

package/dist/weigh.js

@@ -17,8 +17,35 @@ export function prime(voice, held) {
     setting.pass = pass;
     setting.weight = 0;
     setting.state = held.state;
+    setting.mark = 0;
     voice.keepOn = held;
 }
+/**
+ * `prime` for a lane's call, from `arg`: the per-lane fields only where the setting was not
+ * already filled under `Arg.MARK`, since nothing but the engine writes a setting.
+ */
+export function primeLaned(voice, held, arg) {
+    const now = this.now;
+    const setting = voice.setting;
+    if (setting.mark !== arg[6 /* Arg.MARK */])
+        markSetting(setting, now, arg);
+    if (voice.patch.step === undefined && held.probed < now)
+        held.stepped = held.probed;
+    setting.dt = this.capped(now - held.stepped);
+    setting.weight = 0;
+    setting.state = held.state;
+    voice.keepOn = held;
+}
+/**
+ * `primeLaned`'s once-a-lane fields, kept out of it so it fits `one`'s inlining budget beside
+ * `signalled`, which otherwise took its place (`glow^` 4.5% faster, 2026-10-28).
+ */
+function markSetting(setting, now, arg) {
+    setting.timestamp = now;
+    setting.elapsed = arg[1 /* Arg.ELAPSED */];
+    setting.pass = arg[3 /* Arg.PASS */];
+    setting.mark = arg[6 /* Arg.MARK */];
+}
 /** A gap as a `dt`: Infinity under reduced motion, and no more than `maxDt`. */
 export function capped(gap) {
     const cap = this.opts.maxDt;