@orkestrel/terminal 0.0.1

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

@@ -0,0 +1,321 @@
+import { CheckboxOptions } from '../core/index.js';
+import { ConfirmOptions } from '../core/index.js';
+import { EditorOptions } from '../core/index.js';
+import { InputOptions } from '../core/index.js';
+import { PasswordOptions } from '../core/index.js';
+import { PromptFormInterface } from '../core/index.js';
+import { SelectOptions } from '../core/index.js';
+
+/** 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;
+
+/**
+ * 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.
+ */
+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('../core/index.js').TerminalError} (`CANCEL`)
+ * on ctrl-c. It is the ONLY impure part of the prompt 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
+ *
+ * @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.
+ *
+ * @example
+ * ```ts
+ * import { createTerminal } from '@src/server'
+ *
+ * const terminal = createTerminal()
+ * const name = await terminal.input({ message: 'Your name' })
+ * const proceed = await terminal.confirm({ message: 'Continue?', default: true })
+ * ```
+ */
+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 `{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.
+ */
+export declare const CSI_UP: string;
+
+/**
+ * Hide 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). */
+export declare const CURSOR_SHOW: string;
+
+/** 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 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.
+ */
+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).
+ *
+ * @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).
+ */
+export declare interface InputStreamInterface {
+    on(event: 'data', listener: (chunk: string | Uint8Array) => void): void;
+    off(event: 'data', listener: (chunk: string | Uint8Array) => void): void;
+    setRawMode?(mode: boolean): void;
+    resume?(): void;
+    pause?(): void;
+    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`.
+ *
+ * @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
+ * 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`
+ */
+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 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.
+ *
+ * @param input - The resolved {@link InputStreamInterface}
+ * @returns `true` when the stream is a TTY with `setRawMode`
+ */
+export declare function isRawCapable(input: InputStreamInterface): boolean;
+
+/**
+ * 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.
+ *
+ * @param value - The resolved input stream (or any value crossing the boundary)
+ * @returns `true` when `value` has the readable methods readline needs
+ */
+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;
+
+/**
+ * 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.
+ *
+ * @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 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.
+ *
+ * @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;
+
+/**
+ * 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.
+ *
+ * @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.
+ */
+export declare interface OutputStreamInterface {
+    write(text: string): boolean | void;
+    readonly isTTY?: boolean;
+}
+
+/**
+ * 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.
+ *
+ * @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
+ */
+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).
+ */
+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>;
+}
+
+/**
+ * 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('../core/index.js').TerminalError} (`CANCEL`) on ctrl-c.
+ *
+ * @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.
+ */
+export declare interface TerminalInterface extends PromptFormInterface {
+}
+
+/**
+ * Options for {@link import('./factories.js').createTerminal} — both streams optional, so a bare
+ * `createTerminal()` drives the real `process.stdin` / `process.stdout`.
+ *
+ * @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.
+ */
+export declare interface TerminalOptions {
+    readonly input?: InputStreamInterface;
+    readonly output?: OutputStreamInterface;
+}
+
+export { }

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

@@ -0,0 +1,321 @@
+import { CheckboxOptions } from '../core/index.js';
+import { ConfirmOptions } from '../core/index.js';
+import { EditorOptions } from '../core/index.js';
+import { InputOptions } from '../core/index.js';
+import { PasswordOptions } from '../core/index.js';
+import { PromptFormInterface } from '../core/index.js';
+import { SelectOptions } from '../core/index.js';
+
+/** 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;
+
+/**
+ * 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.
+ */
+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('../core/index.js').TerminalError} (`CANCEL`)
+ * on ctrl-c. It is the ONLY impure part of the prompt 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
+ *
+ * @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.
+ *
+ * @example
+ * ```ts
+ * import { createTerminal } from '@src/server'
+ *
+ * const terminal = createTerminal()
+ * const name = await terminal.input({ message: 'Your name' })
+ * const proceed = await terminal.confirm({ message: 'Continue?', default: true })
+ * ```
+ */
+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 `{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.
+ */
+export declare const CSI_UP: string;
+
+/**
+ * Hide 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). */
+export declare const CURSOR_SHOW: string;
+
+/** 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 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.
+ */
+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).
+ *
+ * @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).
+ */
+export declare interface InputStreamInterface {
+    on(event: 'data', listener: (chunk: string | Uint8Array) => void): void;
+    off(event: 'data', listener: (chunk: string | Uint8Array) => void): void;
+    setRawMode?(mode: boolean): void;
+    resume?(): void;
+    pause?(): void;
+    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`.
+ *
+ * @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
+ * 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`
+ */
+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 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.
+ *
+ * @param input - The resolved {@link InputStreamInterface}
+ * @returns `true` when the stream is a TTY with `setRawMode`
+ */
+export declare function isRawCapable(input: InputStreamInterface): boolean;
+
+/**
+ * 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.
+ *
+ * @param value - The resolved input stream (or any value crossing the boundary)
+ * @returns `true` when `value` has the readable methods readline needs
+ */
+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;
+
+/**
+ * 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.
+ *
+ * @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 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.
+ *
+ * @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;
+
+/**
+ * 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.
+ *
+ * @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.
+ */
+export declare interface OutputStreamInterface {
+    write(text: string): boolean | void;
+    readonly isTTY?: boolean;
+}
+
+/**
+ * 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.
+ *
+ * @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
+ */
+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).
+ */
+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>;
+}
+
+/**
+ * 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('../core/index.js').TerminalError} (`CANCEL`) on ctrl-c.
+ *
+ * @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.
+ */
+export declare interface TerminalInterface extends PromptFormInterface {
+}
+
+/**
+ * Options for {@link import('./factories.js').createTerminal} — both streams optional, so a bare
+ * `createTerminal()` drives the real `process.stdin` / `process.stdout`.
+ *
+ * @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.
+ */
+export declare interface TerminalOptions {
+    readonly input?: InputStreamInterface;
+    readonly output?: OutputStreamInterface;
+}
+
+export { }