@msb235/blits 0.6.0 → 0.7.1

package/CHANGELOG.md

@@ -4,6 +4,158 @@ 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.7.1
+
+### Fixed
+
+- Under `history`, a mix whose subjects come and go no longer slows as the voices that have left
+  pile up. `drop` and a freed slot visit only the voices that left that can hold the subject,
+  history lets go of them from the front of the list, and the tape is pruned a second at a time
+  rather than every sync. A 200-subject roster replacing 4 subjects a frame climbed to about 1.2 ms
+  a frame as 14,000 voices that had left built up; it now holds at about 0.065 ms.
+- An anchor naming a score reads only the voices on that score, and only in the mixes on the
+  transport that hold one; it reads each voice that has left once rather than every frame, and
+  picks in one pass instead of sorting. astv's busy stage, whose rail waits on the latest `coast`
+  of its motion score, takes about 0.45 ms a frame in astv's motion bench, against 4.3 ms on 0.7.0.
+  With 200 mixes on scores of their own beside it, a frame's sync takes about 14 µs, against 21
+  before the transport listed the mixes holding each score (Node, medians of six alternated runs).
+
+## 0.7.0
+
+### Breaking
+
+- With lanes on, a stateless patch's `send` from `at` sends only for subjects probed this frame
+  or in the last frame with a probe, where it sent for every subject the lane had met.
+- A `keys` patch's stops are not read for a subject its voice gives no weight, as `at` already
+  was not, unless the voice is fading to rest or is in a locus. A `lerp` or `lerpBy` that counted
+  its calls no longer sees those frames. A `from: 'current'` voice still takes its base on its
+  first read.
+- `sync` throws for a timestamp earlier than the last sync's, short of a `rebase`. It used to take
+  one and half work: stateless voices moved back while a stateful patch without `stepMs` was handed
+  a negative `dt`. A host moving the mix calls `seek`.
+- `project` takes mix time, not the host's timestamp. The two differ only on a mix with its own
+  rate or one that was rebased, where `project(mix.now - 300)` reads 300 ms of mix time back.
+- `Mix` has `seek`, `now` and `tape`, which an engine of its own has to provide.
+- `Mix` has `span`, which an engine of its own has to provide.
+- `Mark` has a fifth value, `coast`, so a `switch` over it that checks every case needs one more.
+- `project` ahead of the mix after a `seek` back throws for a time past a call the tape will make
+  again, which it used to leave out; a seek there makes it.
+- An engine of its own is handed `MixOptions.transport` and `name`, and a `Mix` that can share a
+  transport has to keep its clock there.
+- `Mix` and `Transport` have `prepare`, which an engine of its own has to provide.
+
+### Added
+
+- `transport(opts)` makes one clock several mixes share, each over its own kit, by passing it as
+  `MixOptions.transport` with a `name`. `sync`, `rebase`, `rate`, `ramp` and `seek` on the
+  transport move every mix on it, and a mix's own throw. A query naming a `score` looks in every
+  mix on the transport, so an anchor in one mix waits on a voice in another; one naming no score
+  stays in its own mix. The transport has `announce` (on a named score), `marks`, `project(time)`
+  with `.of(mix)`, `live`, `inert`, `onWake` and `drop(mix)`. One tape records every mix's calls
+  and a seek replays them in the order they were made; under history a seek back before a `drop`
+  puts the mix back. `Marked.mix` names the mix a mark came from, and voice ids are unique across a
+  transport. A mix made alone has a transport of its own, so nothing changes for it.
+- `fade({ at, over })` with `at` a mix time begins the fade exactly there: ahead, the voice plays
+  untouched until then with its `out` and `end` fixed from the call, and `rise` before then takes it
+  back with nothing changed; at or behind now, the fade began then and is partway. It wins over an
+  anchored `out`.
+- A voice **coasts** when its last pass ends, for its latest-staggered subject: the moment
+  `played` resolves true. `coast` is a mark like the other four, listed by `marks`, booked by
+  `book`, read ahead by `project`, and waited on with `{ of, mark: 'coast' }`. It falls with `out`
+  on a voice that does not freeze, and where a frozen voice starts showing its last frame, which
+  has no `out` until it is faded. An owner coasts with its last child, a span where its fit ends. A
+  voice that loops for good, or fades before its last pass ends, never coasts.
+- `color()`, a channel holding color as OKLab `[L, a, b, coverage]` with its merge rule as a
+  parameter. `color()` averages: voices stack as a premultiplied sum, so it runs on lanes, and the
+  pose carries the summed weight as coverage. `color(last())` replaces. `{ lerp: 'oklch' }`
+  interpolates round the hue instead of across OKLab, off lanes. `oklab(0xrrggbb)` makes a value;
+  `toHex(pose, under)` lays a pose over the subject's own color and `css(pose)` writes an
+  `oklab()` string with the coverage as alpha. `color(last())` runs on lanes too, the last voice
+  past the band winning, unless a voice writing it is a motion, sits in a locus or names one
+  subject. `hex` still works, but it is deprecated for
+  `color(last(), { lerp: 'oklch' })`, which replaces and interpolates as it does, and a later
+  release removes it.
+- `mix.span(spec)` cues an owner that lays out the voices it holds in an `order` (`queue`,
+  `stagger`, `together`) and fits them into its `duration`, again whenever one joins or leaves.
+  Each child says how it may give way with `faster`, `slower`, `overlap`, `ballast` and `priority`. The
+  span first retimes its children by one factor toward the budget, faster where they run past it
+  and slower where they leave room, each as far as its hints allow; then its `fit` decides the
+  rest: `condense`, `shed`, `conclude` and `overrun` are exported, `pipe` runs several in turn,
+  and `lax` is every one with `overrun` last.
+  Where nothing fits, `spill: 'instant'` jumps the weaker children to their end at once and
+  `'overrun'` lets the span run long. A span with a budget stays until it has passed, so late
+  children can join, and `handle.result` says how the last fit came out.
+- `ticker().wake()` asks for a frame. A mix changed before `stop` and not synced since fires
+  `onWake` no more, so nothing else starts the loop again; `add` asks for a frame too, as it
+  always did, now documented.
+- An anchor can wait on several: `{ all: [...] }` answers the latest of them and `{ any: [...] }`
+  the earliest, and both nest.
+- `handle.rise({ over })` turns a fade out around: the voice climbs back from where its fade had
+  got to, up the same curve, and plays on as if never faded, so a host can take back a leave
+  without the jump a fresh fade in from 0 makes. It is recorded, so history and `seek` replay it.
+  A fade waiting for rest is taken back at once; a voice not fading is left as it is.
+- `mix.seek(time)` moves the live mix to a mix time and plays on from there, under `history` with
+  a `tape`. `history.tape` takes weasel-history's `createHistory` (`@weasel-js/history`), or
+  anything of the `Tape` shape, and the mix records every call the host makes on it, its handles
+  and its spring and glide patches. Back, the mix restores itself as it stood at the end of that
+  frame: voices that left since return on the handles the host holds, with `done` and `played`
+  starting over, and voices cued since wait `pending` on theirs. Forward, by a sync or a later
+  seek, the recorded calls play again at the mix times they were made. A call made while recorded
+  calls lie ahead starts a branch, and the tape keeps the old future: `mix.tape.branches()` lists
+  them and `switchBranch` picks one. State steps once from the nearest copy history kept, exact
+  under `stepMs`. Playing past a time again sends its events and books its marks and hits again.
+  The host keeps passing its own clock.
+- `mix.now` reads the mix clock, which `seek` and `project` take.
+- `history.store` pages out what `history.ms` would drop, as plain data, so `ms` bounds memory
+  rather than how far back a seek reaches. `store.page` takes records leaving memory,
+  `store.load(t)` gives back what a restore to `t` needs, and `store.cut(t)` forgets what a seek
+  back left behind. `transport.prepare(t)` (and `mix.prepare` for a mix alone) loads before a seek
+  or read past memory; without it, it throws `HistoryMiss` before anything moves. Object subjects
+  need `MixOptions.keyOf`, a patch with `state` or `step` needs `pack` and `unpack` (which `patch`
+  now takes), and every mix on a transport with a store needs a unique `name`. A voice cued with
+  `as: { kind, data }` leaves memory once it has left and history no longer reaches its end, and
+  `history.revive` builds its spec again when a seek needs it, behind the handle the host holds.
+  With a store, blits never prunes the tape; the host bounds it. Without one, nothing changes.
+
+### Fixed
+
+- A lane fills only the subjects probed this frame or in the last frame with a probe, not every
+  subject it has met; one probed in neither takes the general path if it is probed before the next
+  fill. Three `keys` voices over 10k subjects, every subject probed once and then 40% each frame
+  (`view`), take 0.561 ms a frame against 0.878. No other row moves past its run-to-run spread:
+  `signal` and `named` at 10k read 1.06 and 1.09 here and 0.96 and 0.91 in a run against the
+  build before (teitou, medians of six alternated runs, each in its own process).
+- A second `seek` or `project` back no longer reaches into time the first one's history had
+  already let go of, where it read wrong values: after seeking back to 1600 under `ms: 500` from
+  2000, a seek to 1200 read 0 where the mix had shown 90. It throws as a read older than history
+  does.
+- Under `history`, a subject faded out of a voice or dropped after the moment a `seek` or a
+  `project` reads back to comes back with the record it had, and with a motion patch's state for
+  it. It used to come back as never seen, its state started afresh.
+- `project` across a `rebase` reads the moment the host saw: it converted a host timestamp with
+  the offset in force now, so a 1000 ms rise synced at 0 and 200, rebased and synced at 10200 read
+  0 at 200, where the host had seen 20. Taking mix time, it reads 20.
+
+- A probe and `atRest` no longer allocate on the heap to find a subject's voices. Each passed the
+  mix's clock, a fractional number, to a function too large for V8 to inline, which stores such a
+  number on the heap to pass it; and the function that links a subject's voices made a closure
+  context on every call, though only relinking uses one. Collections over 5000 frames of 10k
+  subjects fall from 666 to 375 with a probe and `atRest` of each (`probed`), 279 to 121 with
+  `atRest` alone (`rest`), 428 to 285 with a voice per subject (`named`), and 741 to 524 with three
+  `fn` voices over every subject (`fn`). A frame takes 0.857 ms against 0.885 for `rest`, 1.263
+  against 1.325 for `named`, and 2.074 against 2.156 for `fn`; `probed`, at 1.507 against 1.504,
+  and the rows read by `pull` are unchanged (teitou, medians of twelve alternated runs).
+- A fill no longer stamps every subject: the lanes keep which fill ran a lane, and a subject is
+  stamped only when it is left to the general path. A spring is solved by a function per kind of
+  spring, small enough for V8 to inline where it samples, where one function over all four left
+  spring fills running at one of two speeds. At 10k subjects, a frame takes 0.438 ms against 0.473
+  with a spring voice read by `pull` (`spring^`), 0.411 against 0.463 with a spring voice per
+  subject (`springs^`), 0.937 against 0.996 and 0.884 against 0.935 for the same by `probe`,
+  0.306 against 0.319 with one subject replaced each frame (`turnover^`), 0.226 against 0.233 with
+  one voice replaced each frame (`churn^`), and 0.167 against 0.170 with a tween voice per subject
+  (`tweens^`); a probe and `atRest` of every subject (`probed`) is unchanged, 1.497 against 1.504
+  (teitou, medians of eight alternated runs, twelve for `probed`).
+
 ## 0.6.0
 
 ### Breaking

package/README.md

@@ -1,22 +1,24 @@
 # blits
 
-Concurrent effects, mixed. Each effect runs on its own clock with its own state and weight, and a
-mix folds them into one value per subject per frame by rules that belong to the channel, not the
-effect.
+Effects over time, at once or in order. Each effect runs on its own clock with its own state and
+weight. Effects that overlap are folded by a mix into one value per subject per frame, by rules
+that belong to the channel, not the effect. Effects that follow one another are placed on a score,
+at a time or against another effect's start or end, and the mix can be read ahead, read back, and
+moved to any moment, as a scrubber does.
 
 It is the thing klieg does three times over — motion, effects, lighting — and wod does once for
 transitions, extracted so those repos, sherpa and magicsmoke can share one vocabulary and one
 engine.
 
 ```ts
-import { hex, kit, max, mix, mul, patch, sum, vec } from '@msb235/blits';
+import { color, kit, max, mix, mul, patch, sum, vec } from '@msb235/blits';
 
 // What a part of a sign can move on. The arithmetic lives here and nowhere else.
 const PART = kit<PartPose>({
   gain: mul(),
   dark: max(),
   position: vec(3, sum()),
-  color: hex(),
+  color: color(),
 });
 
 const flicker = patch<Part, PartPose>(
@@ -39,16 +41,38 @@ function frame(timestamp: number) {
 document.addEventListener('visibilitychange', () => document.hidden || m.rebase());
 
 handle.fade({ over: 500 }); // the voice ramps out and leaves
+handle.rise({ over: 500 }); // or, before it is gone, climbs back from where it had got to
+```
+
+In order, on the same mix:
+
+```ts
+// Place a voice at a time on the host's clock, or against another voice's marks.
+m.cue({ patch: typeIn, name: 'title', start: 1000, loop: false });
+m.cue({ patch: tint, loop: false, anchor: { start: { after: 'title', by: 200 } } });
+
+// A span fits the voices it holds into a budget, one after another by default.
+const intro = m.span({ duration: 2000 });
+for (const line of lines) m.cue({ patch: typeIn, loop: false, owner: intro });
+
+// Read the mix half a second ahead without moving it, or move it: a scrubber.
+const next = m.project(m.now + 500).probe(part);
+m.seek(1200); // back as well as forward, given `history` with a tape
 ```
 
 ## The words
 
-Ten of them carry the rest: **delta** (a partial record of channel values), **channel** (one field
+These carry the rest: **delta** (a partial record of channel values), **channel** (one field
 with its own arithmetic), **kit** (the channel set for one kind of delta), **subject** (what is
 driven), **patch** (a pure function of phase and a subject), **voice** (a patch with its own clock
 and weight), **mix** (the live voices over one kit), **signal** (a 0..1 scalar from outside the
 clock), **handle** (the live controls on one voice), **engine** (the implementation behind a mix).
 
+For time: **score** (the plan a source's voices are placed on), **mark** (a voice's start, fade-in
+done, fade-out begun, or end, or a named point the host announces), **anchor** (a time given by
+another voice's mark), **span** (an owner fitting the voices it holds into a duration), **project**
+(read the mix at another time without moving it), **seek** (move the mix to a time and play on).
+
 The design — the full vocabulary, the channel table, the time model, blending, the engine seam, and
 what is still open — is `docs/schema.html`, which ships in the package: open it from
 `node_modules/@msb235/blits/`. The naming work behind it is
@@ -76,7 +100,7 @@ so the engine keeps no dependencies; its README says how it works.
 
 ## Status
 
-v0.6.0, with five consumers. magicsmoke runs every fault on it, wod its wheel, tricks and
+v0.7.1, with five consumers. magicsmoke runs every fault on it, wod its wheel, tricks and
 transitions, weasel its animator's tweens, sherpa its seams, 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.

package/dist/bare.js

@@ -23,6 +23,7 @@ export function bareRows(lanes, c, p, id) {
     const fills = lanes.fills;
     const from = lanes.frameProbes;
     const probed = lanes.probes !== from;
+    const lately = lanes.lately;
     const now = lanes.now;
     const op = ch.op;
     for (; p < list.length; p++) {
@@ -37,6 +38,11 @@ export function bareRows(lanes, c, p, id) {
         if (probed &&
             (per[q + 3 /* Per.LANE_PROBE */] > from || per[q + 4 /* Per.GENERAL_PROBE */] > from))
             break;
+        // Left to the general path, as `rows` leaves it.
+        if (lately >= 0 &&
+            !(per[q + 3 /* Per.LANE_PROBE */] > lately ||
+                per[q + 4 /* Per.GENERAL_PROBE */] > lately))
+            break;
         const elapsed = clock(hot, h, now) - data[o + 0 /* Row.DELAY */];
         if (!(elapsed >= 0))
             break;
@@ -48,9 +54,9 @@ export function bareRows(lanes, c, p, id) {
             data[o + 5 /* Row.SAMPLED */] = -2 /* Sampled.BARE */;
             c.deltas[p] = null;
         }
-        const share = left(c.eases[p], progress(elapsed, hot[h + 8 /* Hot.AT */], hot[h + 9 /* Hot.MS */]));
         if (w <= 0)
             continue;
+        const share = left(c.eases[p], progress(elapsed, hot[h + 8 /* Hot.AT */], hot[h + 9 /* Hot.MS */]));
         const values = ch.values;
         const base = slot * n;
         const x = h + 10 /* Hot.X0 */;

package/dist/book.d.ts

@@ -35,6 +35,8 @@ export declare class Book<I, O> implements Booker {
     private prev;
     private round;
     private stopped;
+    /** The host time the mix last sought at: a mark at or before it was taken before the seek. */
+    private floor;
     /** Bookings of marks, by `keyOf`, kept while listed so one already taken is not taken late. */
     private readonly marked;
     private readonly tracks;
@@ -43,6 +45,11 @@ export declare class Book<I, O> implements Booker {
     /** Books what comes within `ahead` of this sync, and retracts what moved. */
     sync(): void;
     stop(): void;
+    /**
+     * The mix was sought to `host.now`, back or ahead: what is booked ahead is stopped, and
+     * everything after that moment is booked as the mix reaches it.
+     */
+    sought(): void;
     /** Whether a standing booking now falls at host time `time` within `RETIME_MS`. */
     private stands;
     private fits;

package/dist/book.js

@@ -24,6 +24,8 @@ export class Book {
     prev = Number.NaN;
     round = 0;
     stopped = false;
+    /** The host time the mix last sought at: a mark at or before it was taken before the seek. */
+    floor = Number.NEGATIVE_INFINITY;
     /** Bookings of marks, by `keyOf`, kept while listed so one already taken is not taken late. */
     marked = new Map();
     tracks = new Map();
@@ -85,6 +87,35 @@ export class Book {
         this.tracks.clear();
         this.host.unhook(this);
     }
+    /**
+     * The mix was sought to `host.now`, back or ahead: what is booked ahead is stopped, and
+     * everything after that moment is booked as the mix reaches it.
+     */
+    sought() {
+        if (this.stopped)
+            return;
+        const last = this.last;
+        for (const b of this.marked.values())
+            if (b.time > last)
+                b.taken?.stop();
+        for (const t of this.tracks.values())
+            for (const b of t.booked.values())
+                if (b.time > last)
+                    b.taken?.stop();
+        this.marked.clear();
+        this.tracks.clear();
+        const host = this.host;
+        this.floor = host.timestamp;
+        this.prev = host.now;
+        for (const voice of host.voices)
+            if (voice.spec.hits !== undefined && voice.state !== 'done')
+                this.tracks.set(voice, {
+                    seenTo: voice.elapsedAt(host.now),
+                    seeks: voice.seeks,
+                    booked: new Map(),
+                    met: this.round,
+                });
+    }
     /** Whether a standing booking now falls at host time `time` within `RETIME_MS`. */
     stands(b, time) {
         if (time === undefined || !Number.isFinite(time))
@@ -100,7 +131,7 @@ export class Book {
         const marked = this.marked;
         const seen = new Set();
         for (const m of listed) {
-            if (!this.fits(m.score, m.tags))
+            if (!this.fits(m.score, m.tags) || m.timestamp <= this.floor)
                 continue;
             const key = keyOf(m);
             seen.add(key);
@@ -211,8 +242,8 @@ export class Book {
         return this.host.hostOf(t);
     }
 }
-const markIndex = { start: 1, in: 2, out: 3, end: 4 };
-/** A mark's identity: its voice and which of the four, or the announcement. */
+const markIndex = { start: 1, in: 2, coast: 3, out: 4, end: 5 };
+/** A mark's identity: its voice and which of its marks, or the announcement. */
 function keyOf(m) {
-    return m.order * 5 + (m.mark === undefined ? 0 : markIndex[m.mark]);
+    return m.order * 6 + (m.mark === undefined ? 0 : markIndex[m.mark]);
 }

package/dist/chain.d.ts

@@ -6,7 +6,8 @@ import type { Subject, Voice } from './voice.js';
  * it goes live, since `target` is asked on first sight, and sight only comes once a voice plays
  * or freezes before.
  */
-export declare function chain<I, O>(this: Mixer<I, O>, subject: I, now: number): Subject<unknown>;
+export declare function chain<I, O>(this: Mixer<I, O>, subject: I): Subject<unknown>;
+export declare function relink<I, O>(this: Mixer<I, O>, subject: I, was: Subject<unknown> | undefined): Subject<unknown>;
 /** A voice's record for a subject where its chain links it: the voice plays or freezes, and reaches it. */
 export declare function linkable<I, O>(this: Mixer<I, O>, voice: Voice<I, O>, subject: I, now: number, slot: number): Subject<unknown> | null;
 /** Whether a voice reaches a subject by what its spec says: the subjects it names, or its `target`. */

package/dist/chain.js

@@ -29,10 +29,14 @@ function stub() {
  * it goes live, since `target` is asked on first sight, and sight only comes once a voice plays
  * or freezes before.
  */
-export function chain(subject, now) {
+export function chain(subject) {
     const was = this.chains.get(subject);
-    if (was !== undefined && was.version === this.version)
-        return was;
+    return was !== undefined && was.version === this.version ? was : this.relink(subject, was);
+}
+// Apart from `chain` so that its closures' context is made only when a chain is relinked, and
+// `chain` stays small enough for V8 to inline where a probe links.
+export function relink(subject, was) {
+    const now = this.now;
     const slot = was !== undefined ? was.slot : this.lanes !== null ? this.lanes.number(subject) : -1;
     // Where only voices over every subject changed since, those alone are taken off or put on.
     let first = was === undefined

package/dist/channels.d.ts

@@ -11,9 +11,12 @@ export type LerpInto = (out: unknown[] | undefined, a: unknown, b: unknown, u: n
  * 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. */
+/**
+ * What a lane needs of a stock numeric channel beyond the channel: its arithmetic by name, its axes.
+ * `'last'` has no rest: the last contribution to pass the band replaces, and a weight only gates it.
+ */
 export interface Numeric {
-    op: 'sum' | 'mul' | 'max';
+    op: 'sum' | 'mul' | 'max' | 'last';
     axes: number;
 }
 /**
@@ -21,6 +24,12 @@ export interface Numeric {
  * so a custom channel that claims a stock `kind` is not trusted with a lane.
  */
 export declare function numericOf(channel: Channel<unknown>): Numeric | undefined;
+/** Vouches for a stock channel made outside this module, as `color` makes its own. */
+export declare function vouch(channel: Channel<unknown>, numeric: Numeric): void;
+/** Records how many numbers a rest-less array channel holds a subject, which its rest cannot say. */
+export declare function widen(channel: Channel<unknown>, axes: number): void;
+/** How many numbers a channel holds a subject: its rest's length, a recorded width, or one. */
+export declare function axesOf(channel: Channel<unknown>): number;
 /** `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;
 /**
@@ -51,7 +60,7 @@ export declare function mul(opts?: NumberOptions): 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
+ * A channel with no rest: the last contribution 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
  * consumer with a real interpolation passes its own, as `hex` does.
  *
@@ -66,22 +75,6 @@ export declare function last<V>(opts?: {
  * @category channel
  */
 export declare function vec(n: number, of: Channel<number>): Channel<number[]>;
-/**
- * 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, 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(opts?: {
-    space?: 'oklch' | 'srgb';
-}): Channel<number>;
 /**
  * A kit is plain data; this only fixes the type.
  *

package/dist/channels.js

@@ -23,13 +23,29 @@ const numerics = new WeakMap();
 export function numericOf(channel) {
     return numerics.get(channel);
 }
+/** Vouches for a stock channel made outside this module, as `color` makes its own. */
+export function vouch(channel, numeric) {
+    numerics.set(channel, numeric);
+}
+const widths = new WeakMap();
+/** Records how many numbers a rest-less array channel holds a subject, which its rest cannot say. */
+export function widen(channel, axes) {
+    widths.set(channel, axes);
+}
+/** How many numbers a channel holds a subject: its rest's length, a recorded width, or one. */
+export function axesOf(channel) {
+    const rest = channel.rest;
+    return Array.isArray(rest) ? rest.length : (widths.get(channel) ?? 1);
+}
 /** `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));
+    if (op === 'max')
+        return larger(acc, times(v, w));
+    return v;
 }
 /** 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]}]`;
@@ -85,7 +101,7 @@ export function max(opts) {
     return channel;
 }
 /**
- * A channel with no rest: the last influence to pass wins, and a weight can only gate it. The
+ * A channel with no rest: the last contribution 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
  * consumer with a real interpolation passes its own, as `hex` does.
  *
@@ -162,122 +178,6 @@ export function vec(n, of) {
         numerics.set(channel, { ...inner, axes: n });
     return channel;
 }
-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;
-/**
- * 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;
-    const br = (b >> 16) & 0xff;
-    const bg = (b >> 8) & 0xff;
-    const bb = b & 0xff;
-    return ((clamp255(mix(ar, br, u)) << 16) | (clamp255(mix(ag, bg, u)) << 8) | clamp255(mix(ab, bb, u)));
-}
-/**
- * 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(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

@@ -9,12 +9,19 @@ export declare function passesOf(loop: boolean | number | undefined): number;
 export declare function phaseAt(elapsed: number, duration: 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, duration: number, passes: number): number;
-/** A voice's own fade this frame, 0..1: in from `since` over `fadeIn`, and out along its ramp. */
+/**
+ * A voice's own fade this frame, 0..1: in from `since` over `fadeIn`, out along its ramp, and back
+ * up the same curve where a fade out was turned around.
+ */
 export declare function envelope(fadeIn: number, out: {
     at: number;
     over: number;
     rest: boolean;
-} | null, ease: Curve | undefined, reduced: boolean, now: number, since: number): number;
+} | null, ease: Curve | undefined, reduced: boolean, now: number, since: number, back?: {
+    from: number;
+    at: number;
+    over: number;
+} | null): number;
 /**
  * A subject's voice time `raw` once the voice's freezes apply: 0 before it starts if it freezes
  * before, else NaN, where it shows nothing; `span` once its passes end if it freezes after.

package/dist/clock.js

@@ -21,14 +21,22 @@ export function passAt(elapsed, duration, passes) {
         return 0;
     return over(elapsed, duration, passes) ? passes - 1 : Math.floor(elapsed / duration);
 }
-/** 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) {
+/**
+ * A voice's own fade this frame, 0..1: in from `since` over `fadeIn`, out along its ramp, and back
+ * up the same curve where a fade out was turned around.
+ */
+export function envelope(fadeIn, out, ease, reduced, now, since, back = null) {
     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 (back && !reduced) {
+        const u = back.from + (now - back.at) / back.over;
+        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;