@orkestrel/terminal 0.0.6 → 0.0.8

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

@@ -3,6 +3,8 @@ import { EmitterErrorHandler } from '@orkestrel/emitter';
 import { EmitterHooks } from '@orkestrel/emitter';
 import { EmitterInterface } from '@orkestrel/emitter';
 import { Guard } from '@orkestrel/contract';
+import { Result } from '@orkestrel/contract';
+import { Style } from '@orkestrel/console';
 import { StylerInterface } from '@orkestrel/console';
 import { TableInterface } from '@orkestrel/database';
 
@@ -15,15 +17,6 @@ export declare const ALPHANUMERIC_PATTERN: RegExp;
 /** The rejection reason a bare {@link PromptInterface.answer} returns — `'unknown'` (no such parked prompt) or `'rejected'` (failed validation / type-check). */
 export declare type AnswerError = 'unknown' | 'rejected';
 
-/** The outcome of a bare {@link PromptInterface.answer} call — the accepted `value` on success, else the {@link AnswerError}. */
-export declare type AnswerResult = {
-    readonly success: true;
-    readonly value: unknown;
-} | {
-    readonly success: false;
-    readonly error: AnswerError;
-};
-
 /**
  * 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
@@ -52,14 +45,17 @@ export declare interface CheckboxChoice {
  * `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).
+ * is rejected (the prompt stays active with the reason in the view). `hint` adds a key hint after
+ * the message (no computed default) and reaches the server driver's numbered fallback too.
  */
 export declare interface CheckboxOptions {
     readonly message: string;
-    readonly choices: readonly (string | CheckboxChoice)[];
+    readonly choices: ReadonlyArray<string | CheckboxChoice>;
     readonly min?: number;
     readonly max?: number;
+    readonly hint?: string;
     readonly styler?: StylerInterface;
+    readonly theme?: PromptThemeOptions;
 }
 
 /**
@@ -72,8 +68,9 @@ export declare interface CheckboxOptions {
 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`.
+ * The immutable state of a checkbox prompt — the normalized choices, the optional hint, the
+ * resolved styler + theme, 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
@@ -85,7 +82,9 @@ export declare function checkboxReduce(state: CheckboxState, key: KeyEvent): Pro
 export declare interface CheckboxState {
     readonly message: string;
     readonly choices: readonly CheckboxChoice[];
+    readonly hint?: string;
     readonly styler: StylerInterface;
+    readonly theme: PromptTheme;
     readonly focused: number;
     readonly checked: readonly number[];
     readonly min?: number;
@@ -93,7 +92,7 @@ export declare interface CheckboxState {
     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. */
+/** Render a {@link CheckboxState} as a MULTI-LINE styled view — the header (plus any hint), one box per choice (focused + checked marked), a count, and any error. */
 export declare function checkboxView(state: CheckboxState): string;
 
 /**
@@ -103,11 +102,20 @@ export declare function checkboxView(state: CheckboxState): string;
  */
 export declare function composeValidators(...validators: Validator[]): Validator;
 
-/** Options for a yes/no {@link import('./helpers.js').confirmReduce} confirmation prompt. */
+/**
+ * Options for a yes/no {@link import('./helpers.js').confirmReduce} confirmation prompt.
+ *
+ * @remarks
+ * `hint` replaces the computed `(Y/n)` group in full, parentheses included, and is painted with
+ * the theme's `hint` role. The accepted KEYS stay `y` / `n` / `enter` whatever the hint says, so a
+ * hint that advertises other keys is the consumer's own contradiction.
+ */
 export declare interface ConfirmOptions {
     readonly message: string;
     readonly default?: boolean;
+    readonly hint?: string;
     readonly styler?: StylerInterface;
+    readonly theme?: PromptThemeOptions;
 }
 
 /**
@@ -118,21 +126,28 @@ export declare interface ConfirmOptions {
 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.
+ * The immutable state of a confirm prompt — its message, the default answer, the optional hint
+ * override, and the resolved styler + theme.
  *
  * @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).
+ * `false`, and `enter` takes the `default` (rendered with the active letter emphasized in the
+ * `(Y/n)` hint, unless `hint` replaces that group).
  */
 export declare interface ConfirmState {
     readonly message: string;
     readonly default: boolean;
+    readonly hint?: string;
     readonly styler: StylerInterface;
+    readonly theme: PromptTheme;
 }
 
-/** Render a {@link ConfirmState} as a styled view — the header plus a `(Y/n)` hint with the default letter emphasized. */
+/**
+ * Render a {@link ConfirmState} as a styled view — the header plus the `(Y/n)` group with the
+ * default letter painted by the `selected` role. A supplied `hint` replaces that whole group,
+ * parentheses included, painted by the `hint` role.
+ */
 export declare function confirmView(state: ConfirmState): string;
 
 /**
@@ -151,10 +166,10 @@ export declare const CONTROL_NAMES: Readonly<Record<string, {
     readonly ctrl: boolean;
 }>>;
 
-/** Build the initial {@link CheckboxState} from {@link CheckboxOptions} — normalizing choices, seeding the checked set, carrying min/max. */
+/** Build the initial {@link CheckboxState} from {@link CheckboxOptions} — normalizing choices, resolving the styler + theme, carrying any hint, 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`. */
+/** Build the initial {@link ConfirmState} from {@link ConfirmOptions} — defaulting the answer to `false`, resolving the styler + theme, carrying any hint override. */
 export declare function createConfirmState(options: ConfirmOptions): ConfirmState;
 
 /**
@@ -174,10 +189,10 @@ export declare function createConfirmState(options: ConfirmOptions): ConfirmStat
  */
 export declare function createDatabaseTerminalStore(driver?: DriverInterface): TerminalStoreInterface;
 
-/** Build the initial {@link EditorState} from {@link EditorOptions} — resolving the validator + styler, seeding empty lines. */
+/** Build the initial {@link EditorState} from {@link EditorOptions} — resolving the validator + styler + theme, carrying any hint override, 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. */
+/** Build the initial {@link InputState} from {@link InputOptions} — resolving the validator + styler + theme, seeding an empty value. */
 export declare function createInputState(options: InputOptions): InputState;
 
 /**
@@ -195,7 +210,7 @@ export declare function createInputState(options: InputOptions): InputState;
  */
 export declare function createMemoryTerminalStore(): TerminalStoreInterface;
 
-/** Build the initial {@link PasswordState} from {@link PasswordOptions} — resolving the validator + styler + mask. */
+/** Build the initial {@link PasswordState} from {@link PasswordOptions} — resolving the validator + styler + theme + mask. */
 export declare function createPasswordState(options: PasswordOptions): PasswordState;
 
 /**
@@ -253,7 +268,29 @@ export declare function createPrompt(options?: PromptOptions): PromptInterface;
  */
 export declare function createPromptClient(options: PromptClientOptions): PromptClientInterface;
 
-/** Build the initial {@link SelectState} from {@link SelectOptions} — normalizing choices and pre-focusing the default. */
+/**
+ * Build a complete {@link PromptTheme} by merging a partial one over
+ * {@link DEFAULT_PROMPT_THEME}, leaf by leaf — each supplied icon replaces that glyph, each
+ * supplied role replaces that {@link Style}, and everything else keeps its default. Each supplied
+ * style is snapshotted through the console module's own
+ * {@link import('@orkestrel/console').freezeStyle}, so the result is deeply frozen and a caller
+ * mutating its own attribute list afterwards cannot reach into a built theme.
+ *
+ * @param options - The partial theme to merge, or `undefined` for the defaults
+ * @returns The resolved, deeply frozen theme every prompt state carries
+ *
+ * @example
+ * ```ts
+ * createPromptTheme() // the defaults
+ * createPromptTheme({
+ * 	icons: { pointer: '=>' },
+ * 	roles: { message: { foreground: 'magenta', attributes: ['bold'] } },
+ * })
+ * ```
+ */
+export declare function createPromptTheme(options?: PromptThemeOptions): PromptTheme;
+
+/** Build the initial {@link SelectState} from {@link SelectOptions} — normalizing choices, resolving the styler + theme, carrying any hint, and pre-focusing the default. */
 export declare function createSelectState(options: SelectOptions): SelectState;
 
 /**
@@ -351,6 +388,23 @@ export declare class DatabaseTerminalStore implements TerminalStoreInterface {
 /** The default mask glyph a {@link import('./types.js').PasswordState} renders each input character as — `*`. */
 export declare const DEFAULT_MASK = "*";
 
+/**
+ * The {@link import('./types.js').PromptTheme} every prompt renders with unless its options supply
+ * another — the glyph set assembled from {@link PROMPT_ICONS} plus the console
+ * {@link import('@orkestrel/console').STATUS_ICONS} `success` / `error` marks, and the console
+ * {@link import('@orkestrel/console').Style} each role is painted with. Deeply frozen through the
+ * console module's own {@link import('@orkestrel/console').freezeStyle}; the baseline
+ * {@link import('./helpers.js').createPromptTheme} merges a partial theme over.
+ *
+ * @remarks
+ * The default roles reproduce the views' historical coloring exactly: `question` / `pointer` cyan,
+ * `message` / `focus` bold, `success` / `selected` green, `error` red, `hint` / `muted` /
+ * `description` dim, and `content` the EMPTY style — an empty style renders bare text, so primary
+ * content keeps the bytes it had before it became themeable.
+ * Two roles sharing a style today are still two roles — re-mapping one leaves the other alone.
+ */
+export declare const DEFAULT_PROMPT_THEME: PromptTheme;
+
 /** 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;
 
@@ -376,6 +430,13 @@ export declare const DELETE: string;
  * §14-narrowed, never an `as`; the validator rebuilt from rules via {@link reconstructValidationRules}),
  * then calls the matching prompt form and returns its resolved value.
  *
+ * @remarks
+ * `theme` and `hint` are plain data, so they cross the wire with the rest of the options bag and
+ * are reconstructed here for every form that accepts them: the theme is narrowed by
+ * {@link import('./validators.js').isPromptThemeOptions} (an off-shape theme is dropped, leaving
+ * the defaults), then every glyph and hint is passed through {@link sanitizeDisplayText}. Choice
+ * labels use the stream-safe {@link sanitizeChoiceLabels} treatment instead.
+ *
  * @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)
@@ -390,12 +451,21 @@ export declare function dispatchPendingPrompt(terminal: PromptFormInterface, pen
  */
 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). */
+/**
+ * Options for a multi-line {@link import('./helpers.js').editorReduce} editor prompt (terminated
+ * by ctrl-d).
+ *
+ * @remarks
+ * `hint` replaces the computed `(Ctrl+D to finish)` group in full, parentheses included. The
+ * finish KEY stays ctrl-d whatever the hint says.
+ */
 export declare interface EditorOptions {
     readonly message: string;
     readonly default?: string;
+    readonly hint?: string;
     readonly validate?: Validator | ValidationRules;
     readonly styler?: StylerInterface;
+    readonly theme?: PromptThemeOptions;
 }
 
 /**
@@ -409,7 +479,8 @@ export declare function editorReduce(state: EditorState, key: KeyEvent): PromptS
 
 /**
  * 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`.
+ * line, plus the resolved validator + styler + theme, the default, the optional hint override,
+ * and the current `error`.
  *
  * @remarks
  * Built by {@link import('./helpers.js').createEditorState}; advanced by
@@ -421,21 +492,24 @@ export declare function editorReduce(state: EditorState, key: KeyEvent): PromptS
 export declare interface EditorState {
     readonly message: string;
     readonly default: string;
+    readonly hint?: string;
     readonly validator: Validator;
     readonly styler: StylerInterface;
+    readonly theme: PromptTheme;
     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. */
+/**
+ * Render an {@link EditorState} as a MULTI-LINE styled view — the header with its finish hint, the
+ * committed and in-progress lines painted by the `content` role, and any error. A supplied `hint`
+ * replaces `(Ctrl+D to finish)` in full; the finish key stays ctrl-d.
+ */
 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;
+/** The styled error line (`✖ message`) — appended beneath a prompt view when the last submit failed validation, themed by the `error` role. */
+export declare function errorLine(styler: StylerInterface, theme: PromptTheme, message: string): string;
 
 /** Escape (ESC, U+001B) — the lone byte, and the lead byte of every CSI / SS3 sequence. */
 export declare const ESCAPE: string;
@@ -486,12 +560,25 @@ export declare function globalFetch(input: string, init?: FetchInit): Promise<Re
 /** 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";
 
+/**
+ * Render a prompt header followed by a key hint painted with the `hint` role, or the header alone
+ * when no hint is supplied.
+ *
+ * @param styler - The console styler that renders each role
+ * @param theme - The resolved prompt theme
+ * @param message - The prompt's question text
+ * @param hint - The optional key hint to append
+ * @returns The rendered header with the optional hint
+ */
+export declare function hintedHeader(styler: StylerInterface, theme: PromptTheme, message: string, hint?: string): string;
+
 /** 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;
+    readonly theme?: PromptThemeOptions;
 }
 
 /**
@@ -503,8 +590,8 @@ export declare interface InputOptions {
 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).
+ * The immutable state of a text input prompt — its options, the resolved validator + styler +
+ * theme, the accumulated `value`, and the current `error` (when the last submit failed validation).
  *
  * @remarks
  * Built by {@link import('./helpers.js').createInputState}; advanced by
@@ -517,11 +604,12 @@ export declare interface InputState {
     readonly default: string;
     readonly validator: Validator;
     readonly styler: StylerInterface;
+    readonly theme: PromptTheme;
     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. */
+/** Render an {@link InputState} as a styled view — the header, the typed value painted by the `content` role (or the default painted as a hint), and any error. */
 export declare function inputView(state: InputState): string;
 
 /** Matches an integer (optional sign). The `integer` rule tests against this. */
@@ -581,9 +669,40 @@ 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 wire value to a {@link PromptThemeOptions} — the §14 guard a remote prompt's
+ * `theme` option passes before it reaches a local prompt.
+ *
+ * @remarks
+ * The shape is CLOSED at every level: an unknown icon slot, an unknown role, a non-string glyph, or
+ * a role whose value is not a {@link isStyle}-shaped console style rejects the whole theme, so a
+ * hostile payload degrades to the default theme rather than partially applying. Glyphs still carry
+ * arbitrary text at this point — {@link import('./helpers.js').sanitizeThemeIcons} strips their
+ * control bytes on dispatch.
+ *
+ * The icons and roles shapes are checked against their complete union-keyed guard records. A slot
+ * added to either union without an entry here is a compile error rather than a wire theme that is
+ * silently refused.
+ */
+export declare const isPromptThemeOptions: Guard<PromptThemeOptions>;
+
 /** Narrow an unknown value to a {@link PromptType} — one of the six prompt forms. */
 export declare const isPromptType: Guard<PromptType>;
 
+/**
+ * Narrow an unknown value to a console {@link Style} — the value every
+ * {@link import('./types.js').PromptRole} carries, built from the console module's own
+ * {@link import('@orkestrel/console').COLORS} + {@link import('@orkestrel/console').ATTRIBUTES} so
+ * the style vocabulary has ONE source.
+ *
+ * @remarks
+ * The record is CLOSED and matches the `Style` contract exactly: `foreground` and `background` are
+ * optional and each must name a color (`default` included, as the console `Color` union has it),
+ * `attributes` is REQUIRED and must be an array over the attribute set, and any other key rejects
+ * the whole value.
+ */
+export declare const isStyle: Guard<Style>;
+
 /**
  * Narrow an unknown caught value to a {@link TerminalError}.
  *
@@ -758,13 +877,6 @@ export declare interface ParkRequest {
  */
 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;
 
@@ -774,6 +886,7 @@ export declare interface PasswordOptions {
     readonly mask?: string;
     readonly validate?: Validator | ValidationRules;
     readonly styler?: StylerInterface;
+    readonly theme?: PromptThemeOptions;
 }
 
 /**
@@ -798,11 +911,12 @@ export declare interface PasswordState {
     readonly mask: string;
     readonly validator: Validator;
     readonly styler: StylerInterface;
+    readonly theme: PromptTheme;
     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. */
+/** Render a {@link PasswordState} as a styled view — the header, the value masked to `mask` repeated and painted by the `content` role, and any error. */
 export declare function passwordView(state: PasswordState): string;
 
 /**
@@ -816,7 +930,7 @@ export declare function passwordView(state: PasswordState): string;
  *   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 ValidationRules} data + `choices` / `default` / `mask` / `hint` / `theme` kept — see
  *   {@link import('./helpers.js').serializePromptOptions}). A client reconstructs the validator
  *   from the rules via {@link resolveValidation}.
  * - `status` — the current {@link PendingPromptStatus}.
@@ -862,9 +976,9 @@ export declare type PendingPromptStatus = 'pending' | 'answered' | 'expired';
  *   ({@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.
+ *   the validator resolved from the original `validate` rules. A rejected answer returns a failure
+ *   `Result` with error `'rejected'` 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.
@@ -888,7 +1002,7 @@ export declare class Prompt implements PromptInterface {
     get count(): number;
     pending(): readonly PendingPrompt[];
     pending(id: string): PendingPrompt | undefined;
-    answer(id: string, value: unknown): AnswerResult;
+    answer(id: string, value: unknown): Result<unknown, AnswerError>;
     park(request: ParkRequest): Ticket;
     input(options: InputOptions): Promise<string>;
     password(options: PasswordOptions): Promise<string>;
@@ -900,11 +1014,8 @@ export declare class Prompt implements PromptInterface {
 }
 
 /**
- * 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.
+ * The six 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.
  *
  * @remarks
  * - `question` — the leading mark on a prompt's message line.
@@ -921,6 +1032,13 @@ export declare const PROMPT_ICONS: Readonly<{
     unchecked: "☐";
 }>;
 
+/**
+ * Every {@link import('./types.js').PromptRole}, in one frozen list — the role axis's source of
+ * truth. {@link import('./helpers.js').createPromptTheme} walks it to merge a partial theme, and
+ * a consumer building a complete role map reads it rather than retyping every name.
+ */
+export declare const PROMPT_ROLES: readonly PromptRole[];
+
 /** 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;
@@ -1094,8 +1212,21 @@ export declare interface PromptFormInterface {
  */
 export declare type PromptFormOptions = InputOptions | PasswordOptions | ConfirmOptions | SelectOptions | CheckboxOptions | EditorOptions;
 
-/** The styled prompt-message header (`? message`) — the leading line every active prompt view shares. */
-export declare function promptHeader(styler: StylerInterface, message: string): string;
+/** The styled prompt-message header (`? message`) — the leading line every active prompt view shares, themed by the `question` + `message` roles. */
+export declare function promptHeader(styler: StylerInterface, theme: PromptTheme, message: string): string;
+
+/**
+ * One glyph slot a prompt view renders — the icon axis of a {@link PromptTheme}. A named value
+ * set (which marks a view can draw), not a toggle, so it stays a union.
+ *
+ * @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.
+ * - `success` / `error` — the mark on a resolved prompt's submit line / its validation error line.
+ */
+export declare type PromptIcon = 'question' | 'pointer' | 'dot' | 'selected' | 'checked' | 'unchecked' | 'success' | 'error';
 
 /**
  * The headless prompt BROKER (observable §13) — implements {@link PromptFormInterface} by
@@ -1110,7 +1241,7 @@ export declare function promptHeader(styler: StylerInterface, message: string):
  *   general entry point the six form methods wrap.
  * - **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
- *   (an {@link AnswerResult} failure, the prompt stays `pending`).
+ *   (a {@link Result}<unknown, {@link AnswerError}> failure, 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.
@@ -1122,7 +1253,7 @@ export declare interface PromptInterface extends PromptFormInterface {
     park(request: ParkRequest): Ticket;
     pending(): readonly PendingPrompt[];
     pending(id: string): PendingPrompt | undefined;
-    answer(id: string, value: unknown): AnswerResult;
+    answer(id: string, value: unknown): Result<unknown, AnswerError>;
     destroy(): void;
 }
 
@@ -1149,6 +1280,27 @@ export declare interface PromptOptions {
     readonly cap?: number;
 }
 
+/**
+ * One styling slot a prompt view renders 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 the styled fragments by naming roles rather than reimplementing a view.
+ *
+ * @remarks
+ * - `question` — the leading question mark on an active prompt's line.
+ * - `pointer` — the cursor before the input / the focused choice row.
+ * - `message` — the prompt's own question text.
+ * - `content` — the prompt's primary content: the typed value, the mask run, an unfocused choice
+ *   label, a committed editor line, an in-progress editor line, or a fallback choice name. Its
+ *   default is the EMPTY style, so an unthemed prompt renders this content as bare text.
+ * - `success` / `error` — a resolved prompt's mark / a validation-error mark and its message.
+ * - `selected` — a chosen value: the checked box, the focused select marker, the confirm default letter.
+ * - `focus` — the label of the row the cursor is on.
+ * - `hint` — dim supplementary text: a default value, a key hint, a selection count, a committed answer.
+ * - `muted` — a dim off-state mark: an unfocused select marker, an unchecked box, a fallback index.
+ * - `description` — a choice's one-line description.
+ */
+export declare type PromptRole = 'question' | 'pointer' | 'message' | 'content' | 'success' | 'error' | 'selected' | 'focus' | 'hint' | 'muted' | 'description';
+
 /**
  * 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
@@ -1185,6 +1337,35 @@ export declare interface PromptStep<T, S> {
     readonly value?: T;
 }
 
+/**
+ * A prompt's resolved PRESENTATION — the glyph for every {@link PromptIcon} and the console
+ * {@link Style} for every {@link PromptRole}. Plain JSON data (no functions), so it crosses the wire
+ * with the prompt it decorates. Built by {@link import('./helpers.js').createPromptTheme}; carried
+ * resolved on every prompt state, so a view never reads a hardcoded glyph or color.
+ *
+ * @remarks
+ * A role's value is the console module's own {@link Style} — the one style model the whole console
+ * / terminal system shares — so a view paints a role through
+ * {@link StylerInterface.render} and this package holds no second style vocabulary. A `Style`
+ * carries a `foreground`, a `background`, and an attribute list, so a role can express a background
+ * color, which the styler's accessor chain cannot name.
+ */
+export declare interface PromptTheme {
+    readonly icons: Readonly<Record<PromptIcon, string>>;
+    readonly roles: Readonly<Record<PromptRole, Style>>;
+}
+
+/**
+ * The PARTIAL {@link PromptTheme} a prompt 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.
+ */
+export declare interface PromptThemeOptions {
+    readonly icons?: Readonly<Partial<Record<PromptIcon, string>>>;
+    readonly roles?: Readonly<Partial<Record<PromptRole, Style>>>;
+}
+
 /**
  * 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.
@@ -1207,7 +1388,7 @@ export declare type PromptValue = string | boolean | readonly string[];
 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)[];
+export declare function resolveChoices<TChoice extends PromptChoice | CheckboxChoice>(options: Readonly<Record<string, unknown>>, guard: Guard<TChoice>): ReadonlyArray<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;
@@ -1269,7 +1450,31 @@ export declare const RULE_MESSAGES: Readonly<{
  *   {@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)[];
+export declare function sanitizeChoiceLabels<TChoice extends PromptChoice | CheckboxChoice>(choices: ReadonlyArray<string | TChoice>): ReadonlyArray<string | TChoice>;
+
+/**
+ * Sanitize text for one single-line display slot. Composes console's {@link stripControls} pass
+ * with removal of tab, line feed, and carriage return, so no C0 control or DEL survives.
+ *
+ * @param text - The text to sanitize for a glyph or hint slot
+ * @returns The text with every C0 control character and DEL removed
+ *
+ * @example
+ * ```ts
+ * sanitizeDisplayText('Q\rOVERWRITE\nNEXT\tX') // 'QOVERWRITENEXTX'
+ * ```
+ */
+export declare function sanitizeDisplayText(text: string): string;
+
+/**
+ * Sanitize every glyph a wire-supplied {@link PromptThemeOptions} carries for a single-line display
+ * slot. Only the icons need it: a role is guard-narrowed to a console {@link Style}, whose colors
+ * and attributes are fixed name sets, so no role can carry a byte a terminal would act on.
+ *
+ * @param theme - The narrowed theme options a remote prompt supplied
+ * @returns The same theme with every supplied glyph sanitized for a single-line display slot
+ */
+export declare function sanitizeThemeIcons(theme: PromptThemeOptions): PromptThemeOptions;
 
 /**
  * Options for a single-selection {@link import('./helpers.js').selectReduce} prompt.
@@ -1277,13 +1482,17 @@ export declare function sanitizeChoiceLabels<TChoice extends PromptChoice | Chec
  * @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.
+ * the choice whose `value` matches it. `hint` adds a key hint after the message — the list is
+ * self-explanatory at a TTY, so there is no computed default; the server driver shows it on the
+ * numbered fallback too.
  */
 export declare interface SelectOptions {
     readonly message: string;
-    readonly choices: readonly (string | PromptChoice)[];
+    readonly choices: ReadonlyArray<string | PromptChoice>;
     readonly default?: string;
+    readonly hint?: string;
     readonly styler?: StylerInterface;
+    readonly theme?: PromptThemeOptions;
 }
 
 /**
@@ -1295,8 +1504,8 @@ export declare interface SelectOptions {
 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).
+ * The immutable state of a select prompt — the normalized choices, the optional hint, the
+ * resolved styler + theme, and the `focused` index (the highlighted row).
  *
  * @remarks
  * Built by {@link import('./helpers.js').createSelectState}; advanced by
@@ -1306,11 +1515,13 @@ export declare function selectReduce(state: SelectState, key: KeyEvent): PromptS
 export declare interface SelectState {
     readonly message: string;
     readonly choices: readonly PromptChoice[];
+    readonly hint?: string;
     readonly styler: StylerInterface;
+    readonly theme: PromptTheme;
     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. */
+/** Render a {@link SelectState} as a MULTI-LINE styled view — the header (plus any hint) followed by one row per choice, the focused row marked. */
 export declare function selectView(state: SelectState): string;
 
 /**
@@ -1341,7 +1552,8 @@ export declare function serializePending(prompt: PendingPrompt): WireEvent;
  * 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`
+ * `default` / `mask` / `min` / `max` / `hint` / `theme`. This is WHY T-a's validation is
+ * rules-as-data, and why a theme is data too: a `Validator`
  * FUNCTION can't be serialized, but its declarative rules can — the client rebuilds the validator
  * from them via {@link resolveValidation}.
  *
@@ -1395,8 +1607,8 @@ export declare const SSE_EVENTS: Readonly<{
     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;
+/** The styled submit line (`✔ message`) — the committed header an interactive prompt shows once resolved, themed by the `success` + `message` roles. */
+export declare function submitHeader(styler: StylerInterface, theme: PromptTheme, message: string): string;
 
 /** Tab (`\t`, U+0009). */
 export declare const TAB: string;
@@ -1404,15 +1616,6 @@ export declare const TAB: string;
 /** The rejection reason a {@link TerminalManagerInterface.answer} call returns — an {@link AnswerError}, plus `'terminal'` (no such endpoint). */
 export declare type TerminalAnswerError = AnswerError | 'terminal';
 
-/** The outcome of a {@link TerminalManagerInterface.answer} call — the accepted `value` on success, else the {@link TerminalAnswerError}. */
-export declare type TerminalAnswerResult = {
-    readonly success: true;
-    readonly value: unknown;
-} | {
-    readonly success: false;
-    readonly error: TerminalAnswerError;
-};
-
 /**
  * An error a {@link import('./Prompt.js').Prompt} broker rejects a parked prompt's Promise with.
  *
@@ -1466,9 +1669,9 @@ export declare type TerminalErrorCode = 'EXPIRE' | 'CANCEL' | 'DRIVER' | 'DEADLO
  * - **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 or a batch (§9.2, array overload FIRST), destroying
- *   each broker (which expires every prompt still parked on it). `clear` drops all; `destroy` is
- *   idempotent.
+ * - **Removal.** `remove` drops one endpoint, a batch (§9.2, array overload FIRST), or every
+ *   endpoint when called without an argument. It destroys each broker, which expires every prompt
+ *   still parked on it. `destroy` is idempotent.
  *
  * @example
  * ```ts
@@ -1493,12 +1696,12 @@ export declare class TerminalManager implements TerminalManagerInterface {
     ask(from: string, to: string, form: 'checkbox', options: CheckboxOptions): Promise<readonly string[]>;
     pending(): readonly PendingPrompt[];
     pending(to: string): readonly PendingPrompt[];
-    answer(to: string, id: string, value: unknown): TerminalAnswerResult;
+    answer(to: string, id: string, value: unknown): Result<unknown, TerminalAnswerError>;
     open(name: string): Promise<PromptInterface | undefined>;
     save(name: string): Promise<boolean>;
     remove(names: readonly string[]): boolean;
     remove(name: string): boolean;
-    clear(): void;
+    remove(): void;
     destroy(): void;
 }
 
@@ -1536,9 +1739,9 @@ export declare type TerminalManagerEventMap = {
  * - **`save`** persists an endpoint's config snapshot to the `store` (`false` when there is no
  *   store, or `name` is unknown).
  * - **Batch `remove` (§9.2).** The array overload is declared FIRST — `remove(names)` removes each
- *   listed endpoint (`true` when any of the named terminals was removed); `remove(name)` removes one.
- * - **`clear`** removes every endpoint without destroying the manager; **`destroy`** tears down
- *   every broker, then the manager's own emitter.
+ *   listed endpoint (`true` when any named terminal was removed); `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 {
     readonly emitter: EmitterInterface<TerminalManagerEventMap>;
@@ -1552,12 +1755,12 @@ export declare interface TerminalManagerInterface {
     ask(from: string, to: string, form: 'checkbox', options: CheckboxOptions): Promise<readonly string[]>;
     pending(): readonly PendingPrompt[];
     pending(to: string): readonly PendingPrompt[];
-    answer(to: string, id: string, value: unknown): TerminalAnswerResult;
+    answer(to: string, id: string, value: unknown): Result<unknown, TerminalAnswerError>;
     open(name: string): Promise<PromptInterface | undefined>;
     save(name: string): Promise<boolean>;
     remove(names: readonly string[]): boolean;
     remove(name: string): boolean;
-    clear(): void;
+    remove(): void;
     destroy(): void;
 }
 
@@ -1631,7 +1834,10 @@ export { TimerHandler_2 as TimerHandler }
 /** 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. */
+/**
+ * Matches an HTTP(S) URL. The `url` rule tests against this. Kept locally because it is
+ * narrower than `FORMAT_PATTERNS.uri`, which accepts other URI schemes.
+ */
 export declare const URL_PATTERN: RegExp;
 
 /**