@msb235/blits 0.14.0 → 0.15.0

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;
+}