@msb235/blits 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -4,6 +4,102 @@ This package follows [semver](https://semver.org). Below 1.0.0, a breaking chang
 version and everything else the patch. Each release lists its changes as **Breaking**, **Added** and
 **Fixed**, and the release workflow refuses a tag with no section here.
 
+## 0.3.0
+
+### Breaking
+
+- `spring` and `glide` build patches of a third form, `'motion'`, instead of `'fn'`, and carry
+  their kind and constants on `patch.motion`, a `MotionSpec`. `Patch.form` and `Engine.runs` take
+  `'motion'`, so an engine that declares `runs` must list it to run a spring or a glide. A motion
+  patch throws when two of its subjects, or a subject's start, target and velocity, or a `to` or
+  `push`, move on different numbers of axes. It makes a subject's first stretch at its first `to`
+  or `push` as well as at its first read, so `read(subject, at)` answers from then on.
+- An untimed retarget lands at the subject's own voice time at the mix's latest sync, not at the
+  subject's next read, so a subject the host did not probe changes at the same moment as one it
+  did; `read` with no time answers at that time, counting every change due by then. For a subject
+  no frame of its voice has met yet, or still inside its stagger, an untimed change applies at its
+  first read, after any timed change due by then, and `read` with no time returns undefined, as it
+  does once the voice is gone. Changes apply in time order, not the order they were made.
+- `drop(subject)` also forgets a motion patch's state for the subject, so it starts afresh.
+- With lanes on, a stateless patch calling `setting.send` from `at` sends every frame for every
+  subject the mix has met, probed that frame or not; and a patch that first calls `setting.keep`
+  partway through playing can advance that state once more for one subject the host did not probe
+  that frame.
+- `mixHex`, and so the `hex` channel, blends in OKLCH rather than sRGB, taking hue the short way
+  round and a gray end's hue from the other end. A crossfade from red to blue passes through
+  0xba00c2 rather than 0x800080, and black to white through 0x636363 rather than 0x808080. A blend
+  costs about 45 ns where the two ends repeat frame to frame and 210 ns where every call brings new
+  colors, against 8 ns in sRGB. `hex({ space: 'srgb' })` keeps the sRGB blend.
+- `Mix` has a `pull` method, so an engine's `create` must return a mix that implements it.
+
+### Added
+
+- `tween(writes, { from, to, ms, ease? })`, a motion patch that eases each subject from one value
+  to another over `ms`, with `from` and `to` given per subject and read once when the mix first
+  meets it. `to(subject, target)` retargets one subject from where it is over a full `ms` again,
+  and `read` reports value and velocity as a spring's does. It runs on lanes as springs do, with
+  each subject's endpoints as data, so a tween over every subject no longer needs a `fn` that looks
+  its endpoints up on each call: in weasel's shape (10,000 string ids, endpoints in a map) a frame
+  costs 0.83 of that `fn`'s and pauses for collection a quarter as long. A motion lane no longer
+  allocates a delta per subject either, which takes a spring frame over 10,000 subjects to
+  0.82–0.90 of the last build's. `MotionSpec` gains
+  `{ kind: 'tween', ms, ease }`.
+- Lanes: a channel every voice writing it can run that way is computed for every subject at once,
+  in flat arrays, at the frame's first probe, rather than subject by subject, and gives the same
+  pose. `keys`, a stateless `fn` and `motion` voices with a number weight qualify. Three `keys`
+  voices over 10,000 subjects fell from 6.1 to 2.6 ms a frame. A lane whose subjects were mostly
+  left unprobed last frame stops filling and its subjects take the general path until probes pick
+  up again, so a host probing 5% of 10,000 subjects pays about what it would with lanes off, not
+  ten times it. `MixOptions.lanes: false` turns lanes off. They cost a little on frames they
+  don't serve: a voice per subject reads up to 7% slower at 10,000 subjects (about 20% at
+  100–1,000, a few hundredths of a millisecond), a mix probing few of its subjects about 0.03 ms
+  more, and a projection made every frame about 10% more.
+- `mix.pull(subjects, { channel: Float64Array, ... })` writes each subject's pose into one array per
+  channel, in the order given, giving what `probe(subject, out)` gives without a pose object per
+  subject. A channel of `n` numbers takes `n` places a subject; one with no value writes NaN. While
+  every voice runs on a lane it copies straight from the lanes: a frame of three `keys` voices
+  over 10,000 subjects costs 0.84 of the same frame read through `probe`, a spring 0.91.
+- `mix.project(timestamp)` reads the mix at another time without moving it: `probe` gives the pose
+  then, and `assess` says per channel whether it is `exact`, `stepped` or `held`. Ahead it plays
+  what is cued forward; behind it needs `MixOptions.history: { ms, every? }`, which keeps every
+  handle change, the voices that left, and copies of stateful state, so a read back under `stepMs`
+  lands on the pose the mix showed, and with `inputs` it records what input weight signals and the
+  host fields patches `reads` held, so a read back over a `level` or a pointer is known. `Patch.clone` copies state `structuredClone` cannot.
+- The score: a voice takes a `name` and an `anchor` placement, `start` or `in` and `out` or `end`,
+  each a timestamp or another voice's mark (`after`, `with`, `before`, or `of` plus `mark`),
+  selected by name, tag or written channel with a resolver. Each source can keep its own `score`,
+  with names namespaced per score. `mix.announce(name, { at? })` puts a named mark on a score for
+  anchors to wait on, and `mix.marks(from, to)` lists every mark the plan knows.
+- `spring` and `glide` keep every stretch within the mix's history, so a read before a retarget
+  finds where the subject was.
+- A cue can name its subjects, `subjects: [a, b]`, in place of a `target`. The mix files the voice
+  under each one, so a voice per subject costs the same as one voice: the first frame of 1,000
+  subjects on a voice each fell from about 500 ms to 1 ms.
+
+### Fixed
+
+- A voice faded before its start plays once its start arrives. It used to stay out of every
+  subject's fold until some other voice was cued or left.
+- A probe after a `seek` in the same frame reads the voice where the seek put it, rather than the
+  value an earlier probe that frame read before the seek. A stateful patch still steps once.
+- A probe looks its subject up once rather than once per voice, which makes frames with several
+  voices 5–12% faster.
+- A `keys` patch reads a keyed `vec` channel into an array its voice reuses, rather than a new one
+  each read, which halves collections at 10,000 subjects and leaves frame time unchanged.
+
+- A finite loop's fade out starts when its last pass ended, not at the first frame after, so it
+  plays the same at any frame rate.
+- The published `package.json` no longer lists `workspaces: ["site"]`, which only the repo's docs
+  site uses.
+
+## 0.2.1
+
+### Added
+
+- Channel `bounds`: `sum`, `mul` and `max` take `{ bounds: [min, max] }`, and `vec` inherits its
+  axis channel's. The mix clamps the folded value to the range, so stacked voices and a retarget
+  that carries speed stop flat at the bound. Bounds are part of the channel's kind.
+
 ## 0.2.0
 
 ### Breaking

package/README.md

@@ -68,10 +68,17 @@ npm run site:smoke   # build, then load every page headless and fail on any erro
 `.github/workflows/site.yml` deploys it to GitHub Pages. It runs only by hand until Pages is enabled
 on the repo.
 
+## Packages
+
+`packages/quarks` is `@msb235/blits-quarks`, a driver that turns poses into
+[three.quarks](https://github.com/Alchemist0823/three.quarks) particles. It is published separately
+so the engine keeps no dependencies; its README says how it works.
+
 ## Status
 
-v0.1.0, and one real consumer: [klieg](https://github.com/orochi235/klieg) composes all three of
-its systems — letter motion, part effects, and the environment a sign is lit by — on a mix each.
+v0.3.0, with two consumers. magicsmoke runs every fault on it, and
+[klieg](https://github.com/orochi235/klieg) composes all three of its systems — letter motion,
+part effects, and the environment a sign is lit by — on a mix each, on a branch not yet merged.
 That port was an extraction rather than a rewrite, so it is also the evidence that the arithmetic
 here is the arithmetic a working renderer already had: klieg's suite of 1974 cases and its
 screenshot baselines came through it unchanged.

package/dist/channels.d.ts

@@ -1,22 +1,53 @@
 import type { Channel, Kit } from './types.js';
+/**
+ * Writes `lerp(a, b, u)` into `out` and returns it, or returns a new array where `out` is absent or
+ * the wrong length. The caller must own `out`: nothing else may hold it.
+ */
+export type LerpInto = (out: unknown[] | undefined, a: unknown, b: unknown, u: number) => unknown[];
+/**
+ * The in-place form of a stock array channel's `lerp`. Keyed by the channel rather than its `lerp`,
+ * since only the stock fold and merge are known to copy the array rather than keep it.
+ */
+export declare function lerpInto(channel: Channel<unknown>): LerpInto | undefined;
+/** What a lane needs of a stock numeric channel beyond the channel: its arithmetic by name, its axes. */
+export interface Numeric {
+    op: 'sum' | 'mul' | 'max';
+    axes: number;
+}
+/**
+ * The stock arithmetic of a channel `sum`, `mul`, `max` or `vec` made, keyed by the object itself,
+ * so a custom channel that claims a stock `kind` is not trusted with a lane.
+ */
+export declare function numericOf(channel: Channel<unknown>): Numeric | undefined;
+/** `merge(acc, scale(v, w))` for a stock numeric channel, in exactly its arithmetic. */
+export declare function foldNumber(op: Numeric['op'], acc: number, v: number, w: number): number;
+/**
+ * What a stock numeric channel takes.
+ *
+ * @category channel
+ */
+export interface NumberOptions {
+    /** The range the value means anything in; the mix clamps to it. */
+    bounds?: readonly [min: number, max: number];
+}
 /**
  * Position axes, rotation, crawl, yaw, pitch, offset.
  *
  * @category channel
  */
-export declare function sum(): Channel<number>;
+export declare function sum(opts?: NumberOptions): Channel<number>;
 /**
  * Gain, scale, opacity, hold.
  *
  * @category channel
  */
-export declare function mul(): Channel<number>;
+export declare function mul(opts?: NumberOptions): Channel<number>;
 /**
  * Dark, aperture.
  *
  * @category channel
  */
-export declare function max(): Channel<number>;
+export declare function max(opts?: NumberOptions): Channel<number>;
 /**
  * A channel with no rest: the last influence to pass wins, and a weight can only gate it. The
  * default `lerp` steps at the midpoint, which is all a value with no arithmetic can promise; a
@@ -34,18 +65,21 @@ export declare function last<V>(opts?: {
  */
 export declare function vec(n: number, of: Channel<number>): Channel<number[]>;
 /**
- * sRGB, which is what klieg's light channel already assumes, so the port's arithmetic is
- * unchanged. OKLCH reads better across hues and is the open question, not a second function.
+ * 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.
  *
  * @category channel
  */
 export declare function mixHex(a: number, b: number, u: number): number;
 /**
- * Color, as 0xrrggbb.
+ * Color, as 0xrrggbb, blended in OKLCH as `mixHex` does, or with `space: 'srgb'` channel by
+ * channel in sRGB, which keeps a port's arithmetic identical to a host that blended that way.
  *
  * @category channel
  */
-export declare function hex(): Channel<number>;
+export declare function hex(opts?: {
+    space?: 'oklch' | 'srgb';
+}): Channel<number>;
 /**
  * A kit is plain data; this only fixes the type.
  *

package/dist/channels.js

@@ -1,45 +1,86 @@
 const mix = (a, b, u) => a + (b - a) * u;
+const inPlace = new WeakMap();
+/**
+ * The in-place form of a stock array channel's `lerp`. Keyed by the channel rather than its `lerp`,
+ * since only the stock fold and merge are known to copy the array rather than keep it.
+ */
+export function lerpInto(channel) {
+    return inPlace.get(channel);
+}
+/** The stock channels' arithmetic, once: their `merge` and `scale` are these, and so is `foldNumber`. */
+const add = (a, b) => a + b;
+const times = (v, w) => v * w;
+const product = (a, b) => a * b;
+const toward = (v, w) => 1 + (v - 1) * w;
+const larger = (a, b) => (a > b ? a : b);
+const numerics = new WeakMap();
+/**
+ * The stock arithmetic of a channel `sum`, `mul`, `max` or `vec` made, keyed by the object itself,
+ * so a custom channel that claims a stock `kind` is not trusted with a lane.
+ */
+export function numericOf(channel) {
+    return numerics.get(channel);
+}
+/** `merge(acc, scale(v, w))` for a stock numeric channel, in exactly its arithmetic. */
+export function foldNumber(op, acc, v, w) {
+    if (op === 'sum')
+        return add(acc, times(v, w));
+    if (op === 'mul')
+        return product(acc, toward(v, w));
+    return larger(acc, times(v, w));
+}
+/** 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.
  *
  * @category channel
  */
-export function sum() {
-    return {
-        kind: 'sum',
+export function sum(opts) {
+    const channel = {
+        kind: kindOf('sum', opts?.bounds),
+        bounds: opts?.bounds,
         rest: 0,
-        merge: (a, b) => a + b,
-        scale: (v, w) => v * w,
+        merge: add,
+        scale: times,
         lerp: mix,
     };
+    numerics.set(channel, { op: 'sum', axes: 1 });
+    return channel;
 }
 /**
  * Gain, scale, opacity, hold.
  *
  * @category channel
  */
-export function mul() {
-    return {
-        kind: 'mul',
+export function mul(opts) {
+    const channel = {
+        kind: kindOf('mul', opts?.bounds),
+        bounds: opts?.bounds,
         rest: 1,
-        merge: (a, b) => a * b,
-        scale: (v, w) => 1 + (v - 1) * w,
+        merge: product,
+        scale: toward,
         lerp: mix,
     };
+    numerics.set(channel, { op: 'mul', axes: 1 });
+    return channel;
 }
 /**
  * Dark, aperture.
  *
  * @category channel
  */
-export function max() {
-    return {
-        kind: 'max',
+export function max(opts) {
+    const channel = {
+        kind: kindOf('max', opts?.bounds),
+        bounds: opts?.bounds,
         rest: 0,
-        merge: (a, b) => (a > b ? a : b),
-        scale: (v, w) => v * w,
+        merge: larger,
+        scale: times,
         lerp: mix,
     };
+    numerics.set(channel, { op: 'max', axes: 1 });
+    return channel;
 }
 /**
  * A channel with no rest: the last influence to pass wins, and a weight can only gate it. The
@@ -56,17 +97,39 @@ export function last(opts) {
         lerp: opts?.lerp ?? ((a, b, u) => (u < 0.5 ? a : b)),
     };
 }
+/**
+ * `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.
+ */
+function doubles(n, v) {
+    if (n === 0)
+        return [];
+    const a = [0.5];
+    for (let i = 1; i < n; i++)
+        a.push(0.5);
+    for (let i = 0; i < n; i++)
+        a[i] = v;
+    return a;
+}
 /**
  * Vec3 position, premultiplied light: one channel's arithmetic applied down an axis list.
  *
  * @category channel
  */
 export function vec(n, of) {
-    const rest = of.rest === undefined ? undefined : new Array(n).fill(of.rest);
+    const rest = of.rest === undefined ? undefined : doubles(n, of.rest);
     const scale = of.scale;
     const fill = of.rest ?? 0;
-    return {
+    const lerpTo = (out, a, b, u) => {
+        const o = out?.length === n ? out : new Array(n);
+        for (let i = 0; i < n; i++)
+            o[i] = of.lerp(a[i] ?? fill, b[i] ?? fill, u);
+        return o;
+    };
+    const channel = {
         kind: of.kind === undefined ? undefined : `vec(${n}, ${of.kind})`,
+        bounds: of.bounds,
         rest,
         merge: (a, b) => {
             const out = new Array(n);
@@ -89,22 +152,113 @@ export function vec(n, of) {
                     into[i] = of.merge(into[i] ?? fill, scale(v[i] ?? fill, w));
                 return into;
             },
-        lerp: (a, b, u) => {
-            const out = new Array(n);
-            for (let i = 0; i < n; i++)
-                out[i] = of.lerp(a[i] ?? fill, b[i] ?? fill, u);
-            return out;
-        },
+        lerp: (a, b, u) => lerpTo(undefined, a, b, u),
     };
+    inPlace.set(channel, lerpTo);
+    const inner = numerics.get(of);
+    if (inner !== undefined && inner.axes === 1)
+        numerics.set(channel, { ...inner, axes: n });
+    return channel;
 }
-const clamp255 = (v) => (v < 0 ? 0 : v > 255 ? 255 : Math.round(v));
+const LINEAR = Array.from({ length: 256 }, (_, c) => {
+    const v = c / 255;
+    return v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4;
+});
+/** The linear value halfway between byte c - 1 and c: at or above it, a value rounds to c. */
+const ROUNDS_UP = LINEAR.map((_, c) => {
+    const v = (c - 0.5) / 255;
+    return v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4;
+});
+/** The byte each 1/4096 of linear light starts at; a bin holds at most one rounding point. */
+const BINS = 4096;
+const FIRST = Array.from({ length: BINS + 1 }, (_, i) => {
+    let c = 0;
+    while (c < 255 && i / BINS >= ROUNDS_UP[c + 1])
+        c++;
+    return c;
+});
+const toByte = (v) => {
+    if (v <= 0)
+        return 0;
+    if (v >= 1)
+        return 255;
+    const c = FIRST[(v * BINS) | 0];
+    return c < 255 && v >= ROUNDS_UP[c + 1] ? c + 1 : c;
+};
+/** Below this chroma a color is gray and its hue is noise, so the lerp takes the other end's. */
+const GRAY = 1e-4;
 /**
- * sRGB, which is what klieg's light channel already assumes, so the port's arithmetic is
- * unchanged. OKLCH reads better across hues and is the open question, not a second function.
+ * Colors already turned into OKLCH, direct-mapped on a byte of their hash: a mix reads the same
+ * few keyframe colors every frame, and the table stays 256 colors however many it meets.
+ */
+const SLOTS = 256;
+const slotColor = new Int32Array(SLOTS).fill(-1);
+const slotL = new Float64Array(SLOTS);
+const slotC = new Float64Array(SLOTS);
+const slotH = new Float64Array(SLOTS);
+/** 0xrrggbb to its slot, filled with [L, C, h], h in radians; Björn Ottosson's OKLab matrices. */
+function oklch(rgb) {
+    const slot = Math.imul(rgb, 0x9e3779b1) >>> 24;
+    if (slotColor[slot] === rgb)
+        return slot;
+    const r = LINEAR[(rgb >> 16) & 0xff];
+    const g = LINEAR[(rgb >> 8) & 0xff];
+    const b = LINEAR[rgb & 0xff];
+    const l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b);
+    const m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b);
+    const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b);
+    const A = 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s;
+    const B = 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s;
+    slotColor[slot] = rgb;
+    slotL[slot] = 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s;
+    slotC[slot] = Math.sqrt(A * A + B * B);
+    slotH[slot] = Math.atan2(B, A);
+    return slot;
+}
+/** [L, C, h] to 0xrrggbb, clipping each channel to sRGB's gamut. */
+function fromOklch(L, C, h) {
+    const A = C * Math.cos(h);
+    const B = C * Math.sin(h);
+    const l_ = L + 0.3963377774 * A + 0.2158037573 * B;
+    const m_ = L - 0.1055613458 * A - 0.0638541728 * B;
+    const s_ = L - 0.0894841775 * A - 1.291485548 * B;
+    const l = l_ * l_ * l_;
+    const m = m_ * m_ * m_;
+    const s = s_ * s_ * s_;
+    const r = 4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s;
+    const g = -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s;
+    const b = -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s;
+    return (toByte(r) << 16) | (toByte(g) << 8) | toByte(b);
+}
+/**
+ * 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.
  *
  * @category channel
  */
 export function mixHex(a, b, u) {
+    if (u === 0 || a === b)
+        return a;
+    if (u === 1)
+        return b;
+    const sa = oklch(a);
+    const al = slotL[sa];
+    const ac = slotC[sa];
+    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];
+    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);
+}
+const clamp255 = (v) => (v < 0 ? 0 : v > 255 ? 255 : Math.round(v));
+/** Each of red, green and blue on its own, as klieg's light channel blends. */
+function mixSrgb(a, b, u) {
     const ar = (a >> 16) & 0xff;
     const ag = (a >> 8) & 0xff;
     const ab = a & 0xff;
@@ -114,12 +268,13 @@ export function mixHex(a, b, u) {
     return ((clamp255(mix(ar, br, u)) << 16) | (clamp255(mix(ag, bg, u)) << 8) | clamp255(mix(ab, bb, u)));
 }
 /**
- * Color, as 0xrrggbb.
+ * Color, as 0xrrggbb, blended in OKLCH as `mixHex` does, or with `space: 'srgb'` channel by
+ * channel in sRGB, which keeps a port's arithmetic identical to a host that blended that way.
  *
  * @category channel
  */
-export function hex() {
-    return { ...last({ lerp: mixHex }), kind: 'hex' };
+export function hex(opts) {
+    return { ...last({ lerp: opts?.space === 'srgb' ? mixSrgb : mixHex }), kind: 'hex' };
 }
 /**
  * A kit is plain data; this only fixes the type.

package/dist/clock.d.ts

@@ -0,0 +1,19 @@
+import type { Curve } from './easing.js';
+/** How many passes a voice's `loop` plays. */
+export declare function passesOf(loop: boolean | number | undefined): number;
+/**
+ * The phase `elapsed` voice ms into a patch of `period` ms playing `passes` passes, held at 1 once
+ * they are done. A pure function rather than one writing phase and pass together, so a hot caller
+ * keeps both in registers.
+ */
+export declare function phaseAt(elapsed: number, period: number, passes: number): number;
+/** The pass `elapsed` voice ms falls in, held at the last once they are done. */
+export declare function passAt(elapsed: number, period: number, passes: number): number;
+/** A voice's own fade this frame, 0..1: in from `since` over `fadeIn`, and out along its ramp. */
+export declare function envelope(fadeIn: number, out: {
+    at: number;
+    over: number;
+    rest: boolean;
+} | null, ease: Curve | undefined, reduced: boolean, now: number, since: number): number;
+/** A weight held to 0..1. */
+export declare function clampWeight(raw: number): number;

package/dist/clock.js

@@ -0,0 +1,44 @@
+/** How many passes a voice's `loop` plays. */
+export function passesOf(loop) {
+    const l = loop ?? true;
+    return l === true ? Number.POSITIVE_INFINITY : l === false ? 1 : l;
+}
+/** Whether `elapsed` voice ms is past the last of `passes` passes of a patch of `period` ms. */
+const over = (elapsed, period, passes) => Number.isFinite(passes) && elapsed >= period * passes;
+/**
+ * The phase `elapsed` voice ms into a patch of `period` ms playing `passes` passes, held at 1 once
+ * they are done. A pure function rather than one writing phase and pass together, so a hot caller
+ * keeps both in registers.
+ */
+export function phaseAt(elapsed, period, passes) {
+    if (!(period > 0))
+        return 0;
+    return over(elapsed, period, passes) ? 1 : (elapsed % period) / period;
+}
+/** The pass `elapsed` voice ms falls in, held at the last once they are done. */
+export function passAt(elapsed, period, passes) {
+    if (!(period > 0))
+        return 0;
+    return over(elapsed, period, passes) ? passes - 1 : Math.floor(elapsed / period);
+}
+/** A voice's own fade this frame, 0..1: in from `since` over `fadeIn`, and out along its ramp. */
+export function envelope(fadeIn, out, ease, reduced, now, since) {
+    let w = 1;
+    if (fadeIn > 0 && !reduced) {
+        const u = (now - since) / fadeIn;
+        if (u < 1)
+            w *= ease ? ease(Math.max(0, u)) : Math.max(0, u);
+    }
+    if (out && !out.rest) {
+        if (reduced || out.over === 0)
+            return 0;
+        const u = 1 - (now - out.at) / out.over;
+        const clamped = u < 0 ? 0 : u > 1 ? 1 : u;
+        w *= ease ? ease(clamped) : clamped;
+    }
+    return w;
+}
+/** A weight held to 0..1. */
+export function clampWeight(raw) {
+    return raw < 0 ? 0 : raw > 1 ? 1 : raw;
+}

package/dist/index.d.ts

@@ -1,8 +1,9 @@
+export type { NumberOptions } from './channels.js';
 export { hex, kit, last, max, mixHex, mul, sum, vec } from './channels.js';
 export { mix, mixer } from './mixer.js';
 export type { Motion, Moving, PerSubject, Value } from './motion.js';
-export { glide, spring } from './motion.js';
+export { glide, spring, tween } from './motion.js';
 export type { KeysOptions, PatchOptions } from './patch.js';
 export { keys, patch } from './patch.js';
 export { gate, lag, level, peak, slew } from './signals.js';
-export type { Channel, Easing, Engine, FadeOptions, FadeSpec, Handle, Keyframe, Kit, Mix, MixOptions, Patch, Sent, Setting, Signal, VoiceSpec, } from './types.js';
+export type { Anchor, Channel, Columns, Doubt, Easing, Engine, FadeOptions, FadeSpec, Handle, Keyframe, Kit, Mark, Marked, Mix, MixOptions, MotionSpec, Patch, Placement, Projection, Query, Sent, Setting, Signal, VoiceSpec, } from './types.js';

package/dist/index.js

@@ -1,5 +1,5 @@
 export { hex, kit, last, max, mixHex, mul, sum, vec } from './channels.js';
 export { mix, mixer } from './mixer.js';
-export { glide, spring } from './motion.js';
+export { glide, spring, tween } from './motion.js';
 export { keys, patch } from './patch.js';
 export { gate, lag, level, peak, slew } from './signals.js';