@msb235/blits 0.14.0 → 0.15.1

package/dist/types/mix.d.ts

@@ -1,18 +1,19 @@
 import type { ArcHandle, ArcSpec } from './arc.js';
 import type { Kit } from './channel.js';
 import type { HistoryOptions, Tape } from './history.js';
-import type { Patch, Sent, Signal } from './patch.js';
+import type { Band, Easing, Patch, Sent, Signal } from './patch.js';
 import type { Booker, BookOptions, Marked } from './place.js';
+import type { Trace, TraceOptions } from './trace.js';
 import type { Transport } from './transport.js';
-import type { BlendMember, Handle, OwnerSpec, SpanHandle, SpanSpec, VoiceSpec } from './voice.js';
+import type { BlendMember, Circle, Handle, OwnerSpec, SpanHandle, SpanSpec, VoiceSpec } from './voice.js';
 /**
- * How a mix is built: its engine, reduced motion, the host, and its limits.
+ * How a mix is built. It names the engine, reduced motion, the host, and the mix's limits.
  *
  * @category mix
  */
 export interface MixOptions<H = unknown> {
     engine?: Engine;
-    /** Reduced motion: fades and warm-ups snap, `dt` reads Infinity. */
+    /** Whether motion is reduced. Fades and warm-ups then snap, and `dt` reads Infinity. */
     reduce?: boolean | (() => boolean);
     /** Merged into every `setting.host`. Its type is the mix's `H`, which every patch and signal it cues reads. */
     host?: H;
@@ -20,14 +21,13 @@ export interface MixOptions<H = unknown> {
      * The band a rest-less channel's contribution switches on and off across. Default: on at any weight
      * above 0, off at 0, so the contribution passes whole while its voice has any weight.
      */
-    band?: {
-        on: number;
-        off: number;
-    };
+    band?: Band;
     /**
-     * Tags that act as loci: a voice carrying one folds with the others carrying it, as if its `locus`
-     * named that tag.
+     * Tags that act as roles. A voice carrying one folds with the others carrying it, as if its
+     * `role` named that tag.
      */
+    roles?: readonly string[];
+    /** @deprecated Renamed `roles`. Taken as `roles`, with a warning outside production. */
     loci?: readonly string[];
     /**
      * The most `dt` a `step` or signal is handed, however long the gap. Off by default, since a
@@ -35,48 +35,49 @@ export interface MixOptions<H = unknown> {
      */
     maxDt?: number;
     /**
-     * Run every `step` at this fixed interval, ms, instead of once by the frame's gap, so stateful
-     * patches play the same at any frame rate. Intervals count from when a subject's delay ran out,
-     * the remainder carrying to the next sample; `maxDt` then caps how many one sample may run.
-     * Signals and `at` still see the frame. Off by default.
+     * A fixed interval, ms, to run every `step` at. Without it each `step` runs once by the frame's
+     * gap; with it stateful patches play the same at any frame rate. Intervals count from when a
+     * subject's delay ran out, the remainder carrying to the next sample; `maxDt` then caps how many
+     * one sample may run. Signals and `at` still see the frame. Off by default.
      */
     stepMs?: number;
     /**
-     * How far back `project` may read, in ms of mix time, and how often a stateful voice's state is
-     * kept per subject on the way, `every` ms (default 200). Within it the mix remembers what it cued,
-     * every change a handle made and when, the voices that have left, and those copies of state, so a
-     * read back restores the nearest copy and steps forward from it. Off by default, and a mix without
-     * it keeps nothing. With `inputs`, it also keeps what each input signal on a voice's weight read
-     * per subject, and the host fields patches `reads`, each time they changed, so a read back over a
+     * What the mix remembers so `project` and `seek` can read back. `ms` is how far back `project`
+     * may read, in ms of mix time, and `every` how often a stateful voice's state is kept per subject
+     * on the way, in ms (default 200). Within it the mix remembers what it cued, every change a
+     * handle made and when, the voices that have left, and those copies of state, so a read back
+     * restores the nearest copy and steps forward from it. Off by default, and a mix without it keeps
+     * nothing. With `inputs`, it also keeps what each input signal on a voice's weight read per
+     * subject, and the host fields patches `reads`, each time they changed, so a read back over a
      * `level` or a pointer is known rather than held. With `tape`, the mix also records every call
      * the host makes on it, its handles and its motion patches, so `seek` can move it and play those
      * calls again.
      */
     history?: HistoryOptions;
     /**
-     * A subject's key, for a history `store`: unique among this mix's subjects for the session. A
-     * string or number subject is its own key; with a store, an object subject needs this.
+     * A subject's key, for a history `store`. It is unique among this mix's subjects for the session.
+     * A string or number subject is its own key; with a store, an object subject needs this.
      */
     keyOf?(subject: never): string | number;
     /**
-     * What a debugger calls a subject (see `watched`); where it gives nothing, the subject's own
-     * `name` or `id`, a DOM element's tag, id and classes, or its class and a number.
+     * What a debugger calls a subject (see `watched`). Where it gives nothing, the debugger uses the
+     * subject's own `name` or `id`, a DOM element's tag, id and classes, or its class and a number.
      */
     labelOf?(subject: never): string | undefined;
     /**
-     * Whether a channel may run as a lane: computed for every subject at once in flat arrays, when
-     * every voice writing it can run that way. On by default; what a host reads is the same either
-     * way (`probe`, `pull`, `atRest`, `weightOf`, `inert` and `project`), so turning it off is for
-     * ruling a lane out, or for comparing against. A voice weighted by an input signal `input` did not
-     * make, or whose patch reads host fields, never runs on a lane, since a change to either
-     * between two probes would not reach it. Two things differ: a
-     * stateless patch's `setting.send` from `at` sends for every subject a lane fills, those probed
-     * this frame or the last, and a patch that first calls `setting.keep` partway through playing can
-     * advance that state once more for one subject probed the frame before (see `Setting.keep`).
+     * Whether a channel may run as a lane. A lane computes every subject at once in flat arrays, when
+     * every voice writing the channel can run that way. On by default; what a host reads is the same
+     * either way (`probe`, `pull`, `atRest`, `weightOf`, `inert` and `project`), so turning it off is
+     * for ruling a lane out, or for comparing against. A voice weighted by an input signal `input`
+     * did not make, or whose patch reads host fields, never runs on a lane, since a change to either
+     * between two probes would not reach it. Two things differ: a stateless patch's `setting.send`
+     * from `at` sends for every subject a lane fills, those probed this frame or the last, and a
+     * patch that first calls `setting.keep` partway through playing can advance that state once more
+     * for one subject probed the frame before (see `Setting.keep`).
      */
     lanes?: boolean;
     /**
-     * The transport this mix plays on, shared with other mixes, so they keep one clock and a query
+     * The transport this mix plays on, shared with other mixes. They then keep one clock, and a query
      * naming a score looks in all of them. The transport's `sync`, `rebase`, `rate`, `ramp` and
      * `seek` move it, and the mix's own throw. Its history is the transport's, so the mix takes no
      * `history` of its own.
@@ -86,17 +87,17 @@ export interface MixOptions<H = unknown> {
     name?: string;
 }
 /**
- * How sure a projection is of one channel: `exact` where only the clock and known changes drove
- * it; `stepped` where state was advanced across a gap in one go, which is as good as the patch's
- * step makes it, or a signal's state was read back from a copy; `held` where it depends on input from outside the clock, whose value at that time
- * is not known, so the value it had is held.
+ * How sure a projection is of one channel. It is `exact` where only the clock and known changes
+ * drove it; `stepped` where state was advanced across a gap in one go, which is as good as the
+ * patch's step makes it, or a signal's state was read back from a copy; `held` where it depends on
+ * input from outside the clock, whose value at that time is not known, so the value it had is held.
  *
  * @category mix
  */
 export type Doubt = 'exact' | 'stepped' | 'held';
 /**
- * The mix read at another time: what `probe` would give at that timestamp, with nothing in the
- * live mix moved. Valid until the mix is next synced or cued.
+ * The mix read at another time, with nothing in the live mix moved. It gives what `probe` would
+ * give at that timestamp. Valid until the mix is next synced or cued.
  *
  * @category mix
  */
@@ -105,14 +106,14 @@ export interface Projection<I, O> {
     readonly timestamp: number;
     /** The merged pose for one subject at this projection's timestamp. */
     probe(subject: I, out?: O): O;
-    /** Per channel, how sure that pose is; the least sure voice that fed a channel decides. */
+    /** How sure that pose is, per channel. The least sure voice that fed a channel decides. */
     assess(subject: I): {
         [K in keyof O]-?: Doubt;
     };
 }
 /**
- * Arrays for `pull` to write, one per channel it reads: any channel whose value is a number or an
- * array of numbers.
+ * Arrays for `pull` to write, one per channel it reads. It reads any channel whose value is a
+ * number or an array of numbers.
  *
  * @category mix
  */
@@ -128,45 +129,45 @@ export interface Mix<I, O, H = unknown> {
     /** Cues a voice. Throws when the engine cannot run the patch's form, or the kit lacks a channel. */
     cue(spec: VoiceSpec<I, O, H>): Handle<I>;
     /**
-     * N voices whose weights split one signal, cued into one locus so they fold as alternatives. The
-     * signal is read once per subject per frame, with the first member's setting, and every member
-     * takes its share of that one reading, which `share` reads outside the blend; a signal keeping
-     * state keeps it once, not per member. One `spec` cues them all, and a member given as a
+     * Cues N voices into one role, their weights split from one signal. They fold as alternatives.
+     * The signal is read once per subject per frame, with the first member's setting, and every
+     * member takes its share of that one reading, which `share` reads outside the blend; a signal
+     * keeping state keeps it once, not per member. One `spec` cues them all, and a member given as a
      * `BlendMember` carries its own `name`, `tags` and `hits` in place of the spec's.
      */
-    blend(members: readonly (Patch<I, O, any, H> | BlendMember<I, O, H>)[], by: Signal<I, H>, spec?: Omit<VoiceSpec<I, O, H>, 'patch' | 'weight' | 'locus'>): Handle<I>[];
+    blend(members: readonly (Patch<I, O, any, H> | BlendMember<I, O, H>)[], by: Signal<I, H>, spec?: Omit<VoiceSpec<I, O, H>, 'patch' | 'weight' | 'role' | 'locus' | 'within'>): Handle<I>[];
     /**
-     * Cues an owner: a voice with no patch that holds the voices cued with `owner` set to its handle,
-     * and plays them on its own clock, so they can be placed, timed and faded as one. Its handle acts
-     * on all of them: `rate` and `ramp` multiply into theirs, `seek` moves their clocks with its own
-     * and rebuilds their state as it does a voice's, and `weight` and `fade()` multiply into their weights, by
-     * what its `weightOf` reports; it fades as a whole, not by subject or at rest. It is
-     * `played` once every voice it held has finished its passes, and leaves, `done`, with its last; a
-     * fade that ends takes the rest with it. One that never holds a voice stays until faded. Owners
-     * nest. Throws for a `loop`: a pass would have to restart its children.
+     * Cues an owner, a voice with no patch that plays other voices on its own clock. It holds the
+     * voices cued with `owner` set to its handle, so they can be placed, timed and faded as one. Its
+     * handle acts on all of them: `rate` and `ramp` multiply into theirs, `seek` moves their clocks
+     * with its own and rebuilds their state as it does a voice's, and `weight` and `fade()` multiply
+     * into their weights, by what its `weightOf` reports; it fades as a whole, not by subject or at
+     * rest. It is `played` once every voice it held has finished its passes, and leaves, `done`, with
+     * its last; a fade that ends takes the rest with it. One that never holds a voice stays until
+     * faded. Owners nest. Throws for a `loop`: a pass would have to restart its children.
      */
     owns(spec: OwnerSpec<I, H>): Handle<I>;
     /**
-     * Cues a span: an owner that lays out the voices it holds in `order` and fits them into its
-     * `duration`, again each time one joins or leaves early. A child's start and rate are the
-     * span's to set, so it takes neither `start` nor an anchored start; its `SpanHints` say how it
-     * may give way. A span with a budget stays until the budget has passed, though its children
-     * finish sooner, so late ones can still join, and its `end` mark is where its children end or
-     * its budget does, whichever is later. A voice that loops for good cannot join one. Throws for
-     * a `rate` below 0: a span lays its children out forward from its start, and its handle's `rate`
-     * turns it once it plays.
+     * Cues a span, an owner that fits the voices it holds into its `duration`. It lays them out in
+     * `order`, again each time one joins or leaves early. A child's start and rate are the span's to
+     * set, so it takes neither `start` nor an anchored start; its `SpanHints` say how it may give
+     * way. A span with a budget stays until the budget has passed, though its children finish sooner,
+     * so late ones can still join, and its `end` mark is where its children end or its budget does,
+     * whichever is later. A voice that loops for good cannot join one. Throws for a `rate` below 0: a
+     * span lays its children out forward from its start, and its handle's `rate` turns it once it
+     * plays.
      */
     span(spec: SpanSpec<I, H>): SpanHandle<I>;
     /**
-     * Cues an arc: an owner holding three parts that hand over in order on its clock, `enter`, then
-     * `active` for the `hold`, then `exit`, each a voice or several layered. Its marks are its own:
-     * `start` as the enter begins, `in` as it ends, `coast` as the hold ends and `out` as the exit
-     * begins, which are one time, and `end` as the exit ends, where it leaves and `done` resolves.
-     * While the hold is open, `coast`, `out` and `end` are unknown until `release` fixes them. Each
-     * part shows its first and last frames through the blends either side of it, and a part left
-     * out leaves its time to the one before it. Its `fade` takes it out with no exit. An arc with a
-     * finite hold may sit in a span. Throws for a `rate` below 0, a hold below 0, and an `enter` or
-     * `exit` that never ends.
+     * Cues an arc, an owner holding three parts that hand over in order. On its clock `enter` plays,
+     * then `active` for the `hold`, then `exit`, each a voice or several layered. Its marks are its
+     * own: `start` as the enter begins, `in` as it ends, `coast` as the hold ends and `out` as the
+     * exit begins, which are one time, and `end` as the exit ends, where it leaves and `done`
+     * resolves. While the hold is open, `coast`, `out` and `end` are unknown until `release` fixes
+     * them. Each part shows its first and last frames through the blends either side of it, and a
+     * part left out leaves its time to the one before it. Its `fade` takes it out with no exit. An
+     * arc with a finite hold may sit in a span. Throws for a `rate` below 0, a hold below 0, and an
+     * `enter` or `exit` that never ends.
      */
     arc(spec: ArcSpec<I, O, H>): ArcHandle<I>;
     /**
@@ -176,27 +177,27 @@ export interface Mix<I, O, H = unknown> {
      */
     sync(timestamp: number): void;
     /**
-     * The time between the last sync and the next one is not to count: a host calls it when a
-     * hidden tab comes back. Every voice, fade and subject resumes where it was left.
+     * Leaves the time between the last sync and the next one uncounted. A host calls it when a hidden
+     * tab comes back. Every voice, fade and subject resumes where it was left.
      */
     rebase(): void;
     /**
-     * The mix's own playback rate, multiplied into every voice's: 1 is real time and 0 pauses the
-     * whole mix. A negative rate throws: the mix plays only forward, and `seek` moves it back. Setting it changes speed at
-     * once; `ramp` eases into a new one. It scales mix time, which everything a voice owns runs on:
-     * its clock, its fades and a handle's ramp, `stagger`, an anchor's `by`, `stepMs`, `maxDt`,
-     * `history.ms`, every `dt`, and `setting.timestamp`. Timestamps on the host's clock name the same
-     * moment whatever the rate does: a `start`, an anchor given as a number, an announced mark, what
-     * `marks` reports and the time `project` reads, so a start ahead of a paused mix waits for the
-     * host's clock to reach it. A weight signal is still asked at every probe, so one reading host
-     * input follows it while the mix is paused.
+     * The mix's own playback rate, multiplied into every voice's. 1 is real time and 0 pauses the
+     * whole mix. A negative rate throws: the mix plays only forward, and `seek` moves it back.
+     * Setting it changes speed at once; `ramp` eases into a new one. It scales mix time, which
+     * everything a voice owns runs on: its clock, its fades and a handle's ramp, `stagger`, an
+     * anchor's `by`, `stepMs`, `maxDt`, `history.ms`, every `dt`, and `setting.timestamp`. Timestamps
+     * on the host's clock name the same moment whatever the rate does: a `start`, an anchor given as
+     * a number, an announced mark, what `marks` reports and the time `project` reads, so a start
+     * ahead of a paused mix waits for the host's clock to reach it. A weight signal is still asked at
+     * every probe, so one reading host input follows it while the mix is paused.
      */
     rate: number;
     /**
-     * Moves the mix's rate to `rate` linearly over `over` ms of the host's clock, as `Handle.ramp`
-     * moves a voice's. Mix time integrates the ramp and a voice's clock integrates mix time, so a ramp
-     * on both multiplies and every position stays continuous. A later `rate` write or `ramp` replaces
-     * it.
+     * Moves the mix's rate to `rate` linearly over `over` ms of the host's clock. It works as
+     * `Handle.ramp` does on a voice's. Mix time integrates the ramp and a voice's clock integrates
+     * mix time, so a ramp on both multiplies and every position stays continuous. A later `rate`
+     * write or `ramp` replaces it.
      */
     ramp(rate: number, over: number): void;
     /**
@@ -209,8 +210,17 @@ export interface Mix<I, O, H = unknown> {
      */
     probe(subject: I, out?: O): O;
     /**
-     * Writes each subject's pose into arrays, one per channel, subject by subject in the order given:
-     * what `probe(subject, out)` gives, without a pose object per subject. A channel of `n` numbers
+     * A new empty pose, to pass as `probe`'s `out`. Each call makes its own object, holding every
+     * channel with a rest in kit order: a number rest at its value, any other `undefined` until a
+     * probe writes it. Make one and pass it as `probe`'s `out` every frame. An `out` made as `{}` or
+     * a literal shares V8's shapes with the host's other small objects, which can leave each number
+     * written into it boxed; this one has a shape of its own, so the mix writes numbers into it
+     * without allocating.
+     */
+    pose(): O;
+    /**
+     * Writes each subject's pose into arrays, one per channel. Subjects go in the order given, each
+     * as `probe(subject, out)` gives it, without a pose object per subject. A channel of `n` numbers
      * takes `n` places per subject, side by side; one with no value for a subject writes NaN there.
      * Fastest while every voice runs on a lane, and when `subjects` is an array read again in the
      * same order: the mix remembers the last array's subjects by position, holding them until the
@@ -242,34 +252,49 @@ export interface Mix<I, O, H = unknown> {
         readonly frame: number;
     }): Projection<I, O>;
     /**
-     * Moves the mix to mix time `time`, as it stood at the end of that frame, and plays on from
-     * there; where rate 0 held the clock at `time` for several frames, the last of them. Needs
-     * `history` with a `tape`, which records the host's calls by the host time they were made at.
+     * Reads the mix over a window of mix time, `from` to `to`, without moving it, as `project` reads
+     * one moment: `trace.of(subject, channel)` gives that channel as points joined by straight lines.
+     * Where every voice feeding the channel is a `keys` voice whose shape is known through the
+     * window, the points are its own breakpoints and the lines are exact; elsewhere the run is read
+     * every `grid` ms, as many `project` calls would read it.
+     *
+     * Exact needs, of each voice reaching the subject and writing the channel: a `keys` patch whose
+     * stops are plain numbers, eased `linear`; a number weight; no owner, anchor, role, blend,
+     * `within`, `stepMs`, `from: 'current'`, or rate ramp; a fade in finished by `from` and no fade
+     * out under way or due. The channel folds by `sum`, or by `mul` from one such voice, and has no
+     * `bounds`. The window lies at or after the mix's own time, and the tape holds no calls ahead.
+     */
+    trace(from: number, to: number, opts?: TraceOptions): Trace<I, O>;
+    /**
+     * Moves the mix to mix time `time` and plays on from there. It lands as the mix stood at the end
+     * of that frame; where rate 0 held the clock at `time` for several frames, the last of them.
+     * Needs `history` with a `tape`, which records the host's calls by the host time they were made
+     * at.
      *
      * Back, the mix restores itself: controls, records, voices and marks as they stood then. Voices
      * that left after it are back on the handles the host holds, their `done` and `played` starting
      * over where they had settled since. Voices cued after it wait as `pending` until the mix plays
      * their cue again, and a write to the handle of one waiting changes nothing. Stateful voices
      * restart from the copy `history` kept nearest before it and step once to it, exact under
-     * `stepMs`. A subject faded out of a voice or dropped after it comes back with the record it
-     * had, a motion patch's state included. Recorded input and host fields after it are let go:
-     * after a seek back, signals and host fields read live again, and `assess` reports what they
-     * fed as `held`.
+     * `stepMs`. A subject faded out of a voice or dropped after it comes back with the record it had,
+     * a motion patch's state included. Recorded input and host fields after it are let go: after a
+     * seek back, signals and host fields read live again, and `assess` reports what they fed as
+     * `held`.
      *
      * Forward, through a sync or a later seek, the mix plays the recorded calls again in the frames
-     * they were made in: cues, handle writes, fades, retargets and pushes, its rate, marks,
-     * `mute` and `drop`. A call the host makes while there are recorded calls ahead starts a new
-     * branch, and the tape keeps the old future beside it; `tape.switchBranch` picks one back.
-     * Playing past a time again sends its events and books its marks and hits again.
+     * they were made in: cues, handle writes, fades, retargets and pushes, its rate, marks, `mute`
+     * and `drop`. A call the host makes while there are recorded calls ahead starts a new branch, and
+     * the tape keeps the old future beside it; `tape.switchBranch` picks one back. Playing past a
+     * time again sends its events and books its marks and hits again.
      *
-     * The host goes on passing its own clock: the next `sync` reads the moment sought plus the
-     * host's time since its last sync. Throws for a time older than history reaches, and before
-     * the first sync. With a history `store`, a time older than memory needs `prepare` first, or
-     * throws `HistoryMiss` before anything moves.
+     * The host goes on passing its own clock: the next `sync` reads the moment sought plus the host's
+     * time since its last sync. Throws for a time older than history reaches, and before the first
+     * sync. With a history `store`, a time older than memory needs `prepare` first, or throws
+     * `HistoryMiss` before anything moves.
      *
-     * Given `{ frame }`, a number `seq` read, it moves to the end of that frame instead, which is
-     * how a host reaches an earlier one of several frames rate 0 held at one mix time. The frame has
-     * to be one history still holds: not let go with age, and not after a moment an earlier seek went
+     * Given `{ frame }`, a number `seq` read, it moves to the end of that frame instead, which is how
+     * a host reaches an earlier one of several frames rate 0 held at one mix time. The frame has to
+     * be one history still holds: not let go with age, and not after a moment an earlier seek went
      * back to. With a store, one older than memory needs `prepare` of its mix time first.
      */
     seek(to: number | {
@@ -278,112 +303,161 @@ export interface Mix<I, O, H = unknown> {
     /** As `Transport.prepare`, for a mix made alone. */
     prepare(time: number): Promise<void>;
     /**
-     * The mix clock at the last sync or seek, which `seek` and `project` take; NaN before the first
-     * sync. Host time at the mix's rate, less what `rebase` took out and `seek` moved.
+     * The mix clock at the last sync or seek. It is the time `seek` and `project` take; NaN before
+     * the first sync. Host time at the mix's rate, less what `rebase` took out and `seek` moved.
      */
     readonly now: number;
     /** The host's timestamp at the last sync; NaN before the first. */
     readonly timestamp: number;
     /**
-     * The number of the frame being played, which `seek({ frame })` and `project({ frame })` take:
-     * each sync and seek begins a frame with a higher one, so two frames at one mix time differ.
+     * The number of the frame being played. `seek({ frame })` and `project({ frame })` take it. Each
+     * sync and seek begins a frame with a higher one, so two frames at one mix time differ.
      */
     readonly seq: number;
     /** The tape `history.tape` made, undefined without one. */
     readonly tape: Tape | undefined;
     /**
-     * Every channel at rest for this subject this frame, so a host can skip the write. After a probe
-     * of the subject this frame, it answers for the pose that probe gave, without folding again.
+     * Whether every channel is at rest for this subject this frame. A host can then skip the write.
+     * After a probe of the subject this frame, it answers for the pose that probe gave, without
+     * folding again.
      */
     atRest(subject: I): boolean;
     /**
-     * A handle on every voice still in the mix, pending, live, frozen or fading, in the order they were
-     * cued; given a tag, only the voices whose `tags` carry it. Each is the handle `cue` returned for
-     * that voice, so a listed handle is `===` the cued one.
+     * A handle on every voice still in the mix, in the order they were cued. That includes pending,
+     * live, frozen and fading voices; given a tag, only the voices whose `tags` carry it. Each is the
+     * handle `cue` returned for that voice, so a listed handle is `===` the cued one.
      */
     voices(tag?: string): Handle<I>[];
     /** Anything still contributing, fading, or pending. */
     readonly live: boolean;
     /**
-     * Another frame would change no pose, so a host's frame loop may sleep: every voice is done, frozen
-     * at a plain weight, or a motion whose every subject has landed on its target. At rate 0 it is
-     * enough that every voice not done has started, at a plain weight, with no anchor. A change made
-     * since the last sync, a retarget or a rate included, makes it false until the next. Read as true,
-     * it tells the mix the host may sleep: a voice cued with no `start` before the next sync starts
-     * at that sync.
+     * Whether another frame would change no pose, so a host's frame loop may sleep. It holds when
+     * every voice is done, frozen at a plain weight, or a motion whose every subject has landed on
+     * its target. At rate 0 it is enough that every voice not done has started, at a plain weight,
+     * with no anchor. A change made since the last sync, a retarget or a rate included, makes it
+     * false until the next. Read as true, it tells the mix the host may sleep: a voice cued with no
+     * `start` before the next sync starts at that sync.
      */
     readonly inert: boolean;
     /**
-     * Calls `fn` when a host call makes the mix need frames again after a sync: a cue, a fade, a
-     * handle's or the mix's rate, a seek, a `drop`, a motion retargeted. It fires once until the next
-     * sync clears the change, and never during `sync`. Returns a function that unsubscribes `fn`.
-     * A frame loop sleeping on `inert` subscribes here to wake.
+     * Calls `fn` when a host call makes the mix need frames again after a sync. Such a call is a cue,
+     * a fade, a handle's or the mix's rate, a seek, a `drop`, or a motion retargeted. It fires once
+     * until the next sync clears the change, and never during `sync`. Returns a function that
+     * unsubscribes `fn`. A frame loop sleeping on `inert` subscribes here to wake.
      */
     onWake(fn: () => void): () => void;
     /**
-     * Takes the mix off the list debuggers read (see `watched`), for a host done with it, where it
-     * would otherwise stay until collected. Stops every watcher, and frees a hold no other listed mix
-     * on its transport shares. It still plays if synced.
+     * Takes the mix off the list debuggers read (see `watched`). It is for a host done with it, where
+     * it would otherwise stay until collected. Stops every watcher, and frees a hold no other listed
+     * mix on its transport shares. It still plays if synced.
      */
     close(): void;
-    /** Fades every voice out: over `over` when given, over each voice's own `fade.out` otherwise. */
+    /** Fades every voice out. The ramp is `over` when given, else each voice's own `fade.out`. */
     mute(opts?: {
         over?: number;
     }): void;
     /**
-     * Forgets per-subject state, a motion patch's for the subject included, and any fade of the
-     * subject out of a voice, so nothing keeps the subject alive.
+     * Forgets a subject's state, so nothing keeps the subject alive. That includes a motion patch's
+     * state for the subject, and any fade of the subject out of a voice.
      */
     drop(subject: I): void;
     /**
-     * Says that something a patch reads from outside the mix has changed since the last sync, such as
-     * a table its `at` looks a subject up in, so the next probe calls the patch again where it would
-     * have answered with what it read this frame. Given a subject, for that subject only; with none,
-     * for every subject. The clock stays where it is and no `step` runs again, and it wakes a frame
-     * loop sleeping on `inert`, as any change does.
+     * Says that something a patch reads from outside the mix has changed since the last sync. One
+     * such thing is a table its `at` looks a subject up in. The next probe calls the patch again
+     * where it would have answered with what it read this frame. Given a subject, for that subject
+     * only; with none, for every subject. The clock stays where it is and no `step` runs again, and
+     * it wakes a frame loop sleeping on `inert`, as any change does.
      */
     touch(subject?: I): void;
     /**
-     * Puts a named mark on a score, for anchors to target as they target a voice's marks: a voice
+     * The subject's index, which a `within` finder names it by. It is the one it has, or a new one.
+     * It keeps it until `drop`, or, for an object, until the host lets it go; then the index is
+     * handed to the next subject placed. A subject placed with no `plot` has no position until `put`
+     * gives it one.
+     */
+    place(subject: I): number;
+    /**
+     * Gives the mix each subject's index and position at once, for voices cued `within` a circle. The
+     * index is the subject's place in `subjects`, and `xy` holds two numbers a subject, `x` then `y`,
+     * in that order. It is read in place, so a host moving its subjects writes into it and calls
+     * `moved`. `cell` sizes the grid the mix finds subjects in, best near the radius the circles use;
+     * by default, about two subjects a cell. Another call replaces the list and every index. A
+     * subject `place`d after it takes an index freed by `drop`, which reads whatever `xy` holds
+     * there, or one past the list, which has no position. Throws for an `xy` shorter than two numbers
+     * a subject.
+     */
+    plot(subjects: readonly I[], xy: Float64Array, cell?: number): void;
+    /** Says the host wrote new positions into the array it gave `plot`. The next frame reads them. */
+    moved(): void;
+    /**
+     * Moves one subject to (`x`, `y`), for a host where few move at once. It writes into the array
+     * `plot` was given, so the host's array holds the move too, or with no `plot`, into the mix's
+     * own, and the grid is built again only once many subjects have left their cells. The same as
+     * writing the array and calling `moved`; the two mix freely. Throws for a subject with no index,
+     * and for one whose index is past the array `plot` was given.
+     */
+    put(subject: I, x: number, y: number): void;
+    /**
+     * A weight signal over the positions `plot` or `put` gave, highest at a circle's center. It is 1
+     * at the center, falling with distance to 0 at `r` and beyond, along `ease` read from the edge
+     * (0) to the center (1), linear by default. The host moves or resizes the circle by writing to
+     * it. A voice it weighs is bounded to the circle as if cued `within` it, with no check, since the
+     * circle is the signal's own edge, from the first `place` or `plot` for one cued before it. A
+     * subject with no position reads 0.
+     */
+    around(circle: Circle, opts?: {
+        ease?: Easing;
+    }): Signal<I, H>;
+    /**
+     * Puts a named mark on a score, for anchors to target as they target a voice's marks. A voice
      * placed `{ with: 'reply' }` waits until the host announces `reply`. `at` is a timestamp on the
      * host's clock, default now, and may lie ahead, so a read ahead sees it. A mark stays while it is
      * ahead or while the mix's history reaches it.
      */
-    announce(name: string, opts?: {
-        at?: number;
-        score?: string;
-        tags?: readonly string[];
-    }): void;
+    announce(name: string, opts?: AnnounceOptions): void;
     /**
-     * Every mark the plan knows between two timestamps on the host's clock, earliest first: when
-     * voices start, are fully in, end their last pass, begin to fade and are gone, and what the host
-     * announced. A mark
-     * nothing has fixed yet, such as the out of a voice that loops for good, is not listed.
+     * Every mark the plan knows between two timestamps on the host's clock, earliest first. They are
+     * when voices start, are fully in, end their last pass, begin to fade and are gone, and what the
+     * host announced. A mark nothing has fixed yet, such as the out of a voice that loops for good,
+     * is not listed.
      */
     marks(from: number, to: number): Marked[];
     /**
-     * Every event patches have sent since the last drain, earliest first, in the order they were sent
-     * where two share a timestamp. A subject's events are made while it catches up, which is when it is
-     * probed, so one nobody probes has sent nothing yet: promptness is the host's, by probing. A
-     * stateless patch's `at` on a lane is the exception: it runs at the frame's first probe for every
-     * subject probed that frame or the last. Under `stepMs` each carries the end of the interval it happened in, so
-     * what is sent and when does not depend on how the host spaces its probes. Time `rebase` took out
-     * sends nothing. Given a tag, it takes only the events of voices carrying it and leaves the rest for
-     * whoever drains them.
+     * Every event patches have sent since the last drain, earliest first. Where two share a
+     * timestamp, they come in the order they were sent. A subject's events are made while it catches
+     * up, which is when it is probed, so one nobody probes has sent nothing yet: promptness is the
+     * host's, by probing. A stateless patch's `at` on a lane is the exception: it runs at the frame's
+     * first probe for every subject probed that frame or the last. Under `stepMs` each carries the
+     * end of the interval it happened in, so what is sent and when does not depend on how the host
+     * spaces its probes. Time `rebase` took out sends nothing. Given a tag, it takes only the events
+     * of voices carrying it and leaves the rest for whoever drains them.
      */
     drain<E = unknown>(tag?: string): Sent<I, E>[];
     /**
-     * Hands the host each mark and hit before it comes, against a clock of its own, so it can schedule
-     * the thing itself: a sound on an `AudioContext`, a MIDI message with a timestamp, a video loaded
-     * before the voice that shows it starts. Booking runs at each `sync`, `ahead` ms out, and a
-     * booking whose time moves is stopped and taken again. Nothing is booked twice: a mark is known by
-     * its voice and which mark, a hit by its voice, index and pass. `project` books nothing, and
-     * nothing about booking is replayed under `history`. A mix with no booker pays nothing for it.
+     * Hands the host each mark and hit ahead of time, against a clock of its own. The host can then
+     * schedule the thing itself: a sound on an `AudioContext`, a MIDI message with a timestamp, a
+     * video loaded before the voice that shows it starts. Booking runs at each `sync`, `ahead` ms
+     * out, and a booking whose time moves is stopped and taken again. Nothing is booked twice: a mark
+     * is known by its voice and which mark, a hit by its voice, index and pass. `project` books
+     * nothing, and nothing about booking is replayed under `history`. A mix with no booker pays
+     * nothing for it.
      */
     book<E = unknown>(opts: BookOptions<E, I>): Booker;
 }
 /**
- * The implementation behind a mix: which patch forms it runs, and how it makes one.
+ * What `announce` takes besides the mark's name.
+ *
+ * @category mix
+ */
+export interface AnnounceOptions {
+    /** A timestamp on the host's clock, which may lie ahead. Default now. */
+    at?: number;
+    /** The score the mark goes on. Default: the mix's one unnamed score. */
+    score?: string;
+    tags?: readonly string[];
+}
+/**
+ * The implementation behind a mix. It says which patch forms it runs, and how it makes one.
  *
  * @category engine
  */