@orkestrel/terminal 0.0.13 → 0.0.15

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

@@ -1,27 +1,25 @@
-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;
+import type { FieldChoice } from '@orkestrel/form';
+import type { FieldControl } from '@orkestrel/form';
+import type { FieldValue } from '@orkestrel/form';
+import type { FormField } from '@orkestrel/form';
+import type { FormInterface } from '@orkestrel/form';
+import type { FormValues } from '@orkestrel/form';
+import type { PromptTheme } from '@orkestrel/terminal';
+import type { PromptThemeOptions } from '@orkestrel/terminal';
+import type { StreamTargetInterface } from '@orkestrel/console/server';
+import type { StylerInterface } from '@orkestrel/console';
+import type { TerminalInterface } from '@orkestrel/terminal';
+import type { TextField } from '@orkestrel/form';
 
 /**
- * Erase from the cursor down to the end of the screen (`ESC[J`) — wipes the WHOLE previous (possibly
- * multi-line `select` / `checkbox`) view in one write before the new view is rendered, so a redraw
- * never leaves orphaned rows below.
+ * Erases from the cursor down to the end of the screen (`ESC[J`) — wipes the whole previous view,
+ * which a `select` or `checkbox` can spread over several lines, in one write before the new view is
+ * rendered, so a redraw never leaves orphaned rows behind.
  */
 export declare const CLEAR_DOWN: string;
 
 /**
- * The format cue appended to a field's label for each control the walk reads as a line of text —
+ * Holds 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
@@ -30,12 +28,12 @@ export declare const CLEAR_DOWN: string;
 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.
+ * Creates 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} whose `ask` drives one whole form over the resolved streams
@@ -43,7 +41,7 @@ export declare const CONTROL_HINTS: Readonly<Partial<Record<FieldControl, string
  * @remarks
  * - **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,
+ * - **Every control renders.** The line-read 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
@@ -55,90 +53,82 @@ export declare const CONTROL_HINTS: Readonly<Partial<Record<FieldControl, string
  * - **Non-TTY fallback.** A piped stream cannot enter raw mode, so the same walk runs over
  *   `node:readline` line input.
  *
- * @example
+ * @example Ask one form at this keyboard
  * ```ts
  * import { createForm } from '@orkestrel/form'
+ * import { isTerminalError } from '@orkestrel/terminal'
  * import { createTerminal } from '@orkestrel/terminal/server'
  *
- * const terminal = createTerminal()
- * 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' },
- * 		],
- * 	}),
- * )
+ * const terminal = createTerminal() // process.stdin / process.stdout by default
+ * const form = createForm({
+ * 	label: 'Sign up',
+ * 	fields: [
+ * 		{ control: 'text', name: 'name', label: 'Your name', rule: { required: true, minimum: 2 } },
+ * 		{ control: 'text', name: 'email', label: 'Email', rule: { required: true, email: true } },
+ * 		{ control: 'password', name: 'token', label: 'Token' },
+ * 		{ control: 'confirm', name: 'terms', label: 'Accept the terms', rule: { required: true } },
+ * 		{
+ * 			control: 'select',
+ * 			name: 'role',
+ * 			label: 'Role',
+ * 			choices: [
+ * 				{ value: 'admin', label: 'Admin' },
+ * 				{ value: 'viewer', label: 'Viewer', help: 'read-only' },
+ * 			],
+ * 		},
+ * 	],
+ * })
+ *
+ * try {
+ * 	const values = await terminal.ask(form)
+ * 	deploy(values)
+ * } catch (error) {
+ * 	// Ctrl-c: the walk ended, and the form is still `editing` for whoever owns it.
+ * 	if (isTerminalError(error) && error.code === 'CANCEL') form.destroy()
+ * }
  * ```
  */
 export declare function createTerminal(options?: TerminalOptions): TerminalInterface;
 
-/** The Control Sequence Introducer (`ESC[`) — the prefix of every cursor / erase sequence. */
-export declare const CSI: string;
-
 /**
- * The cursor-UP sequence TEMPLATE (`ESC[{count}A`) — {@link import('./helpers.js').moveUp}
- * interpolates the `{count}` placeholder with the number of lines to climb. Kept as a template so
- * the count stays out of the constant.
+ * Holds the cursor-up sequence template (`ESC[{count}A`) —
+ * {@link import('./helpers.js').renderCursorUp} 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;
 
 /**
- * Hide the cursor (`ESC[?25l`) — written before the driver starts redrawing a prompt so the cursor
+ * Hides the cursor (`ESC[?25l`) — written before the driver starts redrawing a prompt so the cursor
  * does not flicker across the view during an in-place re-render; paired with {@link CURSOR_SHOW}.
  */
 export declare const CURSOR_HIDE: string;
 
-/** Show the cursor (`ESC[?25h`) — restores the cursor after a prompt resolves / cancels (the {@link CURSOR_HIDE} pair). */
+/** Shows 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). */
+/** Holds 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. */
+/** Holds 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. */
+/** Holds 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` fallback
+ * Holds 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";
 
 /**
- * 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.
+ * Projects any field the walk reads as a line of text into the {@link TextField} the text reducer
+ * takes — `text` itself, and the 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 covers every one of them.
  *
  * @param field - The field being read
  * @returns The text field the reducer renders for it
@@ -151,14 +141,31 @@ export declare const FALLBACK_SELECT_HINT = "Enter a number";
  */
 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. */
+/** Holds 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;
+/**
+ * Returns the choices a `select` or `checkbox` field shows but refuses — the complement of
+ * {@link filterEnabled}, rendered by {@link renderUnavailableLine} 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 filterDisabled(choices: readonly FieldChoice[]): readonly FieldChoice[];
+
+/**
+ * Returns 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 filterDisabled} 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 filterEnabled(choices: readonly FieldChoice[]): readonly FieldChoice[];
 
 /**
- * The minimal input-stream shape the driver reads — exactly the slice of a Node `tty.ReadStream` /
+ * Represents 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
@@ -167,7 +174,7 @@ export declare function groupHeader(styler: StylerInterface, theme: PromptTheme,
  * @remarks
  * - `on(event, listener)` / `off(event, listener)` — subscribe / unsubscribe a `'data'` chunk
  *   listener (the irreducible event seam; a `Buffer`, string, or `Uint8Array` chunk arrives). The
- *   two required methods.
+ *   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
@@ -177,195 +184,202 @@ export declare function groupHeader(styler: StylerInterface, theme: PromptTheme,
  * - `isTTY` — `true` on a real terminal, absent or `false` when piped to a file or another process.
  */
 export declare interface InputStreamInterface {
+    /** Subscribes a `'data'` chunk listener — the irreducible event seam. */
     on(event: 'data', listener: (chunk: string | Uint8Array) => void): void;
+    /** Unsubscribes that listener. The driver always pairs it, so no listener leaks. */
     off(event: 'data', listener: (chunk: string | Uint8Array) => void): void;
+    /** Switches the TTY in and out of raw mode. Absent on a piped stream. */
     setRawMode?(mode: boolean): void;
+    /** Starts the flow of `'data'` events. */
     resume?(): void;
+    /** Stops it again on cleanup. */
     pause?(): void;
+    /** Reports whether the stream is a real terminal; absent or false when piped. */
     readonly isTTY?: boolean;
 }
 
 /**
- * Whether `value` is a usable {@link InputStreamInterface} — a record with callable `on` / `off`
- * `'data'` subscription methods. A total type guard (AGENTS §14): it NEVER throws and returns `false`
- * for anything off-shape, so it narrows the one unavoidable input boundary (the real `process.stdin`,
- * or a fake TTY a test injects) to the exact slice the driver reads — no `as`.
+ * Checks whether `value` is a usable {@link InputStreamInterface} — a record with callable `on` /
+ * `off` `'data'` subscription methods. A total type guard: it never throws and returns `false` for
+ * anything off-shape, so it narrows the one unavoidable input boundary (the real `process.stdin`,
+ * or a fake TTY a test injects) to the exact slice the driver reads, never an assertion.
  *
  * @remarks
  * Only `on` / `off` are required (the irreducible event seam); `setRawMode` / `resume` / `pause` /
  * `isTTY` are optional on {@link InputStreamInterface}, so their absence does not disqualify a stream
- * — a piped, non-TTY stream is still a valid input, just one the driver reads through the readline
+ * — a piped, non-TTY stream is still a valid input, one the driver reads through the readline
  * fallback rather than raw mode.
  *
  * @param value - Any value crossing the boundary (a process stream, an injected fake, `unknown`)
- * @returns `true` when `value` has callable `on` and `off`
+ * @returns True if `value` has callable `on` and `off`; false otherwise
  */
 export declare function isInputStream(value: unknown): value is InputStreamInterface;
 
 /**
- * Whether `value` is a usable {@link OutputStreamInterface} — a record with a callable `write`. A
- * total type guard (AGENTS §14): it NEVER throws and returns `false` for anything off-shape, so it
- * narrows the output boundary (the real `process.stdout`, or a recording fake a test injects) to the
- * one method the driver writes through — no `as`.
- *
- * @param value - Any value crossing the boundary (a process stream, an injected fake, `unknown`)
- * @returns `true` when `value` has a callable `write`
- */
-export declare function isOutputStream(value: unknown): value is OutputStreamInterface;
-
-/**
- * Whether `value` is a Node {@link NodeJS.ReadableStream} — a total structural guard (AGENTS §14)
- * checking for the callable `read` / `pipe` / `on` that `node:readline`'s `createInterface` requires
- * as its `input`. The non-TTY fallback narrows the resolved input stream through this before handing
- * it to readline (never an `as`), so a real piped `process.stdin` (or a `PassThrough` a test injects)
- * crosses into the readline boundary honestly. Never throws; returns `false` for a minimal fake that
- * isn't a full readable.
+ * Checks whether `value` is a Node {@link NodeJS.ReadableStream} — a total structural guard
+ * checking for the callable `read` / `pipe` / `on` that `node:readline`'s `createInterface`
+ * requires as its `input`. The non-TTY fallback narrows the resolved input stream through this
+ * before handing it to readline, never through an assertion, so a real piped `process.stdin` (or a
+ * `PassThrough` a test injects) crosses into the readline boundary honestly. Never throws; returns
+ * `false` for a minimal fake that isn't a full readable.
  *
  * @param value - The resolved input stream (or any value crossing the boundary)
- * @returns `true` when `value` has the readable methods readline needs
+ * @returns True if `value` has the readable methods readline needs; false otherwise
  */
 export declare function isReadable(value: unknown): value is NodeJS.ReadableStream;
 
-/** A line feed (`\n`, U+000A) — the line terminator the driver writes after the final committed prompt view. */
-export declare const LINE_FEED: string;
-
 /**
- * The number of terminal LINES a rendered prompt `view` occupies — one more than its newline count
- * (a view with no newline is a single line; N newlines span N+1 lines). The basis of the in-place
- * re-render: the driver records the line count of the view it just wrote so the next redraw knows how
- * far up to move the cursor before overwriting. Total; an empty string is one (empty) line.
+ * Counts the terminal lines a rendered prompt `view` occupies — one more than its newline count, so
+ * a view with no newline is a single line and a view with N newlines spans N+1 lines. The basis of
+ * the in-place re-render: the driver records the line count of the view it wrote so the next redraw
+ * knows how far up to move the cursor before overwriting. Total; an empty string is one empty line.
  *
  * @param view - The rendered (possibly multi-line, possibly ANSI-styled) view string
  * @returns The number of lines the view spans (always at least 1)
  */
 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. */
+/** Holds 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.
+ * Returns the full reposition-and-clear prefix to write before re-rendering a prompt view in place
+ * — given the line count of the previous view, it moves the cursor up over those lines, returns it
+ * to column 0, and erases everything from there to the end of the screen, so the next view is drawn
+ * on a clean region and a taller previous view leaves no orphaned rows. Pure; the driver writes
+ * this immediately followed by the new view.
  *
- * @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
+ * @remarks
+ * For the first render `previousLines` is `1` (the cursor sits on the line the prompt opened on) so
+ * the prefix is a carriage return + clear-down — the prompt draws from the current line. For a
+ * subsequent render it climbs `previousLines - 1` lines (the cursor is on the last line of the prior
+ * view) before clearing. Keeping the math here (not in the driver) makes the re-render unit-testable
+ * without a real terminal.
+ *
+ * @param previousLines - The line count of the view on screen (from {@link lineCount})
+ * @returns The control-sequence prefix to write before the new view
+ */
+export declare function redrawPrefix(previousLines: number): string;
+
+/**
+ * States 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 function lockedLine(styler: StylerInterface, theme: PromptTheme, label: string, value: string): string;
+export declare const REFUSAL_MESSAGE = "Enter a value this field accepts";
 
 /**
- * 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).
- * The pure step the in-place re-render uses to climb back over the previous view before clearing it.
- * Total.
+ * Returns 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, because no movement is needed and `ESC[0A`
+ * is a wasted write. The pure step the in-place re-render uses to climb back over the previous view
+ * before clearing it. Total.
  *
  * @param count - How many lines to move the cursor up
  * @returns The `ESC[{count}A` sequence, or `''` when `count <= 0`
  */
-export declare function moveUp(count: number): string;
+export declare function renderCursorUp(count: number): string;
 
 /**
- * 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.
+ * Renders the section header the walk writes when it enters a new field group, painted by the
+ * `message` role.
  *
  * @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
+ * @param label - The group's declared label, falling back to its own name
+ * @returns The rendered section header
  */
-export declare function numberedList(styler: StylerInterface, theme: PromptTheme, choices: readonly FieldChoice[]): string;
+export declare function renderGroupHeader(styler: StylerInterface, theme: PromptTheme, label: string): 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.
+ * Renders the read-only line a locked field shows — 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.
  *
- * @remarks
- * - `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.
+ * @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 interface OutputStreamInterface {
-    write(text: string): boolean | void;
-    readonly isTTY?: boolean;
-}
+export declare function renderLockedLine(styler: StylerInterface, theme: PromptTheme, label: string, value: string): string;
 
 /**
- * Whether an input stream can be driven in RAW mode — it both reports `isTTY === true` AND exposes a
- * callable `setRawMode`. The {@link import('./Terminal.js').Terminal} probes this to choose its path:
- * `true` ⇒ the interactive raw-mode prompts (arrow-key navigation, live re-render); `false` ⇒ the
- * `node:readline` line-input fallback (a piped / non-terminal stream cannot enter raw mode). Total —
- * never throws.
+ * Renders 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 input - The resolved {@link InputStreamInterface}
- * @returns `true` when the stream is a TTY with `setRawMode`
+ * @param styler - The console styler that renders each role
+ * @param theme - The resolved prompt theme
+ * @param choices - The choices the walk offers, from {@link filterEnabled}
+ * @returns The rendered list
  */
-export declare function rawCapable(input: InputStreamInterface): boolean;
+export declare function renderNumberedList(styler: StylerInterface, theme: PromptTheme, choices: readonly FieldChoice[]): string;
 
 /**
- * The full reposition-and-clear prefix to write BEFORE re-rendering a prompt view in place — given
- * the line count of the PREVIOUS view, it moves the cursor up over those lines, returns it to column
- * 0, and erases everything from there to the end of the screen, so the next view is drawn on a clean
- * region (no orphaned rows from a taller previous view). Pure; the driver writes this immediately
- * followed by the new view.
- *
- * @remarks
- * For the FIRST render `previousLines` is `1` (the cursor sits on the line the prompt opened on) so
- * the prefix is just a carriage return + clear-down — the prompt draws from the current line. For a
- * subsequent render it climbs `previousLines - 1` lines (the cursor is on the LAST line of the prior
- * view) before clearing. Keeping the math here (not in the driver) makes the re-render unit-testable
- * without a real terminal.
+ * Renders 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.
  *
- * @param previousLines - The line count of the view currently on screen (from {@link lineCount})
- * @returns The control-sequence prefix to write before the new view
+ * @param styler - The console styler that renders each role
+ * @param theme - The resolved prompt theme
+ * @param choices - The choices the open select offers, from {@link filterEnabled}
+ * @returns The rendered suggestion line
  */
-export declare function redrawPrefix(previousLines: number): string;
+export declare function renderSuggestionLine(styler: StylerInterface, theme: PromptTheme, choices: readonly FieldChoice[]): string;
 
 /**
- * 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.
+ * Renders the line naming the choices a field shows but refuses, written above the list the walk
+ * drives.
+ *
+ * @param styler - The console styler that renders each role
+ * @param theme - The resolved prompt theme
+ * @param choices - The refused choices, from {@link filterDisabled}
+ * @returns The rendered unavailable line
  */
-export declare const REFUSAL_MESSAGE = "Enter a value this field accepts";
+export declare function renderUnavailableLine(styler: StylerInterface, theme: PromptTheme, choices: readonly FieldChoice[]): string;
 
-/** The lead on the line listing an open `select`'s offered values, which a typed answer may ignore. */
+/**
+ * Holds the lead on the line listing an open `select`'s offered values, which a typed answer can
+ * 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;
+/**
+ * Checks whether an input stream can be driven in raw mode — it reports `isTTY === true` and
+ * exposes a callable `setRawMode`. The {@link import('./Terminal.js').Terminal} probes this to
+ * choose its path: true selects the interactive raw-mode fields, with arrow-key navigation and a
+ * live re-render; false selects the `node:readline` line-input fallback, because a piped or
+ * non-terminal stream cannot enter raw mode. Total — never throws.
+ *
+ * @param input - The resolved {@link InputStreamInterface}
+ * @returns True if the stream is a TTY with `setRawMode`; false otherwise
+ */
+export declare function supportsRawMode(input: InputStreamInterface): boolean;
 
 /**
- * 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.
+ * Implements {@link TerminalInterface} for a human at this machine's keyboard — the interactive
+ * form driver, 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, binds every answer through the form's own `fill`, and
+ * re-asks what the form refused. 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
  * See {@link TerminalInterface} for the driving contract. The walk itself:
  *
- * - **Twelve controls, seven reducers.** `text`, `number`, `date`, `time`, `datetime`, `color`, and
+ * - **Controls and 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
+ *   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.
+ * - **Visibility is honored.** A `hidden` field and a field 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
@@ -382,7 +396,7 @@ export declare class Terminal implements TerminalInterface {
 }
 
 /**
- * Options for {@link import('./factories.js').createTerminal} — every member optional, so a bare
+ * Configures {@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.
  *
@@ -392,27 +406,29 @@ export declare class Terminal implements TerminalInterface {
  *   {@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.
+ *   {@link import('@orkestrel/console/server').StreamTargetInterface}-shaped stream is accepted,
+ *   resolved through {@link import('@orkestrel/console/server').isStreamTarget}, so a test records
+ *   the rendered output. That is the console module's own boundary shape, so one target drives a
+ *   console sink and this driver alike.
  * - `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
+ *   {@link import('@orkestrel/terminal').DEFAULT_PROMPT_THEME} leaf by leaf by
+ *   {@link import('@orkestrel/terminal').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 output?: StreamTargetInterface;
     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. */
+/**
+ * Holds 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 it heads.
+ */
 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
+ * Projects 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.
  *