@optique/core 1.3.0-dev.2524 → 1.3.0-dev.2530

package/dist/doc.js

@@ -1,7 +1,10 @@
+import { messageRenderers } from "./message-registry.js";
 import { getDisplayWidth } from "./displaywidth.js";
-import { cloneMessage, formatMessage, text } from "./message.js";
+import { cacheTerminalTheme, formatTerminalTerm, fragmentTokens, renderTerminalTerm, styleCode } from "./terminal-internal.js";
+import { cloneMessage, text } from "./message.js";
+import { resolveMessageFormatter } from "./message-renderer.js";
 import { validateLabel, validateProgramName } from "./validate.js";
-import { cloneUsageTerm, formatUsage, formatUsageTerm, isDocHidden, isUsageHidden } from "./usage.js";
+import { cloneUsageTerm, formatUsage, formatUsageTerm, isDocHidden } from "./usage.js";
 
 //#region src/doc.ts
 /**
@@ -211,6 +214,46 @@ function defaultSectionOrder(a, b) {
 * ```
 */
 function formatDocPage(programName, page, options = {}) {
+	options = {
+		...options,
+		theme: cacheTerminalTheme(options.theme)
+	};
+	const formatMessage = resolveMessageFormatter(options);
+	const opaqueFormatter = options.messageFormatter != null && !messageRenderers.has(options.messageFormatter);
+	const defaultAmbient = options.theme?.annotationStyles?.default ?? { dim: true };
+	const choicesAmbient = options.theme?.annotationStyles?.choices ?? { dim: true };
+	const labelCache = /* @__PURE__ */ new Map();
+	const label = (label$1, kind) => {
+		const key = `${kind}:${label$1}`;
+		let rendered = labelCache.get(key);
+		if (rendered == null) {
+			rendered = renderTerminalTerm({
+				type: "label",
+				label: label$1,
+				kind
+			}, options.theme, options.colors, void 0, kind === "choices" ? choicesAmbient : void 0);
+			labelCache.set(key, rendered);
+		}
+		return rendered;
+	};
+	const punctuationCache = /* @__PURE__ */ new Map();
+	const punctuation = (punctuation$1, kind) => {
+		const key = `${kind}:${punctuation$1}`;
+		let rendered = punctuationCache.get(key);
+		if (rendered == null) {
+			rendered = renderTerminalTerm({
+				type: "syntaxPunctuation",
+				punctuation: punctuation$1,
+				kind
+			}, options.theme, options.colors, void 0, kind.startsWith("default") ? defaultAmbient : kind.startsWith("choices") ? choicesAmbient : void 0);
+			punctuationCache.set(key, rendered);
+		}
+		return rendered;
+	};
+	const usageLabel = page.usage != null && options.showUsage !== false ? label("Usage:", "usage") + " " : "";
+	const usageLabelWidth = getDisplayWidth(usageLabel);
+	const defaultStyle = styleCode(options.theme?.annotationStyles?.default ?? { dim: true });
+	const choicesStyle = styleCode(options.theme?.annotationStyles?.choices ?? { dim: true });
 	validateProgramName(programName);
 	const termIndent = options.termIndent ?? 2;
 	const showUsage = options.showUsage ?? true;
@@ -238,6 +281,7 @@ function formatDocPage(programName, page, options = {}) {
 			if (!needsDescriptionColumn(entry)) continue;
 			const rendered = formatUsageTerm(entry.term, {
 				colors: options.colors,
+				theme: options.theme,
 				optionsSeparator: ", ",
 				context: "doc"
 			});
@@ -260,24 +304,27 @@ function formatDocPage(programName, page, options = {}) {
 		let minDescWidth = 1;
 		if (needsDescColumn) {
 			if (options.showDefault && page.sections.some((s) => s.entries.some((e) => hasContent(e.default)))) {
-				const prefix = typeof options.showDefault === "object" ? options.showDefault.prefix ?? " [" : " [";
+				const prefix = punctuation(typeof options.showDefault === "object" ? options.showDefault.prefix ?? " [" : " [", "defaultPrefix");
 				minDescWidth = Math.max(minDescWidth, getDisplayWidth(prefix));
 			}
 			if (options.showChoices && page.sections.some((s) => s.entries.some((e) => hasContent(e.choices)))) {
-				const prefix = typeof options.showChoices === "object" ? options.showChoices.prefix ?? " (" : " (";
-				const label = typeof options.showChoices === "object" ? options.showChoices.label ?? "choices: " : "choices: ";
-				minDescWidth = Math.max(minDescWidth, getDisplayWidth(prefix) + getDisplayWidth(label));
+				const prefix = punctuation(typeof options.showChoices === "object" ? options.showChoices.prefix ?? " (" : " (", "choicesPrefix");
+				const choicesLabelText = label(typeof options.showChoices === "object" ? options.showChoices.label ?? "choices: " : "choices: ", "choices");
+				minDescWidth = Math.max(minDescWidth, getDisplayWidth(prefix) + getDisplayWidth(choicesLabelText));
 			}
 		}
 		const splitEntryMin = termIndent + 2 + Math.max(2, 2 * minDescWidth - 1);
 		const fixedEntryMin = termIndent + 2 + termWidth + minDescWidth;
 		const entryMin = needsDescColumn ? Math.min(splitEntryMin, fixedEntryMin) : hasEntries ? termIndent + 1 : 1;
-		const programNameWidth = getDisplayWidth(programName);
-		const usageMin = page.usage != null && showUsage ? 7 + Math.max(programNameWidth, Math.min(maxVisibleAtomicWidth(page.usage), programNameWidth + 7)) : 1;
+		const programNameWidth = page.usage != null && showUsage ? Math.max(0, ...[...fragmentTokens(formatTerminalTerm({
+			type: "programName",
+			programName
+		}, options.theme))].map((token) => token.width)) : 0;
+		const usageMin = page.usage != null && showUsage ? usageLabelWidth + Math.max(programNameWidth, Math.min(maxVisibleAtomicWidth(page.usage, options.theme), programNameWidth + usageLabelWidth)) : 1;
 		let sectionMin = 1;
-		if (hasContent(page.examples)) sectionMin = Math.max(sectionMin, 9);
-		if (hasContent(page.author)) sectionMin = Math.max(sectionMin, 7);
-		if (hasContent(page.bugs)) sectionMin = Math.max(sectionMin, 5);
+		if (hasContent(page.examples)) sectionMin = Math.max(sectionMin, getDisplayWidth(label("Examples:", "examples")));
+		if (hasContent(page.author)) sectionMin = Math.max(sectionMin, getDisplayWidth(label("Author:", "author")));
+		if (hasContent(page.bugs)) sectionMin = Math.max(sectionMin, getDisplayWidth(label("Bugs:", "bugs")));
 		const minWidth = Math.max(entryMin, usageMin, sectionMin);
 		if (options.maxWidth < minWidth) throw new RangeError(`maxWidth must be at least ${minWidth}, got ${options.maxWidth}.`);
 		if (needsDescColumn && minDescWidth > 1) {
@@ -299,13 +346,13 @@ function formatDocPage(programName, page, options = {}) {
 		output += "\n";
 	}
 	if (page.usage != null && showUsage) {
-		const usageLabel = options.colors ? "\x1B[1;2mUsage:\x1B[0m " : "Usage: ";
 		output += usageLabel;
 		output += indentLines(formatUsage(programName, page.usage, {
 			colors: options.colors,
-			maxWidth: options.maxWidth == null ? void 0 : options.maxWidth - 7,
+			theme: options.theme,
+			maxWidth: options.maxWidth == null ? void 0 : options.maxWidth - usageLabelWidth,
 			expandCommands: true
-		}), 7);
+		}), usageLabelWidth);
 		output += "\n";
 	}
 	if (hasContent(page.description)) {
@@ -331,12 +378,13 @@ function formatDocPage(programName, page, options = {}) {
 		output += "\n";
 		if (section.title != null) {
 			validateLabel(section.title);
-			const sectionLabel = options.colors ? `\x1b[1;2m${section.title}:\x1b[0m\n` : `${section.title}:\n`;
+			const sectionLabel = label(`${section.title}:`, "section") + "\n";
 			output += sectionLabel;
 		}
 		for (const entry of section.entries) {
 			const term = formatUsageTerm(entry.term, {
 				colors: options.colors,
+				theme: options.theme,
 				optionsSeparator: ", ",
 				context: "doc",
 				maxWidth: options.maxWidth == null ? void 0 : options.maxWidth - termIndent
@@ -349,12 +397,12 @@ function formatDocPage(programName, page, options = {}) {
 				colors: options.colors,
 				quotes: !options.colors,
 				maxWidth: descColumnWidth,
-				startWidth: extraTermOffset > 0 ? extraTermOffset : void 0
+				initialWidth: extraTermOffset > 0 ? extraTermOffset : void 0
 			};
 			let description = entry.description == null ? "" : formatMessage(entry.description, descFormatOptions);
 			if (options.showDefault && hasContent(entry.default)) {
-				const prefix = typeof options.showDefault === "object" ? options.showDefault.prefix ?? " [" : " [";
-				const suffix = typeof options.showDefault === "object" ? options.showDefault.suffix ?? "]" : "]";
+				const prefix = punctuation(typeof options.showDefault === "object" ? options.showDefault.prefix ?? " [" : " [", "defaultPrefix");
+				const suffix = punctuation(typeof options.showDefault === "object" ? options.showDefault.suffix ?? "]" : "]", "defaultSuffix");
 				const prefixWidth = getDisplayWidth(prefix);
 				const suffixWidth = getDisplayWidth(suffix);
 				let defaultStartWidth;
@@ -367,20 +415,20 @@ function formatDocPage(programName, page, options = {}) {
 					} else defaultStartWidth = effectiveLastW + prefixWidth;
 				}
 				const defaultFormatOptions = {
-					colors: options.colors ? { resetSuffix: "\x1B[2m" } : false,
+					colors: options.colors ? { resetSuffix: defaultStyle } : false,
 					quotes: !options.colors,
 					maxWidth: descColumnWidth == null ? void 0 : descColumnWidth - suffixWidth,
-					startWidth: defaultStartWidth
+					initialWidth: defaultStartWidth
 				};
-				const defaultContent = formatMessage(entry.default, defaultFormatOptions);
-				const defaultText = `${prefix}${defaultContent}${suffix}`;
-				const formattedDefault = options.colors ? `\x1b[2m${defaultText}\x1b[0m` : defaultText;
+				const defaultContent = formatMessage(entry.default, defaultFormatOptions, options.theme?.annotationStyles?.default ?? { dim: true });
+				const defaultText = `${prefix}${defaultContent}${opaqueFormatter && options.colors ? defaultStyle : ""}${suffix}`;
+				const formattedDefault = options.colors ? `${defaultStyle}${defaultText}${defaultStyle ? "\x1B[0m" : ""}` : defaultText;
 				description += formattedDefault;
 			}
 			if (options.showChoices && hasContent(entry.choices)) {
-				const prefix = typeof options.showChoices === "object" ? options.showChoices.prefix ?? " (" : " (";
-				const suffix = typeof options.showChoices === "object" ? options.showChoices.suffix ?? ")" : ")";
-				const label = typeof options.showChoices === "object" ? options.showChoices.label ?? "choices: " : "choices: ";
+				const prefix = punctuation(typeof options.showChoices === "object" ? options.showChoices.prefix ?? " (" : " (", "choicesPrefix");
+				const suffix = punctuation(typeof options.showChoices === "object" ? options.showChoices.suffix ?? ")" : ")", "choicesSuffix");
+				const choicesLabelText = label(typeof options.showChoices === "object" ? options.showChoices.label ?? "choices: " : "choices: ", "choices");
 				const maxItems = typeof options.showChoices === "object" ? options.showChoices.maxItems ?? 8 : 8;
 				const terms = Array.isArray(entry.choices) ? entry.choices : [];
 				let truncatedTerms = terms;
@@ -400,7 +448,7 @@ function formatDocPage(programName, page, options = {}) {
 				}
 				const choicesPrefixWidth = getDisplayWidth(prefix);
 				const choicesSuffixWidth = getDisplayWidth(suffix);
-				const choicesLabelWidth = getDisplayWidth(label);
+				const choicesLabelWidth = getDisplayWidth(choicesLabelText);
 				let choicesStartWidth;
 				if (descColumnWidth != null) {
 					const lastW = lastLineVisibleLength(description);
@@ -412,14 +460,14 @@ function formatDocPage(programName, page, options = {}) {
 					} else choicesStartWidth = effectiveLastW + prefixLabelLen;
 				}
 				const choicesFormatOptions = {
-					colors: options.colors ? { resetSuffix: "\x1B[2m" } : false,
+					colors: options.colors ? { resetSuffix: choicesStyle } : false,
 					quotes: false,
 					maxWidth: descColumnWidth == null ? void 0 : descColumnWidth - choicesSuffixWidth,
-					startWidth: choicesStartWidth
+					initialWidth: choicesStartWidth
 				};
-				const choicesDisplay = formatMessage(truncatedTerms, choicesFormatOptions);
-				const choicesText = `${prefix}${label}${choicesDisplay}${suffix}`;
-				const formattedChoices = options.colors ? `\x1b[2m${choicesText}\x1b[0m` : choicesText;
+				const choicesDisplay = formatMessage(truncatedTerms, choicesFormatOptions, options.theme?.annotationStyles?.choices ?? { dim: true });
+				const choicesText = `${prefix}${choicesLabelText}${choicesDisplay}${opaqueFormatter && options.colors ? choicesStyle : ""}${suffix}`;
+				const formattedChoices = options.colors ? `${choicesStyle}${choicesText}${choicesStyle ? "\x1B[0m" : ""}` : choicesText;
 				description += formattedChoices;
 			}
 			output += `${" ".repeat(termIndent)}${ansiAwareRightPad(term, effectiveTermWidth)}${description === "" ? "" : `  ${indentLines(description, termIndent + effectiveTermWidth + 2)}`}\n`;
@@ -427,7 +475,7 @@ function formatDocPage(programName, page, options = {}) {
 	}
 	if (hasContent(page.examples)) {
 		output += "\n";
-		const examplesLabel = options.colors ? "\x1B[1;2mExamples:\x1B[0m\n" : "Examples:\n";
+		const examplesLabel = label("Examples:", "examples") + "\n";
 		output += examplesLabel;
 		const examplesContent = formatMessage(page.examples, {
 			colors: options.colors,
@@ -439,7 +487,7 @@ function formatDocPage(programName, page, options = {}) {
 	}
 	if (hasContent(page.author)) {
 		output += "\n";
-		const authorLabel = options.colors ? "\x1B[1;2mAuthor:\x1B[0m\n" : "Author:\n";
+		const authorLabel = label("Author:", "author") + "\n";
 		output += authorLabel;
 		const authorContent = formatMessage(page.author, {
 			colors: options.colors,
@@ -451,7 +499,7 @@ function formatDocPage(programName, page, options = {}) {
 	}
 	if (hasContent(page.bugs)) {
 		output += "\n";
-		const bugsLabel = options.colors ? "\x1B[1;2mBugs:\x1B[0m\n" : "Bugs:\n";
+		const bugsLabel = label("Bugs:", "bugs") + "\n";
 		output += bugsLabel;
 		const bugsContent = formatMessage(page.bugs, {
 			colors: options.colors,
@@ -480,50 +528,11 @@ function indentLines(text$1, indent) {
 * because they are filtered out before rendering, so they do not
 * contribute to the rendered width.
 */
-function maxVisibleAtomicWidth(usage) {
-	let max = 0;
-	for (const term of usage) switch (term.type) {
-		case "argument":
-			if (!isUsageHidden(term.hidden)) max = Math.max(max, getDisplayWidth(term.metavar));
-			break;
-		case "option":
-			if (!isUsageHidden(term.hidden) && term.names.length > 0) {
-				for (const name of term.names) max = Math.max(max, getDisplayWidth(name));
-				if (term.metavar != null) max = Math.max(max, getDisplayWidth(term.metavar));
-			}
-			break;
-		case "command":
-			if (!isUsageHidden(term.hidden)) max = Math.max(max, getDisplayWidth(term.name));
-			break;
-		case "passthrough":
-			if (!isUsageHidden(term.hidden)) max = Math.max(max, 5);
-			break;
-		case "optional":
-			max = Math.max(max, maxVisibleAtomicWidth(term.terms));
-			break;
-		case "multiple": {
-			const innerMax = maxVisibleAtomicWidth(term.terms);
-			if (innerMax > 0) max = Math.max(max, 3, innerMax);
-			break;
-		}
-		case "exclusive":
-			for (const branch of term.terms) {
-				const first = branch[0];
-				if (first?.type === "command" && isUsageHidden(first.hidden)) continue;
-				max = Math.max(max, maxVisibleAtomicWidth(branch));
-			}
-			break;
-		case "sequence":
-			max = Math.max(max, maxVisibleAtomicWidth(term.terms));
-			break;
-		case "literal":
-			if (term.value !== "") max = Math.max(max, getDisplayWidth(term.value));
-			break;
-		case "ellipsis":
-			max = Math.max(max, 3);
-			break;
-	}
-	return max;
+function maxVisibleAtomicWidth(usage, theme) {
+	return Math.max(0, ...usage.flatMap((term) => formatUsageTerm(term, {
+		theme,
+		maxWidth: 1
+	}).split("\n").map(getDisplayWidth)));
 }
 function ansiAwareRightPad(text$1, length, char = " ") {
 	const visibleWidth = lastLineVisibleLength(text$1);

package/dist/facade.cjs

@@ -1,5 +1,8 @@
 const require_internal_annotations = require('./internal/annotations.cjs');
+const require_displaywidth = require('./displaywidth.cjs');
+const require_terminal_internal = require('./terminal-internal.cjs');
 const require_message = require('./message.cjs');
+const require_message_renderer = require('./message-renderer.cjs');
 const require_validate = require('./validate.cjs');
 const require_usage = require('./usage.cjs');
 const require_doc = require('./doc.cjs');
@@ -513,14 +516,22 @@ function classifyParseFailure(failure, helpOptionNames, helpCommandNames, versio
 * Handles shell completion requests.
 * @since 0.6.0
 */
-function handleCompletion(completionArgs, programName, parser, completionParser, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, termWidth, completionCommandDisplayName, completionOptionDisplayName, isOptionMode, sectionOrder, showUsage, rootOptionSuggestions = []) {
+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.`;
-		stderr(`Error: ${require_message.formatMessage(error, {
+		stderr(`${errorLabel()}${formatMessage(error, {
 			colors,
 			quotes: !colors
 		})}\n`);
@@ -528,6 +539,8 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 			const displayName = isOptionMode ? completionOptionDisplayName ?? "--completion" : completionCommandDisplayName ?? "completion";
 			const doc = require_internal_parser.getDocPage(completionParser, [displayName]);
 			if (doc) stderr(require_doc.formatDocPage(programName, doc, {
+				messageFormatter,
+				theme,
 				colors,
 				maxWidth,
 				termWidth,
@@ -549,7 +562,7 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 			available.push(require_message.value(name));
 		}
 		const error = require_message.message`Unsupported shell ${shellName}. Available shells: ${available}.`;
-		stderr(`Error: ${require_message.formatMessage(error, {
+		stderr(`${errorLabel()}${formatMessage(error, {
 			colors,
 			quotes: !colors
 		})}`);
@@ -860,9 +873,24 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		options = optionsParam ?? {};
 	}
 	require_validate.validateProgramName(programName);
-	const { colors, maxWidth, termWidth, showDefault, showChoices, sectionOrder, showUsage, usageLine, commandList = "recursive", aboveError = "usage", onError = () => {
+	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({
+		type: "label",
+		label: "Usage:",
+		kind: "usageSummary"
+	}, theme, colors) + " ";
+	const usageLabelWidth = () => require_displaywidth.getDisplayWidth(usageLabel());
 	const norm = (c) => c === true ? {} : c;
 	const helpCommandConfig = norm(options.help?.command);
 	const helpOptionConfig = norm(options.help?.option);
@@ -998,7 +1026,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 				classified.shell,
 				...classified.commandPath ?? [],
 				...classified.args
-			], programName, parser, classified.source === "command" ? completionParsers.completionCommand : completionParsers.completionOption, stdout, stderr, onCompletionResult, onErrorResult, availableShells, colors, maxWidth, termWidth, completionCommandNames[0], completionOptionNames[0], classified.source === "option", sectionOrder, showUsage, rootOptionSuggestions);
+			], programName, parser, classified.source === "command" ? completionParsers.completionCommand : completionParsers.completionOption, stdout, stderr, onCompletionResult, onErrorResult, availableShells, colors, maxWidth, termWidth, completionCommandNames[0], completionOptionNames[0], classified.source === "option", sectionOrder, showUsage, rootOptionSuggestions, messageFormatter, theme);
 			case "help": {
 				let helpGeneratorParser;
 				let docGeneratorParser;
@@ -1017,16 +1045,17 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 					docGeneratorParser = classified.commands.length > 0 ? parser : helpGeneratorParser;
 				}
 				const reportInvalidHelpCommand = (validationError) => {
-					stderr(`Usage: ${indentLines(require_usage.formatUsage(programName, augmentedParser.usage, {
+					stderr(`${usageLabel()}${indentLines(require_usage.formatUsage(programName, augmentedParser.usage, {
+						theme,
 						colors,
-						maxWidth: maxWidth == null ? void 0 : maxWidth - 7,
+						maxWidth: maxWidth == null ? void 0 : maxWidth - usageLabelWidth(),
 						expandCommands: true
-					}), 7)}`);
-					const errorMessage = require_message.formatMessage(validationError, {
+					}), usageLabelWidth())}`);
+					const errorMessage = formatMessage(validationError, {
 						colors,
 						quotes: !colors
 					});
-					stderr(`Error: ${errorMessage}`);
+					stderr(`${errorLabel()}${errorMessage}`);
 					return onError(1, validationError);
 				};
 				const displayHelp = (doc) => {
@@ -1046,6 +1075,8 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 						}, commandList, isTopLevel);
 						const renderedDoc = isTopLevel && usageLine != null ? applyUsageLine(augmentedDoc, usageLine) : augmentedDoc;
 						stdout(require_doc.formatDocPage(programName, renderedDoc, {
+							messageFormatter,
+							theme,
 							colors,
 							maxWidth,
 							termWidth,
@@ -1120,6 +1151,8 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 						const defaultRootUsage = typeof usageLine === "function" && (options.help || options.version || options.completion) ? require_usage.normalizeUsage(getRootHelpGeneratorParser().usage) : augmentedDoc.usage ?? [];
 						const renderedDoc = isTopLevel && usageLine != null ? applyUsageLine(augmentedDoc, usageLine, defaultRootUsage) : augmentedDoc;
 						stderr(require_doc.formatDocPage(programName, renderedDoc, {
+							messageFormatter,
+							theme,
 							colors,
 							maxWidth,
 							termWidth,
@@ -1129,16 +1162,17 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							showUsage
 						}));
 					}
-					if (effectiveAboveError === "usage") stderr(`Usage: ${indentLines(require_usage.formatUsage(programName, augmentedParser.usage, {
+					if (effectiveAboveError === "usage") stderr(`${usageLabel()}${indentLines(require_usage.formatUsage(programName, augmentedParser.usage, {
+						theme,
 						colors,
-						maxWidth: maxWidth == null ? void 0 : maxWidth - 7,
+						maxWidth: maxWidth == null ? void 0 : maxWidth - usageLabelWidth(),
 						expandCommands: true
-					}), 7)}`);
-					const errorMessage = require_message.formatMessage(classified.error, {
+					}), usageLabelWidth())}`);
+					const errorMessage = formatMessage(classified.error, {
 						colors,
 						quotes: !colors
 					});
-					stderr(`Error: ${errorMessage}`);
+					stderr(`${errorLabel()}${errorMessage}`);
 					return onError(1, classified.error);
 				};
 				if (aboveError === "help") {

package/dist/facade.d.cts

@@ -1,4 +1,5 @@
-import { Message } from "./message.cjs";
+import { Message, MessageFormatter } from "./message.cjs";
+import { TerminalTheme } from "./terminal.cjs";
 import { HiddenVisibility, OptionName, Usage } from "./usage.cjs";
 import { DocPage, DocSection, ShowChoicesOptions, ShowDefaultOptions } from "./doc.cjs";
 import { InferMode, InferValue, Mode, ModeValue, Parser } from "./internal/parser.cjs";
@@ -78,6 +79,16 @@ interface OptionSubConfig {
  * @template TError The return type when an error occurs.
  */
 interface RunOptions<THelp, TError> {
+  /**
+   * Custom message renderer, taking precedence over theme for messages.
+   * @since 1.3.0
+   */
+  readonly messageFormatter?: MessageFormatter;
+  /**
+   * Semantic terminal theme.
+   * @since 1.3.0
+   */
+  readonly theme?: TerminalTheme;
   /**
    * Enable colored output in help and error messages.
    *

package/dist/facade.d.ts

@@ -1,4 +1,5 @@
-import { Message } from "./message.js";
+import { Message, MessageFormatter } from "./message.js";
+import { TerminalTheme } from "./terminal.js";
 import { HiddenVisibility, OptionName, Usage } from "./usage.js";
 import { DocPage, DocSection, ShowChoicesOptions, ShowDefaultOptions } from "./doc.js";
 import { InferMode, InferValue, Mode, ModeValue, Parser } from "./internal/parser.js";
@@ -78,6 +79,16 @@ interface OptionSubConfig {
  * @template TError The return type when an error occurs.
  */
 interface RunOptions<THelp, TError> {
+  /**
+   * Custom message renderer, taking precedence over theme for messages.
+   * @since 1.3.0
+   */
+  readonly messageFormatter?: MessageFormatter;
+  /**
+   * Semantic terminal theme.
+   * @since 1.3.0
+   */
+  readonly theme?: TerminalTheme;
   /**
    * Enable colored output in help and error messages.
    *

package/dist/facade.js

@@ -1,5 +1,8 @@
 import { injectAnnotations } from "./internal/annotations.js";
-import { commandLine, formatMessage, lineBreak, message, optionName, text, value } from "./message.js";
+import { getDisplayWidth } from "./displaywidth.js";
+import { renderTerminalTerm } from "./terminal-internal.js";
+import { commandLine, lineBreak, message, optionName, text, value } from "./message.js";
+import { resolveMessageFormatter } 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";
@@ -513,14 +516,22 @@ function classifyParseFailure(failure, helpOptionNames, helpCommandNames, versio
 * Handles shell completion requests.
 * @since 0.6.0
 */
-function handleCompletion(completionArgs, programName, parser, completionParser, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, termWidth, completionCommandDisplayName, completionOptionDisplayName, isOptionMode, sectionOrder, showUsage, rootOptionSuggestions = []) {
+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.`;
-		stderr(`Error: ${formatMessage(error, {
+		stderr(`${errorLabel()}${formatMessage(error, {
 			colors,
 			quotes: !colors
 		})}\n`);
@@ -528,6 +539,8 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 			const displayName = isOptionMode ? completionOptionDisplayName ?? "--completion" : completionCommandDisplayName ?? "completion";
 			const doc = getDocPage(completionParser, [displayName]);
 			if (doc) stderr(formatDocPage(programName, doc, {
+				messageFormatter,
+				theme,
 				colors,
 				maxWidth,
 				termWidth,
@@ -549,7 +562,7 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 			available.push(value(name));
 		}
 		const error = message`Unsupported shell ${shellName}. Available shells: ${available}.`;
-		stderr(`Error: ${formatMessage(error, {
+		stderr(`${errorLabel()}${formatMessage(error, {
 			colors,
 			quotes: !colors
 		})}`);
@@ -860,9 +873,24 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		options = optionsParam ?? {};
 	}
 	validateProgramName(programName);
-	const { colors, maxWidth, termWidth, showDefault, showChoices, sectionOrder, showUsage, usageLine, commandList = "recursive", aboveError = "usage", onError = () => {
+	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({
+		type: "label",
+		label: "Usage:",
+		kind: "usageSummary"
+	}, theme, colors) + " ";
+	const usageLabelWidth = () => getDisplayWidth(usageLabel());
 	const norm = (c) => c === true ? {} : c;
 	const helpCommandConfig = norm(options.help?.command);
 	const helpOptionConfig = norm(options.help?.option);
@@ -998,7 +1026,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 				classified.shell,
 				...classified.commandPath ?? [],
 				...classified.args
-			], programName, parser, classified.source === "command" ? completionParsers.completionCommand : completionParsers.completionOption, stdout, stderr, onCompletionResult, onErrorResult, availableShells, colors, maxWidth, termWidth, completionCommandNames[0], completionOptionNames[0], classified.source === "option", sectionOrder, showUsage, rootOptionSuggestions);
+			], programName, parser, classified.source === "command" ? completionParsers.completionCommand : completionParsers.completionOption, stdout, stderr, onCompletionResult, onErrorResult, availableShells, colors, maxWidth, termWidth, completionCommandNames[0], completionOptionNames[0], classified.source === "option", sectionOrder, showUsage, rootOptionSuggestions, messageFormatter, theme);
 			case "help": {
 				let helpGeneratorParser;
 				let docGeneratorParser;
@@ -1017,16 +1045,17 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 					docGeneratorParser = classified.commands.length > 0 ? parser : helpGeneratorParser;
 				}
 				const reportInvalidHelpCommand = (validationError) => {
-					stderr(`Usage: ${indentLines(formatUsage(programName, augmentedParser.usage, {
+					stderr(`${usageLabel()}${indentLines(formatUsage(programName, augmentedParser.usage, {
+						theme,
 						colors,
-						maxWidth: maxWidth == null ? void 0 : maxWidth - 7,
+						maxWidth: maxWidth == null ? void 0 : maxWidth - usageLabelWidth(),
 						expandCommands: true
-					}), 7)}`);
+					}), usageLabelWidth())}`);
 					const errorMessage = formatMessage(validationError, {
 						colors,
 						quotes: !colors
 					});
-					stderr(`Error: ${errorMessage}`);
+					stderr(`${errorLabel()}${errorMessage}`);
 					return onError(1, validationError);
 				};
 				const displayHelp = (doc) => {
@@ -1046,6 +1075,8 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 						}, commandList, isTopLevel);
 						const renderedDoc = isTopLevel && usageLine != null ? applyUsageLine(augmentedDoc, usageLine) : augmentedDoc;
 						stdout(formatDocPage(programName, renderedDoc, {
+							messageFormatter,
+							theme,
 							colors,
 							maxWidth,
 							termWidth,
@@ -1120,6 +1151,8 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 						const defaultRootUsage = typeof usageLine === "function" && (options.help || options.version || options.completion) ? normalizeUsage(getRootHelpGeneratorParser().usage) : augmentedDoc.usage ?? [];
 						const renderedDoc = isTopLevel && usageLine != null ? applyUsageLine(augmentedDoc, usageLine, defaultRootUsage) : augmentedDoc;
 						stderr(formatDocPage(programName, renderedDoc, {
+							messageFormatter,
+							theme,
 							colors,
 							maxWidth,
 							termWidth,
@@ -1129,16 +1162,17 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							showUsage
 						}));
 					}
-					if (effectiveAboveError === "usage") stderr(`Usage: ${indentLines(formatUsage(programName, augmentedParser.usage, {
+					if (effectiveAboveError === "usage") stderr(`${usageLabel()}${indentLines(formatUsage(programName, augmentedParser.usage, {
+						theme,
 						colors,
-						maxWidth: maxWidth == null ? void 0 : maxWidth - 7,
+						maxWidth: maxWidth == null ? void 0 : maxWidth - usageLabelWidth(),
 						expandCommands: true
-					}), 7)}`);
+					}), usageLabelWidth())}`);
 					const errorMessage = formatMessage(classified.error, {
 						colors,
 						quotes: !colors
 					});
-					stderr(`Error: ${errorMessage}`);
+					stderr(`${errorLabel()}${errorMessage}`);
 					return onError(1, classified.error);
 				};
 				if (aboveError === "help") {

package/dist/index.cjs

@@ -1,4 +1,5 @@
 const require_internal_annotations = require('./internal/annotations.cjs');
+const require_terminal = require('./terminal.cjs');
 const require_message = require('./message.cjs');
 const require_usage = require('./usage.cjs');
 const require_doc = require('./doc.cjs');
@@ -31,10 +32,12 @@ exports.commandLine = require_message.commandLine;
 exports.concat = require_constructs.concat;
 exports.conditional = require_constructs.conditional;
 exports.constant = require_primitives.constant;
+exports.createMessageFormatter = require_message.createMessageFormatter;
 exports.createParserContext = require_internal_parser.createParserContext;
 exports.cron = require_valueparser.cron;
 exports.deduplicateDocEntries = require_doc.deduplicateDocEntries;
 exports.deduplicateDocFragments = require_doc.deduplicateDocFragments;
+exports.defaultTerminalTheme = require_terminal.defaultTerminalTheme;
 exports.deferredValue = require_modifiers.deferredValue;
 exports.dependency = require_internal_dependency.dependency;
 exports.deriveFrom = require_internal_dependency.deriveFrom;