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

package/dist/doc.cjs

@@ -1,8 +1,8 @@
 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');
 const require_message_renderer = require('./message-renderer.cjs');
-const require_text_layout = require('./text-layout.cjs');
 const require_validate = require('./validate.cjs');
 const require_usage = require('./usage.cjs');
 

package/dist/doc.js

@@ -1,8 +1,8 @@
 import { messageRenderers } from "./message-registry.js";
 import { cacheTerminalTheme, formatTerminalTerm, fragmentTokens, renderTerminalTerm, styleCode } from "./terminal-internal.js";
+import { measureAnnotation, measureText, placeText, spaceAfterLabel } from "./text-layout.js";
 import { cloneMessage, text } from "./message.js";
 import { resolveMessageFormatter } from "./message-renderer.js";
-import { measureAnnotation, measureText, placeText, spaceAfterLabel } from "./text-layout.js";
 import { validateLabel, validateProgramName } from "./validate.js";
 import { cloneUsageTerm, formatUsage, formatUsageTerm, isDocHidden } from "./usage.js";
 

package/dist/facade.cjs

@@ -1,8 +1,8 @@
 const require_internal_annotations = require('./internal/annotations.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_text_layout = require('./text-layout.cjs');
 const require_validate = require('./validate.cjs');
 const require_usage = require('./usage.cjs');
 const require_doc = require('./doc.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_text_layout.spaceAfterLabel(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_text_layout.measureText(prefix).lastLineWidth
-		})}\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_text_layout.measureText(prefix).lastLineWidth
-		})}`);
+			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,14 +874,6 @@ 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_text_layout.spaceAfterLabel(require_terminal_internal.renderTerminalTerm({
-		type: "errorLabel",
-		label: "Error:"
-	}, theme, colors));
 	let usagePrefix;
 	const usageLabel = () => usagePrefix ??= require_text_layout.spaceAfterLabel(require_terminal_internal.renderTerminalTerm({
 		type: "label",
@@ -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_text_layout.measureText(prefix).lastLineWidth,
-						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_text_layout.measureText(prefix).lastLineWidth,
-						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 { renderTerminalTerm } from "./terminal-internal.js";
-import { commandLine, lineBreak, message, optionName, text, value } from "./message.js";
-import { resolveMessageFormatter } from "./message-renderer.js";
 import { measureText, spaceAfterLabel } from "./text-layout.js";
+import { commandLine, lineBreak, message, optionName, text, value } from "./message.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 = () => spaceAfterLabel(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: measureText(prefix).lastLineWidth
-		})}\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: measureText(prefix).lastLineWidth
-		})}`);
+			maxWidth
+		}));
 		return dispatchByMode(parser.mode, () => {
 			const result = callOnError(1, error);
 			if (result instanceof Promise) throw new RunParserError("Synchronous parser returned async result.");
@@ -882,14 +874,6 @@ 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 = () => spaceAfterLabel(renderTerminalTerm({
-		type: "errorLabel",
-		label: "Error:"
-	}, theme, colors));
 	let usagePrefix;
 	const usageLabel = () => usagePrefix ??= spaceAfterLabel(renderTerminalTerm({
 		type: "label",
@@ -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: measureText(prefix).lastLineWidth,
-						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: measureText(prefix).lastLineWidth,
-						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,11 +1,12 @@
 const require_displaywidth = require('../displaywidth.cjs');
 const require_terminal_internal = require('../terminal-internal.cjs');
-const require_message_renderer = require('../message-renderer.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.spaceAfterLabel = require_text_layout.spaceAfterLabel;

package/dist/internal/terminal.d.cts

@@ -1,5 +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";
 import { measureText, placeText, spaceAfterLabel } from "../text-layout.cjs";
-export { getDisplayWidth, measureText, placeText, renderTerminalTerm, resolveMessageFormatter, spaceAfterLabel };
+export { getDisplayWidth, measureText, placeText, renderErrorMessage, renderTerminalTerm, resolveMessageFormatter, spaceAfterLabel };

package/dist/internal/terminal.d.ts

@@ -1,5 +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";
 import { measureText, placeText, spaceAfterLabel } from "../text-layout.js";
-export { getDisplayWidth, measureText, placeText, renderTerminalTerm, resolveMessageFormatter, spaceAfterLabel };
+export { getDisplayWidth, measureText, placeText, renderErrorMessage, renderTerminalTerm, resolveMessageFormatter, spaceAfterLabel };

package/dist/internal/terminal.js

@@ -1,6 +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, measureText, placeText, renderTerminalTerm, resolveMessageFormatter, spaceAfterLabel };
+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

@@ -12,9 +12,27 @@ interface TerminalToken {
   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;
@@ -31,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

@@ -12,9 +12,27 @@ interface TerminalToken {
   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;
@@ -31,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.js

@@ -17,11 +17,29 @@ function valuesFormatter(theme) {
 		children: [defaultTerminalTheme.values(term, context)]
 	});
 }
+/** Default callback identity survives any number of per-pass caches. */
+const defaultFormatters = new WeakSet(Object.values(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 ?? defaultTerminalTheme.optionName)(term, ctx);
-		case "optionNames": return (theme.optionNames ?? defaultTerminalTheme.optionNames)(term, ctx);
-		case "metavar": return (theme.metavar ?? defaultTerminalTheme.metavar)(term, ctx);
-		case "value": return (theme.value ?? defaultTerminalTheme.value)(term, ctx);
-		case "values": return valuesFormatter(theme)(term, ctx);
-		case "envVar": return (theme.envVar ?? defaultTerminalTheme.envVar)(term, ctx);
-		case "commandLine": return (theme.commandLine ?? defaultTerminalTheme.commandLine)(term, ctx);
-		case "url": return (theme.url ?? defaultTerminalTheme.url)(term, ctx);
-		case "programName": return (theme.programName ?? defaultTerminalTheme.programName)(term, ctx);
-		case "label": return (theme.label ?? defaultTerminalTheme.label)(term, ctx);
-		case "syntaxPunctuation": return (theme.syntaxPunctuation ?? defaultTerminalTheme.syntaxPunctuation)(term, ctx);
-		case "errorLabel": return (theme.errorLabel ?? defaultTerminalTheme.errorLabel)(term, ctx);
+		case "optionName": return render(theme.optionName ?? defaultTerminalTheme.optionName, term);
+		case "optionNames": return render(theme.optionNames ?? defaultTerminalTheme.optionNames, term);
+		case "metavar": return render(theme.metavar ?? defaultTerminalTheme.metavar, term);
+		case "value": return render(theme.value ?? defaultTerminalTheme.value, term);
+		case "values": return render(valuesFormatter(theme), term);
+		case "envVar": return render(theme.envVar ?? defaultTerminalTheme.envVar, term);
+		case "commandLine": return render(theme.commandLine ?? defaultTerminalTheme.commandLine, term);
+		case "url": return render(theme.url ?? defaultTerminalTheme.url, term);
+		case "programName": return render(theme.programName ?? defaultTerminalTheme.programName, term);
+		case "label": return render(theme.label ?? defaultTerminalTheme.label, term);
+		case "syntaxPunctuation": return render(theme.syntaxPunctuation ?? defaultTerminalTheme.syntaxPunctuation, term);
+		case "errorLabel": return render(theme.errorLabel ?? 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 ?? defaultTerminalTheme.optionName),
@@ -267,4 +293,4 @@ function cacheTerminalTheme(theme = {}) {
 }
 
 //#endregion
-export { cacheTerminalTheme, formatTerminalTerm, fragmentTokens, renderTerminalTerm, serializeTokens, styleCode, terminalText };
+export { cacheTerminalTheme, formatTerminalLeaf, formatTerminalTerm, fragmentTokens, renderTerminalTerm, serializeTokens, styleCode, terminalText };

package/dist/usage.cjs

@@ -196,34 +196,25 @@ function formatUsage(programName, usage, options = {}) {
 		if (usage.length > 0 && usage.slice(0, -1).every((t) => t.type === "command") && lastTerm.type === "exclusive" && lastTerm.terms.every((t) => t.length > 0 && (t[0].type === "command" || t[0].type === "option" || t[0].type === "argument" || t[0].type === "optional" && t[0].terms.length === 1 && (t[0].terms[0].type === "command" || t[0].terms[0].type === "option" || t[0].terms[0].type === "argument")))) {
 			const lines = [];
 			for (let command of lastTerm.terms) {
-				const firstTerm$1 = command[0];
-				if (firstTerm$1?.type === "command" && isUsageHidden(firstTerm$1.hidden)) continue;
+				const firstTerm = command[0];
+				if (firstTerm?.type === "command" && isUsageHidden(firstTerm.hidden)) continue;
 				if (usage.length > 1) command = [...usage.slice(0, -1), ...command];
 				lines.push(formatUsage(programName, command, options));
 			}
 			if (lines.length > 0) return lines.join("\n");
 		}
 	}
-	const programTokens = layoutUsageTokens(require_terminal_internal.fragmentTokens(require_terminal_internal.formatTerminalTerm({
-		type: "programName",
-		programName
-	}, options.theme)), options);
-	const terms = [...normalizeUsageSeparators(formatUsageTerms(usage, options))];
-	if (terms.length === 0) return require_terminal_internal.serializeTokens(programTokens, options.colors);
-	const width = programTokens.reduce((n, token) => token.width === -1 ? 0 : n + token.width, 0);
-	const firstTerm = terms.find((token) => token.text !== "");
-	const lastProgram = programTokens.findLast((token) => token.text !== "");
-	if (lastProgram == null || firstTerm == null || lastProgram.width === -1 || firstTerm.width === -1) return require_terminal_internal.serializeTokens(programTokens, options.colors) + wrapUsageTokens(terms, options, width);
-	const separator = options.maxWidth != null && width + 1 + firstTerm.width > options.maxWidth ? {
-		text: "\n",
-		width: -1,
-		scopes: []
-	} : {
-		text: " ",
-		width: 1,
-		scopes: []
-	};
-	return require_terminal_internal.serializeTokens([...programTokens, separator], options.colors) + wrapUsageTokens(terms, options, separator.width === -1 ? 0 : width + 1);
+	return wrapUsageTokens(function* () {
+		yield* usageLeafTokens({
+			type: "programName",
+			programName
+		}, options);
+		yield {
+			...usageSpace,
+			programBoundary: true
+		};
+		yield* formatUsageTerms(usage, options);
+	}(), options);
 }
 /**
 * Normalizes a usage description by flattening nested exclusive terms,
@@ -453,15 +444,23 @@ function filterUsageForDisplay(usage, isHidden = isUsageHidden) {
 	}
 	return terms;
 }
+const usageSpace = {
+	text: " ",
+	width: 1,
+	scopes: [],
+	separator: true
+};
+function* usageLeafTokens(term, options, usage) {
+	const { fragment, defaultOrigin } = require_terminal_internal.formatTerminalLeaf(term, options.theme, false, usage);
+	for (const token of require_terminal_internal.fragmentTokens(fragment)) yield {
+		...token,
+		legacyWhitespace: defaultOrigin
+	};
+}
 function* formatUsageTerms(terms, options) {
 	let i = 0;
 	for (const t of terms) {
-		if (i > 0) yield {
-			text: " ",
-			width: 1,
-			scopes: [],
-			separator: true
-		};
+		if (i > 0) yield usageSpace;
 		yield* formatUsageTermInternal(t, options);
 		i++;
 	}
@@ -487,8 +486,8 @@ function formatUsageTerm(term, options = {}) {
 	if (visibleTerms.length < 1) return "";
 	return wrapUsageTokens(formatUsageTermInternal(visibleTerms[0], options), options);
 }
-function wrapUsageTokens(input, options, initialWidth = 0) {
-	return require_terminal_internal.serializeTokens(layoutUsageTokens(input, options, initialWidth), options.colors);
+function wrapUsageTokens(input, options) {
+	return require_terminal_internal.serializeTokens(layoutUsageTokens(input, options), options.colors);
 }
 /** Keeps one layout-owned space between nonempty outputs on the same line. */
 function* normalizeUsageSeparators(input) {
@@ -511,18 +510,33 @@ function* normalizeUsageSeparators(input) {
 	}
 	for (const item of pending) if (!item.separator) yield item;
 }
-function layoutUsageTokens(input, options, initialWidth = 0) {
-	let lineWidth = initialWidth;
+function layoutUsageTokens(input, options) {
+	let lineWidth = 0;
 	const output = [];
-	for (const token of normalizeUsageSeparators(input)) {
+	const tokens = [...normalizeUsageSeparators(input)];
+	for (const [index, token] of tokens.entries()) {
+		if (token.programBoundary && options.maxWidth != null) {
+			const next = tokens.find((item, i) => i > index && item.text !== "");
+			if (next != null && lineWidth + token.width + next.width > options.maxWidth) {
+				output.push({
+					text: "\n",
+					width: -1,
+					scopes: []
+				});
+				lineWidth = 0;
+				continue;
+			}
+		}
 		if (token.width === -1) {
 			output.push(token);
 			lineWidth = 0;
 			continue;
 		}
 		if (options.maxWidth != null && lineWidth > 0 && token.width > 0 && lineWidth + token.width > options.maxWidth) {
-			const last = output.at(-1);
-			if (last?.text.endsWith(" ") && (!options.colors || last.scopes.length === 0)) output[output.length - 1] = {
+			let lastIndex = output.length - 1;
+			while (lastIndex >= 0 && output[lastIndex].text === "") lastIndex--;
+			const last = output[lastIndex];
+			if (last?.text.endsWith(" ") && (last.separator || last.legacyWhitespace && (!options.colors || last.scopes.length === 0))) output[lastIndex] = {
 				...last,
 				text: last.text.slice(0, -1),
 				width: last.width - 1
@@ -533,7 +547,7 @@ function layoutUsageTokens(input, options, initialWidth = 0) {
 				scopes: []
 			});
 			lineWidth = 0;
-			if (token.text === " ") continue;
+			if (token.separator || token.legacyWhitespace && token.text === " ") continue;
 		}
 		output.push(token);
 		lineWidth += token.width;
@@ -542,7 +556,7 @@ function layoutUsageTokens(input, options, initialWidth = 0) {
 }
 function* formatUsageTermInternal(term, options) {
 	function leaf(t, usage) {
-		return require_terminal_internal.fragmentTokens(require_terminal_internal.formatTerminalTerm(t, options.theme, false, usage));
+		return usageLeafTokens(t, options, usage);
 	}
 	function punctuation(punctuation$1, kind) {
 		return leaf({
@@ -551,12 +565,7 @@ function* formatUsageTermInternal(term, options) {
 			kind
 		});
 	}
-	const space = {
-		text: " ",
-		width: 1,
-		scopes: [],
-		separator: true
-	};
+	const space = usageSpace;
 	if (term.type === "argument") yield* leaf({
 		type: "metavar",
 		metavar: term.metavar

package/dist/usage.js

@@ -1,5 +1,5 @@
 import { getDisplayWidth } from "./displaywidth.js";
-import { cacheTerminalTheme, formatTerminalTerm, fragmentTokens, serializeTokens } from "./terminal-internal.js";
+import { cacheTerminalTheme, formatTerminalLeaf, fragmentTokens, serializeTokens } from "./terminal-internal.js";
 import { validateProgramName } from "./validate.js";
 
 //#region src/usage.ts
@@ -196,34 +196,25 @@ function formatUsage(programName, usage, options = {}) {
 		if (usage.length > 0 && usage.slice(0, -1).every((t) => t.type === "command") && lastTerm.type === "exclusive" && lastTerm.terms.every((t) => t.length > 0 && (t[0].type === "command" || t[0].type === "option" || t[0].type === "argument" || t[0].type === "optional" && t[0].terms.length === 1 && (t[0].terms[0].type === "command" || t[0].terms[0].type === "option" || t[0].terms[0].type === "argument")))) {
 			const lines = [];
 			for (let command of lastTerm.terms) {
-				const firstTerm$1 = command[0];
-				if (firstTerm$1?.type === "command" && isUsageHidden(firstTerm$1.hidden)) continue;
+				const firstTerm = command[0];
+				if (firstTerm?.type === "command" && isUsageHidden(firstTerm.hidden)) continue;
 				if (usage.length > 1) command = [...usage.slice(0, -1), ...command];
 				lines.push(formatUsage(programName, command, options));
 			}
 			if (lines.length > 0) return lines.join("\n");
 		}
 	}
-	const programTokens = layoutUsageTokens(fragmentTokens(formatTerminalTerm({
-		type: "programName",
-		programName
-	}, options.theme)), options);
-	const terms = [...normalizeUsageSeparators(formatUsageTerms(usage, options))];
-	if (terms.length === 0) return serializeTokens(programTokens, options.colors);
-	const width = programTokens.reduce((n, token) => token.width === -1 ? 0 : n + token.width, 0);
-	const firstTerm = terms.find((token) => token.text !== "");
-	const lastProgram = programTokens.findLast((token) => token.text !== "");
-	if (lastProgram == null || firstTerm == null || lastProgram.width === -1 || firstTerm.width === -1) return serializeTokens(programTokens, options.colors) + wrapUsageTokens(terms, options, width);
-	const separator = options.maxWidth != null && width + 1 + firstTerm.width > options.maxWidth ? {
-		text: "\n",
-		width: -1,
-		scopes: []
-	} : {
-		text: " ",
-		width: 1,
-		scopes: []
-	};
-	return serializeTokens([...programTokens, separator], options.colors) + wrapUsageTokens(terms, options, separator.width === -1 ? 0 : width + 1);
+	return wrapUsageTokens(function* () {
+		yield* usageLeafTokens({
+			type: "programName",
+			programName
+		}, options);
+		yield {
+			...usageSpace,
+			programBoundary: true
+		};
+		yield* formatUsageTerms(usage, options);
+	}(), options);
 }
 /**
 * Normalizes a usage description by flattening nested exclusive terms,
@@ -453,15 +444,23 @@ function filterUsageForDisplay(usage, isHidden = isUsageHidden) {
 	}
 	return terms;
 }
+const usageSpace = {
+	text: " ",
+	width: 1,
+	scopes: [],
+	separator: true
+};
+function* usageLeafTokens(term, options, usage) {
+	const { fragment, defaultOrigin } = formatTerminalLeaf(term, options.theme, false, usage);
+	for (const token of fragmentTokens(fragment)) yield {
+		...token,
+		legacyWhitespace: defaultOrigin
+	};
+}
 function* formatUsageTerms(terms, options) {
 	let i = 0;
 	for (const t of terms) {
-		if (i > 0) yield {
-			text: " ",
-			width: 1,
-			scopes: [],
-			separator: true
-		};
+		if (i > 0) yield usageSpace;
 		yield* formatUsageTermInternal(t, options);
 		i++;
 	}
@@ -487,8 +486,8 @@ function formatUsageTerm(term, options = {}) {
 	if (visibleTerms.length < 1) return "";
 	return wrapUsageTokens(formatUsageTermInternal(visibleTerms[0], options), options);
 }
-function wrapUsageTokens(input, options, initialWidth = 0) {
-	return serializeTokens(layoutUsageTokens(input, options, initialWidth), options.colors);
+function wrapUsageTokens(input, options) {
+	return serializeTokens(layoutUsageTokens(input, options), options.colors);
 }
 /** Keeps one layout-owned space between nonempty outputs on the same line. */
 function* normalizeUsageSeparators(input) {
@@ -511,18 +510,33 @@ function* normalizeUsageSeparators(input) {
 	}
 	for (const item of pending) if (!item.separator) yield item;
 }
-function layoutUsageTokens(input, options, initialWidth = 0) {
-	let lineWidth = initialWidth;
+function layoutUsageTokens(input, options) {
+	let lineWidth = 0;
 	const output = [];
-	for (const token of normalizeUsageSeparators(input)) {
+	const tokens = [...normalizeUsageSeparators(input)];
+	for (const [index, token] of tokens.entries()) {
+		if (token.programBoundary && options.maxWidth != null) {
+			const next = tokens.find((item, i) => i > index && item.text !== "");
+			if (next != null && lineWidth + token.width + next.width > options.maxWidth) {
+				output.push({
+					text: "\n",
+					width: -1,
+					scopes: []
+				});
+				lineWidth = 0;
+				continue;
+			}
+		}
 		if (token.width === -1) {
 			output.push(token);
 			lineWidth = 0;
 			continue;
 		}
 		if (options.maxWidth != null && lineWidth > 0 && token.width > 0 && lineWidth + token.width > options.maxWidth) {
-			const last = output.at(-1);
-			if (last?.text.endsWith(" ") && (!options.colors || last.scopes.length === 0)) output[output.length - 1] = {
+			let lastIndex = output.length - 1;
+			while (lastIndex >= 0 && output[lastIndex].text === "") lastIndex--;
+			const last = output[lastIndex];
+			if (last?.text.endsWith(" ") && (last.separator || last.legacyWhitespace && (!options.colors || last.scopes.length === 0))) output[lastIndex] = {
 				...last,
 				text: last.text.slice(0, -1),
 				width: last.width - 1
@@ -533,7 +547,7 @@ function layoutUsageTokens(input, options, initialWidth = 0) {
 				scopes: []
 			});
 			lineWidth = 0;
-			if (token.text === " ") continue;
+			if (token.separator || token.legacyWhitespace && token.text === " ") continue;
 		}
 		output.push(token);
 		lineWidth += token.width;
@@ -542,7 +556,7 @@ function layoutUsageTokens(input, options, initialWidth = 0) {
 }
 function* formatUsageTermInternal(term, options) {
 	function leaf(t, usage) {
-		return fragmentTokens(formatTerminalTerm(t, options.theme, false, usage));
+		return usageLeafTokens(t, options, usage);
 	}
 	function punctuation(punctuation$1, kind) {
 		return leaf({
@@ -551,12 +565,7 @@ function* formatUsageTermInternal(term, options) {
 			kind
 		});
 	}
-	const space = {
-		text: " ",
-		width: 1,
-		scopes: [],
-		separator: true
-	};
+	const space = usageSpace;
 	if (term.type === "argument") yield* leaf({
 		type: "metavar",
 		metavar: term.metavar

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.3.0-dev.2554",
+  "version": "1.3.0-dev.2558",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -237,7 +237,7 @@
   },
   "sideEffects": false,
   "devDependencies": {
-    "@optique/env": "1.3.0-dev.2554+5fdcbbad",
+    "@optique/env": "1.3.0-dev.2558+85f681ee",
     "@types/node": "^24.0.0",
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",