@orkestrel/terminal 0.0.1

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

@@ -0,0 +1,1273 @@
+import { EmitterErrorHandler } from '@orkestrel/emitter';
+import { EmitterHooks } from '@orkestrel/emitter';
+import { EmitterInterface } from '@orkestrel/emitter';
+import { Guard } from '@orkestrel/contract';
+import { StylerInterface } from '@orkestrel/console';
+
+/** The `Accept` header value that opens the broker's SSE stream. */
+export declare const ACCEPT_EVENT_STREAM = "text/event-stream";
+
+/** Matches an alphanumeric string (letters and digits only). The `alphanumeric` rule tests against this. */
+export declare const ALPHANUMERIC_PATTERN: RegExp;
+
+/**
+ * Append a rule-backed {@link Validator} to `validators` when the rule is enabled — a `false` /
+ * `undefined` `check` is skipped, a function `check` is added verbatim (the custom override), and
+ * a primitive `check` is wrapped via {@link buildRuleValidator}. Mutates `validators` in place.
+ */
+export declare function appendRule(validators: Validator[], rule: string, check: boolean | number | string | Validator | undefined): void;
+
+/** Backspace (BS, U+0008) — Ctrl+H / some terminals' Backspace. */
+export declare const BACKSPACE: string;
+
+/** Wrap a named rule + its primitive check into a {@link Validator} (returns `true` or the rule's message). */
+export declare function buildRuleValidator(rule: string, check: boolean | number | string): Validator;
+
+/** A choice item in a {@link CheckboxOptions} prompt — a {@link PromptChoice} plus an optional initial `checked` state. */
+export declare interface CheckboxChoice {
+    readonly name: string;
+    readonly value: string;
+    readonly description?: string;
+    readonly checked?: boolean;
+}
+
+/**
+ * Options for a multi-selection {@link import('./helpers.js').checkboxReduce} prompt.
+ *
+ * @remarks
+ * `choices` accepts bare strings or full {@link CheckboxChoice} objects (with an optional
+ * initial `checked`); {@link import('./helpers.js').createCheckboxState} normalizes them.
+ * `min` / `max` gate submission — a submit with fewer than `min` or more than `max` selected
+ * is rejected (the prompt stays active with the reason in the view).
+ */
+export declare interface CheckboxOptions {
+    readonly message: string;
+    readonly choices: readonly (string | CheckboxChoice)[];
+    readonly min?: number;
+    readonly max?: number;
+    readonly styler?: StylerInterface;
+}
+
+/**
+ * Advance a checkbox prompt by one {@link KeyEvent} — the pure
+ * `(state, key) → PromptStep<readonly string[]>` reducer. `up` / `down` (and `k` / `j`) move the
+ * focus (wrapping); `space` toggles the focused index in the checked set; return submits the
+ * checked values in CHOICE order — gated by `min` / `max` (an out-of-range count stays active with
+ * the reason in the view); ctrl-c cancels.
+ */
+export declare function checkboxReduce(state: CheckboxState, key: KeyEvent): PromptStep<readonly string[], CheckboxState>;
+
+/**
+ * The immutable state of a checkbox prompt — the normalized choices, the styler, the `focused`
+ * index, the set of `checked` indices, the optional `min` / `max` gate, and the current `error`.
+ *
+ * @remarks
+ * Built by {@link import('./helpers.js').createCheckboxState}; advanced by
+ * {@link import('./helpers.js').checkboxReduce}. `up` / `down` move `focus` (wrapping); `space`
+ * toggles the focused index in `checked`; `return` submits the checked values in choice order
+ * (rejected, with `error`, when the count is outside `[min, max]`). `checked` is modelled as a
+ * readonly index array (plain JSON data, copy-on-write — no `Set` to clone).
+ */
+export declare interface CheckboxState {
+    readonly message: string;
+    readonly choices: readonly CheckboxChoice[];
+    readonly styler: StylerInterface;
+    readonly focused: number;
+    readonly checked: readonly number[];
+    readonly min?: number;
+    readonly max?: number;
+    readonly error?: string;
+}
+
+/** Render a {@link CheckboxState} as a MULTI-LINE styled view — the header, one box per choice (focused + checked marked), a count, and any error. */
+export declare function checkboxView(state: CheckboxState): string;
+
+/**
+ * Compose several {@link Validator}s into ONE short-circuiting validator — it runs them in order
+ * and returns the FIRST error message, or `true` when all pass. The empty composition always
+ * passes.
+ */
+export declare function composeValidators(...validators: Validator[]): Validator;
+
+/** Options for a yes/no {@link import('./helpers.js').confirmReduce} confirmation prompt. */
+export declare interface ConfirmOptions {
+    readonly message: string;
+    readonly default?: boolean;
+    readonly styler?: StylerInterface;
+}
+
+/**
+ * Advance a confirm prompt by one {@link KeyEvent} — the pure `(state, key) → PromptStep<boolean>`
+ * reducer. `y` / `Y` submits `true`, `n` / `N` submits `false`, return on an empty line submits
+ * the `default`, ctrl-c cancels; any other key is ignored (stays active).
+ */
+export declare function confirmReduce(state: ConfirmState, key: KeyEvent): PromptStep<boolean, ConfirmState>;
+
+/**
+ * The immutable state of a confirm prompt — its message, the default answer, and the styler.
+ *
+ * @remarks
+ * Built by {@link import('./helpers.js').createConfirmState}; advanced by
+ * {@link import('./helpers.js').confirmReduce}. `y` / `Y` submits `true`, `n` / `N` submits
+ * `false`, and `enter` takes the `default` (rendered with the active letter capitalized in the
+ * `(Y/n)` hint).
+ */
+export declare interface ConfirmState {
+    readonly message: string;
+    readonly default: boolean;
+    readonly styler: StylerInterface;
+}
+
+/** Render a {@link ConfirmState} as a styled view — the header plus a `(Y/n)` hint with the default letter emphasized. */
+export declare function confirmView(state: ConfirmState): string;
+
+/**
+ * The single control BYTE → key descriptor table {@link import('./helpers.js').parseKey}
+ * consults for the one-byte keys. Each entry carries the canonical `name` and whether it is a
+ * `ctrl` combination. The source of truth for the single-byte key decode; frozen.
+ *
+ * @remarks
+ * `return` / `newline` map to `return` (one canonical Enter name); `delete` / `backspace` both
+ * map to `backspace` (the two Backspace bytes); the Ctrl combos (`c` / `d` / `u` / `a` / `e`)
+ * carry `ctrl: true` so a reducer can match `key.ctrl && key.name === 'c'`. `escape` / `tab` /
+ * `space` are plain named keys.
+ */
+export declare const CONTROL_NAMES: Readonly<Record<string, {
+    readonly name: string;
+    readonly ctrl: boolean;
+}>>;
+
+/** Build the initial {@link CheckboxState} from {@link CheckboxOptions} — normalizing choices, seeding the checked set, carrying min/max. */
+export declare function createCheckboxState(options: CheckboxOptions): CheckboxState;
+
+/** Build the initial {@link ConfirmState} from {@link ConfirmOptions} — defaulting the answer to `false`. */
+export declare function createConfirmState(options: ConfirmOptions): ConfirmState;
+
+/** Build the initial {@link EditorState} from {@link EditorOptions} — resolving the validator + styler, seeding empty lines. */
+export declare function createEditorState(options: EditorOptions): EditorState;
+
+/** Build the initial {@link InputState} from {@link InputOptions} — resolving the validator + styler, seeding an empty value. */
+export declare function createInputState(options: InputOptions): InputState;
+
+/** Build the initial {@link PasswordState} from {@link PasswordOptions} — resolving the validator + styler + mask. */
+export declare function createPasswordState(options: PasswordOptions): PasswordState;
+
+/**
+ * Create the headless prompt {@link PromptInterface} BROKER — it parks each prompt call as a
+ * pending prompt and resolves it when {@link PromptInterface.answer} arrives (or rejects on
+ * timeout). The tri-surface's headless arm: subscribe `emitter.on('pending', …)` to forward each
+ * prompt to whoever can answer (an SSE transport, a remote terminal), then route the answer back
+ * through `answer(id, value)`.
+ *
+ * @param options - See {@link PromptOptions}
+ * @returns A {@link PromptInterface}
+ *
+ * @remarks
+ * - **Park-as-Promise.** `await prompt.input({ message })` blocks until `answer(id, value)` accepts
+ *   a matching value; the value is validated (text forms) and type-checked to the form first.
+ * - **Timeout → expire → reject (deterministic).** An unanswered prompt expires after
+ *   `options.timeout` (default {@link import('./constants.js').DEFAULT_PROMPT_TIMEOUT_MS}) and its
+ *   Promise rejects with a {@link import('./errors.js').TerminalError}; inject `options.timer` to
+ *   drive expiry without real time.
+ *
+ * @example
+ * ```ts
+ * import { createPrompt } from '@src/core'
+ *
+ * const prompt = createPrompt()
+ * prompt.emitter.on('pending', (pending) => send(pending)) // forward to a remote client
+ * const name = await prompt.input({ message: 'Your name', validate: { required: true } })
+ * ```
+ */
+export declare function createPrompt(options?: PromptOptions): PromptInterface;
+
+/**
+ * Create the SSE prompt {@link PromptClientInterface} BRIDGE — it connects to a remote broker's SSE
+ * endpoint, dispatches each received prompt to a LOCAL {@link import('./types.js').PromptFormInterface}
+ * terminal (so a human at this machine answers a prompt parked elsewhere), and POSTs the answer
+ * back. Universal — `fetch` / SSE are web-standard.
+ *
+ * @param options - See {@link PromptClientOptions} (`url` + `terminal` required)
+ * @returns A {@link PromptClientInterface}
+ *
+ * @remarks
+ * - **Connect + reconnect.** `await client.connect()` streams remote prompts until the stream
+ *   ends; it reconnects with the `delay` backoff unless `reconnect` is `false` / the client was
+ *   `destroy`ed. Inject `options.fetch` (a scripted `fetch`) and `options.timer` to drive it
+ *   deterministically in tests — no real network.
+ * - **§14 wire narrowing.** Every decoded prompt is guard-narrowed before dispatch (never an `as`).
+ *
+ * @example
+ * ```ts
+ * import { createPromptClient } from '@src/core'
+ *
+ * const client = createPromptClient({ url: 'http://host/prompts', terminal })
+ * await client.connect()
+ * ```
+ */
+export declare function createPromptClient(options: PromptClientOptions): PromptClientInterface;
+
+/** Build the initial {@link SelectState} from {@link SelectOptions} — normalizing choices and pre-focusing the default. */
+export declare function createSelectState(options: SelectOptions): SelectState;
+
+/** Ctrl+A (SOH, U+0001) — move to start of line. */
+export declare const CTRL_A: string;
+
+/** Ctrl+C (ETX, U+0003) — interrupt / cancel. */
+export declare const CTRL_C: string;
+
+/** Ctrl+D (EOT, U+0004) — end-of-transmission / finish (the editor's commit key). */
+export declare const CTRL_D: string;
+
+/** Ctrl+E (ENQ, U+0005) — move to end of line. */
+export declare const CTRL_E: string;
+
+/** Ctrl+U (NAK, U+0015) — clear the current line. */
+export declare const CTRL_U: string;
+
+/** The default mask glyph a {@link import('./types.js').PasswordState} renders each input character as — `*`. */
+export declare const DEFAULT_MASK = "*";
+
+/** How long (ms) the {@link import('./types.js').PromptInterface} broker parks an unanswered prompt before it expires — 5 minutes. */
+export declare const DEFAULT_PROMPT_TIMEOUT_MS = 300000;
+
+/** How long (ms) the {@link import('./types.js').PromptClientInterface} waits before each reconnect attempt — 2 seconds. */
+export declare const DEFAULT_RECONNECT_DELAY_MS = 2000;
+
+/**
+ * The default {@link import('./types.js').TimerHandler} — a thin host `setTimeout` / `clearTimeout`
+ * wrapper that arms `callback` after `ms` and returns a {@link TimerCancel}. The deadline seam
+ * behind both the {@link import('./Prompt.js').Prompt} broker (its expiry) and the
+ * {@link import('./PromptClient.js').PromptClient} (its reconnect backoff); a test injects a
+ * deterministic timer instead, so neither entity touches real time.
+ */
+export declare function defaultTimer(callback: () => void, ms: number): TimerCancel;
+
+/** Delete (DEL, U+007F) — the usual Backspace byte on a Unix TTY. */
+export declare const DELETE: string;
+
+/**
+ * Dispatch a {@link PendingPrompt} to the matching {@link PromptFormInterface} method — the bridge
+ * step a {@link PromptClient} runs to drive a LOCAL terminal with a prompt issued elsewhere.
+ * Reconstructs typed options from the wire-safe {@link PendingPrompt.options} (every field
+ * §14-narrowed, never an `as`; the validator rebuilt from rules via {@link reconstructValidationRules}),
+ * then calls the matching prompt form and returns its resolved value.
+ *
+ * @param terminal - The local {@link PromptFormInterface} to drive
+ * @param pending - The decoded pending prompt to dispatch
+ * @returns The prompt's resolved value (a `string` / `boolean` / `readonly string[]` per form)
+ */
+export declare function dispatchPendingPrompt(terminal: PromptFormInterface, pending: PendingPrompt): Promise<string | boolean | readonly string[]>;
+
+/**
+ * Apply 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. Returns the new buffer, or `undefined` when the
+ * key does not edit the line (so the caller can leave the state untouched).
+ */
+export declare function editLine(value: string, key: KeyEvent): string | undefined;
+
+/** Options for a multi-line {@link import('./helpers.js').editorReduce} editor prompt (terminated by ctrl-d). */
+export declare interface EditorOptions {
+    readonly message: string;
+    readonly default?: string;
+    readonly validate?: Validator | ValidationRules;
+    readonly styler?: StylerInterface;
+}
+
+/**
+ * Advance 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) through the validator; ctrl-c cancels. An invalid finish stays active with
+ * the error.
+ */
+export declare function editorReduce(state: EditorState, key: KeyEvent): PromptStep<string, EditorState>;
+
+/**
+ * The immutable state of an editor prompt — the committed `lines`, the in-progress `current`
+ * line, plus the resolved validator + styler, the default, and the current `error`.
+ *
+ * @remarks
+ * Built by {@link import('./helpers.js').createEditorState}; advanced by
+ * {@link import('./helpers.js').editorReduce}. A printable key appends to `current`; `return`
+ * commits `current` to `lines` and starts a fresh line; ctrl-d finishes, submitting
+ * `lines + current` joined by newlines (or `default` when empty). The whole text is validated
+ * on finish.
+ */
+export declare interface EditorState {
+    readonly message: string;
+    readonly default: string;
+    readonly validator: Validator;
+    readonly styler: StylerInterface;
+    readonly lines: readonly string[];
+    readonly current: string;
+    readonly error?: string;
+}
+
+/** Render an {@link EditorState} as a MULTI-LINE styled view — the header (with a Ctrl+D hint), the committed lines, the in-progress line, and any error. */
+export declare function editorView(state: EditorState): string;
+
+/** Matches an email address — a non-trivial `local@domain.tld` shape. The `email` rule tests against this. */
+export declare const EMAIL_PATTERN: RegExp;
+
+/** The styled error line (`✖ message`) — appended beneath a prompt view when the last submit failed validation. */
+export declare function errorLine(styler: StylerInterface, message: string): string;
+
+/** Escape (ESC, U+001B) — the lone byte, and the lead byte of every CSI / SS3 sequence. */
+export declare const ESCAPE: string;
+
+/**
+ * Evaluate ONE built-in validation rule against `input`, returning its error message when the
+ * rule fails or `undefined` when it passes. The atomic check {@link buildRuleValidator} wraps
+ * into a {@link Validator}. Pure.
+ *
+ * @remarks
+ * A function `check` is the custom-override path: it is called and its `true` ⇒ pass, a string
+ * ⇒ that message, anything else ⇒ the generic {@link RULE_MESSAGES.invalid}. A primitive `check`
+ * runs the named built-in: `required` (non-empty trimmed), `minimum` / `maximum` (length
+ * bounds, the message interpolated with the count), `pattern` (a regex source), and the
+ * `email` / `url` / `numeric` / `integer` / `alphanumeric` pattern tests.
+ *
+ * @param rule - The rule name (`'required'`, `'minimum'`, …)
+ * @param check - The configured value (a primitive toggle / bound / pattern, or a custom {@link Validator})
+ * @param input - The input string to test
+ * @returns The error message when the rule fails, else `undefined`
+ */
+export declare function evaluateRule(rule: string, check: boolean | number | string | Validator, input: string): string | undefined;
+
+/**
+ * A minimal `fetch` — the subset of the global `fetch` the {@link PromptClient} uses (open the
+ * SSE stream, POST an answer). Injected so a test drives the client with a controlled
+ * `Response` (a scripted SSE `ReadableStream`) instead of a real network.
+ */
+export declare type FetchHandler = (input: string, init?: FetchInit) => Promise<Response>;
+
+/**
+ * The request init the {@link PromptClient} passes to its {@link FetchHandler} — the `fetch`
+ * `RequestInit` fields it actually sets (method / headers / body / abort signal).
+ */
+export declare interface FetchInit {
+    readonly method?: string;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly body?: string;
+    readonly signal?: AbortSignal;
+}
+
+/** The min/max gate for a checkbox submit — the rejection message when `count` is out of range, else `undefined`. */
+export declare function gateSelection(count: number, min?: number, max?: number): string | undefined;
+
+/** The default {@link import('./types.js').FetchHandler} — the global `fetch`, adapted to the minimal injected shape the {@link import('./PromptClient.js').PromptClient} uses. */
+export declare function globalFetch(input: string, init?: FetchInit): Promise<Response>;
+
+/** The auth-token request header the {@link import('./types.js').PromptClient} sends when a `token` is configured. */
+export declare const HEADER_TOKEN = "x-orkestrel-token";
+
+/** Options for a single-line text {@link import('./helpers.js').inputReduce} prompt. */
+export declare interface InputOptions {
+    readonly message: string;
+    readonly default?: string;
+    readonly validate?: Validator | ValidationRules;
+    readonly styler?: StylerInterface;
+}
+
+/**
+ * Advance an input prompt by one {@link KeyEvent} — the pure `(state, key) → PromptStep<string>`
+ * reducer. Printable characters extend the value; backspace shrinks it; ctrl-u clears it; ctrl-c
+ * cancels; return submits (the empty line falls back to the default) through the validator — an
+ * invalid submit stays active with the error in the view.
+ */
+export declare function inputReduce(state: InputState, key: KeyEvent): PromptStep<string, InputState>;
+
+/**
+ * The immutable state of a text input prompt — its options, the resolved validator + styler,
+ * the accumulated `value`, and the current `error` (when the last submit failed validation).
+ *
+ * @remarks
+ * Built by {@link import('./helpers.js').createInputState}; advanced by
+ * {@link import('./helpers.js').inputReduce}. `value` accumulates printable characters and
+ * shrinks on backspace; `error` holds the validation message shown in the view after a
+ * rejected submit (cleared on the next keystroke).
+ */
+export declare interface InputState {
+    readonly message: string;
+    readonly default: string;
+    readonly validator: Validator;
+    readonly styler: StylerInterface;
+    readonly value: string;
+    readonly error?: string;
+}
+
+/** Render an {@link InputState} as a styled view — the header, the typed value (or dimmed default hint), and any error. */
+export declare function inputView(state: InputState): string;
+
+/** Matches an integer (optional sign). The `integer` rule tests against this. */
+export declare const INTEGER_PATTERN: RegExp;
+
+/**
+ * Whether a caught value is an `AbortError` — the {@link import('./PromptClient.js').PromptClient}
+ * distinguishes a deliberate `disconnect` / teardown (an aborted `fetch`) from a real fault, so it
+ * exits its connect loop quietly instead of emitting `error` / reconnecting.
+ */
+export declare function isAbortError(error: unknown): boolean;
+
+/** Narrow an unknown value to a {@link CheckboxChoice} — the `recordOf` shape inlined so no non-exported member lingers (§5). */
+export declare function isCheckboxChoice(value: unknown): value is CheckboxChoice;
+
+/**
+ * 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.
+ *
+ * @remarks
+ * A loopback host (`localhost`, `127.0.0.1`, `[::1]`) over `http://` is exempt (local
+ * development has no network hop to eavesdrop on); every other `http://` host is insecure.
+ * An `https://` URL (or any non-`http://` scheme) is never flagged.
+ *
+ * @param url - The candidate endpoint URL
+ * @returns `true` when `url` is a non-loopback `http://` endpoint
+ *
+ * @example
+ * ```ts
+ * isInsecureRemote('http://example.com')     // true
+ * isInsecureRemote('http://localhost:3000')  // false
+ * isInsecureRemote('https://example.com')    // false
+ * ```
+ */
+export declare function isInsecureRemote(url: string): boolean;
+
+/**
+ * Narrow an unknown wire value to a {@link PendingPrompt} — the §14 guard a {@link PromptClient}
+ * applies to each decoded SSE `pending` payload before dispatching it (never an `as`).
+ */
+export declare const isPendingPrompt: Guard<PendingPrompt>;
+
+/** Narrow an unknown value to a {@link PendingPromptStatus}. */
+export declare const isPendingPromptStatus: Guard<PendingPromptStatus>;
+
+/** Whether a single character is a printable (non-control) character — used by {@link parseKey}'s char fallback. */
+export declare function isPrintable(character: string): boolean;
+
+/** Narrow an unknown value to a {@link PromptChoice} — the `recordOf` shape inlined so no non-exported member lingers (§5). */
+export declare function isPromptChoice(value: unknown): value is PromptChoice;
+
+/** Narrow an unknown value to a {@link PromptType} — one of the six prompt forms. */
+export declare const isPromptType: Guard<PromptType>;
+
+/**
+ * Narrow an unknown caught value to a {@link TerminalError}.
+ *
+ * @param value - The value to test (typically a `catch` binding or a rejected prompt call)
+ * @returns `true` when `value` is a {@link TerminalError}
+ *
+ * @example
+ * ```ts
+ * try {
+ * 	const name = await prompt.input({ message: 'Your name' })
+ * } catch (error) {
+ * 	if (isTerminalError(error) && error.code === 'EXPIRE') retryLater()
+ * }
+ * ```
+ */
+export declare function isTerminalError(value: unknown): value is TerminalError;
+
+/**
+ * The Control Sequence Introducer lead (`ESC[`) for the navigation keys — the prefix of the
+ * arrow / home / end / delete sequences {@link SEQUENCE_NAMES} is keyed by. Named `KEY_CSI`
+ * (not `CSI`) so it never collides with the console module's SGR `CSI` (both barrel through
+ * `@src/core`).
+ */
+export declare const KEY_CSI: string;
+
+/** The Single Shift Three lead (`ESCO`) — the alternate arrow-key prefix some terminals emit (`ESC O A`). */
+export declare const KEY_SS3: string;
+
+/**
+ * One decoded keypress — the universal, TTY-agnostic representation of a single key, the
+ * output of {@link import('./helpers.js').parseKey}. A reducer reads `name` (and the
+ * modifier flags) to decide its transition; the raw `sequence` is preserved so a printable
+ * character round-trips and an unknown escape is never lost.
+ *
+ * @remarks
+ * - `name` — the canonical key name: a control / navigation key (`return`, `backspace`,
+ *   `tab`, `escape`, `up` / `down` / `left` / `right`, `space`, `home`, `end`, `delete`),
+ *   a named ctrl combo (`c` with `ctrl` true for ctrl-c, likewise `d` / `u` / `a` / `e`),
+ *   or the printable character itself (`'a'`, `'7'`, `'?'`). An UNRECOGNIZED sequence
+ *   yields `name: ''` (empty) — never a throw (the decoder is total).
+ * - `sequence` — the exact input bytes as a string (a `Uint8Array` is decoded UTF-8). The
+ *   driver writes this verbatim for a printable key; a reducer that needs the literal char
+ *   reads it.
+ * - `ctrl` / `meta` / `shift` — the modifier flags. `ctrl` is `true` for a C0 control byte
+ *   (ctrl-c / ctrl-d / ctrl-u / ctrl-a / ctrl-e and the like); `meta` is `true` for an
+ *   ESC-prefixed (Alt) sequence; `shift` is `true` for an uppercase-letter printable.
+ */
+export declare interface KeyEvent {
+    readonly name: string;
+    readonly sequence: string;
+    readonly ctrl: boolean;
+    readonly meta: boolean;
+    readonly shift: boolean;
+}
+
+/** Line feed (`\n`, U+000A) — Enter on some terminals / pasted input. */
+export declare const NEWLINE: string;
+
+/** Normalize a checkbox choice input into a full {@link CheckboxChoice} (a bare string becomes both name and value). */
+export declare function normalizeCheckboxChoice(choice: string | CheckboxChoice): CheckboxChoice;
+
+/** Normalize a select choice input into a full {@link PromptChoice} (a bare string becomes both name and value). */
+export declare function normalizeChoice(choice: string | PromptChoice): PromptChoice;
+
+/** Matches a numeric value (integer or decimal, optional sign). The `numeric` rule tests against this. */
+export declare const NUMERIC_PATTERN: RegExp;
+
+/**
+ * One parked prompt's runtime state inside the broker — the wire-safe {@link PendingPrompt} record
+ * it exposes, plus the live machinery that settles that prompt's Promise. `respond` is the per-form
+ * gate-and-resolve closure: it validates + type-checks an answer and (on accept) resolves the parked
+ * Promise, returning whether it accepted; it closes over the form's precisely-typed `resolve`, so no
+ * per-form generic leaks into `answer`. `expire` rejects the parked Promise; `cancel` clears the
+ * injected expiry timer ({@link TimerCancel}).
+ */
+export declare interface Parked {
+    readonly prompt: PendingPrompt;
+    readonly respond: (value: unknown) => unknown;
+    readonly expire: () => void;
+    readonly cancel: TimerCancel;
+}
+
+/**
+ * Decode 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
+ * ({@link CONTROL_NAMES}) and escape sequences ({@link SEQUENCE_NAMES}), falling back to a
+ * single printable character. An unrecognized sequence yields `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`) 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
+ *   `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
+ *   `shift` set when it is an uppercase letter. A multi-code-point printable (an emoji, a pasted
+ *   run) keeps its first code point as the name and the whole input as `sequence`.
+ * - **Unknown.** Anything else (an unrecognized escape, an empty input) yields `name: ''` —
+ *   total, so the driver never crashes on a stray byte.
+ *
+ * @param input - The raw keypress bytes, as a string or `Uint8Array`
+ * @returns The decoded {@link KeyEvent}
+ *
+ * @example
+ * ```ts
+ * parseKey('\r')        // { name: 'return', sequence: '\r', ctrl: false, meta: false, shift: false }
+ * parseKey('\x1b[A')    // { name: 'up', sequence: '\x1b[A', ctrl: false, meta: true, shift: false }
+ * parseKey('A')         // { name: 'A', sequence: 'A', ctrl: false, meta: false, shift: true }
+ * parseKey('\x03')      // { name: 'c', sequence: '\x03', ctrl: true, meta: false, shift: false }
+ * ```
+ */
+export declare function parseKey(input: string | Uint8Array): KeyEvent;
+
+/**
+ * Parse a JSON wire string TOTAL — a malformed / empty payload yields `undefined` (the caller's
+ * guard then rejects it), never a throw. The {@link import('./PromptClient.js').PromptClient}
+ * decodes every SSE `data` field through this before §14-narrowing it.
+ */
+export declare function parseWireJSON(text: string): unknown;
+
+/** The always-passing {@link Validator} — the resolved validator when no rules were supplied. */
+export declare function passing(_input: string): true;
+
+/** Options for a masked password {@link import('./helpers.js').passwordReduce} prompt. */
+export declare interface PasswordOptions {
+    readonly message: string;
+    readonly mask?: string;
+    readonly validate?: Validator | ValidationRules;
+    readonly styler?: StylerInterface;
+}
+
+/**
+ * Advance a password prompt by one {@link KeyEvent} — the pure `(state, key) → PromptStep<string>`
+ * reducer. Identical line-editing to {@link inputReduce} (printable extends, backspace shrinks,
+ * ctrl-u clears, ctrl-c cancels) but the view masks the value; return submits through the
+ * validator (no default fallback — a password has no echoed default).
+ */
+export declare function passwordReduce(state: PasswordState, key: KeyEvent): PromptStep<string, PasswordState>;
+
+/**
+ * The immutable state of a password prompt — like {@link InputState} but with a `mask`
+ * character the view renders in place of each input character.
+ *
+ * @remarks
+ * Built by {@link import('./helpers.js').createPasswordState}; advanced by
+ * {@link import('./helpers.js').passwordReduce}. The `value` is the real (unmasked) input;
+ * the view shows `mask` repeated `value.length` times.
+ */
+export declare interface PasswordState {
+    readonly message: string;
+    readonly mask: string;
+    readonly validator: Validator;
+    readonly styler: StylerInterface;
+    readonly value: string;
+    readonly error?: string;
+}
+
+/** Render a {@link PasswordState} as a styled view — the header, the value masked to `mask` repeated, and any error. */
+export declare function passwordView(state: PasswordState): string;
+
+/**
+ * One prompt PARKED by the broker — an id-keyed, wire-safe record of a {@link PromptFormInterface}
+ * call awaiting a remote answer. The value a `pending` listener receives and the broker serializes
+ * over SSE to a {@link PromptClient}.
+ *
+ * @remarks
+ * - `id` — the unique id (minted via `crypto.randomUUID()`); the key for {@link PromptInterface.answer}.
+ * - `form` — which prompt form was called ({@link PromptType}); the discriminant a client
+ *   dispatches on (named for its axis — the prompt form — never `kind` / `type`).
+ * - `message` — the prompt's question (lifted out of `options` for direct display).
+ * - `options` — the WIRE-SAFE options (a `validate` FUNCTION dropped; the declarative
+ *   {@link ValidationRules} data + `choices` / `default` / `mask` kept — see
+ *   {@link import('./helpers.js').serializePromptOptions}). A client reconstructs the validator
+ *   from the rules via {@link resolveValidation}.
+ * - `status` — the current {@link PendingPromptStatus}.
+ * - `time` — the creation timestamp (ms since epoch).
+ */
+export declare interface PendingPrompt {
+    readonly id: string;
+    readonly form: PromptType;
+    readonly message: string;
+    readonly options: Readonly<Record<string, unknown>>;
+    readonly status: PendingPromptStatus;
+    readonly time: number;
+}
+
+/**
+ * The lifecycle status of a parked {@link PendingPrompt} — where a brokered prompt stands.
+ * Names its axis (the pending prompt's progression), never `kind` (AGENTS §4.4).
+ *
+ * @remarks
+ * - `pending` — parked, awaiting an {@link PromptInterface.answer} (the Promise is unresolved).
+ * - `answered` — answered and accepted (the Promise resolved with the validated value).
+ * - `expired` — timed out (or torn down by `destroy`) before an answer (the Promise rejected).
+ */
+export declare type PendingPromptStatus = 'pending' | 'answered' | 'expired';
+
+/**
+ * The headless prompt BROKER (observable §13) — parks each {@link PromptInterface} call as a
+ * pending prompt and returns a Promise that resolves when the prompt is {@link answer}ed (or
+ * rejects on timeout / teardown). The tri-surface's headless arm: there is no terminal here, so a
+ * transport forwards each `pending` event to whoever can answer, and {@link answer} resolves the
+ * parked Promise — for environments where direct user access is unavailable (a headless server on
+ * stdio, a browser with no TTY, a prompt issued on one machine answered on another).
+ *
+ * @remarks
+ * - **Park-as-Promise.** Each `input` / `password` / `confirm` / `select` / `checkbox` / `editor`
+ *   mints an id (`crypto.randomUUID()`), parks a wire-safe {@link PendingPrompt}, emits `pending`,
+ *   and returns an unresolved Promise. The prompt's options are serialized
+ *   ({@link serializePromptOptions}) so a transport can forward them as-is.
+ * - **Answer validates + type-checks.** {@link answer} runs the prompt's per-form gate: it
+ *   type-checks `value` to the form (string / boolean / string[]) AND, for the text forms, runs
+ *   the validator resolved from the original `validate` rules. A rejected answer returns `false`
+ *   and the prompt stays `pending`; an accepted answer resolves the Promise, emits `answer`, and
+ *   removes the prompt.
+ * - **Timeout → expire → reject.** An unanswered prompt expires after `timeout` ms (via the
+ *   INJECTED timer): `expire` fires and the parked Promise rejects with a {@link TerminalError}
+ *   (`code: 'EXPIRE'`). {@link destroy} expires every still-pending prompt the same way.
+ * - **Deterministic.** The timer is injectable ({@link import('./types.js').TimerHandler}); a test
+ *   supplies one that fires on demand, so expiry is driven without real time.
+ *
+ * @example
+ * ```ts
+ * const prompt = createPrompt({ timeout: 60_000 })
+ * prompt.emitter.on('pending', (pending) => broadcast(pending)) // forward to a client
+ *
+ * const name = await prompt.input({ message: 'Your name' }) // parks; resolves on answer()
+ * // ...elsewhere, a client POSTs the answer back:
+ * prompt.answer(id, 'Ada') // resolves the awaited input() above
+ * ```
+ */
+export declare class Prompt implements PromptInterface {
+    #private;
+    constructor(options?: PromptOptions);
+    get emitter(): EmitterInterface<PromptEventMap>;
+    get count(): number;
+    pending(): readonly PendingPrompt[];
+    pending(id: string): PendingPrompt | undefined;
+    answer(id: string, value: unknown): boolean;
+    input(options: InputOptions): Promise<string>;
+    password(options: PasswordOptions): Promise<string>;
+    confirm(options: ConfirmOptions): Promise<boolean>;
+    select(options: SelectOptions): Promise<string>;
+    checkbox(options: CheckboxOptions): Promise<readonly string[]>;
+    editor(options: EditorOptions): Promise<string>;
+    destroy(): void;
+}
+
+/**
+ * The prompt-view icon glyphs the reducers render the prompt line and choice rows with. PLAIN
+ * glyphs — color is applied by the {@link import('./types.js').PromptState}'s
+ * {@link import('@orkestrel/console').StylerInterface} at render time, never baked into the
+ * constant (AGENTS — styling orthogonal to data; the rework fixes the terminal's ANSI-in-the-icon).
+ * Frozen.
+ *
+ * @remarks
+ * - `question` — the leading mark on a prompt's message line.
+ * - `pointer` — the cursor before the input / the focused choice row.
+ * - `dot` / `selected` — an unfocused / focused row marker in a select list.
+ * - `checked` / `unchecked` — a checked / unchecked box in a checkbox list.
+ */
+export declare const PROMPT_ICONS: Readonly<{
+    question: "?";
+    pointer: "›";
+    dot: "○";
+    selected: "●";
+    checked: "☑";
+    unchecked: "☐";
+}>;
+
+/** A choice item in a {@link SelectOptions} prompt — its displayed `name`, its resolved `value`, and an optional one-line `description`. */
+export declare interface PromptChoice {
+    readonly name: string;
+    readonly value: string;
+    readonly description?: string;
+}
+
+/**
+ * The SSE prompt BRIDGE (observable §13) — the client-side counterpart to
+ * {@link import('./Prompt.js').Prompt}. Connects to a remote broker's SSE endpoint, receives
+ * serialized pending prompts, dispatches EACH to a LOCAL {@link PromptFormInterface} terminal (so
+ * a human at THIS machine answers a prompt parked elsewhere), and POSTs the answer back.
+ * Universal — `fetch` + SSE are web-standard, so it runs in a browser or on a server; the
+ * injected `fetch` / timer make it fully deterministic in tests.
+ *
+ * @remarks
+ * - **Connect + reconnect.** {@link connect} opens the SSE stream (via the injected `fetch` + the
+ *   core `SSEParser`) and loops, reconnecting after the stream drops with the `delay` backoff
+ *   (driven by the injected timer) — unless `reconnect` is `false`, the client was
+ *   {@link destroy}ed, or the drop was a deliberate {@link disconnect} (an abort).
+ * - **Dispatch + answer.** Each decoded `pending` event is narrowed to a `PendingPrompt` (§14 —
+ *   never an `as`), dispatched to `terminal`, and its resolved value POSTed back to `url`.
+ *   Dispatch is strictly SERIAL: the read loop drives the terminal for ONE prompt at a time and
+ *   only reads/dispatches the next event after the current prompt fully settles (its answer
+ *   POSTed). A prompt id redelivered by the broker AFTER its prior dispatch has settled is
+ *   dispatched again — the client does not dedupe across completion.
+ * - **Server signals.** An `expire` event (the broker dropped a parked prompt) emits `expire`; a
+ *   `shutdown` event calls {@link disconnect} (not {@link destroy}) — the client stops streaming
+ *   without auto-reconnect but stays reusable; a later {@link connect} recovers it.
+ * - **Lean events (§13).** `connect` / `disconnect` / `expire` / `error` — errors are `unknown`.
+ *   `disconnect` fires exactly once per connected-to-disconnected transition, whether triggered by
+ *   the server ending the stream cleanly or by a deliberate {@link disconnect} / {@link destroy}.
+ *
+ * @example
+ * ```ts
+ * const client = createPromptClient({
+ * 	url: 'http://localhost:3001/prompts',
+ * 	terminal: createTerminal(), // a local PromptFormInterface (T-c)
+ * 	on: { connect: () => log('connected') },
+ * })
+ * await client.connect() // streams remote prompts to the local terminal, POSTs answers back
+ * ```
+ */
+export declare class PromptClient implements PromptClientInterface {
+    #private;
+    readonly url: string;
+    constructor(options: PromptClientOptions);
+    get emitter(): EmitterInterface<PromptClientEventMap>;
+    get connected(): boolean;
+    connect(): Promise<void>;
+    disconnect(): void;
+    destroy(): void;
+}
+
+/**
+ * The client's event map (AGENTS §13) — lean, errors `unknown`, no listener-error event.
+ *
+ * @remarks
+ * - `connect` — the SSE stream opened.
+ * - `disconnect` — the SSE stream closed (the server ended it, or {@link PromptClientInterface.disconnect}).
+ * - `expire` — the remote broker signalled a parked prompt expired (carries its `id`).
+ * - `error` — a connection / dispatch / POST fault (errors are `unknown`).
+ */
+export declare type PromptClientEventMap = {
+    connect: [];
+    disconnect: [];
+    expire: [id: string];
+    error: [error: unknown];
+};
+
+/**
+ * The SSE prompt BRIDGE (observable §13) — the client-side counterpart to {@link PromptInterface}.
+ * Connects to a remote broker's SSE endpoint, receives serialized {@link PendingPrompt}s,
+ * dispatches EACH to a local {@link PromptFormInterface} terminal, and POSTs the answer back —
+ * so a human at this machine answers prompts a broker parked elsewhere.
+ *
+ * @remarks
+ * - **Connect.** {@link connect} opens the SSE stream (via the injected `fetch` + the core
+ *   `SSEParser`) and resolves when the stream ends; it reconnects with the `delay` backoff
+ *   unless `reconnect` is `false` or the client was {@link destroy}ed.
+ * - **Dispatch + answer.** Each decoded prompt is narrowed (§14) and dispatched to `terminal`;
+ *   the resolved value POSTs back to `url`.
+ * - **`connected`** reflects whether the stream is currently open.
+ */
+export declare interface PromptClientInterface {
+    readonly emitter: EmitterInterface<PromptClientEventMap>;
+    readonly url: string;
+    readonly connected: boolean;
+    connect(): Promise<void>;
+    disconnect(): void;
+    destroy(): void;
+}
+
+/**
+ * Options for {@link import('./factories.js').createPromptClient} / the {@link PromptClientInterface}.
+ *
+ * @remarks
+ * - `url` — the remote broker's SSE endpoint (GET opens the stream; answers POST back to it).
+ * - `terminal` — the LOCAL {@link PromptFormInterface} each remote prompt is dispatched to, so a
+ *   human at THIS machine answers a prompt issued 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`).
+ * - `delay` — ms to wait before each reconnect attempt (default
+ *   {@link import('./constants.js').DEFAULT_RECONNECT_DELAY_MS}).
+ * - `on` — initial {@link PromptClientEventMap} listeners (AGENTS §8/§13).
+ * - `error` — the emitter's listener-error handler (AGENTS §13).
+ * - `fetch` — the injected {@link FetchHandler} (default the global `fetch`); supply a scripted
+ *   fetch to drive the client deterministically in tests.
+ * - `timer` — the injected {@link TimerHandler} for the reconnect backoff (default the host
+ *   `setTimeout`); supply a deterministic timer to drive reconnection without real time.
+ */
+export declare interface PromptClientOptions {
+    readonly url: string;
+    readonly terminal: PromptFormInterface;
+    readonly token?: string;
+    readonly reconnect?: boolean;
+    readonly delay?: number;
+    readonly on?: EmitterHooks<PromptClientEventMap>;
+    readonly error?: EmitterErrorHandler;
+    readonly fetch?: FetchHandler;
+    readonly timer?: TimerHandler;
+}
+
+/**
+ * The broker's event map (AGENTS §13) — lean, errors `unknown`, no listener-error event.
+ *
+ * @remarks
+ * - `pending` — a prompt was parked (carries the wire-safe {@link PendingPrompt}); a transport
+ *   forwards it to remote clients.
+ * - `answer` — a parked prompt was answered (carries its `id` + the accepted `value`).
+ * - `expire` — a parked prompt timed out (or was torn down) unanswered (carries its `id`).
+ */
+export declare type PromptEventMap = {
+    pending: [prompt: PendingPrompt];
+    answer: [id: string, value: unknown];
+    expire: [id: string];
+};
+
+/**
+ * The shared ASYNC prompt contract — the six prompt forms as Promise-returning methods. The
+ * ONE vocabulary BOTH the headless {@link PromptInterface} broker (this module) and the server
+ * `Terminal` driver (T-c) implement, so a prompt issued through this surface resolves the same
+ * way on every surface (local TTY, headless broker, remote bridge).
+ *
+ * @remarks
+ * Each method takes the prompt's `*Options` and resolves to that form's value type:
+ * - `input` / `password` / `select` / `editor` → a `string`
+ * - `confirm` → a `boolean`
+ * - `checkbox` → a `readonly string[]` (the checked values, in choice order)
+ *
+ * This is a behavioral CONTRACT (the method surface), not an observable entity — the broker and
+ * the driver add their own emitter / lifecycle on top. The {@link PromptClient} dispatches a
+ * remote {@link PendingPrompt} to a LOCAL `PromptFormInterface` (so a human at this machine
+ * answers a prompt parked elsewhere).
+ */
+export declare interface PromptFormInterface {
+    input(options: InputOptions): Promise<string>;
+    password(options: PasswordOptions): Promise<string>;
+    confirm(options: ConfirmOptions): Promise<boolean>;
+    select(options: SelectOptions): Promise<string>;
+    checkbox(options: CheckboxOptions): Promise<readonly string[]>;
+    editor(options: EditorOptions): Promise<string>;
+}
+
+/** The styled prompt-message header (`? message`) — the leading line every active prompt view shares. */
+export declare function promptHeader(styler: StylerInterface, message: string): string;
+
+/**
+ * The headless prompt BROKER (observable §13) — implements {@link PromptFormInterface} by
+ * PARKING each call as a {@link PendingPrompt} and returning a Promise that resolves when the
+ * prompt is {@link answer}ed (or rejects on timeout). The local-TTY / headless / remote
+ * tri-surface's headless arm: no terminal here — a transport forwards each `pending` to whoever
+ * can answer, and {@link answer} resolves the parked Promise.
+ *
+ * @remarks
+ * - **Park-as-Promise.** Each `input` / `password` / … call mints an id, parks a
+ *   {@link PendingPrompt}, emits `pending`, and returns an unresolved Promise.
+ * - **Answer validates.** {@link answer} validates `value` against the prompt's resolved
+ *   validator AND type-checks it to the prompt form before accepting; a bad answer is rejected
+ *   (returns `false`, the prompt stays `pending`).
+ * - **Timeout → expire → reject.** An unanswered prompt expires after `timeout` ms — `expire`
+ *   fires and the parked Promise rejects (a {@link import('./errors.js').TerminalError}). The
+ *   timer is injectable for deterministic tests.
+ * - **Accessors (§9.1).** `pending()` lists the parked prompts; `pending(id)` looks one up.
+ */
+export declare interface PromptInterface extends PromptFormInterface {
+    readonly emitter: EmitterInterface<PromptEventMap>;
+    readonly count: number;
+    pending(): readonly PendingPrompt[];
+    pending(id: string): PendingPrompt | undefined;
+    answer(id: string, value: unknown): boolean;
+    destroy(): void;
+}
+
+/**
+ * Options for {@link import('./factories.js').createPrompt} / the {@link PromptInterface} broker.
+ *
+ * @remarks
+ * - `on` — initial {@link PromptEventMap} listeners (AGENTS §8/§13).
+ * - `error` — the emitter's listener-error handler (AGENTS §13).
+ * - `timeout` — ms a parked prompt waits before it expires + its Promise rejects (default
+ *   {@link import('./constants.js').DEFAULT_PROMPT_TIMEOUT_MS}).
+ * - `timer` — the injected {@link TimerHandler} (default the host `setTimeout`); supply a
+ *   deterministic timer to drive expiry in tests without real time.
+ */
+export declare interface PromptOptions {
+    readonly on?: EmitterHooks<PromptEventMap>;
+    readonly error?: EmitterErrorHandler;
+    readonly timeout?: number;
+    readonly timer?: TimerHandler;
+}
+
+/**
+ * The discriminant of a {@link PromptStep} — where the prompt stands after a key. `active`:
+ * keep prompting (the input was consumed, or rejected by validation). `submit`: the prompt
+ * resolved with its `value`. `cancel`: the user aborted (ctrl-c). Names its axis (the prompt's
+ * progression), never `kind` (AGENTS §4.4).
+ */
+export declare type PromptStatus = 'active' | 'submit' | 'cancel';
+
+/**
+ * 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 prompt reducer and the
+ * impure driver: the driver applies the next `state`, writes the `view`, and — when `status`
+ * is `submit` — reads `value`.
+ *
+ * @typeParam T - The prompt's resolved value type (`string` for input / password / select /
+ *   editor, `boolean` for confirm, `readonly string[]` for checkbox).
+ * @typeParam S - The prompt's concrete state shape ({@link InputState}, {@link SelectState}, …) —
+ *   carried directly so `state` stays precisely typed with no union narrowing or assertion.
+ *
+ * @remarks
+ * - `state` — the next immutable prompt state (feed it to the next reduce call). On `submit` /
+ *   `cancel` it is the final state.
+ * - `view` — the styled string to render NOW (possibly MULTI-LINE for `select` / `checkbox`),
+ *   built through the state's {@link StylerInterface}. On an invalid `submit` it carries the
+ *   error; the driver re-renders it each step.
+ * - `status` — the {@link PromptStatus}: `active` to continue, `submit` when resolved, `cancel`
+ *   on abort.
+ * - `value` — present ONLY on a `submit` step, carrying the prompt's resolved value.
+ */
+export declare interface PromptStep<T, S> {
+    readonly state: S;
+    readonly view: string;
+    readonly status: PromptStatus;
+    readonly value?: T;
+}
+
+/**
+ * The six prompt KINDS this core provides — the value family a higher-level broker (T-b)
+ * dispatches on. Names the prompt axis; a named value set (not a toggle), so it stays a union.
+ */
+export declare type PromptType = 'input' | 'password' | 'confirm' | 'select' | 'checkbox' | 'editor';
+
+/**
+ * Rebuild a wire-decoded `validate` payload into a {@link ValidationRules} bag — the inverse of
+ * {@link serializeValidationRules}. Keeps only the primitive rule values (`boolean` / `number` /
+ * `string`) a serialized prompt could carry; an empty / non-record / all-dropped payload yields
+ * `undefined` (no rules to apply). The client feeds the result back through {@link resolveValidation}.
+ */
+export declare function reconstructValidationRules(value: unknown): ValidationRules | undefined;
+
+/** Read a `choices` option as a list of bare strings / full choices — each element narrowed by `guard`, off-shape elements stringified. */
+export declare function resolveChoices<TChoice extends PromptChoice | CheckboxChoice>(options: Readonly<Record<string, unknown>>, guard: Guard<TChoice>): readonly (string | TChoice)[];
+
+/** Read one option by key, narrowed by `guard` — `undefined` when absent or off-shape (§14, never an `as`). */
+export declare function resolveOption<T>(options: Readonly<Record<string, unknown>>, key: string, guard: Guard<T>): T | undefined;
+
+/**
+ * Compile a {@link Validator} or declarative {@link ValidationRules} (or nothing) into ONE
+ * composed {@link Validator}. A bare validator passes through; rules are appended in the fixed
+ * order (required → minimum → maximum → pattern → email → url → numeric → integer → alphanumeric
+ * → custom) and composed; absent / empty input yields an always-passing validator. Pure.
+ *
+ * @remarks
+ * Unlike a prior variant (which returned `Validator | undefined`), this ALWAYS returns a
+ * `Validator` — an absent or empty rule set yields a validator that returns `true` for every
+ * input. That keeps a prompt's state unconditional (it always holds a real validator to apply on
+ * submit), with no `undefined` branch at the call site.
+ *
+ * @param validate - A custom {@link Validator}, a {@link ValidationRules} bag, or `undefined`
+ * @returns The composed {@link Validator} (always-passing when nothing was supplied)
+ *
+ * @example
+ * ```ts
+ * const v = resolveValidation({ required: true, minimum: 3 })
+ * v('')    // 'This field is required'
+ * v('ab')  // 'Must be at least 3 characters'
+ * v('abc') // true
+ * ```
+ */
+export declare function resolveValidation(validate?: Validator | ValidationRules): Validator;
+
+/** Carriage return (`\r`, U+000D) — Enter on most terminals. */
+export declare const RETURN: string;
+
+/**
+ * Each built-in validation rule's default error message — what the composed {@link
+ * import('./types.js').Validator} returns when that rule fails (the `minimum` / `maximum`
+ * messages are interpolated with the configured length at build time). Frozen; the source of
+ * truth for the rule-failure copy.
+ */
+export declare const RULE_MESSAGES: Readonly<{
+    required: "This field is required";
+    minimum: "Must be at least {count} characters";
+    maximum: "Must be at most {count} characters";
+    pattern: "Must match pattern: {pattern}";
+    email: "Must be a valid email address";
+    url: "Must be a valid URL";
+    numeric: "Must be a numeric value";
+    integer: "Must be an integer";
+    alphanumeric: "Must contain only letters and digits";
+    invalid: "Invalid input";
+}>;
+
+/**
+ * Sanitize a list of resolved choices' human-readable labels (`name` + `description`) with
+ * {@link stripControls} — shared by the `select` and `checkbox` branches of
+ * {@link dispatchPendingPrompt} so a remote-supplied choice can never inject raw control bytes
+ * into the local terminal's rendered view.
+ *
+ * @param choices - The resolved choices (bare strings or full {@link PromptChoice} /
+ *   {@link CheckboxChoice} objects) as returned by {@link resolveChoices}
+ * @returns The same choices with every `name` / `description` control-stripped
+ */
+export declare function sanitizeChoiceLabels<TChoice extends PromptChoice | CheckboxChoice>(choices: readonly (string | TChoice)[]): readonly (string | TChoice)[];
+
+/**
+ * Options for a single-selection {@link import('./helpers.js').selectReduce} prompt.
+ *
+ * @remarks
+ * `choices` accepts bare strings (used as both `name` and `value`) or full {@link PromptChoice}
+ * objects; {@link import('./helpers.js').createSelectState} normalizes them. `default` pre-focuses
+ * the choice whose `value` matches it.
+ */
+export declare interface SelectOptions {
+    readonly message: string;
+    readonly choices: readonly (string | PromptChoice)[];
+    readonly default?: string;
+    readonly styler?: StylerInterface;
+}
+
+/**
+ * Advance 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
+ * 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.
+ */
+export declare function selectReduce(state: SelectState, key: KeyEvent): PromptStep<string, SelectState>;
+
+/**
+ * The immutable state of a select prompt — the normalized choices, the styler, and the
+ * `focused` index (the highlighted row).
+ *
+ * @remarks
+ * Built by {@link import('./helpers.js').createSelectState}; advanced by
+ * {@link import('./helpers.js').selectReduce}. `up` / `down` move `focused` (wrapping at the
+ * ends); `return` submits the focused choice's `value`.
+ */
+export declare interface SelectState {
+    readonly message: string;
+    readonly choices: readonly PromptChoice[];
+    readonly styler: StylerInterface;
+    readonly focused: number;
+}
+
+/** Render a {@link SelectState} as a MULTI-LINE styled view — the header followed by one row per choice, the focused row marked. */
+export declare function selectView(state: SelectState): string;
+
+/**
+ * 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 four 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),
+ * and Home / End / Delete each have a letter form (`ESC[H` / `ESC[F`) and a numeric form
+ * (`ESC[1~` / `ESC[4~` / `ESC[3~`). Every accepted spelling maps to one name so a reducer never
+ * sees the wire encoding.
+ */
+export declare const SEQUENCE_NAMES: Readonly<Record<string, string>>;
+
+/** Strip functions from a `choices` option — each choice keeps its plain fields; a bare string passes through. */
+export declare function serializeChoices(choices: unknown): readonly unknown[];
+
+/**
+ * Produce the WIRE-SAFE form of a prompt's options — the {@link PendingPrompt.options} a broker
+ * serializes over SSE. Drops everything that cannot cross the wire (a `styler`, and any
+ * function-valued `validate` rule), while KEEPING the declarative data a remote client needs to
+ * reconstruct the prompt: the {@link ValidationRules} as data, plus `message` / `choices` /
+ * `default` / `mask` / `min` / `max`. This is WHY T-a's validation is rules-as-data: a `Validator`
+ * FUNCTION can't be serialized, but its declarative rules can — the client rebuilds the validator
+ * from them via {@link resolveValidation}.
+ *
+ * @remarks
+ * - **Functions are dropped.** A top-level function value (e.g. a bare-`Validator` `validate`) is
+ *   omitted entirely; the `styler` (a fluent function-bearing object) is dropped by key.
+ * - **`validate` rules are flattened.** A {@link ValidationRules} bag is copied with each
+ *   function rule replaced by `true` (the rule's INTENT survives as the built-in check; its
+ *   custom function does not). A bare-function `validate` is dropped (no declarative form to keep).
+ * - **`choices` are function-stripped.** Each choice keeps its plain fields (`name` / `value` /
+ *   `description` / `checked`); a bare string passes through.
+ *
+ * @param options - The raw prompt options bag (may hold functions / a styler)
+ * @returns A JSON-safe options record — only serializable, declarative data
+ */
+export declare function serializePromptOptions(options: object): Readonly<Record<string, unknown>>;
+
+/**
+ * Flatten a `validate` option to its wire-safe {@link ValidationRules} DATA — a function rule
+ * becomes `true` (its built-in check survives; its body cannot cross the wire). A bare-function
+ * `validate` (no rules object) has no declarative form, so it yields `undefined` (dropped).
+ */
+export declare function serializeValidationRules(validate: unknown): Readonly<Record<string, unknown>> | undefined;
+
+/** Space (U+0020). */
+export declare const SPACE = " ";
+
+/**
+ * The maximum number of characters the {@link import('./types.js').PromptClient} lets its
+ * SSE parser buffer before treating the stream as hostile — 1 MiB, comfortably above any
+ * legitimate prompt payload. Passed as the `limit` to `createSSEParser` so an unterminated
+ * or oversized `data:` field cannot grow the buffer without bound (a memory-exhaustion guard).
+ */
+export declare const SSE_BUFFER_LIMIT = 1048576;
+
+/**
+ * The SSE `event:` names the broker emits and the {@link import('./types.js').PromptClient}
+ * dispatches on. Frozen; the source of truth for the wire event vocabulary.
+ *
+ * @remarks
+ * - `pending` — a serialized {@link import('./types.js').PendingPrompt} to dispatch + answer.
+ * - `expire` — an `{ id }` payload: the broker expired a parked prompt (the client drops it).
+ * - `shutdown` — the broker is going away; the client disconnects (no auto-reconnect) but stays reusable.
+ */
+export declare const SSE_EVENTS: Readonly<{
+    pending: "pending";
+    expire: "expire";
+    shutdown: "shutdown";
+}>;
+
+/** The styled submit line (`✔ message`) — the committed header an interactive prompt shows once resolved. */
+export declare function submitHeader(styler: StylerInterface, message: string): string;
+
+/** Tab (`\t`, U+0009). */
+export declare const TAB: string;
+
+/**
+ * An error a {@link import('./Prompt.js').Prompt} broker rejects a parked prompt's Promise with.
+ *
+ * @remarks
+ * Carries a {@link TerminalErrorCode} and an optional `context` bag (the prompt `id`). Thrown —
+ * as a Promise rejection on the awaited prompt call — when a parked prompt is not answered before
+ * its `timeout`, or when the broker is `destroy`ed while the prompt is still `pending` (both
+ * `EXPIRE`); or when the user aborts an interactive server-`Terminal` prompt with ctrl-c
+ * (`CANCEL`). Narrow a caught value with {@link isTerminalError} and branch on `error.code`.
+ */
+export declare class TerminalError extends Error {
+    /** The machine-readable condition — see {@link TerminalErrorCode}. */
+    readonly code: TerminalErrorCode;
+    /** An optional context bag naming the offending prompt id. */
+    readonly context?: Readonly<Record<string, unknown>>;
+    constructor(code: TerminalErrorCode, message: string, context?: Readonly<Record<string, unknown>>);
+}
+
+/**
+ * The machine-readable condition carried by a {@link import('./errors.js').TerminalError} — the
+ * axis a `catch` branches on. Names its axis (the failure condition), never `kind` (AGENTS §4.4).
+ *
+ * @remarks
+ * - `EXPIRE` — a parked broker prompt was not answered before its `timeout` (or the broker was
+ *   `destroy`ed while it was still pending); the prompt's Promise rejects with this.
+ * - `CANCEL` — the user aborted an interactive prompt (ctrl-c) at the server `Terminal` (T-c)
+ *   driver; the awaited prompt call rejects with this so a caller can branch on `error.code`.
+ */
+export declare type TerminalErrorCode = 'EXPIRE' | 'CANCEL';
+
+/** Cancel a pending {@link TimerHandler} deadline — idempotent, safe to call after the timer fired. */
+export declare type TimerCancel = () => void;
+
+/**
+ * One injected timer — arms a deadline `callback` to fire after `ms`, returning a
+ * {@link TimerCancel} that cancels it. The broker's timeout seam: the default wraps the host
+ * `setTimeout` / `clearTimeout`; a test injects a deterministic timer that captures the callback
+ * and fires it on demand (no real time, no global fake-timer patching).
+ */
+export declare type TimerHandler = (callback: () => void, ms: number) => TimerCancel;
+
+/** Toggle `index` in a readonly index list — copy-on-write, returning the new sorted-by-insertion list. */
+export declare function toggleIndex(indices: readonly number[], index: number): readonly number[];
+
+/** Matches an HTTP(S) URL. The `url` rule tests against this. */
+export declare const URL_PATTERN: RegExp;
+
+/**
+ * Declarative validation rules for a text prompt — each key toggles (or overrides) one
+ * built-in check. {@link import('./helpers.js').resolveValidation} compiles a `ValidationRules`
+ * (or a bare {@link Validator}) into ONE composed {@link Validator}.
+ *
+ * @remarks
+ * Each rule is EITHER a primitive that turns on the built-in check, OR a {@link Validator}
+ * that replaces it with custom logic:
+ *
+ * - `required` — `true` ⇒ input must be non-empty after trimming.
+ * - `minimum` — a number ⇒ input must be at least that many characters.
+ * - `maximum` — a number ⇒ input must be at most that many characters.
+ * - `pattern` — a string ⇒ input must match that regex source.
+ * - `email` — `true` ⇒ input must look like an email address.
+ * - `url` — `true` ⇒ input must look like an HTTP(S) URL.
+ * - `numeric` — `true` ⇒ input must be a number (integer or decimal).
+ * - `integer` — `true` ⇒ input must be an integer.
+ * - `alphanumeric` — `true` ⇒ input must contain only letters and digits.
+ * - `custom` — an arbitrary {@link Validator} escape hatch.
+ *
+ * Rules compose in the fixed order above; the FIRST failing rule short-circuits and its
+ * message is returned. A `false` / `undefined` rule is skipped.
+ */
+export declare interface ValidationRules {
+    readonly required?: boolean | Validator;
+    readonly minimum?: number | Validator;
+    readonly maximum?: number | Validator;
+    readonly pattern?: string | Validator;
+    readonly email?: boolean | Validator;
+    readonly url?: boolean | Validator;
+    readonly numeric?: boolean | Validator;
+    readonly integer?: boolean | Validator;
+    readonly alphanumeric?: boolean | Validator;
+    readonly custom?: Validator;
+}
+
+/**
+ * A single input validator — given the current input string, returns `true` when the input
+ * is valid, or an error MESSAGE string when it is not. The atomic unit the validation engine
+ * composes and the prompts apply on submit.
+ *
+ * @remarks
+ * A `Validator` is total and pure — it never throws and never mutates. The `true | string`
+ * shape (not `boolean`) is deliberate: an invalid result CARRIES its message, so a prompt
+ * can render the exact reason. {@link import('./helpers.js').composeValidators} runs several
+ * in order and returns the FIRST error (short-circuiting), so the most specific rule wins.
+ */
+export declare type Validator = (input: string) => true | string;
+
+export { }