@orkestrel/terminal 0.0.8 → 0.0.10

package/dist/src/server/index.js

@@ -1,4 +1,6 @@
-import { TerminalError, checkboxReduce, confirmReduce, createCheckboxState, createConfirmState, createEditorState, createInputState, createPasswordState, createSelectState, editorReduce, hintedHeader, inputReduce, parseKey, passwordReduce, promptHeader, resolveValidation, selectReduce } from "../core/index.js";
+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 { matchesAnswer, parseValue } from "@orkestrel/form";
+import { createStyler } from "@orkestrel/console";
 import { createInterface } from "node:readline";
 import { stdin, stdout } from "node:process";
 //#region src/server/constants.ts
@@ -8,8 +10,8 @@ var ESCAPE = String.fromCharCode(27);
 var CSI = `[`;
 /**
 * The cursor-UP sequence TEMPLATE (`ESC[{count}A`) — {@link import('./helpers.js').moveUp}
-* interpolates `{count}` with the number of lines to climb (the `{count}` placeholder idiom the core
-* terminals' `RULE_MESSAGES` uses). Kept as a template so the count stays out of the constant.
+* interpolates the `{count}` placeholder with the number of lines to climb. Kept as a template so
+* the count stays out of the constant.
 */
 var CSI_UP = `${CSI}{count}A`;
 /**
@@ -30,13 +32,47 @@ 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` / `checkbox`
-* fallback appends — a piped (non-terminal) stream cannot navigate with arrow keys, so the choices are
-* printed numbered and the user types the number(s) on a single readline line.
+* The numbered-list prompt the non-TTY {@link import('./Terminal.js').Terminal} `select` fallback
+* appends — a piped (non-terminal) stream cannot navigate with arrow keys, so the choices are
+* printed numbered and the user types one number on a single readline line.
 */
 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). */
 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. */
+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. */
+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 —
+* the terminal has no date picker, no color well, and no file chooser, so the accepted shape is
+* stated instead. A control with no entry needs none: `text` and `editor` accept any line,
+* `password` masks one, and `confirm`, `select`, and `checkbox` are answered by key rather than by
+* format. The form's own rules still decide whether the typed value is acceptable.
+*/
+var CONTROL_HINTS = Object.freeze({
+	number: "(number)",
+	date: "(YYYY-MM-DD)",
+	time: "(HH:MM)",
+	datetime: "(YYYY-MM-DDTHH:MM)",
+	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. */
+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. */
+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. */
+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. */
+var LOCKED_MARK = "(locked)";
+/**
+* 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.
+*/
+var REFUSAL_MESSAGE = "Enter a value this field accepts";
 //#endregion
 //#region src/server/helpers.ts
 /**
@@ -84,18 +120,6 @@ function isReadable(value) {
 	return typeof value === "object" && value !== null && "read" in value && typeof value.read === "function" && "pipe" in value && typeof value.pipe === "function";
 }
 /**
-* 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
-*/
-function isWritable(value) {
-	return typeof value === "object" && value !== null && "write" in value && typeof value.write === "function" && "end" in value && typeof value.end === "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:
 * `true` ⇒ the interactive raw-mode prompts (arrow-key navigation, live re-render); `false` ⇒ the
@@ -155,81 +179,389 @@ function moveUp(count) {
 function redrawPrefix(previousLines) {
 	return `${moveUp(previousLines - 1)}\r${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`,
+* `time`, `datetime`, `color`, and one `file` entry. The label carries that control's format cue
+* from {@link CONTROL_HINTS}, and a declared `default` becomes the line a bare return submits. The
+* projection carries no rule, because the AUTHORITATIVE form still evaluates the answer this line
+* binds; it exists only so one reducer can render seven controls.
+*
+* @param field - The field being read
+* @returns The text field the reducer renders for it
+*
+* @example
+* ```ts
+* fieldToText({ control: 'date', name: 'born', label: 'Birthday' })
+* // { control: 'text', name: 'born', label: 'Birthday (YYYY-MM-DD)' }
+* ```
+*/
+function fieldToText(field) {
+	const label = field.label ?? field.name;
+	const hint = CONTROL_HINTS[field.control];
+	const seed = "default" in field ? field.default : void 0;
+	const text = typeof seed === "number" ? String(seed) : seed;
+	return {
+		control: "text",
+		name: field.name,
+		label: hint === void 0 ? label : `${label} ${hint}`,
+		...typeof text === "string" ? { default: text } : {}
+	};
+}
+/**
+* Project one held answer into the text a read-only line shows — a scalar as itself, a boolean as
+* `yes` / `no` (the word the confirm reducer commits), and a list joined by commas. Absence renders
+* as nothing, because a locked field nobody has answered has nothing to show.
+*
+* @param value - The answer the form holds for a field, or absence
+* @returns The text to render for it
+*/
+function valueToText(value) {
+	if (value === void 0) return "";
+	if (typeof value === "string") return value;
+	if (typeof value === "number") return String(value);
+	if (typeof value === "boolean") return value ? "yes" : "no";
+	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.
+*
+* @param choices - The field's declared choices
+* @returns The choices the walk offers, in declared order
+*/
+function enabledChoices(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.
+*
+* @param choices - The field's declared choices
+* @returns The refused choices, in declared order
+*/
+function disabledChoices(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) {
+	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
+* validated and still submitted but must not be edited here.
+*
+* @param styler - The console styler that renders each role
+* @param theme - The resolved prompt theme
+* @param label - The field's label
+* @param value - The held answer, from {@link valueToText}
+* @returns The rendered line, with no trailing space when there is nothing to show
+*/
+function lockedLine(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) {
+	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) {
+	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.
+*
+* @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
+*/
+function numberedList(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 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.
+* The interactive terminal form DRIVER — the {@link TerminalInterface} implementation for a human at
+* this machine's keyboard, and the only impure part of the terminal stack. {@link ask} walks one
+* form's fields in schema order, feeds raw-mode stdin bytes through `parseKey` into the matching
+* pure reducer, renders each returned view in place, and binds every answer through the form's own
+* `fill`. It owns no form logic: the schema, the rules, the values, and the settlement all belong to
+* the form it is given, and this class owns only raw mode, the cursor, and the re-render.
 *
 * @remarks
-* See {@link TerminalInterface} for the behavioral contract (raw-mode leak-freedom, the in-place
-* re-render, the non-TTY readline fallback, event-free).
+* See {@link TerminalInterface} for the driving contract. The walk itself:
+*
+* - **Twelve controls, seven reducers.** `text`, `number`, `date`, `time`, `datetime`, `color`, and
+*   each `file` entry are read as one line of text through {@link fieldToText}, which appends that
+*   control's format cue to the label. `password`, `confirm`, `editor`, `select`, and `checkbox`
+*   each drive their own reducer. An open `select` is a suggestion list plus a typed line, because
+*   `open` means the answer need not come from the list.
+* - **The binding projects through `matchesAnswer`.** Every answer is filled as
+*   `fill(name, matchesAnswer(value) ? value : undefined)` after `parseValue` has coerced it to the
+*   control's own shape, so a bare return on a field with no default binds as ABSENCE and the
+*   form's `required` rule refuses it. A typed answer the control cannot hold binds as absence and
+*   invalidates the field, so the walk asks again with the reason on screen.
+* - **Visibility is honored.** A `hidden` field and a field currently in `form.disabled` are
+*   skipped; a `locked` field renders read-only; entering a new group writes its label as a section
+*   header.
+* - **Refusal re-asks.** After the walk the form is submitted. A refusal re-walks only the erroring
+*   fields the walk can edit and submits again. When every erroring field is one the walk cannot
+*   edit — hidden, locked, or disabled — the form is abandoned instead, because asking again could
+*   not change the answer.
+* - **Raw-mode leak-free.** Raw mode is entered once per field and always cleaned up: on submit, on
+*   cancel, on a throw, and when the form is abandoned under an active read.
+* - **Non-TTY fallback.** When `input` is not a TTY, the same walk runs over `node:readline` line
+*   input: `select` and `checkbox` print a numbered list, and `editor` reads to end of input.
 */
 var Terminal = class {
 	#input;
 	#output;
+	#styler;
+	#theme;
 	#handlers = /* @__PURE__ */ new Map();
+	#queue = [];
+	#interface;
+	#taker;
+	#ended = false;
 	constructor(options) {
 		this.#input = isInputStream(options?.input) ? options.input : stdin;
 		this.#output = isOutputStream(options?.output) ? options.output : stdout;
+		this.#styler = createStyler();
+		this.#theme = createPromptTheme(options?.theme);
+	}
+	async ask(form) {
+		try {
+			this.#report(form, form.errors);
+			await this.#walk(form, form.schema.fields);
+			for (;;) {
+				if (form.status !== "editing") return await form.answer;
+				const result = form.submit();
+				if (result.success) return await form.answer;
+				this.#report(form, result.error);
+				const again = this.#editable(form, result.error);
+				if (again.length === 0 || this.#ended) {
+					form.destroy();
+					return await form.answer;
+				}
+				await this.#walk(form, again);
+			}
+		} finally {
+			this.#close();
+		}
+	}
+	/**
+	* Ask `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.
+	*/
+	async #walk(form, fields) {
+		let group;
+		for (const field of fields) {
+			if (form.status !== "editing") return;
+			if (field.hidden === true) continue;
+			if (form.disabled.has(field.name)) continue;
+			if (field.group !== group) {
+				group = field.group;
+				if (group !== void 0) this.#group(form, group);
+			}
+			if (field.locked === true) {
+				this.#locked(form, field);
+				continue;
+			}
+			const raw = await this.#read(form, field);
+			if (form.status !== "editing") return;
+			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) {
+		const label = form.schema.groups?.find((group) => group.name === name)?.label ?? name;
+		this.#output.write(`
+${groupHeader(this.#styler, this.#theme, sanitizeDisplayText(label))}
+`);
+	}
+	/** 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}
+`);
+	}
+	/** Read 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 === "confirm") return this.#confirm(form, field);
+		if (field.control === "editor") return this.#editor(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);
 	}
-	input(options) {
-		const state = createInputState(options);
-		if (rawCapable(this.#input)) return this.#drive(state, inputReduce);
-		return this.#lineFallback(options.message, state.styler, state.theme, void 0, (answer) => {
-			const value = answer.length > 0 ? answer : options.default ?? "";
-			return resolveValidation(options.validate)(value) === true ? { value } : void 0;
-		}, (answer) => answer.length > 0 ? answer : options.default ?? "");
-	}
-	password(options) {
-		const state = createPasswordState(options);
-		if (rawCapable(this.#input)) return this.#drive(state, passwordReduce);
-		return this.#lineFallback(options.message, state.styler, state.theme, void 0, (answer) => resolveValidation(options.validate)(answer) === true ? { value: answer } : void 0, (answer) => answer, true);
-	}
-	confirm(options) {
-		const state = createConfirmState(options);
-		if (rawCapable(this.#input)) return this.#drive(state, confirmReduce);
-		return this.#lineFallback(options.message, state.styler, state.theme, state.hint, (answer) => {
-			const normalized = answer.trim().toLowerCase();
-			if (normalized.length === 0) return { value: options.default ?? false };
-			if (normalized === "y" || normalized === "yes") return { value: true };
-			if (normalized === "n" || normalized === "no") return { value: false };
-		}, () => options.default ?? false);
-	}
-	select(options) {
-		const state = createSelectState(options);
-		if (rawCapable(this.#input)) return this.#drive(state, selectReduce);
-		return this.#listFallback(options.message, state.styler, state.theme, state.choices, state.hint ?? "Enter a number", (line) => {
-			const index = Number.parseInt(line.trim(), 10) - 1;
-			const choice = state.choices[index];
-			return choice === void 0 ? void 0 : { value: choice.value };
-		}, "");
-	}
-	checkbox(options) {
-		const state = createCheckboxState(options);
-		if (rawCapable(this.#input)) return this.#drive(state, checkboxReduce);
-		return this.#listFallback(options.message, state.styler, state.theme, state.choices, state.hint ?? "Enter numbers separated by commas", (line) => {
-			const indices = line.split(",").map((part) => Number.parseInt(part.trim(), 10) - 1).filter((index) => index >= 0 && index < state.choices.length);
-			if (options.min !== void 0 && indices.length < options.min) return void 0;
-			if (options.max !== void 0 && indices.length > options.max) return void 0;
-			return { value: indices.map((index) => state.choices[index]?.value).filter((value) => value !== void 0) };
-		}, []);
-	}
-	editor(options) {
-		const state = createEditorState(options);
-		if (rawCapable(this.#input)) return this.#drive(state, editorReduce);
-		return this.#editorFallback(state);
+	/**
+	* Bind 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
+	* back on the next pass carrying the reason rather than vanishing silently.
+	*/
+	#bind(form, field, raw) {
+		form.touch(field.name);
+		const value = raw === void 0 ? void 0 : parseValue(field, raw);
+		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) {
+		const fields = [];
+		for (const error of errors) {
+			const field = form.field(error.field);
+			if (field === void 0) continue;
+			if (field.hidden === true || field.locked === true) continue;
+			if (form.disabled.has(field.name)) continue;
+			if (fields.some((held) => held.name === field.name)) continue;
+			fields.push(field);
+		}
+		return fields;
+	}
+	/** Write 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}
+`);
+		}
+	}
+	/** Read a field as one line of text — `text` itself and the six controls a terminal has no widget for. */
+	#text(form, field) {
+		const state = createInputState(fieldToText(field), this.#styler, this.#theme);
+		if (rawCapable(this.#input)) return this.#drive(form, state, inputReduce);
+		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) {
+		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));
+	}
+	/**
+	* Read 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);
+		const line = await this.#prompt(form, header);
+		const answer = line.trim().toLowerCase();
+		if (answer.length === 0) return state.default;
+		if (answer === "y" || answer === "yes") return true;
+		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) {
+		const state = createEditorState(field, this.#styler, this.#theme);
+		if (rawCapable(this.#input)) return this.#drive(form, state, editorReduce);
+		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
+	* 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);
+		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)}
+`);
+			}
+			return this.#text(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}:`));
+		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
+	* 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 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);
+	}
+	/**
+	* Read 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)}
+`);
+		const paths = [];
+		for (;;) {
+			const entry = await this.#text(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);
+		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) {
+		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
 	* 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, or throw.
+	* leaves raw mode, and pauses the stream on submit, cancel, abandon, or throw.
 	*/
 	#enterRaw(token, handler) {
 		this.#handlers.set(token, handler);
@@ -246,21 +578,20 @@ var Terminal = class {
 		this.#input.pause?.();
 	}
 	/**
-	* Drive ONE interactive prompt over raw-mode stdin — the generic engine all six TTY prompts share.
-	* 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 + resolves the reducer's `value`, on
-	* `cancel` (ctrl-c) it cleans up + rejects a {@link TerminalError} (`CANCEL`). Raw mode is entered
-	* exactly once and cleaned up on every exit path (submit / cancel / a throw inside a step), so no
-	* raw mode and no `'data'` listener ever leak. The cursor is hidden for the duration and restored
-	* on exit.
+	* Drive 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
+	* the form ends the read too, through the rejection of its own `answer`. Raw mode is entered
+	* exactly once and cleaned up on every exit path, so no raw mode and no `'data'` listener ever
+	* leaks. The cursor is hidden for the duration and restored on exit.
 	*/
-	#drive(initial, reduce) {
+	#drive(form, initial, reduce) {
 		return new Promise((resolve, reject) => {
-			const state = initial;
 			this.#output.write(CURSOR_HIDE);
 			let firstView;
 			try {
-				firstView = reduce(state, parseKey("")).view;
+				firstView = reduce(initial, parseKey("")).view;
 				this.#output.write(firstView);
 			} catch (error) {
 				this.#output.write(`${CURSOR_SHOW}
@@ -269,8 +600,9 @@ var Terminal = class {
 				return;
 			}
 			const token = {};
-			const handler = this.#createHandler(token, state, lineCount(firstView), reduce, resolve, reject);
+			const handler = this.#createHandler(token, initial, lineCount(firstView), reduce, resolve, reject);
 			this.#enterRaw(token, handler);
+			form.answer.catch((error) => this.#interrupt(token, reject, error));
 		});
 	}
 	#createHandler(token, initial, initialLines, reduce, resolve, reject) {
@@ -300,169 +632,174 @@ var Terminal = class {
 			}
 		};
 	}
-	/** Redraw a prompt view in place — climb over the previous view's `previousLines`, clear, and write the new view (the pure cursor-math is {@link redrawPrefix}). */
+	/** 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. */
+	#interrupt(token, reject, error) {
+		if (!this.#handlers.has(token)) return;
+		this.#leaveRaw(token);
+		this.#output.write(`${CURSOR_SHOW}
+`);
+		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}). */
 	#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. */
+	async #line(form, message, seed) {
+		const answer = await this.#prompt(form, promptHeader(this.#styler, this.#theme, message));
+		return answer.length > 0 ? answer : seed;
+	}
 	/**
-	* Read a single line via `node:readline` and accept it through `take` — the non-TTY line-input
-	* fallback shared by `input` / `password` / `confirm`. Re-prompts until `take` returns a value (so
-	* validation still gates), writing the prompt header each round. A piped stream cannot enter raw
-	* mode, so there is no masking / live edit — just a validated line read.
-	*
-	* @remarks
-	* The re-prompt loop is bounded by end-of-input: once the stream reaches EOF (a piped stream that
-	* ran out, or one with no trailing newline) it can never deliver another line, so re-prompting
-	* would SPIN. On EOF the loop accepts the final line through `take` if it passes, else returns the
-	* caller's `eof` fallback (the default / empty value) — the prompt always settles, never spins.
+	* Read 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 #lineFallback(message, styler, theme, hint, take, eof, masked = false) {
+	async #block(form, message, seed) {
+		const header = hintedHeader(this.#styler, this.#theme, message, FALLBACK_EDITOR_HINT);
+		this.#output.write(`${header}
+`);
+		const collected = [];
 		for (;;) {
-			const { answer, ended } = await this.#question(`${hintedHeader(styler, theme, message, hint)} `, masked);
-			const accepted = take(answer);
-			if (accepted !== void 0) return accepted.value;
-			if (ended) return eof(answer);
+			const line = await this.#next(form);
+			if (line === void 0) break;
+			collected.push(line);
 		}
+		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. */
+	async #prompt(form, header) {
+		this.#output.write(`${header} `);
+		return await this.#next(form) ?? "";
 	}
 	/**
-	* Print a numbered choice list, then read one readline line and accept it through `take` — the
-	* non-TTY fallback for `select` / `checkbox`. The list is rendered once; the user types the
-	* number(s); `take` parses + gates the line, re-prompting until it returns a value. Each index is
-	* painted by the `muted` role and each choice name by the `content` role.
+	* Take 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.
 	*/
-	async #listFallback(message, styler, theme, choices, hint, take, eof) {
-		let list = `${promptHeader(styler, theme, message)}\n`;
-		choices.forEach((choice, index) => {
-			list += `  ${styler.render(theme.roles.muted, `${String(index + 1)})`)} ${styler.render(theme.roles.content, choice.name)}\n`;
+	#next(form) {
+		const buffered = this.#queue.shift();
+		if (buffered !== void 0) return Promise.resolve(buffered);
+		if (this.#ended) return Promise.resolve(void 0);
+		this.#reader();
+		return new Promise((resolve, reject) => {
+			this.#taker = resolve;
+			form.answer.catch((error) => {
+				if (this.#taker !== resolve) return;
+				this.#taker = void 0;
+				reject(error);
+			});
 		});
-		this.#output.write(list);
-		for (;;) {
-			const { answer, ended } = await this.#question(`${styler.render(theme.roles.hint, `${hint}:`)} `);
-			const accepted = take(answer);
-			if (accepted !== void 0) return accepted.value;
-			if (ended) return eof;
-		}
 	}
 	/**
-	* The non-TTY `editor` fallback — read lines until EOF (the readline `close`), join them, and fall
-	* back to the default when empty. A piped stream has no ctrl-d keypress, so end-of-input is the
-	* natural terminator.
-	*
-	* @remarks
-	* Single-pass by necessity: `#lines` drains the whole stream to EOF in one read, so there is no
-	* second block to re-prompt for (re-reading an exhausted stream returns nothing forever). Validation
-	* is still applied; on a validation FAILURE the best-effort block is returned rather than spinning
-	* on the consumed stream — the EOF analogue of the raw-mode editor's re-edit, which a piped stream
-	* cannot offer.
+	* Open the walk's ONE readline interface, or keep 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.
 	*/
-	async #editorFallback(state) {
-		this.#output.write(`${hintedHeader(state.styler, state.theme, state.message, state.hint ?? "(EOF to finish)")}\n`);
-		const text = await this.#lines();
-		return text.length > 0 ? text : state.default;
+	#reader() {
+		if (this.#interface !== void 0) return;
+		const rl = createInterface(this.#readline());
+		rl.on("line", (line) => this.#accept(line));
+		rl.on("close", () => this.#finish());
+		this.#interface = rl;
 	}
-	/**
-	* Ask one readline question on the resolved streams and resolve the typed (un-trimmed) line plus
-	* whether the stream ENDED. EOF (the readline `close`) before `rl.question`'s callback fires
-	* resolves instead of hanging — a piped stream commonly ends WITHOUT a trailing newline (or is
-	* empty), and the `question` callback only fires on a NEWLINE-terminated line, so without this the
-	* prompt would wait forever. The trailing unterminated line is still recovered: readline emits it
-	* as a `'line'` event just before `'close'`, so the last seen line (or `''` for a truly empty
-	* stream) is returned with `ended: true`. The `ended` flag lets the fallback loops settle rather
-	* than re-prompt an exhausted stream (which would SPIN). Settling is one-shot (a `close` after a
-	* delivered line is ignored, so a normal newline-terminated line reports `ended: false`).
-	*/
-	#question(prompt, masked = false) {
-		const rl = createInterface(this.#readline(masked));
-		return new Promise((resolve) => {
-			let last = "";
-			const settle = this.#createQuestionSettler(rl, resolve);
-			rl.on("line", (line) => {
-				last = line;
-			});
-			rl.question(prompt, (answer) => settle(answer, false));
-			rl.on("close", () => settle(last, true));
-		});
+	/** Hand a line to whoever is waiting for it, or buffer it for the next question. */
+	#accept(line) {
+		const taker = this.#taker;
+		if (taker === void 0) {
+			this.#queue.push(line);
+			return;
+		}
+		this.#taker = void 0;
+		taker(line);
 	}
-	#createQuestionSettler(rl, resolve) {
-		let settled = false;
-		return (answer, ended) => {
-			if (settled) return;
-			settled = true;
-			rl.close();
-			resolve({
-				answer,
-				ended
-			});
-		};
+	/** Record that no further line can arrive and release whoever was waiting for one. */
+	#finish() {
+		this.#ended = true;
+		const taker = this.#taker;
+		if (taker === void 0) return;
+		this.#taker = void 0;
+		taker(void 0);
 	}
-	/** Read every line from the input until EOF and resolve them joined by newlines (the editor fallback's reader). */
-	#lines() {
-		const rl = createInterface(this.#readline());
-		const collected = [];
-		return new Promise((resolve) => {
-			rl.on("line", (line) => collected.push(line));
-			rl.on("close", () => resolve(collected.join("\n")));
-		});
+	/** Close the walk's reader and release 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;
+		if (taker !== void 0) taker(void 0);
+		const rl = this.#interface;
+		if (rl === void 0) return;
+		this.#interface = void 0;
+		rl.removeAllListeners("close");
+		rl.close();
 	}
 	/**
-	* Narrow the resolved streams to the `node:readline` `createInterface` boundary (§14, never an
-	* `as`). The non-TTY 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 fallback
-	* was driven with a stream it cannot use, which fails loudly rather than silently.
+	* Narrow 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(masked = false) {
+	#readline() {
 		const input = this.#input;
-		const output = this.#output;
 		if (!isReadable(input)) throw new TerminalError("DRIVER", "Terminal fallback requires a readable input stream");
 		return {
 			input,
-			...isWritable(output) ? { output } : {},
-			...masked ? { terminal: false } : {}
+			terminal: false
 		};
 	}
 };
 //#endregion
 //#region src/server/factories.ts
 /**
-* Create the interactive terminal prompt {@link TerminalInterface} (T-c) — the local-TTY arm of the
-* prompt tri-surface, the env-symmetric sibling of the core headless `createPrompt` broker and the
-* SSE `createPromptClient` bridge. A `Terminal` answers each prompt LOCALLY at this machine's
-* keyboard: it reads raw-mode stdin, drives the pure core `*Reduce` reducers, renders each `view` in
-* place, and resolves on submit / rejects with a {@link import('@src/core').TerminalError} (`CANCEL`)
-* on ctrl-c. It is the ONLY impure part of the prompt stack.
+* Create the interactive terminal form driver — the local-keyboard arm of the terminal trio, beside
+* the core headless `createPrompt` broker and the SSE `createPromptClient` bridge. Where the broker
+* PARKS a live form until somebody elsewhere answers it, a `Terminal` answers one HERE: it walks the
+* form's fields in schema order, drives each control's pure reducer over raw-mode stdin, binds every
+* answer through the form's own `fill`, and submits. It is the only impure part of the terminal
+* stack.
 *
 * @param options - See {@link TerminalOptions}
-* @returns A {@link TerminalInterface} — the six async prompt forms (`input` / `password` / `confirm`
-*   / `select` / `checkbox` / `editor`) driven over the resolved streams
+* @returns A {@link TerminalInterface} whose `ask` drives one whole form over the resolved streams
 *
 * @remarks
-* - **Drives the pure reducers.** Each prompt builds its initial state (`create*State`), enters raw
-*   mode ONCE, and feeds each keypress through `parseKey` → the reducer → an in-place re-render; the
-*   driver owns no prompt logic itself (state / view / validation / cancel all come from the core).
-* - **Raw-mode leak-free.** Raw mode is entered exactly once per prompt and ALWAYS cleaned up — on
-*   submit, on cancel, and on a throw — leaving no raw mode and no leaked `'data'` listener.
-* - **Injectable + guard-narrowed.** `options.input` / `options.output` default to `process.stdin` /
-*   `process.stdout` but accept ANY {@link import('./types.js').InputStreamInterface} /
-*   {@link import('./types.js').OutputStreamInterface}, resolved through their §14 guards (never an
-*   `as`), so a test drives every prompt with a fake TTY that emits scripted key chunks and records
-*   the rendered output — and asserts the resolved value, cancel-on-ctrl-c, and no leaked raw mode.
-* - **Non-TTY fallback.** When `input` is not a TTY (piped), raw mode is unavailable, so the prompts
-*   fall back to `node:readline` line input (still validating); `select` / `checkbox` present a
-*   numbered list, and `editor` reads lines until EOF.
+* - **The form is the unit.** `ask` takes the caller's live form and returns its settled values. The
+*   returned promise is that form's own `answer`, so a caller holding the form can await either one.
+* - **Every control renders.** Seven controls are read as a line of text with their format cue,
+*   `password` masks, `confirm` takes a key, `editor` takes a block, `select` and `checkbox` drive a
+*   list, and an open `select` accepts a value its list does not offer.
+* - **The form decides.** A blank answer binds as absence, the form evaluates, and a refusal
+*   re-walks only the fields the walk can still edit.
+* - **Injectable and guard-narrowed.** `input` and `output` default to `process.stdin` and
+*   `process.stdout` but accept any stream of the declared minimal shape, resolved through their
+*   guards rather than an assertion, so a test drives a whole form with a fake TTY that emits
+*   scripted key chunks and records every rendered byte.
+* - **Non-TTY fallback.** A piped stream cannot enter raw mode, so the same walk runs over
+*   `node:readline` line input.
 *
 * @example
 * ```ts
-* import { createTerminal } from '@src/server'
+* import { createForm } from '@orkestrel/form'
+* import { createTerminal } from '@orkestrel/terminal/server'
 *
 * const terminal = createTerminal()
-* const name = await terminal.input({ message: 'Your name' })
-* const proceed = await terminal.confirm({ message: 'Continue?', default: true })
+* const values = await terminal.ask(
+* 	createForm({
+* 		label: 'Sign up',
+* 		fields: [
+* 			{ control: 'text', name: 'email', label: 'Email', rule: { required: true, email: true } },
+* 			{ control: 'confirm', name: 'terms', label: 'I accept the terms' },
+* 		],
+* 	}),
+* )
 * ```
 */
 function createTerminal(options) {
 	return new Terminal(options);
 }
 //#endregion
-export { CARRIAGE_RETURN, CLEAR_DOWN, CSI, CSI_UP, CURSOR_HIDE, CURSOR_SHOW, ESCAPE, FALLBACK_CHECKBOX_HINT, FALLBACK_SELECT_HINT, LINE_FEED, Terminal, createTerminal, isInputStream, isOutputStream, isReadable, isWritable, lineCount, moveUp, rawCapable, redrawPrefix };
+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 };
 
 //# sourceMappingURL=index.js.map