@orkestrel/terminal 0.0.8 → 0.0.10

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

@@ -1,10 +1,14 @@
-import { CheckboxOptions } from '@orkestrel/terminal';
-import { ConfirmOptions } from '@orkestrel/terminal';
-import { EditorOptions } from '@orkestrel/terminal';
-import { InputOptions } from '@orkestrel/terminal';
-import { PasswordOptions } from '@orkestrel/terminal';
-import { PromptFormInterface } from '@orkestrel/terminal';
-import { SelectOptions } from '@orkestrel/terminal';
+import { FieldChoice } from '@orkestrel/form';
+import { FieldControl } from '@orkestrel/form';
+import { FieldValue } from '@orkestrel/form';
+import { FormField } from '@orkestrel/form';
+import { FormInterface } from '@orkestrel/form';
+import { FormValues } from '@orkestrel/form';
+import { PromptTheme } from '@orkestrel/terminal';
+import { PromptThemeOptions } from '@orkestrel/terminal';
+import { StylerInterface } from '@orkestrel/console';
+import { TerminalInterface } from '@orkestrel/terminal';
+import { TextField } from '@orkestrel/form';
 
 /** A carriage return (`\r`, U+000D) — returns the cursor to column 0 so a redraw starts at the line's left edge. */
 export declare const CARRIAGE_RETURN: string;
@@ -17,39 +21,55 @@ export declare const CARRIAGE_RETURN: string;
 export declare const CLEAR_DOWN: string;
 
 /**
- * Create the interactive terminal prompt {@link TerminalInterface} (T-c) — the local-TTY arm of the
- * prompt tri-surface, the env-symmetric sibling of the core headless `createPrompt` broker and the
- * SSE `createPromptClient` bridge. A `Terminal` answers each prompt LOCALLY at this machine's
- * keyboard: it reads raw-mode stdin, drives the pure core `*Reduce` reducers, renders each `view` in
- * place, and resolves on submit / rejects with a {@link import('@src/core').TerminalError} (`CANCEL`)
- * on ctrl-c. It is the ONLY impure part of the prompt stack.
+ * The format cue appended to a field's label for each control the walk reads as a line of text —
+ * the terminal has no date picker, no color well, and no file chooser, so the accepted shape is
+ * stated instead. A control with no entry needs none: `text` and `editor` accept any line,
+ * `password` masks one, and `confirm`, `select`, and `checkbox` are answered by key rather than by
+ * format. The form's own rules still decide whether the typed value is acceptable.
+ */
+export declare const CONTROL_HINTS: Readonly<Partial<Record<FieldControl, string>>>;
+
+/**
+ * Create the interactive terminal form driver — the local-keyboard arm of the terminal trio, beside
+ * the core headless `createPrompt` broker and the SSE `createPromptClient` bridge. Where the broker
+ * PARKS a live form until somebody elsewhere answers it, a `Terminal` answers one HERE: it walks the
+ * form's fields in schema order, drives each control's pure reducer over raw-mode stdin, binds every
+ * answer through the form's own `fill`, and submits. It is the only impure part of the terminal
+ * stack.
  *
  * @param options - See {@link TerminalOptions}
- * @returns A {@link TerminalInterface} — the six async prompt forms (`input` / `password` / `confirm`
- *   / `select` / `checkbox` / `editor`) driven over the resolved streams
+ * @returns A {@link TerminalInterface} whose `ask` drives one whole form over the resolved streams
  *
  * @remarks
- * - **Drives the pure reducers.** Each prompt builds its initial state (`create*State`), enters raw
- *   mode ONCE, and feeds each keypress through `parseKey` → the reducer → an in-place re-render; the
- *   driver owns no prompt logic itself (state / view / validation / cancel all come from the core).
- * - **Raw-mode leak-free.** Raw mode is entered exactly once per prompt and ALWAYS cleaned up — on
- *   submit, on cancel, and on a throw — leaving no raw mode and no leaked `'data'` listener.
- * - **Injectable + guard-narrowed.** `options.input` / `options.output` default to `process.stdin` /
- *   `process.stdout` but accept ANY {@link import('./types.js').InputStreamInterface} /
- *   {@link import('./types.js').OutputStreamInterface}, resolved through their §14 guards (never an
- *   `as`), so a test drives every prompt with a fake TTY that emits scripted key chunks and records
- *   the rendered output — and asserts the resolved value, cancel-on-ctrl-c, and no leaked raw mode.
- * - **Non-TTY fallback.** When `input` is not a TTY (piped), raw mode is unavailable, so the prompts
- *   fall back to `node:readline` line input (still validating); `select` / `checkbox` present a
- *   numbered list, and `editor` reads lines until EOF.
+ * - **The form is the unit.** `ask` takes the caller's live form and returns its settled values. The
+ *   returned promise is that form's own `answer`, so a caller holding the form can await either one.
+ * - **Every control renders.** Seven controls are read as a line of text with their format cue,
+ *   `password` masks, `confirm` takes a key, `editor` takes a block, `select` and `checkbox` drive a
+ *   list, and an open `select` accepts a value its list does not offer.
+ * - **The form decides.** A blank answer binds as absence, the form evaluates, and a refusal
+ *   re-walks only the fields the walk can still edit.
+ * - **Injectable and guard-narrowed.** `input` and `output` default to `process.stdin` and
+ *   `process.stdout` but accept any stream of the declared minimal shape, resolved through their
+ *   guards rather than an assertion, so a test drives a whole form with a fake TTY that emits
+ *   scripted key chunks and records every rendered byte.
+ * - **Non-TTY fallback.** A piped stream cannot enter raw mode, so the same walk runs over
+ *   `node:readline` line input.
  *
  * @example
  * ```ts
- * import { createTerminal } from '@src/server'
+ * import { createForm } from '@orkestrel/form'
+ * import { createTerminal } from '@orkestrel/terminal/server'
  *
  * const terminal = createTerminal()
- * const name = await terminal.input({ message: 'Your name' })
- * const proceed = await terminal.confirm({ message: 'Continue?', default: true })
+ * const values = await terminal.ask(
+ * 	createForm({
+ * 		label: 'Sign up',
+ * 		fields: [
+ * 			{ control: 'text', name: 'email', label: 'Email', rule: { required: true, email: true } },
+ * 			{ control: 'confirm', name: 'terms', label: 'I accept the terms' },
+ * 		],
+ * 	}),
+ * )
  * ```
  */
 export declare function createTerminal(options?: TerminalOptions): TerminalInterface;
@@ -59,8 +79,8 @@ export declare const CSI: string;
 
 /**
  * The cursor-UP sequence TEMPLATE (`ESC[{count}A`) — {@link import('./helpers.js').moveUp}
- * interpolates `{count}` with the number of lines to climb (the `{count}` placeholder idiom the core
- * terminals' `RULE_MESSAGES` uses). Kept as a template so the count stays out of the constant.
+ * interpolates the `{count}` placeholder with the number of lines to climb. Kept as a template so
+ * the count stays out of the constant.
  */
 export declare const CSI_UP: string;
 
@@ -73,42 +93,88 @@ export declare const CURSOR_HIDE: string;
 /** Show the cursor (`ESC[?25h`) — restores the cursor after a prompt resolves / cancels (the {@link CURSOR_HIDE} pair). */
 export declare const CURSOR_SHOW: string;
 
+/**
+ * The choices a `select` or `checkbox` field SHOWS but refuses — the complement of
+ * {@link enabledChoices}, rendered by {@link unavailableLine} above the list so a reader sees why a
+ * declared choice is missing from it.
+ *
+ * @param choices - The field's declared choices
+ * @returns The refused choices, in declared order
+ */
+export declare function disabledChoices(choices: readonly FieldChoice[]): readonly FieldChoice[];
+
+/**
+ * The choices a `select` or `checkbox` field actually OFFERS — the form refuses a disabled choice's
+ * value at every door, including a fill, so the walk never puts one in front of the cursor. Pair
+ * with {@link disabledChoices} to tell the reader what was withheld.
+ *
+ * @param choices - The field's declared choices
+ * @returns The choices the walk offers, in declared order
+ */
+export declare function enabledChoices(choices: readonly FieldChoice[]): readonly FieldChoice[];
+
 /** The Escape byte (ESC, U+001B) — the lead byte of every CSI cursor-control sequence below. */
 export declare const ESCAPE: string;
 
 /** The comma-separated multi-select hint the non-TTY `checkbox` fallback shows (the user types one or more numbers). */
 export declare const FALLBACK_CHECKBOX_HINT = "Enter numbers separated by commas";
 
+/** The hint the non-TTY `confirm` fallback shows — a piped stream sends a whole line, so the answer is typed rather than pressed. */
+export declare const FALLBACK_CONFIRM_HINT = "(y/n)";
+
+/** The hint the non-TTY `editor` fallback shows — a piped stream has no ctrl-d, so end of input finishes the block. */
+export declare const FALLBACK_EDITOR_HINT = "(end of input finishes)";
+
 /**
- * The numbered-list prompt the non-TTY {@link import('./Terminal.js').Terminal} `select` / `checkbox`
- * fallback appends — a piped (non-terminal) stream cannot navigate with arrow keys, so the choices are
- * printed numbered and the user types the number(s) on a single readline line.
+ * The numbered-list prompt the non-TTY {@link import('./Terminal.js').Terminal} `select` fallback
+ * appends — a piped (non-terminal) stream cannot navigate with arrow keys, so the choices are
+ * printed numbered and the user types one number on a single readline line.
  */
 export declare const FALLBACK_SELECT_HINT = "Enter a number";
 
 /**
- * The minimal input-stream shape the {@link TerminalInterface} reads — exactly the slice of a Node
- * `tty.ReadStream` / `process.stdin` it touches, and no more (AGENTS §21 — minimal interface). A
- * {@link TerminalOptions} `input` is narrowed to this via
- * {@link import('./helpers.js').isInputStream} (AGENTS §14 — narrow the boundary, never `as`), so a
- * test drives every prompt with a hand-built fake stream that emits scripted key chunks and never
- * touches the real `process.stdin` — and asserts raw mode is entered exactly once and always
- * cleaned up (no leak).
+ * Project any field the walk reads as a LINE OF TEXT into the {@link TextField} the text reducer
+ * takes — `text` itself, and the six controls a terminal has no widget for: `number`, `date`,
+ * `time`, `datetime`, `color`, and one `file` entry. The label carries that control's format cue
+ * from {@link CONTROL_HINTS}, and a declared `default` becomes the line a bare return submits. The
+ * projection carries no rule, because the AUTHORITATIVE form still evaluates the answer this line
+ * binds; it exists only so one reducer can render seven controls.
+ *
+ * @param field - The field being read
+ * @returns The text field the reducer renders for it
+ *
+ * @example
+ * ```ts
+ * fieldToText({ control: 'date', name: 'born', label: 'Birthday' })
+ * // { control: 'text', name: 'born', label: 'Birthday (YYYY-MM-DD)' }
+ * ```
+ */
+export declare function fieldToText(field: FormField): TextField;
+
+/** The instruction a `file` field with `multiple` shows before its entries — one path per line, and a blank line ends the list. */
+export declare const FILE_HINT = "One path per line, blank to finish";
+
+/** The section header the walk writes when it enters a new field group, painted by the `message` role. */
+export declare function groupHeader(styler: StylerInterface, theme: PromptTheme, label: string): string;
+
+/**
+ * The minimal input-stream shape the driver reads — exactly the slice of a Node `tty.ReadStream` /
+ * `process.stdin` it touches, and no more. A {@link TerminalOptions} `input` is narrowed to this
+ * through {@link import('./helpers.js').isInputStream}, never an assertion, so a test drives a whole
+ * form with a hand-built fake stream that emits scripted key chunks, never touches the real
+ * `process.stdin`, and asserts that raw mode is entered once and always cleaned up.
  *
  * @remarks
  * - `on(event, listener)` / `off(event, listener)` — subscribe / unsubscribe a `'data'` chunk
- *   listener (the irreducible event seam; a `Buffer` / string / `Uint8Array` chunk arrives). The two
- *   required methods.
- * - `setRawMode(mode)` — switch the TTY in / out of raw mode (each keypress delivered immediately,
- *   no line buffering, no echo). Present on a real `tty.ReadStream`; ABSENT on a piped, non-TTY
- *   stream — its absence (or `isTTY !== true`) selects the {@link import('node:readline').Interface}
- *   line-input fallback. The ONLY place raw mode is touched is {@link import('./Terminal.js').Terminal}'s
- *   `#enterRaw`.
- * - `resume()` / `pause()` — start / stop the flow of `'data'` events. The raw-mode primitive
- *   `resume()`s on enter and `pause()`s on cleanup; optional (a fake may omit them).
- * - `isTTY` — `true` on a real terminal, absent / `false` when piped to a file or another process.
- *   The driver reads it to choose the raw-mode path (interactive arrow-key prompts) vs. the readline
- *   fallback (numbered / line input).
+ *   listener (the irreducible event seam; a `Buffer`, string, or `Uint8Array` chunk arrives). The
+ *   two required methods.
+ * - `setRawMode(mode)` — switch the TTY in and out of raw mode (each keypress delivered
+ *   immediately, no line buffering, no echo). Present on a real `tty.ReadStream`; ABSENT on a
+ *   piped, non-TTY stream, and its absence (or `isTTY !== true`) selects the
+ *   {@link import('node:readline').Interface} line-input fallback.
+ * - `resume()` / `pause()` — start / stop the flow of `'data'` events. Raw mode `resume()`s on
+ *   enter and `pause()`s on cleanup; both are optional, so a fake may omit them.
+ * - `isTTY` — `true` on a real terminal, absent or `false` when piped to a file or another process.
  */
 export declare interface InputStreamInterface {
     on(event: 'data', listener: (chunk: string | Uint8Array) => void): void;
@@ -160,17 +226,6 @@ export declare function isOutputStream(value: unknown): value is OutputStreamInt
  */
 export declare function isReadable(value: unknown): value is NodeJS.ReadableStream;
 
-/**
- * Whether `value` is a Node {@link NodeJS.WritableStream} — a total structural guard (AGENTS §14)
- * checking for the callable `write` / `end` that `node:readline`'s `createInterface` accepts as its
- * `output`. Paired with {@link isReadable} so the non-TTY fallback narrows BOTH streams to the
- * readline boundary without an `as`. Never throws.
- *
- * @param value - The resolved output stream (or any value crossing the boundary)
- * @returns `true` when `value` has the writable methods readline needs
- */
-export declare function isWritable(value: unknown): value is NodeJS.WritableStream;
-
 /** A line feed (`\n`, U+000A) — the line terminator the driver writes after the final committed prompt view. */
 export declare const LINE_FEED: string;
 
@@ -185,6 +240,22 @@ export declare const LINE_FEED: string;
  */
 export declare function lineCount(view: string): number;
 
+/** The mark on a locked field's line — the walk renders its value and moves on, because the form refuses an edit there. */
+export declare const LOCKED_MARK = "(locked)";
+
+/**
+ * The read-only line a LOCKED field renders — its label, the {@link LOCKED_MARK}, and the answer the
+ * form already holds. The walk writes this instead of a prompt, because the field is still
+ * validated and still submitted but must not be edited here.
+ *
+ * @param styler - The console styler that renders each role
+ * @param theme - The resolved prompt theme
+ * @param label - The field's label
+ * @param value - The held answer, from {@link valueToText}
+ * @returns The rendered line, with no trailing space when there is nothing to show
+ */
+export declare function lockedLine(styler: StylerInterface, theme: PromptTheme, label: string, value: string): string;
+
 /**
  * The cursor-UP control sequence that moves the cursor up `count` lines (`ESC[{count}A`) — or the
  * empty string when `count` is zero or negative (no movement needed, and `ESC[0A` is a wasted write).
@@ -197,19 +268,29 @@ export declare function lineCount(view: string): number;
 export declare function moveUp(count: number): string;
 
 /**
- * The minimal output-stream shape the {@link TerminalInterface} writes — exactly the slice of a Node
- * `tty.WriteStream` / `process.stdout` it touches (AGENTS §21). A {@link TerminalOptions} `output`
- * is narrowed to this via {@link import('./helpers.js').isOutputStream} (AGENTS §14), so a test
- * records every byte the driver renders (the prompt view, the cursor-management sequences) with a
- * fake stream and asserts the rendered content (ANSI stripped) and the resolved value.
+ * The numbered choice list the non-TTY fallback prints — a piped stream cannot navigate with arrow
+ * keys, so each offered choice is printed with the number the reader types back. One line per
+ * choice, with no trailing newline.
+ *
+ * @param styler - The console styler that renders each role
+ * @param theme - The resolved prompt theme
+ * @param choices - The choices the walk offers, from {@link enabledChoices}
+ * @returns The rendered list
+ */
+export declare function numberedList(styler: StylerInterface, theme: PromptTheme, choices: readonly FieldChoice[]): string;
+
+/**
+ * The minimal output-stream shape the driver writes — exactly the slice of a Node `tty.WriteStream`
+ * / `process.stdout` it touches. A {@link TerminalOptions} `output` is narrowed to this through
+ * {@link import('./helpers.js').isOutputStream}, never an assertion, so a test records every byte
+ * the walk renders and asserts the rendered content with the ANSI stripped.
  *
  * @remarks
- * - `write(text)` — the one required method: push a chunk (a rendered prompt view, a cursor / clear
- *   escape sequence) to the stream. A real stream returns a backpressure boolean; the driver ignores
- *   the return (a prompt is human-paced, never backpressured), so a fake may return `void`.
- * - `isTTY` — present and `true` on a real terminal. The driver does not branch its rendering on it
- *   (the styler already decided color); it is part of the minimal shape for symmetry with the input
- *   stream and so a consumer may inspect it.
+ * - `write(text)` — the one required method: push a chunk (a rendered field view, a group header, a
+ *   cursor or clear sequence) to the stream. A real stream returns a backpressure boolean; the
+ *   driver ignores the return, because a prompt is human-paced, so a fake may return `void`.
+ * - `isTTY` — present and `true` on a real terminal. The driver does not branch its rendering on
+ *   it; the styler already decided color.
  */
 export declare interface OutputStreamInterface {
     write(text: string): boolean | void;
@@ -248,74 +329,96 @@ export declare function rawCapable(input: InputStreamInterface): boolean;
 export declare function redrawPrefix(previousLines: number): string;
 
 /**
- * The interactive terminal prompt driver (T-c) — the third {@link TerminalInterface} surface (beside
- * the core headless `Prompt` broker and the SSE `PromptClient` bridge), and the ONLY impure part of
- * the prompt stack. It reads the TTY and DRIVES the pure core `*Reduce` reducers: it feeds raw-mode
- * stdin bytes through `parseKey` into the matching reducer, renders the returned `view` in place, and
- * resolves on a `submit` step / rejects with a {@link TerminalError} (`CANCEL`) on ctrl-c. It owns no
- * prompt logic of its own — state, view, validation, and the cancel signal all come from the pure
- * core; this class owns ONLY the cursor + raw-mode + in-place re-render mechanics.
- *
- * @remarks
- * See {@link TerminalInterface} for the behavioral contract (raw-mode leak-freedom, the in-place
- * re-render, the non-TTY readline fallback, event-free).
+ * What a field is told when the walk read an answer the control cannot hold — a word typed into a
+ * `number`, an off-list value typed into an open `select` whose choice is refused. The value binds
+ * as absence and this message is invalidated onto the field, so the walk re-asks it with the reason
+ * on screen.
  */
-export declare class Terminal implements TerminalInterface {
-    #private;
-    constructor(options?: TerminalOptions);
-    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>;
-}
+export declare const REFUSAL_MESSAGE = "Enter a value this field accepts";
+
+/** The lead on the line listing an open `select`'s offered values, which a typed answer may ignore. */
+export declare const SUGGESTION_LEAD = "Suggestions";
+
+/** The line listing an OPEN select's offered values above its text prompt — a suggestion list, because an open select admits an answer the list does not offer. */
+export declare function suggestionLine(styler: StylerInterface, theme: PromptTheme, choices: readonly FieldChoice[]): string;
 
 /**
- * The interactive terminal prompt DRIVER (the third {@link PromptFormInterface} surface) — reads the
- * TTY and DRIVES the pure core `*Reduce` reducers, the ONLY impure part of the prompt stack. Where
- * the core `Prompt` broker PARKS each prompt and the `PromptClient` bridges one over SSE, a
- * `Terminal` answers each prompt LOCALLY at this machine's keyboard: it feeds raw-mode stdin bytes
- * through `parseKey` into the matching reducer, renders the returned `view` in place (tracking the
- * previous view's line count to overwrite it), and resolves on a `submit` step / rejects with a
- * {@link import('@src/core').TerminalError} (`CANCEL`) on ctrl-c.
+ * The interactive terminal form DRIVER — the {@link TerminalInterface} implementation for a human at
+ * this machine's keyboard, and the only impure part of the terminal stack. {@link ask} walks one
+ * form's fields in schema order, feeds raw-mode stdin bytes through `parseKey` into the matching
+ * pure reducer, renders each returned view in place, and binds every answer through the form's own
+ * `fill`. It owns no form logic: the schema, the rules, the values, and the settlement all belong to
+ * the form it is given, and this class owns only raw mode, the cursor, and the re-render.
  *
  * @remarks
- * - **Drives the pure reducers.** Each method builds the initial state (`create*State(options)`),
- *   enters raw mode once, and on each keypress runs `parseKey` → the reducer → an in-place re-render;
- *   it owns NO prompt logic of its own (state, view, validation, and the cancel signal all come from
- *   the pure core).
- * - **Raw-mode leak-free.** Raw mode is entered exactly once per prompt and ALWAYS cleaned up — on
- *   submit, on cancel, and on a throw — leaving no raw mode and no leaked `'data'` listener.
- * - **In-place re-render.** Between keystrokes the cursor is moved up over the previous view's lines,
- *   the screen cleared down, and the new view written — so a `select` / `checkbox` list redraws live;
- *   the cursor is hidden during the prompt and restored after.
- * - **Non-TTY fallback.** When `input` is not a TTY, raw mode is unavailable, so the prompts fall
- *   back to `node:readline` line input (still validating) — `select` / `checkbox` present a numbered
- *   list read via a readline line, and `editor` reads lines until EOF.
- * - **Event-free.** A `Terminal` is a request / response driver — each prompt is a Promise; there is
- *   no observable lifecycle worth an emitter, so (unlike the broker / bridge) it carries none.
+ * See {@link TerminalInterface} for the driving contract. The walk itself:
+ *
+ * - **Twelve controls, seven reducers.** `text`, `number`, `date`, `time`, `datetime`, `color`, and
+ *   each `file` entry are read as one line of text through {@link fieldToText}, which appends that
+ *   control's format cue to the label. `password`, `confirm`, `editor`, `select`, and `checkbox`
+ *   each drive their own reducer. An open `select` is a suggestion list plus a typed line, because
+ *   `open` means the answer need not come from the list.
+ * - **The binding projects through `matchesAnswer`.** Every answer is filled as
+ *   `fill(name, matchesAnswer(value) ? value : undefined)` after `parseValue` has coerced it to the
+ *   control's own shape, so a bare return on a field with no default binds as ABSENCE and the
+ *   form's `required` rule refuses it. A typed answer the control cannot hold binds as absence and
+ *   invalidates the field, so the walk asks again with the reason on screen.
+ * - **Visibility is honored.** A `hidden` field and a field currently in `form.disabled` are
+ *   skipped; a `locked` field renders read-only; entering a new group writes its label as a section
+ *   header.
+ * - **Refusal re-asks.** After the walk the form is submitted. A refusal re-walks only the erroring
+ *   fields the walk can edit and submits again. When every erroring field is one the walk cannot
+ *   edit — hidden, locked, or disabled — the form is abandoned instead, because asking again could
+ *   not change the answer.
+ * - **Raw-mode leak-free.** Raw mode is entered once per field and always cleaned up: on submit, on
+ *   cancel, on a throw, and when the form is abandoned under an active read.
+ * - **Non-TTY fallback.** When `input` is not a TTY, the same walk runs over `node:readline` line
+ *   input: `select` and `checkbox` print a numbered list, and `editor` reads to end of input.
  */
-export declare interface TerminalInterface extends PromptFormInterface {
+export declare class Terminal implements TerminalInterface {
+    #private;
+    constructor(options?: TerminalOptions);
+    ask(form: FormInterface): Promise<FormValues>;
 }
 
 /**
- * Options for {@link import('./factories.js').createTerminal} — both streams optional, so a bare
- * `createTerminal()` drives the real `process.stdin` / `process.stdout`.
+ * Options for {@link import('./factories.js').createTerminal} — every member optional, so a bare
+ * `createTerminal()` walks a form over the real `process.stdin` / `process.stdout` with the default
+ * theme.
  *
  * @remarks
  * - `input` — the stream keystrokes are read from; defaults to `process.stdin`. Any
- *   {@link InputStreamInterface}-shaped stream is accepted (resolved through
- *   {@link import('./helpers.js').isInputStream}, never `as`), so a test injects a fake TTY that
- *   emits scripted `'data'` chunks. When the stream is not a TTY (no `setRawMode` / `isTTY !== true`),
- *   the prompts fall back to `node:readline` line input.
- * - `output` — the stream the prompt view is rendered to; defaults to `process.stdout`. Any
- *   {@link OutputStreamInterface}-shaped stream is accepted (resolved through
- *   {@link import('./helpers.js').isOutputStream}), so a test records the rendered output.
+ *   {@link InputStreamInterface}-shaped stream is accepted, resolved through
+ *   {@link import('./helpers.js').isInputStream}, so a test injects a fake TTY that emits scripted
+ *   `'data'` chunks. A stream that is not a TTY falls back to `node:readline` line input.
+ * - `output` — the stream each view is rendered to; defaults to `process.stdout`. Any
+ *   {@link OutputStreamInterface}-shaped stream is accepted, resolved through
+ *   {@link import('./helpers.js').isOutputStream}, so a test records the rendered output.
+ * - `theme` — the glyphs and role styles every rendered line is painted with, merged over
+ *   {@link import('@src/core').DEFAULT_PROMPT_THEME} leaf by leaf by
+ *   {@link import('@src/core').createPromptTheme}. Supplying one icon or one role leaves every
+ *   other slot at its default.
  */
 export declare interface TerminalOptions {
     readonly input?: InputStreamInterface;
     readonly output?: OutputStreamInterface;
+    readonly theme?: PromptThemeOptions;
 }
 
+/** The lead on the line listing the choices a `select` or `checkbox` shows but refuses, so a reader sees why one is missing from the list below. */
+export declare const UNAVAILABLE_LEAD = "Unavailable";
+
+/** The line naming the choices a field shows but refuses, written above the list the walk drives. */
+export declare function unavailableLine(styler: StylerInterface, theme: PromptTheme, choices: readonly FieldChoice[]): string;
+
+/**
+ * Project one held answer into the text a read-only line shows — a scalar as itself, a boolean as
+ * `yes` / `no` (the word the confirm reducer commits), and a list joined by commas. Absence renders
+ * as nothing, because a locked field nobody has answered has nothing to show.
+ *
+ * @param value - The answer the form holds for a field, or absence
+ * @returns The text to render for it
+ */
+export declare function valueToText(value: FieldValue | undefined): string;
+
 export { }