@msb235/blits 0.7.1 → 0.8.0

package/CHANGELOG.md

@@ -4,6 +4,186 @@ 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.8.0
+
+### Breaking
+
+- `handle.seek(elapsed)` rebuilds each subject's state for the new position: fresh from the
+  patch's `state`, with what signals keep started over, and stepped from the voice's start to
+  `elapsed` at the next probe, on the `stepMs` grid where there is one. It left state where it was,
+  so a spring seeked back to 0 read about 111 where a fresh one reads 0. `seek(elapsed, { state:
+  'keep' })` keeps the old behavior. The same holds for an owner's seek and its children.
+- A `keys` channel given a `delayBy` waits, then travels in the time left, landing with the other
+  channels at the end of the duration, as klieg's own `delayBy` does. It shifted the phase without
+  compressing it, so a channel waiting 200 ms of 1000 stopped 80% of the way there.
+- In a `locus`, each channel folds at the summed weight of the members that write it, not the whole
+  locus's. A channel only one member writes fades with that member rather than holding at full
+  weight until it snaps to rest.
+- `cue` refuses a `loop` that is not `true`, `false` or a whole number of passes; `spring` refuses
+  a stiffness or mass that is not positive, or a negative damping; `glide` refuses an `ms` that is
+  not positive. Each played wrongly: a fractional loop jumped at its end, and a spring with no
+  stiffness snapped to its target.
+- `sync(NaN)` throws. It slipped past the check that the clock only goes forward.
+- A voice refuses a rate that is not finite and a weight that is NaN, at `cue` and on its handle.
+  Both were accepted. A negative voice rate still is.
+- `{ steps, jump: 'start' }` reads `1/n` at 0, as CSS does. It read 0.
+- A history store's contract changed. `cut` takes the `seq` of the frame a seek went back to, not
+  a mix time, and every `Paged` record carries the `seq` it was made in; keep one record per key
+  and `seq`, since rate 0 lets several frames share a mix time. The transport pages its announced
+  marks, rate changes and frames too, as `mark`, `pace` and `frame` records with `mix: ''`, and a
+  `left` record's `data` is now `[record, sync]`. A store written for 0.7 forgets the wrong records
+  on a seek back.
+- `vec(3, sum())` is typed `Channel<[number, number, number]>`, a tuple of the length it was given,
+  so a kit over a tuple pose needs no cast. A length that is not a literal still gives
+  `Channel<number[]>`. Types only: code that calls such a channel's `merge`, `scale` or `lerp`
+  itself with a `number[]` annotates the channel as `Channel<number[]>`.
+- `probe(subject, out)` writes into the array `out` already holds for a `vec` channel, or a `color`
+  that averages in OKLab or runs on a lane, where that array is the channel's length. It put a new
+  array there on every probe. A host that kept `out.position` from one probe and compared it with
+  the next now holds the same array both times: copy what has to outlast the next probe. A probe
+  with no `out` still makes its own arrays.
+- The deprecated names are removed. A voice's or an owner's `hold` is `freeze`, as since 0.6.0. A
+  patch's `period` is `duration`: a hand-made patch that set only `period` now has no duration.
+  `hex()` is gone, and `hex({ space: 'srgb' })` with it: `last<number>({ lerp: mixHex })` is the
+  same channel for a color kept as 0xrrggbb, and `color(last(), { lerp: 'oklch' })` with `toHex`
+  at write is the one that also runs with `color()`'s coverage. Nothing blends red, green and blue
+  each on its own any more; a host that wants that gives `last` a `lerp` of its own.
+
+### Added
+
+- `angle({ turn })`, a channel for a rotation about one axis: it adds as `sum` does, and `lerp` and
+  a weight below 1 go the short way round, so 350 to 10 passes 0. `turn` is one full turn in the
+  channel's unit, default 360. It runs on lanes.
+- `quat()`, a channel for a rotation in space as a unit quaternion `[x, y, z, w]`: contributions
+  compose in cue order, and `lerp` and a weight take the short arc. It runs on lanes, through its
+  own `fold`.
+- `Vec<N>`, the tuple of `N` numbers a `vec` channel holds.
+- `fold(kit, deltas, weights?)` folds deltas into one pose by a kit's arithmetic with no mix and no
+  clock: what a mix gives for voices contributing those deltas at those weights, every weight 1
+  where none is given.
+- `project(time)` reads an earlier time on a mix made without `history`, where how the mix stands
+  now says what it showed then: every voice plays as it was cued and reads by its clock alone (no
+  state, motion, anchor or owner, no write to its handle, no channel without a rest at a weight
+  that moves), the mix's rate was never set, and `time` is no earlier than the last cue, `drop`,
+  `touch`, `announce` or `rebase`, or the last frame a voice left in. Anywhere else it throws and
+  says which of those it met, where it threw for any time behind the mix. A host that cued its
+  voices once need not build a second mix to read an earlier frame.
+- `handle.to`, `handle.push` and `handle.read` reach the `to`, `push` and `read` of the motion
+  patch a voice plays, so a host holding only the handle need not keep the patch or cast it. `to`
+  and `push` throw for a voice whose patch does not take them; `read` gives undefined.
+- `mix.touch(subject?)` says that something a patch reads from outside the mix changed since the
+  last sync, so the next probe calls the patch again where it would have answered with what it
+  read this frame: for one subject, or for all. A host need not move the clock to show the change.
+- `input(read)` makes a signal of the host's own that reads something outside the clock. The host
+  calls its `touch()` after each change, and a voice weighted by it keeps its lane, where one
+  weighted by a signal flagged `input` by hand never runs on one. `input(read, of)` marks a signal
+  built on others, an input where any of them is. `level` is `input` over one number.
+
+- `@msb235/blits/testing`, for a library writing patches: `setting()` makes a `Setting` to call a
+  patch outside a mix, and `checkPatch(patch, { subject, kit })` lists what a mix cannot rely on.
+- `handle.seek` answers how sure the state it leaves is, as a `Doubt`: `exact`, `stepped` or
+  `held`. `SeekOptions` is exported.
+- `wave(duration, { shape, cycles, phase, depth, kit })` swings each numeric channel `depth` names
+  up to `depth` either side of its rest in `kit` (0 without one), as a sine, triangle, saw, or
+  square, `cycles` times a pass. It is an `fn` patch that keeps its options on `patch.wave` for an
+  engine that reads data; `waveAt` is the unit wave.
+- A `keys` patch carries the options it was given as fields: `ease`, `easeBy`, `delayBy` and
+  `lerpBy`, beside `keys` and `kit`. They were kept in a table keyed by the patch object, so a copy
+  such as `{ ...p, duration: 2000 }` lost its easing; a copy now plays by the fields it carries,
+  and may change one.
+- `Channel.copy`, for a channel whose `rest` is an object the mix cannot copy itself, such as a class
+  instance, and that has `fold`; `cue` refuses such a channel without one. The mix copies arrays,
+  typed arrays and plain objects itself.
+- `npm run test:general` runs the suite with lanes off, so every test checks the general path
+  against the lanes.
+
+### Fixed
+
+- A handle `seek` made in the frame its voice was cued in put every subject's origin before the
+  voice began, so the fade in read as over at once, and under a fade out a subject first probed
+  after the seek read a weight the others did not. The origin is now the cue's frame, as it is for
+  a seek in any later frame.
+- A rate above 0 set on a voice still pending applies from the voice's start. It was taken from
+  the moment it was set, so the voice's clock passed 0 before the start: the voice then began
+  partway in, and a subject it froze before played, and stepped its state, while the voice was
+  still pending.
+- `fade({ at: 'rest' })` begun after a subject's probe in the same frame finds that subject at rest
+  at its next probe, where it stayed in the voice until the frame after.
+- Seeking back many times no longer throws `Maximum call stack size exceeded`. Every `seek` to an
+  earlier time wrapped each voice's records in another layer, kept for the life of the mix, so a
+  scrubbed mix grew with every seek and a subject not probed since was found through all of them:
+  20,000 seeks overflowed the stack. A voice now keeps one store however often the mix seeks. Two
+  seeks back with no probe between could also read a wrong pose, as two fuzzer programs did.
+- An anchor cued after its target had left waited for good, and kept the mix from coming to rest,
+  unless the mix's history still reached the target. A mix now keeps the marks of the first and last
+  voice to leave under each name, tag and channel, and an anchor no voice the mix still knows answers
+  reads those, placing its voice as it would have while the target was there. It holds that much and
+  no more, however many voices leave.
+- A channel whose `rest` is an object or a typed array had it handed to `fold` by reference, so it
+  accumulated across frames and every subject's pose shared it.
+- `fade()` during a fade-in made the weight rise before it fell: the fade-in kept climbing under
+  the fade-out. It now stops where the fade-out begins.
+- A seek put a voice's controls back without its rise ramp, so a seek to before a later `rise()`
+  read the voice at 0.
+- A `from: 'current'` retarget under an easing that jumps or leaves vertically at its start
+  (`steps` with `jump: 'start'`, `bezier [0,1,0,1]`) threw the value hundreds of thousands out. Such
+  an easing now takes no slope bend.
+- A channel with no `rest` stayed switched on across a weight of 0, so a weight going 0.7, 0, 0.5
+  found it on at 0.5.
+- `slew` and `lag` step by no more than `maxDt`, as `step` does. After a long gap a slew finished
+  at once.
+- A `keys` patch reads a channel whose stops are all plain numbers, lerped straight across, by a
+  search and lerp of its own, giving the same bits: `patch.at` over 10,000 four-stop tracks takes
+  about 0.70 of the time it did.
+- Two copies of blits loaded together, as a library pinning its own copy brings, read each other's
+  patches and channels: a `keys` patch one copy made kept its easing on the other's mix, which read
+  it linear, and the facts a stock channel carries for lanes are shared too.
+- Under `history`, a read back to a frame in which the host changed a voice between the sync and
+  the first probe shows the change in that frame, as the live probe did. It showed from the next
+  frame.
+- A subject's fade-in start and step origin came from its voice's rate and anchor as they stood at
+  the subject's first probe, so a rate change, ramp or handle seek before then moved them and the
+  numbers depended on when the host had looked. Every voice now keeps the clocks it ran on, and a
+  subject's origin is when its voice's clock first read the subject's delay. A stateful subject met
+  late steps from that origin, capped by `maxDt`, where it started stepping from first sight. A
+  read ahead no longer loses a stateful voice whose anchored start falls inside it.
+- A seek or read back was keyed on mix time, which rate 0, a backdated `fade({ at })` and several
+  handle calls in one frame can all share, so it could restore the wrong moment or drop a voice
+  whose fade was backdated. The transport now numbers its frames, history entries carry the frame
+  they were made in, and a seek or read to mix time `t` lands on the last frame at or before `t`.
+  The tape stamps calls by host time, so frames rate 0 holds at one mix time stay apart.
+- A frame that passed both a voice's start and the `fade({ at })` set for it began the fade a frame
+  late, so 16 ms and 32 ms frames disagreed.
+- With a history store, the transport kept every announced mark, rate change and frame for good, and
+  a long run slowed quadratically: 20,000 frames took 19.8 s, against 0.17 s now.
+- Lanes and the general path disagreed in three places. A `level` set between two probes in one
+  frame now reaches the next probe on lanes too; `inert` reads the same for a motion voice at weight
+  0, which lanes kept awake until it landed; and `project` reads a subject faded out of a voice as
+  out of it after a retarget or a `drop` brought it back, on both paths. A voice weighted by an input
+  signal not built on `level`, or whose patch reads host fields, never runs on a lane, since a
+  change to either between two probes would not reach it.
+- A span that skipped several children at cue played the last of them in full on the next sync, and
+  then reported none skipped.
+- A pose read NaN for a voice still waiting on a `start` the host gave, once the voice was set to
+  rate 0 while the mix's rate was 0. It reads as any voice before its start does.
+- A frame allocates much less, which is most of what made the garbage collector run during one. A
+  probe into `out` reuses its arrays, a motion voice off lanes reuses its last delta, and a fill
+  no longer boxes a number per subject. `bench/frame.mjs`, 10,000 subjects probed into one `out`:
+  three `keys` voices went from 1.8 MB a frame to 0.16 MB and take 0.81 of the time; a `tween`
+  voice from 0.72 MB to 0.02 MB, 0.90 of the time; a `tween` voice with lanes off from 2.6 MB to
+  0.32 MB, 0.82 of the time.
+- Cueing a voice over every subject costs much less. A voice with no `subjects`, `target`,
+  `stagger` or signal weight, whose patch keeps no state, kept a record for each subject probed;
+  it keeps one for them all, and a read ahead copies that one. `bench/frame.mjs`, 10,000 subjects
+  each under a `tween` voice of its own, with a voice over all of them replaced every frame: 9.3 MB
+  a frame to 2.7 MB, in 0.74 of the time. A read 500 ms ahead of 1,000 subjects under three voices,
+  made and probed every frame: 2.4 MB to 1.5 MB, in 0.80 of the time. A mix made with
+  `lanes: false`, or with `history`, keeps a record for each subject as before.
+- Under `history`, dropping subjects and reading them back each took time that grew with the square
+  of how many had left: every drop went through every record its voice had kept, and so did every
+  read back. 8,000 subjects dropped in one frame took 173 ms and take 7; reading them back took 180
+  ms and takes 3 (`bench/drops.mjs`).
+
 ## 0.7.1
 
 ### Fixed

package/README.md

@@ -69,7 +69,7 @@ and weight), **mix** (the live voices over one kit), **signal** (a 0..1 scalar f
 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
+done, last pass ended, 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).
 
@@ -89,8 +89,26 @@ npm run site         # dev server on port 4880
 npm run site:smoke   # build, then load every page headless and fail on any error
 ```
 
-`.github/workflows/site.yml` deploys it to GitHub Pages. It runs only by hand until Pages is enabled
-on the repo.
+`.github/workflows/site.yml` deploys it to GitHub Pages on every push to `main`, and by hand.
+
+## Writing patches for blits in another library
+
+A library that ships patches exports them with the channels they write, as a `Kit` of its own
+for the host to spread into its kit, and checks them in its own tests against
+`@msb235/blits/testing`:
+
+```ts
+import { checkPatch, setting } from '@msb235/blits/testing';
+
+expect(checkPatch(glow, { subject, kit })).toEqual([]); // each string names a problem
+glow.at(0.5, subject, setting({ weight: 0.5 })); // a Setting for calling a patch outside a mix
+```
+
+`checkPatch` reads the patch across its phase from fresh state and reports what a mix cannot rely
+on: writing outside `writes`, a delta that changes between identical reads, a touched subject,
+state shared between subjects, a `step` that lands differently from the same start, a `clone`,
+`pack` or `unpack` that does not give back an equal state, a missing host field, and a kit that
+`cue` would refuse. Two copies of blits loaded together read each other's patches and channels.
 
 ## Packages
 
@@ -100,7 +118,7 @@ so the engine keeps no dependencies; its README says how it works.
 
 ## Status
 
-v0.7.1, with five consumers. magicsmoke runs every fault on it, wod its wheel, tricks and
+v0.8.0, 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/book.js

@@ -111,7 +111,7 @@ export class Book {
             if (voice.spec.hits !== undefined && voice.state !== 'done')
                 this.tracks.set(voice, {
                     seenTo: voice.elapsedAt(host.now),
-                    seeks: voice.seeks,
+                    jumps: voice.jumps,
                     booked: new Map(),
                     met: this.round,
                 });
@@ -166,13 +166,13 @@ export class Book {
                 continue;
             let t = this.tracks.get(voice);
             if (t === undefined) {
-                t = { seenTo: Number.NEGATIVE_INFINITY, seeks: voice.seeks, booked: new Map(), met: round };
+                t = { seenTo: Number.NEGATIVE_INFINITY, jumps: voice.jumps, booked: new Map(), met: round };
                 this.tracks.set(voice, t);
             }
             t.met = round;
             // A seek counts from where it put the clock: what it jumped over is not late.
-            if (t.seeks !== voice.seeks) {
-                t.seeks = voice.seeks;
+            if (t.jumps !== voice.jumps) {
+                t.jumps = voice.jumps;
                 t.seenTo = voice.elapsedAt(prev);
             }
             const end = host.endOf(voice);

package/dist/chain.d.ts

@@ -9,7 +9,7 @@ import type { Subject, Voice } from './voice.js';
 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;
+export declare function linkable<I, O>(this: Mixer<I, O>, voice: Voice<I, O>, subject: I, slot: number): Subject<unknown> | null;
 /** Whether a voice reaches a subject by what its spec says: the subjects it names, or its `target`. */
 export declare function aims<I, O>(this: Mixer<I, O>, voice: Voice<I, O>, subject: I): boolean;
 /**

package/dist/chain.js

@@ -1,27 +1,8 @@
+import { everyoneOf, sight } from './everyone.js';
+import { record } from './record.js';
 /** The first record of a subject no live voice reaches, so a probe of it still makes one lookup. */
 function stub() {
-    return {
-        reaches: false,
-        delay: 0,
-        since: 0,
-        shown: 0,
-        weight: 0,
-        rested: false,
-        bands: null,
-        state: undefined,
-        stepped: 0,
-        ticks: 0,
-        probed: Number.NaN,
-        delta: null,
-        phase: 0,
-        seeks: 0,
-        kept: null,
-        voice: null,
-        next: null,
-        version: Number.NaN,
-        loci: null,
-        slot: -1,
-    };
+    return record(null, false, undefined);
 }
 /**
  * The first of this subject's records, linked through every live voice that reaches it. A voice
@@ -33,40 +14,15 @@ export function chain(subject) {
     const was = this.chains.get(subject);
     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.
+// Apart from `chain`, which 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
         ? undefined
-        : this.steps.patch(was.voice === null ? null : was, was.version, (voice) => this.linkable(voice, subject, now, slot));
-    if (first === undefined) {
-        let prev = null;
-        first = null;
-        const link = (voice) => {
-            const held = this.linkable(voice, subject, now, slot);
-            if (held === null)
-                return;
-            held.voice = voice;
-            held.next = null;
-            if (prev === null)
-                first = held;
-            else
-                prev.next = held;
-            prev = held;
-        };
-        const named = this.naming === 0 ? undefined : this.named.get(subject);
-        let j = 0;
-        for (const voice of this.general) {
-            while (named !== undefined && j < named.length && named[j].id < voice.id)
-                link(named[j++]);
-            link(voice);
-        }
-        while (named !== undefined && j < named.length)
-            link(named[j++]);
-    }
+        : this.steps.patch(was.voice === null ? null : was, was.version, this, subject, slot);
+    if (first === undefined)
+        first = linkAll(this, subject, slot);
     const head = first ?? stub();
     head.version = this.version;
     if (was !== undefined && was !== head) {
@@ -81,19 +37,59 @@ export function relink(subject, was) {
         this.chains.set(subject, head);
     return head;
 }
+/** A subject's chain linked afresh through every voice that reaches it, in voice order. */
+function linkAll(mix, subject, slot) {
+    let first = null;
+    let prev = null;
+    const named = mix.naming === 0 ? undefined : mix.named.get(subject);
+    let j = 0;
+    const general = mix.general;
+    for (let i = 0; i <= general.length; i++) {
+        const voice = i < general.length ? general[i] : null;
+        // The voices naming the subject that come before this one, then this one.
+        for (;;) {
+            const mine = named !== undefined && j < named.length ? named[j] : null;
+            const next = mine !== null && (voice === null || mine.id < voice.id) ? mine : voice;
+            if (next === null)
+                break;
+            if (next === mine)
+                j++;
+            const held = mix.linkable(next, subject, slot);
+            if (held !== null) {
+                held.voice = next;
+                held.next = null;
+                if (prev === null)
+                    first = held;
+                else
+                    prev.next = held;
+                prev = held;
+            }
+            if (next === voice)
+                break;
+        }
+    }
+    return first;
+}
 /** A voice's record for a subject where its chain links it: the voice plays or freezes, and reaches it. */
-export function linkable(voice, subject, now, slot) {
+export function linkable(voice, subject, slot) {
     const state = voice.state;
     if (state === 'done' || (state === 'pending' && !voice.freezesBefore))
         return null;
-    const held = this.held(voice, subject, now, slot);
+    // A voice sharing one record is in no chain: a fold takes it from `sharers` at its place.
+    if (voice.sharing && everyoneOf(this, voice) !== null) {
+        // A projection numbers no subject, and keeps nothing by subject.
+        if (slot >= 0)
+            sight(voice, slot, this.lanes.cap);
+        return null;
+    }
+    const held = this.held(voice, subject, slot);
     return held.reaches ? held : null;
 }
 /** Whether a voice reaches a subject by what its spec says: the subjects it names, or its `target`. */
 export function aims(voice, subject) {
     // A read back to before a subject left still finds it reached.
     const left = voice.parted?.get(subject);
-    if (left !== undefined && !(this.now < left))
+    if (left !== undefined && !(this.now < left.at))
         return false;
     if (voice.named !== null)
         return voice.named.has(subject);
@@ -128,6 +124,13 @@ export function index(mix, voice) {
         return;
     if (voice.named === null) {
         mix.general.push(voice);
+        if (voice.sharing) {
+            const sharers = mix.sharers;
+            let i = sharers.length;
+            while (i > 0 && sharers[i - 1].id > voice.id)
+                i--;
+            sharers.splice(i, 0, voice);
+        }
         return;
     }
     mix.naming++;

package/dist/channels.d.ts

@@ -14,14 +14,17 @@ export declare function lerpInto(channel: Channel<unknown>): LerpInto | undefine
 /**
  * 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.
+ * `'own'` folds its axes as one value, through the channel's own `fold`.
  */
 export interface Numeric {
-    op: 'sum' | 'mul' | 'max' | 'last';
+    op: 'sum' | 'mul' | 'max' | 'last' | 'own';
     axes: number;
+    /** An angle's full turn: each value is taken the short way round before it folds. */
+    turn?: 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.
+ * The stock arithmetic of a channel `sum`, `mul`, `max` or `vec` made, or `vouch` was given, 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;
 /** Vouches for a stock channel made outside this module, as `color` makes its own. */
@@ -30,7 +33,10 @@ export declare function vouch(channel: Channel<unknown>, numeric: Numeric): void
 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. */
+/**
+ * `merge(acc, scale(v, w))` for a stock numeric channel, in exactly its arithmetic. Not for an
+ * `'own'` channel, and an angle's `v` is taken the short way round first.
+ */
 export declare function foldNumber(op: Numeric['op'], acc: number, v: number, w: number): number;
 /**
  * What a stock numeric channel takes.
@@ -69,15 +75,30 @@ export declare function max(opts?: NumberOptions): Channel<number>;
 export declare function last<V>(opts?: {
     lerp?: (a: V, b: V, u: number) => 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.
+ *
+ * @category channel
+ */
+export type Vec<N extends number> = number extends N ? number[] : Tuple<N>;
 /**
  * Vec3 position, premultiplied light: one channel's arithmetic applied down an axis list.
  *
  * @category channel
  */
-export declare function vec(n: number, of: Channel<number>): Channel<number[]>;
+export declare function vec<N extends number>(n: N, of: Channel<number>): Channel<Vec<N>>;
 /**
  * A kit is plain data; this only fixes the type.
  *
  * @category channel
  */
 export declare function kit<O>(channels: Kit<O>): Kit<O>;
+export {};

package/dist/channels.js

@@ -1,7 +1,8 @@
+import { shared } from './shared.js';
 /** The stock numeric channels' `lerp`, which `vec` applies per axis and lanes call directly. */
 export const lerpNumber = (a, b, u) => a + (b - a) * u;
 const mix = lerpNumber;
-const inPlace = new WeakMap();
+const inPlace = shared('lerp-into@1');
 /**
  * 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.
@@ -15,10 +16,10 @@ 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();
+const numerics = shared('numeric@1');
 /**
- * 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.
+ * The stock arithmetic of a channel `sum`, `mul`, `max` or `vec` made, or `vouch` was given, 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);
@@ -27,7 +28,7 @@ export function numericOf(channel) {
 export function vouch(channel, numeric) {
     numerics.set(channel, numeric);
 }
-const widths = new WeakMap();
+const widths = shared('width@1');
 /** 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);
@@ -37,7 +38,10 @@ 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. */
+/**
+ * `merge(acc, scale(v, w))` for a stock numeric channel, in exactly its arithmetic. Not for an
+ * `'own'` channel, and an angle's `v` is taken the short way round first.
+ */
 export function foldNumber(op, acc, v, w) {
     if (op === 'sum')
         return add(acc, times(v, w));
@@ -120,7 +124,7 @@ export function last(opts) {
  * 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) {
+export function doubles(n, v) {
     if (n === 0)
         return [];
     const a = [0.5];
@@ -174,7 +178,7 @@ export function vec(n, of) {
     };
     inPlace.set(channel, lerpTo);
     const inner = numerics.get(of);
-    if (inner !== undefined && inner.axes === 1)
+    if (inner !== undefined && inner.axes === 1 && inner.turn === undefined)
         numerics.set(channel, { ...inner, axes: n });
     return channel;
 }

package/dist/clock.d.ts

@@ -24,9 +24,16 @@ export declare function envelope(fadeIn: number, out: {
 } | 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.
+ * before, else NaN, where it shows nothing; `span` once its passes end if it freezes after. A `raw`
+ * of NaN is before its start: a pending voice at rate 0 whose pinned start a mix at rate 0 puts at
+ * infinity reads its clock as infinity times 0.
  */
 export declare function frozenTime(raw: number, before: boolean, after: boolean, span: number): number;
+/**
+ * `Object.is` for two numbers, which V8 answers by boxing both where it does not inline the call: 32
+ * bytes a subject in a fill's loop (bench/allocs.mjs, 2026-10-09).
+ */
+export declare function same(a: number, b: number): boolean;
 /** A weight held to 0..1. */
 export declare function clampWeight(raw: number): number;
 /**

package/dist/clock.js

@@ -28,7 +28,9 @@ export function passAt(elapsed, duration, passes) {
 export function envelope(fadeIn, out, ease, reduced, now, since, back = null) {
     let w = 1;
     if (fadeIn > 0 && !reduced) {
-        const u = (now - since) / fadeIn;
+        // A fade in stops climbing where a fade out begins, or the two ramps multiply into a rise.
+        const end = out && !out.rest && out.at < now ? out.at : now;
+        const u = (end - since) / fadeIn;
         if (u < 1)
             w *= ease ? ease(Math.max(0, u)) : Math.max(0, u);
     }
@@ -48,13 +50,22 @@ export function envelope(fadeIn, out, ease, reduced, now, since, back = null) {
 }
 /**
  * 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.
+ * before, else NaN, where it shows nothing; `span` once its passes end if it freezes after. A `raw`
+ * of NaN is before its start: a pending voice at rate 0 whose pinned start a mix at rate 0 puts at
+ * infinity reads its clock as infinity times 0.
  */
 export function frozenTime(raw, before, after, span) {
-    if (raw < 0)
+    if (!(raw >= 0))
         return before ? 0 : Number.NaN;
     return after && raw > span ? span : raw;
 }
+/**
+ * `Object.is` for two numbers, which V8 answers by boxing both where it does not inline the call: 32
+ * bytes a subject in a fill's loop (bench/allocs.mjs, 2026-10-09).
+ */
+export function same(a, b) {
+    return a === b ? a !== 0 || 1 / a === 1 / b : Number.isNaN(a) && Number.isNaN(b);
+}
 /** A weight held to 0..1. */
 export function clampWeight(raw) {
     return raw < 0 ? 0 : raw > 1 ? 1 : raw;

package/dist/clone.d.ts

@@ -4,4 +4,7 @@
  * anything it would refuse, goes to it. A read back copies a record per voice and subject.
  */
 export declare function clone<T>(v: T): T;
+/** A copy a fold may write into: arrays, typed arrays and plain objects copied, the rest as is. */
 export declare function copy(v: unknown): unknown;
+/** Whether `copy` can copy `v` faithfully, when it is an object. */
+export declare function copyable(v: object): boolean;

package/dist/clone.js

@@ -52,6 +52,21 @@ function copied(v, depth) {
     }
     return out;
 }
+/** A copy a fold may write into: arrays, typed arrays and plain objects copied, the rest as is. */
 export function copy(v) {
-    return Array.isArray(v) ? [...v] : v;
+    if (typeof v !== 'object' || v === null)
+        return v;
+    if (Array.isArray(v))
+        return [...v];
+    if (ArrayBuffer.isView(v))
+        return v.slice();
+    return plainObject(v) ? clone(v) : v;
+}
+/** Whether `copy` can copy `v` faithfully, when it is an object. */
+export function copyable(v) {
+    return Array.isArray(v) || ArrayBuffer.isView(v) || plainObject(v);
+}
+function plainObject(v) {
+    const proto = Object.getPrototypeOf(v);
+    return proto === Object.prototype || proto === null;
 }

package/dist/closed.d.ts

@@ -6,7 +6,7 @@ export declare const OVER = 2;
 export declare const COAST = 3;
 export declare const EASED = 4;
 /**
- * A stretch `t` voice ms into it, released at `at` from `x0` moving at `v0` toward `to` (each read
+ * A stretch at voice time `t`, released at `at` from `x0` moving at `v0` toward `to` (each read
  * from its offset), into `xo` and `vo`: the one copy of the closed forms, which `law` (a patch's
  * `[form, settle, k1, k2, k3]`, the head of a patch's buffer or a copy of it) picks between. A tween reads `ease` and
  * `ms`, the stretch's length, dividing in milliseconds so a boundary lands exactly; every other