@orkestrel/terminal 0.0.13 → 0.0.14

package/dist/src/server/index.js

@@ -1,50 +1,43 @@
-import { TerminalError, checkboxReduce, confirmReduce, createCheckboxState, createConfirmState, createEditorState, createInputState, createPasswordState, createPromptTheme, createSelectState, editorReduce, errorLine, hintedHeader, inputReduce, parseKey, passwordReduce, promptHeader, sanitizeDisplayText, selectReduce } from "../core/index.js";
+import { CSI, createStyler } from "@orkestrel/console";
+import { NEWLINE, RETURN, TerminalError, createCheckboxState, createConfirmState, createEditorState, createInputState, createPasswordState, createPromptTheme, createSelectState, parseKey, reduceCheckbox, reduceConfirm, reduceEditor, reduceInput, reducePassword, reduceSelect, renderErrorLine, renderHintedHeader, renderPromptHeader, sanitizeDisplayText } from "../core/index.js";
 import { matchesAnswer, parseValue } from "@orkestrel/form";
-import { createStyler } from "@orkestrel/console";
+import { isStreamTarget } from "@orkestrel/console/server";
 import { createInterface } from "node:readline";
 import { stdin, stdout } from "node:process";
 //#region src/server/constants.ts
-/** The Escape byte (ESC, U+001B) — the lead byte of every CSI cursor-control sequence below. */
-var ESCAPE = String.fromCharCode(27);
-/** The Control Sequence Introducer (`ESC[`) — the prefix of every cursor / erase sequence. */
-var CSI = `[`;
 /**
-* The cursor-UP sequence TEMPLATE (`ESC[{count}A`) — {@link import('./helpers.js').moveUp}
+* 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.
 */
 var CSI_UP = `${CSI}{count}A`;
 /**
-* 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}.
 */
 var CURSOR_HIDE = `${CSI}?25l`;
-/** 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). */
 var CURSOR_SHOW = `${CSI}?25h`;
 /**
-* Erase from the cursor down to the end of the screen (`ESC[J`) — wipes the WHOLE previous (possibly
+* Erases 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.
 */
 var CLEAR_DOWN = `${CSI}J`;
-/** A carriage return (`\r`, U+000D) — returns the cursor to column 0 so a redraw starts at the line's left edge. */
-var CARRIAGE_RETURN = String.fromCharCode(13);
-/** A line feed (`\n`, U+000A) — the line terminator the driver writes after the final committed prompt view. */
-var LINE_FEED = String.fromCharCode(10);
 /**
-* 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.
 */
 var FALLBACK_SELECT_HINT = "Enter a number";
-/** 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). */
 var FALLBACK_CHECKBOX_HINT = "Enter numbers separated by commas";
-/** 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. */
 var FALLBACK_EDITOR_HINT = "(end of input finishes)";
-/** 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. */
 var FALLBACK_CONFIRM_HINT = "(y/n)";
 /**
-* 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
@@ -58,16 +51,16 @@ var CONTROL_HINTS = Object.freeze({
 	color: "(#rrggbb)",
 	file: "(path)"
 });
-/** 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. */
 var FILE_HINT = "One path per line, blank to finish";
-/** 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 may ignore. */
 var SUGGESTION_LEAD = "Suggestions";
-/** 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 below. */
 var UNAVAILABLE_LEAD = "Unavailable";
-/** 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. */
 var LOCKED_MARK = "(locked)";
 /**
-* What a field is told when the walk read an answer the control cannot hold — a word typed into a
+* 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.
@@ -76,8 +69,8 @@ var REFUSAL_MESSAGE = "Enter a value this field accepts";
 //#endregion
 //#region src/server/helpers.ts
 /**
-* 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`
+* 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 — no `as`.
 *
@@ -88,25 +81,13 @@ var REFUSAL_MESSAGE = "Enter a value this field accepts";
 * 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
 */
 function isInputStream(value) {
 	return typeof value === "object" && value !== null && "on" in value && typeof value.on === "function" && "off" in value && typeof value.off === "function";
 }
 /**
-* 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`
-*/
-function isOutputStream(value) {
-	return typeof value === "object" && value !== null && "write" in value && typeof value.write === "function";
-}
-/**
-* Whether `value` is a Node {@link NodeJS.ReadableStream} — a total structural guard (AGENTS §14)
+* 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 an `as`), so a real piped `process.stdin` (or a `PassThrough` a test injects)
@@ -114,26 +95,26 @@ function isOutputStream(value) {
 * 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
 */
 function isReadable(value) {
 	return typeof value === "object" && value !== null && "read" in value && typeof value.read === "function" && "pipe" in value && typeof value.pipe === "function";
 }
 /**
-* 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:
+* Checks 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`
+* @returns True if the stream is a TTY with `setRawMode`; false otherwise
 */
-function rawCapable(input) {
+function supportsRawMode(input) {
 	return input.isTTY === true && typeof input.setRawMode === "function";
 }
 /**
-* The number of terminal LINES a rendered prompt `view` occupies — one more than its newline count
+* Counts the 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.
@@ -147,7 +128,7 @@ function lineCount(view) {
 	return lines;
 }
 /**
-* The cursor-UP control sequence that moves the cursor up `count` lines (`ESC[{count}A`) — or the
+* 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 (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.
@@ -155,12 +136,12 @@ function lineCount(view) {
 * @param count - How many lines to move the cursor up
 * @returns The `ESC[{count}A` sequence, or `''` when `count <= 0`
 */
-function moveUp(count) {
+function renderCursorUp(count) {
 	if (count <= 0) return "";
 	return `${CSI_UP.replace("{count}", String(count))}`;
 }
 /**
-* The full reposition-and-clear prefix to write BEFORE re-rendering a prompt view in place — given
+* 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 (no orphaned rows from a taller previous view). Pure; the driver writes this immediately
@@ -177,15 +158,15 @@ function moveUp(count) {
 * @returns The control-sequence prefix to write before the new view
 */
 function redrawPrefix(previousLines) {
-	return `${moveUp(previousLines - 1)}\r${CLEAR_DOWN}`;
+	return `${renderCursorUp(previousLines - 1)}${RETURN}${CLEAR_DOWN}`;
 }
 /**
-* 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`,
+* 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 can render seven controls.
+* 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
@@ -209,7 +190,7 @@ function fieldToText(field) {
 	};
 }
 /**
-* 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.
 *
@@ -224,34 +205,42 @@ function valueToText(value) {
 	return value.join(", ");
 }
 /**
-* 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.
+* 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
 */
-function enabledChoices(choices) {
+function filterEnabled(choices) {
 	return choices.filter((choice) => choice.disabled !== true);
 }
 /**
-* 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.
+* 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
 */
-function disabledChoices(choices) {
+function filterDisabled(choices) {
 	return choices.filter((choice) => choice.disabled === true);
 }
-/** The section header the walk writes when it enters a new field group, painted by the `message` role. */
-function groupHeader(styler, theme, label) {
+/**
+* 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 label - The group's declared label, falling back to its own name
+* @returns The rendered section header
+*/
+function renderGroupHeader(styler, theme, label) {
 	return styler.render(theme.roles.message, label);
 }
 /**
-* 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
+* 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.
 *
 * @param styler - The console styler that renders each role
@@ -260,38 +249,54 @@ function groupHeader(styler, theme, label) {
 * @param value - The held answer, from {@link valueToText}
 * @returns The rendered line, with no trailing space when there is nothing to show
 */
-function lockedLine(styler, theme, label, value) {
+function renderLockedLine(styler, theme, label, value) {
 	const head = `${styler.render(theme.roles.muted, theme.icons.dot)} ${styler.render(theme.roles.message, label)} ${styler.render(theme.roles.hint, LOCKED_MARK)}`;
 	return value.length === 0 ? head : `${head} ${styler.render(theme.roles.content, value)}`;
 }
-/** 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. */
-function suggestionLine(styler, theme, choices) {
+/**
+* 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 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
+*/
+function renderSuggestionLine(styler, theme, choices) {
 	const values = choices.map((choice) => choice.value).join(", ");
 	return styler.render(theme.roles.hint, `${SUGGESTION_LEAD}: ${values}`);
 }
-/** The line naming the choices a field shows but refuses, written above the list the walk drives. */
-function unavailableLine(styler, theme, choices) {
+/**
+* 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
+*/
+function renderUnavailableLine(styler, theme, choices) {
 	const labels = choices.map((choice) => choice.label).join(", ");
 	return styler.render(theme.roles.muted, `${UNAVAILABLE_LEAD}: ${labels}`);
 }
 /**
-* 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 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}
+* @param choices - The choices the walk offers, from {@link filterEnabled}
 * @returns The rendered list
 */
-function numberedList(styler, theme, choices) {
+function renderNumberedList(styler, theme, choices) {
 	return choices.map((choice, index) => `  ${styler.render(theme.roles.muted, `${String(index + 1)})`)} ${styler.render(theme.roles.content, choice.label)}`).join("\n");
 }
 //#endregion
 //#region src/server/Terminal.ts
 /**
-* 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
+* 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, 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
@@ -300,7 +305,7 @@ function numberedList(styler, theme, choices) {
 * @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
@@ -334,7 +339,7 @@ var Terminal = class {
 	#ended = false;
 	constructor(options) {
 		this.#input = isInputStream(options?.input) ? options.input : stdin;
-		this.#output = isOutputStream(options?.output) ? options.output : stdout;
+		this.#output = isStreamTarget(options?.output) ? options.output : stdout;
 		this.#styler = createStyler();
 		this.#theme = createPromptTheme(options?.theme);
 	}
@@ -347,7 +352,7 @@ var Terminal = class {
 				const result = form.submit();
 				if (result.success) return await form.answer;
 				this.#report(form, result.error);
-				const again = this.#editable(form, result.error);
+				const again = this.#collectEditable(form, result.error);
 				if (again.length === 0 || this.#ended) {
 					form.destroy();
 					return await form.answer;
@@ -359,7 +364,7 @@ var Terminal = class {
 		}
 	}
 	/**
-	* Ask `fields` in the order given, skipping what the walk must not touch and rendering what it
+	* Asks `fields` in the order given, skipping what the walk must not touch and rendering what it
 	* must not edit. Returns early the moment the form stops being editable, so an abandoned form
 	* ends the walk between fields as well as under an active read.
 	*/
@@ -371,10 +376,10 @@ var Terminal = class {
 			if (form.disabled.has(field.name)) continue;
 			if (field.group !== group) {
 				group = field.group;
-				if (group !== void 0) this.#group(form, group);
+				if (group !== void 0) this.#writeGroup(form, group);
 			}
 			if (field.locked === true) {
-				this.#locked(form, field);
+				this.#writeLocked(form, field);
 				continue;
 			}
 			const raw = await this.#read(form, field);
@@ -382,31 +387,28 @@ var Terminal = class {
 			this.#bind(form, field, raw);
 		}
 	}
-	/** Write a group's label as a section header, resolving the schema's declared label and falling back to the group's own name. */
-	#group(form, name) {
+	/** Writes a group's label as a section header, resolving the schema's declared label and falling back to the group's own name. */
+	#writeGroup(form, name) {
 		const label = form.schema.groups?.find((group) => group.name === name)?.label ?? name;
-		this.#output.write(`
-${groupHeader(this.#styler, this.#theme, sanitizeDisplayText(label))}
-`);
+		this.#output.write(`${NEWLINE}${renderGroupHeader(this.#styler, this.#theme, sanitizeDisplayText(label))}${NEWLINE}`);
 	}
-	/** Render a locked field read-only — its label, its mark, and the answer the form already holds. */
-	#locked(form, field) {
-		const line = lockedLine(this.#styler, this.#theme, sanitizeDisplayText(field.label ?? field.name), sanitizeDisplayText(valueToText(form.values[field.name])));
-		this.#output.write(`${line}
-`);
+	/** Renders a locked field read-only — its label, its mark, and the answer the form already holds. */
+	#writeLocked(form, field) {
+		const line = renderLockedLine(this.#styler, this.#theme, sanitizeDisplayText(field.label ?? field.name), sanitizeDisplayText(valueToText(form.values[field.name])));
+		this.#output.write(`${line}${NEWLINE}`);
 	}
-	/** Read one field through the reducer its control names, resolving the raw answer the binding projects. */
+	/** Reads one field through the reducer its control names, resolving the raw answer the binding projects. */
 	#read(form, field) {
-		if (field.control === "password") return this.#password(form, field);
+		if (field.control === "password") return this.#askPassword(form, field);
 		if (field.control === "confirm") return this.#confirm(form, field);
-		if (field.control === "editor") return this.#editor(form, field);
+		if (field.control === "editor") return this.#askEditor(form, field);
 		if (field.control === "select") return this.#select(form, field);
 		if (field.control === "checkbox") return this.#checkbox(form, field);
 		if (field.control === "file") return this.#file(form, field);
-		return this.#text(form, field);
+		return this.#askText(form, field);
 	}
 	/**
-	* Bind one raw answer to the form — the single binding, and the only place this driver writes a
+	* Binds one raw answer to the form — the single binding, and the only place this driver writes a
 	* value. `parseValue` coerces the raw answer to the control's own shape and `matchesAnswer`
 	* projects a blank one to absence, which is what keeps `required` refusing a bare return. A raw
 	* answer the control cannot hold binds as absence and invalidates the field, so the field comes
@@ -418,8 +420,8 @@ ${groupHeader(this.#styler, this.#theme, sanitizeDisplayText(label))}
 		form.fill(field.name, matchesAnswer(value) ? value : void 0);
 		if (value === void 0 && matchesAnswer(raw)) form.invalidate(field.name, REFUSAL_MESSAGE);
 	}
-	/** The erroring fields the walk can ask again — every field the walk skips or renders read-only is excluded, because a second pass could not change its answer. */
-	#editable(form, errors) {
+	/** Collects the erroring fields the walk can ask again — every field the walk skips or renders read-only is excluded, because a second pass could not change its answer. */
+	#collectEditable(form, errors) {
 		const fields = [];
 		for (const error of errors) {
 			const field = form.field(error.field);
@@ -431,37 +433,36 @@ ${groupHeader(this.#styler, this.#theme, sanitizeDisplayText(label))}
 		}
 		return fields;
 	}
-	/** Write every supplied failure against its field's label. */
+	/** Writes every supplied failure against its field's label. */
 	#report(form, errors) {
 		for (const error of errors) {
 			const label = sanitizeDisplayText(form.field(error.field)?.label ?? error.field);
 			const message = sanitizeDisplayText(error.message);
-			const line = errorLine(this.#styler, this.#theme, `${label}: ${message}`);
-			this.#output.write(`${line}
-`);
+			const line = renderErrorLine(this.#styler, this.#theme, `${label}: ${message}`);
+			this.#output.write(`${line}${NEWLINE}`);
 		}
 	}
-	/** Read a field as one line of text — `text` itself and the six controls a terminal has no widget for. */
-	#text(form, field) {
+	/** Reads a field as one line of text — `text` itself and the controls a terminal has no widget for. */
+	#askText(form, field) {
 		const state = createInputState(fieldToText(field), this.#styler, this.#theme);
-		if (rawCapable(this.#input)) return this.#drive(form, state, inputReduce);
+		if (supportsRawMode(this.#input)) return this.#drive(form, state, reduceInput);
 		return this.#line(form, state.message, state.default);
 	}
-	/** Read a secret — masked live in raw mode, and read without echo through readline on a stream that cannot enter it. */
-	#password(form, field) {
+	/** Reads a secret — masked live in raw mode, and read without echo through readline on a stream that cannot enter it. */
+	#askPassword(form, field) {
 		const state = createPasswordState(field, this.#styler, this.#theme);
-		if (rawCapable(this.#input)) return this.#drive(form, state, passwordReduce);
-		return this.#prompt(form, promptHeader(this.#styler, this.#theme, state.message));
+		if (supportsRawMode(this.#input)) return this.#drive(form, state, reducePassword);
+		return this.#prompt(form, renderPromptHeader(this.#styler, this.#theme, state.message));
 	}
 	/**
-	* Read a yes or no. The fallback accepts `y` / `yes` / `n` / `no` in any case and takes the
+	* Reads a yes or no. The fallback accepts `y` / `yes` / `n` / `no` in any case and takes the
 	* field's default for a bare line; anything else is returned as typed, so the binding refuses it
 	* and the walk asks again rather than silently reading it as no.
 	*/
 	async #confirm(form, field) {
 		const state = createConfirmState(field, this.#styler, this.#theme);
-		if (rawCapable(this.#input)) return this.#drive(form, state, confirmReduce);
-		const header = hintedHeader(this.#styler, this.#theme, state.message, FALLBACK_CONFIRM_HINT);
+		if (supportsRawMode(this.#input)) return this.#drive(form, state, reduceConfirm);
+		const header = renderHintedHeader(this.#styler, this.#theme, state.message, FALLBACK_CONFIRM_HINT);
 		const line = await this.#prompt(form, header);
 		const answer = line.trim().toLowerCase();
 		if (answer.length === 0) return state.default;
@@ -469,96 +470,91 @@ ${groupHeader(this.#styler, this.#theme, sanitizeDisplayText(label))}
 		if (answer === "n" || answer === "no") return false;
 		return line.trim();
 	}
-	/** Read text over many lines — ctrl-d finishes in raw mode, and end of input finishes on a piped stream. */
-	#editor(form, field) {
+	/** Reads text over many lines — ctrl-d finishes in raw mode, and end of input finishes on a piped stream. */
+	#askEditor(form, field) {
 		const state = createEditorState(field, this.#styler, this.#theme);
-		if (rawCapable(this.#input)) return this.#drive(form, state, editorReduce);
+		if (supportsRawMode(this.#input)) return this.#drive(form, state, reduceEditor);
 		return this.#block(form, state.message, state.default);
 	}
 	/**
-	* Read one choice. A disabled choice is named above the list and never offered, because the form
+	* Reads one choice. A disabled choice is named above the list and never offered, because the form
 	* refuses its value at every door. An open select is a suggestion list plus a typed line, since
 	* `open` admits an answer the list does not offer; a closed select with nothing left to offer
 	* resolves absence and lets the form's own rules report it.
 	*/
 	async #select(form, field) {
-		const choices = enabledChoices(field.choices);
-		this.#unavailable(field.choices);
+		const choices = filterEnabled(field.choices);
+		this.#writeUnavailable(field.choices);
 		if (field.open === true) {
 			if (choices.length > 0) {
 				const display = choices.map((choice) => ({
 					...choice,
 					value: sanitizeDisplayText(choice.value)
 				}));
-				this.#output.write(`${suggestionLine(this.#styler, this.#theme, display)}
-`);
+				this.#output.write(`${renderSuggestionLine(this.#styler, this.#theme, display)}${NEWLINE}`);
 			}
-			return this.#text(form, field);
+			return this.#askText(form, field);
 		}
 		if (choices.length === 0) return void 0;
 		const state = createSelectState({
 			...field,
 			choices
 		}, this.#styler, this.#theme);
-		if (rawCapable(this.#input)) return this.#drive(form, state, selectReduce);
-		this.#list(state.message, choices);
-		const line = await this.#prompt(form, this.#hint(`${FALLBACK_SELECT_HINT}:`));
+		if (supportsRawMode(this.#input)) return this.#drive(form, state, reduceSelect);
+		this.#writeList(state.message, choices);
+		const line = await this.#prompt(form, this.#formatHint(`${FALLBACK_SELECT_HINT}:`));
 		return choices[Number.parseInt(line.trim(), 10) - 1]?.value;
 	}
 	/**
-	* Read any number of choices. Disabled choices are named above the list and never offered, so a
+	* Reads any number of choices. Disabled choices are named above the list and never offered, so a
 	* box the form would refuse can never be ticked. An empty answer is an answered "none of them",
 	* which is what `matchesAnswer` says an empty list means.
 	*/
 	async #checkbox(form, field) {
-		const choices = enabledChoices(field.choices);
-		this.#unavailable(field.choices);
+		const choices = filterEnabled(field.choices);
+		this.#writeUnavailable(field.choices);
 		const state = createCheckboxState({
 			...field,
 			choices
 		}, this.#styler, this.#theme);
-		if (rawCapable(this.#input)) return this.#drive(form, state, checkboxReduce);
-		this.#list(state.message, choices);
-		return (await this.#prompt(form, this.#hint(`${FALLBACK_CHECKBOX_HINT}:`))).split(",").map((part) => choices[Number.parseInt(part.trim(), 10) - 1]?.value).filter((value) => value !== void 0);
+		if (supportsRawMode(this.#input)) return this.#drive(form, state, reduceCheckbox);
+		this.#writeList(state.message, choices);
+		return (await this.#prompt(form, this.#formatHint(`${FALLBACK_CHECKBOX_HINT}:`))).split(",").map((part) => choices[Number.parseInt(part.trim(), 10) - 1]?.value).filter((value) => value !== void 0);
 	}
 	/**
-	* Read file paths — names only, because bytes never enter a form. A `multiple` field collects one
+	* Reads file paths — names only, because bytes never enter a form. A `multiple` field collects one
 	* path per line until a blank one, and a single field takes one. No path at all is absence rather
 	* than an empty list, because the reader answered a blank line.
 	*/
 	async #file(form, field) {
-		if (field.multiple === true) this.#output.write(`${this.#hint(FILE_HINT)}
-`);
+		if (field.multiple === true) this.#output.write(`${this.#formatHint(FILE_HINT)}${NEWLINE}`);
 		const paths = [];
 		for (;;) {
-			const entry = await this.#text(form, field);
+			const entry = await this.#askText(form, field);
 			if (entry.length === 0) break;
 			paths.push(entry);
 			if (field.multiple !== true || this.#ended) break;
 		}
 		return paths.length > 0 ? paths : void 0;
 	}
-	/** Name the choices a field shows but refuses, above the list the walk drives. */
-	#unavailable(choices) {
-		const refused = disabledChoices(choices);
+	/** Names the choices a field shows but refuses, above the list the walk drives. */
+	#writeUnavailable(choices) {
+		const refused = filterDisabled(choices);
 		if (refused.length === 0) return;
-		this.#output.write(`${unavailableLine(this.#styler, this.#theme, refused)}
-`);
-	}
-	/** Write a field's header above its numbered choice list — the non-TTY presentation of a choice field. */
-	#list(message, choices) {
-		const header = promptHeader(this.#styler, this.#theme, message);
-		const list = numberedList(this.#styler, this.#theme, choices);
-		this.#output.write(`${header}
-${list}
-`);
-	}
-	/** Paint one line of supplementary instruction through the `hint` role. */
-	#hint(text) {
+		this.#output.write(`${renderUnavailableLine(this.#styler, this.#theme, refused)}${NEWLINE}`);
+	}
+	/** Writes a field's header above its numbered choice list — the non-TTY presentation of a choice field. */
+	#writeList(message, choices) {
+		const header = renderPromptHeader(this.#styler, this.#theme, message);
+		const list = renderNumberedList(this.#styler, this.#theme, choices);
+		this.#output.write(`${header}${NEWLINE}${list}${NEWLINE}`);
+	}
+	/** Paints one line of supplementary instruction through the `hint` role. */
+	#formatHint(text) {
 		return this.#styler.render(this.#theme.roles.hint, text);
 	}
 	/**
-	* The irreducible Node raw-mode primitive — the ONLY place raw mode is touched. Switches the input
+	* Isolates the irreducible Node raw-mode primitive — the ONLY place raw mode is touched. Switches the input
 	* into raw mode (each keypress delivered immediately, no echo), resumes its flow, and subscribes
 	* `handler` to `'data'`. The paired {@link #leaveRaw} operation unsubscribes the exact handler,
 	* leaves raw mode, and pauses the stream on submit, cancel, abandon, or throw.
@@ -578,7 +574,7 @@ ${list}
 		this.#input.pause?.();
 	}
 	/**
-	* Drive ONE field over raw-mode stdin — the generic engine every interactive control shares.
+	* Drives ONE field over raw-mode stdin — the generic engine every interactive control shares.
 	* Renders the reducer's initial view, enters raw mode once, and on each keypress runs `parseKey` →
 	* `reduce` → an in-place re-render; on `submit` it cleans up and resolves the reducer's value, on
 	* `cancel` (ctrl-c) it cleans up and rejects a {@link TerminalError} coded `CANCEL`. Abandoning
@@ -594,8 +590,7 @@ ${list}
 				firstView = reduce(initial, parseKey("")).view;
 				this.#output.write(firstView);
 			} catch (error) {
-				this.#output.write(`${CURSOR_SHOW}
-`);
+				this.#output.write(`${CURSOR_SHOW}${NEWLINE}`);
 				reject(error);
 				return;
 			}
@@ -619,45 +614,41 @@ ${list}
 				}
 				this.#render(step.view, lines);
 				this.#leaveRaw(token);
-				this.#output.write(`${CURSOR_SHOW}
-`);
+				this.#output.write(`${CURSOR_SHOW}${NEWLINE}`);
 				if (step.status === "cancel") reject(new TerminalError("CANCEL", "Prompt cancelled"));
 				else if (step.status === "submit" && step.value !== void 0) resolve(step.value);
 				else reject(new TerminalError("DRIVER", "submit produced no value"));
 			} catch (error) {
 				this.#leaveRaw(token);
-				this.#output.write(`${CURSOR_SHOW}
-`);
+				this.#output.write(`${CURSOR_SHOW}${NEWLINE}`);
 				reject(error);
 			}
 		};
 	}
-	/** End an active read that the form outlived — release raw mode exactly as a submit does, then fail the read with the form's own error. */
+	/** Ends an active read that the form outlived — releases raw mode exactly as a submit does, then fails the read with the form's own error. */
 	#interrupt(token, reject, error) {
 		if (!this.#handlers.has(token)) return;
 		this.#leaveRaw(token);
-		this.#output.write(`${CURSOR_SHOW}
-`);
+		this.#output.write(`${CURSOR_SHOW}${NEWLINE}`);
 		reject(error);
 	}
-	/** Redraw a field view in place — climb over the previous view's `previousLines`, clear, and write the new view (the pure cursor-math is {@link redrawPrefix}). */
+	/** Redraws a field view in place — climbs over the previous view's `previousLines`, clears, and writes the new view (the pure cursor-math is {@link redrawPrefix}). */
 	#render(view, previousLines) {
 		this.#output.write(`${redrawPrefix(previousLines)}${view}`);
 	}
-	/** Read one line for a text-shaped field, taking the field's default when the line is bare. */
+	/** Reads one line for a text-shaped field, taking the field's default when the line is bare. */
 	async #line(form, message, seed) {
-		const answer = await this.#prompt(form, promptHeader(this.#styler, this.#theme, message));
+		const answer = await this.#prompt(form, renderPromptHeader(this.#styler, this.#theme, message));
 		return answer.length > 0 ? answer : seed;
 	}
 	/**
-	* Read a whole block for an `editor` field — a piped stream has no ctrl-d keypress, so end of
+	* Reads a whole block for an `editor` field — a piped stream has no ctrl-d keypress, so end of
 	* input is the terminator. It drains every remaining line, which is why nothing after an `editor`
 	* field can be asked on the same stream.
 	*/
 	async #block(form, message, seed) {
-		const header = hintedHeader(this.#styler, this.#theme, message, FALLBACK_EDITOR_HINT);
-		this.#output.write(`${header}
-`);
+		const header = renderHintedHeader(this.#styler, this.#theme, message, FALLBACK_EDITOR_HINT);
+		this.#output.write(`${header}${NEWLINE}`);
 		const collected = [];
 		for (;;) {
 			const line = await this.#next(form);
@@ -667,13 +658,13 @@ ${list}
 		const text = collected.join("\n");
 		return text.length > 0 ? text : seed;
 	}
-	/** Write one field's header and read back the line the reader answers it with, or `''` once the stream has ended. */
+	/** Writes one field's header and reads back the line the reader answers it with, or `''` once the stream has ended. */
 	async #prompt(form, header) {
 		this.#output.write(`${header} `);
 		return await this.#next(form) ?? "";
 	}
 	/**
-	* Take the next line the input carries — from the buffer when the reader has already read ahead,
+	* Takes the next line the input carries — from the buffer when the reader has already read ahead,
 	* and otherwise by waiting for one. It resolves ABSENCE once the stream has ended, so a walk over
 	* an exhausted stream settles instead of waiting forever, and it rejects when the form is
 	* abandoned, so an unanswerable read ends with the form rather than outliving it.
@@ -682,7 +673,7 @@ ${list}
 		const buffered = this.#queue.shift();
 		if (buffered !== void 0) return Promise.resolve(buffered);
 		if (this.#ended) return Promise.resolve(void 0);
-		this.#reader();
+		this.#startReader();
 		return new Promise((resolve, reject) => {
 			this.#taker = resolve;
 			form.answer.catch((error) => {
@@ -693,19 +684,19 @@ ${list}
 		});
 	}
 	/**
-	* Open the walk's ONE readline interface, or keep the open one. A whole form is many questions
+	* Opens the walk's ONE readline interface, or keeps the open one. A whole form is many questions
 	* over one stream, and an interface reads ahead: a fresh interface per question would swallow
 	* every line it read past the one it was asked for, so the walk holds a single reader and buffers
 	* what arrives early. It is closed when the walk ends, so the process is free to exit.
 	*/
-	#reader() {
+	#startReader() {
 		if (this.#interface !== void 0) return;
-		const rl = createInterface(this.#readline());
+		const rl = createInterface(this.#openReadline());
 		rl.on("line", (line) => this.#accept(line));
 		rl.on("close", () => this.#finish());
 		this.#interface = rl;
 	}
-	/** Hand a line to whoever is waiting for it, or buffer it for the next question. */
+	/** Hands a line to whoever is waiting for it, or buffers it for the next question. */
 	#accept(line) {
 		const taker = this.#taker;
 		if (taker === void 0) {
@@ -715,7 +706,7 @@ ${list}
 		this.#taker = void 0;
 		taker(line);
 	}
-	/** Record that no further line can arrive and release whoever was waiting for one. */
+	/** Records that no further line can arrive and releases whoever was waiting for one. */
 	#finish() {
 		this.#ended = true;
 		const taker = this.#taker;
@@ -723,7 +714,7 @@ ${list}
 		this.#taker = void 0;
 		taker(void 0);
 	}
-	/** Close the walk's reader and release a waiting question — the walk is over, so the stream must stop holding the process open. */
+	/** Closes the walk's reader and releases a waiting question — the walk is over, so the stream must stop holding the process open. */
 	#close() {
 		const taker = this.#taker;
 		this.#taker = void 0;
@@ -735,14 +726,14 @@ ${list}
 		rl.close();
 	}
 	/**
-	* Narrow the resolved input to the `node:readline` `createInterface` boundary, never an assertion.
+	* Narrows the resolved input to the `node:readline` `createInterface` boundary, never an assertion.
 	* The fallback only runs on a real piped `process.stdin` (or a `PassThrough` a test injects), both
 	* genuine readables; a minimal non-readable fake reaching here means the walk was driven with a
 	* stream it cannot use, which fails loudly rather than silently. `terminal: false` leaves readline
 	* as a line decoder and nothing else: the walk writes every prompt itself, through the same output
 	* every other line goes to, so nothing is written twice and a secret is never echoed.
 	*/
-	#readline() {
+	#openReadline() {
 		const input = this.#input;
 		if (!isReadable(input)) throw new TerminalError("DRIVER", "Terminal fallback requires a readable input stream");
 		return {
@@ -754,7 +745,7 @@ ${list}
 //#endregion
 //#region src/server/factories.ts
 /**
-* Create the interactive terminal form driver — the local-keyboard arm of the terminal trio, beside
+* 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
@@ -767,7 +758,7 @@ ${list}
 * @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
@@ -800,6 +791,6 @@ function createTerminal(options) {
 	return new Terminal(options);
 }
 //#endregion
-export { CARRIAGE_RETURN, CLEAR_DOWN, CONTROL_HINTS, CSI, CSI_UP, CURSOR_HIDE, CURSOR_SHOW, ESCAPE, FALLBACK_CHECKBOX_HINT, FALLBACK_CONFIRM_HINT, FALLBACK_EDITOR_HINT, FALLBACK_SELECT_HINT, FILE_HINT, LINE_FEED, LOCKED_MARK, REFUSAL_MESSAGE, SUGGESTION_LEAD, Terminal, UNAVAILABLE_LEAD, createTerminal, disabledChoices, enabledChoices, fieldToText, groupHeader, isInputStream, isOutputStream, isReadable, lineCount, lockedLine, moveUp, numberedList, rawCapable, redrawPrefix, suggestionLine, unavailableLine, valueToText };
+export { CLEAR_DOWN, CONTROL_HINTS, CSI_UP, CURSOR_HIDE, CURSOR_SHOW, FALLBACK_CHECKBOX_HINT, FALLBACK_CONFIRM_HINT, FALLBACK_EDITOR_HINT, FALLBACK_SELECT_HINT, FILE_HINT, LOCKED_MARK, REFUSAL_MESSAGE, SUGGESTION_LEAD, Terminal, UNAVAILABLE_LEAD, createTerminal, fieldToText, filterDisabled, filterEnabled, isInputStream, isReadable, lineCount, redrawPrefix, renderCursorUp, renderGroupHeader, renderLockedLine, renderNumberedList, renderSuggestionLine, renderUnavailableLine, supportsRawMode, valueToText };
 
 //# sourceMappingURL=index.js.map