@orkestrel/terminal 0.0.1

package/dist/src/core/index.js

@@ -0,0 +1,1651 @@
+import { isArray, isBoolean, isNonEmptyString, isNumber, isRecord, isString, literalOf, recordOf } from "@orkestrel/contract";
+import { STATUS_ICONS, createStyler, stripControls } from "@orkestrel/console";
+import { Emitter } from "@orkestrel/emitter";
+import { createSSEParser } from "@orkestrel/sse";
+//#region src/core/constants.ts
+/** Carriage return (`\r`, U+000D) — Enter on most terminals. */
+var RETURN = String.fromCharCode(13);
+/** Line feed (`\n`, U+000A) — Enter on some terminals / pasted input. */
+var NEWLINE = String.fromCharCode(10);
+/** Tab (`\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. */
+var BACKSPACE = String.fromCharCode(8);
+/** Delete (DEL, U+007F) — the usual Backspace byte on a Unix TTY. */
+var DELETE = String.fromCharCode(127);
+/** Space (U+0020). */
+var SPACE = " ";
+/** Ctrl+C (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). */
+var CTRL_D = String.fromCharCode(4);
+/** Ctrl+U (NAK, U+0015) — clear the current line. */
+var CTRL_U = String.fromCharCode(21);
+/** Ctrl+A (SOH, U+0001) — move to start of line. */
+var CTRL_A = String.fromCharCode(1);
+/** Ctrl+E (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`).
+*/
+var KEY_CSI = `[`;
+/** The Single Shift Three lead (`ESCO`) — the alternate arrow-key prefix some terminals emit (`ESC O A`). */
+var KEY_SS3 = `O`;
+/**
+* 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
+* their numeric-tilde variants). The source of truth for the multi-byte key decode; frozen.
+*
+* @remarks
+* Terminals disagree on these: a cursor key is `ESC[A` (normal) or `ESCOA` (application mode),
+* and Home / End / Delete each have a letter form (`ESC[H` / `ESC[F`) and a numeric form
+* (`ESC[1~` / `ESC[4~` / `ESC[3~`). Every accepted spelling maps to one name so a reducer never
+* 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",
+	[`${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"
+});
+/**
+* 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.
+*
+* @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.
+*/
+var CONTROL_NAMES = Object.freeze({
+	["\r"]: Object.freeze({
+		name: "return",
+		ctrl: false
+	}),
+	["\n"]: Object.freeze({
+		name: "return",
+		ctrl: false
+	}),
+	["	"]: Object.freeze({
+		name: "tab",
+		ctrl: false
+	}),
+	["\x1B"]: Object.freeze({
+		name: "escape",
+		ctrl: false
+	}),
+	["\b"]: Object.freeze({
+		name: "backspace",
+		ctrl: false
+	}),
+	[""]: Object.freeze({
+		name: "backspace",
+		ctrl: false
+	}),
+	[" "]: Object.freeze({
+		name: "space",
+		ctrl: false
+	}),
+	[""]: Object.freeze({
+		name: "c",
+		ctrl: true
+	}),
+	[""]: Object.freeze({
+		name: "d",
+		ctrl: true
+	}),
+	[""]: Object.freeze({
+		name: "u",
+		ctrl: true
+	}),
+	["
"]: Object.freeze({
+		name: "a",
+		ctrl: true
+	}),
+	[""]: Object.freeze({
+		name: "e",
+		ctrl: true
+	})
+});
+/** The default mask glyph a {@link import('./types.js').PasswordState} renders each input character as — `*`. */
+var DEFAULT_MASK = "*";
+/** Matches an email address — a non-trivial `local@domain.tld` shape. The `email` rule tests against this. */
+var EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+/** Matches an HTTP(S) URL. The `url` rule tests against this. */
+var URL_PATTERN = /^https?:\/\/.+/;
+/** Matches a numeric value (integer or decimal, optional sign). The `numeric` rule tests against this. */
+var NUMERIC_PATTERN = /^-?\d+(\.\d+)?$/;
+/** Matches an integer (optional sign). The `integer` rule tests against this. */
+var INTEGER_PATTERN = /^-?\d+$/;
+/** Matches an alphanumeric string (letters and digits only). The `alphanumeric` rule tests against this. */
+var ALPHANUMERIC_PATTERN = /^[a-zA-Z0-9]+$/;
+/**
+* Each built-in validation rule's default error message — what the composed {@link
+* import('./types.js').Validator} returns when that rule fails (the `minimum` / `maximum`
+* messages are interpolated with the configured length at build time). Frozen; the source of
+* truth for the rule-failure copy.
+*/
+var RULE_MESSAGES = Object.freeze({
+	required: "This field is required",
+	minimum: "Must be at least {count} characters",
+	maximum: "Must be at most {count} characters",
+	pattern: "Must match pattern: {pattern}",
+	email: "Must be a valid email address",
+	url: "Must be a valid URL",
+	numeric: "Must be a numeric value",
+	integer: "Must be an integer",
+	alphanumeric: "Must contain only letters and digits",
+	invalid: "Invalid input"
+});
+/**
+* The prompt-view icon glyphs the reducers render the prompt line and choice rows with. PLAIN
+* glyphs — color is applied by the {@link import('./types.js').PromptState}'s
+* {@link import('@orkestrel/console').StylerInterface} at render time, never baked into the
+* constant (AGENTS — styling orthogonal to data; the rework fixes the terminal's ANSI-in-the-icon).
+* Frozen.
+*
+* @remarks
+* - `question` — the leading mark on a prompt's message line.
+* - `pointer` — the cursor before the input / the focused choice row.
+* - `dot` / `selected` — an unfocused / focused row marker in a select list.
+* - `checked` / `unchecked` — a checked / unchecked box in a checkbox list.
+*/
+var PROMPT_ICONS = Object.freeze({
+	question: "?",
+	pointer: "›",
+	dot: "○",
+	selected: "●",
+	checked: "☑",
+	unchecked: "☐"
+});
+/** 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. */
+var DEFAULT_RECONNECT_DELAY_MS = 2e3;
+/**
+* The SSE `event:` names the broker emits and the {@link import('./types.js').PromptClient}
+* dispatches on. Frozen; the source of truth for the wire event vocabulary.
+*
+* @remarks
+* - `pending` — a serialized {@link import('./types.js').PendingPrompt} to dispatch + answer.
+* - `expire` — an `{ id }` payload: the broker expired a parked prompt (the client drops it).
+* - `shutdown` — 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"
+});
+/** The auth-token request header the {@link import('./types.js').PromptClient} sends when a `token` is configured. */
+var HEADER_TOKEN = "x-orkestrel-token";
+/** 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').PromptClient} 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).
+*/
+var SSE_BUFFER_LIMIT = 1048576;
+//#endregion
+//#region src/core/errors.ts
+/**
+* An error a {@link import('./Prompt.js').Prompt} broker rejects a parked prompt's Promise with.
+*
+* @remarks
+* Carries a {@link TerminalErrorCode} and an optional `context` bag (the prompt `id`). Thrown —
+* as a Promise rejection on the awaited prompt call — when a parked prompt is not answered before
+* its `timeout`, or when the broker is `destroy`ed while the prompt is still `pending` (both
+* `EXPIRE`); or when the user aborts an interactive server-`Terminal` prompt with ctrl-c
+* (`CANCEL`). Narrow a caught value with {@link isTerminalError} and branch on `error.code`.
+*/
+var TerminalError = class extends Error {
+	/** The machine-readable condition — see {@link TerminalErrorCode}. */
+	code;
+	/** An optional context bag naming the offending prompt id. */
+	context;
+	constructor(code, message, context) {
+		super(message);
+		this.name = "TerminalError";
+		this.code = code;
+		this.context = context;
+	}
+};
+/**
+* Narrow 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}
+*
+* @example
+* ```ts
+* try {
+* 	const name = await prompt.input({ message: 'Your name' })
+* } catch (error) {
+* 	if (isTerminalError(error) && error.code === 'EXPIRE') retryLater()
+* }
+* ```
+*/
+function isTerminalError(value) {
+	return value instanceof TerminalError;
+}
+//#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`
+* 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 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.
+*
+* @param input - The raw keypress bytes, as a string or `Uint8Array`
+* @returns The decoded {@link KeyEvent}
+*
+* @example
+* ```ts
+* parseKey('\r')        // { name: 'return', sequence: '\r', 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 }
+* ```
+*/
+function parseKey(input) {
+	const sequence = isString(input) ? input : new TextDecoder().decode(input);
+	const sequenceName = SEQUENCE_NAMES[sequence];
+	if (sequenceName !== void 0) return {
+		name: sequenceName,
+		sequence,
+		ctrl: false,
+		meta: true,
+		shift: false
+	};
+	const control = CONTROL_NAMES[sequence];
+	if (control !== void 0) return {
+		name: control.name,
+		sequence,
+		ctrl: control.ctrl,
+		meta: false,
+		shift: false
+	};
+	const first = [...sequence][0];
+	if (first !== void 0 && isPrintable(first)) return {
+		name: first,
+		sequence,
+		ctrl: false,
+		meta: false,
+		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. */
+function isPrintable(character) {
+	if (character.length === 0) return false;
+	const code = character.codePointAt(0);
+	if (code === void 0) return false;
+	return code >= 32 && code !== 127;
+}
+/**
+* Evaluate ONE built-in validation rule against `input`, returning its error message when the
+* rule fails or `undefined` when it passes. The atomic check {@link buildRuleValidator} wraps
+* into a {@link Validator}. Pure.
+*
+* @remarks
+* A function `check` is the custom-override path: it is called and its `true` ⇒ pass, a string
+* ⇒ that message, anything else ⇒ the generic {@link RULE_MESSAGES.invalid}. A primitive `check`
+* runs the named built-in: `required` (non-empty trimmed), `minimum` / `maximum` (length
+* bounds, the message interpolated with the count), `pattern` (a regex source), and the
+* `email` / `url` / `numeric` / `integer` / `alphanumeric` pattern tests.
+*
+* @param rule - The rule name (`'required'`, `'minimum'`, …)
+* @param check - The configured value (a primitive toggle / bound / pattern, or a custom {@link Validator})
+* @param input - The input string to test
+* @returns The error message when the rule fails, else `undefined`
+*/
+function evaluateRule(rule, check, input) {
+	if (typeof check === "function") {
+		const result = check(input);
+		if (result === true) return void 0;
+		return isString(result) ? result : RULE_MESSAGES.invalid;
+	}
+	switch (rule) {
+		case "required":
+			if (check === true && input.trim().length === 0) return RULE_MESSAGES.required;
+			break;
+		case "minimum":
+			if (isNumber(check) && [...input].length < check) return RULE_MESSAGES.minimum.replace("{count}", String(check));
+			break;
+		case "maximum":
+			if (isNumber(check) && [...input].length > check) return RULE_MESSAGES.maximum.replace("{count}", String(check));
+			break;
+		case "pattern":
+			if (isString(check)) {
+				let compiled;
+				try {
+					compiled = new RegExp(check);
+				} catch {
+					return RULE_MESSAGES.pattern.replace("{pattern}", check);
+				}
+				if (!compiled.test(input)) return RULE_MESSAGES.pattern.replace("{pattern}", check);
+			}
+			break;
+		case "email":
+			if (check === true && !EMAIL_PATTERN.test(input)) return RULE_MESSAGES.email;
+			break;
+		case "url":
+			if (check === true && !URL_PATTERN.test(input)) return RULE_MESSAGES.url;
+			break;
+		case "numeric":
+			if (check === true && !NUMERIC_PATTERN.test(input)) return RULE_MESSAGES.numeric;
+			break;
+		case "integer":
+			if (check === true && !INTEGER_PATTERN.test(input)) return RULE_MESSAGES.integer;
+			break;
+		case "alphanumeric":
+			if (check === true && !ALPHANUMERIC_PATTERN.test(input)) return RULE_MESSAGES.alphanumeric;
+			break;
+	}
+}
+/** Wrap a named rule + its primitive check into a {@link Validator} (returns `true` or the rule's message). */
+function buildRuleValidator(rule, check) {
+	return (input) => evaluateRule(rule, check, input) ?? true;
+}
+/**
+* Append a rule-backed {@link Validator} to `validators` when the rule is enabled — a `false` /
+* `undefined` `check` is skipped, a function `check` is added verbatim (the custom override), and
+* a primitive `check` is wrapped via {@link buildRuleValidator}. Mutates `validators` in place.
+*/
+function appendRule(validators, rule, check) {
+	if (check === void 0 || check === false) return;
+	if (typeof check === "function") {
+		validators.push(check);
+		return;
+	}
+	validators.push(buildRuleValidator(rule, check));
+}
+/**
+* Compose several {@link Validator}s into ONE short-circuiting validator — it runs them in order
+* and returns the FIRST error message, or `true` when all pass. The empty composition always
+* passes.
+*/
+function composeValidators(...validators) {
+	return (input) => {
+		for (const validator of validators) {
+			const result = validator(input);
+			if (result !== true) return result;
+		}
+		return true;
+	};
+}
+/**
+* Compile a {@link Validator} or declarative {@link ValidationRules} (or nothing) into ONE
+* composed {@link Validator}. A bare validator passes through; rules are appended in the fixed
+* order (required → minimum → maximum → pattern → email → url → numeric → integer → alphanumeric
+* → custom) and composed; absent / empty input yields an always-passing validator. Pure.
+*
+* @remarks
+* Unlike a prior variant (which returned `Validator | undefined`), this ALWAYS returns a
+* `Validator` — an absent or empty rule set yields a validator that returns `true` for every
+* input. That keeps a prompt's state unconditional (it always holds a real validator to apply on
+* submit), with no `undefined` branch at the call site.
+*
+* @param validate - A custom {@link Validator}, a {@link ValidationRules} bag, or `undefined`
+* @returns The composed {@link Validator} (always-passing when nothing was supplied)
+*
+* @example
+* ```ts
+* const v = resolveValidation({ required: true, minimum: 3 })
+* v('')    // 'This field is required'
+* v('ab')  // 'Must be at least 3 characters'
+* v('abc') // true
+* ```
+*/
+function resolveValidation(validate) {
+	if (validate === void 0) return passing;
+	if (typeof validate === "function") return validate;
+	const validators = [];
+	appendRule(validators, "required", validate.required);
+	appendRule(validators, "minimum", validate.minimum);
+	appendRule(validators, "maximum", validate.maximum);
+	appendRule(validators, "pattern", validate.pattern);
+	appendRule(validators, "email", validate.email);
+	appendRule(validators, "url", validate.url);
+	appendRule(validators, "numeric", validate.numeric);
+	appendRule(validators, "integer", validate.integer);
+	appendRule(validators, "alphanumeric", validate.alphanumeric);
+	if (typeof validate.custom === "function") validators.push(validate.custom);
+	if (validators.length === 0) return passing;
+	return composeValidators(...validators);
+}
+/** The always-passing {@link Validator} — the resolved validator when no rules were supplied. */
+function passing(_input) {
+	return true;
+}
+/** Normalize a select choice input into a full {@link PromptChoice} (a bare string becomes both name and value). */
+function normalizeChoice(choice) {
+	return isString(choice) ? {
+		name: choice,
+		value: choice
+	} : choice;
+}
+/** Normalize a checkbox choice input into a full {@link CheckboxChoice} (a bare string becomes both name and value). */
+function normalizeCheckboxChoice(choice) {
+	return isString(choice) ? {
+		name: choice,
+		value: choice
+	} : choice;
+}
+/** The styled prompt-message header (`? message`) — the leading line every active prompt view shares. */
+function promptHeader(styler, message) {
+	return `${styler.cyan(PROMPT_ICONS.question)} ${styler.bold(message)}`;
+}
+/** The styled submit line (`✔ message`) — the committed header an interactive prompt shows once resolved. */
+function submitHeader(styler, message) {
+	return `${styler.green(STATUS_ICONS.success)} ${styler.bold(message)}`;
+}
+/** The styled error line (`✖ message`) — appended beneath a prompt view when the last submit failed validation. */
+function errorLine(styler, message) {
+	return `${styler.red(STATUS_ICONS.error)} ${styler.red(message)}`;
+}
+/** Build the initial {@link InputState} from {@link InputOptions} — resolving the validator + styler, seeding an empty value. */
+function createInputState(options) {
+	return {
+		message: options.message,
+		default: options.default ?? "",
+		validator: resolveValidation(options.validate),
+		styler: options.styler ?? createStyler(),
+		value: ""
+	};
+}
+/** Render an {@link InputState} as a styled view — the header, the typed value (or dimmed default hint), and any error. */
+function inputView(state) {
+	const shown = state.value.length > 0 ? state.value : state.styler.dim(state.default);
+	const head = `${promptHeader(state.styler, state.message)} ${state.styler.cyan(PROMPT_ICONS.pointer)} ${shown}`;
+	return state.error === void 0 ? head : `${head}\n${errorLine(state.styler, state.error)}`;
+}
+/**
+* Advance 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 submits (the empty line falls back to the default) through the validator — an
+* invalid submit stays active with the error in the view.
+*/
+function inputReduce(state, key) {
+	if (key.ctrl && key.name === "c") return {
+		state,
+		view: inputView(state),
+		status: "cancel"
+	};
+	if (key.name === "return") {
+		const answer = state.value.length > 0 ? state.value : state.default;
+		const result = state.validator(answer);
+		if (result !== true) {
+			const next = {
+				...state,
+				error: result
+			};
+			return {
+				state: next,
+				view: inputView(next),
+				status: "active"
+			};
+		}
+		return {
+			state: {
+				...state,
+				value: answer,
+				error: void 0
+			},
+			view: `${submitHeader(state.styler, state.message)} ${state.styler.dim(answer)}`,
+			status: "submit",
+			value: answer
+		};
+	}
+	const value = editLine(state.value, key);
+	if (value === void 0) return {
+		state,
+		view: inputView(state),
+		status: "active"
+	};
+	const next = {
+		...state,
+		value,
+		error: void 0
+	};
+	return {
+		state: next,
+		view: inputView(next),
+		status: "active"
+	};
+}
+/** Build the initial {@link PasswordState} from {@link PasswordOptions} — resolving the validator + styler + mask. */
+function createPasswordState(options) {
+	return {
+		message: options.message,
+		mask: options.mask ?? "*",
+		validator: resolveValidation(options.validate),
+		styler: options.styler ?? createStyler(),
+		value: ""
+	};
+}
+/** Render a {@link PasswordState} as a styled view — the header, the value masked to `mask` repeated, and any error. */
+function passwordView(state) {
+	const masked = state.mask.repeat(state.value.length);
+	const head = `${promptHeader(state.styler, state.message)} ${state.styler.cyan(PROMPT_ICONS.pointer)} ${masked}`;
+	return state.error === void 0 ? head : `${head}\n${errorLine(state.styler, state.error)}`;
+}
+/**
+* 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,
+* ctrl-u clears, ctrl-c cancels) but the view masks the value; return submits through the
+* validator (no default fallback — a password has no echoed default).
+*/
+function passwordReduce(state, key) {
+	if (key.ctrl && key.name === "c") return {
+		state,
+		view: passwordView(state),
+		status: "cancel"
+	};
+	if (key.name === "return") {
+		const result = state.validator(state.value);
+		if (result !== true) {
+			const next = {
+				...state,
+				error: result
+			};
+			return {
+				state: next,
+				view: passwordView(next),
+				status: "active"
+			};
+		}
+		return {
+			state: {
+				...state,
+				error: void 0
+			},
+			view: `${submitHeader(state.styler, state.message)} ${state.styler.dim(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),
+		status: "active"
+	};
+	const next = {
+		...state,
+		value,
+		error: void 0
+	};
+	return {
+		state: next,
+		view: passwordView(next),
+		status: "active"
+	};
+}
+/** Build the initial {@link ConfirmState} from {@link ConfirmOptions} — defaulting the answer to `false`. */
+function createConfirmState(options) {
+	return {
+		message: options.message,
+		default: options.default ?? false,
+		styler: options.styler ?? createStyler()
+	};
+}
+/** Render a {@link ConfirmState} as a styled view — the header plus a `(Y/n)` hint with the default letter emphasized. */
+function confirmView(state) {
+	const hint = state.default ? `${state.styler.green("Y")}${state.styler.dim("/n")}` : `${state.styler.dim("y/")}${state.styler.green("N")}`;
+	return `${promptHeader(state.styler, state.message)} ${state.styler.dim("(")}${hint}${state.styler.dim(")")}`;
+}
+/**
+* Advance 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).
+*/
+function confirmReduce(state, key) {
+	if (key.ctrl && key.name === "c") return {
+		state,
+		view: confirmView(state),
+		status: "cancel"
+	};
+	let answer;
+	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),
+		status: "active"
+	};
+	return {
+		state,
+		view: `${submitHeader(state.styler, state.message)} ${state.styler.dim(answer ? "yes" : "no")}`,
+		status: "submit",
+		value: answer
+	};
+}
+/** Build the initial {@link SelectState} from {@link SelectOptions} — normalizing choices and pre-focusing the default. */
+function createSelectState(options) {
+	const choices = options.choices.map(normalizeChoice);
+	const index = choices.findIndex((choice) => choice.value === options.default);
+	return {
+		message: options.message,
+		choices,
+		styler: options.styler ?? createStyler(),
+		focused: index >= 0 ? index : 0
+	};
+}
+/** Render a {@link SelectState} as a MULTI-LINE styled view — the header followed by one row per choice, the focused row marked. */
+function selectView(state) {
+	const lines = state.choices.map((choice, index) => {
+		const active = index === state.focused;
+		return `${active ? state.styler.cyan(PROMPT_ICONS.pointer) : " "} ${active ? state.styler.green(PROMPT_ICONS.selected) : state.styler.dim(PROMPT_ICONS.dot)} ${active ? state.styler.bold(choice.name) : choice.name}${choice.description === void 0 ? "" : `  ${state.styler.dim(choice.description)}`}`;
+	});
+	return [promptHeader(state.styler, state.message), ...lines].join("\n");
+}
+/**
+* Advance 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.
+*/
+function selectReduce(state, key) {
+	if (key.ctrl && key.name === "c") return {
+		state,
+		view: selectView(state),
+		status: "cancel"
+	};
+	const count = state.choices.length;
+	if (count === 0) return {
+		state,
+		view: selectView(state),
+		status: "active"
+	};
+	if (key.name === "up" || key.name === "k") {
+		const next = {
+			...state,
+			focused: (state.focused - 1 + count) % count
+		};
+		return {
+			state: next,
+			view: selectView(next),
+			status: "active"
+		};
+	}
+	if (key.name === "down" || key.name === "j") {
+		const next = {
+			...state,
+			focused: (state.focused + 1) % count
+		};
+		return {
+			state: next,
+			view: selectView(next),
+			status: "active"
+		};
+	}
+	if (key.name === "return") {
+		const choice = state.choices[state.focused];
+		const value = choice?.value ?? "";
+		return {
+			state,
+			view: `${submitHeader(state.styler, state.message)} ${state.styler.dim(choice?.name ?? "")}`,
+			status: "submit",
+			value
+		};
+	}
+	return {
+		state,
+		view: selectView(state),
+		status: "active"
+	};
+}
+/** Build the initial {@link CheckboxState} from {@link CheckboxOptions} — normalizing choices, seeding the checked set, carrying min/max. */
+function createCheckboxState(options) {
+	const choices = options.choices.map(normalizeCheckboxChoice);
+	const checked = choices.reduce((indices, choice, index) => {
+		if (choice.checked === true) indices.push(index);
+		return indices;
+	}, []);
+	return {
+		message: options.message,
+		choices,
+		styler: options.styler ?? createStyler(),
+		focused: 0,
+		checked,
+		min: options.min,
+		max: options.max
+	};
+}
+/** Render a {@link CheckboxState} as a MULTI-LINE styled view — the header, one box per choice (focused + checked marked), a count, and any error. */
+function checkboxView(state) {
+	const lines = state.choices.map((choice, index) => {
+		const active = index === state.focused;
+		const ticked = state.checked.includes(index);
+		return `${active ? state.styler.cyan(PROMPT_ICONS.pointer) : " "} ${ticked ? state.styler.green(PROMPT_ICONS.checked) : state.styler.dim(PROMPT_ICONS.unchecked)} ${active ? state.styler.bold(choice.name) : choice.name}${choice.description === void 0 ? "" : `  ${state.styler.dim(choice.description)}`}`;
+	});
+	const summary = state.styler.dim(`${state.checked.length} selected`);
+	const body = [
+		promptHeader(state.styler, state.message),
+		...lines,
+		summary
+	].join("\n");
+	return state.error === void 0 ? body : `${body}\n${errorLine(state.styler, state.error)}`;
+}
+/**
+* Advance 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 — gated by `min` / `max` (an out-of-range count stays active with
+* the reason in the view); ctrl-c cancels.
+*/
+function checkboxReduce(state, key) {
+	if (key.ctrl && key.name === "c") return {
+		state,
+		view: checkboxView(state),
+		status: "cancel"
+	};
+	const count = state.choices.length;
+	if ((key.name === "up" || key.name === "k") && count > 0) {
+		const next = {
+			...state,
+			focused: (state.focused - 1 + count) % count,
+			error: void 0
+		};
+		return {
+			state: next,
+			view: checkboxView(next),
+			status: "active"
+		};
+	}
+	if ((key.name === "down" || key.name === "j") && count > 0) {
+		const next = {
+			...state,
+			focused: (state.focused + 1) % count,
+			error: void 0
+		};
+		return {
+			state: next,
+			view: checkboxView(next),
+			status: "active"
+		};
+	}
+	if (key.name === "space" && count > 0) {
+		const checked = toggleIndex(state.checked, state.focused);
+		const next = {
+			...state,
+			checked,
+			error: void 0
+		};
+		return {
+			state: next,
+			view: checkboxView(next),
+			status: "active"
+		};
+	}
+	if (key.name === "return") {
+		const error = gateSelection(state.checked.length, state.min, state.max);
+		if (error !== void 0) {
+			const next = {
+				...state,
+				error
+			};
+			return {
+				state: next,
+				view: checkboxView(next),
+				status: "active"
+			};
+		}
+		const ordered = [...state.checked].sort((a, b) => a - b);
+		const values = ordered.map((index) => state.choices[index]?.value).filter((value) => value !== void 0);
+		const summary = ordered.map((index) => state.choices[index]?.name).filter((name) => name !== void 0).join(", ");
+		return {
+			state: {
+				...state,
+				error: void 0
+			},
+			view: `${submitHeader(state.styler, state.message)} ${state.styler.dim(summary)}`,
+			status: "submit",
+			value: values
+		};
+	}
+	return {
+		state,
+		view: checkboxView(state),
+		status: "active"
+	};
+}
+/** Toggle `index` in a readonly index list — copy-on-write, returning the new sorted-by-insertion list. */
+function toggleIndex(indices, index) {
+	return indices.includes(index) ? indices.filter((i) => i !== index) : [...indices, index];
+}
+/** The min/max gate for a checkbox submit — the rejection message when `count` is out of range, else `undefined`. */
+function gateSelection(count, min, max) {
+	if (min !== void 0 && count < min) return `Select at least ${String(min)} option${min === 1 ? "" : "s"}`;
+	if (max !== void 0 && count > max) return `Select no more than ${String(max)} option${max === 1 ? "" : "s"}`;
+}
+/** Build the initial {@link EditorState} from {@link EditorOptions} — resolving the validator + styler, seeding empty lines. */
+function createEditorState(options) {
+	return {
+		message: options.message,
+		default: options.default ?? "",
+		validator: resolveValidation(options.validate),
+		styler: options.styler ?? createStyler(),
+		lines: [],
+		current: ""
+	};
+}
+/** Render an {@link EditorState} as a MULTI-LINE styled view — the header (with a Ctrl+D hint), the committed lines, the in-progress line, and any error. */
+function editorView(state) {
+	const view = [`${promptHeader(state.styler, state.message)} ${state.styler.dim("(Ctrl+D to finish)")}`, ...[...state.lines, `${state.styler.cyan(PROMPT_ICONS.pointer)} ${state.current}`]].join("\n");
+	return state.error === void 0 ? view : `${view}\n${errorLine(state.styler, state.error)}`;
+}
+/**
+* Advance 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) through the validator; ctrl-c cancels. An invalid finish stays active with
+* the error.
+*/
+function editorReduce(state, key) {
+	if (key.ctrl && key.name === "c") return {
+		state,
+		view: editorView(state),
+		status: "cancel"
+	};
+	if (key.ctrl && key.name === "d") {
+		const lines = state.current.length > 0 ? [...state.lines, state.current] : state.lines;
+		const joined = lines.join("\n");
+		const answer = joined.length > 0 ? joined : state.default;
+		const result = state.validator(answer);
+		if (result !== true) {
+			const next = {
+				...state,
+				error: result
+			};
+			return {
+				state: next,
+				view: editorView(next),
+				status: "active"
+			};
+		}
+		return {
+			state: {
+				...state,
+				error: void 0
+			},
+			view: `${submitHeader(state.styler, state.message)} ${state.styler.dim(`${String(lines.length)} line${lines.length === 1 ? "" : "s"}`)}`,
+			status: "submit",
+			value: answer
+		};
+	}
+	if (key.name === "return") {
+		const next = {
+			...state,
+			lines: [...state.lines, state.current],
+			current: "",
+			error: void 0
+		};
+		return {
+			state: next,
+			view: editorView(next),
+			status: "active"
+		};
+	}
+	const current = editLine(state.current, key);
+	if (current === void 0) return {
+		state,
+		view: editorView(state),
+		status: "active"
+	};
+	const next = {
+		...state,
+		current,
+		error: void 0
+	};
+	return {
+		state: next,
+		view: editorView(next),
+		status: "active"
+	};
+}
+/**
+* Apply 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).
+*/
+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}`;
+}
+/**
+* Produce the WIRE-SAFE form of a prompt's options — the {@link PendingPrompt.options} a broker
+* serializes over SSE. Drops everything that cannot cross the wire (a `styler`, and any
+* function-valued `validate` rule), while KEEPING the declarative data a remote client needs to
+* reconstruct the prompt: the {@link ValidationRules} as data, plus `message` / `choices` /
+* `default` / `mask` / `min` / `max`. This is WHY T-a's validation is rules-as-data: a `Validator`
+* FUNCTION can't be serialized, but its declarative rules can — the client rebuilds the validator
+* from them via {@link resolveValidation}.
+*
+* @remarks
+* - **Functions are dropped.** A top-level function value (e.g. a bare-`Validator` `validate`) is
+*   omitted entirely; the `styler` (a fluent function-bearing object) is dropped by key.
+* - **`validate` rules are flattened.** A {@link ValidationRules} bag is copied with each
+*   function rule replaced by `true` (the rule's INTENT survives as the built-in check; its
+*   custom function does not). A bare-function `validate` is dropped (no declarative form to keep).
+* - **`choices` are function-stripped.** Each choice keeps its plain fields (`name` / `value` /
+*   `description` / `checked`); a bare string passes through.
+*
+* @param options - The raw prompt options bag (may hold functions / a styler)
+* @returns A JSON-safe options record — only serializable, declarative data
+*/
+function serializePromptOptions(options) {
+	const result = {};
+	for (const [key, value] of Object.entries(options)) {
+		if (key === "styler" || typeof value === "function") continue;
+		if (key === "validate") {
+			const rules = serializeValidationRules(value);
+			if (rules !== void 0) result[key] = rules;
+			continue;
+		}
+		if (key === "choices") {
+			result[key] = serializeChoices(value);
+			continue;
+		}
+		result[key] = value;
+	}
+	return result;
+}
+/**
+* Flatten a `validate` option to its wire-safe {@link ValidationRules} DATA — a function rule
+* becomes `true` (its built-in check survives; its body cannot cross the wire). A bare-function
+* `validate` (no rules object) has no declarative form, so it yields `undefined` (dropped).
+*/
+function serializeValidationRules(validate) {
+	if (!isRecord(validate)) return void 0;
+	const rules = {};
+	for (const [rule, value] of Object.entries(validate)) rules[rule] = typeof value === "function" ? true : value;
+	return rules;
+}
+/** Strip functions from a `choices` option — each choice keeps its plain fields; a bare string passes through. */
+function serializeChoices(choices) {
+	if (!Array.isArray(choices)) return [];
+	return choices.map((choice) => {
+		if (isString(choice)) return choice;
+		if (!isRecord(choice)) return choice;
+		const normalized = {};
+		for (const [key, value] of Object.entries(choice)) if (typeof value !== "function") normalized[key] = value;
+		return normalized;
+	});
+}
+/** Narrow an unknown value to a {@link PromptType} — one of the six prompt forms. */
+var isPromptType = literalOf("input", "password", "confirm", "select", "checkbox", "editor");
+/** Narrow an unknown value to a {@link PendingPromptStatus}. */
+var isPendingPromptStatus = literalOf("pending", "answered", "expired");
+/**
+* Narrow an unknown wire value to a {@link PendingPrompt} — the §14 guard a {@link PromptClient}
+* applies to each decoded SSE `pending` payload before dispatching it (never an `as`).
+*/
+var isPendingPrompt = recordOf({
+	id: isNonEmptyString,
+	form: isPromptType,
+	message: isString,
+	options: isRecord,
+	status: isPendingPromptStatus,
+	time: isNumber
+});
+/**
+* Rebuild a wire-decoded `validate` payload into a {@link ValidationRules} bag — the inverse of
+* {@link serializeValidationRules}. Keeps only the primitive rule values (`boolean` / `number` /
+* `string`) a serialized prompt could carry; an empty / non-record / all-dropped payload yields
+* `undefined` (no rules to apply). The client feeds the result back through {@link resolveValidation}.
+*/
+function reconstructValidationRules(value) {
+	if (!isRecord(value)) return void 0;
+	const rules = {};
+	let count = 0;
+	for (const [rule, item] of Object.entries(value)) {
+		if (rule === "pattern") continue;
+		if (isBoolean(item) || isNumber(item) || isString(item)) {
+			rules[rule] = item;
+			count += 1;
+		}
+	}
+	if (count === 0) return void 0;
+	return rules;
+}
+/** Read one option by key, narrowed by `guard` — `undefined` when absent or off-shape (§14, never an `as`). */
+function resolveOption(options, key, guard) {
+	const value = options[key];
+	return guard(value) ? value : void 0;
+}
+/** Narrow an unknown value to a {@link PromptChoice} — the `recordOf` shape inlined so no non-exported member lingers (§5). */
+function isPromptChoice(value) {
+	return recordOf({
+		name: isString,
+		value: isString,
+		description: isString
+	}, ["description"])(value);
+}
+/** Narrow an unknown value to a {@link CheckboxChoice} — the `recordOf` shape inlined so no non-exported member lingers (§5). */
+function isCheckboxChoice(value) {
+	return recordOf({
+		name: isString,
+		value: isString,
+		description: isString,
+		checked: isBoolean
+	}, ["description", "checked"])(value);
+}
+/** Read a `choices` option as a list of bare strings / full choices — each element narrowed by `guard`, off-shape elements stringified. */
+function resolveChoices(options, guard) {
+	const choices = options.choices;
+	if (!Array.isArray(choices)) return [];
+	return choices.map((choice) => {
+		if (isString(choice)) return choice;
+		if (guard(choice)) return choice;
+		return String(choice);
+	});
+}
+/**
+* Sanitize a list of resolved choices' human-readable labels (`name` + `description`) with
+* {@link stripControls} — shared by the `select` and `checkbox` branches of
+* {@link dispatchPendingPrompt} so a remote-supplied choice can never inject raw control bytes
+* into the local terminal's rendered view.
+*
+* @param choices - The resolved choices (bare strings or full {@link PromptChoice} /
+*   {@link CheckboxChoice} objects) as returned by {@link resolveChoices}
+* @returns The same choices with every `name` / `description` control-stripped
+*/
+function sanitizeChoiceLabels(choices) {
+	return choices.map((choice) => {
+		if (isString(choice)) return stripControls(choice);
+		const description = choice.description === void 0 ? void 0 : stripControls(choice.description);
+		return {
+			...choice,
+			name: stripControls(choice.name),
+			description
+		};
+	});
+}
+/**
+* Dispatch a {@link PendingPrompt} to the matching {@link PromptFormInterface} method — the bridge
+* step a {@link PromptClient} runs to drive a LOCAL terminal with a prompt issued elsewhere.
+* Reconstructs typed options from the wire-safe {@link PendingPrompt.options} (every field
+* §14-narrowed, never an `as`; the validator rebuilt from rules via {@link reconstructValidationRules}),
+* then calls the matching prompt form and returns its resolved value.
+*
+* @param terminal - The local {@link PromptFormInterface} to drive
+* @param pending - The decoded pending prompt to dispatch
+* @returns The prompt's resolved value (a `string` / `boolean` / `readonly string[]` per form)
+*/
+function dispatchPendingPrompt(terminal, pending) {
+	const options = pending.options;
+	const validate = reconstructValidationRules(options.validate);
+	const message = stripControls(pending.message);
+	switch (pending.form) {
+		case "input": {
+			const value = resolveOption(options, "default", isString);
+			return terminal.input({
+				message,
+				default: value === void 0 ? void 0 : stripControls(value),
+				validate
+			});
+		}
+		case "password": {
+			const value = resolveOption(options, "mask", isString);
+			return terminal.password({
+				message,
+				mask: value === void 0 ? void 0 : stripControls(value),
+				validate
+			});
+		}
+		case "confirm": return terminal.confirm({
+			message,
+			default: resolveOption(options, "default", isBoolean)
+		});
+		case "select": {
+			const value = resolveOption(options, "default", isString);
+			return terminal.select({
+				message,
+				choices: sanitizeChoiceLabels(resolveChoices(options, isPromptChoice)),
+				default: value === void 0 ? void 0 : stripControls(value)
+			});
+		}
+		case "checkbox": return terminal.checkbox({
+			message,
+			choices: sanitizeChoiceLabels(resolveChoices(options, isCheckboxChoice)),
+			min: resolveOption(options, "min", isNumber),
+			max: resolveOption(options, "max", isNumber)
+		});
+		case "editor": {
+			const value = resolveOption(options, "default", isString);
+			return terminal.editor({
+				message,
+				default: value === void 0 ? void 0 : stripControls(value),
+				validate
+			});
+		}
+	}
+}
+/**
+* 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
+* 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.
+*/
+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. */
+function globalFetch(input, init) {
+	return fetch(input, init);
+}
+/**
+* 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.
+*/
+function isAbortError(error) {
+	return (error instanceof DOMException || error instanceof Error) && error.name === "AbortError";
+}
+/**
+* Parse a JSON wire string TOTAL — a malformed / empty payload yields `undefined` (the caller's
+* guard then rejects it), never a throw. The {@link import('./PromptClient.js').PromptClient}
+* decodes every SSE `data` field through this before §14-narrowing it.
+*/
+function parseWireJSON(text) {
+	if (text.length === 0) return void 0;
+	try {
+		return JSON.parse(text);
+	} catch {
+		return;
+	}
+}
+/**
+* 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
+* A loopback host (`localhost`, `127.0.0.1`, `[::1]`) over `http://` is exempt (local
+* development has no network hop to eavesdrop on); every other `http://` host is insecure.
+* 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
+*
+* @example
+* ```ts
+* isInsecureRemote('http://example.com')     // true
+* isInsecureRemote('http://localhost:3000')  // false
+* isInsecureRemote('https://example.com')    // false
+* ```
+*/
+function isInsecureRemote(url) {
+	if (!url.startsWith("http://")) return false;
+	const rest = url.slice(7);
+	const hostEnd = rest.search(/[/?#]/);
+	const authority = hostEnd === -1 ? rest : rest.slice(0, hostEnd);
+	const host = authority.includes("@") ? authority.slice(authority.indexOf("@") + 1) : authority;
+	const hostname = host.startsWith("[") ? host.slice(0, host.indexOf("]") + 1) : host.split(":")[0] ?? "";
+	return hostname !== "localhost" && hostname !== "127.0.0.1" && hostname !== "[::1]";
+}
+//#endregion
+//#region src/core/Prompt.ts
+/**
+* The headless prompt BROKER (observable §13) — parks each {@link PromptInterface} call as a
+* pending prompt and returns a Promise that resolves when the prompt is {@link answer}ed (or
+* rejects on timeout / teardown). The tri-surface's headless arm: there is no terminal here, so a
+* transport forwards each `pending` event to whoever can answer, and {@link answer} resolves the
+* parked Promise — for environments where direct user access is unavailable (a headless server on
+* stdio, a browser with no TTY, a prompt issued on one machine answered on another).
+*
+* @remarks
+* - **Park-as-Promise.** Each `input` / `password` / `confirm` / `select` / `checkbox` / `editor`
+*   mints an id (`crypto.randomUUID()`), parks a wire-safe {@link PendingPrompt}, emits `pending`,
+*   and returns an unresolved Promise. The prompt's options are serialized
+*   ({@link serializePromptOptions}) so a transport can forward them as-is.
+* - **Answer validates + type-checks.** {@link answer} runs the prompt's per-form gate: it
+*   type-checks `value` to the form (string / boolean / string[]) AND, for the text forms, runs
+*   the validator resolved from the original `validate` rules. A rejected answer returns `false`
+*   and the prompt stays `pending`; an accepted answer resolves the Promise, emits `answer`, and
+*   removes the prompt.
+* - **Timeout → expire → reject.** An unanswered prompt expires after `timeout` ms (via the
+*   INJECTED timer): `expire` fires and the parked Promise rejects with a {@link TerminalError}
+*   (`code: 'EXPIRE'`). {@link destroy} expires every still-pending prompt the same way.
+* - **Deterministic.** The timer is injectable ({@link import('./types.js').TimerHandler}); a test
+*   supplies one that fires on demand, so expiry is driven without real time.
+*
+* @example
+* ```ts
+* const prompt = createPrompt({ timeout: 60_000 })
+* prompt.emitter.on('pending', (pending) => broadcast(pending)) // forward to a client
+*
+* const name = await prompt.input({ message: 'Your name' }) // parks; resolves on answer()
+* // ...elsewhere, a client POSTs the answer back:
+* prompt.answer(id, 'Ada') // resolves the awaited input() above
+* ```
+*/
+var Prompt = class {
+	#timeout;
+	#timer;
+	#parked = /* @__PURE__ */ new Map();
+	#emitter;
+	#destroyed = false;
+	constructor(options) {
+		this.#timeout = options?.timeout ?? 3e5;
+		this.#timer = options?.timer ?? defaultTimer;
+		this.#emitter = new Emitter({
+			on: options?.on,
+			error: options?.error
+		});
+	}
+	get emitter() {
+		return this.#emitter;
+	}
+	get count() {
+		return this.#parked.size;
+	}
+	pending(id) {
+		if (id !== void 0) return this.#parked.get(id)?.prompt;
+		const result = [];
+		for (const parked of this.#parked.values()) result.push(parked.prompt);
+		return result;
+	}
+	answer(id, value) {
+		const parked = this.#parked.get(id);
+		if (parked === void 0) return false;
+		const accepted = parked.respond(value);
+		if (accepted === void 0) return false;
+		parked.cancel();
+		this.#emitter.emit("answer", id, accepted);
+		this.#parked.delete(id);
+		return true;
+	}
+	input(options) {
+		const validator = resolveValidation(options.validate);
+		return this.#park("input", options.message, options, (value) => isString(value) && validator(value) === true ? value : void 0);
+	}
+	password(options) {
+		const validator = resolveValidation(options.validate);
+		return this.#park("password", options.message, options, (value) => isString(value) && validator(value) === true ? value : void 0);
+	}
+	confirm(options) {
+		return this.#park("confirm", options.message, options, (value) => isBoolean(value) ? value : void 0);
+	}
+	select(options) {
+		const values = new Set(options.choices.map(normalizeChoice).map((choice) => choice.value));
+		return this.#park("select", options.message, options, (value) => isString(value) && values.has(value) ? value : void 0);
+	}
+	checkbox(options) {
+		const values = new Set(options.choices.map(normalizeCheckboxChoice).map((choice) => choice.value));
+		const { min, max } = options;
+		return this.#park("checkbox", options.message, options, (value) => {
+			if (!isArray(value) || !value.every(isString)) return void 0;
+			if (!value.every((item) => values.has(item))) return void 0;
+			if (min !== void 0 && value.length < min) return void 0;
+			if (max !== void 0 && value.length > max) return void 0;
+			return value;
+		});
+	}
+	editor(options) {
+		const validator = resolveValidation(options.validate);
+		return this.#park("editor", options.message, options, (value) => isString(value) && validator(value) === true ? value : void 0);
+	}
+	destroy() {
+		if (this.#destroyed) return;
+		this.#destroyed = true;
+		for (const id of [...this.#parked.keys()]) this.#expire(id);
+		this.#parked.clear();
+		this.#emitter.destroy();
+	}
+	#park(form, message, options, gate) {
+		if (this.#destroyed) return Promise.reject(new TerminalError("EXPIRE", "broker destroyed"));
+		const id = crypto.randomUUID();
+		const prompt = {
+			id,
+			form,
+			message,
+			options: serializePromptOptions(options),
+			status: "pending",
+			time: Date.now()
+		};
+		return new Promise((resolve, reject) => {
+			const cancel = this.#timer(() => this.#expire(id), this.#timeout);
+			const respond = (value) => {
+				const accepted = gate(value);
+				if (accepted === void 0) return void 0;
+				const current = this.#parked.get(id);
+				if (current !== void 0) this.#parked.set(id, {
+					...current,
+					prompt: {
+						...current.prompt,
+						status: "answered"
+					}
+				});
+				resolve(accepted);
+				return accepted;
+			};
+			const expire = () => {
+				reject(new TerminalError("EXPIRE", `prompt ${id} expired`, { id }));
+			};
+			this.#parked.set(id, {
+				prompt,
+				respond,
+				expire,
+				cancel
+			});
+			this.#emitter.emit("pending", prompt);
+		});
+	}
+	#expire(id) {
+		const parked = this.#parked.get(id);
+		if (parked === void 0) return;
+		parked.cancel();
+		this.#parked.set(id, {
+			...parked,
+			prompt: {
+				...parked.prompt,
+				status: "expired"
+			}
+		});
+		this.#emitter.emit("expire", id);
+		this.#parked.delete(id);
+		parked.expire();
+	}
+};
+//#endregion
+//#region src/core/PromptClient.ts
+/**
+* The SSE prompt BRIDGE (observable §13) — the client-side counterpart to
+* {@link import('./Prompt.js').Prompt}. Connects to a remote broker's SSE endpoint, receives
+* serialized pending prompts, dispatches EACH to a LOCAL {@link PromptFormInterface} terminal (so
+* a human at THIS machine answers a prompt parked elsewhere), and POSTs the answer back.
+* Universal — `fetch` + SSE are web-standard, so it runs in a browser or on a server; the
+* injected `fetch` / timer make it fully deterministic in tests.
+*
+* @remarks
+* - **Connect + reconnect.** {@link connect} opens the SSE stream (via the injected `fetch` + the
+*   core `SSEParser`) and loops, reconnecting after the stream drops with the `delay` backoff
+*   (driven by the injected timer) — unless `reconnect` is `false`, the client was
+*   {@link destroy}ed, or the drop was a deliberate {@link disconnect} (an abort).
+* - **Dispatch + answer.** Each decoded `pending` event is narrowed to a `PendingPrompt` (§14 —
+*   never an `as`), dispatched to `terminal`, and its resolved value POSTed back to `url`.
+*   Dispatch is strictly SERIAL: the read loop drives the terminal for ONE prompt at a time and
+*   only reads/dispatches the next event after the current prompt fully settles (its answer
+*   POSTed). A prompt id redelivered by the broker AFTER its prior dispatch has settled is
+*   dispatched again — the client does not dedupe across completion.
+* - **Server signals.** An `expire` event (the broker dropped a parked prompt) emits `expire`; a
+*   `shutdown` event calls {@link disconnect} (not {@link destroy}) — the client stops streaming
+*   without auto-reconnect but stays reusable; a later {@link connect} recovers it.
+* - **Lean events (§13).** `connect` / `disconnect` / `expire` / `error` — errors are `unknown`.
+*   `disconnect` fires exactly once per connected-to-disconnected transition, whether triggered by
+*   the server ending the stream cleanly or by a deliberate {@link disconnect} / {@link destroy}.
+*
+* @example
+* ```ts
+* const client = createPromptClient({
+* 	url: 'http://localhost:3001/prompts',
+* 	terminal: createTerminal(), // a local PromptFormInterface (T-c)
+* 	on: { connect: () => log('connected') },
+* })
+* await client.connect() // streams remote prompts to the local terminal, POSTs answers back
+* ```
+*/
+var PromptClient = class {
+	url;
+	#terminal;
+	#token;
+	#reconnect;
+	#delay;
+	#fetch;
+	#timer;
+	#emitter;
+	#controller;
+	#backoff;
+	#wake;
+	#connecting = false;
+	#connected = false;
+	#destroyed = false;
+	#warnedInsecureToken = false;
+	constructor(options) {
+		this.url = options.url;
+		this.#terminal = options.terminal;
+		this.#token = options.token;
+		this.#reconnect = options.reconnect ?? true;
+		this.#delay = options.delay ?? 2e3;
+		this.#fetch = options.fetch ?? globalFetch;
+		this.#timer = options.timer ?? defaultTimer;
+		this.#emitter = new Emitter({
+			on: options.on,
+			error: options.error
+		});
+	}
+	get emitter() {
+		return this.#emitter;
+	}
+	get connected() {
+		return this.#connected;
+	}
+	async connect() {
+		if (this.#destroyed) return;
+		if (this.#connecting) return;
+		this.#connecting = true;
+		while (this.#connecting && !this.#destroyed) {
+			try {
+				await this.#stream();
+			} catch (error) {
+				this.#markDisconnected();
+				if (this.#destroyed || isAbortError(error)) return;
+				this.#emitter.emit("error", error);
+			}
+			if (!this.#reconnect || !this.#connecting || this.#destroyed) return;
+			await this.#wait(this.#delay);
+		}
+	}
+	disconnect() {
+		this.#connecting = false;
+		this.#controller?.abort();
+		this.#controller = void 0;
+		this.#backoff?.();
+		this.#backoff = void 0;
+		const wake = this.#wake;
+		this.#wake = void 0;
+		wake?.();
+		this.#markDisconnected();
+	}
+	destroy() {
+		if (this.#destroyed) return;
+		this.#destroyed = true;
+		this.disconnect();
+		this.#emitter.destroy();
+	}
+	async #stream() {
+		if (this.#token !== void 0 && isInsecureRemote(this.url) && !this.#warnedInsecureToken) {
+			this.#warnedInsecureToken = true;
+			this.#emitter.emit("error", /* @__PURE__ */ new Error("auth token sent as cleartext over insecure http; use https"));
+		}
+		const controller = new AbortController();
+		this.#controller = controller;
+		const response = await this.#fetch(this.url, {
+			headers: this.#headers({ Accept: ACCEPT_EVENT_STREAM }),
+			signal: controller.signal
+		});
+		if (!response.ok) throw new Error(`broker returned ${String(response.status)}`);
+		const body = response.body;
+		if (body === null) throw new Error("broker sent no stream");
+		this.#connected = true;
+		this.#emitter.emit("connect");
+		const reader = body.getReader();
+		const decoder = new TextDecoder();
+		const parser = createSSEParser({ limit: SSE_BUFFER_LIMIT });
+		try {
+			for (;;) {
+				const { done, value } = await reader.read();
+				if (done) break;
+				for (const event of parser.parse(decoder.decode(value, { stream: true }))) await this.#handle(event);
+			}
+		} finally {
+			reader.releaseLock();
+		}
+		this.#markDisconnected();
+	}
+	async #handle(event) {
+		if (event.event === SSE_EVENTS.pending) {
+			const parsed = parseWireJSON(event.data);
+			if (isPendingPrompt(parsed)) await this.#dispatch(parsed.id, parsed);
+			return;
+		}
+		if (event.event === SSE_EVENTS.expire) {
+			const parsed = parseWireJSON(event.data);
+			if (isRecord(parsed) && isString(parsed.id)) this.#emitter.emit("expire", parsed.id);
+			return;
+		}
+		if (event.event === SSE_EVENTS.shutdown) this.disconnect();
+	}
+	async #dispatch(id, pending) {
+		try {
+			const value = await dispatchPendingPrompt(this.#terminal, pending);
+			await this.#post(id, value);
+		} catch (error) {
+			this.#emitter.emit("error", error);
+		}
+	}
+	async #post(id, value) {
+		if (!(await this.#fetch(this.url, {
+			method: "POST",
+			headers: this.#headers({ "Content-Type": "application/json" }),
+			body: JSON.stringify({
+				id,
+				value
+			})
+		})).ok) this.#emitter.emit("error", /* @__PURE__ */ new Error(`broker rejected answer ${id}`));
+	}
+	#markDisconnected() {
+		if (!this.#connected) return;
+		this.#connected = false;
+		this.#emitter.emit("disconnect");
+	}
+	#headers(base) {
+		if (this.#token !== void 0) base[HEADER_TOKEN] = this.#token;
+		return base;
+	}
+	#wait(ms) {
+		return new Promise((resolve) => {
+			const settle = () => {
+				this.#backoff = void 0;
+				this.#wake = void 0;
+				resolve();
+			};
+			this.#wake = settle;
+			this.#backoff = this.#timer(() => {
+				settle();
+			}, ms);
+		});
+	}
+};
+//#endregion
+//#region src/core/factories.ts
+/**
+* Create the headless prompt {@link PromptInterface} BROKER — it parks each prompt call as a
+* pending prompt and resolves it when {@link PromptInterface.answer} arrives (or rejects on
+* timeout). The tri-surface's headless arm: subscribe `emitter.on('pending', …)` to forward each
+* prompt to whoever can answer (an SSE transport, a remote terminal), then route the answer back
+* through `answer(id, value)`.
+*
+* @param options - See {@link PromptOptions}
+* @returns A {@link PromptInterface}
+*
+* @remarks
+* - **Park-as-Promise.** `await prompt.input({ message })` blocks until `answer(id, value)` accepts
+*   a matching value; the value is validated (text forms) and type-checked to the form first.
+* - **Timeout → expire → reject (deterministic).** An unanswered prompt expires after
+*   `options.timeout` (default {@link import('./constants.js').DEFAULT_PROMPT_TIMEOUT_MS}) and its
+*   Promise rejects with a {@link import('./errors.js').TerminalError}; inject `options.timer` to
+*   drive expiry without real time.
+*
+* @example
+* ```ts
+* import { createPrompt } from '@src/core'
+*
+* const prompt = createPrompt()
+* prompt.emitter.on('pending', (pending) => send(pending)) // forward to a remote client
+* const name = await prompt.input({ message: 'Your name', validate: { required: true } })
+* ```
+*/
+function createPrompt(options) {
+	return new Prompt(options);
+}
+/**
+* Create the SSE prompt {@link PromptClientInterface} BRIDGE — it connects to a remote broker's SSE
+* endpoint, dispatches each received prompt to a LOCAL {@link import('./types.js').PromptFormInterface}
+* terminal (so a human at this machine answers a prompt parked elsewhere), and POSTs the answer
+* back. Universal — `fetch` / SSE are web-standard.
+*
+* @param options - See {@link PromptClientOptions} (`url` + `terminal` required)
+* @returns A {@link PromptClientInterface}
+*
+* @remarks
+* - **Connect + reconnect.** `await client.connect()` streams remote prompts until the stream
+*   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`).
+*
+* @example
+* ```ts
+* import { createPromptClient } from '@src/core'
+*
+* const client = createPromptClient({ url: 'http://host/prompts', terminal })
+* await client.connect()
+* ```
+*/
+function createPromptClient(options) {
+	return new PromptClient(options);
+}
+//#endregion
+export { ACCEPT_EVENT_STREAM, ALPHANUMERIC_PATTERN, BACKSPACE, CONTROL_NAMES, CTRL_A, CTRL_C, CTRL_D, CTRL_E, CTRL_U, DEFAULT_MASK, DEFAULT_PROMPT_TIMEOUT_MS, DEFAULT_RECONNECT_DELAY_MS, DELETE, EMAIL_PATTERN, ESCAPE, HEADER_TOKEN, INTEGER_PATTERN, KEY_CSI, KEY_SS3, NEWLINE, NUMERIC_PATTERN, PROMPT_ICONS, Prompt, PromptClient, RETURN, RULE_MESSAGES, SEQUENCE_NAMES, SPACE, SSE_BUFFER_LIMIT, SSE_EVENTS, TAB, TerminalError, URL_PATTERN, appendRule, buildRuleValidator, checkboxReduce, checkboxView, composeValidators, confirmReduce, confirmView, createCheckboxState, createConfirmState, createEditorState, createInputState, createPasswordState, createPrompt, createPromptClient, createSelectState, defaultTimer, dispatchPendingPrompt, editLine, editorReduce, editorView, errorLine, evaluateRule, gateSelection, globalFetch, inputReduce, inputView, isAbortError, isCheckboxChoice, isInsecureRemote, isPendingPrompt, isPendingPromptStatus, isPrintable, isPromptChoice, isPromptType, isTerminalError, normalizeCheckboxChoice, normalizeChoice, parseKey, parseWireJSON, passing, passwordReduce, passwordView, promptHeader, reconstructValidationRules, resolveChoices, resolveOption, resolveValidation, sanitizeChoiceLabels, selectReduce, selectView, serializeChoices, serializePromptOptions, serializeValidationRules, submitHeader, toggleIndex };
+
+//# sourceMappingURL=index.js.map