@optique/core 1.3.0-dev.2542 → 1.3.0-dev.2558

package/dist/facade.cjs

@@ -1,6 +1,6 @@
 const require_internal_annotations = require('./internal/annotations.cjs');
-const require_displaywidth = require('./displaywidth.cjs');
 const require_terminal_internal = require('./terminal-internal.cjs');
+const require_text_layout = require('./text-layout.cjs');
 const require_message = require('./message.cjs');
 const require_message_renderer = require('./message-renderer.cjs');
 const require_validate = require('./validate.cjs');
@@ -517,27 +517,19 @@ function classifyParseFailure(failure, helpOptionNames, helpCommandNames, versio
 * @since 0.6.0
 */
 function handleCompletion(completionArgs, programName, parser, completionParser, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, termWidth, completionCommandDisplayName, completionOptionDisplayName, isOptionMode, sectionOrder, showUsage, rootOptionSuggestions = [], messageFormatter, theme) {
-	const formatMessage = require_message_renderer.resolveMessageFormatter({
-		messageFormatter,
-		theme
-	});
-	const errorLabel = () => require_terminal_internal.renderTerminalTerm({
-		type: "errorLabel",
-		label: "Error:"
-	}, theme, colors) + " ";
 	const shellName = completionArgs[0] || "";
 	const args = completionArgs.slice(1);
 	const callOnError = (code, error) => onError(code, error);
 	const callOnCompletion = (code) => onCompletion(code);
 	if (!shellName) {
 		const error = require_message.message`Missing shell name for completion.`;
-		const prefix = errorLabel();
-		stderr(`${prefix}${formatMessage(error, {
+		stderr(require_message_renderer.renderErrorMessage(error, {
+			messageFormatter,
+			theme,
 			colors,
 			quotes: !colors,
-			maxWidth,
-			initialWidth: require_displaywidth.getDisplayWidth(prefix.split("\n").at(-1) ?? "")
-		})}\n`);
+			maxWidth
+		}) + "\n");
 		if (completionParser) {
 			const displayName = isOptionMode ? completionOptionDisplayName ?? "--completion" : completionCommandDisplayName ?? "completion";
 			const doc = require_internal_parser.getDocPage(completionParser, [displayName]);
@@ -565,13 +557,13 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 			available.push(require_message.value(name));
 		}
 		const error = require_message.message`Unsupported shell ${shellName}. Available shells: ${available}.`;
-		const prefix = errorLabel();
-		stderr(`${prefix}${formatMessage(error, {
+		stderr(require_message_renderer.renderErrorMessage(error, {
+			messageFormatter,
+			theme,
 			colors,
 			quotes: !colors,
-			maxWidth,
-			initialWidth: require_displaywidth.getDisplayWidth(prefix.split("\n").at(-1) ?? "")
-		})}`);
+			maxWidth
+		}));
 		return require_mode_dispatch.dispatchByMode(parser.mode, () => {
 			const result = callOnError(1, error);
 			if (result instanceof Promise) throw new RunParserError("Synchronous parser returned async result.");
@@ -882,21 +874,13 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 	const { colors, messageFormatter, theme, maxWidth, termWidth, showDefault, showChoices, sectionOrder, showUsage, usageLine, commandList = "recursive", aboveError = "usage", onError = () => {
 		throw new RunParserError("Failed to parse command line arguments.");
 	}, stderr = console.error, stdout = console.log, brief, description, examples, author, bugs, footer } = options;
-	const formatMessage = require_message_renderer.resolveMessageFormatter({
-		messageFormatter,
-		theme
-	});
-	const errorLabel = () => require_terminal_internal.renderTerminalTerm({
-		type: "errorLabel",
-		label: "Error:"
-	}, theme, colors) + " ";
 	let usagePrefix;
-	const usageLabel = () => usagePrefix ??= require_terminal_internal.renderTerminalTerm({
+	const usageLabel = () => usagePrefix ??= require_text_layout.spaceAfterLabel(require_terminal_internal.renderTerminalTerm({
 		type: "label",
 		label: "Usage:",
 		kind: "usageSummary"
-	}, theme, colors) + " ";
-	const usageLabelWidth = () => require_displaywidth.getDisplayWidth(usageLabel().split("\n").at(-1) ?? "");
+	}, theme, colors));
+	const usageLabelWidth = () => require_text_layout.measureText(usageLabel()).lastLineWidth;
 	const norm = (c) => c === true ? {} : c;
 	const helpCommandConfig = norm(options.help?.command);
 	const helpOptionConfig = norm(options.help?.option);
@@ -1057,14 +1041,13 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 						maxWidth: maxWidth == null ? void 0 : maxWidth - usageLabelWidth(),
 						expandCommands: true
 					}), usageLabelWidth())}`);
-					const prefix = errorLabel();
-					const errorMessage = formatMessage(validationError, {
-						initialWidth: require_displaywidth.getDisplayWidth(prefix.split("\n").at(-1) ?? ""),
-						maxWidth,
+					stderr(require_message_renderer.renderErrorMessage(validationError, {
+						messageFormatter,
+						theme,
 						colors,
-						quotes: !colors
-					});
-					stderr(`${prefix}${errorMessage}`);
+						quotes: !colors,
+						maxWidth
+					}));
 					return onError(1, validationError);
 				};
 				const displayHelp = (doc) => {
@@ -1177,14 +1160,13 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 						maxWidth: maxWidth == null ? void 0 : maxWidth - usageLabelWidth(),
 						expandCommands: true
 					}), usageLabelWidth())}`);
-					const prefix = errorLabel();
-					const errorMessage = formatMessage(classified.error, {
-						initialWidth: require_displaywidth.getDisplayWidth(prefix.split("\n").at(-1) ?? ""),
-						maxWidth,
+					stderr(require_message_renderer.renderErrorMessage(classified.error, {
+						messageFormatter,
+						theme,
 						colors,
-						quotes: !colors
-					});
-					stderr(`${prefix}${errorMessage}`);
+						quotes: !colors,
+						maxWidth
+					}));
 					return onError(1, classified.error);
 				};
 				if (aboveError === "help") {

package/dist/facade.js

@@ -1,8 +1,8 @@
 import { injectAnnotations } from "./internal/annotations.js";
-import { getDisplayWidth } from "./displaywidth.js";
 import { renderTerminalTerm } from "./terminal-internal.js";
+import { measureText, spaceAfterLabel } from "./text-layout.js";
 import { commandLine, lineBreak, message, optionName, text, value } from "./message.js";
-import { resolveMessageFormatter } from "./message-renderer.js";
+import { renderErrorMessage } from "./message-renderer.js";
 import { validateCommandNames, validateContextIds, validateMetaNameCollisions, validateOptionNames, validateProgramName } from "./validate.js";
 import { cloneUsage, formatUsage, isSuggestionHidden, normalizeUsage } from "./usage.js";
 import { formatDocPage } from "./doc.js";
@@ -517,27 +517,19 @@ function classifyParseFailure(failure, helpOptionNames, helpCommandNames, versio
 * @since 0.6.0
 */
 function handleCompletion(completionArgs, programName, parser, completionParser, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, termWidth, completionCommandDisplayName, completionOptionDisplayName, isOptionMode, sectionOrder, showUsage, rootOptionSuggestions = [], messageFormatter, theme) {
-	const formatMessage = resolveMessageFormatter({
-		messageFormatter,
-		theme
-	});
-	const errorLabel = () => renderTerminalTerm({
-		type: "errorLabel",
-		label: "Error:"
-	}, theme, colors) + " ";
 	const shellName = completionArgs[0] || "";
 	const args = completionArgs.slice(1);
 	const callOnError = (code, error) => onError(code, error);
 	const callOnCompletion = (code) => onCompletion(code);
 	if (!shellName) {
 		const error = message`Missing shell name for completion.`;
-		const prefix = errorLabel();
-		stderr(`${prefix}${formatMessage(error, {
+		stderr(renderErrorMessage(error, {
+			messageFormatter,
+			theme,
 			colors,
 			quotes: !colors,
-			maxWidth,
-			initialWidth: getDisplayWidth(prefix.split("\n").at(-1) ?? "")
-		})}\n`);
+			maxWidth
+		}) + "\n");
 		if (completionParser) {
 			const displayName = isOptionMode ? completionOptionDisplayName ?? "--completion" : completionCommandDisplayName ?? "completion";
 			const doc = getDocPage(completionParser, [displayName]);
@@ -565,13 +557,13 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 			available.push(value(name));
 		}
 		const error = message`Unsupported shell ${shellName}. Available shells: ${available}.`;
-		const prefix = errorLabel();
-		stderr(`${prefix}${formatMessage(error, {
+		stderr(renderErrorMessage(error, {
+			messageFormatter,
+			theme,
 			colors,
 			quotes: !colors,
-			maxWidth,
-			initialWidth: getDisplayWidth(prefix.split("\n").at(-1) ?? "")
-		})}`);
+			maxWidth
+		}));
 		return dispatchByMode(parser.mode, () => {
 			const result = callOnError(1, error);
 			if (result instanceof Promise) throw new RunParserError("Synchronous parser returned async result.");
@@ -882,21 +874,13 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 	const { colors, messageFormatter, theme, maxWidth, termWidth, showDefault, showChoices, sectionOrder, showUsage, usageLine, commandList = "recursive", aboveError = "usage", onError = () => {
 		throw new RunParserError("Failed to parse command line arguments.");
 	}, stderr = console.error, stdout = console.log, brief, description, examples, author, bugs, footer } = options;
-	const formatMessage = resolveMessageFormatter({
-		messageFormatter,
-		theme
-	});
-	const errorLabel = () => renderTerminalTerm({
-		type: "errorLabel",
-		label: "Error:"
-	}, theme, colors) + " ";
 	let usagePrefix;
-	const usageLabel = () => usagePrefix ??= renderTerminalTerm({
+	const usageLabel = () => usagePrefix ??= spaceAfterLabel(renderTerminalTerm({
 		type: "label",
 		label: "Usage:",
 		kind: "usageSummary"
-	}, theme, colors) + " ";
-	const usageLabelWidth = () => getDisplayWidth(usageLabel().split("\n").at(-1) ?? "");
+	}, theme, colors));
+	const usageLabelWidth = () => measureText(usageLabel()).lastLineWidth;
 	const norm = (c) => c === true ? {} : c;
 	const helpCommandConfig = norm(options.help?.command);
 	const helpOptionConfig = norm(options.help?.option);
@@ -1057,14 +1041,13 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 						maxWidth: maxWidth == null ? void 0 : maxWidth - usageLabelWidth(),
 						expandCommands: true
 					}), usageLabelWidth())}`);
-					const prefix = errorLabel();
-					const errorMessage = formatMessage(validationError, {
-						initialWidth: getDisplayWidth(prefix.split("\n").at(-1) ?? ""),
-						maxWidth,
+					stderr(renderErrorMessage(validationError, {
+						messageFormatter,
+						theme,
 						colors,
-						quotes: !colors
-					});
-					stderr(`${prefix}${errorMessage}`);
+						quotes: !colors,
+						maxWidth
+					}));
 					return onError(1, validationError);
 				};
 				const displayHelp = (doc) => {
@@ -1177,14 +1160,13 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 						maxWidth: maxWidth == null ? void 0 : maxWidth - usageLabelWidth(),
 						expandCommands: true
 					}), usageLabelWidth())}`);
-					const prefix = errorLabel();
-					const errorMessage = formatMessage(classified.error, {
-						initialWidth: getDisplayWidth(prefix.split("\n").at(-1) ?? ""),
-						maxWidth,
+					stderr(renderErrorMessage(classified.error, {
+						messageFormatter,
+						theme,
 						colors,
-						quotes: !colors
-					});
-					stderr(`${prefix}${errorMessage}`);
+						quotes: !colors,
+						maxWidth
+					}));
 					return onError(1, classified.error);
 				};
 				if (aboveError === "help") {

package/dist/internal/terminal.cjs

@@ -1,7 +1,12 @@
 const require_displaywidth = require('../displaywidth.cjs');
 const require_terminal_internal = require('../terminal-internal.cjs');
+const require_text_layout = require('../text-layout.cjs');
 const require_message_renderer = require('../message-renderer.cjs');
 
 exports.getDisplayWidth = require_displaywidth.getDisplayWidth;
+exports.measureText = require_text_layout.measureText;
+exports.placeText = require_text_layout.placeText;
+exports.renderErrorMessage = require_message_renderer.renderErrorMessage;
 exports.renderTerminalTerm = require_terminal_internal.renderTerminalTerm;
-exports.resolveMessageFormatter = require_message_renderer.resolveMessageFormatter;
+exports.resolveMessageFormatter = require_message_renderer.resolveMessageFormatter;
+exports.spaceAfterLabel = require_text_layout.spaceAfterLabel;

package/dist/internal/terminal.d.cts

@@ -1,4 +1,5 @@
 import { getDisplayWidth } from "../displaywidth.cjs";
-import { resolveMessageFormatter } from "../message-renderer.cjs";
+import { renderErrorMessage, resolveMessageFormatter } from "../message-renderer.cjs";
 import { renderTerminalTerm } from "../terminal-internal.cjs";
-export { getDisplayWidth, renderTerminalTerm, resolveMessageFormatter };
+import { measureText, placeText, spaceAfterLabel } from "../text-layout.cjs";
+export { getDisplayWidth, measureText, placeText, renderErrorMessage, renderTerminalTerm, resolveMessageFormatter, spaceAfterLabel };

package/dist/internal/terminal.d.ts

@@ -1,4 +1,5 @@
 import { getDisplayWidth } from "../displaywidth.js";
-import { resolveMessageFormatter } from "../message-renderer.js";
+import { renderErrorMessage, resolveMessageFormatter } from "../message-renderer.js";
 import { renderTerminalTerm } from "../terminal-internal.js";
-export { getDisplayWidth, renderTerminalTerm, resolveMessageFormatter };
+import { measureText, placeText, spaceAfterLabel } from "../text-layout.js";
+export { getDisplayWidth, measureText, placeText, renderErrorMessage, renderTerminalTerm, resolveMessageFormatter, spaceAfterLabel };

package/dist/internal/terminal.js

@@ -1,5 +1,6 @@
 import { getDisplayWidth } from "../displaywidth.js";
 import { renderTerminalTerm } from "../terminal-internal.js";
-import { resolveMessageFormatter } from "../message-renderer.js";
+import { measureText, placeText, spaceAfterLabel } from "../text-layout.js";
+import { renderErrorMessage, resolveMessageFormatter } from "../message-renderer.js";
 
-export { getDisplayWidth, renderTerminalTerm, resolveMessageFormatter };
+export { getDisplayWidth, measureText, placeText, renderErrorMessage, renderTerminalTerm, resolveMessageFormatter, spaceAfterLabel };

package/dist/message-renderer.cjs

@@ -1,4 +1,6 @@
 const require_message_registry = require('./message-registry.cjs');
+const require_terminal_internal = require('./terminal-internal.cjs');
+const require_text_layout = require('./text-layout.cjs');
 const require_message = require('./message.cjs');
 
 //#region src/message-renderer.ts
@@ -21,6 +23,38 @@ function resolveMessageFormatter(options) {
 		});
 	};
 }
+/**
+* Assembles a themed error prefix and a message at one layout boundary.
+* Callers own streams, trailing newlines, and the default quoting policy.
+* Opaque formatter output is appended unchanged, including empty output.
+* @param message The original, unprefixed error message.
+* @param options Theme, formatter, and physical-line layout options.
+* @returns The prefixed message without an added trailing newline.
+* @throws {TypeError} If initialWidth is not a finite integer.
+* @throws {RangeError} If initialWidth is negative or a theme color is invalid.
+* @internal
+*/
+function renderErrorMessage(message, options = {}) {
+	const occupied = options.initialWidth ?? 0;
+	if (!Number.isFinite(occupied) || !Number.isInteger(occupied)) throw new TypeError("Initial width must be a finite integer.");
+	if (occupied < 0) throw new RangeError("Initial width must be nonnegative.");
+	const colors = options.colors;
+	const prefix = require_text_layout.placeText(require_text_layout.spaceAfterLabel(require_terminal_internal.renderTerminalTerm({
+		type: "errorLabel",
+		label: "Error:"
+	}, options.theme, typeof colors === "object" ? true : colors, void 0, void 0, typeof colors === "object" ? colors.resetSuffix : void 0)), {
+		line: "",
+		column: occupied
+	}, options.maxWidth);
+	const formatted = resolveMessageFormatter(options)(message, {
+		colors,
+		quotes: options.quotes,
+		maxWidth: options.maxWidth,
+		initialWidth: prefix.cursor.column
+	});
+	return prefix.text + formatted;
+}
 
 //#endregion
+exports.renderErrorMessage = renderErrorMessage;
 exports.resolveMessageFormatter = resolveMessageFormatter;

package/dist/message-renderer.d.cts

@@ -15,5 +15,20 @@ declare function resolveMessageFormatter(options: {
   readonly messageFormatter?: MessageFormatter;
   readonly theme?: TerminalTheme;
 }): (message: Message, options?: MessageFormatOptions, ambient?: TerminalStyle) => string;
+/**
+ * Assembles a themed error prefix and a message at one layout boundary.
+ * Callers own streams, trailing newlines, and the default quoting policy.
+ * Opaque formatter output is appended unchanged, including empty output.
+ * @param message The original, unprefixed error message.
+ * @param options Theme, formatter, and physical-line layout options.
+ * @returns The prefixed message without an added trailing newline.
+ * @throws {TypeError} If initialWidth is not a finite integer.
+ * @throws {RangeError} If initialWidth is negative or a theme color is invalid.
+ * @internal
+ */
+declare function renderErrorMessage(message: Message, options?: MessageFormatOptions & {
+  readonly theme?: TerminalTheme;
+  readonly messageFormatter?: MessageFormatter;
+}): string;
 //#endregion
-export { resolveMessageFormatter };
+export { renderErrorMessage, resolveMessageFormatter };

package/dist/message-renderer.d.ts

@@ -15,5 +15,20 @@ declare function resolveMessageFormatter(options: {
   readonly messageFormatter?: MessageFormatter;
   readonly theme?: TerminalTheme;
 }): (message: Message, options?: MessageFormatOptions, ambient?: TerminalStyle) => string;
+/**
+ * Assembles a themed error prefix and a message at one layout boundary.
+ * Callers own streams, trailing newlines, and the default quoting policy.
+ * Opaque formatter output is appended unchanged, including empty output.
+ * @param message The original, unprefixed error message.
+ * @param options Theme, formatter, and physical-line layout options.
+ * @returns The prefixed message without an added trailing newline.
+ * @throws {TypeError} If initialWidth is not a finite integer.
+ * @throws {RangeError} If initialWidth is negative or a theme color is invalid.
+ * @internal
+ */
+declare function renderErrorMessage(message: Message, options?: MessageFormatOptions & {
+  readonly theme?: TerminalTheme;
+  readonly messageFormatter?: MessageFormatter;
+}): string;
 //#endregion
-export { resolveMessageFormatter };
+export { renderErrorMessage, resolveMessageFormatter };

package/dist/message-renderer.js

@@ -1,4 +1,6 @@
 import { messageRenderers } from "./message-registry.js";
+import { renderTerminalTerm } from "./terminal-internal.js";
+import { placeText, spaceAfterLabel } from "./text-layout.js";
 import { createMessageFormatter, formatMessage } from "./message.js";
 
 //#region src/message-renderer.ts
@@ -21,6 +23,37 @@ function resolveMessageFormatter(options) {
 		});
 	};
 }
+/**
+* Assembles a themed error prefix and a message at one layout boundary.
+* Callers own streams, trailing newlines, and the default quoting policy.
+* Opaque formatter output is appended unchanged, including empty output.
+* @param message The original, unprefixed error message.
+* @param options Theme, formatter, and physical-line layout options.
+* @returns The prefixed message without an added trailing newline.
+* @throws {TypeError} If initialWidth is not a finite integer.
+* @throws {RangeError} If initialWidth is negative or a theme color is invalid.
+* @internal
+*/
+function renderErrorMessage(message, options = {}) {
+	const occupied = options.initialWidth ?? 0;
+	if (!Number.isFinite(occupied) || !Number.isInteger(occupied)) throw new TypeError("Initial width must be a finite integer.");
+	if (occupied < 0) throw new RangeError("Initial width must be nonnegative.");
+	const colors = options.colors;
+	const prefix = placeText(spaceAfterLabel(renderTerminalTerm({
+		type: "errorLabel",
+		label: "Error:"
+	}, options.theme, typeof colors === "object" ? true : colors, void 0, void 0, typeof colors === "object" ? colors.resetSuffix : void 0)), {
+		line: "",
+		column: occupied
+	}, options.maxWidth);
+	const formatted = resolveMessageFormatter(options)(message, {
+		colors,
+		quotes: options.quotes,
+		maxWidth: options.maxWidth,
+		initialWidth: prefix.cursor.column
+	});
+	return prefix.text + formatted;
+}
 
 //#endregion
-export { resolveMessageFormatter };
+export { renderErrorMessage, resolveMessageFormatter };

package/dist/terminal-internal.cjs

@@ -17,11 +17,29 @@ function valuesFormatter(theme) {
 		children: [require_terminal.defaultTerminalTheme.values(term, context)]
 	});
 }
+/** Default callback identity survives any number of per-pass caches. */
+const defaultFormatters = new WeakSet(Object.values(require_terminal.defaultTerminalTheme).filter((value) => typeof value === "function"));
 function formatTerminalTerm(term, theme = {}, quotes = false, usage) {
+	return formatTerminalLeaf(term, theme, quotes, usage).fragment;
+}
+/**
+* Renders a semantic leaf and records the selected callback's provenance.
+* @param term The semantic leaf to render.
+* @param theme The optional role overrides.
+* @param quotes Whether values should use their quoted representation.
+* @param usage The leaf's position within a usage expression.
+* @returns The fragment and whether its callback has default origin.
+* @throws {TypeError} If the term is invalid or is a message-level hard break.
+* @internal
+*/
+function formatTerminalLeaf(term, theme = {}, quotes = false, usage) {
 	const quote = (s) => quotes ? `\`${s}\`` : s;
 	let text;
 	switch (term.type) {
-		case "text": return terminalText(term.text);
+		case "text": return {
+			fragment: terminalText(term.text),
+			defaultOrigin: true
+		};
 		case "lineBreak": throw new TypeError("Hard breaks must be rendered at the message level.");
 		case "optionName":
 			text = quote(term.optionName);
@@ -65,19 +83,25 @@ function formatTerminalTerm(term, theme = {}, quotes = false, usage) {
 		usage,
 		format: (child) => formatTerminalTerm(child, theme, quotes, usage)
 	};
+	function render(formatter, value) {
+		return {
+			fragment: formatter(value, ctx),
+			defaultOrigin: defaultFormatters.has(formatter)
+		};
+	}
 	switch (term.type) {
-		case "optionName": return (theme.optionName ?? require_terminal.defaultTerminalTheme.optionName)(term, ctx);
-		case "optionNames": return (theme.optionNames ?? require_terminal.defaultTerminalTheme.optionNames)(term, ctx);
-		case "metavar": return (theme.metavar ?? require_terminal.defaultTerminalTheme.metavar)(term, ctx);
-		case "value": return (theme.value ?? require_terminal.defaultTerminalTheme.value)(term, ctx);
-		case "values": return valuesFormatter(theme)(term, ctx);
-		case "envVar": return (theme.envVar ?? require_terminal.defaultTerminalTheme.envVar)(term, ctx);
-		case "commandLine": return (theme.commandLine ?? require_terminal.defaultTerminalTheme.commandLine)(term, ctx);
-		case "url": return (theme.url ?? require_terminal.defaultTerminalTheme.url)(term, ctx);
-		case "programName": return (theme.programName ?? require_terminal.defaultTerminalTheme.programName)(term, ctx);
-		case "label": return (theme.label ?? require_terminal.defaultTerminalTheme.label)(term, ctx);
-		case "syntaxPunctuation": return (theme.syntaxPunctuation ?? require_terminal.defaultTerminalTheme.syntaxPunctuation)(term, ctx);
-		case "errorLabel": return (theme.errorLabel ?? require_terminal.defaultTerminalTheme.errorLabel)(term, ctx);
+		case "optionName": return render(theme.optionName ?? require_terminal.defaultTerminalTheme.optionName, term);
+		case "optionNames": return render(theme.optionNames ?? require_terminal.defaultTerminalTheme.optionNames, term);
+		case "metavar": return render(theme.metavar ?? require_terminal.defaultTerminalTheme.metavar, term);
+		case "value": return render(theme.value ?? require_terminal.defaultTerminalTheme.value, term);
+		case "values": return render(valuesFormatter(theme), term);
+		case "envVar": return render(theme.envVar ?? require_terminal.defaultTerminalTheme.envVar, term);
+		case "commandLine": return render(theme.commandLine ?? require_terminal.defaultTerminalTheme.commandLine, term);
+		case "url": return render(theme.url ?? require_terminal.defaultTerminalTheme.url, term);
+		case "programName": return render(theme.programName ?? require_terminal.defaultTerminalTheme.programName, term);
+		case "label": return render(theme.label ?? require_terminal.defaultTerminalTheme.label, term);
+		case "syntaxPunctuation": return render(theme.syntaxPunctuation ?? require_terminal.defaultTerminalTheme.syntaxPunctuation, term);
+		case "errorLabel": return render(theme.errorLabel ?? require_terminal.defaultTerminalTheme.errorLabel, term);
 	}
 }
 const colorNames = [
@@ -225,14 +249,14 @@ function serializeTokens(tokens, colors = false, resetSuffix = "", ambient = {})
 * @since 1.3.0
 * @internal
 */
-function renderTerminalTerm(term, theme, colors, usage, ambient) {
-	return serializeTokens(fragmentTokens(formatTerminalTerm(term, theme, false, usage)), colors, "", ambient);
+function renderTerminalTerm(term, theme, colors, usage, ambient, resetSuffix = "") {
+	return serializeTokens(fragmentTokens(formatTerminalTerm(term, theme, false, usage)), colors, resetSuffix, ambient);
 }
 /** Memoizes semantic leaves for one layout pass, including measurement. */
 function cacheTerminalTheme(theme = {}) {
 	function cache(formatter) {
 		const fragments = /* @__PURE__ */ new Map();
-		return (term, context) => {
+		const cached = (term, context) => {
 			const key = JSON.stringify([
 				term,
 				context.quotes,
@@ -245,6 +269,8 @@ function cacheTerminalTheme(theme = {}) {
 			}
 			return fragment;
 		};
+		if (defaultFormatters.has(formatter)) defaultFormatters.add(cached);
+		return cached;
 	}
 	return {
 		optionName: cache(theme.optionName ?? require_terminal.defaultTerminalTheme.optionName),
@@ -268,6 +294,7 @@ function cacheTerminalTheme(theme = {}) {
 
 //#endregion
 exports.cacheTerminalTheme = cacheTerminalTheme;
+exports.formatTerminalLeaf = formatTerminalLeaf;
 exports.formatTerminalTerm = formatTerminalTerm;
 exports.fragmentTokens = fragmentTokens;
 exports.renderTerminalTerm = renderTerminalTerm;

package/dist/terminal-internal.d.cts

@@ -10,9 +10,29 @@ interface TerminalToken {
   readonly text: string;
   readonly width: number;
   readonly scopes: readonly Scope[];
+  /** Layout-owned space, removable beside an explicit hard break. */
+  readonly separator?: boolean;
+  /** The historical program separator wraps before its following atom. */
+  readonly programBoundary?: boolean;
+  /** Enables only the legacy default formatter whitespace behavior. */
+  readonly legacyWhitespace?: boolean;
 }
 declare function terminalText(text: string): TerminalFragment;
 declare function formatTerminalTerm(term: TerminalTerm, theme?: TerminalTheme, quotes?: boolean, usage?: TerminalFormatContext["usage"]): TerminalFragment;
+/**
+ * Renders a semantic leaf and records the selected callback's provenance.
+ * @param term The semantic leaf to render.
+ * @param theme The optional role overrides.
+ * @param quotes Whether values should use their quoted representation.
+ * @param usage The leaf's position within a usage expression.
+ * @returns The fragment and whether its callback has default origin.
+ * @throws {TypeError} If the term is invalid or is a message-level hard break.
+ * @internal
+ */
+declare function formatTerminalLeaf(term: TerminalTerm, theme?: TerminalTheme, quotes?: boolean, usage?: TerminalFormatContext["usage"]): {
+  readonly fragment: TerminalFragment;
+  readonly defaultOrigin: boolean;
+};
 declare function styleCode(style: TerminalStyle): string;
 declare function fragmentTokens(fragment: TerminalFragment, scopes?: readonly Scope[], inherited?: TerminalStyle): Generator<TerminalToken>;
 declare function serializeTokens(tokens: Iterable<TerminalToken>, colors?: boolean, resetSuffix?: string, ambient?: TerminalStyle): string;
@@ -29,8 +49,8 @@ declare function serializeTokens(tokens: Iterable<TerminalToken>, colors?: boole
  * @since 1.3.0
  * @internal
  */
-declare function renderTerminalTerm(term: TerminalTerm, theme?: TerminalTheme, colors?: boolean, usage?: TerminalFormatContext["usage"], ambient?: TerminalStyle): string;
+declare function renderTerminalTerm(term: TerminalTerm, theme?: TerminalTheme, colors?: boolean, usage?: TerminalFormatContext["usage"], ambient?: TerminalStyle, resetSuffix?: string): string;
 /** Memoizes semantic leaves for one layout pass, including measurement. */
 declare function cacheTerminalTheme(theme?: TerminalTheme): TerminalTheme;
 //#endregion
-export { Scope, TerminalToken, cacheTerminalTheme, formatTerminalTerm, fragmentTokens, renderTerminalTerm, serializeTokens, styleCode, terminalText };
+export { Scope, TerminalToken, cacheTerminalTheme, formatTerminalLeaf, formatTerminalTerm, fragmentTokens, renderTerminalTerm, serializeTokens, styleCode, terminalText };

package/dist/terminal-internal.d.ts

@@ -10,9 +10,29 @@ interface TerminalToken {
   readonly text: string;
   readonly width: number;
   readonly scopes: readonly Scope[];
+  /** Layout-owned space, removable beside an explicit hard break. */
+  readonly separator?: boolean;
+  /** The historical program separator wraps before its following atom. */
+  readonly programBoundary?: boolean;
+  /** Enables only the legacy default formatter whitespace behavior. */
+  readonly legacyWhitespace?: boolean;
 }
 declare function terminalText(text: string): TerminalFragment;
 declare function formatTerminalTerm(term: TerminalTerm, theme?: TerminalTheme, quotes?: boolean, usage?: TerminalFormatContext["usage"]): TerminalFragment;
+/**
+ * Renders a semantic leaf and records the selected callback's provenance.
+ * @param term The semantic leaf to render.
+ * @param theme The optional role overrides.
+ * @param quotes Whether values should use their quoted representation.
+ * @param usage The leaf's position within a usage expression.
+ * @returns The fragment and whether its callback has default origin.
+ * @throws {TypeError} If the term is invalid or is a message-level hard break.
+ * @internal
+ */
+declare function formatTerminalLeaf(term: TerminalTerm, theme?: TerminalTheme, quotes?: boolean, usage?: TerminalFormatContext["usage"]): {
+  readonly fragment: TerminalFragment;
+  readonly defaultOrigin: boolean;
+};
 declare function styleCode(style: TerminalStyle): string;
 declare function fragmentTokens(fragment: TerminalFragment, scopes?: readonly Scope[], inherited?: TerminalStyle): Generator<TerminalToken>;
 declare function serializeTokens(tokens: Iterable<TerminalToken>, colors?: boolean, resetSuffix?: string, ambient?: TerminalStyle): string;
@@ -29,8 +49,8 @@ declare function serializeTokens(tokens: Iterable<TerminalToken>, colors?: boole
  * @since 1.3.0
  * @internal
  */
-declare function renderTerminalTerm(term: TerminalTerm, theme?: TerminalTheme, colors?: boolean, usage?: TerminalFormatContext["usage"], ambient?: TerminalStyle): string;
+declare function renderTerminalTerm(term: TerminalTerm, theme?: TerminalTheme, colors?: boolean, usage?: TerminalFormatContext["usage"], ambient?: TerminalStyle, resetSuffix?: string): string;
 /** Memoizes semantic leaves for one layout pass, including measurement. */
 declare function cacheTerminalTheme(theme?: TerminalTheme): TerminalTheme;
 //#endregion
-export { Scope, TerminalToken, cacheTerminalTheme, formatTerminalTerm, fragmentTokens, renderTerminalTerm, serializeTokens, styleCode, terminalText };
+export { Scope, TerminalToken, cacheTerminalTheme, formatTerminalLeaf, formatTerminalTerm, fragmentTokens, renderTerminalTerm, serializeTokens, styleCode, terminalText };