@msb235/blits 0.14.0 → 0.15.0

package/dist/types/motion.d.ts

@@ -0,0 +1,151 @@
+import type { Easing, Patch } from './patch.js';
+/**
+ * A number, or one number per axis.
+ *
+ * @category patch
+ */
+export type Value = number | readonly number[];
+/**
+ * One value for every subject, or one per subject.
+ *
+ * @category patch
+ */
+export type PerSubject<I, V> = V | ((subject: I) => V);
+/**
+ * Where a subject is and how fast it is moving. At one moment of voice time.
+ *
+ * @category patch
+ */
+export interface Motion<V extends Value = number> {
+    value: V;
+    /** How fast `value` is changing, in its units per second. */
+    velocity: V;
+}
+/**
+ * A patch whose motion is a closed form per subject. It lands in the same place at any frame rate,
+ * and its changes mid-flight start from where the subject is and how fast it moves.
+ *
+ * @category patch
+ */
+export interface Moving<I, O, V extends Value> extends Patch<I, O, void> {
+    /**
+     * Where `subject` is and how fast it moves at voice time `at`. `at` defaults to the mix's latest
+     * frame, counting every change due by then. With no time given, undefined until a frame of its
+     * voice has met the subject, while the subject is still inside its stagger, and once that voice
+     * is gone. At any time, undefined for a subject the patch has never met or changed, or that the
+     * mix dropped.
+     */
+    read(subject: I, at?: number): Motion<V> | undefined;
+    /**
+     * Sets `subject` moving at `velocity`, units per second, from voice time `at`. `at` defaults to
+     * the mix's latest frame; for a subject no frame of its voice has met yet, or still inside its
+     * stagger, its first read, after any change with a time due by then. A subject faded out of the
+     * voice comes back at the latest frame too, however long it is before it is next read.
+     */
+    push(subject: I, velocity: V, at?: number): void;
+    /**
+     * Puts `subject` at `value` from voice time `at`, keeping its velocity. `at` defaults as `push`'s
+     * does. A spring or tween heads for its target from there, a glide coasts on from there.
+     */
+    set(subject: I, value: V, at?: number): void;
+}
+/**
+ * What `spring` and `glide` both take.
+ *
+ * @category patch
+ */
+export interface MotionOptions<I, V extends Value> {
+    /** Units per second each subject starts moving at. Default 0. */
+    velocity?: PerSubject<I, V>;
+    /**
+     * How near and slow a subject must be to land exactly where it heads. Within this distance of
+     * where it heads, and this slow, a subject lands there exactly, so a mix can see it at rest.
+     * Default 1e-4; 0 keeps the curve exact.
+     */
+    settle?: number;
+}
+/**
+ * What `spring` takes.
+ *
+ * @category patch
+ */
+export interface SpringOptions<I, V extends Value> extends MotionOptions<I, V> {
+    to: PerSubject<I, V>;
+    /** Where each subject starts. Default: `to`, at rest. */
+    from?: PerSubject<I, V>;
+    /** How hard the spring pulls toward its target, per second squared. Default 170. */
+    stiffness?: number;
+    /**
+     * How fast the spring's motion dies away, per second. Default 26, just short of critical at the
+     * default stiffness.
+     */
+    damping?: number;
+    mass?: number;
+}
+/**
+ * What `glide` takes.
+ *
+ * @category patch
+ */
+export interface GlideOptions<I, V extends Value> extends MotionOptions<I, V> {
+    /** Where each subject starts. */
+    from: PerSubject<I, V>;
+    /** The friction's time constant, ms. Default 325, a touch scroll's. */
+    ms?: number;
+    /** The least and greatest value a coast comes to rest at, per axis. Default none. */
+    bounds?: PerSubject<I, readonly [min: V, max: V]>;
+    /** The spring back's, per second squared, with `bounds`. Default 170, as a spring's. */
+    stiffness?: number;
+}
+/**
+ * What `tween` takes.
+ *
+ * @category patch
+ */
+export interface TweenOptions<I, V extends Value> {
+    /** Where each subject starts. */
+    from: PerSubject<I, V>;
+    /** Where each subject ends. */
+    to: PerSubject<I, V>;
+    /** How long a stretch takes, ms. Asked per subject each time one of its stretches starts. */
+    ms: PerSubject<I, number>;
+    /** The curve from `from` to `to`. Default `'ease'`, as CSS's. */
+    ease?: Easing;
+}
+/**
+ * The patch `spring` returns, a motion that can be retargeted.
+ *
+ * @category patch
+ */
+export interface Spring<I, O, V extends Value> extends Moving<I, O, V> {
+    /**
+     * Heads `subject` for `target` from voice time `at`, keeping its velocity. `at` is by default the
+     * mix's latest frame, or for a subject no frame of its voice has met yet, or still inside its
+     * stagger, its first read, after any change with a time due by then. A subject faded out of the
+     * voice comes back at the latest frame too, however long it is before it is next read.
+     */
+    to(subject: I, target: V, at?: number): void;
+}
+/**
+ * The patch `glide` returns, a motion that reports its bounds.
+ *
+ * @category patch
+ */
+export interface Glide<I, O, V extends Value> extends Moving<I, O, V> {
+    /** `subject`'s bounds, undefined for a glide without them. */
+    bounds(subject: I): readonly [min: V, max: V] | undefined;
+}
+/**
+ * The patch `tween` returns, a motion that can be retargeted, with no `push`.
+ *
+ * @category patch
+ */
+export interface Tween<I, O, V extends Value> extends Omit<Moving<I, O, V>, 'push'> {
+    /**
+     * Heads `subject` for `target` from voice time `at`, over a full `ms` from where it is. `at` is
+     * by default the mix's latest frame, or for a subject no frame of its voice has met yet, or still
+     * inside its stagger, its first read, after any change with a time due by then. A subject faded
+     * out of the voice comes back at the latest frame too, however long it is before it is next read.
+     */
+    to(subject: I, target: V, at?: number): void;
+}

package/dist/types/motion.js

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

package/dist/types/patch.d.ts

@@ -1,7 +1,7 @@
 import type { WaveOptions } from '../wave.js';
 import type { Kit } from './channel.js';
 /**
- * A curve on 0..1, as data where it can be: CSS's names, a `cubic-bezier`, or `steps`, which a
+ * A curve on 0..1, as data where it can be. CSS's names, a `cubic-bezier`, or `steps`, which a
  * WAAPI or GPU engine can read. The function form runs on the CPU engine only.
  *
  * @category patch
@@ -25,37 +25,38 @@ export interface Keyframe<O> {
 }
 /**
  * What a patch may read and did not compute, for one subject this frame. The mix reuses the object,
- * so it is valid only during the call it is handed to.
+ * so it is valid only during the call it is handed to, and read-only: a write would reach whatever
+ * the mix calls next.
  *
  * @category state
  */
 export interface Setting<S = void, H = unknown> {
     /**
-     * The mix clock at this frame: the host's timestamp less any time `rebase` took out, run at the
+     * The mix clock at this frame. The host's timestamp less any time `rebase` took out, run at the
      * mix's `rate`. Identical for every probe in the frame.
      */
-    timestamp: number;
+    readonly timestamp: number;
     /**
-     * The gap this subject is catching up by: milliseconds since it last advanced, which is the gap
+     * The gap this subject is catching up by, in milliseconds since it last advanced. That is the gap
      * since the previous sync only for a subject sampled every frame. Infinity under reduced motion;
-     * no more than `maxDt` where the mix sets one. Inside a `step` under `stepMs`, it is `stepMs`, and
-     * `timestamp` is the end of that interval. A lane samples a subject for one frame after its last
-     * probe. A read by `project` is one sample, so its gap is not the gap a frame of play has.
+     * no more than `maxDt` where the mix sets one. Inside a `step` under `stepMs`, it is `stepMs`,
+     * and `timestamp` is the end of that interval. A lane samples a subject for one frame after its
+     * last probe. A read by `project` is one sample, so its gap is not the gap a frame of play has.
      */
-    dt: number;
+    readonly dt: number;
     /**
      * Milliseconds this voice has been playing, rate applied. Below 0 only for a voice with no end
      * cued backward, which plays into the passes before its first.
      */
-    elapsed: number;
+    readonly elapsed: number;
     /** Which pass this is, 0 first; below 0 where `elapsed` is. */
-    pass: number;
-    /** This voice's weight for this subject this frame, after fades, signals and any locus. */
-    weight: number;
+    readonly pass: number;
+    /** This voice's weight for this subject this frame, after fades, signals and any role. */
+    readonly weight: number;
     /** This subject's state, when the patch declares one. */
-    state: S;
-    /** Anything the host adds for its own patches: the mix's `host`, typed as its `H`. */
-    host: H;
+    readonly state: S;
+    /** Anything the host adds for its own patches. The mix's `host`, typed as its `H`. */
+    readonly host: H;
     /**
      * The state `owner` keeps for this voice and this subject, made by `init` on first ask. The mix
      * holds it, so a read at another time can copy it instead of moving it. A stateful signal keeps
@@ -91,33 +92,51 @@ export interface Sent<I, E = unknown> {
     event: E;
 }
 /**
- * What a `'motion'` patch is made of, as data an engine can read: the kind of motion and its
+ * What a `'motion'` patch is made of, as data an engine can read. The kind of motion and its
  * constants. Each subject's start, target and starting velocity stay on the patch, since they may
  * be functions of the subject.
  *
  * @category patch
  */
-export type MotionSpec = {
+export type MotionSpec = SpringSpec | GlideSpec | TweenSpec;
+/**
+ * A spring's constants, as `MotionSpec` gives them.
+ *
+ * @category patch
+ */
+export interface SpringSpec {
     readonly kind: 'spring';
-    /** Per second squared. */
+    /** How hard the spring pulls toward its target, per second squared. */
     readonly stiffness: number;
-    /** Per second. */
+    /** How fast the spring's motion dies away, per second. */
     readonly damping: number;
     readonly mass: number;
     readonly settle: number;
-} | {
+}
+/**
+ * A glide's constants, as `MotionSpec` gives them.
+ *
+ * @category patch
+ */
+export interface GlideSpec {
     readonly kind: 'glide';
     /** The friction's time constant, ms. */
     readonly ms: number;
     readonly settle: number;
     /** The spring back's, per second squared; only on a glide with bounds. */
     readonly stiffness?: number;
-} | {
+}
+/**
+ * A tween's constants, as `MotionSpec` gives them.
+ *
+ * @category patch
+ */
+export interface TweenSpec {
     readonly kind: 'tween';
-    /** How long a stretch takes; undefined where it varies by subject, kept on the patch then. */
+    /** How long a stretch takes. Undefined where it varies by subject, kept on the patch then. */
     readonly ms: number | undefined;
     readonly ease: Easing;
-};
+}
 /**
  * A pure function of phase and a subject that returns a delta. Optionally stateful.
  *
@@ -125,7 +144,7 @@ export type MotionSpec = {
  */
 export interface Patch<I, O, S = void, H = unknown> {
     /**
-     * Which authoring form built it: `'fn'` from `patch`, `'keys'` from `keys`, `'motion'` from
+     * Which authoring form built it. `'fn'` from `patch`, `'keys'` from `keys`, `'motion'` from
      * `spring`, `glide` or `tween`. An engine declares which forms it runs.
      */
     readonly form: 'fn' | 'keys' | 'motion';
@@ -146,20 +165,20 @@ export interface Patch<I, O, S = void, H = unknown> {
     readonly reads?: readonly string[];
     /**
      * `phase` is 0..1 across one pass, wrapping. Not asked for a subject its voice gives no weight, unless the voice is fading to rest;
-     * `step` still runs. A `keys` patch's stops are not read there either, unless its voice is in a locus.
+     * `step` still runs. A `keys` patch's stops are not read there either, unless its voice is in a role.
      */
     at(phase: number, subject: I, setting: Setting<S, H>): Partial<O>;
     /** Per-subject state, created on the first frame this patch sees a subject. */
     state?(subject: I): S;
     /**
-     * Advances state once per subject per sampled frame, by the whole gap since it last advanced; or,
-     * where the mix sets `stepMs`, once per whole interval of that length.
+     * Advances state once per subject per sampled frame. It advances by the whole gap since it last
+     * advanced; or, where the mix sets `stepMs`, once per whole interval of that length.
      */
     step?(state: S, dt: number, subject: I, setting: Setting<S, H>): void;
     /** Present when the patch was authored as keyframes, so an engine that reads data can. */
     readonly keys?: readonly Keyframe<O>[];
     /**
-     * Present on a `keys` patch that was given them: what `keys` took besides its stops, each as
+     * What `keys` took besides its stops, on a `keys` patch that was given them. Each is as
      * `KeysOptions` describes it. They are read off the patch, so a copy that changes one, as
      * `{ ...p, ease: 'linear' }` does, plays by its own.
      */
@@ -167,9 +186,12 @@ export interface Patch<I, O, S = void, H = unknown> {
     easeBy?(channel: keyof O): Easing | undefined;
     delayBy?(channel: keyof O): number;
     lerpBy?(channel: keyof O): ((a: never, b: never, u: number) => unknown) | undefined;
-    /** Present on a `wave` patch: what `wave` took, which a copy may change as it may a `keys` field. */
+    /** What `wave` took, present on a `wave` patch. A copy may change it as it may a `keys` field. */
     readonly wave?: WaveOptions<O>;
-    /** Present on a `'motion'` patch: its kind and constants, for an engine that reads data. */
+    /**
+     * A `'motion'` patch's kind and constants, for an engine that reads data. Absent on any other
+     * patch.
+     */
     readonly motion?: MotionSpec;
     /**
      * A copy of `state` that shares nothing with it, for a read at another time. Default
@@ -178,7 +200,7 @@ export interface Patch<I, O, S = void, H = unknown> {
      */
     clone?(state: S): S;
     /**
-     * `state` as data that survives `structuredClone`, for a history `store` to keep; `unpack` makes
+     * `state` as data that survives `structuredClone`, for a history `store` to keep. `unpack` makes
      * a state from it again. With a store, a patch with `state` or `step` needs both, or `cue`
      * refuses it.
      */
@@ -192,6 +214,17 @@ export interface Patch<I, O, S = void, H = unknown> {
  *
  * @category signal
  */
-export type Signal<I, H = unknown> = ((subject: I, setting: Setting<void, H>) => number) & {
+export interface Signal<I, H = unknown> {
+    (subject: I, setting: Setting<void, H>): number;
     readonly input?: boolean;
-};
+}
+/**
+ * Two thresholds that switch something on and off. On at `on` and off at `off`, holding it as it
+ * was between.
+ *
+ * @category signal
+ */
+export interface Band {
+    on: number;
+    off: number;
+}

package/dist/types/place.d.ts

@@ -1,24 +1,25 @@
 /**
- * The times a voice is known by on the mix clock: when its fade in begins (`start`), when it is
- * fully in (`in`), when its last pass ends (`coast`), when its fade out begins (`out`), and when it
- * is gone (`end`). A voice coasts when `played` resolves true, for its latest-staggered subject: at
- * its `out` where it does not freeze, and where it starts showing its last frame where it does. A
- * voice that loops for good, or fades before its last pass ends, never coasts.
+ * One of the five times a voice is known by on the mix clock. They are when its fade in begins
+ * (`start`), when it is fully in (`in`), when its last pass ends (`coast`), when its fade out
+ * begins (`out`), and when it is gone (`end`). A voice coasts when `played` resolves true, for its
+ * latest-staggered subject: at its `out` where it does not freeze, and where it starts showing its
+ * last frame where it does. A voice that loops for good, or fades before its last pass ends, never
+ * coasts.
  *
  * @category score
  */
 export type Mark = 'start' | 'in' | 'coast' | 'out' | 'end';
 /**
- * A mark by name: one of a voice's own five, or one it places inside itself with `marks`.
+ * A mark by name. It is one of a voice's own five, or one it places inside itself with `marks`.
  *
  * @category score
  */
 export type MarkName = Mark | (string & {});
 /**
- * Selects voices by what the plan knows of them, never by a channel's value, within the asking
- * voice's own score unless it names another. Where several match,
- * the resolver picks one: `last` cued (the default), `first` cued, `next` (the earliest whose mark
- * is still to come), `earliest` or `latest` by the mark's time.
+ * Selects voices by what the plan knows of them, never by a channel's value. It looks within the
+ * asking voice's own score unless it names another. Where several match, the resolver picks one:
+ * `last` cued (the default), `first` cued, `next` (the earliest whose mark is still to come),
+ * `earliest` or `latest` by the mark's time.
  *
  * @category score
  */
@@ -32,8 +33,8 @@ export interface Query {
     resolver?: 'last' | 'first' | 'next' | 'earliest' | 'latest';
 }
 /**
- * A time given by another voice: `mark` of the voice `of` selects, moved by `by` ms, where `mark`
- * is one of its five or one it places inside itself with `marks`. `after` is
+ * A time given by another voice. It is `mark` of the voice `of` selects, moved by `by` ms, where
+ * `mark` is one of its five or one it places inside itself with `marks`. `after` is
  * sugar for that voice's `end`, `with` for its `start`, and `before` for its start less `by`. A
  * string selects by name. `all` is the latest of its anchors, known once every one is; `any` the
  * earliest, known once one has passed or every one is known.
@@ -59,12 +60,12 @@ export type Anchor = {
     any: readonly Anchor[];
 };
 /**
- * Where a voice sits on the mix clock: at most one of `start` and `in`, and at most one of `out`
- * and `end`, each a timestamp on the host's clock or an anchor to another voice. A voice whose
- * anchor has no answer yet waits pending; one whose anchored mark is already past starts partway
- * through, as playback does from the middle of a region. A fade out begins no earlier than the
- * voice starts: an `end` that leaves less room than `fade.out` shortens the fade to fit, and one
- * before the start makes the voice an instant, which starts and ends at its start and shows
+ * Where a voice sits on the mix clock. It sets at most one of `start` and `in`, and at most one of
+ * `out` and `end`, each a timestamp on the host's clock or an anchor to another voice. A voice
+ * whose anchor has no answer yet waits pending; one whose anchored mark is already past starts
+ * partway through, as playback does from the middle of a region. A fade out begins no earlier than
+ * the voice starts: an `end` that leaves less room than `fade.out` shortens the fade to fit, and
+ * one before the start makes the voice an instant, which starts and ends at its start and shows
  * nothing.
  *
  * @category score
@@ -76,32 +77,38 @@ export interface Placement {
     end?: number | Anchor;
 }
 /**
- * One mark as `marks` lists it: one of a voice's, or one the host announced on a score, which has a
- * name and no voice.
+ * One mark as `marks` lists it. It is one of a voice's, or one the host announced on a score,
+ * which has a name and no voice.
  *
  * @category score
  */
 export interface Marked {
     /** On the host's clock. */
     timestamp: number;
-    /** Which of a voice's this is, one of its five or one it placed inside itself; undefined for an announced mark. */
+    /**
+     * Which of a voice's marks this is. It is one of its five or one it placed inside itself;
+     * undefined for an announced mark.
+     */
     mark: MarkName | undefined;
     /** The voice it belongs to; undefined for an announced mark. */
     voice: number | undefined;
     score: string | undefined;
     name: string | undefined;
     tags: readonly string[];
-    /** The `name` of the mix the voice is in, or that announced the mark; undefined for none. */
+    /** The `name` of the mix the voice is in, or that announced the mark. Undefined for none. */
     mix: string | undefined;
 }
 /**
- * An event at a time on a voice's own clock, which `book` hands a host ahead of time. It plays once
+ * An event at a time on a voice's own clock. `book` hands it to a host ahead of time. It plays once
  * per pass, for the voice and not per subject, so `stagger` does not spread it.
  *
  * @category score
  */
 export interface Hit<E = unknown> {
-    /** Voice ms into each pass: 0 up to the patch's `duration`, or any time from 0 for a patch with none. */
+    /**
+     * Voice ms into each pass. It runs from 0 up to the patch's `duration`, or any time from 0 for a
+     * patch with none.
+     */
     at: number;
     event: E;
 }
@@ -126,38 +133,46 @@ export interface BookedHit<E = unknown, I = unknown> {
     subjects: readonly I[] | undefined;
 }
 /**
- * What `book` takes: an outside clock, how far ahead to book on it, and what to do with each item.
+ * What `book` takes. It names an outside clock, how far ahead to book on it, and what to do with
+ * each item.
  *
  * @category score
  */
 export interface BookOptions<E = unknown, I = unknown> {
     /**
-     * The outside clock, in ms: `audio.currentTime * 1000`, `performance.now()`, or whatever the host
-     * schedules against. Read once a sync. The mix maps its host time onto it by an offset that folds
-     * in 5% of each frame's difference, and starts over from the clock's own reading on a jump past
-     * 50 ms, such as a suspended context or a hidden tab.
+     * The outside clock, in ms. It is `audio.currentTime * 1000`, `performance.now()`, or whatever
+     * the host schedules against. Read once a sync. The mix maps its host time onto it by an offset
+     * that folds in 5% of each frame's difference, and starts over from the clock's own reading on a
+     * jump past 50 ms, such as a suspended context or a hidden tab.
      */
     clock: () => number;
     /** How far ahead to book, host ms. It has to cover the longest gap between two syncs. */
     ahead: number;
-    /** How far past an item first seen late may be and still be taken, host ms. */
+    /** How late an item may be when first seen and still be taken, host ms. */
     late: number;
     /**
-     * Called once per item: a mark as `marks` lists it, or a hit. `when` is on the outside clock;
+     * Called once per item, a mark as `marks` lists it or a hit. `when` is on the outside clock;
      * `lateBy` is how many host ms past the item was when first seen, which is then taken at the
      * clock's now; it is 0 for one booked ahead. Return a `cancel` to hear about a booking whose time moved by
      * more than 1 ms or that went away (a seek, a rate or ramp on the voice or the mix, a fade, a
      * `rebase`, an anchor's target moving, the voice leaving); the item is then booked again, at its
      * new time, at the same sync.
      */
-    take(item: Marked | BookedHit<E, I>, when: number, lateBy: number): {
-        cancel(): void;
-    } | undefined;
+    take(item: Marked | BookedHit<E, I>, when: number, lateBy: number): Taken | undefined;
     /** Book only the voices, and announced marks, carrying this tag. */
     tag?: string;
     /** Book only this score's voices and marks. */
     score?: string;
 }
+/**
+ * What `BookOptions.take` may return for a booking it took.
+ *
+ * @category score
+ */
+export interface Taken {
+    /** Called when the booking's time moved by more than 1 ms, or it went away. */
+    cancel(): void;
+}
 /**
  * A running booker, returned by `book`.
  *
@@ -167,8 +182,8 @@ export interface Booker {
     /** Cancels every booking still ahead, and books nothing more. */
     cancel(): void;
     /**
-     * Where host `timestamp` falls on the outside clock, by the offset as the last sync left it;
-     * NaN before the first sync.
+     * Where host `timestamp` falls on the outside clock. It goes by the offset as the last sync left
+     * it; NaN before the first sync.
      */
     at(timestamp: number): number;
 }

package/dist/types/transport.d.ts

@@ -1,8 +1,8 @@
 import type { Tape } from './history.js';
-import type { Mix, MixOptions, Projection } from './mix.js';
+import type { AnnounceOptions, Mix, MixOptions, Projection } from './mix.js';
 import type { Marked } from './place.js';
 /**
- * How a transport is made: what history it keeps for every mix on it.
+ * How a transport is made. It says what history the transport keeps for every mix on it.
  *
  * @category mix
  */
@@ -10,8 +10,8 @@ export interface TransportOptions {
     history?: MixOptions['history'];
 }
 /**
- * Every mix on a transport read at another mix time, with nothing live moved: `of` gives one mix's
- * reading. Valid until the transport is next synced or a mix on it cued.
+ * Every mix on a transport read at another mix time, with nothing live moved. `of` gives one
+ * mix's reading. Valid until the transport is next synced or a mix on it cued.
  *
  * @category mix
  */
@@ -20,8 +20,8 @@ export interface TransportProjection {
     of<I, O, H>(mix: Mix<I, O, H>): Projection<I, O>;
 }
 /**
- * One clock several mixes play on, each over its own kit: one sync, one rate, one seek and one
- * tape for all of them, and a score that spans them, so an anchor in one mix waits on a voice in
+ * One clock several mixes play on, each over its own kit. It gives them one sync, one rate, one
+ * seek and one tape, and a score that spans them, so an anchor in one mix waits on a voice in
  * another by naming the score they share. A query naming no score stays in its own mix.
  *
  * @category mix
@@ -35,7 +35,7 @@ export interface Transport {
     rate: number;
     ramp(rate: number, over: number): void;
     /**
-     * As `Mix.seek`, for every mix on it at once: back, each mix restores itself; forward, the one
+     * As `Mix.seek`, for every mix on it at once. Back, each mix restores itself; forward, the one
      * tape plays every mix's calls again in the order they were made, so an anchor across mixes
      * answers as it did. A mix dropped after the moment sought is back on the transport.
      */
@@ -43,25 +43,24 @@ export interface Transport {
         readonly frame: number;
     }): void;
     /**
-     * Loads from the history `store` what `seek(time)` and `project(time)` will need, where that
-     * reaches past memory. Without a store, or within memory, it loads nothing.
+     * Loads from the history `store` what a seek or projection to `time` will need. That is, what
+     * `seek(time)` and `project(time)` need where it reaches past memory. Without a store, or within
+     * memory, it loads nothing.
      */
     prepare(time: number): Promise<void>;
     readonly now: number;
-    /** As `Mix.seq`: the number of the frame being played, the same for every mix on it. */
+    /** As `Mix.seq`, the number of the frame being played. It is the same for every mix on it. */
     readonly seq: number;
     readonly tape: Tape | undefined;
     /** Puts a named mark on a score every mix on it sees. Throws without a `score`. */
-    announce(name: string, opts: {
-        at?: number;
+    announce(name: string, opts: AnnounceOptions & {
         score: string;
-        tags?: readonly string[];
     }): void;
     /** Every mark of every mix on it, and every mark announced on it, earliest first. */
     marks(from: number, to: number): Marked[];
     /**
-     * Every mix on it read at mix time `at`, or at the frame `{ frame }` names, together, so anchors
-     * across them answer.
+     * Every mix on it read together at another time. The time is mix time `at`, or the frame
+     * `{ frame }` names, and reading them together lets anchors across them answer.
      */
     project(at: number | {
         readonly frame: number;
@@ -70,11 +69,14 @@ export interface Transport {
     readonly live: boolean;
     /** Every mix on it inert. */
     readonly inert: boolean;
-    /** Calls `fn` when any mix on it needs frames again after a sync, once until the next sync. */
+    /**
+     * Calls `fn` when any mix on it needs frames again after a sync. It fires once until the next
+     * sync.
+     */
     onWake(fn: () => void): () => void;
     /**
-     * Takes a mix off: it is no longer synced and takes no more calls. With history, a seek back
-     * before the drop puts it back as it was then; without, it is let go.
+     * Takes a mix off the transport. It is no longer synced and takes no more calls. With history, a
+     * seek back before the drop puts it back as it was then; without, it is let go.
      */
     drop<I, O, H>(mix: Mix<I, O, H>): void;
 }