@msb235/blits 0.14.0 → 0.15.1

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

package/dist/types/voice.d.ts

@@ -1,7 +1,7 @@
 import type { Fit, Order, Strength } from '../fit.js';
-import type { Motion, Value } from '../motion.js';
 import type { Described } from './history.js';
 import type { Doubt } from './mix.js';
+import type { Motion, Value } from './motion.js';
 import type { Easing, Patch, Signal } from './patch.js';
 import type { Anchor, Hit, Placement } from './place.js';
 /**
@@ -15,42 +15,68 @@ export interface FadeSpec {
     ease?: Easing;
 }
 /**
- * How a voice or owner held by a span may give way so the span keeps its budget, which the span's
- * fit reads. Anything it does not allow, it will not do. Read only under a span.
+ * How a span's child may give way so the span keeps its budget. A child is a voice or owner
+ * held by a span, and the span's fit reads this. Anything it does not allow, it will not do. Read only under a span.
  *
  * @category score
  */
 export interface SpanHints {
-    /** How many times faster than its own rate it may play. Default 1: no faster. */
+    /** How many times faster than its own rate it may play. Default 1, no faster. */
     faster?: number;
-    /** How many times slower than its own rate it may play. Default 1: no slower. */
+    /** How many times slower than its own rate it may play. Default 1, no slower. */
     slower?: number;
-    /** Whether it may start before the one before it ends, where the span's order would not. */
+    /** Whether it may start before the one before it ends, even where the span's order would not. */
     overlap?: boolean;
     /** Whether it may jump to its end instead of playing. A span held by a span is never skipped. */
     ballast?: boolean;
     /** How hard its own length holds against the span's budget. Default `weak`. */
     priority?: Strength;
     /**
-     * The soonest it may start: a time on the span's clock, or an anchor. The fit never places it
+     * The soonest it may start, as a time on the span's clock or an anchor. The fit never places it
      * sooner, and the children after it are laid out from where it starts. One already past when it is
      * cued places it there, partway through. One whose anchor has no answer yet waits, and under `queue` or
      * `stagger` so does every child after it.
      */
     earliest?: number | Anchor;
-    /** Where it plays among the span's children still to start: lower first, ties as cued. Default 0. */
+    /**
+     * Where it plays among the span's children still to start. Lower goes first, and ties go as cued.
+     * Default 0.
+     */
     rank?: number;
 }
 /**
- * What `cue` takes: a patch, and the clock, weight and reach it plays with.
+ * A circle by its center, `x` and `y`, and radius `r`. It is in the units of the positions `plot`
+ * gave.
+ *
+ * @category voice
+ */
+export interface Circle {
+    x: number;
+    y: number;
+    r: number;
+}
+/**
+ * The host's own answer to where a `within` signal can be above 0. It works over any axes or
+ * none. Once a
+ * frame, `find` writes into `out`, from 0, the indices `place` or `plot` gave the subjects the
+ * signal can be above 0 for, and returns how many it wrote. `out` has room for every index handed
+ * out; a repeat is read once, and an index no subject holds is skipped.
+ *
+ * @category voice
+ */
+export interface Finder {
+    find(out: Int32Array): number;
+}
+/**
+ * What `cue` takes. That is a patch, and the clock, weight and reach it plays with.
  *
  * @category voice
  */
 export interface VoiceSpec<I, O, H = unknown> extends SpanHints {
     patch: Patch<I, O, any, H>;
     /**
-     * What `history.revive` rebuilds this spec from, so a history `store` can page the voice out once
-     * it has left. A voice cued without it stays in memory for as long as history reaches it.
+     * What `history.revive` rebuilds this spec from. It lets a history `store` page the voice out
+     * once it has left. A voice cued without it stays in memory for as long as history reaches it.
      */
     as?: Described;
     /**
@@ -63,14 +89,14 @@ export interface VoiceSpec<I, O, H = unknown> extends SpanHints {
      */
     target?: (subject: I) => boolean;
     /**
-     * The subjects this voice reaches, fixed at `cue` and matched by identity; a probe of any other
-     * never asks this voice. Takes the place of `target`, and a cue giving both is refused: a
+     * The subjects this voice reaches, fixed at `cue` and matched by identity. A probe of any other
+     * never asks this voice. Takes the place of `target`, and a cue giving both is refused, since a
      * predicate over a fixed list is that list filtered, which the host can do before cueing.
      */
     subjects?: readonly I[];
     /**
-     * When the voice starts, in ms on the host's clock, the one it passes `sync`: a rAF timestamp and
-     * `performance.now()` share an origin, `Date.now()` does not. Default: the time the mix last
+     * When the voice starts, in ms on the host's clock. That is the clock it passes `sync`: a rAF
+     * timestamp and `performance.now()` share an origin, `Date.now()` does not. Default: the time the mix last
      * synced to, and 0 for a voice cued before the first sync, which that sync finds already as far
      * in as its timestamp. Where the host read `inert` as true since the last sync, its frame loop
      * may be asleep, and the default is the next sync instead, so a voice cued after a long pause
@@ -93,8 +119,8 @@ export interface VoiceSpec<I, O, H = unknown> extends SpanHints {
      */
     seek?: number;
     /**
-     * The interval this voice's `step` runs at, in ms of mix time, in place of the mix's `stepMs`.
-     * 0 steps it once a frame by the frame's gap, whatever the mix sets. Default: the mix's.
+     * The interval this voice's `step` runs at, in ms of mix time. It takes the place of the mix's
+     * `stepMs`. 0 steps it once a frame by the frame's gap, whatever the mix sets. Default: the mix's.
      */
     stepMs?: number;
     /**
@@ -107,20 +133,25 @@ export interface VoiceSpec<I, O, H = unknown> extends SpanHints {
      */
     catchUp?: 'exact' | 'fresh';
     /**
-     * true loops for good, false plays one pass, n plays n passes. A finite loop leaves when its
-     * passes are done for the latest-staggered subject it has seen — over `fade.out` where one is
-     * set, at once where none is — unless it freezes after. Default: false.
+     * How many passes the voice plays. true loops for good, false plays one pass, n plays n passes.
+     * A finite loop leaves when its
+     * passes are done for its latest-staggered subject — over `fade.out` where one is set, at once
+     * where none is — unless it freezes after. Default: false.
      */
     loop?: boolean | number;
     /**
-     * Per-subject delay in voice ms, klieg's stagger grammar reduced to the one thing the mix needs.
-     * Like `target`, it runs once per subject on first sight, and the answer is kept.
+     * Per-subject delay in voice ms. It is klieg's stagger grammar reduced to the one thing the mix
+     * needs. It runs once per subject and the answer is kept: at `cue` for every subject a voice
+     * names in `subjects`, else, like `target`, on first sight. So a voice naming its subjects ends by
+     * all of them, and one reaching them by `target` ends by those the mix has been asked about: a
+     * subject first read later than that sees a finite loop already over.
      */
     stagger?: (subject: I) => number;
     /**
-     * Show a subject the first frame before it starts — while the voice is pending and while the
-     * subject waits out its `stagger` — the last frame of the last pass after a finite loop plays
-     * out, or both. A frozen subject's clock stands still: `at` is asked for the edge frame and `step`
+     * Which edge frames a subject is shown while the voice is not playing. `before` shows the first
+     * frame before it starts, while the voice is pending and while the subject waits out its
+     * `stagger`; `after` shows the last frame of the last pass after a finite loop plays out; `both`
+     * shows both. A frozen subject's clock stands still: `at` is asked for the edge frame and `step`
      * does not run, past one last step to the end of the last pass. `fade.in` counts from the first
      * frame the voice shows. A voice freezing after stays, `frozen`, until `fade()` or an anchored
      * `out` takes it out, so every one cued must be faded or it stays in the mix for good. Does
@@ -129,13 +160,32 @@ export interface VoiceSpec<I, O, H = unknown> extends SpanHints {
     freeze?: 'before' | 'after' | 'both';
     /** Steady weight, or a signal read per subject per frame. Default 1. */
     weight?: number | Signal<I, H>;
+    /**
+     * Where the `weight` signal can be above 0. It is a circle the host moves by writing to it, read
+     * once a frame, over the positions `plot` or `put` gave, or a `Finder` the host answers by index.
+     * Outside
+     * it the voice gives a subject nothing and the signal is not read, so a frame visits only the
+     * subjects within rather than all of them. The signal has to be 0 outside already, or the bound
+     * cuts it off: outside production, every few frames, the mix reads it for a few subjects just
+     * outside and warns once if one is above 0.
+     * A patch that steps still steps outside, and a `from: 'current'` voice still takes its base,
+     * as each does at weight 0. Needs `place` or `plot` first, and a signal `weight`.
+     */
+    within?: Circle | Finder;
     /** Ramp in and out, ms. Out applies on `fade()` and when a finite loop ends. */
     fade?: FadeSpec;
-    /** Voices sharing a locus are alternatives: the mix folds them through each channel's `lerp`. */
+    /**
+     * The role this voice plays; voices in one role are alternatives. Whichever plays it, the subject
+     * shows one performance, not two stacked. The mix folds them through each channel's `lerp`.
+     */
+    role?: string;
+    /** @deprecated Renamed `role`. Taken as `role`, with a warning outside production. */
     locus?: string;
     /** A `keys` voice whose first stop reads wherever this subject is now. */
     from?: 'current';
-    /** Words a source attaches to this voice, so its events and its handle can be taken as a set. */
+    /**
+     * Words a source attaches to this voice. They let its events and its handle be taken as a set.
+     */
     tags?: readonly string[];
     /** What other voices call this one by. A label blits never reads. */
     name?: string;
@@ -153,15 +203,15 @@ export interface VoiceSpec<I, O, H = unknown> extends SpanHints {
      */
     hits?: readonly Hit[];
     /**
-     * Named marks inside the voice, beside its five, each at voice ms into a pass as a hit's `at` is:
-     * `{ drop: 340 }`. An anchor names one as it names the five, `{ of: 'lead', mark: 'drop' }`, and
+     * Named marks inside the voice, beside its five. Each is at voice ms into a pass, as a hit's `at`
+     * is: `{ drop: 340 }`. An anchor names one as it names the five, `{ of: 'lead', mark: 'drop' }`, and
      * `marks` lists it and `book` books it under its name. Each is reached once: on the first pass
      * that reaches it from where the voice starts, while its clock runs forward and before it ends.
      * A name cannot be one of the five.
      */
     marks?: Readonly<Record<string, number>>;
     /**
-     * The owner this voice plays under, a handle `owns` returned. Its `start` and `anchor` are then on
+     * The owner this voice plays under, as a handle `owns` returned. Its `start` and `anchor` are then on
      * the owner's clock, in ms from when the owner starts, and default to where that clock is now; a
      * bare name in an anchor means a sibling, another voice the owner holds. Its clock runs on the
      * owner's, so the owner's rate, ramp and seeks move it, and its weight is multiplied by the
@@ -170,7 +220,7 @@ export interface VoiceSpec<I, O, H = unknown> extends SpanHints {
     owner?: Handle<I>;
 }
 /**
- * One of `mix.blend`'s members, with the labels it carries in place of the spec's: each set here
+ * One of `mix.blend`'s members, with the labels it carries in place of the spec's. Each set here
  * replaces the spec's for this member alone. The rest of the spec times and places every member
  * alike, so they stay one blend.
  *
@@ -180,20 +230,20 @@ export interface BlendMember<I, O, H = unknown> {
     patch: Patch<I, O, any, H>;
     /** What other voices call this member by. Default: the spec's `name`. */
     name?: string;
-    /** Default: the spec's `tags`. */
+    /** The member's tags. Default: the spec's `tags`. */
     tags?: readonly string[];
     /** Events at times on this member's clock, as a voice's `hits`. Default: the spec's. */
     hits?: readonly Hit[];
 }
 /**
- * What `owns` takes: an owner has no patch, and plays only through the voices it holds.
+ * What `owns` takes. An owner has no patch, and plays only through the voices it holds.
  *
  * @category voice
  */
 export interface OwnerSpec<I, H = unknown> extends SpanHints {
     /**
-     * When the owner starts, on its own owner's clock: the host's for an owner on the mix, as a
-     * voice's `start` is. Default: now.
+     * When the owner starts, on its own owner's clock. That is the host's clock for an owner on the
+     * mix, as a voice's `start` is. Default: now.
      */
     start?: number;
     /**
@@ -204,14 +254,14 @@ export interface OwnerSpec<I, H = unknown> extends SpanHints {
      */
     rate?: number;
     /**
-     * Where its clock starts, ms, as `seek` on its handle sets: its children play as far in as that
+     * Where its clock starts, ms, as `seek` on its handle sets. Its children play as far in as that
      * puts them. Default 0, cued backward too, since an owner has no end of its own to start from; one
      * cued at a rate below 0 with no seek runs back from 0, before any child placed on its clock.
      */
     seek?: number;
     /**
-     * Multiplied into every child's weight per subject, as the child's own fade is, before the child's
-     * locus folds it: a number, or a signal read per subject per frame. Default 1.
+     * Multiplied into every child's weight per subject. It applies as the child's own fade does,
+     * before the child's role folds it: a number, or a signal read per subject per frame. Default 1.
      */
     weight?: number | Signal<I, H>;
     /** One ramp in and out over every child, multiplied into their weights as `weight` is. */
@@ -224,11 +274,14 @@ export interface OwnerSpec<I, H = unknown> extends SpanHints {
     name?: string;
     /** The plan it belongs to, as a voice's. */
     score?: string;
-    /** Where it sits relative to its own owner's clock or to other voices, in place of `start`. */
+    /**
+     * Where it sits relative to its own owner's clock or to other voices. It takes the place of
+     * `start`.
+     */
     anchor?: Placement;
     /**
-     * Events at times on its own clock, the one its children's `start` counts on, which `book`
-     * hands a host ahead of time with its `score` and `tags`. An owner does not loop, so each is
+     * Events at times on its own clock, which `book` hands a host ahead of time. That is the clock its
+     * children's `start` counts on, and they go with its `score` and `tags`. An owner does not loop, so each is
      * booked once, while it plays: none past where it leaves, and none while its clock runs back.
      */
     hits?: readonly Hit[];
@@ -238,8 +291,8 @@ export interface OwnerSpec<I, H = unknown> extends SpanHints {
     owner?: Handle<I>;
 }
 /**
- * What `span` takes: an owner with a budget, which lays out the voices it holds in an order and
- * fits them into the budget.
+ * What `span` takes, an owner with a budget. It lays out the voices it holds in an order and fits
+ * them into the budget.
  *
  * @category score
  */
@@ -253,13 +306,13 @@ export interface SpanSpec<I, H = unknown> extends OwnerSpec<I, H> {
     /** How far through the one before a child starts under `stagger`, 0..1. Default 0.5. */
     share?: number;
     /**
-     * How the children are fitted once they are retimed toward the budget, faster or slower as
-     * their hints allow. Default `pipe(condense(), shed())`.
+     * How the children are fitted once they are retimed toward the budget. They are retimed faster
+     * or slower as their hints allow. Default `pipe(condense(), shed())`.
      */
     fit?: Fit;
     /**
-     * What happens where the fit leaves them too long for a span at least `strong`: `instant` jumps
-     * every child weaker than the span to its end at once, and `overrun` lets them run long.
+     * What happens where the fit leaves the children too long for a span at least `strong`.
+     * `instant` jumps every child weaker than the span to its end at once, and `overrun` lets them run long.
      * Default `instant`.
      */
     spill?: 'instant' | 'overrun';
@@ -282,7 +335,7 @@ export interface FitResult {
     fell: boolean;
 }
 /**
- * A span's handle: an owner's, and how its children were last fitted.
+ * A span's handle. It is an owner's, and reports how its children were last fitted.
  *
  * @category score
  */
@@ -290,15 +343,21 @@ export interface SpanHandle<I = unknown> extends Handle<I> {
     readonly result: FitResult;
 }
 /**
- * How a voice leaves when it is faded: the whole voice, or one subject.
+ * How a voice leaves when it is faded. It fades the whole voice, or one subject.
+ *
+ * @category blending
+ */
+export type FadeOptions<I = unknown> = VoiceFade | SubjectFade<I>;
+/**
+ * A fade of the whole voice, as `FadeOptions` takes it.
  *
  * @category blending
  */
-export type FadeOptions<I = unknown> = {
+export interface VoiceFade {
     /** The ramp, ms. Defaults to the voice's own `fade.out`. */
     over?: number;
     /**
-     * When the fade begins. A mix time: ahead, the voice plays untouched until then and begins
+     * When the fade begins, as a mix time or `'rest'`. A mix time: ahead, the voice plays untouched until then and begins
      * its fade exactly there, its `out` mark fixed from now, and `rise` before then takes it
      * back with nothing changed; at or behind now, the fade began then and is partway. `'rest'`:
      * leave per subject at the first frame that subject's contribution is at rest. Default now.
@@ -307,16 +366,23 @@ export type FadeOptions<I = unknown> = {
     /** Ms after which the voice leaves whether or not it rested. */
     deadline?: number;
     subject?: never;
-} | {
+}
+/**
+ * A fade of one subject out of a voice, as `FadeOptions` takes it.
+ *
+ * @category blending
+ */
+export interface SubjectFade<I = unknown> {
     /**
      * The one subject to fade out of this voice, which plays on for the rest. Once the ramp ends
      * the voice forgets the subject and reaches it no more, until a motion patch's `to` or `push`
-     * or the mix's `drop` brings it back, met afresh: `from`, `target` and `stagger` asked again.
+     * or the mix's `drop` brings it back, met afresh: `from` and `target` asked again, and
+     * `stagger` too unless the voice names its `subjects`.
      */
     subject: I;
     /** The ramp, ms. Defaults to the voice's own `fade.out`; 0 takes the subject out at once. */
     over?: number;
-};
+}
 /**
  * The live controls on one voice, returned by `cue`.
  *
@@ -324,11 +390,16 @@ export type FadeOptions<I = unknown> = {
  */
 export interface Handle<I = unknown> {
     readonly id: number;
-    /** `frozen`: a voice freezing after has played every pass and shows its last frame until faded. */
+    /**
+     * Where the voice is in its life. `frozen`: a voice freezing after has played every pass and shows
+     * its last frame until faded.
+     */
     readonly state: 'pending' | 'live' | 'frozen' | 'fading' | 'done';
-    /** The handle of the owner this voice plays under; undefined for one on the mix clock. */
+    /** The handle of the owner this voice plays under. Undefined for one on the mix clock. */
     readonly owner: Handle<I> | undefined;
-    /** Live. A write shows at the next probe. */
+    /**
+     * The voice's weight now, which can be written while it plays. A write shows at the next probe.
+     */
     weight: number;
     /**
      * Playback rate now. Setting it changes speed at once; `ramp` eases into a new one. On a voice
@@ -337,7 +408,7 @@ export interface Handle<I = unknown> {
      */
     rate: number;
     /**
-     * Moves the rate to `rate` linearly over `over` mix ms, so a pause or a slow-motion eases in
+     * Moves the rate to `rate` linearly over `over` mix ms. A pause or a slow-motion then eases in
      * rather than snapping. The voice clock integrates the ramp, so its position stays continuous and
      * its speed does too. A later `rate` write or `ramp` replaces it; `seek` keeps it.
      */
@@ -359,9 +430,8 @@ export interface Handle<I = unknown> {
      */
     fade(opts?: FadeOptions<I>): void;
     /**
-     * Turns a fade out around: the voice climbs back from where its fade had got to, up the same
-     * curve, over `over` ms for the whole curve (default its `fade.in`, else its `fade.out`), and
-     * plays on as if never faded. A fade waiting for rest is taken back at once; a voice not fading
+     * Turns a fade out around, so the voice plays on as if never faded. It climbs back from where its
+     * fade had got to, up the same curve, over `over` ms for the whole curve (default its `fade.in`, else its `fade.out`). A fade waiting for rest is taken back at once; a voice not fading
      * is left as it is. A voice whose own end began the fade starts it again at its next frame. A
      * voice faded before its start goes back to `pending` and starts on time.
      */
@@ -369,43 +439,44 @@ export interface Handle<I = unknown> {
         over?: number;
     }): void;
     /**
-     * The weight this voice gave `subject` the last frame that subject was probed: after its fades
-     * and its weight signal, before a locus folds it with its alternatives. 0 for a subject it does
+     * The weight this voice gave `subject` the last frame that subject was probed. That is after its
+     * fades and its weight signal, before a role folds it with its alternatives. 0 for a subject it does
      * not reach, has not started on and does not freeze before, has left at rest, or has never been
      * probed for; 0 once done, and 0 after `mix.seek` goes back until the subject is probed again.
      * Costs nothing until it is asked.
      */
     weightOf(subject: I): number;
     /**
-     * Heads `subject` for `target`, for a voice playing a `spring` or a `tween`: the patch's own `to`,
-     * reached without holding the patch. Throws for any other voice.
+     * Heads `subject` for `target`, for a voice playing a `spring` or a `tween`. It is the patch's own
+     * `to`, reached without holding the patch. Throws for any other voice.
      */
     to(subject: I, target: Value, at?: number): void;
     /**
-     * Sets `subject` moving at `velocity`, units per second, for a voice playing a `spring` or a
-     * `glide`: the patch's own `push`. Throws for any other voice.
+     * Sets `subject` moving at `velocity`, for a voice playing a `spring` or a `glide`. The velocity
+     * is in units per second, and this is the patch's own `push`. Throws for any other voice.
      */
     push(subject: I, velocity: Value, at?: number): void;
     /**
-     * Puts `subject` at `value`, keeping its velocity, for a voice playing any motion patch: the
+     * Puts `subject` at `value`, keeping its velocity, for a voice playing any motion patch. It is the
      * patch's own `set`. Throws for any other voice.
      */
     set(subject: I, value: Value, at?: number): void;
     /**
-     * Where `subject` is and how fast it moves, for a voice playing a motion patch: the patch's own
-     * `read`. Undefined for any other voice, and wherever the patch's `read` is.
+     * Where `subject` is and how fast it moves, for a voice playing a motion patch. It is the patch's
+     * own `read`. Undefined for any other voice, and wherever the patch's `read` is.
      */
     read(subject: I, at?: number): Motion<Value> | undefined;
     /** Resolves when the voice has been removed from the mix, however that happened. */
     readonly done: Promise<void>;
     /**
-     * Resolves true when a finite loop's last pass ends, for the latest-staggered subject it has
-     * seen, and false if the voice leaves before that. Never rejects.
+     * Resolves true when a finite loop's last pass ends, false if the voice leaves before that. The
+     * last pass is the one for its latest-staggered subject; `stagger` says which subjects count.
+     * Never rejects.
      */
     readonly played: Promise<boolean>;
 }
 /**
- * What `Handle.seek` does with each subject's state: `rebuild` (the default) makes it fresh and
+ * What `Handle.seek` does with each subject's state. `rebuild` (the default) makes it fresh and
  * steps it to the new position; `keep` leaves it as it was, except for a subject the seek sends back
  * before its start, which starts afresh there.
  *