@msb235/blits 0.14.0 → 0.15.0

package/dist/channels.d.ts

@@ -26,6 +26,11 @@ export interface Numeric {
     axes: number;
     /** An angle's full turn: each value is taken the short way round before it folds. */
     turn?: number;
+    /**
+     * An `'own'` channel whose fold is this plain arithmetic, its lerp alone its own: a lane folds
+     * it as the op and lerps it through the channel. A copy that predates it folds it as `'own'`.
+     */
+    folds?: 'sum';
 }
 /**
  * The stock arithmetic of a channel `sum`, `mul`, `max` or `vec` made, or `vouch` was given, keyed
@@ -55,49 +60,71 @@ export interface NumberOptions {
     bounds?: readonly [min: number, max: number];
 }
 /**
- * Position axes, rotation, crawl, yaw, pitch, offset.
+ * A number whose contributions add, resting at 0.
+ *
+ * A weight scales a contribution toward 0, so two voices each moving `x` by 10 at half weight move it
+ * 10 in all. For position axes, rotation, crawl, yaw, pitch, offset.
  *
  * @category channel
  */
 export declare function sum(opts?: NumberOptions): Channel<number>;
 /**
- * Gain, scale, opacity, hold.
+ * A number whose contributions multiply, resting at 1.
+ *
+ * A weight fades a contribution toward 1 rather than 0, so 0.5 at half weight multiplies by 0.75, and
+ * at weight 0 it leaves the value alone. For gain, scale, opacity, hold.
  *
  * @category channel
  */
 export declare function mul(opts?: NumberOptions): Channel<number>;
 /**
- * Dark, aperture.
+ * A number where the largest contribution wins, resting at 0.
+ *
+ * A weight scales a contribution toward 0 before the comparison, so a fading voice gives way once
+ * another's value passes its scaled one. For dark, aperture.
  *
  * @category channel
  */
 export declare function max(opts?: NumberOptions): Channel<number>;
 /**
- * A channel with no rest: the last contribution to pass wins, and a weight can only gate it. The
+ * What `last` takes.
+ *
+ * @category channel
+ */
+export interface LastOptions<V> {
+    /** How to interpolate between two values. Default: step at the midpoint. */
+    lerp?: (a: V, b: V, u: number) => V;
+}
+/**
+ * A channel with no rest, where the last contribution to pass wins. A weight can only gate it. The
  * default `lerp` steps at the midpoint, which is all a value with no arithmetic can promise; a
  * consumer with a real interpolation passes its own, as `hex` does.
  *
  * @category channel
  */
-export declare function last<V>(opts?: {
-    lerp?: (a: V, b: V, u: number) => V;
-}): Channel<V>;
+export declare function last<V>(opts?: LastOptions<V>): Channel<V>;
 /**
  * `n` copies of `v` in an array the engine stores as doubles from the start, so a copy of it, and
  * every fraction written into that copy, keeps one element kind: a pose's arrays then look alike to
  * every fold, whichever path made them.
  */
 export declare function doubles(n: number, v: number): number[];
-type Tuple<N extends number, T extends number[] = []> = T['length'] extends N ? T : Tuple<N, [...T, number]>;
 /**
- * `N` numbers: a tuple where `N` is a literal, as `Vec<3>` is `[number, number, number]`, and
- * `number[]` where it is only known to be a number.
+ * A tuple of `N` numbers, as `NumberTuple<3>` is `[number, number, number]`. `T` is the tuple built
+ * so far; leave it out.
+ *
+ * @category channel
+ */
+export type NumberTuple<N extends number, T extends number[] = []> = T['length'] extends N ? T : NumberTuple<N, [...T, number]>;
+/**
+ * `N` numbers, as a tuple where `N` is a literal. `Vec<3>` is `[number, number, number]`, and a
+ * `Vec` is `number[]` where `N` is only known to be a number.
  *
  * @category channel
  */
-export type Vec<N extends number> = number extends N ? number[] : Tuple<N>;
+export type Vec<N extends number> = number extends N ? number[] : NumberTuple<N>;
 /**
- * Vec3 position, premultiplied light: one channel's arithmetic applied down an axis list.
+ * One channel's arithmetic applied down an axis list. For a Vec3 position, or premultiplied light.
  *
  * @category channel
  */
@@ -108,4 +135,3 @@ export declare function vec<N extends number>(n: N, of: Channel<number>): Channe
  * @category channel
  */
 export declare function kit<O>(channels: Kit<O>): Kit<O>;
-export {};

package/dist/channels.js

@@ -67,7 +67,10 @@ export function scalarOp(channel) {
 /** Bounds change how a value folds at its edges, so they are part of the kind. */
 const kindOf = (name, bounds) => bounds === undefined ? name : `${name}[${bounds[0]}, ${bounds[1]}]`;
 /**
- * Position axes, rotation, crawl, yaw, pitch, offset.
+ * A number whose contributions add, resting at 0.
+ *
+ * A weight scales a contribution toward 0, so two voices each moving `x` by 10 at half weight move it
+ * 10 in all. For position axes, rotation, crawl, yaw, pitch, offset.
  *
  * @category channel
  */
@@ -84,7 +87,10 @@ export function sum(opts) {
     return channel;
 }
 /**
- * Gain, scale, opacity, hold.
+ * A number whose contributions multiply, resting at 1.
+ *
+ * A weight fades a contribution toward 1 rather than 0, so 0.5 at half weight multiplies by 0.75, and
+ * at weight 0 it leaves the value alone. For gain, scale, opacity, hold.
  *
  * @category channel
  */
@@ -101,7 +107,10 @@ export function mul(opts) {
     return channel;
 }
 /**
- * Dark, aperture.
+ * A number where the largest contribution wins, resting at 0.
+ *
+ * A weight scales a contribution toward 0 before the comparison, so a fading voice gives way once
+ * another's value passes its scaled one. For dark, aperture.
  *
  * @category channel
  */
@@ -118,7 +127,7 @@ export function max(opts) {
     return channel;
 }
 /**
- * A channel with no rest: the last contribution to pass wins, and a weight can only gate it. The
+ * A channel with no rest, where the last contribution to pass wins. A weight can only gate it. The
  * default `lerp` steps at the midpoint, which is all a value with no arithmetic can promise; a
  * consumer with a real interpolation passes its own, as `hex` does.
  *
@@ -148,7 +157,7 @@ export function doubles(n, v) {
     return a;
 }
 /**
- * Vec3 position, premultiplied light: one channel's arithmetic applied down an axis list.
+ * One channel's arithmetic applied down an axis list. For a Vec3 position, or premultiplied light.
  *
  * @category channel
  */

package/dist/color.d.ts

@@ -1,13 +1,14 @@
 import type { Channel } from './types.js';
 /**
- * OKLCH, hue the short way round, so a crossfade between hues keeps its lightness and saturation
- * instead of dipping through a muddy middle. A mix that leaves sRGB's gamut is clipped per channel.
+ * Crossfades two hex colors in OKLCH, hue the short way round. A crossfade between hues then keeps
+ * its lightness and saturation instead of dipping through a muddy middle. A mix that leaves sRGB's
+ * gamut is clipped per channel.
  *
  * @category channel
  */
 export declare function mixHex(a: number, b: number, u: number): number;
 /**
- * How a `color` channel interpolates two colors: straight across OKLab, or in OKLCH with hue the
+ * How a `color` channel interpolates two colors. Straight across OKLab, or in OKLCH with hue the
  * short way round, as `mixHex` does.
  *
  * @category channel
@@ -21,29 +22,30 @@ export interface ColorOptions {
  * `toHex` divides it out and lays it over what is under it. `color(last())` replaces, the last
  * voice to pass winning, at the coverage it was authored with. `lerp` picks how two colors
  * interpolate: OKLab, the default, crosses through gray between opposite hues, and `'oklch'`
- * goes round the hue instead, off lanes.
+ * goes round the hue instead.
  *
  * @category channel
  */
 export declare function color(opts?: ColorOptions): Channel<number[]>;
 export declare function color(of: Channel<number> | Channel<unknown>, opts?: ColorOptions): Channel<number[]>;
 /**
- * 0xrrggbb as a `color` value: OKLab `[L, a, b]` at full coverage. Convert keyframe stops once
- * when authoring them, and call it outside the hot path in an `fn` patch.
+ * Converts 0xrrggbb to a `color` value. The value is OKLab `[L, a, b]` at full coverage. Convert
+ * keyframe stops once when authoring them, and call it outside the hot path in an `fn` patch.
  *
  * @category channel
  */
 export declare function oklab(rgb: number): number[];
 /**
- * A `color` pose as 0xrrggbb: its color divided out of its coverage, the coverage capped at 1
- * and laid over `under` in OKLab, then clipped to sRGB per channel. No coverage gives `under`.
+ * A `color` pose as 0xrrggbb, laid over `under`. Its color is divided out of its coverage, the
+ * coverage capped at 1 and laid over `under` in OKLab, then clipped to sRGB per channel. No
+ * coverage gives `under`.
  *
  * @category channel
  */
 export declare function toHex(pose: ArrayLike<number>, under?: number): number;
 /**
- * A `color` pose as a CSS `oklab()` color with its coverage, capped at 1, as the alpha, for a
- * host that lets the browser lay it over what is under it.
+ * A `color` pose as a CSS `oklab()` color, its coverage as the alpha. The coverage is capped at 1.
+ * For a host that lets the browser lay it over what is under it.
  *
  * @category channel
  */

package/dist/color.js

@@ -82,8 +82,9 @@ function fromOklch(L, C, h) {
     return fromLab(L, C * Math.cos(h), C * Math.sin(h));
 }
 /**
- * OKLCH, hue the short way round, so a crossfade between hues keeps its lightness and saturation
- * instead of dipping through a muddy middle. A mix that leaves sRGB's gamut is clipped per channel.
+ * Crossfades two hex colors in OKLCH, hue the short way round. A crossfade between hues then keeps
+ * its lightness and saturation instead of dipping through a muddy middle. A mix that leaves sRGB's
+ * gamut is clipped per channel.
  *
  * @category channel
  */
@@ -98,14 +99,19 @@ export function mixHex(a, b, u) {
     const ah = slotH[sa];
     const sb = oklch(b);
     const bc = slotC[sb];
-    const from = ac < GRAY ? slotH[sb] : ah;
-    const to = bc < GRAY ? ah : slotH[sb];
+    const h = hueAt(ah, ac, slotH[sb], bc, u);
+    return fromOklch(mix(al, slotL[sb], u), mix(ac, bc, u), h);
+}
+/** The hue `u` of the way from `ah` to `bh` the short way round, a gray end taking the other's. */
+function hueAt(ah, ac, bh, bc, u) {
+    const from = ac < GRAY ? bh : ah;
+    const to = bc < GRAY ? ah : bh;
     let turn = to - from;
     if (turn > Math.PI)
         turn -= 2 * Math.PI;
     else if (turn < -Math.PI)
         turn += 2 * Math.PI;
-    return fromOklch(mix(al, slotL[sb], u), mix(ac, bc, u), from + turn * u);
+    return from + turn * u;
 }
 /** Two OKLab colors with coverage, interpolated in OKLCH: color by `u`, coverage by `u` alongside. */
 function lerpLch(x, y, u) {
@@ -126,17 +132,8 @@ function lerpLch(x, y, u) {
     const toB = yw > 0 ? yB : xB;
     const xc = Math.sqrt(xA * xA + xB * xB);
     const yc = Math.sqrt(toA * toA + toB * toB);
-    const xh = Math.atan2(xB, xA);
-    const yh = Math.atan2(toB, toA);
-    const from = xc < GRAY ? yh : xh;
-    const to = yc < GRAY ? xh : yh;
-    let turn = to - from;
-    if (turn > Math.PI)
-        turn -= 2 * Math.PI;
-    else if (turn < -Math.PI)
-        turn += 2 * Math.PI;
     const C = mix(xc, yc, u);
-    const h = from + turn * u;
+    const h = hueAt(Math.atan2(xB, xA), xc, Math.atan2(toB, toA), yc, u);
     return [mix(xL, toL, u) * w, C * Math.cos(h) * w, C * Math.sin(h) * w, w];
 }
 export function color(ofOrOpts, maybe) {
@@ -149,8 +146,11 @@ export function color(ofOrOpts, maybe) {
         (stock?.op === 'sum' && stock.turn === undefined && of.bounds === undefined)) {
         const channel = vec(4, sum());
         channel.kind = `color(sum${space})`;
-        // A lane interpolates a stock channel straight across, so a lerp of its own takes it off them.
-        return round ? { ...channel, lerp: lerpLch } : channel;
+        if (!round)
+            return channel;
+        const turning = { ...channel, lerp: lerpLch };
+        vouch(turning, { op: 'own', axes: 4, folds: 'sum' });
+        return turning;
     }
     if (of.kind === 'last') {
         const channel = {
@@ -159,15 +159,14 @@ export function color(ofOrOpts, maybe) {
             lerp: round ? lerpLch : vec(4, sum()).lerp,
         };
         widen(channel, 4);
-        if (!round)
-            vouch(channel, { op: 'last', axes: 4 });
+        vouch(channel, { op: 'last', axes: 4 });
         return channel;
     }
     throw new Error(`color takes sum() to average or last() to replace, not ${of.kind ?? 'a channel of its own'}`);
 }
 /**
- * 0xrrggbb as a `color` value: OKLab `[L, a, b]` at full coverage. Convert keyframe stops once
- * when authoring them, and call it outside the hot path in an `fn` patch.
+ * Converts 0xrrggbb to a `color` value. The value is OKLab `[L, a, b]` at full coverage. Convert
+ * keyframe stops once when authoring them, and call it outside the hot path in an `fn` patch.
  *
  * @category channel
  */
@@ -176,8 +175,9 @@ export function oklab(rgb) {
     return [LAB[0], LAB[1], LAB[2], 1];
 }
 /**
- * A `color` pose as 0xrrggbb: its color divided out of its coverage, the coverage capped at 1
- * and laid over `under` in OKLab, then clipped to sRGB per channel. No coverage gives `under`.
+ * A `color` pose as 0xrrggbb, laid over `under`. Its color is divided out of its coverage, the
+ * coverage capped at 1 and laid over `under` in OKLab, then clipped to sRGB per channel. No
+ * coverage gives `under`.
  *
  * @category channel
  */
@@ -195,8 +195,8 @@ export function toHex(pose, under = 0x000000) {
     return fromLab(mix(LAB[0], L, w), mix(LAB[1], A, w), mix(LAB[2], B, w));
 }
 /**
- * A `color` pose as a CSS `oklab()` color with its coverage, capped at 1, as the alpha, for a
- * host that lets the browser lay it over what is under it.
+ * A `color` pose as a CSS `oklab()` color, its coverage as the alpha. The coverage is capped at 1.
+ * For a host that lets the browser lay it over what is under it.
  *
  * @category channel
  */

package/dist/columns.js

@@ -22,6 +22,9 @@ export function pullRun(lanes, slots, list, was, since, from, columns, now, vers
     const frame = lanes.frameProbes;
     const subjects = lanes.subjects;
     const unlinked = lanes.unlinked;
+    const holds = lanes.holds;
+    // Nothing in `pullRun` makes a subject owe a voice, so one with nobody owing need not ask.
+    const owing = lanes.owed.any();
     const current = since === Number.POSITIVE_INFINITY;
     if (columns !== lanes.queuedFor) {
         flush(lanes);
@@ -47,14 +50,15 @@ export function pullRun(lanes, slots, list, was, since, from, columns, now, vers
             per[o + 0 /* Per.FILLED */] >= busy ||
             per[o + 2 /* Per.IDLE */] !== 0 ||
             per[o + 1 /* Per.SEEN */] < wide ||
-            lanes.owes(slot))
+            (owing && lanes.owes(slot)))
             break;
         if (!(per[o + 3 /* Per.LANE_PROBE */] > frame ||
             per[o + 4 /* Per.GENERAL_PROBE */] > frame))
             lanes.distinct++;
         per[o + 3 /* Per.LANE_PROBE */] = ++lanes.probes;
         per[o + 5 /* Per.LANE_FILL */] = fills;
-        subjects[slot] = subject;
+        if (holds)
+            subjects[slot] = subject;
         if (slot !== first + (n - start)) {
             if (first >= 0) {
                 qSlots[k] = first;
@@ -73,7 +77,7 @@ export function pullRun(lanes, slots, list, was, since, from, columns, now, vers
         k++;
     }
     lanes.queued = k;
-    if (n > from)
+    if (n > from && holds)
         lanes.holding = true;
     return n;
 }

package/dist/contribution.d.ts

@@ -0,0 +1,30 @@
+import type { Mixer } from './mixer.js';
+import type { Subject } from './subject.js';
+import { type Voice } from './voice.js';
+/**
+ * One live voice's delta for one subject this frame, through its record for the subject, or null
+ * when it does not reach. Its weight is left in `w`.
+ */
+export declare function contribution<I, O>(this: Mixer<I, O>, voice: Voice<I, O>, subject: I, now: number, held: Subject<unknown>): Record<string, unknown> | null;
+/** Reads a keys voice's stops at `held.phase` into the subject's delta, through the voice's scratch. */
+export declare function keyed<I, O>(this: Mixer<I, O>, voice: Voice<I, O>, subject: I, held: Subject<unknown>): Record<string, unknown>;
+/**
+ * Runs `step` once per whole interval between where this subject last stopped and now, on a grid
+ * counted from when its delay ran out, and leaves the remainder for the next sample. Counting
+ * rather than adding keeps the grid where it is however many samples it is reached through.
+ */
+export declare function tick<I, O>(this: Mixer<I, O>, voice: Voice<I, O>, subject: I, held: Subject<unknown>, tick: number, to: number): void;
+/**
+ * Stop 0 for a retargeting voice: the subject's pose in the frame before this voice contributes.
+ * With no such frame on record — a voice cued before the subject was ever probed, or a host that
+ * samples into its own object — it is this frame's pose with every other voice folded in.
+ */
+export declare function baseFor<I, O>(this: Mixer<I, O>, voice: Voice<I, O>, subject: I): Record<string, unknown>;
+/**
+ * How fast each numeric channel this voice writes was moving, from the subject's last two probed
+ * poses, in units per ms. Undefined with fewer than two on record, which starts the voice at rest.
+ */
+export declare function slopeFor<I, O>(this: Mixer<I, O>, voice: Voice<I, O>, subject: I): Record<string, unknown> | undefined;
+export declare function isRest<I, O>(this: Mixer<I, O>, delta: Record<string, unknown>): boolean;
+/** `contribution`, or for a dry fold a subject already probed this frame, without advancing it. */
+export declare function read<I, O>(this: Mixer<I, O>, voice: Voice<I, O>, subject: I, now: number, dry: boolean, held: Subject<unknown>): Record<string, unknown> | null;