@orkestrel/terminal 0.0.12 → 0.0.14

package/dist/src/core/index.js

@@ -1,47 +1,43 @@
-import { STATUS_ICONS, createStyler, freezeStyle, strip, stripControls } from "@orkestrel/console";
+import { CSI, ESC, STATUS_ICONS, createStyler, freezeStyle, strip, stripControls } from "@orkestrel/console";
 import { arrayOf, attempt, isArray, isBoolean, isNonEmptyString, isNumber, isRecord, isString, literalOf, parseJSON, rawShape, recordOf, stringShape } from "@orkestrel/contract";
 import { Emitter } from "@orkestrel/emitter";
 import { createForm, isFieldError, isFormError, parseForm, serializeForm } from "@orkestrel/form";
 import { createSSEParser } from "@orkestrel/sse";
 import { createDatabase, createMemoryDriver } from "@orkestrel/database";
 //#region src/core/constants.ts
-/** Carriage return (`\r`, U+000D) — Enter on most terminals. */
+/** Names the carriage return byte (`\r`, U+000D) — Enter on most terminals. */
 var RETURN = String.fromCharCode(13);
-/** Line feed (`\n`, U+000A) — Enter on some terminals / pasted input. */
+/** Names the line feed byte (`\n`, U+000A) — Enter on some terminals / pasted input. */
 var NEWLINE = String.fromCharCode(10);
-/** Tab (`\t`, U+0009). */
+/** Names the tab byte (`\t`, U+0009). */
 var TAB = String.fromCharCode(9);
-/** Escape (ESC, U+001B) — the lone byte, and the lead byte of every CSI / SS3 sequence. */
-var ESCAPE = String.fromCharCode(27);
-/** Backspace (BS, U+0008) — Ctrl+H / some terminals' Backspace. */
+/** Names the backspace byte (BS, U+0008) — Ctrl+H / some terminals' Backspace. */
 var BACKSPACE = String.fromCharCode(8);
-/** Delete (DEL, U+007F) — the usual Backspace byte on a Unix TTY. */
+/** Names the delete byte (DEL, U+007F) — the usual Backspace byte on a Unix TTY. */
 var DELETE = String.fromCharCode(127);
-/** Space (U+0020). */
+/** Names the space byte (U+0020). */
 var SPACE = " ";
-/** Ctrl+C (ETX, U+0003) — interrupt / cancel. */
+/** Names the Ctrl+C byte (ETX, U+0003) — interrupt / cancel. */
 var CTRL_C = String.fromCharCode(3);
-/** Ctrl+D (EOT, U+0004) — end-of-transmission / finish (the editor's commit key). */
+/** Names the Ctrl+D byte (EOT, U+0004) — end-of-transmission / finish (the editor's commit key). */
 var CTRL_D = String.fromCharCode(4);
-/** Ctrl+U (NAK, U+0015) — clear the current line. */
+/** Names the Ctrl+U byte (NAK, U+0015) — clear the current line. */
 var CTRL_U = String.fromCharCode(21);
-/** Ctrl+A (SOH, U+0001) — move to start of line. */
+/** Names the Ctrl+A byte (SOH, U+0001) — move to start of line. */
 var CTRL_A = String.fromCharCode(1);
-/** Ctrl+E (ENQ, U+0005) — move to end of line. */
+/** Names the Ctrl+E byte (ENQ, U+0005) — move to end of line. */
 var CTRL_E = String.fromCharCode(5);
 /**
-* The Control Sequence Introducer lead (`ESC[`) for the navigation keys — the prefix of the
-* arrow / home / end / delete sequences {@link SEQUENCE_NAMES} is keyed by. Named `KEY_CSI`
-* (not `CSI`) so it never collides with the console module's SGR `CSI` (both barrel through
-* `@src/core`).
+* Names the Single Shift Three lead (`ESCO`) — the alternate arrow-key prefix some terminals emit
+* (`ESC O A`). Built from the console module's own {@link import('@orkestrel/console').ESC}; the
+* navigation keys' CSI lead is that module's {@link import('@orkestrel/console').CSI}, which this
+* package reuses rather than redeclaring.
 */
-var KEY_CSI = `[`;
-/** The Single Shift Three lead (`ESCO`) — the alternate arrow-key prefix some terminals emit (`ESC O A`). */
-var KEY_SS3 = `O`;
+var KEY_SS3 = `${ESC}O`;
 /**
-* The exact escape SEQUENCE → canonical key NAME table {@link import('./helpers.js').parseKey}
+* Holds the exact escape SEQUENCE → canonical key NAME table {@link import('./helpers.js').parseKey}
 * consults for the navigation / editing keys. Covers BOTH the CSI form (`ESC[A`…) and the SS3
-* form (`ESCOA`…) of the four arrows, plus the `home` / `end` / `delete` CSI sequences (with
+* form (`ESCOA`…) of the arrows, plus the `home` / `end` / `delete` CSI sequences (with
 * their numeric-tilde variants). The source of truth for the multi-byte key decode; frozen.
 *
 * @remarks
@@ -51,32 +47,34 @@ var KEY_SS3 = `O`;
 * sees the wire encoding.
 */
 var SEQUENCE_NAMES = Object.freeze({
-	[`${KEY_CSI}A`]: "up",
-	[`${KEY_CSI}B`]: "down",
-	[`${KEY_CSI}C`]: "right",
-	[`${KEY_CSI}D`]: "left",
+	[`${CSI}A`]: "up",
+	[`${CSI}B`]: "down",
+	[`${CSI}C`]: "right",
+	[`${CSI}D`]: "left",
 	[`${KEY_SS3}A`]: "up",
 	[`${KEY_SS3}B`]: "down",
 	[`${KEY_SS3}C`]: "right",
 	[`${KEY_SS3}D`]: "left",
-	[`${KEY_CSI}H`]: "home",
-	[`${KEY_CSI}F`]: "end",
-	[`${KEY_CSI}1~`]: "home",
-	[`${KEY_CSI}4~`]: "end",
-	[`${KEY_CSI}3~`]: "delete",
-	[`${KEY_CSI}7~`]: "home",
-	[`${KEY_CSI}8~`]: "end"
+	[`${CSI}H`]: "home",
+	[`${CSI}F`]: "end",
+	[`${CSI}1~`]: "home",
+	[`${CSI}4~`]: "end",
+	[`${CSI}3~`]: "delete",
+	[`${CSI}7~`]: "home",
+	[`${CSI}8~`]: "end"
 });
 /**
-* The single control BYTE → key descriptor table {@link import('./helpers.js').parseKey}
-* consults for the one-byte keys. Each entry carries the canonical `name` and whether it is a
-* `ctrl` combination. The source of truth for the single-byte key decode; frozen.
+* Holds the control BYTE (or CRLF pair) → key descriptor table {@link import('./helpers.js').parseKey}
+* consults for the one-byte keys and the two-byte CRLF Enter chunk. Each entry carries the
+* canonical `name` and whether it is a `ctrl` combination. The source of truth for that decode;
+* frozen.
 *
 * @remarks
-* `return` / `newline` map to `return` (one canonical Enter name); `delete` / `backspace` both
-* map to `backspace` (the two Backspace bytes); the Ctrl combos (`c` / `d` / `u` / `a` / `e`)
-* carry `ctrl: true` so a reducer can match `key.ctrl && key.name === 'c'`. `escape` / `tab` /
-* `space` are plain named keys.
+* `return` / `newline` / `return + newline` all map to `return` (one canonical Enter name) — a
+* terminal or a paste can deliver Enter as `\r`, `\n`, or the `\r\n` pair in one chunk;
+* `delete` / `backspace` both map to `backspace` (the Backspace bytes); the Ctrl combos
+* (`c` / `d` / `u` / `a` / `e`) carry `ctrl: true` so a reducer can match
+* `key.ctrl && key.name === 'c'`. `escape` / `tab` / `space` are plain named keys.
 */
 var CONTROL_NAMES = Object.freeze({
 	["\r"]: Object.freeze({
@@ -87,11 +85,16 @@ var CONTROL_NAMES = Object.freeze({
 		name: "return",
 		ctrl: false
 	}),
+	[`\r
+`]: Object.freeze({
+		name: "return",
+		ctrl: false
+	}),
 	["	"]: Object.freeze({
 		name: "tab",
 		ctrl: false
 	}),
-	["\x1B"]: Object.freeze({
+	[ESC]: Object.freeze({
 		name: "escape",
 		ctrl: false
 	}),
@@ -128,10 +131,10 @@ var CONTROL_NAMES = Object.freeze({
 		ctrl: true
 	})
 });
-/** The default mask glyph {@link import('./helpers.js').createPasswordState} uses — `*`. */
+/** Names the default mask glyph {@link import('./helpers.js').createPasswordState} uses — `*`. */
 var DEFAULT_MASK = "*";
 /**
-* The six default glyphs {@link DEFAULT_PROMPT_THEME} assembles its `icons` from. Read only when
+* Holds the default glyphs {@link DEFAULT_PROMPT_THEME} assembles its `icons` from. Read only when
 * the default theme is assembled; a view reads its resolved theme and never this constant. Frozen.
 *
 * @remarks
@@ -149,7 +152,7 @@ var PROMPT_ICONS = Object.freeze({
 	unchecked: "☐"
 });
 /**
-* Every {@link import('./types.js').PromptRole}, in one frozen list — the role axis's source of
+* Holds every {@link import('./types.js').PromptRole}, in one frozen list — the role axis's source of
 * truth. {@link import('./helpers.js').createPromptTheme} walks it to merge a partial theme, and
 * a consumer building a complete role map reads it rather than retyping every name.
 */
@@ -167,7 +170,7 @@ var PROMPT_ROLES = Object.freeze([
 	"description"
 ]);
 /**
-* The {@link import('./types.js').PromptTheme} every prompt renders with unless its options supply
+* Holds the {@link import('./types.js').PromptTheme} every prompt renders with unless its options supply
 * another — the glyph set assembled from {@link PROMPT_ICONS} plus the console
 * {@link import('@orkestrel/console').STATUS_ICONS} `success` / `error` marks, and the console
 * {@link import('@orkestrel/console').Style} each role is painted with. Deeply frozen through the
@@ -221,30 +224,30 @@ var DEFAULT_PROMPT_THEME = Object.freeze({
 		description: freezeStyle({ attributes: ["dim"] })
 	})
 });
-/** How long (ms) the {@link import('./types.js').PromptInterface} broker parks an unanswered prompt before it expires — 5 minutes. */
+/** Holds how long (ms) the {@link import('./types.js').PromptInterface} broker parks an unanswered prompt before it expires — 5 minutes. */
 var DEFAULT_PROMPT_TIMEOUT_MS = 3e5;
-/** How long (ms) the {@link import('./types.js').PromptClientInterface} waits before each reconnect attempt — 2 seconds. */
+/** Holds how long (ms) the {@link import('./types.js').PromptClientInterface} waits before each reconnect attempt — 2 seconds. */
 var DEFAULT_RECONNECT_DELAY_MS = 2e3;
 /**
-* The SSE `event:` names the broker emits and the {@link import('./types.js').PromptClientInterface}
+* Holds the SSE `event:` names the broker emits and the {@link import('./types.js').PromptClientInterface}
 * dispatches on. Frozen; the source of truth for the wire event vocabulary.
 *
 * @remarks
 * - `pending` — a serialized {@link import('./types.js').PendingForm} to dispatch and answer.
 * - `expire` — an `{ id }` payload: the broker expired or released a parked prompt (the client drops it).
-* - `shutdown` — the broker is going away; the client disconnects (no auto-reconnect) but stays reusable.
+* - `destroy` — the broker is going away; the client disconnects (no auto-reconnect) but stays reusable.
 */
 var SSE_EVENTS = Object.freeze({
 	pending: "pending",
 	expire: "expire",
-	shutdown: "shutdown"
+	destroy: "destroy"
 });
-/** The auth-token request header the {@link import('./types.js').PromptClientInterface} sends. */
+/** Names the auth-token request header the {@link import('./types.js').PromptClientInterface} sends. */
 var HEADER_TOKEN = "x-orkestrel-token";
-/** The `Accept` header value that opens the broker's SSE stream. */
+/** Names the `Accept` header value that opens the broker's SSE stream. */
 var ACCEPT_EVENT_STREAM = "text/event-stream";
 /**
-* The maximum number of characters the {@link import('./types.js').PromptClientInterface} lets its
+* Sets the maximum number of characters the {@link import('./types.js').PromptClientInterface} lets its
 * SSE parser buffer before treating the stream as hostile — 1 MiB, comfortably above any
 * legitimate prompt payload. Passed as the `limit` to `createSSEParser` so an unterminated
 * or oversized `data:` field cannot grow the buffer without bound (a memory-exhaustion guard).
@@ -253,7 +256,7 @@ var SSE_BUFFER_LIMIT = 1048576;
 //#endregion
 //#region src/core/errors.ts
 /**
-* The error the terminal surfaces for its own refusals: parking on a destroyed or full broker, an
+* Represents the error the terminal surfaces for its own refusals: parking on a destroyed or full broker, an
 * unusable driver stream, a manager routing fault, or a ctrl-c cancellation. A parked form's own
 * lifecycle failures reject through the form's `answer` with the form package's error, never with
 * this one.
@@ -264,10 +267,17 @@ var SSE_BUFFER_LIMIT = 1048576;
 * a caught value with {@link isTerminalError} and branch on `error.code`.
 */
 var TerminalError = class extends Error {
-	/** The machine-readable condition — see {@link TerminalErrorCode}. */
+	/** Holds the machine-readable condition — see {@link TerminalErrorCode}. */
 	code;
-	/** An optional context bag naming the offending values — see the class {@link TerminalError remarks}. */
+	/** Holds an optional context bag naming the offending values — see the class {@link TerminalError remarks}. */
 	context;
+	/**
+	* Builds one terminal refusal.
+	*
+	* @param code - The machine-readable {@link TerminalErrorCode} a caller branches on
+	* @param message - The human-readable reason
+	* @param context - The optional bag naming the offending values — see the class {@link TerminalError remarks}
+	*/
 	constructor(code, message, context) {
 		super(message);
 		this.name = "TerminalError";
@@ -276,10 +286,10 @@ var TerminalError = class extends Error {
 	}
 };
 /**
-* Narrow an unknown caught value to a {@link TerminalError}.
+* Narrows an unknown caught value to a {@link TerminalError}.
 *
 * @param value - The value to test (typically a `catch` binding or a rejected prompt call)
-* @returns `true` when `value` is a {@link TerminalError}
+* @returns True if `value` is a {@link TerminalError}; false otherwise
 *
 * @example
 * ```ts
@@ -297,17 +307,22 @@ function isTerminalError(value) {
 }
 //#endregion
 //#region src/core/validators.ts
-/** Narrow an unknown value to a {@link PendingFormStatus}. */
+/**
+* Narrows an unknown value to a {@link PendingFormStatus}.
+*
+* @param value - The candidate ticket status
+* @returns True if the value is one of the declared ticket statuses; false otherwise
+*/
 var isPendingFormStatus = literalOf("pending", "answered", "expired");
 /**
-* Narrow an unknown wire value to a {@link PendingForm} envelope.
+* Narrows an unknown wire value to a {@link PendingForm} envelope.
 *
 * @remarks
 * This guard checks the transport record and proves only that `schema` is a record. The Form
 * package's `parseForm` owns the schema payload and its semantic audit.
 *
 * @param value - The decoded wire value to inspect
-* @returns Whether the value is a complete pending-form envelope
+* @returns True if the value is a complete pending-form envelope; false otherwise
 */
 function isPendingForm(value) {
 	return recordOf({
@@ -320,17 +335,23 @@ function isPendingForm(value) {
 	}, ["from", "to"])(value);
 }
 /**
-* Narrow an unknown value to a transport-neutral {@link WireEvent}.
+* Narrows an unknown value to a transport-neutral {@link WireEvent}.
 *
 * @param value - The candidate wire event
-* @returns Whether the value carries an event name, serialized data, and an optional id
+* @returns True if the value carries an event name, serialized data, and an optional id; false otherwise
 */
 var isWireEvent = recordOf({
 	event: isString,
 	data: isString,
 	id: isString
 }, ["id"]);
-/** Narrow an unknown value to a {@link TerminalSnapshot}. */
+/**
+* Narrows an unknown value to a {@link TerminalSnapshot} — the read boundary a store applies to an
+* untrusted persisted row.
+*
+* @param value - The candidate snapshot read back from storage
+* @returns True if the value carries a non-empty `id` and an optional numeric `timeout`; false otherwise
+*/
 var isTerminalSnapshot = recordOf({
 	id: isNonEmptyString,
 	timeout: isNumber
@@ -338,24 +359,24 @@ var isTerminalSnapshot = recordOf({
 //#endregion
 //#region src/core/helpers.ts
 /**
-* Decode one keypress's bytes into a {@link KeyEvent} — total, never throws. A `Uint8Array` is
-* read as UTF-8; the resulting string is matched against the known control bytes
-* ({@link CONTROL_NAMES}) and escape sequences ({@link SEQUENCE_NAMES}), falling back to a
-* single printable character. An unrecognized sequence yields `name: ''` with the raw `sequence`
+* Decodes one keypress's bytes into a {@link KeyEvent} — total, never throws. A `Uint8Array` is
+* read as UTF-8; the resulting string is matched against the known control bytes and the CRLF
+* pair ({@link CONTROL_NAMES}) and escape sequences ({@link SEQUENCE_NAMES}), falling back to a
+* single printable character. An unrecognized sequence carries NO `name`, with the raw `sequence`
 * preserved.
 *
 * @remarks
 * - **Single control byte.** A one-character control input (`return` / `backspace` / `tab` /
-*   `escape` / `space`, or a Ctrl combo `c` / `d` / `u` / `a` / `e`) is looked up in
-*   {@link CONTROL_NAMES}, carrying its `ctrl` flag.
+*   `escape` / `space`, or a Ctrl combo `c` / `d` / `u` / `a` / `e`), or the two-byte `\r\n`
+*   CRLF pair, is looked up in {@link CONTROL_NAMES}, carrying its `ctrl` flag.
 * - **Escape sequence.** A multi-byte ESC sequence (`up` / `down` / `left` / `right` in BOTH the
 *   `ESC[A` and `ESCOA` forms, plus `home` / `end` / `delete`) is looked up in
 *   {@link SEQUENCE_NAMES} and flagged `meta`.
 * - **Printable character.** A single printable character becomes `name` = that character, with
 *   `shift` set when it is an uppercase letter. A multi-code-point printable (an emoji, a pasted
 *   run) keeps its first code point as the name and the whole input as `sequence`.
-* - **Unknown.** Anything else (an unrecognized escape, an empty input) yields `name: ''` —
-*   total, so the driver never crashes on a stray byte.
+* - **Unknown.** Anything else (an unrecognized escape, an empty input) yields an event with NO
+*   `name` — absence, never an empty string — total, so the driver never crashes on a stray byte.
 *
 * @param input - The raw keypress bytes, as a string or `Uint8Array`
 * @returns The decoded {@link KeyEvent}
@@ -363,6 +384,7 @@ var isTerminalSnapshot = recordOf({
 * @example
 * ```ts
 * parseKey('\r')        // { name: 'return', sequence: '\r', ctrl: false, meta: false, shift: false }
+* parseKey('\r\n')      // { name: 'return', sequence: '\r\n', ctrl: false, meta: false, shift: false }
 * parseKey('\x1b[A')    // { name: 'up', sequence: '\x1b[A', ctrl: false, meta: true, shift: false }
 * parseKey('A')         // { name: 'A', sequence: 'A', ctrl: false, meta: false, shift: true }
 * parseKey('\x03')      // { name: 'c', sequence: '\x03', ctrl: true, meta: false, shift: false }
@@ -395,14 +417,19 @@ function parseKey(input) {
 		shift: first !== first.toLowerCase()
 	};
 	return {
-		name: "",
 		sequence,
 		ctrl: false,
 		meta: false,
 		shift: false
 	};
 }
-/** Whether a single character is a printable (non-control) character — used by {@link parseKey}'s char fallback. */
+/**
+* Checks whether a single character is a printable (non-control) character — used by
+* {@link parseKey}'s char fallback.
+*
+* @param character - The single character to test
+* @returns True if the character is at or above space and is not DEL; false otherwise
+*/
 function isPrintable(character) {
 	if (character.length === 0) return false;
 	const code = character.codePointAt(0);
@@ -410,7 +437,7 @@ function isPrintable(character) {
 	return code >= 32 && code !== 127;
 }
 /**
-* Build a complete {@link PromptTheme} by merging a partial one over
+* Builds a complete {@link PromptTheme} by merging a partial one over
 * {@link DEFAULT_PROMPT_THEME}, leaf by leaf — each supplied icon replaces that glyph, each
 * supplied role replaces that {@link Style}, and everything else keeps its default. Each supplied
 * style is snapshotted through the console module's own
@@ -445,7 +472,7 @@ function createPromptTheme(options) {
 	});
 }
 /**
-* Sanitize text for one single-line display slot. Composes console's ANSI {@link strip} and C0
+* Sanitizes text for one single-line display slot. Composes console's ANSI {@link strip} and C0
 * {@link stripControls} passes with removal of tab, line feed, and carriage return.
 *
 * @param text - The text to sanitize for a glyph or hint slot
@@ -460,7 +487,7 @@ function sanitizeDisplayText(text) {
 	return stripControls(strip(text)).replaceAll("	", "").replaceAll("\n", "").replaceAll("\r", "");
 }
 /**
-* Sanitize every terminal-readable string in a parsed form schema.
+* Sanitizes every terminal-readable string in a parsed form schema.
 *
 * @remarks
 * Display strings pass through {@link sanitizeDisplayText}: labels, help, placeholders, masks,
@@ -502,6 +529,7 @@ function sanitizeSchema(schema) {
 		switch (field.control) {
 			case "text":
 			case "editor":
+			case "number":
 				fields.push({
 					...field,
 					...shared,
@@ -515,22 +543,10 @@ function sanitizeSchema(schema) {
 					...field.mask !== void 0 ? { mask: sanitizeDisplayText(field.mask) } : {}
 				});
 				break;
-			case "number":
-				fields.push({
-					...field,
-					...shared,
-					...field.placeholder !== void 0 ? { placeholder: sanitizeDisplayText(field.placeholder) } : {}
-				});
-				break;
 			case "date":
 			case "time":
 			case "datetime":
 			case "color":
-				fields.push({
-					...field,
-					...shared
-				});
-				break;
 			case "confirm":
 				fields.push({
 					...field,
@@ -538,17 +554,6 @@ function sanitizeSchema(schema) {
 				});
 				break;
 			case "select":
-				fields.push({
-					...field,
-					...shared,
-					choices: field.choices.map((choice) => ({
-						...choice,
-						value: choice.value,
-						label: sanitizeDisplayText(choice.label),
-						...choice.help !== void 0 ? { help: sanitizeDisplayText(choice.help) } : {}
-					}))
-				});
-				break;
 			case "checkbox":
 				fields.push({
 					...field,
@@ -577,7 +582,7 @@ function sanitizeSchema(schema) {
 	};
 }
 /**
-* Sanitize every glyph a wire-supplied {@link PromptThemeOptions} carries for a single-line display
+* Sanitizes every glyph a wire-supplied {@link PromptThemeOptions} carries for a single-line display
 * slot. Only the icons need it: a role is guard-narrowed to a console {@link Style}, whose colors
 * and attributes are fixed name sets, so no role can carry a byte a terminal would act on.
 *
@@ -594,13 +599,21 @@ function sanitizeThemeIcons(theme) {
 		icons: sanitized
 	};
 }
-/** The styled prompt-message header (`? message`) — the leading line every active prompt view shares, themed by the `question` + `message` roles. */
-function promptHeader(styler, theme, message) {
+/**
+* Renders the styled question header (`? message`) — the leading line every active prompt view
+* shares, themed by the `question` + `message` roles.
+*
+* @param styler - The console styler that renders each role
+* @param theme - The resolved prompt theme
+* @param message - The prompt's question text
+* @returns The rendered question header
+*/
+function renderPromptHeader(styler, theme, message) {
 	return `${styler.render(theme.roles.question, theme.icons.question)} ${styler.render(theme.roles.message, message)}`;
 }
 /**
-* Render a prompt header followed by a key hint painted with the `hint` role, or the header alone
-* when no hint is supplied.
+* Renders a question header followed by a key hint painted with the `hint` role, or the header
+* alone when no hint is supplied.
 *
 * @param styler - The console styler that renders each role
 * @param theme - The resolved prompt theme
@@ -608,20 +621,35 @@ function promptHeader(styler, theme, message) {
 * @param hint - The optional key hint to append
 * @returns The rendered header with the optional hint
 */
-function hintedHeader(styler, theme, message, hint) {
-	const head = promptHeader(styler, theme, message);
+function renderHintedHeader(styler, theme, message, hint) {
+	const head = renderPromptHeader(styler, theme, message);
 	return hint === void 0 ? head : `${head} ${styler.render(theme.roles.hint, hint)}`;
 }
-/** The styled submit line (`✔ message`) — the committed header an interactive prompt shows once resolved, themed by the `success` + `message` roles. */
-function submitHeader(styler, theme, message) {
+/**
+* Renders the styled submit line (`✔ message`) — the committed header an interactive prompt shows
+* after it resolves, themed by the `success` + `message` roles.
+*
+* @param styler - The console styler that renders each role
+* @param theme - The resolved prompt theme
+* @param message - The settled prompt's question text
+* @returns The rendered committed header
+*/
+function renderSubmitHeader(styler, theme, message) {
 	return `${styler.render(theme.roles.success, theme.icons.success)} ${styler.render(theme.roles.message, message)}`;
 }
-/** The styled error line (`✖ message`) a form driver appends for a field failure. */
-function errorLine(styler, theme, message) {
+/**
+* Renders the styled failure line (`✖ message`) a form driver appends for a refused field.
+*
+* @param styler - The console styler that renders each role
+* @param theme - The resolved prompt theme
+* @param message - The failure text, normally the field's label and the reason
+* @returns The rendered failure line
+*/
+function renderErrorLine(styler, theme, message) {
 	return `${styler.render(theme.roles.error, theme.icons.error)} ${styler.render(theme.roles.error, message)}`;
 }
 /**
-* Build the initial text-field key state.
+* Builds the initial text-field key state.
 *
 * @param field - The text field to render
 * @param styler - The styler used to render the view
@@ -637,22 +665,31 @@ function createInputState(field, styler = createStyler(), theme) {
 		value: ""
 	};
 }
-/** Render a text-field key state as a styled view. */
-function inputView(state) {
+/**
+* Renders a text-field key state as a styled view.
+*
+* @param state - The text field's current reducer state
+* @returns The rendered single-line view — header, pointer, and the typed value or the default
+*/
+function renderInputView(state) {
 	const content = state.value.length > 0 ? state.value : state.default;
 	const role = state.value.length > 0 ? state.theme.roles.content : state.theme.roles.hint;
 	const shown = state.styler.render(role, sanitizeDisplayText(content));
-	return `${promptHeader(state.styler, state.theme, state.message)} ${state.styler.render(state.theme.roles.pointer, state.theme.icons.pointer)} ${shown}`;
+	return `${renderPromptHeader(state.styler, state.theme, state.message)} ${state.styler.render(state.theme.roles.pointer, state.theme.icons.pointer)} ${shown}`;
 }
 /**
-* Advance an input prompt by one {@link KeyEvent} — the pure `(state, key) → PromptStep<string>`
+* Advances an input prompt by one {@link KeyEvent} — the pure `(state, key) → PromptStep<string>`
 * reducer. Printable characters extend the value; backspace shrinks it; ctrl-u clears it; ctrl-c
 * cancels; return produces the candidate value, with an empty line falling back to the default.
+*
+* @param state - The text field's current reducer state
+* @param key - The decoded keypress to apply
+* @returns The next step — the new state, the rendered view, the status, and the value on submit
 */
-function inputReduce(state, key) {
+function reduceInput(state, key) {
 	if (key.ctrl && key.name === "c") return {
 		state,
-		view: inputView(state),
+		view: renderInputView(state),
 		status: "cancel"
 	};
 	if (key.name === "return") {
@@ -662,7 +699,7 @@ function inputReduce(state, key) {
 				...state,
 				value: answer
 			},
-			view: `${submitHeader(state.styler, state.theme, state.message)} ${state.styler.render(state.theme.roles.hint, sanitizeDisplayText(answer))}`,
+			view: `${renderSubmitHeader(state.styler, state.theme, state.message)} ${state.styler.render(state.theme.roles.hint, sanitizeDisplayText(answer))}`,
 			status: "submit",
 			value: answer
 		};
@@ -670,7 +707,7 @@ function inputReduce(state, key) {
 	const value = editLine(state.value, key);
 	if (value === void 0) return {
 		state,
-		view: inputView(state),
+		view: renderInputView(state),
 		status: "active"
 	};
 	const next = {
@@ -679,12 +716,12 @@ function inputReduce(state, key) {
 	};
 	return {
 		state: next,
-		view: inputView(next),
+		view: renderInputView(next),
 		status: "active"
 	};
 }
 /**
-* Build the initial password-field key state.
+* Builds the initial password-field key state.
 *
 * @param field - The password field to render
 * @param styler - The styler used to render the view
@@ -700,32 +737,41 @@ function createPasswordState(field, styler = createStyler(), theme) {
 		value: ""
 	};
 }
-/** Render a password-field key state as a styled view. */
-function passwordView(state) {
+/**
+* Renders a password-field key state as a styled view.
+*
+* @param state - The password field's current reducer state
+* @returns The rendered view, with the mask repeated in place of the typed value
+*/
+function renderPasswordView(state) {
 	const masked = state.styler.render(state.theme.roles.content, state.mask.repeat(state.value.length));
-	return `${promptHeader(state.styler, state.theme, state.message)} ${state.styler.render(state.theme.roles.pointer, state.theme.icons.pointer)} ${masked}`;
+	return `${renderPromptHeader(state.styler, state.theme, state.message)} ${state.styler.render(state.theme.roles.pointer, state.theme.icons.pointer)} ${masked}`;
 }
 /**
-* Advance a password prompt by one {@link KeyEvent} — the pure `(state, key) → PromptStep<string>`
-* reducer. Identical line-editing to {@link inputReduce} (printable extends, backspace shrinks,
+* Advances a password prompt by one {@link KeyEvent} — the pure `(state, key) → PromptStep<string>`
+* reducer. Identical line-editing to {@link reduceInput} (printable extends, backspace shrinks,
 * ctrl-u clears, ctrl-c cancels) but the view masks the value. Return produces the candidate value.
+*
+* @param state - The password field's current reducer state
+* @param key - The decoded keypress to apply
+* @returns The next step — the new state, the masked view, the status, and the value on submit
 */
-function passwordReduce(state, key) {
+function reducePassword(state, key) {
 	if (key.ctrl && key.name === "c") return {
 		state,
-		view: passwordView(state),
+		view: renderPasswordView(state),
 		status: "cancel"
 	};
 	if (key.name === "return") return {
 		state,
-		view: `${submitHeader(state.styler, state.theme, state.message)} ${state.styler.render(state.theme.roles.hint, state.mask.repeat(state.value.length))}`,
+		view: `${renderSubmitHeader(state.styler, state.theme, state.message)} ${state.styler.render(state.theme.roles.hint, state.mask.repeat(state.value.length))}`,
 		status: "submit",
 		value: state.value
 	};
 	const value = editLine(state.value, key);
 	if (value === void 0) return {
 		state,
-		view: passwordView(state),
+		view: renderPasswordView(state),
 		status: "active"
 	};
 	const next = {
@@ -734,12 +780,12 @@ function passwordReduce(state, key) {
 	};
 	return {
 		state: next,
-		view: passwordView(next),
+		view: renderPasswordView(next),
 		status: "active"
 	};
 }
 /**
-* Build the initial confirm-field key state.
+* Builds the initial confirm-field key state.
 *
 * @param field - The confirm field to render
 * @param styler - The styler used to render the view
@@ -755,43 +801,50 @@ function createConfirmState(field, styler = createStyler(), theme) {
 	};
 }
 /**
-* Render a confirm-field key state as a styled view. The selected role paints the default letter.
+* Renders a confirm-field key state as a styled view. The selected role paints the default letter.
+*
+* @param state - The confirm field's current reducer state
+* @returns The rendered view — the header and the yes/no group with the default capitalized
 */
-function confirmView(state) {
-	const head = promptHeader(state.styler, state.theme, state.message);
+function renderConfirmView(state) {
+	const head = renderPromptHeader(state.styler, state.theme, state.message);
 	const answer = state.default ? `${state.styler.render(state.theme.roles.selected, "Y")}${state.styler.render(state.theme.roles.hint, "/n")}` : `${state.styler.render(state.theme.roles.hint, "y/")}${state.styler.render(state.theme.roles.selected, "N")}`;
 	return `${head} ${state.styler.render(state.theme.roles.hint, "(")}${answer}${state.styler.render(state.theme.roles.hint, ")")}`;
 }
 /**
-* Advance a confirm prompt by one {@link KeyEvent} — the pure `(state, key) → PromptStep<boolean>`
+* Advances a confirm prompt by one {@link KeyEvent} — the pure `(state, key) → PromptStep<boolean>`
 * reducer. `y` / `Y` submits `true`, `n` / `N` submits `false`, return on an empty line submits
 * the `default`, ctrl-c cancels; any other key is ignored (stays active).
+*
+* @param state - The confirm field's current reducer state
+* @param key - The decoded keypress to apply
+* @returns The next step — the state, the rendered view, the status, and the answer on submit
 */
-function confirmReduce(state, key) {
+function reduceConfirm(state, key) {
 	if (key.ctrl && key.name === "c") return {
 		state,
-		view: confirmView(state),
+		view: renderConfirmView(state),
 		status: "cancel"
 	};
 	let answer;
-	const choice = key.name.toLowerCase();
+	const choice = key.name?.toLowerCase();
 	if (key.name === "return") answer = state.default;
 	else if (choice === "y") answer = true;
 	else if (choice === "n") answer = false;
 	if (answer === void 0) return {
 		state,
-		view: confirmView(state),
+		view: renderConfirmView(state),
 		status: "active"
 	};
 	return {
 		state,
-		view: `${submitHeader(state.styler, state.theme, state.message)} ${state.styler.render(state.theme.roles.hint, answer ? "yes" : "no")}`,
+		view: `${renderSubmitHeader(state.styler, state.theme, state.message)} ${state.styler.render(state.theme.roles.hint, answer ? "yes" : "no")}`,
 		status: "submit",
 		value: answer
 	};
 }
 /**
-* Build the initial select-field key state.
+* Builds the initial select-field key state.
 *
 * @param field - The select field to render
 * @param styler - The styler used to render the view
@@ -809,30 +862,39 @@ function createSelectState(field, styler = createStyler(), theme) {
 		focused: index >= 0 ? index : 0
 	};
 }
-/** Render a select-field key state as a multi-line styled view. */
-function selectView(state) {
+/**
+* Renders a select-field key state as a multi-line styled view.
+*
+* @param state - The select field's current reducer state
+* @returns The rendered view — the header, then one row per choice with the focused row marked
+*/
+function renderSelectView(state) {
 	const lines = state.choices.map((choice, index) => {
 		const active = index === state.focused;
 		return `${active ? state.styler.render(state.theme.roles.pointer, state.theme.icons.pointer) : " "} ${active ? state.styler.render(state.theme.roles.selected, state.theme.icons.selected) : state.styler.render(state.theme.roles.muted, state.theme.icons.dot)} ${active ? state.styler.render(state.theme.roles.focus, choice.label) : state.styler.render(state.theme.roles.content, choice.label)}${choice.help === void 0 ? "" : `  ${state.styler.render(state.theme.roles.description, choice.help)}`}`;
 	});
-	return [promptHeader(state.styler, state.theme, state.message), ...lines].join("\n");
+	return [renderPromptHeader(state.styler, state.theme, state.message), ...lines].join("\n");
 }
 /**
-* Advance a select prompt by one {@link KeyEvent} — the pure `(state, key) → PromptStep<string>`
+* Advances a select prompt by one {@link KeyEvent} — the pure `(state, key) → PromptStep<string>`
 * reducer. `up` / `down` (and `k` / `j`) move the focus, WRAPPING at the ends; return submits the
 * focused choice's `value`; ctrl-c cancels. An empty choice list can never submit (a higher layer
 * guards against it); any other key is ignored.
+*
+* @param state - The select field's current reducer state
+* @param key - The decoded keypress to apply
+* @returns The next step — the state, the rendered view, the status, and the chosen value on submit
 */
-function selectReduce(state, key) {
+function reduceSelect(state, key) {
 	if (key.ctrl && key.name === "c") return {
 		state,
-		view: selectView(state),
+		view: renderSelectView(state),
 		status: "cancel"
 	};
 	const count = state.choices.length;
 	if (count === 0) return {
 		state,
-		view: selectView(state),
+		view: renderSelectView(state),
 		status: "active"
 	};
 	if (key.name === "up" || key.name === "k") {
@@ -842,7 +904,7 @@ function selectReduce(state, key) {
 		};
 		return {
 			state: next,
-			view: selectView(next),
+			view: renderSelectView(next),
 			status: "active"
 		};
 	}
@@ -853,7 +915,7 @@ function selectReduce(state, key) {
 		};
 		return {
 			state: next,
-			view: selectView(next),
+			view: renderSelectView(next),
 			status: "active"
 		};
 	}
@@ -862,19 +924,19 @@ function selectReduce(state, key) {
 		const value = choice?.value ?? "";
 		return {
 			state,
-			view: `${submitHeader(state.styler, state.theme, state.message)} ${state.styler.render(state.theme.roles.hint, choice?.label ?? "")}`,
+			view: `${renderSubmitHeader(state.styler, state.theme, state.message)} ${state.styler.render(state.theme.roles.hint, choice?.label ?? "")}`,
 			status: "submit",
 			value
 		};
 	}
 	return {
 		state,
-		view: selectView(state),
+		view: renderSelectView(state),
 		status: "active"
 	};
 }
 /**
-* Build the initial checkbox-field key state.
+* Builds the initial checkbox-field key state.
 *
 * @param field - The checkbox field to render
 * @param styler - The styler used to render the view
@@ -896,8 +958,13 @@ function createCheckboxState(field, styler = createStyler(), theme) {
 		checked
 	};
 }
-/** Render a checkbox-field key state as a multi-line styled view. */
-function checkboxView(state) {
+/**
+* Renders a checkbox-field key state as a multi-line styled view.
+*
+* @param state - The checkbox field's current reducer state
+* @returns The rendered view — the header, one box per choice, and the selected count
+*/
+function renderCheckboxView(state) {
 	const lines = state.choices.map((choice, index) => {
 		const active = index === state.focused;
 		const ticked = state.checked.includes(index);
@@ -905,21 +972,25 @@ function checkboxView(state) {
 	});
 	const summary = state.styler.render(state.theme.roles.hint, `${state.checked.length} selected`);
 	return [
-		promptHeader(state.styler, state.theme, state.message),
+		renderPromptHeader(state.styler, state.theme, state.message),
 		...lines,
 		summary
 	].join("\n");
 }
 /**
-* Advance a checkbox prompt by one {@link KeyEvent} — the pure
+* Advances a checkbox prompt by one {@link KeyEvent} — the pure
 * `(state, key) → PromptStep<readonly string[]>` reducer. `up` / `down` (and `k` / `j`) move the
 * focus (wrapping); `space` toggles the focused index in the checked set; return submits the
 * checked values in choice order; ctrl-c cancels. The form applies selection-count rules.
+*
+* @param state - The checkbox field's current reducer state
+* @param key - The decoded keypress to apply
+* @returns The next step — the state, the rendered view, the status, and the ticked values on submit
 */
-function checkboxReduce(state, key) {
+function reduceCheckbox(state, key) {
 	if (key.ctrl && key.name === "c") return {
 		state,
-		view: checkboxView(state),
+		view: renderCheckboxView(state),
 		status: "cancel"
 	};
 	const count = state.choices.length;
@@ -930,7 +1001,7 @@ function checkboxReduce(state, key) {
 		};
 		return {
 			state: next,
-			view: checkboxView(next),
+			view: renderCheckboxView(next),
 			status: "active"
 		};
 	}
@@ -941,7 +1012,7 @@ function checkboxReduce(state, key) {
 		};
 		return {
 			state: next,
-			view: checkboxView(next),
+			view: renderCheckboxView(next),
 			status: "active"
 		};
 	}
@@ -953,7 +1024,7 @@ function checkboxReduce(state, key) {
 		};
 		return {
 			state: next,
-			view: checkboxView(next),
+			view: renderCheckboxView(next),
 			status: "active"
 		};
 	}
@@ -963,23 +1034,30 @@ function checkboxReduce(state, key) {
 		const summary = ordered.map((index) => state.choices[index]?.label).filter((name) => name !== void 0).join(", ");
 		return {
 			state,
-			view: `${submitHeader(state.styler, state.theme, state.message)} ${state.styler.render(state.theme.roles.hint, summary)}`,
+			view: `${renderSubmitHeader(state.styler, state.theme, state.message)} ${state.styler.render(state.theme.roles.hint, summary)}`,
 			status: "submit",
 			value: values
 		};
 	}
 	return {
 		state,
-		view: checkboxView(state),
+		view: renderCheckboxView(state),
 		status: "active"
 	};
 }
-/** Toggle `index` in a readonly index list — copy-on-write, returning the new sorted-by-insertion list. */
+/**
+* Toggles `index` in a readonly index list — copy-on-write, returning the new sorted-by-insertion
+* list.
+*
+* @param indices - The ticked indices, in tick order
+* @param index - The index to add when absent, or drop when present
+* @returns A new list carrying the toggled membership; the input is never mutated
+*/
 function toggleIndex(indices, index) {
 	return indices.includes(index) ? indices.filter((i) => i !== index) : [...indices, index];
 }
 /**
-* Build the initial editor-field key state.
+* Builds the initial editor-field key state.
 *
 * @param field - The editor field to render
 * @param styler - The styler used to render the view
@@ -997,23 +1075,30 @@ function createEditorState(field, styler = createStyler(), theme) {
 	};
 }
 /**
-* Render an editor-field key state as a multi-line styled view with its finish hint.
+* Renders an editor-field key state as a multi-line styled view with its finish hint.
+*
+* @param state - The editor field's current reducer state
+* @returns The rendered view — the hinted header, the committed lines, and the line in progress
 */
-function editorView(state) {
-	const head = hintedHeader(state.styler, state.theme, state.message, "(Ctrl+D to finish)");
+function renderEditorView(state) {
+	const head = renderHintedHeader(state.styler, state.theme, state.message, "(Ctrl+D to finish)");
 	const pointer = state.styler.render(state.theme.roles.pointer, state.theme.icons.pointer);
 	return [head, ...[...state.lines.map((line) => state.styler.render(state.theme.roles.content, line)), `${pointer} ${state.styler.render(state.theme.roles.content, state.current)}`]].join("\n");
 }
 /**
-* Advance an editor prompt by one {@link KeyEvent} — the pure `(state, key) → PromptStep<string>`
+* Advances an editor prompt by one {@link KeyEvent} — the pure `(state, key) → PromptStep<string>`
 * reducer. Printable characters extend the current line; backspace shrinks it; return commits the
 * current line and starts a fresh one; ctrl-d FINISHES (joining all lines, falling back to the
 * default when empty); ctrl-c cancels. The form validates the candidate after the driver fills it.
+*
+* @param state - The editor field's current reducer state
+* @param key - The decoded keypress to apply
+* @returns The next step — the state, the rendered view, the status, and the joined text on submit
 */
-function editorReduce(state, key) {
+function reduceEditor(state, key) {
 	if (key.ctrl && key.name === "c") return {
 		state,
-		view: editorView(state),
+		view: renderEditorView(state),
 		status: "cancel"
 	};
 	if (key.ctrl && key.name === "d") {
@@ -1022,7 +1107,7 @@ function editorReduce(state, key) {
 		const answer = joined.length > 0 ? joined : state.default;
 		return {
 			state,
-			view: `${submitHeader(state.styler, state.theme, state.message)} ${state.styler.render(state.theme.roles.hint, `${String(lines.length)} line${lines.length === 1 ? "" : "s"}`)}`,
+			view: `${renderSubmitHeader(state.styler, state.theme, state.message)} ${state.styler.render(state.theme.roles.hint, `${String(lines.length)} line${lines.length === 1 ? "" : "s"}`)}`,
 			status: "submit",
 			value: answer
 		};
@@ -1035,14 +1120,14 @@ function editorReduce(state, key) {
 		};
 		return {
 			state: next,
-			view: editorView(next),
+			view: renderEditorView(next),
 			status: "active"
 		};
 	}
 	const current = editLine(state.current, key);
 	if (current === void 0) return {
 		state,
-		view: editorView(state),
+		view: renderEditorView(state),
 		status: "active"
 	};
 	const next = {
@@ -1051,47 +1136,65 @@ function editorReduce(state, key) {
 	};
 	return {
 		state: next,
-		view: editorView(next),
+		view: renderEditorView(next),
 		status: "active"
 	};
 }
 /**
-* Apply a single line-editing {@link KeyEvent} to a text buffer — the editing shared by input /
+* Applies a single line-editing {@link KeyEvent} to a text buffer — the editing shared by input /
 * password / editor. A printable key appends its character; `backspace` drops the last character;
-* `space` appends a space; ctrl-u clears the line. Returns the new buffer, or `undefined` when the
-* key does not edit the line (so the caller can leave the state untouched).
+* `space` appends a space; ctrl-u clears the line.
+*
+* @param value - The buffer the field holds so far
+* @param key - The decoded keypress to apply
+* @returns The new buffer, or `undefined` when the key does not edit the line, so the caller can
+*   leave the state untouched
 */
 function editLine(value, key) {
 	if (key.ctrl && key.name === "u") return "";
 	if (key.name === "backspace") return value.slice(0, -1);
 	if (key.name === "space") return `${value} `;
-	if (!key.ctrl && !key.meta && [...key.name].length === 1 && isPrintable(key.name)) return `${value}${key.sequence}`;
+	if (!key.ctrl && !key.meta && key.name !== void 0 && [...key.name].length === 1 && isPrintable(key.name)) return `${value}${key.sequence}`;
 }
 /**
-* The default {@link import('./types.js').TimerHandler} — a thin host `setTimeout` / `clearTimeout`
-* wrapper that arms `callback` after `ms` and returns a {@link TimerCancel}. The deadline seam
+* Implements the default {@link import('./types.js').TimerHandler} — a thin host `setTimeout` / `clearTimeout`
+* wrapper that arms `callback` after `ms` and returns a {@link TimerCancelFunction}. The deadline seam
 * behind both the {@link import('./Prompt.js').Prompt} broker (its expiry) and the
 * {@link import('./PromptClient.js').PromptClient} (its reconnect backoff); a test injects a
 * deterministic timer instead, so neither entity touches real time.
+*
+* @param callback - The deadline callback to arm
+* @param ms - How long to wait before firing it, in milliseconds
+* @returns The {@link TimerCancelFunction} that clears the armed deadline
 */
 function defaultTimer(callback, ms) {
 	const handle = setTimeout(callback, ms);
 	return () => clearTimeout(handle);
 }
-/** The default {@link import('./types.js').FetchHandler} — the global `fetch`, adapted to the minimal injected shape the {@link import('./PromptClient.js').PromptClient} uses. */
+/**
+* Implements the default {@link import('./types.js').FetchHandler} — the global `fetch`, adapted to
+* the minimal injected shape the {@link import('./PromptClient.js').PromptClient} uses.
+*
+* @param input - The request URL
+* @param init - The request init the client sets — method, headers, body, and abort signal
+* @returns The host `fetch` promise for that request
+*/
 function globalFetch(input, init) {
 	return fetch(input, init);
 }
 /**
-* Whether a caught value is an `AbortError` — the {@link import('./PromptClient.js').PromptClient}
+* Checks whether a caught value is an `AbortError` — the {@link import('./PromptClient.js').PromptClient}
 * distinguishes a deliberate `disconnect` / teardown (an aborted `fetch`) from a real fault, so it
 * exits its connect loop quietly instead of emitting `error` / reconnecting.
+*
+* @param error - The caught value to test
+* @returns True if the value is a host `Error` or `DOMException` named `AbortError`; false otherwise
 */
 function isAbortError(error) {
 	return (error instanceof DOMException || error instanceof Error) && error.name === "AbortError";
 }
 /**
-* Whether `url` is an INSECURE remote endpoint — a plain `http://` URL whose host is NOT a
+* Checks whether `url` is an INSECURE remote endpoint — a plain `http://` URL whose host is NOT a
 * loopback address. Pure string parsing (no `URL` global), so it stays total on malformed input.
 *
 * @remarks
@@ -1100,7 +1203,7 @@ function isAbortError(error) {
 * An `https://` URL (or any non-`http://` scheme) is never flagged.
 *
 * @param url - The candidate endpoint URL
-* @returns `true` when `url` is a non-loopback `http://` endpoint
+* @returns True if `url` is a non-loopback `http://` endpoint; false otherwise
 *
 * @example
 * ```ts
@@ -1118,7 +1221,12 @@ function isInsecureRemote(url) {
 	const hostname = host.startsWith("[") ? host.slice(0, host.indexOf("]") + 1) : host.split(":")[0] ?? "";
 	return hostname !== "localhost" && hostname !== "127.0.0.1" && hostname !== "[::1]";
 }
-/** Serialize a parked {@link PendingForm} into a {@link WireEvent}. */
+/**
+* Serializes a parked {@link PendingForm} into a {@link WireEvent}.
+*
+* @param form - The parked form's wire-safe record
+* @returns The `pending` frame — the JSON-stringified record as `data`, and the form's own `id`
+*/
 function serializePending(form) {
 	return {
 		event: "pending",
@@ -1126,24 +1234,33 @@ function serializePending(form) {
 		id: form.id
 	};
 }
-/** Serialize a parked prompt's expiry or release into a {@link WireEvent} — event `'expire'`, `data` the JSON-stringified `{ id }` payload. */
+/**
+* Serializes a parked prompt's expiry or release into a {@link WireEvent}.
+*
+* @param id - The id of the parked form that expired or was released
+* @returns The `expire` frame, carrying the JSON-stringified `{ id }` payload as `data`
+*/
 function serializeExpire(id) {
 	return {
 		event: "expire",
 		data: JSON.stringify({ id })
 	};
 }
-/** The {@link WireEvent} a broker/manager sends when it is going away — event `'shutdown'`, no payload. */
-function serializeShutdown() {
+/**
+* Serializes the {@link WireEvent} a broker or manager sends when it is going away.
+*
+* @returns The `destroy` frame, whose `data` is empty because the signal carries no payload
+*/
+function serializeDestroy() {
 	return {
-		event: "shutdown",
+		event: "destroy",
 		data: ""
 	};
 }
 //#endregion
 //#region src/core/Prompt.ts
 /**
-* The headless form broker. It parks live forms, exposes their serialized schemas, and applies
+* Implements the headless form broker. It parks live forms, exposes their serialized schemas, and applies
 * remote answers to the authoritative form.
 *
 * @remarks
@@ -1334,7 +1451,7 @@ var Prompt = class {
 //#endregion
 //#region src/core/PromptClient.ts
 /**
-* The SSE form bridge. It ingests serialized forms from a remote broker, renders them through a
+* Implements the SSE form bridge. It ingests serialized forms from a remote broker, renders them through a
 * local terminal, and posts answers back without blocking the event stream.
 *
 * @remarks
@@ -1343,12 +1460,12 @@ var Prompt = class {
 *   {@link disconnect} deliberately stopped it.
 * - **Ingest + render.** Each `pending` envelope passes through `isPendingForm`, Form's `parseForm`,
 *   and terminal's `sanitizeSchema`, then enters a serial render queue. The SSE reader never awaits
-*   that queue, so `expire` and `shutdown` remain live while a person is answering.
+*   that queue, so `expire` and `destroy` remain live while a person is answering.
 * - **Safe local form.** The rendering copy omits every wire `pattern`, because Form compiles a
 *   pattern during local evaluation. The broker's parked form retains it and remains authoritative.
 * - **Refusal retry.** A structured `rejected` response seeds a new rendering form with the values
 *   just submitted, applies every {@link FieldError} through `invalidate`, and asks again. No retry
-*   counter truncates the loop; acceptance, expiry, and shutdown are its bounds.
+*   counter truncates the loop; acceptance, expiry, and the broker's own teardown are its bounds.
 * - **Replay safety.** A replayed id is skipped while it is queued, rendering, or posting. Once an
 *   attempt ends, a later delivery of that id may be rendered again.
 *
@@ -1486,7 +1603,7 @@ var PromptClient = class {
 			if (isRecord(parsed) && isString(parsed.id)) this.#expire(parsed.id);
 			return;
 		}
-		if (event.event === SSE_EVENTS.shutdown) {
+		if (event.event === SSE_EVENTS.destroy) {
 			this.disconnect();
 			this.#interrupt();
 		}
@@ -1639,10 +1756,9 @@ var PromptClient = class {
 //#endregion
 //#region src/core/TerminalManager.ts
 /**
-* The multi-endpoint terminal MANAGER — a registry of named {@link PromptInterface} brokers (one
-* per endpoint), so several parties can `ask` forms of each other by NAME with a `from` → `to`
-* attribution edge on every parked form, and a transitive DEADLOCK check across all in-flight
-* asks.
+* Registers named {@link PromptInterface} brokers (one per endpoint), so several parties can
+* `ask` forms of each other by NAME with a `from` → `to` attribution edge on every parked form,
+* and a transitive DEADLOCK check across all in-flight asks.
 *
 * @remarks
 * - **Registry.** `add(name, options?)` mints (or, if `name` is already mounted, returns the
@@ -1657,7 +1773,7 @@ var PromptClient = class {
 * - **Durable open / save.** `open(name)` restores an EMPTY broker from the `store` (parked
 *   Promises are process-bound and never resurrected); `save(name)` persists the endpoint's
 *   configured `timeout`.
-* - **Removal.** `remove` drops one endpoint, a batch (§9.2, array overload FIRST), or every
+* - **Removal.** `remove` drops one endpoint, a batch (the array overload declared FIRST), or every
 *   endpoint when called without an argument. It destroys each broker, which expires every form
 *   still parked on it. `destroy` is idempotent.
 *
@@ -1702,7 +1818,7 @@ var TerminalManager = class {
 		return this.#terminals.get(name);
 	}
 	terminals() {
-		return [...this.#terminals.keys()];
+		return [...this.#terminals.values()];
 	}
 	add(name, options) {
 		if (this.#destroyed) throw new TerminalError("DESTROYED", "manager destroyed");
@@ -1734,7 +1850,7 @@ var TerminalManager = class {
 	ask(from, to, form) {
 		const broker = this.#terminals.get(to);
 		if (broker === void 0) {
-			const known = this.terminals();
+			const known = [...this.#terminals.keys()];
 			return Promise.reject(new TerminalError("TARGET", `unknown terminal '${to}' (known: ${known.length > 0 ? known.join(", ") : "none"})`, {
 				to,
 				known
@@ -1772,7 +1888,7 @@ var TerminalManager = class {
 		const broker = this.#terminals.get(to);
 		if (broker === void 0) return {
 			success: false,
-			error: { reason: "terminal" }
+			error: { reason: "target" }
 		};
 		const result = broker.answer(id, values);
 		if (result.success) this.#edges.delete(id);
@@ -1805,8 +1921,8 @@ var TerminalManager = class {
 			return;
 		}
 		if (isArray(names)) {
-			let removed = false;
-			for (const name of names) if (this.#removeOne(name)) removed = true;
+			let removed = true;
+			for (const name of names) if (!this.#removeOne(name)) removed = false;
 			return removed;
 		}
 		return this.#removeOne(names);
@@ -1881,16 +1997,16 @@ var TerminalManager = class {
 	}
 };
 //#endregion
-//#region src/core/MemoryTerminalStore.ts
+//#region src/core/stores/MemoryTerminalStore.ts
 /**
-* The in-memory {@link TerminalStoreInterface} — a process-lifetime `Map` of
+* Implements the in-memory {@link TerminalStoreInterface} — a process-lifetime `Map` of
 * {@link TerminalSnapshot}s keyed by endpoint id, the DEFAULT store
-* {@link import('./factories.js').createMemoryTerminalStore} builds. The EXACT twin of
+* {@link import('../factories.js').createMemoryTerminalStore} builds. The EXACT twin of
 * {@link import('./DatabaseTerminalStore.js').DatabaseTerminalStore}.
 *
 * @remarks
-* A plain `Map<string, TerminalSnapshot>` (AGENTS §21 — the snapshot is already pure, self-contained
-* CONFIG-only JSON, so no encoding is needed for the memory tier). There is NO idle-TTL and NO
+* A plain `Map<string, TerminalSnapshot>` — the snapshot is already pure, self-contained CONFIG-only
+* JSON, so the memory tier needs no encoding. There is NO idle-TTL and NO
 * eviction: a persisted config lives until an explicit `delete`. A durable backend (JSON / SQLite /
 * IndexedDB) swaps in through the SAME interface without touching the manager — its
 * driver-pluggable twin is {@link import('./DatabaseTerminalStore.js').DatabaseTerminalStore} (the
@@ -1900,13 +2016,13 @@ var TerminalManager = class {
 * - **`set` inserts / replaces under the snapshot's OWN `id`** (no separate id param).
 * - **`delete` drops a snapshot by id**; an absent id is a no-op (no throw).
 *
-* The public surface is EXACTLY `get` / `set` / `delete` — no extra members (the §22 method
-* bijection with {@link TerminalStoreInterface}). Hydration is a caller concern: `open` always
+* The public surface is EXACTLY `get` / `set` / `delete` — no extra members, so the class and
+* {@link TerminalStoreInterface} carry the same methods. Hydration is a caller concern: `open` always
 * restores an EMPTY broker — parked Promises are process-bound and never resurrected.
 *
 * @example
 * ```ts
-* import { createMemoryTerminalStore } from '@src/core'
+* import { createMemoryTerminalStore } from '@orkestrel/terminal'
 *
 * const store = createMemoryTerminalStore()
 * await store.set({ id: 'shell', timeout: 5000 })   // persist a config
@@ -1916,22 +2032,40 @@ var TerminalManager = class {
 */
 var MemoryTerminalStore = class {
 	#snapshots = /* @__PURE__ */ new Map();
+	/**
+	* Resolves the persisted snapshot for `id`.
+	*
+	* @param id - The endpoint name the snapshot is keyed by
+	* @returns The stored snapshot, or `undefined` when none is held
+	*/
 	get(id) {
 		return Promise.resolve(this.#snapshots.get(id));
 	}
+	/**
+	* Inserts or replaces under the snapshot's OWN `id` (no separate id param).
+	*
+	* @param snapshot - The config snapshot to persist, carrying its own `id`
+	* @returns A promise that settles once the snapshot is held
+	*/
 	set(snapshot) {
 		this.#snapshots.set(snapshot.id, snapshot);
 		return Promise.resolve();
 	}
+	/**
+	* Drops a snapshot by id; an absent id is a no-op (no throw).
+	*
+	* @param id - The endpoint name to drop
+	* @returns A promise that settles once the snapshot is gone
+	*/
 	delete(id) {
 		this.#snapshots.delete(id);
 		return Promise.resolve();
 	}
 };
 //#endregion
-//#region src/core/DatabaseTerminalStore.ts
+//#region src/core/stores/DatabaseTerminalStore.ts
 /**
-* A {@link TerminalStoreInterface} backed by one table of the `databases` layer — an endpoint's
+* Implements a {@link TerminalStoreInterface} backed by one table of the `databases` layer — an endpoint's
 * durable CONFIG state IS a row, so persistence reduces to keyed point-access (`get` / `set` /
 * `delete`) over a {@link TableInterface}, the driver-pluggable twin of the plain-`Map`
 * {@link import('./MemoryTerminalStore.js').MemoryTerminalStore}.
@@ -1941,7 +2075,7 @@ var MemoryTerminalStore = class {
 * JSON, SQLite, IndexedDB) is chosen by whoever builds it (the factories), so a JSON / SQLite /
 * IndexedDB backend swaps in WITHOUT touching the manager — the same seam as
 * {@link import('./MemoryTerminalStore.js').MemoryTerminalStore}. The driver defaults to memory
-* ({@link import('./factories.js').createDatabaseTerminalStore} passes `createMemoryDriver()`), so
+* ({@link import('../factories.js').createDatabaseTerminalStore} passes `createMemoryDriver()`), so
 * it ALSO works in memory out of the box; you opt into the durable plumbing by passing a JSON /
 * SQLite / IndexedDB driver.
 *
@@ -1953,18 +2087,19 @@ var MemoryTerminalStore = class {
 * - **`set(snapshot)` upserts under the snapshot's OWN `id`** (no separate id param) — it writes
 *   the row `{ id: snapshot.id, snapshot }`.
 * - **`get(id)` resolves the stored snapshot for an id**, narrowing the opaque JSON column back to
-*   a {@link TerminalSnapshot} ({@link import('./validators.js').isTerminalSnapshot} — the AGENTS §14
-*   boundary narrow for an untrusted storage read), or `undefined` if none is stored.
+*   a {@link TerminalSnapshot} ({@link import('../validators.js').isTerminalSnapshot} — the total
+*   guard that narrows an untrusted storage read), or `undefined` if none is stored.
 * - **`delete(id)` drops a snapshot by id**; an absent id is a no-op (no throw).
 *
 * There is NO idle-TTL / eviction — a persisted config lives until an explicit `delete`. The public
-* surface is EXACTLY `get` / `set` / `delete` — no extra members (the §22 method bijection with
-* {@link TerminalStoreInterface}). Hydration stays a caller concern: `open` always restores an EMPTY
+* surface is EXACTLY `get` / `set` / `delete` — no extra members, so the class and
+* {@link TerminalStoreInterface} carry the same methods. Hydration stays a caller concern: `open` always restores an EMPTY
 * broker — parked Promises are process-bound and never resurrected.
 *
 * @example
 * ```ts
-* import { createDatabaseTerminalStore, createMemoryDriver } from '@src/core'
+* import { createDatabaseTerminalStore } from '@orkestrel/terminal'
+* import { createMemoryDriver } from '@orkestrel/database'
 *
 * const store = createDatabaseTerminalStore(createMemoryDriver()) // a durable driver swaps in here
 * await store.set({ id: 'shell', timeout: 5000 })        // persist the config (one JSON column)
@@ -1975,7 +2110,7 @@ var MemoryTerminalStore = class {
 var DatabaseTerminalStore = class {
 	#table;
 	/**
-	* Wrap a table as a terminal store.
+	* Wraps a table as a terminal store.
 	*
 	* @param table - The {@link TableInterface} holding the snapshots — its row is the
 	*   {@link TerminalSnapshotRow} `{ id; snapshot }` shape (the snapshot one opaque JSON column)
@@ -1983,20 +2118,37 @@ var DatabaseTerminalStore = class {
 	constructor(table) {
 		this.#table = table;
 	}
-	/** Resolve the persisted snapshot for `id`, narrowing the opaque JSON column back to a `TerminalSnapshot`. */
+	/**
+	* Resolves the persisted snapshot for `id`, narrowing the opaque JSON column back to a
+	* `TerminalSnapshot`.
+	*
+	* @param id - The endpoint name the row is keyed by
+	* @returns The stored snapshot, or `undefined` when none is held or the column is off-shape
+	*/
 	async get(id) {
 		const row = await this.#table.get(id);
 		if (row === void 0) return void 0;
 		return isTerminalSnapshot(row.snapshot) ? row.snapshot : void 0;
 	}
-	/** Insert or replace under the snapshot's OWN `id` (no separate id param) — the row is `{ id, snapshot }`. */
+	/**
+	* Inserts or replaces under the snapshot's OWN `id` (no separate id param) — the row is
+	* `{ id, snapshot }`.
+	*
+	* @param snapshot - The config snapshot to persist, carrying its own `id`
+	* @returns A promise that settles once the row is written
+	*/
 	async set(snapshot) {
 		await this.#table.set({
 			id: snapshot.id,
 			snapshot
 		});
 	}
-	/** Drop a snapshot by id; an absent id is a no-op (no throw). */
+	/**
+	* Drops a snapshot by id; an absent id is a no-op (no throw).
+	*
+	* @param id - The endpoint name to drop
+	* @returns A promise that settles once the row is gone
+	*/
 	async delete(id) {
 		await this.#table.remove(id);
 	}
@@ -2004,7 +2156,7 @@ var DatabaseTerminalStore = class {
 //#endregion
 //#region src/core/factories.ts
 /**
-* Create the headless {@link PromptInterface} broker. It parks live forms and applies remote
+* Creates the headless {@link PromptInterface} broker. It parks live forms and applies remote
 * answers to the authoritative instances.
 *
 * @param options - See {@link PromptOptions}
@@ -2017,7 +2169,7 @@ var DatabaseTerminalStore = class {
 *
 * @example
 * ```ts
-* import { createPrompt } from '@src/core'
+* import { createPrompt } from '@orkestrel/terminal'
 * import { createForm } from '@orkestrel/form'
 *
 * const prompt = createPrompt()
@@ -2030,7 +2182,7 @@ function createPrompt(options) {
 	return new Prompt(options);
 }
 /**
-* Create the SSE prompt {@link PromptClientInterface} BRIDGE — it connects to a remote broker's SSE
+* Creates the SSE prompt {@link PromptClientInterface} BRIDGE — it connects to a remote broker's SSE
 * endpoint, dispatches each received form to a local {@link import('./types.js').TerminalInterface},
 * and POSTs the answer back. Universal — `fetch` / SSE are web-standard.
 *
@@ -2042,11 +2194,11 @@ function createPrompt(options) {
 *   ends; it reconnects with the `delay` backoff unless `reconnect` is `false` / the client was
 *   `destroy`ed. Inject `options.fetch` (a scripted `fetch`) and `options.timer` to drive it
 *   deterministically in tests — no real network.
-* - **§14 wire narrowing.** Every decoded prompt is guard-narrowed before dispatch (never an `as`).
+* - **Wire narrowing.** Every decoded prompt is guard-narrowed before dispatch (never an `as`).
 *
 * @example
 * ```ts
-* import { createPromptClient } from '@src/core'
+* import { createPromptClient } from '@orkestrel/terminal'
 *
 * const client = createPromptClient({ url: 'http://host/prompts', terminal })
 * await client.connect()
@@ -2056,7 +2208,7 @@ function createPromptClient(options) {
 	return new PromptClient(options);
 }
 /**
-* Create the multi-endpoint {@link TerminalManager} — a named registry of
+* Creates the multi-endpoint {@link TerminalManager} — a named registry of
 * {@link PromptInterface} brokers so several parties can `ask` prompts of each other by name,
 * with a transitive DEADLOCK check across every in-flight ask.
 *
@@ -2065,7 +2217,7 @@ function createPromptClient(options) {
 *
 * @example
 * ```ts
-* import { createTerminalManager } from '@src/core'
+* import { createTerminalManager } from '@orkestrel/terminal'
 *
 * const manager = createTerminalManager()
 * manager.add('agent')
@@ -2075,14 +2227,14 @@ function createTerminalManager(options) {
 	return new TerminalManager(options);
 }
 /**
-* Create the in-memory {@link TerminalStoreInterface} — a process-lifetime `Map` of endpoint
+* Creates the in-memory {@link TerminalStoreInterface} — a process-lifetime `Map` of endpoint
 * config snapshots, the default store backing a {@link TerminalManagerInterface}'s `open` / `save`.
 *
 * @returns A {@link TerminalStoreInterface}
 *
 * @example
 * ```ts
-* import { createMemoryTerminalStore } from '@src/core'
+* import { createMemoryTerminalStore } from '@orkestrel/terminal'
 *
 * const store = createMemoryTerminalStore()
 * ```
@@ -2091,7 +2243,7 @@ function createMemoryTerminalStore() {
 	return new MemoryTerminalStore();
 }
 /**
-* Create a {@link TerminalStoreInterface} backed by one table of the `databases` layer — the
+* Creates a {@link TerminalStoreInterface} backed by one table of the `databases` layer — the
 * driver-pluggable twin of {@link createMemoryTerminalStore}, storing each endpoint's config
 * snapshot as one opaque JSON column.
 *
@@ -2100,7 +2252,7 @@ function createMemoryTerminalStore() {
 *
 * @example
 * ```ts
-* import { createDatabaseTerminalStore } from '@src/core'
+* import { createDatabaseTerminalStore } from '@orkestrel/terminal'
 *
 * const store = createDatabaseTerminalStore() // in-memory by default
 * ```
@@ -2116,6 +2268,6 @@ function createDatabaseTerminalStore(driver = createMemoryDriver()) {
 	}).table("terminals"));
 }
 //#endregion
-export { ACCEPT_EVENT_STREAM, BACKSPACE, CONTROL_NAMES, CTRL_A, CTRL_C, CTRL_D, CTRL_E, CTRL_U, DEFAULT_MASK, DEFAULT_PROMPT_THEME, DEFAULT_PROMPT_TIMEOUT_MS, DEFAULT_RECONNECT_DELAY_MS, DELETE, DatabaseTerminalStore, ESCAPE, HEADER_TOKEN, KEY_CSI, KEY_SS3, MemoryTerminalStore, NEWLINE, PROMPT_ICONS, PROMPT_ROLES, Prompt, PromptClient, RETURN, SEQUENCE_NAMES, SPACE, SSE_BUFFER_LIMIT, SSE_EVENTS, TAB, TerminalError, TerminalManager, checkboxReduce, checkboxView, confirmReduce, confirmView, createCheckboxState, createConfirmState, createDatabaseTerminalStore, createEditorState, createInputState, createMemoryTerminalStore, createPasswordState, createPrompt, createPromptClient, createPromptTheme, createSelectState, createTerminalManager, defaultTimer, editLine, editorReduce, editorView, errorLine, globalFetch, hintedHeader, inputReduce, inputView, isAbortError, isInsecureRemote, isPendingForm, isPendingFormStatus, isPrintable, isTerminalError, isTerminalSnapshot, isWireEvent, parseKey, passwordReduce, passwordView, promptHeader, sanitizeDisplayText, sanitizeSchema, sanitizeThemeIcons, selectReduce, selectView, serializeExpire, serializePending, serializeShutdown, submitHeader, toggleIndex };
+export { ACCEPT_EVENT_STREAM, BACKSPACE, CONTROL_NAMES, CTRL_A, CTRL_C, CTRL_D, CTRL_E, CTRL_U, DEFAULT_MASK, DEFAULT_PROMPT_THEME, DEFAULT_PROMPT_TIMEOUT_MS, DEFAULT_RECONNECT_DELAY_MS, DELETE, DatabaseTerminalStore, HEADER_TOKEN, KEY_SS3, MemoryTerminalStore, NEWLINE, PROMPT_ICONS, PROMPT_ROLES, Prompt, PromptClient, RETURN, SEQUENCE_NAMES, SPACE, SSE_BUFFER_LIMIT, SSE_EVENTS, TAB, TerminalError, TerminalManager, createCheckboxState, createConfirmState, createDatabaseTerminalStore, createEditorState, createInputState, createMemoryTerminalStore, createPasswordState, createPrompt, createPromptClient, createPromptTheme, createSelectState, createTerminalManager, defaultTimer, editLine, globalFetch, isAbortError, isInsecureRemote, isPendingForm, isPendingFormStatus, isPrintable, isTerminalError, isTerminalSnapshot, isWireEvent, parseKey, reduceCheckbox, reduceConfirm, reduceEditor, reduceInput, reducePassword, reduceSelect, renderCheckboxView, renderConfirmView, renderEditorView, renderErrorLine, renderHintedHeader, renderInputView, renderPasswordView, renderPromptHeader, renderSelectView, renderSubmitHeader, sanitizeDisplayText, sanitizeSchema, sanitizeThemeIcons, serializeDestroy, serializeExpire, serializePending, toggleIndex };
 
 //# sourceMappingURL=index.js.map