@optique/core 1.3.0-dev.2565 → 1.3.0-dev.2567

package/dist/constructs.cjs

@@ -1,7 +1,7 @@
 const require_internal_annotations = require('./internal/annotations.cjs');
-const require_message = require('./message.cjs');
 const require_validate = require('./validate.cjs');
 const require_usage = require('./usage.cjs');
+const require_message = require('./message.cjs');
 const require_doc = require('./doc.cjs');
 const require_mode_dispatch = require('./internal/mode-dispatch.cjs');
 const require_internal_dependency = require('./internal/dependency.cjs');

package/dist/constructs.js

@@ -1,7 +1,7 @@
 import { annotateFreshArray, getAnnotations, inheritAnnotations } from "./internal/annotations.js";
-import { message, optionName, text, values } from "./message.js";
 import { validateLabel } from "./validate.js";
 import { extractArgumentMetavars, extractCommandNames, extractOptionNames, isDocHidden, mergeHidden } from "./usage.js";
+import { message, optionName, text, values } from "./message.js";
 import { deduplicateDocFragments } from "./doc.js";
 import { dispatchByMode, dispatchIterableByMode } from "./internal/mode-dispatch.js";
 import { createDependencySourceState, dependencyId, isDependencySourceState, isPendingDependencySourceState, isWrappedDependencySource, wrappedDependencySourceMarker } from "./internal/dependency.js";

package/dist/doc.cjs

@@ -1,10 +1,11 @@
-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_validate = require('./validate.cjs');
 const require_usage = require('./usage.cjs');
+const require_terminal_width = require('./terminal-width.cjs');
+const require_message_registry = require('./message-registry.cjs');
+const require_message = require('./message.cjs');
+const require_message_renderer = require('./message-renderer.cjs');
 
 //#region src/doc.ts
 /**
@@ -322,11 +323,7 @@ function formatDocPage(programName, page, options = {}) {
 		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 = page.usage != null && showUsage ? Math.max(0, ...[...require_terminal_internal.fragmentTokens(require_terminal_internal.formatTerminalTerm({
-			type: "programName",
-			programName
-		}, options.theme))].map((token) => token.width)) : 0;
-		const usageMin = page.usage != null && showUsage ? Math.max(require_text_layout.measureText(usageLabel).maxLineWidth, usageLabelWidth + Math.max(programNameWidth, Math.min(maxVisibleAtomicWidth(page.usage, options.theme), programNameWidth + usageLabelWidth))) : 1;
+		const usageMin = page.usage != null && showUsage ? require_terminal_width.minimumUsageWidth(programName, page.usage, usageLabel, options.theme) : 1;
 		let sectionMin = 1;
 		for (const kind of [
 			"examples",
@@ -338,16 +335,29 @@ function formatDocPage(programName, page, options = {}) {
 			sectionMin = Math.max(sectionMin, 3, require_text_layout.measureText(label(title, kind)).maxLineWidth);
 		}
 		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) {
+		if (options.maxWidth < minWidth) {
+			if (!require_terminal_width.hasAutomaticWidth(options)) throw new RangeError(`maxWidth must be at least ${minWidth}, got ${options.maxWidth}.`);
+			options = {
+				...options,
+				maxWidth: void 0
+			};
+			effectiveTermWidth = termWidth;
+		}
+		if (options.maxWidth != null && needsDescColumn && minDescWidth > 1) {
 			const avail = options.maxWidth - termIndent - 2;
 			const descW = avail - effectiveTermWidth;
 			if (descW < minDescWidth) {
 				const needed = termIndent + effectiveTermWidth + 2 + minDescWidth;
-				throw new RangeError(`maxWidth must be at least ${needed}, got ${options.maxWidth}.`);
+				if (!require_terminal_width.hasAutomaticWidth(options)) throw new RangeError(`maxWidth must be at least ${needed}, got ${options.maxWidth}.`);
+				options = {
+					...options,
+					maxWidth: void 0
+				};
+				effectiveTermWidth = termWidth;
 			}
 		}
 	}
+	require_terminal_width.reportAutomaticWidth(options, options.maxWidth);
 	let output = "";
 	if (hasContent(page.brief)) {
 		output += formatMessage(page.brief, {
@@ -508,18 +518,6 @@ function formatDocPage(programName, page, options = {}) {
 function indentLines(text$1, indent) {
 	return text$1.split("\n").join("\n" + " ".repeat(indent));
 }
-/**
-* Returns the width of the widest non-breakable segment among visible
-* (non-usage-hidden) terms in a usage tree.  Hidden terms are excluded
-* because they are filtered out before rendering, so they do not
-* contribute to the rendered width.
-*/
-function maxVisibleAtomicWidth(usage, theme) {
-	return usage.reduce((widest, term) => Math.max(widest, require_text_layout.measureText(require_usage.formatUsageTerm(term, {
-		theme,
-		maxWidth: 1
-	})).maxLineWidth), 0);
-}
 function ansiAwareRightPad(text$1, length, char = " ") {
 	const visibleWidth = require_text_layout.measureText(text$1).lastLineWidth;
 	if (visibleWidth >= length) return text$1;

package/dist/doc.js

@@ -1,10 +1,11 @@
-import { messageRenderers } from "./message-registry.js";
-import { cacheTerminalTheme, formatTerminalTerm, fragmentTokens, renderTerminalTerm, styleCode } from "./terminal-internal.js";
+import { cacheTerminalTheme, 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 { validateLabel, validateProgramName } from "./validate.js";
 import { cloneUsageTerm, formatUsage, formatUsageTerm, isDocHidden } from "./usage.js";
+import { hasAutomaticWidth, minimumUsageWidth, reportAutomaticWidth } from "./terminal-width.js";
+import { messageRenderers } from "./message-registry.js";
+import { cloneMessage, text } from "./message.js";
+import { resolveMessageFormatter } from "./message-renderer.js";
 
 //#region src/doc.ts
 /**
@@ -322,11 +323,7 @@ function formatDocPage(programName, page, options = {}) {
 		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 = 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 ? Math.max(measureText(usageLabel).maxLineWidth, usageLabelWidth + Math.max(programNameWidth, Math.min(maxVisibleAtomicWidth(page.usage, options.theme), programNameWidth + usageLabelWidth))) : 1;
+		const usageMin = page.usage != null && showUsage ? minimumUsageWidth(programName, page.usage, usageLabel, options.theme) : 1;
 		let sectionMin = 1;
 		for (const kind of [
 			"examples",
@@ -338,16 +335,29 @@ function formatDocPage(programName, page, options = {}) {
 			sectionMin = Math.max(sectionMin, 3, measureText(label(title, kind)).maxLineWidth);
 		}
 		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) {
+		if (options.maxWidth < minWidth) {
+			if (!hasAutomaticWidth(options)) throw new RangeError(`maxWidth must be at least ${minWidth}, got ${options.maxWidth}.`);
+			options = {
+				...options,
+				maxWidth: void 0
+			};
+			effectiveTermWidth = termWidth;
+		}
+		if (options.maxWidth != null && needsDescColumn && minDescWidth > 1) {
 			const avail = options.maxWidth - termIndent - 2;
 			const descW = avail - effectiveTermWidth;
 			if (descW < minDescWidth) {
 				const needed = termIndent + effectiveTermWidth + 2 + minDescWidth;
-				throw new RangeError(`maxWidth must be at least ${needed}, got ${options.maxWidth}.`);
+				if (!hasAutomaticWidth(options)) throw new RangeError(`maxWidth must be at least ${needed}, got ${options.maxWidth}.`);
+				options = {
+					...options,
+					maxWidth: void 0
+				};
+				effectiveTermWidth = termWidth;
 			}
 		}
 	}
+	reportAutomaticWidth(options, options.maxWidth);
 	let output = "";
 	if (hasContent(page.brief)) {
 		output += formatMessage(page.brief, {
@@ -508,18 +518,6 @@ function formatDocPage(programName, page, options = {}) {
 function indentLines(text$1, indent) {
 	return text$1.split("\n").join("\n" + " ".repeat(indent));
 }
-/**
-* Returns the width of the widest non-breakable segment among visible
-* (non-usage-hidden) terms in a usage tree.  Hidden terms are excluded
-* because they are filtered out before rendering, so they do not
-* contribute to the rendered width.
-*/
-function maxVisibleAtomicWidth(usage, theme) {
-	return usage.reduce((widest, term) => Math.max(widest, measureText(formatUsageTerm(term, {
-		theme,
-		maxWidth: 1
-	})).maxLineWidth), 0);
-}
 function ansiAwareRightPad(text$1, length, char = " ") {
 	const visibleWidth = measureText(text$1).lastLineWidth;
 	if (visibleWidth >= length) return text$1;

package/dist/facade.cjs

@@ -1,10 +1,11 @@
 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_validate = require('./validate.cjs');
 const require_usage = require('./usage.cjs');
+const require_terminal_width = require('./terminal-width.cjs');
+const require_message = require('./message.cjs');
+const require_message_renderer = require('./message-renderer.cjs');
 const require_doc = require('./doc.cjs');
 const require_mode_dispatch = require('./internal/mode-dispatch.cjs');
 const require_dependency_runtime = require('./dependency-runtime.cjs');
@@ -516,24 +517,34 @@ 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 = [], messageFormatter, theme) {
+function handleCompletion(completionArgs, programName, parser, completionParser, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, termWidth, completionCommandDisplayName, completionOptionDisplayName, isOptionMode, sectionOrder, showUsage, rootOptionSuggestions = [], messageFormatter, theme, automaticWidth = false) {
+	const errorOptions = (format) => automaticWidth ? require_terminal_width.withAutomaticWidth(format, (width) => {
+		maxWidth = width;
+	}) : format;
 	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(require_message_renderer.renderErrorMessage(error, {
+		const writeError = () => stderr(require_message_renderer.renderErrorMessage(error, errorOptions({
 			messageFormatter,
 			theme,
 			colors,
 			quotes: !colors,
 			maxWidth
-		}) + "\n");
+		})) + "\n");
+		if (!automaticWidth) writeError();
+		let wroteError = !automaticWidth;
+		const completionDocOptions = (format) => automaticWidth ? require_terminal_width.withAutomaticWidth(format, (width) => {
+			maxWidth = width;
+			writeError();
+			wroteError = true;
+		}) : format;
 		if (completionParser) {
 			const displayName = isOptionMode ? completionOptionDisplayName ?? "--completion" : completionCommandDisplayName ?? "completion";
 			const doc = require_internal_parser.getDocPage(completionParser, [displayName]);
-			if (doc) stderr(require_doc.formatDocPage(programName, doc, {
+			if (doc) stderr(require_doc.formatDocPage(programName, doc, completionDocOptions({
 				messageFormatter,
 				theme,
 				colors,
@@ -541,8 +552,9 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 				termWidth,
 				sectionOrder,
 				showUsage
-			}));
+			})));
 		}
+		if (!wroteError) writeError();
 		return require_mode_dispatch.dispatchByMode(parser.mode, () => {
 			const result = callOnError(1, error);
 			if (result instanceof Promise) throw new RunParserError("Synchronous parser returned async result.");
@@ -557,13 +569,13 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 			available.push(require_message.value(name));
 		}
 		const error = require_message.message`Unsupported shell ${shellName}. Available shells: ${available}.`;
-		stderr(require_message_renderer.renderErrorMessage(error, {
+		stderr(require_message_renderer.renderErrorMessage(error, errorOptions({
 			messageFormatter,
 			theme,
 			colors,
 			quotes: !colors,
 			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.");
@@ -871,9 +883,18 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		options = optionsParam ?? {};
 	}
 	require_validate.validateProgramName(programName);
-	const { colors, messageFormatter, theme, maxWidth, termWidth, showDefault, showChoices, sectionOrder, showUsage, usageLine, commandList = "recursive", aboveError = "usage", onError = () => {
+	const { colors, messageFormatter, theme: requestedTheme, maxWidth: requestedMaxWidth, 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;
+	let maxWidth = requestedMaxWidth;
+	const automaticWidth = require_terminal_width.hasAutomaticWidth(options);
+	const theme = automaticWidth ? require_terminal_internal.cacheTerminalTheme(requestedTheme) : requestedTheme;
+	const formatOptions = (format) => automaticWidth ? require_terminal_width.withAutomaticWidth(format, (width) => {
+		maxWidth = width;
+	}) : format;
+	const resolveUsageWidth = (usage) => {
+		if (automaticWidth && maxWidth != null && maxWidth < require_terminal_width.minimumUsageWidth(programName, usage, usageLabel(), theme)) maxWidth = void 0;
+	};
 	let usagePrefix;
 	const usageLabel = () => usagePrefix ??= require_text_layout.spaceAfterLabel(require_terminal_internal.renderTerminalTerm({
 		type: "label",
@@ -1016,7 +1037,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, messageFormatter, theme);
+			], 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, automaticWidth);
 			case "help": {
 				let helpGeneratorParser;
 				let docGeneratorParser;
@@ -1035,19 +1056,20 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 					docGeneratorParser = classified.commands.length > 0 ? parser : helpGeneratorParser;
 				}
 				const reportInvalidHelpCommand = (validationError) => {
+					resolveUsageWidth(augmentedParser.usage);
 					stderr(`${usageLabel()}${indentLines(require_usage.formatUsage(programName, augmentedParser.usage, {
 						theme,
 						colors,
 						maxWidth: maxWidth == null ? void 0 : maxWidth - usageLabelWidth(),
 						expandCommands: true
 					}), usageLabelWidth())}`);
-					stderr(require_message_renderer.renderErrorMessage(validationError, {
+					stderr(require_message_renderer.renderErrorMessage(validationError, formatOptions({
 						messageFormatter,
 						theme,
 						colors,
 						quotes: !colors,
 						maxWidth
-					}));
+					})));
 					return onError(1, validationError);
 				};
 				const displayHelp = (doc) => {
@@ -1066,7 +1088,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							footer: shouldOverride ? footer ?? doc.footer : doc.footer ?? footer
 						}, commandList, isTopLevel);
 						const renderedDoc = isTopLevel && usageLine != null ? applyUsageLine(augmentedDoc, usageLine) : augmentedDoc;
-						stdout(require_doc.formatDocPage(programName, renderedDoc, {
+						stdout(require_doc.formatDocPage(programName, renderedDoc, formatOptions({
 							messageFormatter,
 							theme,
 							colors,
@@ -1076,7 +1098,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							showChoices,
 							sectionOrder,
 							showUsage
-						}));
+						})));
 						return onHelp(0, renderedDoc);
 					}
 					throw new RunParserError("Failed to generate help page.");
@@ -1142,7 +1164,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 						}, commandList, isTopLevel);
 						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, {
+						stderr(require_doc.formatDocPage(programName, renderedDoc, formatOptions({
 							messageFormatter,
 							theme,
 							colors,
@@ -1152,21 +1174,24 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							showChoices,
 							sectionOrder,
 							showUsage
-						}));
+						})));
 					}
-					if (effectiveAboveError === "usage") stderr(`${usageLabel()}${indentLines(require_usage.formatUsage(programName, augmentedParser.usage, {
-						theme,
-						colors,
-						maxWidth: maxWidth == null ? void 0 : maxWidth - usageLabelWidth(),
-						expandCommands: true
-					}), usageLabelWidth())}`);
-					stderr(require_message_renderer.renderErrorMessage(classified.error, {
+					if (effectiveAboveError === "usage") {
+						resolveUsageWidth(augmentedParser.usage);
+						stderr(`${usageLabel()}${indentLines(require_usage.formatUsage(programName, augmentedParser.usage, {
+							theme,
+							colors,
+							maxWidth: maxWidth == null ? void 0 : maxWidth - usageLabelWidth(),
+							expandCommands: true
+						}), usageLabelWidth())}`);
+					}
+					stderr(require_message_renderer.renderErrorMessage(classified.error, formatOptions({
 						messageFormatter,
 						theme,
 						colors,
 						quotes: !colors,
 						maxWidth
-					}));
+					})));
 					return onError(1, classified.error);
 				};
 				if (aboveError === "help") {

package/dist/facade.js

@@ -1,10 +1,11 @@
 import { injectAnnotations } from "./internal/annotations.js";
-import { renderTerminalTerm } from "./terminal-internal.js";
+import { cacheTerminalTheme, renderTerminalTerm } from "./terminal-internal.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 { hasAutomaticWidth, minimumUsageWidth, withAutomaticWidth } from "./terminal-width.js";
+import { commandLine, lineBreak, message, optionName, text, value } from "./message.js";
+import { renderErrorMessage } from "./message-renderer.js";
 import { formatDocPage } from "./doc.js";
 import { dispatchByMode } from "./internal/mode-dispatch.js";
 import { collectExplicitSourceValues, collectExplicitSourceValuesAsync, createDependencyRuntimeContext } from "./dependency-runtime.js";
@@ -516,24 +517,34 @@ 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 = [], messageFormatter, theme) {
+function handleCompletion(completionArgs, programName, parser, completionParser, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, termWidth, completionCommandDisplayName, completionOptionDisplayName, isOptionMode, sectionOrder, showUsage, rootOptionSuggestions = [], messageFormatter, theme, automaticWidth = false) {
+	const errorOptions = (format) => automaticWidth ? withAutomaticWidth(format, (width) => {
+		maxWidth = width;
+	}) : format;
 	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(renderErrorMessage(error, {
+		const writeError = () => stderr(renderErrorMessage(error, errorOptions({
 			messageFormatter,
 			theme,
 			colors,
 			quotes: !colors,
 			maxWidth
-		}) + "\n");
+		})) + "\n");
+		if (!automaticWidth) writeError();
+		let wroteError = !automaticWidth;
+		const completionDocOptions = (format) => automaticWidth ? withAutomaticWidth(format, (width) => {
+			maxWidth = width;
+			writeError();
+			wroteError = true;
+		}) : format;
 		if (completionParser) {
 			const displayName = isOptionMode ? completionOptionDisplayName ?? "--completion" : completionCommandDisplayName ?? "completion";
 			const doc = getDocPage(completionParser, [displayName]);
-			if (doc) stderr(formatDocPage(programName, doc, {
+			if (doc) stderr(formatDocPage(programName, doc, completionDocOptions({
 				messageFormatter,
 				theme,
 				colors,
@@ -541,8 +552,9 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 				termWidth,
 				sectionOrder,
 				showUsage
-			}));
+			})));
 		}
+		if (!wroteError) writeError();
 		return dispatchByMode(parser.mode, () => {
 			const result = callOnError(1, error);
 			if (result instanceof Promise) throw new RunParserError("Synchronous parser returned async result.");
@@ -557,13 +569,13 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 			available.push(value(name));
 		}
 		const error = message`Unsupported shell ${shellName}. Available shells: ${available}.`;
-		stderr(renderErrorMessage(error, {
+		stderr(renderErrorMessage(error, errorOptions({
 			messageFormatter,
 			theme,
 			colors,
 			quotes: !colors,
 			maxWidth
-		}));
+		})));
 		return dispatchByMode(parser.mode, () => {
 			const result = callOnError(1, error);
 			if (result instanceof Promise) throw new RunParserError("Synchronous parser returned async result.");
@@ -871,9 +883,18 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		options = optionsParam ?? {};
 	}
 	validateProgramName(programName);
-	const { colors, messageFormatter, theme, maxWidth, termWidth, showDefault, showChoices, sectionOrder, showUsage, usageLine, commandList = "recursive", aboveError = "usage", onError = () => {
+	const { colors, messageFormatter, theme: requestedTheme, maxWidth: requestedMaxWidth, 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;
+	let maxWidth = requestedMaxWidth;
+	const automaticWidth = hasAutomaticWidth(options);
+	const theme = automaticWidth ? cacheTerminalTheme(requestedTheme) : requestedTheme;
+	const formatOptions = (format) => automaticWidth ? withAutomaticWidth(format, (width) => {
+		maxWidth = width;
+	}) : format;
+	const resolveUsageWidth = (usage) => {
+		if (automaticWidth && maxWidth != null && maxWidth < minimumUsageWidth(programName, usage, usageLabel(), theme)) maxWidth = void 0;
+	};
 	let usagePrefix;
 	const usageLabel = () => usagePrefix ??= spaceAfterLabel(renderTerminalTerm({
 		type: "label",
@@ -1016,7 +1037,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, messageFormatter, theme);
+			], 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, automaticWidth);
 			case "help": {
 				let helpGeneratorParser;
 				let docGeneratorParser;
@@ -1035,19 +1056,20 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 					docGeneratorParser = classified.commands.length > 0 ? parser : helpGeneratorParser;
 				}
 				const reportInvalidHelpCommand = (validationError) => {
+					resolveUsageWidth(augmentedParser.usage);
 					stderr(`${usageLabel()}${indentLines(formatUsage(programName, augmentedParser.usage, {
 						theme,
 						colors,
 						maxWidth: maxWidth == null ? void 0 : maxWidth - usageLabelWidth(),
 						expandCommands: true
 					}), usageLabelWidth())}`);
-					stderr(renderErrorMessage(validationError, {
+					stderr(renderErrorMessage(validationError, formatOptions({
 						messageFormatter,
 						theme,
 						colors,
 						quotes: !colors,
 						maxWidth
-					}));
+					})));
 					return onError(1, validationError);
 				};
 				const displayHelp = (doc) => {
@@ -1066,7 +1088,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							footer: shouldOverride ? footer ?? doc.footer : doc.footer ?? footer
 						}, commandList, isTopLevel);
 						const renderedDoc = isTopLevel && usageLine != null ? applyUsageLine(augmentedDoc, usageLine) : augmentedDoc;
-						stdout(formatDocPage(programName, renderedDoc, {
+						stdout(formatDocPage(programName, renderedDoc, formatOptions({
 							messageFormatter,
 							theme,
 							colors,
@@ -1076,7 +1098,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							showChoices,
 							sectionOrder,
 							showUsage
-						}));
+						})));
 						return onHelp(0, renderedDoc);
 					}
 					throw new RunParserError("Failed to generate help page.");
@@ -1142,7 +1164,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 						}, commandList, isTopLevel);
 						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, {
+						stderr(formatDocPage(programName, renderedDoc, formatOptions({
 							messageFormatter,
 							theme,
 							colors,
@@ -1152,21 +1174,24 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							showChoices,
 							sectionOrder,
 							showUsage
-						}));
+						})));
 					}
-					if (effectiveAboveError === "usage") stderr(`${usageLabel()}${indentLines(formatUsage(programName, augmentedParser.usage, {
-						theme,
-						colors,
-						maxWidth: maxWidth == null ? void 0 : maxWidth - usageLabelWidth(),
-						expandCommands: true
-					}), usageLabelWidth())}`);
-					stderr(renderErrorMessage(classified.error, {
+					if (effectiveAboveError === "usage") {
+						resolveUsageWidth(augmentedParser.usage);
+						stderr(`${usageLabel()}${indentLines(formatUsage(programName, augmentedParser.usage, {
+							theme,
+							colors,
+							maxWidth: maxWidth == null ? void 0 : maxWidth - usageLabelWidth(),
+							expandCommands: true
+						}), usageLabelWidth())}`);
+					}
+					stderr(renderErrorMessage(classified.error, formatOptions({
 						messageFormatter,
 						theme,
 						colors,
 						quotes: !colors,
 						maxWidth
-					}));
+					})));
 					return onError(1, classified.error);
 				};
 				if (aboveError === "help") {

package/dist/index.cjs

@@ -1,7 +1,7 @@
 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_message = require('./message.cjs');
 const require_doc = require('./doc.cjs');
 const require_internal_dependency = require('./internal/dependency.cjs');
 const require_internal_parser = require('./internal/parser.cjs');

package/dist/index.js

@@ -1,7 +1,7 @@
 import { getAnnotations } from "./internal/annotations.js";
 import { defaultTerminalTheme } from "./terminal.js";
-import { commandLine, createMessageFormatter, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.js";
 import { cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.js";
+import { commandLine, createMessageFormatter, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.js";
 import { cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage, isDocEntryHidden } from "./doc.js";
 import { dependency, deriveFrom, deriveFromAsync, deriveFromSync, getDependencySourceInfo, isDependencySource, isDerivedValueParser } from "./internal/dependency.js";
 import { createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseDetailed, parseSync, suggest, suggestAsync, suggestSync } from "./internal/parser.js";

package/dist/internal/parser.cjs

@@ -1,6 +1,6 @@
 const require_internal_annotations = require('./annotations.cjs');
-const require_message = require('../message.cjs');
 const require_usage = require('../usage.cjs');
+const require_message = require('../message.cjs');
 const require_doc = require('../doc.cjs');
 const require_mode_dispatch = require('./mode-dispatch.cjs');
 const require_dependency_runtime = require('../dependency-runtime.cjs');

package/dist/internal/parser.js

@@ -1,6 +1,6 @@
 import { hasMeaningfulAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper } from "./annotations.js";
-import { cloneMessage, message } from "../message.js";
 import { cloneUsage, normalizeUsage } from "../usage.js";
+import { cloneMessage, message } from "../message.js";
 import { cloneDocEntry, isDocEntryHidden } from "../doc.js";
 import { dispatchByMode, dispatchParserByMode } from "./mode-dispatch.js";
 import { collectExplicitSourceValues, collectExplicitSourceValuesAsync, createDependencyRuntimeContext } from "../dependency-runtime.js";

package/dist/internal/terminal.cjs

@@ -1,6 +1,7 @@
 const require_displaywidth = require('../displaywidth.cjs');
 const require_terminal_internal = require('../terminal-internal.cjs');
 const require_text_layout = require('../text-layout.cjs');
+const require_terminal_width = require('../terminal-width.cjs');
 const require_message_renderer = require('../message-renderer.cjs');
 
 exports.getDisplayWidth = require_displaywidth.getDisplayWidth;
@@ -9,4 +10,5 @@ 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;
+exports.spaceAfterLabel = require_text_layout.spaceAfterLabel;
+exports.withAutomaticWidth = require_terminal_width.withAutomaticWidth;

package/dist/internal/terminal.d.cts

@@ -2,4 +2,5 @@ import { getDisplayWidth } from "../displaywidth.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, renderErrorMessage, renderTerminalTerm, resolveMessageFormatter, spaceAfterLabel };
+import { withAutomaticWidth } from "../terminal-width.cjs";
+export { getDisplayWidth, measureText, placeText, renderErrorMessage, renderTerminalTerm, resolveMessageFormatter, spaceAfterLabel, withAutomaticWidth };

package/dist/internal/terminal.d.ts

@@ -2,4 +2,5 @@ import { getDisplayWidth } from "../displaywidth.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, renderErrorMessage, renderTerminalTerm, resolveMessageFormatter, spaceAfterLabel };
+import { withAutomaticWidth } from "../terminal-width.js";
+export { getDisplayWidth, measureText, placeText, renderErrorMessage, renderTerminalTerm, resolveMessageFormatter, spaceAfterLabel, withAutomaticWidth };

package/dist/internal/terminal.js

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

package/dist/message-renderer.cjs

@@ -1,6 +1,7 @@
-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_terminal_width = require('./terminal-width.cjs');
+const require_message_registry = require('./message-registry.cjs');
 const require_message = require('./message.cjs');
 
 //#region src/message-renderer.ts
@@ -39,10 +40,19 @@ function renderErrorMessage(message, options = {}) {
 	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({
+	const label = 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)), {
+	}, options.theme, typeof colors === "object" ? true : colors, void 0, void 0, typeof colors === "object" ? colors.resetSuffix : void 0));
+	if (require_terminal_width.hasAutomaticWidth(options) && options.maxWidth != null) {
+		const size = require_text_layout.measureText(label);
+		if (options.maxWidth < Math.max(size.maxLineWidth, occupied + size.lastLineWidth + 1)) options = {
+			...options,
+			maxWidth: void 0
+		};
+	}
+	require_terminal_width.reportAutomaticWidth(options, options.maxWidth);
+	const prefix = require_text_layout.placeText(label, {
 		line: "",
 		column: occupied
 	}, options.maxWidth);

package/dist/message-renderer.js

@@ -1,6 +1,7 @@
-import { messageRenderers } from "./message-registry.js";
 import { renderTerminalTerm } from "./terminal-internal.js";
-import { placeText, spaceAfterLabel } from "./text-layout.js";
+import { measureText, placeText, spaceAfterLabel } from "./text-layout.js";
+import { hasAutomaticWidth, reportAutomaticWidth } from "./terminal-width.js";
+import { messageRenderers } from "./message-registry.js";
 import { createMessageFormatter, formatMessage } from "./message.js";
 
 //#region src/message-renderer.ts
@@ -39,10 +40,19 @@ function renderErrorMessage(message, options = {}) {
 	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({
+	const label = spaceAfterLabel(renderTerminalTerm({
 		type: "errorLabel",
 		label: "Error:"
-	}, options.theme, typeof colors === "object" ? true : colors, void 0, void 0, typeof colors === "object" ? colors.resetSuffix : void 0)), {
+	}, options.theme, typeof colors === "object" ? true : colors, void 0, void 0, typeof colors === "object" ? colors.resetSuffix : void 0));
+	if (hasAutomaticWidth(options) && options.maxWidth != null) {
+		const size = measureText(label);
+		if (options.maxWidth < Math.max(size.maxLineWidth, occupied + size.lastLineWidth + 1)) options = {
+			...options,
+			maxWidth: void 0
+		};
+	}
+	reportAutomaticWidth(options, options.maxWidth);
+	const prefix = placeText(label, {
 		line: "",
 		column: occupied
 	}, options.maxWidth);

package/dist/message.cjs

@@ -1,6 +1,6 @@
-const require_message_registry = require('./message-registry.cjs');
 const require_displaywidth = require('./displaywidth.cjs');
 const require_terminal_internal = require('./terminal-internal.cjs');
+const require_message_registry = require('./message-registry.cjs');
 
 //#region src/message.ts
 /**

package/dist/message.js

@@ -1,6 +1,6 @@
-import { messageRenderers } from "./message-registry.js";
 import { getDisplayWidth } from "./displaywidth.js";
 import { formatTerminalTerm, fragmentTokens, serializeTokens } from "./terminal-internal.js";
+import { messageRenderers } from "./message-registry.js";
 
 //#region src/message.ts
 /**

package/dist/primitives.cjs

@@ -1,7 +1,7 @@
 const require_internal_annotations = require('./internal/annotations.cjs');
-const require_message = require('./message.cjs');
 const require_validate = require('./validate.cjs');
 const require_usage = require('./usage.cjs');
+const require_message = require('./message.cjs');
 const require_mode_dispatch = require('./internal/mode-dispatch.cjs');
 const require_internal_dependency = require('./internal/dependency.cjs');
 const require_dependency_runtime = require('./dependency-runtime.cjs');

package/dist/primitives.js

@@ -1,7 +1,7 @@
 import { annotateFreshArray, getAnnotations } from "./internal/annotations.js";
-import { message, metavar, optionName, optionNames, text, valueSet } from "./message.js";
 import { validateCommandNames, validateOptionNames } from "./validate.js";
 import { extractOptionNames, isDocHidden, isSuggestionHidden } from "./usage.js";
+import { message, metavar, optionName, optionNames, text, valueSet } from "./message.js";
 import { dispatchByMode, dispatchIterableByMode, wrapForMode } from "./internal/mode-dispatch.js";
 import { getDefaultValuesFunction, getDependencyIds, getSnapshottedDefaultDependencyValues, isDerivedValueParser, suggestWithDependency } from "./internal/dependency.js";
 import { effectfulSchedulingNodesKey, exclusiveSourceScopeKey, includeSourceFailureChain, recordDerivedRawInput, replayDerivedParser, replayDerivedParserAsync, sourceCollectionExpansionKey } from "./dependency-runtime.js";

package/dist/suggestion.cjs

@@ -1,5 +1,5 @@
-const require_message = require('./message.cjs');
 const require_usage = require('./usage.cjs');
+const require_message = require('./message.cjs');
 
 //#region src/suggestion.ts
 /**

package/dist/suggestion.js

@@ -1,5 +1,5 @@
-import { lineBreak, message, optionName, text, value } from "./message.js";
 import { extractCommandNames, extractOptionNames, isSuggestionHidden } from "./usage.js";
+import { lineBreak, message, optionName, text, value } from "./message.js";
 
 //#region src/suggestion.ts
 /**

package/dist/terminal-width.cjs

@@ -0,0 +1,65 @@
+const require_terminal_internal = require('./terminal-internal.cjs');
+const require_text_layout = require('./text-layout.cjs');
+const require_usage = require('./usage.cjs');
+
+//#region src/terminal-width.ts
+const automaticWidth = Symbol.for("@optique/core/automaticWidth");
+/**
+* Marks runner options without changing their public type. The enumerable
+* symbol survives the option copies made by Program and context runners.
+* @param options The options whose width was automatically detected.
+* @param onResolved Receives the effective width before message rendering.
+* @returns A marked copy of the options.
+* @internal
+*/
+function withAutomaticWidth(options, onResolved = () => {}) {
+	return {
+		...options,
+		[automaticWidth]: onResolved
+	};
+}
+/**
+* Checks whether a width is a runner hint rather than an explicit constraint.
+* @param options The formatting or runner options.
+* @returns Whether automatic width fallback is enabled.
+* @internal
+*/
+function hasAutomaticWidth(options) {
+	return automaticWidth in options && typeof options[automaticWidth] === "function";
+}
+/**
+* Reports the resolved width before any opaque message formatter runs.
+* @param options The marked formatting options.
+* @param width The width selected by layout validation.
+* @internal
+*/
+function reportAutomaticWidth(options, width) {
+	if (automaticWidth in options && typeof options[automaticWidth] === "function") options[automaticWidth](width);
+}
+/**
+* Measures the minimum usage layout, allowing long atomic terms to overflow.
+* @param programName The program name shown in the usage line.
+* @param usage The visible usage tree.
+* @param label The rendered usage label, including its trailing space.
+* @param theme The semantic terminal theme.
+* @returns The minimum feasible width for the usage block.
+* @internal
+*/
+function minimumUsageWidth(programName, usage, label, theme) {
+	const labelWidth = require_text_layout.measureText(label).lastLineWidth;
+	const programWidth = Math.max(0, ...[...require_terminal_internal.fragmentTokens(require_terminal_internal.formatTerminalTerm({
+		type: "programName",
+		programName
+	}, theme))].map((token) => token.width));
+	const atomicWidth = usage.reduce((widest, term) => Math.max(widest, require_text_layout.measureText(require_usage.formatUsageTerm(term, {
+		theme,
+		maxWidth: 1
+	})).maxLineWidth), 0);
+	return Math.max(require_text_layout.measureText(label).maxLineWidth, labelWidth + Math.max(programWidth, Math.min(atomicWidth, programWidth + labelWidth)));
+}
+
+//#endregion
+exports.hasAutomaticWidth = hasAutomaticWidth;
+exports.minimumUsageWidth = minimumUsageWidth;
+exports.reportAutomaticWidth = reportAutomaticWidth;
+exports.withAutomaticWidth = withAutomaticWidth;

package/dist/terminal-width.d.cts

@@ -0,0 +1,19 @@
+//#region src/terminal-width.d.ts
+
+/**
+ * Marks runner options without changing their public type. The enumerable
+ * symbol survives the option copies made by Program and context runners.
+ * @param options The options whose width was automatically detected.
+ * @param onResolved Receives the effective width before message rendering.
+ * @returns A marked copy of the options.
+ * @internal
+ */
+declare function withAutomaticWidth<T extends object>(options: T, onResolved?: (width: number | undefined) => void): T;
+/**
+ * Checks whether a width is a runner hint rather than an explicit constraint.
+ * @param options The formatting or runner options.
+ * @returns Whether automatic width fallback is enabled.
+ * @internal
+ */
+//#endregion
+export { withAutomaticWidth };

package/dist/terminal-width.d.ts

@@ -0,0 +1,19 @@
+//#region src/terminal-width.d.ts
+
+/**
+ * Marks runner options without changing their public type. The enumerable
+ * symbol survives the option copies made by Program and context runners.
+ * @param options The options whose width was automatically detected.
+ * @param onResolved Receives the effective width before message rendering.
+ * @returns A marked copy of the options.
+ * @internal
+ */
+declare function withAutomaticWidth<T extends object>(options: T, onResolved?: (width: number | undefined) => void): T;
+/**
+ * Checks whether a width is a runner hint rather than an explicit constraint.
+ * @param options The formatting or runner options.
+ * @returns Whether automatic width fallback is enabled.
+ * @internal
+ */
+//#endregion
+export { withAutomaticWidth };

package/dist/terminal-width.js

@@ -0,0 +1,62 @@
+import { formatTerminalTerm, fragmentTokens } from "./terminal-internal.js";
+import { measureText } from "./text-layout.js";
+import { formatUsageTerm } from "./usage.js";
+
+//#region src/terminal-width.ts
+const automaticWidth = Symbol.for("@optique/core/automaticWidth");
+/**
+* Marks runner options without changing their public type. The enumerable
+* symbol survives the option copies made by Program and context runners.
+* @param options The options whose width was automatically detected.
+* @param onResolved Receives the effective width before message rendering.
+* @returns A marked copy of the options.
+* @internal
+*/
+function withAutomaticWidth(options, onResolved = () => {}) {
+	return {
+		...options,
+		[automaticWidth]: onResolved
+	};
+}
+/**
+* Checks whether a width is a runner hint rather than an explicit constraint.
+* @param options The formatting or runner options.
+* @returns Whether automatic width fallback is enabled.
+* @internal
+*/
+function hasAutomaticWidth(options) {
+	return automaticWidth in options && typeof options[automaticWidth] === "function";
+}
+/**
+* Reports the resolved width before any opaque message formatter runs.
+* @param options The marked formatting options.
+* @param width The width selected by layout validation.
+* @internal
+*/
+function reportAutomaticWidth(options, width) {
+	if (automaticWidth in options && typeof options[automaticWidth] === "function") options[automaticWidth](width);
+}
+/**
+* Measures the minimum usage layout, allowing long atomic terms to overflow.
+* @param programName The program name shown in the usage line.
+* @param usage The visible usage tree.
+* @param label The rendered usage label, including its trailing space.
+* @param theme The semantic terminal theme.
+* @returns The minimum feasible width for the usage block.
+* @internal
+*/
+function minimumUsageWidth(programName, usage, label, theme) {
+	const labelWidth = measureText(label).lastLineWidth;
+	const programWidth = Math.max(0, ...[...fragmentTokens(formatTerminalTerm({
+		type: "programName",
+		programName
+	}, theme))].map((token) => token.width));
+	const atomicWidth = usage.reduce((widest, term) => Math.max(widest, measureText(formatUsageTerm(term, {
+		theme,
+		maxWidth: 1
+	})).maxLineWidth), 0);
+	return Math.max(measureText(label).maxLineWidth, labelWidth + Math.max(programWidth, Math.min(atomicWidth, programWidth + labelWidth)));
+}
+
+//#endregion
+export { hasAutomaticWidth, minimumUsageWidth, reportAutomaticWidth, withAutomaticWidth };

package/package.json

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