@msb235/blits 0.13.0 → 0.15.0

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, unknown, H>;
+    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,16 +89,18 @@ 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.
+     * 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
+     * starts there rather than that far in.
      */
     start?: number;
     /**
@@ -91,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;
     /**
@@ -105,20 +133,22 @@ 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
+     * 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 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.
      */
     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. Like `target`, it runs once per subject on first sight, and the answer is kept.
      */
     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
@@ -127,13 +157,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;
@@ -151,15 +200,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
@@ -168,30 +217,30 @@ 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.
  *
  * @category blending
  */
 export interface BlendMember<I, O, H = unknown> {
-    patch: Patch<I, O, unknown, H>;
+    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;
     /**
@@ -202,14 +251,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. */
@@ -222,11 +271,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[];
@@ -236,8 +288,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
  */
@@ -251,13 +303,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';
@@ -280,7 +332,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
  */
@@ -288,15 +340,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.
@@ -305,7 +363,13 @@ 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`
@@ -314,7 +378,7 @@ export type FadeOptions<I = unknown> = {
     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`.
  *
@@ -322,11 +386,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
@@ -335,7 +404,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.
      */
@@ -357,9 +426,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.
      */
@@ -367,38 +435,43 @@ 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;
     /**
-     * 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.
+     * 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. 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 the latest-staggered subject it has seen. 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.
  *

package/dist/types/watch.d.ts

@@ -1,10 +1,10 @@
 import type { HistoryOptions } from './history.js';
 import type { Mix } from './mix.js';
 import type { Sent } from './patch.js';
-import type { Handle } from './voice.js';
+import type { Circle, Finder, Handle } from './voice.js';
 /**
- * Every mix made on the page, for a debugger: shared by every copy of blits loaded, so a mix one
- * copy made is listed by another. `watched()` returns it.
+ * Every mix made on the page, for a debugger. It is shared by every copy of blits loaded, so a
+ * mix one copy made is listed by another. `watched()` returns it.
  *
  * @category mix
  */
@@ -12,19 +12,27 @@ export interface Registry {
     /** The mixes still alive, in the order they were made. */
     entries(): Watched[];
     /** Hears each mix made, and each one collected, by its entry's `id`. Returns an unsubscribe. */
-    on(fn: (change: {
-        kind: 'add';
-        entry: Watched;
-    } | {
-        kind: 'gone';
-        id: number;
-    }) => void): () => void;
+    on(fn: (change: RegistryChange) => void): () => void;
     /**
-     * The history a mix made from now on keeps when its options name none and it is on no
-     * transport, so a debugger present before the page's mixes can scrub them. Undefined by default.
+     * The history new mixes keep when they name none. It applies to a mix made from now on whose
+     * options name no history and that is on no transport, so a debugger present before the page's
+     * mixes can scrub them. Undefined by default.
      */
     history: HistoryOptions | undefined;
 }
+/**
+ * What `Registry.on` hears. It is a mix made, with its entry, or a mix collected, by its entry's
+ * `id`.
+ *
+ * @category mix
+ */
+export type RegistryChange = {
+    kind: 'add';
+    entry: Watched;
+} | {
+    kind: 'gone';
+    id: number;
+};
 /**
  * One mix as a debugger sees it. Built by the copy of blits that made the mix, so a debugger
  * reads mixes from other releases through it alike.
@@ -39,21 +47,17 @@ export interface Watched<I = unknown, O = unknown> {
     readonly name: string | undefined;
     readonly mix: Mix<I, O>;
     /** What history it keeps, and whether the registry's `history` gave it; undefined for none. */
-    readonly history: {
-        readonly ms: number;
-        readonly tape: boolean;
-        readonly added: boolean;
-    } | undefined;
-    /** The earliest mix time `read` reaches back to: `mix.now` without history. */
+    readonly history: WatchedHistory | undefined;
+    /** The earliest mix time `read` reaches back to. It is `mix.now` without history. */
     readonly reach: number;
     /** The kit's channel names, in kit order. */
     readonly channels: readonly string[];
-    /** What a voice was cued with that its handle does not carry; undefined for a handle not on this mix. */
-    voice(handle: Handle<I>): {
-        readonly name: string | undefined;
-        readonly tags: readonly string[];
-    } | undefined;
-    /** What to call a subject: the mix's `labelOf`, else a guess from the subject itself. */
+    /**
+     * What a voice was cued with that its handle does not carry. Undefined for a handle not on this
+     * mix.
+     */
+    voice(handle: Handle<I>): WatchedVoice | undefined;
+    /** What to call a subject. It is the mix's `labelOf`, else a guess from the subject itself. */
     label(subject: I): string;
     /**
      * Calls `fn` with each frame the host read, once the next one begins. While anyone watches, the
@@ -61,16 +65,46 @@ export interface Watched<I = unknown, O = unknown> {
      * a function that stops watching.
      */
     watch(fn: (frame: WatchedFrame<I, O>) => void): () => void;
-    /** The subjects its voices still playing name, and those the host read in the last two frames while watched. */
+    /**
+     * The subjects its voices still playing name. It also lists those the host read in the last two
+     * frames while watched.
+     */
     subjects(): I[];
     /**
-     * One subject's pose at mix time `at`, default now, read through `project`, which moves nothing:
-     * never a probe. A time behind now needs history that reaches it.
+     * One subject's pose at mix time `at`, default now. It is read through `project`, which moves
+     * nothing, never a probe. A time behind now needs history that reaches it.
      */
     read(subject: I, at?: number): O;
-    /** Takes the clock from the host: see `Hold`. Throws while another hold has it. */
+    /** Takes the clock from the host. See `Hold`. Throws while another hold has it. */
     hold(): Hold;
 }
+/**
+ * What history a watched mix keeps, as `Watched.history` reports it.
+ *
+ * @category mix
+ */
+export interface WatchedHistory {
+    /** How much stays in memory, ms of mix time. */
+    readonly ms: number;
+    /** Whether it records a tape. */
+    readonly tape: boolean;
+    /** Whether the registry's `history` gave it. */
+    readonly added: boolean;
+}
+/**
+ * What a voice was cued with that its handle does not carry. `Watched.voice` reports it.
+ *
+ * @category mix
+ */
+export interface WatchedVoice {
+    readonly name: string | undefined;
+    readonly tags: readonly string[];
+    /**
+     * What it is bounded to, by `within` or an `around` weight. It is a circle, read live, or the
+     * host's finder; undefined for none.
+     */
+    readonly within: Readonly<Circle> | Finder | undefined;
+}
 /**
  * What the host read in one frame.
  *
@@ -83,19 +117,33 @@ export interface WatchedFrame<I, O> {
     /** The host's timestamp at the frame's sync. */
     timestamp: number;
     /** Each probe, in order, with a copy of the pose it returned. */
-    probed: {
-        subject: I;
-        pose: O;
-    }[];
+    probed: Probed<I, O>[];
     /** Each pull, with copies of the columns it wrote. */
-    pulled: {
-        subjects: I[];
-        columns: Record<string, Float64Array>;
-    }[];
+    pulled: Pulled<I>[];
     /** What `drain` handed the host. */
     sent: Sent<I, unknown>[];
     voices: Handle<I>[];
 }
+/**
+ * One probe a watched frame recorded.
+ *
+ * @category mix
+ */
+export interface Probed<I, O> {
+    subject: I;
+    /** A copy of the pose the probe returned. */
+    pose: O;
+}
+/**
+ * One pull a watched frame recorded.
+ *
+ * @category mix
+ */
+export interface Pulled<I> {
+    subjects: I[];
+    /** Copies of the columns it wrote, by channel. */
+    columns: Record<string, Float64Array>;
+}
 /**
  * A mix's clock in a debugger's hands, and every mix's on the same transport. The host's `sync`
  * still begins each frame, but the frame's gap counts at `rate`, so the mix moves at `rate` times
@@ -109,7 +157,7 @@ export interface Hold {
     readonly mixes: Mix<unknown, unknown>[];
     /** The mix clock. */
     readonly now: number;
-    /** The earliest mix time `seek` reaches: `now` without history and a tape. */
+    /** The earliest mix time `seek` reaches. It is `now` without history and a tape. */
     readonly reach: number;
     /** How much of each of the host's frames the held mix plays; 0 pauses it. Starts at 0. */
     rate: number;
@@ -118,9 +166,9 @@ export interface Hold {
     /** Plays the mixes `ms` of mix time further on, in one frame. */
     step(ms: number): void;
     /**
-     * Gives the clock back: the host's next sync carries on from where the hold left the mix, and
-     * its clock calls made meanwhile are made, in order. A call made while the tape holds later
-     * calls acts on the mix but is not recorded, so those calls still play.
+     * Gives the clock back to the host. The host's next sync carries on from where the hold left the
+     * mix, and its clock calls made meanwhile are made, in order. A call made while the tape holds
+     * later calls acts on the mix but is not recorded, so those calls still play.
      */
     free(): void;
 }