@msb235/blits 0.14.0 → 0.15.0

package/dist/strays.js

@@ -1,6 +1,6 @@
 import { unpart } from './fade.js';
 import { pageOut } from './paging.js';
-import { record, unplayable } from './tape.js';
+import { record, taping, unplayable } from './tape.js';
 /** Notes a motion patch that may hold state for a subject no voice playing it reaches. */
 export function stray(mix, motion, subject) {
     const list = mix.strays.get(subject);
@@ -24,7 +24,7 @@ export function unplay(mix, voice) {
     if (voice.named === null)
         mix.strayAll.add(motion);
     else
-        for (const subject of voice.named)
+        for (const subject of voice.named.list)
             stray(mix, motion, subject);
 }
 /**
@@ -45,19 +45,14 @@ export function motionOwner(mix) {
         seq() {
             return mix.deref()?.transport.seq ?? Number.NaN;
         },
+        early() {
+            const m = mix.deref();
+            return m !== undefined && (m.syncing || !m.looked);
+        },
         changed(id, motion, subject, change) {
             const m = mix.deref();
-            if (m === undefined)
-                return;
-            record(m, 'motion', (stage) => {
-                const to = stage.mix(m);
-                if (to === undefined)
-                    return;
-                if (to !== m)
-                    return changeAhead(to, id, motion, subject, change);
-                const v = cuedById(m, id) ?? m.gone.find((g) => g.id === id);
-                (v?.motion ?? motion).change(subject, { ...change });
-            });
+            if (m !== undefined && taping(m))
+                recordChange(m, id, motion, subject, change);
         },
         page(id, stream, subject, out) {
             const m = mix.deref();
@@ -84,6 +79,18 @@ export function motionOwner(mix) {
         },
     };
 }
+// Apart from `changed`, whose body would otherwise make this closure's context on every change.
+function recordChange(m, id, motion, subject, change) {
+    record(m, 'motion', (stage) => {
+        const to = stage.mix(m);
+        if (to === undefined)
+            return;
+        if (to !== m)
+            return changeAhead(to, id, motion, subject, change);
+        const v = cuedById(m, id) ?? m.gone.find((g) => g.id === id);
+        (v?.motion ?? motion).change(subject, { ...change });
+    });
+}
 /**
  * A retarget or push the tape holds, made for a read ahead: kept on its transport for the patch
  * to apply as it reads, since the patch's own state is the live mix's.

package/dist/stretch.d.ts

@@ -0,0 +1,112 @@
+import type { Curve } from './easing.js';
+import type { Motions } from './motions.js';
+import type { MotionSpec } from './types.js';
+/**
+ * One closed-form stretch: released at `at` (voice ms) from `x0` moving at `v0`, toward `to`, over
+ * `ms` for a tween (0 for any other shape).
+ */
+export interface Segment {
+    at: number;
+    ms: number;
+    x0: number[];
+    v0: number[];
+    to: number[];
+    /** The change that released it; undefined for a subject's first stretch. */
+    change?: Change;
+}
+export interface Change {
+    /**
+     * Voice ms it takes effect at; absent, until the subject's next read stamps it with that read's
+     * time, for one made while no frame had met the subject.
+     */
+    at?: number;
+    to?: number[];
+    /** Where it moves from, in place of where its stretch has it then. */
+    x?: number[];
+    v?: number[];
+    /** The mix clock when it was made, NaN where no mix was playing the patch. */
+    made?: number;
+    /** The frame it was made in, which a rewind partitions by; NaN where no mix was playing the patch. */
+    seq?: number;
+    /** Whether it was made before its frame was read, so a read of what that frame showed has it. */
+    early?: boolean;
+}
+/** A record of a motion patch's history leaving memory, at a mix time and frame. */
+export interface Paging {
+    at: number;
+    seq: number;
+    data: unknown;
+}
+/** A subject's run as plain data: its flags, its stretches oldest first, and changes still to apply. */
+export interface Run {
+    flags: number;
+    stretches: Segment[];
+    pending: Change[] | undefined;
+}
+/** `n` numbers of `from` from `at`, as an array of their own. */
+export declare function numbers(from: Float64Array, at: number, n: number): number[];
+/**
+ * A subject's flags: its value is a number; it has changes pending; it has older stretches; the
+ * stretch it is playing was found landed, which holds until another replaces it.
+ */
+export declare const enum RunFlag {
+    SCALAR = 1,
+    PENDING = 2,
+    OLDER = 4,
+    LANDED = 8
+}
+/**
+ * The mix playing a patch, asked with its voice's id: an owner and an id, where a pair of closures
+ * cost two functions, their contexts and a weak reference per voice.
+ */
+export interface MotionOwner {
+    /** The subject's voice time at the mix's latest frame; NaN where no frame of the voice met it. */
+    frame(id: number, subject: unknown): number;
+    /**
+     * Brings a subject the voice faded out back to it, so a change is not made for nothing: its
+     * voice time now, which a change bringing it back is made at; NaN for any other subject.
+     */
+    revive(id: number, subject: unknown): number;
+    /** The mix clock at its latest frame; NaN before the first. */
+    now(): number;
+    /** The number of the frame the mix is playing. */
+    seq(): number;
+    /** Whether a change made now comes before anything read the frame. */
+    early(): boolean;
+    /**
+     * The host made a change, already given its time, which a seek makes again on the patch its
+     * voice plays then: a voice a history store paged out comes back with a patch of its own.
+     */
+    changed<I>(id: number, motion: Motions<I>, subject: I, change: Change): void;
+    /** History leaving memory for a subject, which a mix with a history store pages out. */
+    page(id: number, stream: 'released' | 'stretch', subject: unknown, out: Paging[]): void;
+}
+/**
+ * What a mix keeping copies of a patch's stretches is told, with its id and the subject's number,
+ * before one changes.
+ */
+export interface Watcher {
+    stretchChanged(id: number, s: number): void;
+}
+export interface Shape<I> {
+    from: (subject: I) => number[];
+    /** How fast each axis starts moving, given where it starts: still unless the options say. */
+    velocity: (subject: I, x: number[]) => number[];
+    /**
+     * Where it heads when released from `x` at `v`, given where it was heading; `put` for a stretch a
+     * `set` released.
+     */
+    aim: (x: number[], v: number[], was: number[] | null, subject: I, put: boolean) => number[];
+    /** `[form, settle, k1, k2, k3]`. */
+    law: readonly number[];
+    /** Whether a subject's value is a number rather than an array. */
+    scalar: (subject: I) => boolean;
+    /** Whether every subject's value is a number; undefined where that depends on the subject. */
+    scalarEvery(): boolean | undefined;
+    /** A tween's easing, which its law cannot hold; undefined, but present, on every other shape. */
+    ease: Curve | undefined;
+    /** A tween's ms for a stretch the subject starts now; undefined, but present, on the rest. */
+    ms: ((subject: I) => number) | undefined;
+    /** The patch's kind and constants, as `Patch.motion` reports them. */
+    spec(): MotionSpec;
+}

package/dist/stretch.js

@@ -0,0 +1,9 @@
+/** Where `numbers` gathers what it copies, kept an array of doubles so every copy is one too. */
+const gathered = [0.5];
+/** `n` numbers of `from` from `at`, as an array of their own. */
+export function numbers(from, at, n) {
+    // `Array.from` walks a typed array by its iterator: about 500 B a call for three axes.
+    for (let i = 0; i < n; i++)
+        gathered[i] = from[at + i];
+    return gathered.slice(0, n);
+}

package/dist/subject.d.ts

@@ -0,0 +1,142 @@
+import type { Stamp } from './restored.js';
+/**
+ * A subject's record as it left a voice, faded out of it or dropped: the mix time and frame it
+ * left at, and `sync` where it shows in its own frame: left in the frame's sync, or before anything
+ * read the mix that frame.
+ */
+export interface Left<I> {
+    subject: I;
+    at: number;
+    seq: number;
+    sync: boolean;
+    held: Subject<unknown>;
+    /**
+     * The voice's fade of the subject as it stood on leaving, which a seek or read back to before
+     * puts back: its ramp out, while running, or its having faded out.
+     */
+    ramp: Parting | null;
+    parted: Parted | null;
+}
+/** A subject's ramp out of one voice: when it began, how long it runs, and the frame it was asked in. */
+export interface Parting {
+    at: number;
+    over: number;
+    seq: number;
+}
+export interface Parted {
+    at: number;
+    seq: number;
+    ramp: Parting | undefined;
+}
+/**
+ * What a copy of a record keeps for the seeks that put a record back from it: the copy's state
+ * stepped on to `ticks`, as it stood near `at`, a moment one of them sought.
+ */
+export interface Ahead<S> {
+    /** The record the last seek put back, and the moment it sought, until that record steps. */
+    put: Subject<S> | null;
+    sought: number;
+    /** The `since` of the record put back, which the steps in `state` were counted from. */
+    since: number;
+    at: number;
+    ticks: number;
+    /** Undefined until a record has stepped on from the copy. */
+    state: S | undefined;
+    /**
+     * The state the record a seek replaced had stepped on to from the copy, at `leftTicks`; undefined
+     * until one had.
+     */
+    leftTicks: number;
+    left: S | undefined;
+}
+/** A copy of a record kept under `history`, by the mix time and frame it was taken at. */
+export interface Snap<S> {
+    at: number;
+    seq: number;
+    held: Subject<S>;
+    ahead?: Ahead<S>;
+    /** Set where another record's list holds it too, so a seek cutting it from one lets go of it. */
+    shared?: true;
+}
+/** Everything one voice holds for one subject, chained through the next voice that reaches it. */
+export interface Subject<S> {
+    /** The voice's `target` answer, fixed on first sight. */
+    reaches: boolean;
+    /** The voice's `stagger` answer in voice ms, fixed on first sight. */
+    delay: number;
+    /** The mix timestamp this subject's delay ran out at, which its step grid counts from. */
+    since: number;
+    /** The mix timestamp its fade in counts from: `since`, or earlier for a voice freezing before. */
+    shown: number;
+    /** The weight this voice gave this subject the last frame it was probed, 0 where it gave none. */
+    weight: number;
+    /**
+     * The mix time it was left at rest during a handover, so it stops contributing, and which a seek
+     * reads to know whether it had by then; NaN while it has not (`isRested`).
+     */
+    restedAt: number;
+    /**
+     * Per written channel, whether a rest-less contribution is on: 0 unknown, 1 on, 2 off; null until
+     * a rest-less channel asks.
+     */
+    bands: Uint8Array | null;
+    state: S;
+    /** The `now` this subject last caught up to, for this voice. */
+    stepped: number;
+    /** Under `stepMs`, how many intervals have run since `since`; `stepped` is where that lands. */
+    ticks: number;
+    /** The `now` this subject was last probed at, so twelve probes in a frame step once. */
+    probed: number;
+    /** The last delta computed this frame, handed back to a repeat probe unchanged. */
+    delta: Record<string, unknown> | null;
+    /** The phase `delta` was read at, to read it again once its voice's scratch has moved on. */
+    phase: number;
+    /** The voice's `seeks` when `delta` was read, so a seek later in the frame reads it again. */
+    seeks: number;
+    /** The voice's `rebuilds` when its state was last made, so a seek's rebuild reaches it once. */
+    rebuilt: number;
+    /** Its kept signal state was stepped on in one go from a copy history kept, by a seek. */
+    copied: boolean;
+    /** Stop 0 for a `from: 'current'` voice, taken the first frame this subject is seen. */
+    base?: Record<string, unknown>;
+    /** The pose's velocity per channel at that moment, units per ms, so the first segment leaves at it. */
+    slope?: Record<string, unknown>;
+    /** What `setting.keep` holds for this voice and subject, by owner; null until it holds any. */
+    kept: Map<object, unknown> | null;
+    /** Kept state a history store gave back, which each owner takes in turn on its first keep. */
+    unkept?: unknown[];
+    /** Under `history`, copies of this record by the mix time they were taken, oldest first. */
+    snaps?: Snap<S>[];
+    /** In a projection: where this record started from, and whether nothing known could be. */
+    from?: number;
+    unknown?: boolean;
+    /** Under `history` with `inputs`, what an input weight signal read for this subject, when it changed. */
+    inputs?: {
+        at: number;
+        seq: number;
+        value: number;
+    }[];
+    /** In a projection reading back: that record, to read in place of the signal. */
+    replay?: {
+        at: number;
+        value: number;
+    }[];
+    /** The voice this is the record of; null on a subject's stub. */
+    voice: object | null;
+    /** The next voice's record for this subject, in voice order, among those that reach it. */
+    next: Subject<unknown> | null;
+    /**
+     * On the first record, which the mix keeps per subject so a probe makes one lookup: the `version`
+     * the chain was linked at, and per role, by channel slot, whether a rest-less contribution is on:
+     * 0 never decided, 1 on, 2 off.
+     */
+    version: number;
+    roles: Map<string, Uint8Array> | null;
+    /** On the first record: the number lanes index this subject by, -1 without one. */
+    slot: number;
+    /** A motion voice's number for this subject in its patch, good while `freed` is the patch's own. */
+    run: number;
+    freed: number;
+    /** In a voice's store once a seek has gone back, the stamp of the seek it was last put back or written at. */
+    restored: Stamp | null;
+}

package/dist/subject.js

@@ -0,0 +1 @@
+export {};

package/dist/tape.d.ts

@@ -18,15 +18,18 @@ export declare function unplayable(what: string): never;
  * at: rate 0 holds mix time still across frames, and host time tells them apart.
  */
 export declare function tapeOf(transport: Transport): Tape | undefined;
+interface Recorder {
+    readonly tape: Tape | undefined;
+    readonly replaying: boolean;
+    readonly projecting: boolean;
+}
+/** Whether `record` keeps a call made on `on` now, so a caller can skip making one it would drop. */
+export declare function taping(on: Recorder): boolean;
 /**
  * Records a host call, which `again` makes once more when the mix plays past it after a seek, or
  * when a read ahead does, on the stage it is given.
  */
-export declare function record(on: {
-    readonly tape: Tape | undefined;
-    readonly replaying: boolean;
-    readonly projecting: boolean;
-}, label: string, again: (stage: Stage) => void): void;
+export declare function record(on: Recorder, label: string, again: (stage: Stage) => void): void;
 /** The host time at which the mix clock reads `t`, under the rate it has now. */
 export declare function hostAt(clock: {
     readonly pace: Pace | null;
@@ -47,3 +50,4 @@ export declare function hostAhead(clock: {
  * stage of its copies, it makes them on those, and the caller puts the tape back.
  */
 export declare function replay(transport: Transport, due: (u: number) => boolean, onto?: Transport, on?: Stage): number;
+export {};

package/dist/tape.js

@@ -24,13 +24,17 @@ export function tapeOf(transport) {
         coalesceWindowMs: 0,
     });
 }
+/** Whether `record` keeps a call made on `on` now, so a caller can skip making one it would drop. */
+export function taping(on) {
+    return on.tape !== undefined && !on.replaying && !on.projecting;
+}
 /**
  * Records a host call, which `again` makes once more when the mix plays past it after a seek, or
  * when a read ahead does, on the stage it is given.
  */
 export function record(on, label, again) {
     const tape = on.tape;
-    if (tape === undefined || on.replaying || on.projecting)
+    if (tape === undefined || !taping(on))
         return;
     const op = {
         label,

package/dist/then.d.ts

@@ -0,0 +1,9 @@
+import { type Cut } from './cut.js';
+import type { Motions } from './motions.js';
+/**
+ * `subject`'s position and velocity at voice time `t`, into the patch's `xs` and `vs`, as frame `cut` left it:
+ * in the run it had then, with only the changes made by then, as a seek back there plays it. A run
+ * with none made since reads as it stands; one with some plays from its earliest stretch kept,
+ * the rest applied again in the order they take effect. Commits nothing, and gives the run's flags.
+ */
+export declare function sampleThen<I>(motions: Motions<I>, subject: I, t: number, cut: Cut): number;

package/dist/then.js

@@ -0,0 +1,57 @@
+import { within } from './cut.js';
+/** Whether `c` was made by frame `cut`; one made with no mix playing its patch was. */
+const madeBy = (c, cut) => c.seq === undefined || Number.isNaN(c.seq) || within(cut, c.seq, c.early === true);
+/** The stretch playing at voice time `t` of a run's, oldest first: the latest released by then, else the first. */
+function playingIn(list, t) {
+    const last = list[list.length - 1];
+    if (t >= last.at || list.length === 1)
+        return last;
+    if (list[0].at > t)
+        return list[0];
+    let lo = 0;
+    let hi = list.length - 2;
+    while (lo < hi) {
+        const mid = (lo + hi + 1) >> 1;
+        if (list[mid].at <= t)
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    return list[lo];
+}
+/**
+ * `subject`'s position and velocity at voice time `t`, into the patch's `xs` and `vs`, as frame `cut` left it:
+ * in the run it had then, with only the changes made by then, as a seek back there plays it. A run
+ * with none made since reads as it stands; one with some plays from its earliest stretch kept,
+ * the rest applied again in the order they take effect. Commits nothing, and gives the run's flags.
+ */
+export function sampleThen(motions, subject, t, cut) {
+    const run = motions.runThen(subject, cut) ?? motions.freshRun(subject);
+    let stretches = run.stretches;
+    let pending = run.pending ?? [];
+    const kept = [];
+    let since = false;
+    for (const c of [...stretches.slice(1).map((seg) => seg.change), ...pending])
+        if (c === undefined || madeBy(c, cut)) {
+            if (c !== undefined)
+                kept.push(c);
+        }
+        else
+            since = true;
+    if (since) {
+        stretches = [stretches[0]];
+        pending = kept
+            .filter((c) => c.at !== undefined)
+            .sort((a, b) => a.at - b.at);
+    }
+    let seg = playingIn(stretches, t);
+    for (const c of pending) {
+        const a = c.at;
+        if (a === undefined || !(a <= t))
+            break;
+        if (a >= seg.at)
+            seg = motions.applied(subject, seg, c, a);
+    }
+    motions.evaluateSegment(seg, t, motions.xs, motions.vs);
+    return run.flags;
+}

package/dist/ticker.d.ts

@@ -1,5 +1,5 @@
 /**
- * What a ticker runs: a mix, or anything that syncs, sleeps on `inert` and wakes by `onWake`.
+ * What a ticker runs. A mix, or anything that syncs, sleeps on `inert` and wakes by `onWake`.
  *
  * @category mix
  */
@@ -21,9 +21,9 @@ export interface TickerOptions {
      */
     fps?: number;
     /**
-     * Where frames come from: `'frame'`, `requestAnimationFrame`, or `'timer'`, `setTimeout`. By
-     * default animation frames where they exist, and a timer where they don't, as in a worker
-     * without them or in Node.
+     * Where frames come from. `'frame'` is `requestAnimationFrame`, and `'timer'` is `setTimeout`. By
+     * default animation frames where they exist, and a timer where they don't, as in a worker without
+     * them or in Node.
      */
     grain?: 'frame' | 'timer';
     /**

package/dist/transport.d.ts

@@ -31,14 +31,6 @@ export interface Frame {
     at: number;
     u: number;
 }
-/** Where history is cut for a seek or read: what frame `seq` made, and before it, is kept. */
-export interface Cut {
-    seq: number;
-    /** For a read of what a frame showed: of that frame's own changes, only those made before it was read. */
-    strict: boolean;
-}
-/** Whether a change made in frame `seq` falls inside `cut`; `early` for one made before the frame was read. */
-export declare function within(cut: Cut, seq: number, early?: boolean): boolean;
 /**
  * The clock its mixes play on: host time less what `rebase` took out, at the rate its `pace`
  * sets, moved by `sync` and `seek`, and the tape of calls a seek plays again. A mix made alone

package/dist/transport.js

@@ -11,10 +11,6 @@ import { hostAt, record, replay, tapeOf } from './tape.js';
 import { gave, historyFor } from './watch.js';
 /** How far the tape's reach moves before it is pruned again, ms of mix time. */
 const TAPE_STEP_MS = 1000;
-/** Whether a change made in frame `seq` falls inside `cut`; `early` for one made before the frame was read. */
-export function within(cut, seq, early = false) {
-    return seq < cut.seq || (seq === cut.seq && (!cut.strict || early));
-}
 /**
  * The clock its mixes play on: host time less what `rebase` took out, at the rate its `pace`
  * sets, moved by `sync` and `seek`, and the tape of calls a seek plays again. A mix made alone

package/dist/turns.d.ts

@@ -7,11 +7,12 @@ export declare function shortWay(d: number, turn: number): number;
  * `fold`, which takes its axes as one value.
  */
 export declare function turnInto(ch: Laned, values: Float64Array, base: number, value: unknown, w: number): void;
-/** `turnInto` for a value held as numbers at `from` in `source`, as a locus holds what it gathered. */
+/** `turnInto` for a value held as numbers at `from` in `source`, as a role holds what it gathered. */
 export declare function turnFrom(ch: Laned, values: Float64Array, base: number, source: Float64Array, from: number, w: number): void;
 /**
- * A locus member's rotation lerped by `u` into what the members before it left at `base`, through
- * the channel's own `lerp`; the first member's value as it is, where `taken` is 0.
+ * A role member's value for a channel not lerped straight across, lerped by `u` into what the
+ * members before it left at `base` through the channel's own `lerp`, or an angle's short way round;
+ * the first member's value as it is, where `taken` is 0.
  */
 export declare function turnToward(ch: Laned, values: Float64Array, base: number, value: unknown, taken: number, u: number): void;
 /** Sets every numbered subject's values on a lane to the channel's rest, as a fill starts from. */

package/dist/turns.js

@@ -28,7 +28,7 @@ export function turnInto(ch, values, base, value, w) {
     for (let a = 0; a < axes; a++)
         values[base + a] = out[a];
 }
-/** `turnInto` for a value held as numbers at `from` in `source`, as a locus holds what it gathered. */
+/** `turnInto` for a value held as numbers at `from` in `source`, as a role holds what it gathered. */
 export function turnFrom(ch, values, base, source, from, w) {
     if (ch.turn > 0) {
         turnInto(ch, values, base, source[from], w);
@@ -38,8 +38,9 @@ export function turnFrom(ch, values, base, source, from, w) {
     turnInto(ch, values, base, other, w);
 }
 /**
- * A locus member's rotation lerped by `u` into what the members before it left at `base`, through
- * the channel's own `lerp`; the first member's value as it is, where `taken` is 0.
+ * A role member's value for a channel not lerped straight across, lerped by `u` into what the
+ * members before it left at `base` through the channel's own `lerp`, or an angle's short way round;
+ * the first member's value as it is, where `taken` is 0.
  */
 export function turnToward(ch, values, base, value, taken, u) {
     if (ch.turn > 0) {

package/dist/types/arc.d.ts

@@ -1,7 +1,7 @@
 import type { Handle, OwnerSpec, VoiceSpec } from './voice.js';
 /**
- * One voice of an arc's part: a voice's spec, less what the arc sets for it. The arc places it,
- * fades it across each boundary by `blend`, and holds its first and last frames for the blend.
+ * One voice of an arc's part. It is a voice's spec, less what the arc sets for it. The arc places
+ * it, fades it across each boundary by `blend`, and holds its first and last frames for the blend.
  *
  * @category score
  */
@@ -13,15 +13,15 @@ export interface ArcVoice<I, O, H = unknown> extends Omit<VoiceSpec<I, O, H>, 'o
     duration?: number;
 }
 /**
- * One part of an arc: a voice, or several layered together that play as one and last as long as
- * the longest.
+ * One part of an arc. It is a voice, or several layered together that play as one and last as
+ * long as the longest.
  *
  * @category score
  */
 export type ArcPart<I, O, H = unknown> = ArcVoice<I, O, H> | readonly ArcVoice<I, O, H>[];
 /**
- * What `arc` takes: an owner over three parts that hand over in order, `enter`, `active` and
- * `exit`, any of which may be left out.
+ * What `arc` takes. It is an owner over three parts that hand over in order, `enter`, `active`
+ * and `exit`, any of which may be left out.
  *
  * @category score
  */
@@ -33,22 +33,23 @@ export interface ArcSpec<I, O, H = unknown> extends Omit<OwnerSpec<I, H>, 'freez
     /** What plays as it leaves. Its start is the arc's `out` mark, and its end the arc's `end`. */
     exit?: ArcPart<I, O, H>;
     /**
-     * How long `active` plays, ms on the arc's clock, looping for it unless its `loop` says how many
-     * passes; or `'open'`, until `release`. Default: `active`'s own length, held open where it loops
-     * for good, and 0 with no `active`.
+     * How long `active` plays, ms on the arc's clock, or `'open'`. A number loops `active` for it
+     * unless its `loop` says how many passes; `'open'` plays it until `release`. Default: `active`'s
+     * own length, held open where it loops for good, and 0 with no `active`.
      */
     hold?: number | 'open';
     /** A crossfade across each boundary, ms, half before it and half after. Default 0. */
     blend?: number;
 }
 /**
- * An arc's handle: an owner's, and the release of its hold. `fade` takes it out with no exit.
+ * An arc's handle, which can release its hold. It is an owner's handle, and `release` ends the
+ * hold. `fade` takes it out with no exit.
  *
  * @category score
  */
 export interface ArcHandle<I = unknown> extends Handle<I> {
     /**
-     * Ends the hold now and plays the exit, its blend starting here; where the enter is still
+     * Ends the hold now and plays the exit. Its blend starts here; where the enter is still
      * playing, the exit follows it. Nothing once the exit has begun or the arc is fading.
      */
     release(): void;

package/dist/types/channel.d.ts

@@ -5,9 +5,9 @@
  */
 export interface Channel<V> {
     /**
-     * Names this channel's arithmetic, so a patch written against one channel can be checked against
-     * another of the same name. Two channels of one kind must fold identically; the stock ones set it,
-     * as `'sum'` or `'vec(3, sum)'`. Absent, a channel matches only itself.
+     * Names this channel's arithmetic. A patch written against one channel can then be checked
+     * against another of the same name. Two channels of one kind must fold identically; the stock
+     * ones set it, as `'sum'` or `'vec(3, sum)'`. Absent, a channel matches only itself.
      */
     kind?: string;
     /**
@@ -16,21 +16,25 @@ export interface Channel<V> {
      * carries speed can push it out; overshoot stops flat at the bound.
      */
     bounds?: readonly [min: number, max: number];
-    /** Identity. Absent means the channel has none: it replaces rather than contributes. */
+    /**
+     * The value that changes nothing when folded in, such as 0 for `sum` or 1 for `mul`. Absent means
+     * the channel has none: it replaces rather than contributes.
+     */
     rest?: V;
     /** Fold two contributions into one. */
     merge(a: V, b: V): V;
     /** Fade toward `rest` by weight 0..1. Required when `rest` is set; absent otherwise. */
     scale?(v: V, w: number): V;
-    /** Interpolate, for retargeting, for blending alternatives, and for folding a locus. */
+    /** Interpolate, for retargeting, for blending alternatives, and for folding a role. */
     lerp(a: V, b: V, u: number): V;
     /**
-     * Optional: `merge(into, scale(v, w))`, written into `into` and returned, so a channel whose
-     * values are objects need not allocate per contribution. The mix only hands it a value it made.
+     * Folds a weighted contribution into `into` in place. Optional. It computes
+     * `merge(into, scale(v, w))`, written into `into` and returned, so a channel whose values are
+     * objects need not allocate per contribution. The mix only hands it a value it made.
      */
     fold?(into: V, v: V, w: number): V;
     /**
-     * Optional: a fresh copy of `v`, which the mix makes of `rest` for `fold` to write into. The mix
+     * A fresh copy of `v`. Optional. The mix makes one of `rest` for `fold` to write into. The mix
      * copies arrays, typed arrays and plain objects itself; a channel whose `rest` is anything else,
      * such as a class instance, and that has `fold`, needs this or `cue` refuses it.
      */