@msb235/blits 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -4,6 +4,146 @@ 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.4.0
+
+### Breaking
+
+- A tween's `MotionSpec` reads `ms: undefined` where its `ms` is a function of the subject.
+- `Handle.state` can read `'held'`. Only a voice cued with `hold` reaches it, so nothing changes at
+  run time for one cued without, but a `switch` over every state no longer covers them all.
+
+### Added
+
+- `mix.inert` is true when another frame would change no pose, so a host's loop may sleep while
+  `live` is still true: every voice is done, held after its passes at a plain weight, or a motion
+  whose every subject has landed on its target. A retarget, a fade or a cue makes it false again.
+- `handle.fade({ subject, over })` fades one subject out of a voice, which plays on for the rest.
+  Once the ramp ends the voice forgets the subject (its record, its lane position and a motion
+  patch's state for it) and no longer reaches it; a motion patch's `to` brings it back, met afresh.
+  `mix.drop(subject)` clears it too. It keeps the voice on its lane.
+- `tween`'s `ms` may be a function of the subject, asked each time one of its stretches starts.
+- `hold: 'before' | 'after' | 'both'` on a voice. Before, a subject shows the voice's first frame
+  while the voice is pending and while the subject waits out its `stagger`; after, a finite loop
+  shows its last frame once its passes are done and stays, `held`, until faded. `fade.in` counts
+  from the first frame shown. What WAAPI calls `fill`.
+- `handle.played` resolves true when a finite loop's last pass ends, false if the voice leaves
+  first. It never rejects.
+
+### Fixed
+
+- A `keys` or stateless `fn` voice naming one subject and writing one channel fills from its
+  channel's crowd, as a motion voice does, where it took the general path. On teitou 10k `fn`
+  voices of one subject each read by `pull` take 0.7 of the time they did.
+- A voice naming its subjects that is cued, starts or retires relinks only those subjects, and
+  joins or leaves its crowd in place, where it made every subject relink and the lanes qualify
+  every voice again: a frame stopping one of 10k such voices and cueing another fell from about
+  9 ms to 0.6 by `pull` on teitou. `mix.drop` looks only at the voices over every subject and
+  those naming the one dropped, where it walked every voice.
+- `mix.drop` frees a subject from a voice faded off it with `handle.fade({ subject })`, and a mix
+  whose last ramp of that kind is dropped can read `inert` again; it also frees the subject from a
+  motion patch that another voice plays on after the voice naming the subject left.
+- `pull` reads a list it read before in the same order from the lanes in one run, checking the
+  frame once rather than per subject: a tween voice over 10k subjects read by `pull` takes about
+  0.83 of the time it did on teitou.
+- A lane gives a `vec(1)` channel an array of one, as the general path does, where it gave a
+  bare number; and a motion voice on one folds without making an array per subject per frame.
+- A `tween` divides elapsed by its length in milliseconds, so a point a whole fraction of the way
+  in lands exactly: 150 ms into a 200 ms linear tween from 0 to 100 reads 75, not 74.99999999999999.
+- `pull` over a list read again in the same order skips looking each subject up, and copies lane
+  values a column at a time; a motion voice's lane fills in one loop. One tween voice over 10k
+  subjects read by `pull` takes 0.59–0.66 of the time it did on teitou; a spring 0.68–0.74.
+- Motion voices of one subject each fill from one crowd of flat rows per channel, and `sync` visits
+  only voices with something due: 10k tween voices of one subject each take 0.54–0.59 of the time
+  they did on teitou, 100k take 0.31–0.33.
+
+## 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

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.4.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.
 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,5 +1,31 @@
 import type { Channel, Kit } from './types.js';
-/** What a stock numeric channel takes. */
+/**
+ * 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];
@@ -39,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,4 +1,34 @@
 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]}]`;
 /**
@@ -7,14 +37,16 @@ const kindOf = (name, bounds) => bounds === undefined ? name : `${name}[${bounds
  * @category channel
  */
 export function sum(opts) {
-    return {
+    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.
@@ -22,14 +54,16 @@ export function sum(opts) {
  * @category channel
  */
 export function mul(opts) {
-    return {
+    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.
@@ -37,14 +71,16 @@ export function mul(opts) {
  * @category channel
  */
 export function max(opts) {
-    return {
+    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
@@ -61,16 +97,37 @@ 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,
@@ -95,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;
@@ -120,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

@@ -2,8 +2,8 @@ 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';