@orkestrel/terminal 0.0.14 → 0.0.15

package/dist/src/core/index.d.ts

@@ -1,30 +1,32 @@
-import { CheckboxField } from '@orkestrel/form';
-import { ConfirmField } from '@orkestrel/form';
-import { DriverInterface } from '@orkestrel/database';
-import { EditorField } from '@orkestrel/form';
-import { EmitterErrorHandler } from '@orkestrel/emitter';
-import { EmitterHooks } from '@orkestrel/emitter';
-import { EmitterInterface } from '@orkestrel/emitter';
-import { FieldChoice } from '@orkestrel/form';
-import { FieldError } from '@orkestrel/form';
-import { FormInterface } from '@orkestrel/form';
-import { FormSchema } from '@orkestrel/form';
-import { FormValues } from '@orkestrel/form';
-import { Guard } from '@orkestrel/contract';
-import { JSONRecord } from '@orkestrel/contract';
-import { PasswordField } from '@orkestrel/form';
-import { Result } from '@orkestrel/contract';
-import { SelectField } from '@orkestrel/form';
-import { Style } from '@orkestrel/console';
-import { StylerInterface } from '@orkestrel/console';
-import { TableInterface } from '@orkestrel/database';
-import { TextField } from '@orkestrel/form';
-
-/** Names the `Accept` header value that opens the broker's SSE stream. */
+import type { CheckboxField } from '@orkestrel/form';
+import type { ConfirmField } from '@orkestrel/form';
+import type { DriverInterface } from '@orkestrel/database';
+import type { EditorField } from '@orkestrel/form';
+import type { EmitterErrorHandler } from '@orkestrel/emitter';
+import type { EmitterHooks } from '@orkestrel/emitter';
+import type { EmitterInterface } from '@orkestrel/emitter';
+import type { FieldChoice } from '@orkestrel/form';
+import type { FieldError } from '@orkestrel/form';
+import type { FormInterface } from '@orkestrel/form';
+import type { FormSchema } from '@orkestrel/form';
+import type { FormValues } from '@orkestrel/form';
+import type { Guard } from '@orkestrel/contract';
+import type { JSONRecord } from '@orkestrel/contract';
+import type { PasswordField } from '@orkestrel/form';
+import type { Result } from '@orkestrel/contract';
+import type { SelectField } from '@orkestrel/form';
+import type { Style } from '@orkestrel/console';
+import type { StylerInterface } from '@orkestrel/console';
+import type { TableInterface } from '@orkestrel/database';
+import type { TextField } from '@orkestrel/form';
+
+/** Names the `Accept` header value that opens the broker's SSE stream — `text/event-stream`. */
 export declare const ACCEPT_EVENT_STREAM = "text/event-stream";
 
 /**
- * Explains why {@link PromptInterface.answer} refused. Names its axis with `reason`.
+ * Explains why {@link PromptInterface.answer} refused — `unknown` for an id no form is parked
+ * under, `rejected` for values the authoritative form itself refused, carrying the `FieldError`
+ * list it reported. Names its axis with `reason`.
  *
  * @remarks
  * - `unknown` — no form is parked under that id, or the one that was has already settled.
@@ -81,10 +83,10 @@ export declare interface ConfirmState {
 }
 
 /**
- * Holds the control BYTE (or CRLF pair) → key descriptor table {@link import('./helpers.js').parseKey}
- * consults for the one-byte keys and the two-byte CRLF Enter chunk. Each entry carries the
- * canonical `name` and whether it is a `ctrl` combination. The source of truth for that decode;
- * frozen.
+ * Holds the control byte (or CRLF pair) to key descriptor table
+ * {@link import('./helpers.js').parseKey} consults for the one-byte keys and the two-byte CRLF
+ * Enter chunk. Each entry carries the canonical `name` and whether it is a `ctrl` combination. The
+ * source of truth for that decode; frozen.
  *
  * @remarks
  * `return` / `newline` / `return + newline` all map to `return` (one canonical Enter name) — a
@@ -99,7 +101,8 @@ export declare const CONTROL_NAMES: Readonly<Record<string, {
 }>>;
 
 /**
- * Builds the initial checkbox-field key state.
+ * Builds the initial checkbox-field reducer state — the offered choices, with every value in the
+ * field's `default` list pre-checked.
  *
  * @param field - The checkbox field to render
  * @param styler - The styler used to render the view
@@ -109,7 +112,8 @@ export declare const CONTROL_NAMES: Readonly<Record<string, {
 export declare function createCheckboxState(field: CheckboxField, styler?: StylerInterface, theme?: PromptThemeOptions): CheckboxState;
 
 /**
- * Builds the initial confirm-field key state.
+ * Builds the initial confirm-field reducer state — the sanitized label and the declared default
+ * answer.
  *
  * @param field - The confirm field to render
  * @param styler - The styler used to render the view
@@ -121,7 +125,8 @@ export declare function createConfirmState(field: ConfirmField, styler?: StylerI
 /**
  * Creates a {@link TerminalStoreInterface} backed by one table of the `databases` layer — the
  * driver-pluggable twin of {@link createMemoryTerminalStore}, storing each endpoint's config
- * snapshot as one opaque JSON column.
+ * snapshot as one opaque JSON column. The default driver is an in-memory `@orkestrel/database`
+ * driver.
  *
  * @param driver - The {@link DriverInterface} backing the table (default an in-memory driver)
  * @returns A {@link TerminalStoreInterface}
@@ -136,7 +141,8 @@ export declare function createConfirmState(field: ConfirmField, styler?: StylerI
 export declare function createDatabaseTerminalStore(driver?: DriverInterface): TerminalStoreInterface;
 
 /**
- * Builds the initial editor-field key state.
+ * Builds the initial editor-field reducer state — the committed lines empty, and the declared
+ * default held for a finish with nothing typed.
  *
  * @param field - The editor field to render
  * @param styler - The styler used to render the view
@@ -146,7 +152,8 @@ export declare function createDatabaseTerminalStore(driver?: DriverInterface): T
 export declare function createEditorState(field: EditorField, styler?: StylerInterface, theme?: PromptThemeOptions): EditorState;
 
 /**
- * Builds the initial text-field key state.
+ * Builds the initial text-field reducer state — the sanitized label, the declared default, the
+ * styler, and the resolved theme.
  *
  * @param field - The text field to render
  * @param styler - The styler used to render the view
@@ -171,7 +178,8 @@ export declare function createInputState(field: TextField, styler?: StylerInterf
 export declare function createMemoryTerminalStore(): TerminalStoreInterface;
 
 /**
- * Builds the initial password-field key state.
+ * Builds the initial password-field reducer state — the text-field state, plus the mask glyph each
+ * typed character renders as.
  *
  * @param field - The password field to render
  * @param styler - The styler used to render the view
@@ -206,9 +214,10 @@ export declare function createPasswordState(field: PasswordField, styler?: Style
 export declare function createPrompt(options?: PromptOptions): PromptInterface;
 
 /**
- * Creates the SSE prompt {@link PromptClientInterface} BRIDGE — it connects to a remote broker's SSE
- * endpoint, dispatches each received form to a local {@link import('./types.js').TerminalInterface},
- * and POSTs the answer back. Universal — `fetch` / SSE are web-standard.
+ * Creates the SSE prompt {@link PromptClientInterface} bridge — it connects to a remote broker's
+ * SSE endpoint, dispatches each received form to a local
+ * {@link import('./types.js').TerminalInterface}, and POSTs the answer back. Universal — `fetch`
+ * and SSE are web standards.
  *
  * @param options - See {@link PromptClientOptions} (`url` + `terminal` required)
  * @returns A {@link PromptClientInterface}
@@ -253,7 +262,8 @@ export declare function createPromptClient(options: PromptClientOptions): Prompt
 export declare function createPromptTheme(options?: PromptThemeOptions): PromptTheme;
 
 /**
- * Builds the initial select-field key state.
+ * Builds the initial select-field reducer state — the offered choices, with the focus pre-placed on
+ * the declared default.
  *
  * @param field - The select field to render
  * @param styler - The styler used to render the view
@@ -263,9 +273,9 @@ export declare function createPromptTheme(options?: PromptThemeOptions): PromptT
 export declare function createSelectState(field: SelectField, styler?: StylerInterface, theme?: PromptThemeOptions): SelectState;
 
 /**
- * Creates the multi-endpoint {@link TerminalManager} — a named registry of
- * {@link PromptInterface} brokers so several parties can `ask` prompts of each other by name,
- * with a transitive DEADLOCK check across every in-flight ask.
+ * Creates the multi-endpoint {@link TerminalManager} — a named registry of {@link PromptInterface}
+ * brokers so several parties can `ask` forms of each other by name, with a transitive cycle check
+ * that refuses `DEADLOCK` across every in-flight ask.
  *
  * @param options - See {@link TerminalManagerOptions}
  * @returns A {@link TerminalManager}
@@ -296,10 +306,11 @@ export declare const CTRL_E: string;
 export declare const CTRL_U: string;
 
 /**
- * Implements a {@link TerminalStoreInterface} backed by one table of the `databases` layer — an endpoint's
- * durable CONFIG state IS a row, so persistence reduces to keyed point-access (`get` / `set` /
- * `delete`) over a {@link TableInterface}, the driver-pluggable twin of the plain-`Map`
- * {@link import('./MemoryTerminalStore.js').MemoryTerminalStore}.
+ * Implements a {@link TerminalStoreInterface} backed by one table of the `databases` layer — an
+ * endpoint's durable config state is a row, so persistence reduces to keyed point-access (`get` /
+ * `set` / `delete`) over a {@link TableInterface}, the driver-pluggable twin of the plain-`Map`
+ * {@link import('./MemoryTerminalStore.js').MemoryTerminalStore}. A stored `snapshot` is narrowed
+ * with {@link import('../validators.js').isTerminalSnapshot} on read.
  *
  * @remarks
  * The store is driver-agnostic: it holds a single {@link TableInterface} whose backend (memory,
@@ -392,7 +403,7 @@ export declare const DEFAULT_MASK = "*";
  */
 export declare const DEFAULT_PROMPT_THEME: PromptTheme;
 
-/** Holds how long (ms) the {@link import('./types.js').PromptInterface} broker parks an unanswered prompt before it expires — 5 minutes. */
+/** Holds how long (ms) the {@link import('./types.js').PromptInterface} broker parks an unanswered form before it expires — 5 minutes. */
 export declare const DEFAULT_PROMPT_TIMEOUT_MS = 300000;
 
 /** Holds how long (ms) the {@link import('./types.js').PromptClientInterface} waits before each reconnect attempt — 2 seconds. */
@@ -415,9 +426,10 @@ export declare function defaultTimer(callback: () => void, ms: number): TimerCan
 export declare const DELETE: string;
 
 /**
- * Applies a single line-editing {@link KeyEvent} to a text buffer — the editing shared by input /
- * password / editor. A printable key appends its character; `backspace` drops the last character;
- * `space` appends a space; ctrl-u clears the line.
+ * Applies a single line-editing {@link KeyEvent} to a text buffer — the editing shared by input,
+ * password, and editor. A printable key appends its character; `backspace` drops the last
+ * character; `space` appends a space; ctrl-u clears the line; a key that edits nothing returns
+ * `undefined`.
  *
  * @param value - The buffer the field holds so far
  * @param key - The decoded keypress to apply
@@ -474,7 +486,10 @@ export declare interface FetchInit {
  */
 export declare function globalFetch(input: string, init?: FetchInit): Promise<Response>;
 
-/** Names the auth-token request header the {@link import('./types.js').PromptClientInterface} sends. */
+/**
+ * Names the auth-token request header the {@link import('./types.js').PromptClientInterface} sends
+ * when a `token` is configured — `x-orkestrel-token`.
+ */
 export declare const HEADER_TOKEN = "x-orkestrel-token";
 
 /**
@@ -509,8 +524,10 @@ export declare interface InputState {
 export declare function isAbortError(error: unknown): boolean;
 
 /**
- * Checks whether `url` is an INSECURE remote endpoint — a plain `http://` URL whose host is NOT a
- * loopback address. Pure string parsing (no `URL` global), so it stays total on malformed input.
+ * Checks whether `url` is an insecure remote endpoint — a plain `http://` URL whose host is not a
+ * loopback address. Pure string parsing (no `URL` global), so it stays total on malformed input;
+ * the {@link import('./PromptClient.js').PromptClient} warns once when a `token` would cross such
+ * an endpoint in cleartext.
  *
  * @remarks
  * A loopback host (`localhost`, `127.0.0.1`, `[::1]`) over `http://` is exempt (local
@@ -530,7 +547,8 @@ export declare function isAbortError(error: unknown): boolean;
 export declare function isInsecureRemote(url: string): boolean;
 
 /**
- * Narrows an unknown wire value to a {@link PendingForm} envelope.
+ * Narrows an unknown wire value to a {@link PendingForm} envelope — the envelope alone, because the
+ * form package's `parseForm` owns the schema payload.
  *
  * @remarks
  * This guard checks the transport record and proves only that `schema` is a record. The Form
@@ -550,8 +568,8 @@ export declare function isPendingForm(value: unknown): value is PendingForm;
 export declare const isPendingFormStatus: Guard<PendingFormStatus>;
 
 /**
- * Checks whether a single character is a printable (non-control) character — used by
- * {@link parseKey}'s char fallback.
+ * Checks whether a single character is printable — the fallback test {@link parseKey} applies after
+ * the control bytes and the escape sequences, so the C0 controls and DEL are excluded.
  *
  * @param character - The single character to test
  * @returns True if the character is at or above space and is not DEL; false otherwise
@@ -559,7 +577,7 @@ export declare const isPendingFormStatus: Guard<PendingFormStatus>;
 export declare function isPrintable(character: string): boolean;
 
 /**
- * Narrows an unknown caught value to a {@link TerminalError}.
+ * Narrows an unknown caught value to a {@link TerminalError}, so a caller can branch on its `code`.
  *
  * @param value - The value to test (typically a `catch` binding or a rejected prompt call)
  * @returns True if `value` is a {@link TerminalError}; false otherwise
@@ -578,8 +596,8 @@ export declare function isPrintable(character: string): boolean;
 export declare function isTerminalError(value: unknown): value is TerminalError;
 
 /**
- * Narrows an unknown value to a {@link TerminalSnapshot} — the read boundary a store applies to an
- * untrusted persisted row.
+ * Narrows an unknown value to a {@link TerminalSnapshot} — a non-empty `id` and an optional numeric
+ * `timeout`, the read boundary a store applies to an untrusted persisted row.
  *
  * @param value - The candidate snapshot read back from storage
  * @returns True if the value carries a non-empty `id` and an optional numeric `timeout`; false otherwise
@@ -587,7 +605,8 @@ export declare function isTerminalError(value: unknown): value is TerminalError;
 export declare const isTerminalSnapshot: Guard<TerminalSnapshot>;
 
 /**
- * Narrows an unknown value to a transport-neutral {@link WireEvent}.
+ * Narrows an unknown value to a transport-neutral {@link WireEvent} — the guard a consumer's own
+ * transport applies to an inbound frame.
  *
  * @param value - The candidate wire event
  * @returns True if the value carries an event name, serialized data, and an optional id; false otherwise
@@ -629,9 +648,10 @@ export declare interface KeyEvent {
 
 /**
  * Implements the in-memory {@link TerminalStoreInterface} — a process-lifetime `Map` of
- * {@link TerminalSnapshot}s keyed by endpoint id, the DEFAULT store
- * {@link import('../factories.js').createMemoryTerminalStore} builds. The EXACT twin of
- * {@link import('./DatabaseTerminalStore.js').DatabaseTerminalStore}.
+ * {@link TerminalSnapshot} records keyed by endpoint id, the default store
+ * {@link import('../factories.js').createMemoryTerminalStore} builds and the exact twin of
+ * {@link import('./DatabaseTerminalStore.js').DatabaseTerminalStore}. It carries no idle expiry and
+ * no eviction.
  *
  * @remarks
  * A plain `Map<string, TerminalSnapshot>` — the snapshot is already pure, self-contained CONFIG-only
@@ -692,13 +712,14 @@ export declare const NEWLINE: string;
  * broker exposes, and the cancel for its expiry timer.
  *
  * @remarks
- * `form` is the AUTHORITATIVE form the caller parked, not a copy: an answer fills and submits this
+ * `form` is the authoritative form the caller parked, not a copy: an answer fills and submits this
  * one, so a `custom` rule that never crossed the wire still decides. Expiry destroys it, which
  * abandons it and settles the caller's promise through the form's own lifecycle. `pending` is the
  * wire record, whose `status` tracks the ticket.
  */
 export declare interface ParkedForm {
     readonly form: FormInterface;
+    /** Lists every parked record (`pending()`), or looks one up by id (`pending(id)`). */
     readonly pending: PendingForm;
     readonly cancel: TimerCancelFunction;
 }
@@ -708,7 +729,7 @@ export declare interface ParkedForm {
  * say.
  *
  * @remarks
- * `from` and `to` are the attribution edge, set ONLY by a {@link TerminalManagerInterface}: which
+ * `from` and `to` are the attribution edge, set only by a {@link TerminalManagerInterface}: which
  * endpoint asked, which endpoint must answer. A direct broker caller passes no request at all.
  */
 export declare interface ParkRequest {
@@ -718,16 +739,16 @@ export declare interface ParkRequest {
 
 /**
  * Decodes one keypress's bytes into a {@link KeyEvent} — total, never throws. A `Uint8Array` is
- * read as UTF-8; the resulting string is matched against the known control bytes and the CRLF
- * pair ({@link CONTROL_NAMES}) and escape sequences ({@link SEQUENCE_NAMES}), falling back to a
- * single printable character. An unrecognized sequence carries NO `name`, with the raw `sequence`
+ * read as UTF-8; the resulting string is matched against the known control bytes and the CRLF pair
+ * ({@link CONTROL_NAMES}) and escape sequences ({@link SEQUENCE_NAMES}), falling back to a single
+ * printable character. An unrecognized sequence carries no `name`, with the raw `sequence`
  * preserved.
  *
  * @remarks
  * - **Single control byte.** A one-character control input (`return` / `backspace` / `tab` /
  *   `escape` / `space`, or a Ctrl combo `c` / `d` / `u` / `a` / `e`), or the two-byte `\r\n`
  *   CRLF pair, is looked up in {@link CONTROL_NAMES}, carrying its `ctrl` flag.
- * - **Escape sequence.** A multi-byte ESC sequence (`up` / `down` / `left` / `right` in BOTH the
+ * - **Escape sequence.** A multi-byte ESC sequence (`up` / `down` / `left` / `right` in both the
  *   `ESC[A` and `ESCOA` forms, plus `home` / `end` / `delete`) is looked up in
  *   {@link SEQUENCE_NAMES} and flagged `meta`.
  * - **Printable character.** A single printable character becomes `name` = that character, with
@@ -769,8 +790,8 @@ export declare interface PasswordState {
 }
 
 /**
- * Represents one form PARKED by the broker — an id-keyed, wire-safe record of a live form awaiting a remote
- * answer. The value a `pending` listener receives and the broker serializes over SSE to a
+ * Represents one form parked by the broker — an id-keyed, wire-safe record of a live form awaiting
+ * a remote answer. The value a `pending` listener receives and the broker serializes over SSE to a
  * {@link PromptClientInterface}.
  *
  * @remarks
@@ -795,9 +816,9 @@ export declare interface PendingForm {
 }
 
 /**
- * Names the lifecycle status of a parked {@link PendingForm} — where the TICKET stands, which is not
- * where the form stands. A ticket is `pending` until somebody answers it; the form it carries has
- * its own status, and the two are separate facts about separate entities.
+ * Names the lifecycle status of a parked {@link PendingForm} — where the ticket stands, which is
+ * not where the form stands. A ticket is `pending` until somebody answers it; the form it carries
+ * has its own status, and each is a separate fact about a separate entity.
  *
  * @remarks
  * - `pending` — parked, awaiting {@link PromptInterface.answer}.
@@ -807,8 +828,9 @@ export declare interface PendingForm {
 export declare type PendingFormStatus = 'pending' | 'answered' | 'expired';
 
 /**
- * Implements the headless form broker. It parks live forms, exposes their serialized schemas, and applies
- * remote answers to the authoritative form.
+ * Implements the headless form broker. It parks live forms, exposes their serialized schemas,
+ * applies remote answers to the authoritative form, and abandons a parked form on timeout, release,
+ * or teardown.
  *
  * @remarks
  * A parked record carries one call to `serializeForm`. A failed fill or submit leaves the record
@@ -841,8 +863,9 @@ export declare class Prompt implements PromptInterface {
 }
 
 /**
- * Holds the default glyphs {@link DEFAULT_PROMPT_THEME} assembles its `icons` from. Read only when
- * the default theme is assembled; a view reads its resolved theme and never this constant. Frozen.
+ * Holds the terminal-owned glyphs {@link DEFAULT_PROMPT_THEME} assembles its `icons` from, beside
+ * the console module's own success and error marks. Read only when the default theme is assembled;
+ * a view reads its resolved theme and never this constant. Frozen.
  *
  * @remarks
  * - `question` — the leading mark on a prompt's message line.
@@ -867,8 +890,9 @@ export declare const PROMPT_ICONS: Readonly<{
 export declare const PROMPT_ROLES: readonly PromptRole[];
 
 /**
- * Implements the SSE form bridge. It ingests serialized forms from a remote broker, renders them through a
- * local terminal, and posts answers back without blocking the event stream.
+ * Implements the SSE form bridge. It ingests serialized forms from a remote broker without waiting
+ * on a render, drives one form at a time through a local terminal, posts each answer back, and asks
+ * again when the authoritative form refuses one.
  *
  * @remarks
  * - **Connect + reconnect.** {@link connect} opens the SSE stream and reconnects after a transport
@@ -880,8 +904,9 @@ export declare const PROMPT_ROLES: readonly PromptRole[];
  * - **Safe local form.** The rendering copy omits every wire `pattern`, because Form compiles a
  *   pattern during local evaluation. The broker's parked form retains it and remains authoritative.
  * - **Refusal retry.** A structured `rejected` response seeds a new rendering form with the values
- *   just submitted, applies every {@link FieldError} through `invalidate`, and asks again. No retry
- *   counter truncates the loop; acceptance, expiry, and the broker's own teardown are its bounds.
+ *   the refused attempt submitted, applies every {@link FieldError} through `invalidate`, and asks
+ *   again. No retry counter truncates the loop; acceptance, expiry, and the broker's own teardown
+ *   are its bounds.
  * - **Replay safety.** A replayed id is skipped while it is queued, rendering, or posting. Once an
  *   attempt ends, a later delivery of that id may be rendered again.
  *
@@ -924,10 +949,10 @@ export declare type PromptClientEventMap = {
 };
 
 /**
- * Declares the SSE form BRIDGE — the client-side counterpart to {@link PromptInterface}. It receives
- * serialized {@link PendingForm} records from a remote broker, rebuilds each schema locally, drives
- * it through a {@link TerminalInterface}, and POSTs the answer back, so a human at this machine
- * answers forms a broker parked elsewhere.
+ * Declares the SSE form bridge — the client-side counterpart to {@link PromptInterface}. It
+ * receives serialized {@link PendingForm} records from a remote broker, rebuilds each schema
+ * locally, drives it through a {@link TerminalInterface}, and POSTs the answer back, so a human at
+ * this machine answers forms a broker parked elsewhere.
  *
  * @remarks
  * - **Connect.** {@link connect} opens the SSE stream through the injected `fetch` and resolves
@@ -940,14 +965,29 @@ export declare type PromptClientEventMap = {
  *   the wire is never executed locally. The authoritative form decides.
  * - **Refusal retries.** A rejected answer comes back with the parked form's own errors; the client
  *   applies them to the local form and asks again until the answer is accepted or the form expires.
- * - **`connected`** reflects whether the stream is currently open.
+ * - **`connected`** reflects whether the stream is open.
  */
 export declare interface PromptClientInterface {
+    /** Holds the typed emitter every client event is published on. */
     readonly emitter: EmitterInterface<PromptClientEventMap>;
+    /** Holds the remote broker's SSE endpoint this client reads from and answers to. */
     readonly url: string;
+    /** Reports whether the SSE stream is open. */
     readonly connected: boolean;
+    /**
+     * Opens the stream and pumps it, queueing each received form for the local terminal; reconnects
+     * on the `delay` backoff.
+     */
     connect(): Promise<void>;
+    /**
+     * Stops the current connection and the reconnect loop. An active local render continues, and a
+     * later `connect()` can restart the stream.
+     */
     disconnect(): void;
+    /**
+     * Tears the client down permanently — disconnects, drops the queue, abandons the active local
+     * form, and destroys the emitter.
+     */
     destroy(): void;
 }
 
@@ -957,8 +997,8 @@ export declare interface PromptClientInterface {
  *
  * @remarks
  * - `url` — the remote broker's SSE endpoint. A GET opens the stream; answers POST back to it.
- * - `terminal` — the LOCAL {@link TerminalInterface} each remote form is driven through, so a human
- *   at THIS machine answers a form parked elsewhere.
+ * - `terminal` — the local {@link TerminalInterface} each remote form is driven through, so a human
+ *   at this machine answers a form parked elsewhere.
  * - `token` — an optional auth token, sent as the {@link import('./constants.js').HEADER_TOKEN}
  *   header on every request.
  * - `reconnect` — whether to reconnect after the stream drops, default true.
@@ -992,6 +1032,9 @@ export declare interface PromptClientOptions {
  */
 export declare type PromptEventMap = {
     readonly pending: readonly [form: PendingForm];
+    /**
+     * Reports an accepted answer, carrying the parked form id and settled values.
+     */
     readonly answer: readonly [id: string, values: FormValues];
     readonly expire: readonly [id: string];
 };
@@ -1010,16 +1053,16 @@ export declare type PromptEventMap = {
 export declare type PromptIcon = 'question' | 'pointer' | 'dot' | 'selected' | 'checked' | 'unchecked' | 'success' | 'error';
 
 /**
- * Declares the headless form BROKER — parks a live form until somebody elsewhere answers it. The headless
- * arm of the local-TTY / headless / remote trio: there is no terminal here, so a transport forwards
- * each `pending` record to whoever can answer, and {@link answer} drives the parked form to
- * settlement.
+ * Declares the headless form broker — parks a live form until somebody elsewhere answers it. The
+ * headless arm of the local-TTY, headless, and remote trio: there is no terminal here, so a
+ * transport forwards each `pending` record to whoever can answer, and {@link answer} drives the
+ * parked form to settlement.
  *
  * @remarks
  * - **The form is the unit.** {@link park} takes a live form, mints an id, emits `pending`, and
  *   returns the id. It wraps no promise, because the caller already holds one: the form's own
  *   `answer`.
- * - **The parked form is authoritative.** {@link answer} fills and submits THAT form, so every rule
+ * - **The parked form is authoritative.** {@link answer} fills and submits that form, so every rule
  *   it carries decides, including a `custom` validator the wire dropped. A refusal returns the
  *   form's own errors and leaves the form parked.
  * - **Timeout abandons.** An unanswered form is destroyed after `timeout` ms; `expire` fires and
@@ -1040,15 +1083,34 @@ export declare type PromptIcon = 'question' | 'pointer' | 'dot' | 'selected' | '
  * ```
  */
 export declare interface PromptInterface {
+    /** Holds the typed emitter every broker event is published on. */
     readonly emitter: EmitterInterface<PromptEventMap>;
+    /** Reports how many forms this broker holds parked. */
     readonly count: number;
+    /**
+     * Parks a live form, mints its id, emits `pending`, and arms the expiry deadline. Returns the id;
+     * the caller already holds the promise.
+     */
     park(form: FormInterface, request?: ParkRequest): string;
+    /** Lists every parked record (`pending()`), or looks one up by id (`pending(id)`). */
     pending(): readonly PendingForm[];
     pending(id: string): PendingForm | undefined;
+    /**
+     * Fills and submits the authoritative parked form. Accepted, it settles and the record is
+     * dropped; refused, the form stays parked.
+     */
     answer(id: string, values: FormValues): Result<FormValues, AnswerError>;
+    /**
+     * Releases a batch (`stop(ids)`, the array overload declared first), one id, or every parked
+     * form. The broker stays usable.
+     */
     stop(ids: readonly string[]): boolean;
     stop(id: string): boolean;
     stop(): void;
+    /**
+     * Tears the broker down — abandons every parked form, cancels every deadline, then destroys the
+     * emitter. Idempotent.
+     */
     destroy(): void;
 }
 
@@ -1077,9 +1139,9 @@ export declare interface PromptOptions {
 }
 
 /**
- * Names one styling slot a rendered field paints through — the semantic axis of a {@link PromptTheme}. A
- * role says what a fragment MEANS; the theme decides what that meaning looks like, so a consumer
- * re-maps styled output by naming roles rather than reimplementing a renderer.
+ * Names one styling slot a rendered field paints through — the semantic axis of a
+ * {@link PromptTheme}. A role says what a fragment means; the theme decides what that meaning looks
+ * like, so a consumer re-maps styled output by naming roles rather than reimplementing a renderer.
  *
  * @remarks
  * - `question` — the leading mark on an active field's line.
@@ -1107,9 +1169,10 @@ export declare type PromptRole = 'question' | 'pointer' | 'message' | 'content'
 export declare type PromptStatus = 'active' | 'submit' | 'cancel';
 
 /**
- * Represents the result of one reducer step — the next `state`, the rendered `view`, the `status`, and, on
- * `submit`, the resolved `value`. The whole contract between a pure reducer and the impure driver:
- * the driver applies the next `state`, writes the `view`, and reads `value` on `submit`.
+ * Represents the result of one reducer step — the next `state`, the rendered `view`, the `status`,
+ * and, on `submit` alone, the candidate `value`. The whole contract between a pure reducer and the
+ * impure driver: the driver applies the next `state`, writes the `view`, and reads `value` on
+ * `submit`.
  *
  * @typeParam T - The value this field resolves to, as its control admits it.
  * @typeParam S - The reducer's concrete state shape, carried directly so `state` stays precisely
@@ -1120,7 +1183,7 @@ export declare type PromptStatus = 'active' | 'submit' | 'cancel';
  *   is the final state.
  * - `view` — the styled string to render now, possibly multi-line. On a refused `submit` it carries
  *   the failure; the driver re-renders it each step.
- * - `value` — present ONLY on a `submit` step.
+ * - `value` — present only on a `submit` step.
  */
 export declare interface PromptStep<T, S> {
     readonly state: S;
@@ -1130,9 +1193,9 @@ export declare interface PromptStep<T, S> {
 }
 
 /**
- * Represents a resolved PRESENTATION — the glyph for every {@link PromptIcon} and the console {@link Style}
- * for every {@link PromptRole}. Plain JSON data with no functions, so it crosses the wire with the
- * form it decorates. Built by {@link import('./helpers.js').createPromptTheme}.
+ * Represents a resolved presentation — the glyph for every {@link PromptIcon} and the console
+ * {@link Style} for every {@link PromptRole}. Plain JSON data with no functions, so it crosses the
+ * wire with the form it decorates. Built by {@link import('./helpers.js').createPromptTheme}.
  *
  * @remarks
  * A role's value is the console module's own {@link Style} — the one style model the whole console
@@ -1147,8 +1210,8 @@ export declare interface PromptTheme {
 }
 
 /**
- * Represents the PARTIAL {@link PromptTheme} an option bag carries — every icon and every role is optional,
- * and {@link import('./helpers.js').createPromptTheme} merges what is supplied over
+ * Represents the partial {@link PromptTheme} an option bag carries — every icon and every role is
+ * optional, and {@link import('./helpers.js').createPromptTheme} merges what is supplied over
  * {@link import('./constants.js').DEFAULT_PROMPT_THEME} leaf by leaf. Supplying one icon or one
  * role leaves every other slot at its default.
  */
@@ -1183,8 +1246,8 @@ export declare function reduceConfirm(state: ConfirmState, key: KeyEvent): Promp
 /**
  * Advances an editor prompt by one {@link KeyEvent} — the pure `(state, key) → PromptStep<string>`
  * reducer. Printable characters extend the current line; backspace shrinks it; return commits the
- * current line and starts a fresh one; ctrl-d FINISHES (joining all lines, falling back to the
- * default when empty); ctrl-c cancels. The form validates the candidate after the driver fills it.
+ * current line and starts a fresh one; ctrl-d finishes, joining every line and falling back to the
+ * default when empty; ctrl-c cancels. The form validates the candidate after the driver fills it.
  *
  * @param state - The editor field's current reducer state
  * @param key - The decoded keypress to apply
@@ -1216,7 +1279,7 @@ export declare function reducePassword(state: PasswordState, key: KeyEvent): Pro
 
 /**
  * Advances a select prompt by one {@link KeyEvent} — the pure `(state, key) → PromptStep<string>`
- * reducer. `up` / `down` (and `k` / `j`) move the focus, WRAPPING at the ends; return submits the
+ * reducer. `up` / `down` (and `k` / `j`) move the focus, wrapping at the ends; return submits the
  * focused choice's `value`; ctrl-c cancels. An empty choice list can never submit (a higher layer
  * guards against it); any other key is ignored.
  *
@@ -1227,7 +1290,8 @@ export declare function reducePassword(state: PasswordState, key: KeyEvent): Pro
 export declare function reduceSelect(state: SelectState, key: KeyEvent): PromptStep<string, SelectState>;
 
 /**
- * Renders a checkbox-field key state as a multi-line styled view.
+ * Renders a checkbox-field reducer state as a multi-line styled view — one box per choice, and the
+ * selected count beneath them.
  *
  * @param state - The checkbox field's current reducer state
  * @returns The rendered view — the header, one box per choice, and the selected count
@@ -1235,7 +1299,8 @@ export declare function reduceSelect(state: SelectState, key: KeyEvent): PromptS
 export declare function renderCheckboxView(state: CheckboxState): string;
 
 /**
- * Renders a confirm-field key state as a styled view. The selected role paints the default letter.
+ * Renders a confirm-field reducer state as a styled view — the header and the yes/no group, with
+ * the default letter capitalized and painted by the `selected` role.
  *
  * @param state - The confirm field's current reducer state
  * @returns The rendered view — the header and the yes/no group with the default capitalized
@@ -1243,7 +1308,8 @@ export declare function renderCheckboxView(state: CheckboxState): string;
 export declare function renderConfirmView(state: ConfirmState): string;
 
 /**
- * Renders an editor-field key state as a multi-line styled view with its finish hint.
+ * Renders an editor-field reducer state as a multi-line styled view — the finish hint, the
+ * committed lines, and the line in progress.
  *
  * @param state - The editor field's current reducer state
  * @returns The rendered view — the hinted header, the committed lines, and the line in progress
@@ -1251,7 +1317,8 @@ export declare function renderConfirmView(state: ConfirmState): string;
 export declare function renderEditorView(state: EditorState): string;
 
 /**
- * Renders the styled failure line (`✖ message`) a form driver appends for a refused field.
+ * Renders the styled failure line (`✖ message`) a form driver writes for each refused field before
+ * it asks that field again.
  *
  * @param styler - The console styler that renders each role
  * @param theme - The resolved prompt theme
@@ -1273,7 +1340,8 @@ export declare function renderErrorLine(styler: StylerInterface, theme: PromptTh
 export declare function renderHintedHeader(styler: StylerInterface, theme: PromptTheme, message: string, hint?: string): string;
 
 /**
- * Renders a text-field key state as a styled view.
+ * Renders a text-field reducer state as a styled view — the header, the pointer, and the typed
+ * value, or the default shown as a hint while nothing is typed.
  *
  * @param state - The text field's current reducer state
  * @returns The rendered single-line view — header, pointer, and the typed value or the default
@@ -1281,7 +1349,8 @@ export declare function renderHintedHeader(styler: StylerInterface, theme: Promp
 export declare function renderInputView(state: InputState): string;
 
 /**
- * Renders a password-field key state as a styled view.
+ * Renders a password-field reducer state as a styled view, with the value replaced by the mask
+ * repeated so the secret is never echoed.
  *
  * @param state - The password field's current reducer state
  * @returns The rendered view, with the mask repeated in place of the typed value
@@ -1300,7 +1369,8 @@ export declare function renderPasswordView(state: PasswordState): string;
 export declare function renderPromptHeader(styler: StylerInterface, theme: PromptTheme, message: string): string;
 
 /**
- * Renders a select-field key state as a multi-line styled view.
+ * Renders a select-field reducer state as a multi-line styled view — one row per choice, with the
+ * focused row marked and its help shown.
  *
  * @param state - The select field's current reducer state
  * @returns The rendered view — the header, then one row per choice with the focused row marked
@@ -1336,7 +1406,8 @@ export declare const RETURN: string;
 export declare function sanitizeDisplayText(text: string): string;
 
 /**
- * Sanitizes every terminal-readable string in a parsed form schema.
+ * Sanitizes every terminal-readable string in a parsed form schema, keeping every identity and
+ * answer string verbatim and dropping field metadata.
  *
  * @remarks
  * Display strings pass through {@link sanitizeDisplayText}: labels, help, placeholders, masks,
@@ -1368,7 +1439,8 @@ export declare function sanitizeSchema(schema: FormSchema): FormSchema;
 export declare function sanitizeThemeIcons(theme: PromptThemeOptions): PromptThemeOptions;
 
 /**
- * Represents the immutable state a select field's reducer carries.
+ * Represents the immutable state a select field's reducer carries — the choices the list offers and
+ * the index the cursor sits on.
  *
  * @remarks
  * - `message` — the sanitized label the header renders.
@@ -1385,10 +1457,11 @@ export declare interface SelectState {
 }
 
 /**
- * Holds the exact escape SEQUENCE → canonical key NAME table {@link import('./helpers.js').parseKey}
- * consults for the navigation / editing keys. Covers BOTH the CSI form (`ESC[A`…) and the SS3
- * form (`ESCOA`…) of the arrows, plus the `home` / `end` / `delete` CSI sequences (with
- * their numeric-tilde variants). The source of truth for the multi-byte key decode; frozen.
+ * Holds the exact escape sequence to canonical key name table
+ * {@link import('./helpers.js').parseKey} consults for the navigation and editing keys. Covers the
+ * CSI form (`ESC[A`…) and the SS3 form (`ESCOA`…) of the arrows, plus the `home` / `end` / `delete`
+ * CSI sequences with their numeric-tilde variants. The source of truth for the multi-byte key
+ * decode; frozen.
  *
  * @remarks
  * Terminals disagree on these: a cursor key is `ESC[A` (normal) or `ESCOA` (application mode),
@@ -1399,14 +1472,16 @@ export declare interface SelectState {
 export declare const SEQUENCE_NAMES: Readonly<Record<string, string>>;
 
 /**
- * Serializes the {@link WireEvent} a broker or manager sends when it is going away.
+ * Serializes the `destroy` {@link WireEvent} a broker or manager sends when it is going away, which
+ * carries no payload.
  *
  * @returns The `destroy` frame, whose `data` is empty because the signal carries no payload
  */
 export declare function serializeDestroy(): WireEvent;
 
 /**
- * Serializes a parked prompt's expiry or release into a {@link WireEvent}.
+ * Serializes a parked form's expiry or release into an `expire` {@link WireEvent}, whose `data` is
+ * the JSON `{ id }` payload.
  *
  * @param id - The id of the parked form that expired or was released
  * @returns The `expire` frame, carrying the JSON-stringified `{ id }` payload as `data`
@@ -1414,7 +1489,8 @@ export declare function serializeDestroy(): WireEvent;
 export declare function serializeExpire(id: string): WireEvent;
 
 /**
- * Serializes a parked {@link PendingForm} into a {@link WireEvent}.
+ * Serializes a parked {@link PendingForm} into a `pending` {@link WireEvent}, whose frame `id` is
+ * the form's own id.
  *
  * @param form - The parked form's wire-safe record
  * @returns The `pending` frame — the JSON-stringified record as `data`, and the form's own `id`
@@ -1433,12 +1509,13 @@ export declare const SPACE = " ";
 export declare const SSE_BUFFER_LIMIT = 1048576;
 
 /**
- * Holds the SSE `event:` names the broker emits and the {@link import('./types.js').PromptClientInterface}
- * dispatches on. Frozen; the source of truth for the wire event vocabulary.
+ * Holds the SSE `event:` names the broker emits and the
+ * {@link import('./types.js').PromptClientInterface} dispatches on — `pending`, `expire`, and
+ * `destroy`. Frozen; the source of truth for the wire event vocabulary.
  *
  * @remarks
  * - `pending` — a serialized {@link import('./types.js').PendingForm} to dispatch and answer.
- * - `expire` — an `{ id }` payload: the broker expired or released a parked prompt (the client drops it).
+ * - `expire` — an `{ id }` payload: the broker expired or released a parked form (the client drops it).
  * - `destroy` — the broker is going away; the client disconnects (no auto-reconnect) but stays reusable.
  */
 export declare const SSE_EVENTS: Readonly<{
@@ -1510,15 +1587,15 @@ export declare class TerminalError extends Error {
 export declare type TerminalErrorCode = 'EXPIRE' | 'CANCEL' | 'DRIVER' | 'DEADLOCK' | 'TARGET' | 'LIMIT' | 'DESTROYED';
 
 /**
- * Declares the contract for asking a form of a human at a keyboard — one method, because a form is one
- * question however many fields it holds. The server `Terminal` implements it against a real TTY;
- * a {@link PromptClientInterface} holds one to answer forms parked elsewhere.
+ * Declares the contract for asking a form of a human at a keyboard — `ask` and nothing beside it,
+ * because a form is one question however many fields it holds. The server `Terminal` implements it
+ * against a real TTY; a {@link PromptClientInterface} holds one to answer forms parked elsewhere.
  *
  * @remarks
  * `ask` drives the form the caller passes: it walks the schema's fields in order, binds each
  * keystroke through the form's own `fill`, submits, and returns the settled values. The returned
  * promise is the form's `answer`, so a caller holding the form can await either one. Ctrl-c at an
- * interactive driver is the one exception: it rejects THIS promise with a `TerminalError` coded
+ * interactive driver is the one exception: it rejects this promise with a `TerminalError` coded
  * `CANCEL` and leaves the form `editing`, so the form's own `answer` stays pending for its owner.
  *
  * A driver never owns the form's lifetime. To interrupt an active walk, destroy the form: it
@@ -1526,28 +1603,32 @@ export declare type TerminalErrorCode = 'EXPIRE' | 'CANCEL' | 'DRIVER' | 'DEADLO
  * is the only cancellation channel, which is why this contract needs no second method.
  */
 export declare interface TerminalInterface {
+    /**
+     * Walks the given form to settlement and resolves its values. The Contract section names the
+     * ctrl-c exception.
+     */
     ask(form: FormInterface): Promise<FormValues>;
 }
 
 /**
- * Registers named {@link PromptInterface} brokers (one per endpoint), so several parties can
- * `ask` forms of each other by NAME with a `from` → `to` attribution edge on every parked form,
- * and a transitive DEADLOCK check across all in-flight asks.
+ * Registers named {@link PromptInterface} brokers, one per endpoint, so several parties can `ask`
+ * forms of each other by name with a `from` → `to` attribution edge on every parked form, and
+ * refuses `DEADLOCK` on a transitive cycle across every in-flight ask.
  *
  * @remarks
  * - **Registry.** `add(name, options?)` mints (or, if `name` is already mounted, returns the
- *   EXISTING broker UNCHANGED — idempotent, never clobbers a live/parked endpoint). Every mounted
+ *   existing broker unchanged — idempotent, never clobbers a live/parked endpoint). Every mounted
  *   broker's `pending` / `answer` / `expire` events are re-emitted on the manager, attributed by
  *   `name`.
- * - **`ask`.** The target must already be mounted via {@link add} — `ask` never auto-adds it;
+ * - **`ask`.** The target must already be mounted through {@link add} — `ask` never auto-adds it;
  *   rejects `TARGET` for an unknown `to` (listing the known names). Rejects `DEADLOCK` when parking
- *   `from → to` would close a cycle over the CURRENT in-flight edge set (walked transitively);
+ *   `from → to` would close a cycle over the current in-flight edge set (walked transitively);
  *   otherwise parks the caller's live form through the target's broker and returns that form's own
  *   `answer` promise. Edge cleanup never alters the value or rejection the caller observes.
  * - **Durable open / save.** `open(name)` restores an EMPTY broker from the `store` (parked
  *   Promises are process-bound and never resurrected); `save(name)` persists the endpoint's
  *   configured `timeout`.
- * - **Removal.** `remove` drops one endpoint, a batch (the array overload declared FIRST), or every
+ * - **Removal.** `remove` drops one endpoint, a batch (the array overload declared first), or every
  *   endpoint when called without an argument. It destroys each broker, which expires every form
  *   still parked on it. `destroy` is idempotent.
  *
@@ -1582,8 +1663,8 @@ export declare class TerminalManager implements TerminalManagerInterface {
 }
 
 /**
- * Declares the manager's event map — the name-attributed re-emission of every mounted broker's events, so a
- * caller subscribes once for ALL endpoints instead of once per broker.
+ * Declares the manager's event map — the name-attributed re-emission of every mounted broker's
+ * events, so a caller subscribes once for every endpoint instead of once per broker.
  *
  * @remarks
  * - `pending` — an endpoint parked a form; the record itself carries `from` and `to`.
@@ -1598,8 +1679,8 @@ export declare type TerminalManagerEventMap = {
 
 /**
  * Declares a registry of named {@link PromptInterface} brokers, one per endpoint, so several
- * parties (agents, tools, humans) can ask forms of each other BY NAME, attributed with a
- * `from` → `to` edge on every parked record.
+ * parties (agents, tools, humans) can ask forms of each other by name, attributed with a `from` →
+ * `to` edge on every parked record.
  *
  * @remarks
  * - **Accessors.** `terminal(name)` looks up one endpoint's broker; `terminals()` lists every
@@ -1616,26 +1697,57 @@ export declare type TerminalManagerEventMap = {
  * - **`open`** restores, or returns the live, broker for `name` from the `store`.
  * - **`save`** persists an endpoint's config snapshot; false when there is no store, or `name` is
  *   unknown.
- * - **Batch `remove`.** The array overload is declared FIRST: `remove(names)` removes every listed
+ * - **Batch `remove`.** The array overload is declared first: `remove(names)` removes every listed
  *   endpoint and reports true only when all of them were mounted; `remove(name)` removes one;
  *   `remove()` removes every endpoint without destroying the manager.
  * - **`destroy`** tears down every broker, then the manager's own emitter.
  */
 export declare interface TerminalManagerInterface {
+    /**
+     * Holds the typed emitter every mounted broker's events are re-published on, attributed by name.
+     */
     readonly emitter: EmitterInterface<TerminalManagerEventMap>;
+    /** Reports how many endpoints are mounted. */
     readonly count: number;
+    /** Looks up one endpoint's broker by name. */
     terminal(name: string): PromptInterface | undefined;
+    /** Lists every mounted broker, in insertion order. */
     terminals(): readonly PromptInterface[];
+    /**
+     * Mints, or returns unchanged, the broker for `name`. Idempotent; it never clobbers a live
+     * endpoint.
+     */
     add(name: string, options?: PromptOptions): PromptInterface;
+    /**
+     * Parks `form` from `from` to `to` and resolves with the settled values. Rejects `TARGET` or
+     * `DEADLOCK`.
+     */
     ask(from: string, to: string, form: FormInterface): Promise<FormValues>;
+    /**
+     * Lists every endpoint's parked records (`pending()`), or scopes to one endpoint (`pending(to)`).
+     */
     pending(): readonly PendingForm[];
     pending(to: string): readonly PendingForm[];
+    /**
+     * Routes an answer to the named endpoint's broker; `{ reason: 'target' }` when no endpoint
+     * carries that name.
+     */
     answer(to: string, id: string, values: FormValues): Result<FormValues, TerminalAnswerError>;
+    /**
+     * Returns the live broker for `name`, or restores an empty one from the `store`. Parked forms are
+     * never resurrected.
+     */
     open(name: string): Promise<PromptInterface | undefined>;
+    /** Persists an endpoint's config snapshot; false with no store, or an unknown name. */
     save(name: string): Promise<boolean>;
+    /**
+     * Removes a batch (`remove(names)`, the array overload declared first, true only when every name
+     * was mounted), one endpoint, or every endpoint.
+     */
     remove(names: readonly string[]): boolean;
     remove(name: string): boolean;
     remove(): void;
+    /** Tears down every broker, then the manager's own emitter. */
     destroy(): void;
 }
 
@@ -1659,9 +1771,9 @@ export declare interface TerminalManagerOptions {
 }
 
 /**
- * Represents one endpoint's persisted CONFIG snapshot — `id` is the endpoint name and `timeout` its configured
- * default. Parked forms are process-bound and are never resurrected, so `open` always restores an
- * EMPTY broker.
+ * Represents one endpoint's persisted config snapshot — `id` is the endpoint name and `timeout` its
+ * configured default. Parked forms are process-bound and are never resurrected, so `open` always
+ * restores an empty broker.
  */
 export declare interface TerminalSnapshot {
     readonly id: string;
@@ -1669,9 +1781,9 @@ export declare interface TerminalSnapshot {
 }
 
 /**
- * Represents one opaque persisted row — the shape a `TableInterface<TerminalSnapshotRow>`-backed store reads
- * and writes. `snapshot` is narrowed with {@link import('./validators.js').isTerminalSnapshot} on
- * read.
+ * Represents one opaque persisted row — the shape a table-backed store reads and writes. The store
+ * is a `TableInterface<TerminalSnapshotRow>`, and `snapshot` is narrowed with
+ * {@link import('./validators.js').isTerminalSnapshot} on read.
  */
 export declare interface TerminalSnapshotRow {
     readonly id: string;
@@ -1683,8 +1795,11 @@ export declare interface TerminalSnapshotRow {
  * Every primitive is async; deleting an absent id is a no-op.
  */
 export declare interface TerminalStoreInterface {
+    /** Resolves the snapshot stored for `id`, or `undefined` when none is. */
     get(id: string): Promise<TerminalSnapshot | undefined>;
+    /** Inserts or replaces under the snapshot's own `id`; there is no id argument. */
     set(snapshot: TerminalSnapshot): Promise<void>;
+    /** Drops a snapshot by id. An absent id is a no-op, never a throw. */
     delete(id: string): Promise<void>;
 }
 
@@ -1702,7 +1817,7 @@ export { TimerHandler_2 as TimerHandler }
 
 /**
  * Toggles `index` in a readonly index list — copy-on-write, returning the new sorted-by-insertion
- * list.
+ * list; the primitive {@link reduceCheckbox} calls.
  *
  * @param indices - The ticked indices, in tick order
  * @param index - The index to add when absent, or drop when present