@orkestrel/terminal 0.0.6 → 0.0.8

package/dist/src/core/index.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-let _orkestrel_contract = require("@orkestrel/contract");
 let _orkestrel_console = require("@orkestrel/console");
+let _orkestrel_contract = require("@orkestrel/contract");
 let _orkestrel_emitter = require("@orkestrel/emitter");
 let _orkestrel_sse = require("@orkestrel/sse");
 let _orkestrel_database = require("@orkestrel/database");
@@ -130,9 +130,10 @@ var CONTROL_NAMES = Object.freeze({
 });
 /** 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. */
+/**
+* Matches an HTTP(S) URL. The `url` rule tests against this. Kept locally because it is
+* narrower than `FORMAT_PATTERNS.uri`, which accepts other URI schemes.
+*/
 var URL_PATTERN = /^https?:\/\/.+/;
 /** Matches a numeric value (integer or decimal, optional sign). The `numeric` rule tests against this. */
 var NUMERIC_PATTERN = /^-?\d+(\.\d+)?$/;
@@ -159,11 +160,8 @@ var RULE_MESSAGES = Object.freeze({
 	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.
+* The six 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
 * - `question` — the leading mark on a prompt's message line.
@@ -179,6 +177,79 @@ var PROMPT_ICONS = Object.freeze({
 	checked: "☑",
 	unchecked: "☐"
 });
+/**
+* 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.
+*/
+var PROMPT_ROLES = Object.freeze([
+	"question",
+	"pointer",
+	"message",
+	"content",
+	"success",
+	"error",
+	"selected",
+	"focus",
+	"hint",
+	"muted",
+	"description"
+]);
+/**
+* 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
+* console module's own {@link import('@orkestrel/console').freezeStyle}; the baseline
+* {@link import('./helpers.js').createPromptTheme} merges a partial theme over.
+*
+* @remarks
+* The default roles reproduce the views' historical coloring exactly: `question` / `pointer` cyan,
+* `message` / `focus` bold, `success` / `selected` green, `error` red, `hint` / `muted` /
+* `description` dim, and `content` the EMPTY style — an empty style renders bare text, so primary
+* content keeps the bytes it had before it became themeable.
+* Two roles sharing a style today are still two roles — re-mapping one leaves the other alone.
+*/
+var DEFAULT_PROMPT_THEME = Object.freeze({
+	icons: Object.freeze({
+		question: PROMPT_ICONS.question,
+		pointer: PROMPT_ICONS.pointer,
+		dot: PROMPT_ICONS.dot,
+		selected: PROMPT_ICONS.selected,
+		checked: PROMPT_ICONS.checked,
+		unchecked: PROMPT_ICONS.unchecked,
+		success: _orkestrel_console.STATUS_ICONS.success,
+		error: _orkestrel_console.STATUS_ICONS.error
+	}),
+	roles: Object.freeze({
+		question: (0, _orkestrel_console.freezeStyle)({
+			foreground: "cyan",
+			attributes: []
+		}),
+		pointer: (0, _orkestrel_console.freezeStyle)({
+			foreground: "cyan",
+			attributes: []
+		}),
+		message: (0, _orkestrel_console.freezeStyle)({ attributes: ["bold"] }),
+		content: (0, _orkestrel_console.freezeStyle)({ attributes: [] }),
+		success: (0, _orkestrel_console.freezeStyle)({
+			foreground: "green",
+			attributes: []
+		}),
+		error: (0, _orkestrel_console.freezeStyle)({
+			foreground: "red",
+			attributes: []
+		}),
+		selected: (0, _orkestrel_console.freezeStyle)({
+			foreground: "green",
+			attributes: []
+		}),
+		focus: (0, _orkestrel_console.freezeStyle)({ attributes: ["bold"] }),
+		hint: (0, _orkestrel_console.freezeStyle)({ attributes: ["dim"] }),
+		muted: (0, _orkestrel_console.freezeStyle)({ attributes: ["dim"] }),
+		description: (0, _orkestrel_console.freezeStyle)({ attributes: ["dim"] })
+	})
+});
 /** 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. */
@@ -272,6 +343,63 @@ var isPendingPrompt = (0, _orkestrel_contract.recordOf)({
 	from: _orkestrel_contract.isString,
 	to: _orkestrel_contract.isString
 }, ["from", "to"]);
+/**
+* Narrow an unknown value to a console {@link Style} — the value every
+* {@link import('./types.js').PromptRole} carries, built from the console module's own
+* {@link import('@orkestrel/console').COLORS} + {@link import('@orkestrel/console').ATTRIBUTES} so
+* the style vocabulary has ONE source.
+*
+* @remarks
+* The record is CLOSED and matches the `Style` contract exactly: `foreground` and `background` are
+* optional and each must name a color (`default` included, as the console `Color` union has it),
+* `attributes` is REQUIRED and must be an array over the attribute set, and any other key rejects
+* the whole value.
+*/
+var isStyle = (0, _orkestrel_contract.recordOf)({
+	foreground: (0, _orkestrel_contract.literalOf)(..._orkestrel_console.COLORS, "default"),
+	background: (0, _orkestrel_contract.literalOf)(..._orkestrel_console.COLORS, "default"),
+	attributes: (0, _orkestrel_contract.arrayOf)((0, _orkestrel_contract.literalOf)(..._orkestrel_console.ATTRIBUTES))
+}, ["foreground", "background"]);
+/**
+* Narrow an unknown wire value to a {@link PromptThemeOptions} — the §14 guard a remote prompt's
+* `theme` option passes before it reaches a local prompt.
+*
+* @remarks
+* The shape is CLOSED at every level: an unknown icon slot, an unknown role, a non-string glyph, or
+* a role whose value is not a {@link isStyle}-shaped console style rejects the whole theme, so a
+* hostile payload degrades to the default theme rather than partially applying. Glyphs still carry
+* arbitrary text at this point — {@link import('./helpers.js').sanitizeThemeIcons} strips their
+* control bytes on dispatch.
+*
+* The icons and roles shapes are checked against their complete union-keyed guard records. A slot
+* added to either union without an entry here is a compile error rather than a wire theme that is
+* silently refused.
+*/
+var isPromptThemeOptions = (0, _orkestrel_contract.recordOf)({
+	icons: (0, _orkestrel_contract.recordOf)({
+		question: _orkestrel_contract.isString,
+		pointer: _orkestrel_contract.isString,
+		dot: _orkestrel_contract.isString,
+		selected: _orkestrel_contract.isString,
+		checked: _orkestrel_contract.isString,
+		unchecked: _orkestrel_contract.isString,
+		success: _orkestrel_contract.isString,
+		error: _orkestrel_contract.isString
+	}, true),
+	roles: (0, _orkestrel_contract.recordOf)({
+		question: isStyle,
+		pointer: isStyle,
+		message: isStyle,
+		content: isStyle,
+		success: isStyle,
+		error: isStyle,
+		selected: isStyle,
+		focus: isStyle,
+		hint: isStyle,
+		description: isStyle,
+		muted: isStyle
+	}, true)
+}, true);
 /** Narrow an unknown value to a {@link TerminalSnapshot}. */
 var isTerminalSnapshot = (0, _orkestrel_contract.recordOf)({
 	id: _orkestrel_contract.isNonEmptyString,
@@ -396,7 +524,7 @@ function evaluateRule(rule, check, input) {
 			}
 			break;
 		case "email":
-			if (check === true && !EMAIL_PATTERN.test(input)) return RULE_MESSAGES.email;
+			if (check === true && !_orkestrel_contract.FORMAT_PATTERNS.email.test(input)) return RULE_MESSAGES.email;
 			break;
 		case "url":
 			if (check === true && !URL_PATTERN.test(input)) return RULE_MESSAGES.url;
@@ -501,33 +629,116 @@ function normalizeCheckboxChoice(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)}`;
+/**
+* Build 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
+* {@link import('@orkestrel/console').freezeStyle}, so the result is deeply frozen and a caller
+* mutating its own attribute list afterwards cannot reach into a built theme.
+*
+* @param options - The partial theme to merge, or `undefined` for the defaults
+* @returns The resolved, deeply frozen theme every prompt state carries
+*
+* @example
+* ```ts
+* createPromptTheme() // the defaults
+* createPromptTheme({
+* 	icons: { pointer: '=>' },
+* 	roles: { message: { foreground: 'magenta', attributes: ['bold'] } },
+* })
+* ```
+*/
+function createPromptTheme(options) {
+	const icons = {
+		...DEFAULT_PROMPT_THEME.icons,
+		...options?.icons
+	};
+	const roles = { ...DEFAULT_PROMPT_THEME.roles };
+	for (const role of PROMPT_ROLES) {
+		const style = options?.roles?.[role];
+		if (style !== void 0) roles[role] = (0, _orkestrel_console.freezeStyle)(style);
+	}
+	return Object.freeze({
+		icons: Object.freeze(icons),
+		roles: Object.freeze(roles)
+	});
 }
-/** The styled submit line (`✔ message`) — the committed header an interactive prompt shows once resolved. */
-function submitHeader(styler, message) {
-	return `${styler.green(_orkestrel_console.STATUS_ICONS.success)} ${styler.bold(message)}`;
+/**
+* Sanitize text for one single-line display slot. Composes console's {@link stripControls} pass
+* with removal of tab, line feed, and carriage return, so no C0 control or DEL survives.
+*
+* @param text - The text to sanitize for a glyph or hint slot
+* @returns The text with every C0 control character and DEL removed
+*
+* @example
+* ```ts
+* sanitizeDisplayText('Q\rOVERWRITE\nNEXT\tX') // 'QOVERWRITENEXTX'
+* ```
+*/
+function sanitizeDisplayText(text) {
+	return (0, _orkestrel_console.stripControls)(text).replaceAll("	", "").replaceAll("\n", "").replaceAll("\r", "");
+}
+/**
+* Sanitize 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.
+*
+* @param theme - The narrowed theme options a remote prompt supplied
+* @returns The same theme with every supplied glyph sanitized for a single-line display slot
+*/
+function sanitizeThemeIcons(theme) {
+	const icons = theme.icons;
+	if (icons === void 0) return theme;
+	const sanitized = {};
+	for (const [icon, glyph] of Object.entries(icons)) sanitized[icon] = sanitizeDisplayText(glyph);
+	return {
+		...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) {
+	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.
+*
+* @param styler - The console styler that renders each role
+* @param theme - The resolved prompt theme
+* @param message - The prompt's question text
+* @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);
+	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) {
+	return `${styler.render(theme.roles.success, theme.icons.success)} ${styler.render(theme.roles.message, message)}`;
 }
-/** The styled error line (`✖ message`) — appended beneath a prompt view when the last submit failed validation. */
-function errorLine(styler, message) {
-	return `${styler.red(_orkestrel_console.STATUS_ICONS.error)} ${styler.red(message)}`;
+/** The styled error line (`✖ message`) — appended beneath a prompt view when the last submit failed validation, themed by the `error` role. */
+function errorLine(styler, theme, message) {
+	return `${styler.render(theme.roles.error, theme.icons.error)} ${styler.render(theme.roles.error, message)}`;
 }
-/** Build the initial {@link InputState} from {@link InputOptions} — resolving the validator + styler, seeding an empty value. */
+/** Build the initial {@link InputState} from {@link InputOptions} — resolving the validator + styler + theme, seeding an empty value. */
 function createInputState(options) {
 	return {
 		message: options.message,
 		default: options.default ?? "",
 		validator: resolveValidation(options.validate),
 		styler: options.styler ?? (0, _orkestrel_console.createStyler)(),
+		theme: createPromptTheme(options.theme),
 		value: ""
 	};
 }
-/** Render an {@link InputState} as a styled view — the header, the typed value (or dimmed default hint), and any error. */
+/** Render an {@link InputState} as a styled view — the header, the typed value painted by the `content` role (or the default painted as a 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)}`;
+	const shown = state.value.length > 0 ? state.styler.render(state.theme.roles.content, state.value) : state.styler.render(state.theme.roles.hint, state.default);
+	const head = `${promptHeader(state.styler, state.theme, state.message)} ${state.styler.render(state.theme.roles.pointer, state.theme.icons.pointer)} ${shown}`;
+	return state.error === void 0 ? head : `${head}\n${errorLine(state.styler, state.theme, state.error)}`;
 }
 /**
 * Advance an input prompt by one {@link KeyEvent} — the pure `(state, key) → PromptStep<string>`
@@ -561,7 +772,7 @@ function inputReduce(state, key) {
 				...clear,
 				value: answer
 			},
-			view: `${submitHeader(state.styler, state.message)} ${state.styler.dim(answer)}`,
+			view: `${submitHeader(state.styler, state.theme, state.message)} ${state.styler.render(state.theme.roles.hint, answer)}`,
 			status: "submit",
 			value: answer
 		};
@@ -582,21 +793,22 @@ function inputReduce(state, key) {
 		status: "active"
 	};
 }
-/** Build the initial {@link PasswordState} from {@link PasswordOptions} — resolving the validator + styler + mask. */
+/** Build the initial {@link PasswordState} from {@link PasswordOptions} — resolving the validator + styler + theme + mask. */
 function createPasswordState(options) {
 	return {
 		message: options.message,
 		mask: options.mask ?? "*",
 		validator: resolveValidation(options.validate),
 		styler: options.styler ?? (0, _orkestrel_console.createStyler)(),
+		theme: createPromptTheme(options.theme),
 		value: ""
 	};
 }
-/** Render a {@link PasswordState} as a styled view — the header, the value masked to `mask` repeated, and any error. */
+/** Render a {@link PasswordState} as a styled view — the header, the value masked to `mask` repeated and painted by the `content` role, 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)}`;
+	const masked = state.styler.render(state.theme.roles.content, state.mask.repeat(state.value.length));
+	const head = `${promptHeader(state.styler, state.theme, state.message)} ${state.styler.render(state.theme.roles.pointer, state.theme.icons.pointer)} ${masked}`;
+	return state.error === void 0 ? head : `${head}\n${errorLine(state.styler, state.theme, state.error)}`;
 }
 /**
 * Advance a password prompt by one {@link KeyEvent} — the pure `(state, key) → PromptStep<string>`
@@ -626,7 +838,7 @@ function passwordReduce(state, key) {
 		}
 		return {
 			state: clear,
-			view: `${submitHeader(state.styler, state.message)} ${state.styler.dim(state.mask.repeat(state.value.length))}`,
+			view: `${submitHeader(state.styler, state.theme, state.message)} ${state.styler.render(state.theme.roles.hint, state.mask.repeat(state.value.length))}`,
 			status: "submit",
 			value: state.value
 		};
@@ -647,18 +859,26 @@ function passwordReduce(state, key) {
 		status: "active"
 	};
 }
-/** Build the initial {@link ConfirmState} from {@link ConfirmOptions} — defaulting the answer to `false`. */
+/** Build the initial {@link ConfirmState} from {@link ConfirmOptions} — defaulting the answer to `false`, resolving the styler + theme, carrying any hint override. */
 function createConfirmState(options) {
 	return {
 		message: options.message,
 		default: options.default ?? false,
-		styler: options.styler ?? (0, _orkestrel_console.createStyler)()
+		...options.hint !== void 0 ? { hint: options.hint } : {},
+		styler: options.styler ?? (0, _orkestrel_console.createStyler)(),
+		theme: createPromptTheme(options.theme)
 	};
 }
-/** Render a {@link ConfirmState} as a styled view — the header plus a `(Y/n)` hint with the default letter emphasized. */
+/**
+* Render a {@link ConfirmState} as a styled view — the header plus the `(Y/n)` group with the
+* default letter painted by the `selected` role. A supplied `hint` replaces that whole group,
+* parentheses included, painted by the `hint` role.
+*/
 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(")")}`;
+	if (state.hint !== void 0) return hintedHeader(state.styler, state.theme, state.message, state.hint);
+	const head = promptHeader(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>`
@@ -683,29 +903,31 @@ function confirmReduce(state, key) {
 	};
 	return {
 		state,
-		view: `${submitHeader(state.styler, state.message)} ${state.styler.dim(answer ? "yes" : "no")}`,
+		view: `${submitHeader(state.styler, state.theme, state.message)} ${state.styler.render(state.theme.roles.hint, answer ? "yes" : "no")}`,
 		status: "submit",
 		value: answer
 	};
 }
-/** Build the initial {@link SelectState} from {@link SelectOptions} — normalizing choices and pre-focusing the default. */
+/** Build the initial {@link SelectState} from {@link SelectOptions} — normalizing choices, resolving the styler + theme, carrying any hint, 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,
+		...options.hint !== void 0 ? { hint: options.hint } : {},
 		styler: options.styler ?? (0, _orkestrel_console.createStyler)(),
+		theme: createPromptTheme(options.theme),
 		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. */
+/** Render a {@link SelectState} as a MULTI-LINE styled view — the header (plus any hint) 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 `${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.name) : state.styler.render(state.theme.roles.content, choice.name)}${choice.description === void 0 ? "" : `  ${state.styler.render(state.theme.roles.description, choice.description)}`}`;
 	});
-	return [promptHeader(state.styler, state.message), ...lines].join("\n");
+	return [hintedHeader(state.styler, state.theme, state.message, state.hint), ...lines].join("\n");
 }
 /**
 * Advance a select prompt by one {@link KeyEvent} — the pure `(state, key) → PromptStep<string>`
@@ -752,7 +974,7 @@ function selectReduce(state, key) {
 		const value = choice?.value ?? "";
 		return {
 			state,
-			view: `${submitHeader(state.styler, state.message)} ${state.styler.dim(choice?.name ?? "")}`,
+			view: `${submitHeader(state.styler, state.theme, state.message)} ${state.styler.render(state.theme.roles.hint, choice?.name ?? "")}`,
 			status: "submit",
 			value
 		};
@@ -763,7 +985,7 @@ function selectReduce(state, key) {
 		status: "active"
 	};
 }
-/** Build the initial {@link CheckboxState} from {@link CheckboxOptions} — normalizing choices, seeding the checked set, carrying min/max. */
+/** Build the initial {@link CheckboxState} from {@link CheckboxOptions} — normalizing choices, resolving the styler + theme, carrying any hint, seeding the checked set, carrying min/max. */
 function createCheckboxState(options) {
 	const choices = options.choices.map(normalizeCheckboxChoice);
 	const checked = choices.reduce((indices, choice, index) => {
@@ -773,27 +995,29 @@ function createCheckboxState(options) {
 	return {
 		message: options.message,
 		choices,
+		...options.hint !== void 0 ? { hint: options.hint } : {},
 		styler: options.styler ?? (0, _orkestrel_console.createStyler)(),
+		theme: createPromptTheme(options.theme),
 		focused: 0,
 		checked,
 		...options.min !== void 0 ? { min: options.min } : {},
 		...options.max !== void 0 ? { 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. */
+/** Render a {@link CheckboxState} as a MULTI-LINE styled view — the header (plus any hint), 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)}`}`;
+		return `${active ? state.styler.render(state.theme.roles.pointer, state.theme.icons.pointer) : " "} ${ticked ? state.styler.render(state.theme.roles.selected, state.theme.icons.checked) : state.styler.render(state.theme.roles.muted, state.theme.icons.unchecked)} ${active ? state.styler.render(state.theme.roles.focus, choice.name) : state.styler.render(state.theme.roles.content, choice.name)}${choice.description === void 0 ? "" : `  ${state.styler.render(state.theme.roles.description, choice.description)}`}`;
 	});
-	const summary = state.styler.dim(`${state.checked.length} selected`);
+	const summary = state.styler.render(state.theme.roles.hint, `${state.checked.length} selected`);
 	const body = [
-		promptHeader(state.styler, state.message),
+		hintedHeader(state.styler, state.theme, state.message, state.hint),
 		...lines,
 		summary
 	].join("\n");
-	return state.error === void 0 ? body : `${body}\n${errorLine(state.styler, state.error)}`;
+	return state.error === void 0 ? body : `${body}\n${errorLine(state.styler, state.theme, state.error)}`;
 }
 /**
 * Advance a checkbox prompt by one {@link KeyEvent} — the pure
@@ -862,7 +1086,7 @@ function checkboxReduce(state, key) {
 		const summary = ordered.map((index) => state.choices[index]?.name).filter((name) => name !== void 0).join(", ");
 		return {
 			state: clear,
-			view: `${submitHeader(state.styler, state.message)} ${state.styler.dim(summary)}`,
+			view: `${submitHeader(state.styler, state.theme, state.message)} ${state.styler.render(state.theme.roles.hint, summary)}`,
 			status: "submit",
 			value: values
 		};
@@ -882,21 +1106,29 @@ 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. */
+/** Build the initial {@link EditorState} from {@link EditorOptions} — resolving the validator + styler + theme, carrying any hint override, seeding empty lines. */
 function createEditorState(options) {
 	return {
 		message: options.message,
 		default: options.default ?? "",
+		...options.hint !== void 0 ? { hint: options.hint } : {},
 		validator: resolveValidation(options.validate),
 		styler: options.styler ?? (0, _orkestrel_console.createStyler)(),
+		theme: createPromptTheme(options.theme),
 		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. */
+/**
+* Render an {@link EditorState} as a MULTI-LINE styled view — the header with its finish hint, the
+* committed and in-progress lines painted by the `content` role, and any error. A supplied `hint`
+* replaces `(Ctrl+D to finish)` in full; the finish key stays ctrl-d.
+*/
 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)}`;
+	const head = hintedHeader(state.styler, state.theme, state.message, state.hint ?? "(Ctrl+D to finish)");
+	const pointer = state.styler.render(state.theme.roles.pointer, state.theme.icons.pointer);
+	const view = [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");
+	return state.error === void 0 ? view : `${view}\n${errorLine(state.styler, state.theme, state.error)}`;
 }
 /**
 * Advance an editor prompt by one {@link KeyEvent} — the pure `(state, key) → PromptStep<string>`
@@ -930,7 +1162,7 @@ function editorReduce(state, key) {
 		}
 		return {
 			state: clear,
-			view: `${submitHeader(state.styler, state.message)} ${state.styler.dim(`${String(lines.length)} line${lines.length === 1 ? "" : "s"}`)}`,
+			view: `${submitHeader(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
 		};
@@ -980,7 +1212,8 @@ function editLine(value, key) {
 * 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`
+* `default` / `mask` / `min` / `max` / `hint` / `theme`. This is WHY T-a's validation is
+* rules-as-data, and why a theme is data too: a `Validator`
 * FUNCTION can't be serialized, but its declarative rules can — the client rebuilds the validator
 * from them via {@link resolveValidation}.
 *
@@ -1114,6 +1347,13 @@ function sanitizeChoiceLabels(choices) {
 * §14-narrowed, never an `as`; the validator rebuilt from rules via {@link reconstructValidationRules}),
 * then calls the matching prompt form and returns its resolved value.
 *
+* @remarks
+* `theme` and `hint` are plain data, so they cross the wire with the rest of the options bag and
+* are reconstructed here for every form that accepts them: the theme is narrowed by
+* {@link import('./validators.js').isPromptThemeOptions} (an off-shape theme is dropped, leaving
+* the defaults), then every glyph and hint is passed through {@link sanitizeDisplayText}. Choice
+* labels use the stream-safe {@link sanitizeChoiceLabels} treatment instead.
+*
 * @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)
@@ -1122,13 +1362,18 @@ function dispatchPendingPrompt(terminal, pending) {
 	const options = pending.options;
 	const validate = reconstructValidationRules(options.validate);
 	const message = (0, _orkestrel_console.stripControls)(pending.message);
+	const supplied = resolveOption(options, "theme", isPromptThemeOptions);
+	const theme = supplied === void 0 ? void 0 : sanitizeThemeIcons(supplied);
+	const raw = resolveOption(options, "hint", _orkestrel_contract.isString);
+	const hint = raw === void 0 ? void 0 : sanitizeDisplayText(raw);
 	switch (pending.form) {
 		case "input": {
 			const value = resolveOption(options, "default", _orkestrel_contract.isString);
 			return terminal.input({
 				message,
 				...value !== void 0 ? { default: (0, _orkestrel_console.stripControls)(value) } : {},
-				...validate !== void 0 ? { validate } : {}
+				...validate !== void 0 ? { validate } : {},
+				...theme !== void 0 ? { theme } : {}
 			});
 		}
 		case "password": {
@@ -1136,14 +1381,17 @@ function dispatchPendingPrompt(terminal, pending) {
 			return terminal.password({
 				message,
 				...value !== void 0 ? { mask: (0, _orkestrel_console.stripControls)(value) } : {},
-				...validate !== void 0 ? { validate } : {}
+				...validate !== void 0 ? { validate } : {},
+				...theme !== void 0 ? { theme } : {}
 			});
 		}
 		case "confirm": {
 			const value = resolveOption(options, "default", _orkestrel_contract.isBoolean);
 			return terminal.confirm({
 				message,
-				...value !== void 0 ? { default: value } : {}
+				...value !== void 0 ? { default: value } : {},
+				...hint !== void 0 ? { hint } : {},
+				...theme !== void 0 ? { theme } : {}
 			});
 		}
 		case "select": {
@@ -1151,7 +1399,9 @@ function dispatchPendingPrompt(terminal, pending) {
 			return terminal.select({
 				message,
 				choices: sanitizeChoiceLabels(resolveChoices(options, isPromptChoice)),
-				...value !== void 0 ? { default: (0, _orkestrel_console.stripControls)(value) } : {}
+				...value !== void 0 ? { default: (0, _orkestrel_console.stripControls)(value) } : {},
+				...hint !== void 0 ? { hint } : {},
+				...theme !== void 0 ? { theme } : {}
 			});
 		}
 		case "checkbox": {
@@ -1161,7 +1411,9 @@ function dispatchPendingPrompt(terminal, pending) {
 				message,
 				choices: sanitizeChoiceLabels(resolveChoices(options, isCheckboxChoice)),
 				...min !== void 0 ? { min } : {},
-				...max !== void 0 ? { max } : {}
+				...max !== void 0 ? { max } : {},
+				...hint !== void 0 ? { hint } : {},
+				...theme !== void 0 ? { theme } : {}
 			});
 		}
 		case "editor": {
@@ -1169,7 +1421,9 @@ function dispatchPendingPrompt(terminal, pending) {
 			return terminal.editor({
 				message,
 				...value !== void 0 ? { default: (0, _orkestrel_console.stripControls)(value) } : {},
-				...validate !== void 0 ? { validate } : {}
+				...validate !== void 0 ? { validate } : {},
+				...hint !== void 0 ? { hint } : {},
+				...theme !== void 0 ? { theme } : {}
 			});
 		}
 	}
@@ -1198,19 +1452,6 @@ 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.
 *
@@ -1281,9 +1522,9 @@ function isAnswerPayload(value) {
 *   ({@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.
+*   the validator resolved from the original `validate` rules. A rejected answer returns a failure
+*   `Result` with error `'rejected'` 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.
@@ -1632,12 +1873,12 @@ var PromptClient = class {
 	}
 	async #handle(event) {
 		if (event.event === SSE_EVENTS.pending) {
-			const parsed = parseWireJSON(event.data);
+			const parsed = (0, _orkestrel_contract.parseJSON)(event.data);
 			if (isPendingPrompt(parsed) && !this.#seen.has(parsed.id)) await this.#dispatch(parsed.id, parsed);
 			return;
 		}
 		if (event.event === SSE_EVENTS.expire) {
-			const parsed = parseWireJSON(event.data);
+			const parsed = (0, _orkestrel_contract.parseJSON)(event.data);
 			if ((0, _orkestrel_contract.isRecord)(parsed) && (0, _orkestrel_contract.isString)(parsed.id)) {
 				this.#seen.delete(parsed.id);
 				this.#emitter.emit("expire", parsed.id);
@@ -1715,9 +1956,9 @@ 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 or a batch (§9.2, array overload FIRST), destroying
-*   each broker (which expires every prompt still parked on it). `clear` drops all; `destroy` is
-*   idempotent.
+* - **Removal.** `remove` drops one endpoint, a batch (§9.2, array overload FIRST), or every
+*   endpoint when called without an argument. It destroys each broker, which expires every prompt
+*   still parked on it. `destroy` is idempotent.
 *
 * @example
 * ```ts
@@ -1856,6 +2097,10 @@ var TerminalManager = class {
 		return true;
 	}
 	remove(names) {
+		if (names === void 0) {
+			for (const name of [...this.#terminals.keys()]) this.#removeOne(name);
+			return;
+		}
 		if ((0, _orkestrel_contract.isArray)(names)) {
 			let removed = false;
 			for (const name of names) if (this.#removeOne(name)) removed = true;
@@ -1863,13 +2108,10 @@ var TerminalManager = class {
 		}
 		return this.#removeOne(names);
 	}
-	clear() {
-		for (const name of [...this.#terminals.keys()]) this.#removeOne(name);
-	}
 	destroy() {
 		if (this.#destroyed) return;
 		this.#destroyed = true;
-		this.clear();
+		this.remove();
 		this.#emitter.destroy();
 	}
 	#createPendingListener() {
@@ -2174,11 +2416,11 @@ exports.CTRL_D = CTRL_D;
 exports.CTRL_E = CTRL_E;
 exports.CTRL_U = CTRL_U;
 exports.DEFAULT_MASK = DEFAULT_MASK;
+exports.DEFAULT_PROMPT_THEME = DEFAULT_PROMPT_THEME;
 exports.DEFAULT_PROMPT_TIMEOUT_MS = DEFAULT_PROMPT_TIMEOUT_MS;
 exports.DEFAULT_RECONNECT_DELAY_MS = DEFAULT_RECONNECT_DELAY_MS;
 exports.DELETE = DELETE;
 exports.DatabaseTerminalStore = DatabaseTerminalStore;
-exports.EMAIL_PATTERN = EMAIL_PATTERN;
 exports.ESCAPE = ESCAPE;
 exports.HEADER_TOKEN = HEADER_TOKEN;
 exports.INTEGER_PATTERN = INTEGER_PATTERN;
@@ -2188,6 +2430,7 @@ exports.MemoryTerminalStore = MemoryTerminalStore;
 exports.NEWLINE = NEWLINE;
 exports.NUMERIC_PATTERN = NUMERIC_PATTERN;
 exports.PROMPT_ICONS = PROMPT_ICONS;
+exports.PROMPT_ROLES = PROMPT_ROLES;
 exports.Prompt = Prompt;
 exports.PromptClient = PromptClient;
 exports.RETURN = RETURN;
@@ -2216,6 +2459,7 @@ exports.createMemoryTerminalStore = createMemoryTerminalStore;
 exports.createPasswordState = createPasswordState;
 exports.createPrompt = createPrompt;
 exports.createPromptClient = createPromptClient;
+exports.createPromptTheme = createPromptTheme;
 exports.createSelectState = createSelectState;
 exports.createTerminalManager = createTerminalManager;
 exports.defaultTimer = defaultTimer;
@@ -2227,6 +2471,7 @@ exports.errorLine = errorLine;
 exports.evaluateRule = evaluateRule;
 exports.gateSelection = gateSelection;
 exports.globalFetch = globalFetch;
+exports.hintedHeader = hintedHeader;
 exports.inputReduce = inputReduce;
 exports.inputView = inputView;
 exports.isAbortError = isAbortError;
@@ -2237,13 +2482,14 @@ exports.isPendingPrompt = isPendingPrompt;
 exports.isPendingPromptStatus = isPendingPromptStatus;
 exports.isPrintable = isPrintable;
 exports.isPromptChoice = isPromptChoice;
+exports.isPromptThemeOptions = isPromptThemeOptions;
 exports.isPromptType = isPromptType;
+exports.isStyle = isStyle;
 exports.isTerminalError = isTerminalError;
 exports.isTerminalSnapshot = isTerminalSnapshot;
 exports.normalizeCheckboxChoice = normalizeCheckboxChoice;
 exports.normalizeChoice = normalizeChoice;
 exports.parseKey = parseKey;
-exports.parseWireJSON = parseWireJSON;
 exports.passing = passing;
 exports.passwordReduce = passwordReduce;
 exports.passwordView = passwordView;
@@ -2253,6 +2499,8 @@ exports.resolveChoices = resolveChoices;
 exports.resolveOption = resolveOption;
 exports.resolveValidation = resolveValidation;
 exports.sanitizeChoiceLabels = sanitizeChoiceLabels;
+exports.sanitizeDisplayText = sanitizeDisplayText;
+exports.sanitizeThemeIcons = sanitizeThemeIcons;
 exports.selectReduce = selectReduce;
 exports.selectView = selectView;
 exports.serializeChoices = serializeChoices;