@msb235/blits 0.13.0 → 0.15.0

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.
      */

package/dist/types/history.d.ts

@@ -1,6 +1,6 @@
 import type { VoiceSpec } from './voice.js';
 /**
- * What a mix or transport remembers, for `seek` and `project` to read back: see
+ * What a mix or transport remembers, for `seek` and `project` to read back. See
  * `MixOptions.history`.
  *
  * @category mix
@@ -17,11 +17,11 @@ export interface HistoryOptions {
      * the tape: the host bounds it.
      */
     store?: HistoryStore;
-    /** Rebuilds a cued voice's spec from the descriptor it was cued with, so the voice can be paged out. */
+    /** Rebuilds a cued voice's spec from its descriptor. That lets the voice be paged out. */
     revive?(d: Described): VoiceSpec<any, any>;
 }
 /**
- * A voice as plain data: `kind` names what built it, and `data` survives `structuredClone`.
+ * A voice as plain data. `kind` names what built it, and `data` survives `structuredClone`.
  *
  * @category mix
  */
@@ -39,21 +39,23 @@ export interface HistoryStore {
     /** Records leaving memory. One brought back by a seek may be paged again: keep one per key and `seq`. */
     page(out: readonly Paged[]): void;
     /**
-     * What a restore to mix time `t` needs, for every mix: from each stream, per voice and subject,
-     * the latest record at or before `t` and every record after it. Returning everything is fine.
+     * Loads what a restore to mix time `t` needs, for every mix. That is, from each stream, per voice
+     * and subject, the latest record at or before `t` and every record after it. Returning
+     * everything is fine.
      */
     load(t: number): Promise<readonly Paged[]>;
     /**
-     * A seek went back to frame `seq`: every record whose `seq` is greater is from a future the tape
-     * makes again. Forget them.
+     * Forgets every record after frame `seq`, which a seek went back to. Every record whose `seq` is
+     * greater is from a future the tape makes again.
      */
     cut(seq: number): void;
 }
 /**
- * What a history record holds: a voice's `controls`, a stateful record's `snap`, an `input`
- * signal's reading, a subject's record when it `left` a voice, a motion subject's `released` run
- * or older `stretch`, the `host` fields patches read, a whole `voice` that has left, or the
- * transport's own: a `mark` announced on it, a change of its `pace`, and a `frame` it played.
+ * Which kind of thing a history record holds. It is a voice's `controls`, a stateful record's
+ * `snap`, an `input` signal's reading, a subject's record when it `left` a voice, a motion
+ * subject's `released` run or older `stretch`, the `host` fields patches read, a whole `voice`
+ * that has left, or the transport's own: a `mark` announced on it, a change of its `pace`, and a
+ * `frame` it played.
  *
  * @category mix
  */
@@ -64,12 +66,17 @@ export type PagedStream = 'voice' | 'snap' | 'input' | 'left' | 'released' | 'st
  * @category mix
  */
 export interface Paged {
-    /** The mix's `name`; '' for a mix made alone without one, and for the transport's own records. */
+    /**
+     * The mix's `name`. It is '' for a mix made alone without one, and for the transport's own
+     * records.
+     */
     mix: string;
     stream: PagedStream;
     /** The voice's id, for every stream but `host` and the transport's own. */
     voice?: number;
-    /** The subject's key, for a record of one subject; for a `mark`, the number it was announced as. */
+    /**
+     * The subject's key, for a record of one subject. For a `mark`, the number it was announced as.
+     */
     subject?: string | number;
     /** Mix time. */
     at: number;
@@ -81,7 +88,7 @@ export interface Paged {
     data: unknown;
 }
 /**
- * One host call a mix recorded on its tape: `apply` makes it again, and `invert` does nothing,
+ * One host call a mix recorded on its tape. `apply` makes it again, and `invert` does nothing,
  * since a mix goes back by restoring what it kept rather than by undoing calls.
  *
  * @category mix
@@ -92,8 +99,8 @@ export interface TapeOp {
     label?: string;
 }
 /**
- * One future a tape keeps at its current entry: the calls the host made after the mix last went
- * back here, before it made new ones.
+ * One future a tape keeps at its current entry. It holds the calls the host made after the mix
+ * last went back here, before it made new ones.
  *
  * @category mix
  */
@@ -126,14 +133,23 @@ export interface Tape {
     switchBranch(id: number): void;
 }
 /**
- * Makes a mix's tape: weasel-history's `createHistory` is one. The mix passes the clock it stamps
+ * Makes a mix's tape. weasel-history's `createHistory` is one. The mix passes the clock it stamps
  * calls with, branching on, so a call made after going back keeps the old future as a branch, and
  * coalescing off.
  *
  * @category mix
  */
-export type TapeMaker = (adapter: unknown, opts: {
+export type TapeMaker = (adapter: unknown, opts: TapeOptions) => Tape;
+/**
+ * What a mix passes its `TapeMaker` besides the adapter.
+ *
+ * @category mix
+ */
+export interface TapeOptions {
+    /** The clock the tape stamps calls with. */
     now: () => number;
+    /** Always `true`, so a call made after going back keeps the old future as a branch. */
     branching: boolean;
+    /** Always `0`, which turns coalescing off. */
     coalesceWindowMs: number;
-}) => Tape;
+}