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

package/dist/displaywidth.cjs

@@ -1,6 +1,15 @@
 
 //#region src/displaywidth.ts
 const ansiRegex = /\x1B(?:\[[0-9;:]*[@-~]|\][^\x1B\x07]*(?:\x1B\\|\x07))/g;
+/**
+* Removes ANSI CSI and OSC sequences before measuring visible text.
+* @param text Rendered terminal text.
+* @returns Text without terminal escape sequences.
+* @internal
+*/
+function stripAnsi(text) {
+	return text.replace(ansiRegex, "");
+}
 const segmenter = new Intl.Segmenter(void 0, { granularity: "grapheme" });
 /**
 * Computes the terminal display width of a string, accounting for
@@ -11,7 +20,7 @@ const segmenter = new Intl.Segmenter(void 0, { granularity: "grapheme" });
 * @internal
 */
 function getDisplayWidth(text) {
-	const stripped = text.replace(ansiRegex, "");
+	const stripped = stripAnsi(text);
 	let width = 0;
 	for (const { segment } of segmenter.segment(stripped)) width += graphemeWidth(segment);
 	return width;
@@ -41,4 +50,5 @@ function isEastAsianWide(cp) {
 }
 
 //#endregion
-exports.getDisplayWidth = getDisplayWidth;
+exports.getDisplayWidth = getDisplayWidth;
+exports.stripAnsi = stripAnsi;

package/dist/displaywidth.d.cts

@@ -1,4 +1,11 @@
 //#region src/displaywidth.d.ts
+/**
+ * Removes ANSI CSI and OSC sequences before measuring visible text.
+ * @param text Rendered terminal text.
+ * @returns Text without terminal escape sequences.
+ * @internal
+ */
+declare function stripAnsi(text: string): string;
 /**
  * Computes the terminal display width of a string, accounting for
  * East Asian wide characters, combining marks, emoji, and ANSI escapes.
@@ -9,4 +16,4 @@
  */
 declare function getDisplayWidth(text: string): number;
 //#endregion
-export { getDisplayWidth };
+export { getDisplayWidth, stripAnsi };

package/dist/displaywidth.d.ts

@@ -1,4 +1,11 @@
 //#region src/displaywidth.d.ts
+/**
+ * Removes ANSI CSI and OSC sequences before measuring visible text.
+ * @param text Rendered terminal text.
+ * @returns Text without terminal escape sequences.
+ * @internal
+ */
+declare function stripAnsi(text: string): string;
 /**
  * Computes the terminal display width of a string, accounting for
  * East Asian wide characters, combining marks, emoji, and ANSI escapes.
@@ -9,4 +16,4 @@
  */
 declare function getDisplayWidth(text: string): number;
 //#endregion
-export { getDisplayWidth };
+export { getDisplayWidth, stripAnsi };

package/dist/displaywidth.js

@@ -1,5 +1,14 @@
 //#region src/displaywidth.ts
 const ansiRegex = /\x1B(?:\[[0-9;:]*[@-~]|\][^\x1B\x07]*(?:\x1B\\|\x07))/g;
+/**
+* Removes ANSI CSI and OSC sequences before measuring visible text.
+* @param text Rendered terminal text.
+* @returns Text without terminal escape sequences.
+* @internal
+*/
+function stripAnsi(text) {
+	return text.replace(ansiRegex, "");
+}
 const segmenter = new Intl.Segmenter(void 0, { granularity: "grapheme" });
 /**
 * Computes the terminal display width of a string, accounting for
@@ -10,7 +19,7 @@ const segmenter = new Intl.Segmenter(void 0, { granularity: "grapheme" });
 * @internal
 */
 function getDisplayWidth(text) {
-	const stripped = text.replace(ansiRegex, "");
+	const stripped = stripAnsi(text);
 	let width = 0;
 	for (const { segment } of segmenter.segment(stripped)) width += graphemeWidth(segment);
 	return width;
@@ -40,4 +49,4 @@ function isEastAsianWide(cp) {
 }
 
 //#endregion
-export { getDisplayWidth };
+export { getDisplayWidth, stripAnsi };

package/dist/doc.cjs

@@ -1,8 +1,8 @@
 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 = 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');
 
@@ -251,8 +251,8 @@ function formatDocPage(programName, page, options = {}) {
 		}
 		return rendered;
 	};
-	const usageLabel = page.usage != null && options.showUsage !== false ? label("Usage:", "usage") + " " : "";
-	const usageLabelWidth = require_displaywidth.getDisplayWidth(usageLabel.split("\n").at(-1) ?? "");
+	const usageLabel = page.usage != null && options.showUsage !== false ? require_text_layout.spaceAfterLabel(label("Usage:", "usage")) : "";
+	const usageLabelWidth = require_text_layout.measureText(usageLabel).lastLineWidth;
 	const defaultStyle = require_terminal_internal.styleCode(options.theme?.annotationStyles?.default ?? { dim: true });
 	const choicesStyle = require_terminal_internal.styleCode(options.theme?.annotationStyles?.choices ?? { dim: true });
 	require_validate.validateProgramName(programName);
@@ -276,6 +276,18 @@ function formatDocPage(programName, page, options = {}) {
 	}
 	const hasContent = (msg) => Array.isArray(msg) && msg.length > 0;
 	const needsDescriptionColumn = (entry) => hasContent(entry.description) || (options.showDefault === true || typeof options.showDefault === "object") && hasContent(entry.default) || (options.showChoices === true || typeof options.showChoices === "object") && hasContent(entry.choices);
+	const annotations = /* @__PURE__ */ new Map();
+	const annotation = (kind) => {
+		const cached = annotations.get(kind);
+		if (cached != null) return cached;
+		const config = kind === "default" ? options.showDefault : options.showChoices;
+		const prefix = punctuation(typeof config === "object" ? config.prefix ?? (kind === "default" ? " [" : " (") : kind === "default" ? " [" : " (", kind === "default" ? "defaultPrefix" : "choicesPrefix");
+		const suffix = punctuation(typeof config === "object" ? config.suffix ?? (kind === "default" ? "]" : ")") : kind === "default" ? "]" : ")", kind === "default" ? "defaultSuffix" : "choicesSuffix");
+		const choicesLabel = kind === "choices" ? label(typeof options.showChoices === "object" ? options.showChoices.label ?? "choices: " : "choices: ", "choices") : "";
+		const layout = require_text_layout.measureAnnotation(prefix + choicesLabel, suffix);
+		annotations.set(kind, layout);
+		return layout;
+	};
 	const automaticTermWidth = () => {
 		let widest;
 		for (const section of page.sections) for (const entry of section.entries) {
@@ -286,7 +298,7 @@ function formatDocPage(programName, page, options = {}) {
 				optionsSeparator: ", ",
 				context: "doc"
 			});
-			const width = Math.max(...rendered.split("\n").map((line) => require_displaywidth.getDisplayWidth(line)));
+			const width = require_text_layout.measureText(rendered).maxLineWidth;
 			widest = widest == null ? width : Math.max(widest, width);
 		}
 		return widest;
@@ -303,16 +315,9 @@ function formatDocPage(programName, page, options = {}) {
 	}
 	if (options.maxWidth != null) {
 		let minDescWidth = 1;
-		if (needsDescColumn) {
-			if (options.showDefault && page.sections.some((s) => s.entries.some((e) => hasContent(e.default)))) {
-				const prefix = punctuation(typeof options.showDefault === "object" ? options.showDefault.prefix ?? " [" : " [", "defaultPrefix");
-				minDescWidth = Math.max(minDescWidth, require_displaywidth.getDisplayWidth(prefix));
-			}
-			if (options.showChoices && page.sections.some((s) => s.entries.some((e) => hasContent(e.choices)))) {
-				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, require_displaywidth.getDisplayWidth(prefix) + require_displaywidth.getDisplayWidth(choicesLabelText));
-			}
+		if (needsDescColumn) for (const kind of ["default", "choices"]) {
+			const enabled = kind === "default" ? options.showDefault : options.showChoices;
+			if (enabled && page.sections.some((section) => section.entries.some((entry) => hasContent(entry[kind])))) minDescWidth = Math.max(minDescWidth, annotation(kind).minWidth);
 		}
 		const splitEntryMin = termIndent + 2 + Math.max(2, 2 * minDescWidth - 1);
 		const fixedEntryMin = termIndent + 2 + termWidth + minDescWidth;
@@ -321,11 +326,17 @@ function formatDocPage(programName, page, options = {}) {
 			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;
+		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;
 		let sectionMin = 1;
-		if (hasContent(page.examples)) sectionMin = Math.max(sectionMin, ...label("Examples:", "examples").split("\n").map((line) => require_displaywidth.getDisplayWidth(line)));
-		if (hasContent(page.author)) sectionMin = Math.max(sectionMin, ...label("Author:", "author").split("\n").map((line) => require_displaywidth.getDisplayWidth(line)));
-		if (hasContent(page.bugs)) sectionMin = Math.max(sectionMin, ...label("Bugs:", "bugs").split("\n").map((line) => require_displaywidth.getDisplayWidth(line)));
+		for (const kind of [
+			"examples",
+			"author",
+			"bugs"
+		]) {
+			if (!hasContent(page[kind])) continue;
+			const title = kind === "examples" ? "Examples:" : kind === "author" ? "Author:" : "Bugs:";
+			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) {
@@ -383,17 +394,21 @@ function formatDocPage(programName, page, options = {}) {
 			output += sectionLabel;
 		}
 		for (const entry of section.entries) {
-			const term = require_usage.formatUsageTerm(entry.term, {
+			const termOptions = {
 				colors: options.colors,
 				theme: options.theme,
 				optionsSeparator: ", ",
-				context: "doc",
-				maxWidth: options.maxWidth == null ? void 0 : options.maxWidth - termIndent
+				context: "doc"
+			};
+			const unwrappedTerm = require_usage.formatUsageTerm(entry.term, termOptions);
+			const multilineReplacement = require_text_layout.measureText(unwrappedTerm).lineCount > 1;
+			const term = options.maxWidth == null ? unwrappedTerm : require_usage.formatUsageTerm(entry.term, {
+				...termOptions,
+				maxWidth: options.maxWidth - termIndent
 			});
 			const descColumnWidth = options.maxWidth == null ? void 0 : options.maxWidth - termIndent - effectiveTermWidth - 2;
-			const termVisibleWidth = lastLineVisibleLength(term);
+			const termVisibleWidth = require_text_layout.measureText(term).lastLineWidth;
 			const extraTermOffset = descColumnWidth != null ? Math.max(0, termVisibleWidth - effectiveTermWidth) : 0;
-			const currentExtraOffset = () => description.includes("\n") ? 0 : extraTermOffset;
 			const descFormatOptions = {
 				colors: options.colors,
 				quotes: !options.colors,
@@ -401,35 +416,26 @@ function formatDocPage(programName, page, options = {}) {
 				initialWidth: extraTermOffset > 0 ? extraTermOffset : void 0
 			};
 			let description = entry.description == null ? "" : formatMessage(entry.description, descFormatOptions);
-			if (options.showDefault && hasContent(entry.default)) {
-				const prefix = punctuation(typeof options.showDefault === "object" ? options.showDefault.prefix ?? " [" : " [", "defaultPrefix");
-				const suffix = punctuation(typeof options.showDefault === "object" ? options.showDefault.suffix ?? "]" : "]", "defaultSuffix");
-				const prefixWidth = require_displaywidth.getDisplayWidth(prefix);
-				const suffixWidth = require_displaywidth.getDisplayWidth(suffix);
-				let defaultStartWidth;
-				if (descColumnWidth != null) {
-					const lastW = lastLineVisibleLength(description);
-					const effectiveLastW = lastW + currentExtraOffset();
-					if (effectiveLastW + prefixWidth >= descColumnWidth) {
-						description += "\n";
-						defaultStartWidth = prefixWidth;
-					} else defaultStartWidth = effectiveLastW + prefixWidth;
-				}
-				const defaultFormatOptions = {
-					colors: options.colors ? { resetSuffix: defaultStyle } : false,
-					quotes: !options.colors,
-					maxWidth: descColumnWidth == null ? void 0 : descColumnWidth - suffixWidth,
-					initialWidth: defaultStartWidth
-				};
-				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;
-			}
+			let cursor = require_text_layout.placeText(description, {
+				line: "",
+				column: extraTermOffset
+			}).cursor;
+			const appendAnnotation = (content, layout, style, ambient, quotes) => {
+				const prefix = require_text_layout.placeText(layout.prefix, cursor, descColumnWidth, 1);
+				if (prefix.text !== layout.prefix) description += "\n";
+				const rendered = formatMessage(content, {
+					colors: options.colors ? { resetSuffix: style } : false,
+					quotes,
+					maxWidth: descColumnWidth == null ? void 0 : descColumnWidth - layout.suffixMetrics.firstLineWidth,
+					initialWidth: descColumnWidth != null || layout.prefixMetrics.lineCount > 1 ? prefix.cursor.column : void 0
+				}, ambient);
+				const suffix = require_text_layout.placeText(layout.suffix, require_text_layout.placeText(rendered, prefix.cursor).cursor, descColumnWidth);
+				const annotationText = `${layout.prefix}${rendered}${opaqueFormatter && options.colors ? style : ""}${suffix.text}`;
+				description += options.colors ? `${style}${annotationText}${style ? "\x1B[0m" : ""}` : annotationText;
+				cursor = suffix.cursor;
+			};
+			if (options.showDefault && hasContent(entry.default)) appendAnnotation(entry.default, annotation("default"), defaultStyle, defaultAmbient, !options.colors);
 			if (options.showChoices && hasContent(entry.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;
@@ -447,31 +453,10 @@ function formatDocPage(programName, page, options = {}) {
 					}
 					if (truncated) truncatedTerms = [...terms.slice(0, cutIndex), require_message.text(", ...")];
 				}
-				const choicesPrefixWidth = require_displaywidth.getDisplayWidth(prefix);
-				const choicesSuffixWidth = require_displaywidth.getDisplayWidth(suffix);
-				const choicesLabelWidth = require_displaywidth.getDisplayWidth(choicesLabelText);
-				let choicesStartWidth;
-				if (descColumnWidth != null) {
-					const lastW = lastLineVisibleLength(description);
-					const effectiveLastW = lastW + currentExtraOffset();
-					const prefixLabelLen = choicesPrefixWidth + choicesLabelWidth;
-					if (effectiveLastW + prefixLabelLen >= descColumnWidth) {
-						description += "\n";
-						choicesStartWidth = prefixLabelLen;
-					} else choicesStartWidth = effectiveLastW + prefixLabelLen;
-				}
-				const choicesFormatOptions = {
-					colors: options.colors ? { resetSuffix: choicesStyle } : false,
-					quotes: false,
-					maxWidth: descColumnWidth == null ? void 0 : descColumnWidth - choicesSuffixWidth,
-					initialWidth: choicesStartWidth
-				};
-				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;
+				appendAnnotation(truncatedTerms, annotation("choices"), choicesStyle, choicesAmbient, false);
 			}
-			output += `${" ".repeat(termIndent)}${ansiAwareRightPad(term, effectiveTermWidth)}${description === "" ? "" : `  ${indentLines(description, termIndent + effectiveTermWidth + 2)}`}\n`;
+			const paddedTerm = ansiAwareRightPad(term, effectiveTermWidth);
+			output += `${" ".repeat(termIndent)}${multilineReplacement ? indentLines(paddedTerm, termIndent) : paddedTerm}${description === "" ? "" : `  ${indentLines(description, termIndent + effectiveTermWidth + 2)}`}\n`;
 		}
 	}
 	if (hasContent(page.examples)) {
@@ -530,21 +515,16 @@ function indentLines(text$1, indent) {
 * contribute to the rendered width.
 */
 function maxVisibleAtomicWidth(usage, theme) {
-	return Math.max(0, ...usage.flatMap((term) => require_usage.formatUsageTerm(term, {
+	return usage.reduce((widest, term) => Math.max(widest, require_text_layout.measureText(require_usage.formatUsageTerm(term, {
 		theme,
 		maxWidth: 1
-	}).split("\n").map(require_displaywidth.getDisplayWidth)));
+	})).maxLineWidth), 0);
 }
 function ansiAwareRightPad(text$1, length, char = " ") {
-	const visibleWidth = lastLineVisibleLength(text$1);
+	const visibleWidth = require_text_layout.measureText(text$1).lastLineWidth;
 	if (visibleWidth >= length) return text$1;
 	return text$1 + char.repeat(length - visibleWidth);
 }
-function lastLineVisibleLength(text$1) {
-	const lastNewline = text$1.lastIndexOf("\n");
-	const lastLine = lastNewline === -1 ? text$1 : text$1.slice(lastNewline + 1);
-	return require_displaywidth.getDisplayWidth(lastLine);
-}
 
 //#endregion
 exports.cloneDocEntry = cloneDocEntry;

package/dist/doc.js

@@ -1,8 +1,8 @@
 import { messageRenderers } from "./message-registry.js";
-import { getDisplayWidth } from "./displaywidth.js";
 import { cacheTerminalTheme, formatTerminalTerm, fragmentTokens, renderTerminalTerm, styleCode } from "./terminal-internal.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";
 
@@ -251,8 +251,8 @@ function formatDocPage(programName, page, options = {}) {
 		}
 		return rendered;
 	};
-	const usageLabel = page.usage != null && options.showUsage !== false ? label("Usage:", "usage") + " " : "";
-	const usageLabelWidth = getDisplayWidth(usageLabel.split("\n").at(-1) ?? "");
+	const usageLabel = page.usage != null && options.showUsage !== false ? spaceAfterLabel(label("Usage:", "usage")) : "";
+	const usageLabelWidth = measureText(usageLabel).lastLineWidth;
 	const defaultStyle = styleCode(options.theme?.annotationStyles?.default ?? { dim: true });
 	const choicesStyle = styleCode(options.theme?.annotationStyles?.choices ?? { dim: true });
 	validateProgramName(programName);
@@ -276,6 +276,18 @@ function formatDocPage(programName, page, options = {}) {
 	}
 	const hasContent = (msg) => Array.isArray(msg) && msg.length > 0;
 	const needsDescriptionColumn = (entry) => hasContent(entry.description) || (options.showDefault === true || typeof options.showDefault === "object") && hasContent(entry.default) || (options.showChoices === true || typeof options.showChoices === "object") && hasContent(entry.choices);
+	const annotations = /* @__PURE__ */ new Map();
+	const annotation = (kind) => {
+		const cached = annotations.get(kind);
+		if (cached != null) return cached;
+		const config = kind === "default" ? options.showDefault : options.showChoices;
+		const prefix = punctuation(typeof config === "object" ? config.prefix ?? (kind === "default" ? " [" : " (") : kind === "default" ? " [" : " (", kind === "default" ? "defaultPrefix" : "choicesPrefix");
+		const suffix = punctuation(typeof config === "object" ? config.suffix ?? (kind === "default" ? "]" : ")") : kind === "default" ? "]" : ")", kind === "default" ? "defaultSuffix" : "choicesSuffix");
+		const choicesLabel = kind === "choices" ? label(typeof options.showChoices === "object" ? options.showChoices.label ?? "choices: " : "choices: ", "choices") : "";
+		const layout = measureAnnotation(prefix + choicesLabel, suffix);
+		annotations.set(kind, layout);
+		return layout;
+	};
 	const automaticTermWidth = () => {
 		let widest;
 		for (const section of page.sections) for (const entry of section.entries) {
@@ -286,7 +298,7 @@ function formatDocPage(programName, page, options = {}) {
 				optionsSeparator: ", ",
 				context: "doc"
 			});
-			const width = Math.max(...rendered.split("\n").map((line) => getDisplayWidth(line)));
+			const width = measureText(rendered).maxLineWidth;
 			widest = widest == null ? width : Math.max(widest, width);
 		}
 		return widest;
@@ -303,16 +315,9 @@ function formatDocPage(programName, page, options = {}) {
 	}
 	if (options.maxWidth != null) {
 		let minDescWidth = 1;
-		if (needsDescColumn) {
-			if (options.showDefault && page.sections.some((s) => s.entries.some((e) => hasContent(e.default)))) {
-				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 = 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));
-			}
+		if (needsDescColumn) for (const kind of ["default", "choices"]) {
+			const enabled = kind === "default" ? options.showDefault : options.showChoices;
+			if (enabled && page.sections.some((section) => section.entries.some((entry) => hasContent(entry[kind])))) minDescWidth = Math.max(minDescWidth, annotation(kind).minWidth);
 		}
 		const splitEntryMin = termIndent + 2 + Math.max(2, 2 * minDescWidth - 1);
 		const fixedEntryMin = termIndent + 2 + termWidth + minDescWidth;
@@ -321,11 +326,17 @@ function formatDocPage(programName, page, options = {}) {
 			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;
+		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;
 		let sectionMin = 1;
-		if (hasContent(page.examples)) sectionMin = Math.max(sectionMin, ...label("Examples:", "examples").split("\n").map((line) => getDisplayWidth(line)));
-		if (hasContent(page.author)) sectionMin = Math.max(sectionMin, ...label("Author:", "author").split("\n").map((line) => getDisplayWidth(line)));
-		if (hasContent(page.bugs)) sectionMin = Math.max(sectionMin, ...label("Bugs:", "bugs").split("\n").map((line) => getDisplayWidth(line)));
+		for (const kind of [
+			"examples",
+			"author",
+			"bugs"
+		]) {
+			if (!hasContent(page[kind])) continue;
+			const title = kind === "examples" ? "Examples:" : kind === "author" ? "Author:" : "Bugs:";
+			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) {
@@ -383,17 +394,21 @@ function formatDocPage(programName, page, options = {}) {
 			output += sectionLabel;
 		}
 		for (const entry of section.entries) {
-			const term = formatUsageTerm(entry.term, {
+			const termOptions = {
 				colors: options.colors,
 				theme: options.theme,
 				optionsSeparator: ", ",
-				context: "doc",
-				maxWidth: options.maxWidth == null ? void 0 : options.maxWidth - termIndent
+				context: "doc"
+			};
+			const unwrappedTerm = formatUsageTerm(entry.term, termOptions);
+			const multilineReplacement = measureText(unwrappedTerm).lineCount > 1;
+			const term = options.maxWidth == null ? unwrappedTerm : formatUsageTerm(entry.term, {
+				...termOptions,
+				maxWidth: options.maxWidth - termIndent
 			});
 			const descColumnWidth = options.maxWidth == null ? void 0 : options.maxWidth - termIndent - effectiveTermWidth - 2;
-			const termVisibleWidth = lastLineVisibleLength(term);
+			const termVisibleWidth = measureText(term).lastLineWidth;
 			const extraTermOffset = descColumnWidth != null ? Math.max(0, termVisibleWidth - effectiveTermWidth) : 0;
-			const currentExtraOffset = () => description.includes("\n") ? 0 : extraTermOffset;
 			const descFormatOptions = {
 				colors: options.colors,
 				quotes: !options.colors,
@@ -401,35 +416,26 @@ function formatDocPage(programName, page, options = {}) {
 				initialWidth: extraTermOffset > 0 ? extraTermOffset : void 0
 			};
 			let description = entry.description == null ? "" : formatMessage(entry.description, descFormatOptions);
-			if (options.showDefault && hasContent(entry.default)) {
-				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;
-				if (descColumnWidth != null) {
-					const lastW = lastLineVisibleLength(description);
-					const effectiveLastW = lastW + currentExtraOffset();
-					if (effectiveLastW + prefixWidth >= descColumnWidth) {
-						description += "\n";
-						defaultStartWidth = prefixWidth;
-					} else defaultStartWidth = effectiveLastW + prefixWidth;
-				}
-				const defaultFormatOptions = {
-					colors: options.colors ? { resetSuffix: defaultStyle } : false,
-					quotes: !options.colors,
-					maxWidth: descColumnWidth == null ? void 0 : descColumnWidth - suffixWidth,
-					initialWidth: defaultStartWidth
-				};
-				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;
-			}
+			let cursor = placeText(description, {
+				line: "",
+				column: extraTermOffset
+			}).cursor;
+			const appendAnnotation = (content, layout, style, ambient, quotes) => {
+				const prefix = placeText(layout.prefix, cursor, descColumnWidth, 1);
+				if (prefix.text !== layout.prefix) description += "\n";
+				const rendered = formatMessage(content, {
+					colors: options.colors ? { resetSuffix: style } : false,
+					quotes,
+					maxWidth: descColumnWidth == null ? void 0 : descColumnWidth - layout.suffixMetrics.firstLineWidth,
+					initialWidth: descColumnWidth != null || layout.prefixMetrics.lineCount > 1 ? prefix.cursor.column : void 0
+				}, ambient);
+				const suffix = placeText(layout.suffix, placeText(rendered, prefix.cursor).cursor, descColumnWidth);
+				const annotationText = `${layout.prefix}${rendered}${opaqueFormatter && options.colors ? style : ""}${suffix.text}`;
+				description += options.colors ? `${style}${annotationText}${style ? "\x1B[0m" : ""}` : annotationText;
+				cursor = suffix.cursor;
+			};
+			if (options.showDefault && hasContent(entry.default)) appendAnnotation(entry.default, annotation("default"), defaultStyle, defaultAmbient, !options.colors);
 			if (options.showChoices && hasContent(entry.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;
@@ -447,31 +453,10 @@ function formatDocPage(programName, page, options = {}) {
 					}
 					if (truncated) truncatedTerms = [...terms.slice(0, cutIndex), text(", ...")];
 				}
-				const choicesPrefixWidth = getDisplayWidth(prefix);
-				const choicesSuffixWidth = getDisplayWidth(suffix);
-				const choicesLabelWidth = getDisplayWidth(choicesLabelText);
-				let choicesStartWidth;
-				if (descColumnWidth != null) {
-					const lastW = lastLineVisibleLength(description);
-					const effectiveLastW = lastW + currentExtraOffset();
-					const prefixLabelLen = choicesPrefixWidth + choicesLabelWidth;
-					if (effectiveLastW + prefixLabelLen >= descColumnWidth) {
-						description += "\n";
-						choicesStartWidth = prefixLabelLen;
-					} else choicesStartWidth = effectiveLastW + prefixLabelLen;
-				}
-				const choicesFormatOptions = {
-					colors: options.colors ? { resetSuffix: choicesStyle } : false,
-					quotes: false,
-					maxWidth: descColumnWidth == null ? void 0 : descColumnWidth - choicesSuffixWidth,
-					initialWidth: choicesStartWidth
-				};
-				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;
+				appendAnnotation(truncatedTerms, annotation("choices"), choicesStyle, choicesAmbient, false);
 			}
-			output += `${" ".repeat(termIndent)}${ansiAwareRightPad(term, effectiveTermWidth)}${description === "" ? "" : `  ${indentLines(description, termIndent + effectiveTermWidth + 2)}`}\n`;
+			const paddedTerm = ansiAwareRightPad(term, effectiveTermWidth);
+			output += `${" ".repeat(termIndent)}${multilineReplacement ? indentLines(paddedTerm, termIndent) : paddedTerm}${description === "" ? "" : `  ${indentLines(description, termIndent + effectiveTermWidth + 2)}`}\n`;
 		}
 	}
 	if (hasContent(page.examples)) {
@@ -530,21 +515,16 @@ function indentLines(text$1, indent) {
 * contribute to the rendered width.
 */
 function maxVisibleAtomicWidth(usage, theme) {
-	return Math.max(0, ...usage.flatMap((term) => formatUsageTerm(term, {
+	return usage.reduce((widest, term) => Math.max(widest, measureText(formatUsageTerm(term, {
 		theme,
 		maxWidth: 1
-	}).split("\n").map(getDisplayWidth)));
+	})).maxLineWidth), 0);
 }
 function ansiAwareRightPad(text$1, length, char = " ") {
-	const visibleWidth = lastLineVisibleLength(text$1);
+	const visibleWidth = measureText(text$1).lastLineWidth;
 	if (visibleWidth >= length) return text$1;
 	return text$1 + char.repeat(length - visibleWidth);
 }
-function lastLineVisibleLength(text$1) {
-	const lastNewline = text$1.lastIndexOf("\n");
-	const lastLine = lastNewline === -1 ? text$1 : text$1.slice(lastNewline + 1);
-	return getDisplayWidth(lastLine);
-}
 
 //#endregion
 export { cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage, isDocEntryHidden };

package/dist/facade.cjs

@@ -1,8 +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_text_layout = require('./text-layout.cjs');
 const require_validate = require('./validate.cjs');
 const require_usage = require('./usage.cjs');
 const require_doc = require('./doc.cjs');
@@ -521,10 +521,10 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 		messageFormatter,
 		theme
 	});
-	const errorLabel = () => require_terminal_internal.renderTerminalTerm({
+	const errorLabel = () => require_text_layout.spaceAfterLabel(require_terminal_internal.renderTerminalTerm({
 		type: "errorLabel",
 		label: "Error:"
-	}, theme, colors) + " ";
+	}, theme, colors));
 	const shellName = completionArgs[0] || "";
 	const args = completionArgs.slice(1);
 	const callOnError = (code, error) => onError(code, error);
@@ -536,7 +536,7 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 			colors,
 			quotes: !colors,
 			maxWidth,
-			initialWidth: require_displaywidth.getDisplayWidth(prefix.split("\n").at(-1) ?? "")
+			initialWidth: require_text_layout.measureText(prefix).lastLineWidth
 		})}\n`);
 		if (completionParser) {
 			const displayName = isOptionMode ? completionOptionDisplayName ?? "--completion" : completionCommandDisplayName ?? "completion";
@@ -570,7 +570,7 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 			colors,
 			quotes: !colors,
 			maxWidth,
-			initialWidth: require_displaywidth.getDisplayWidth(prefix.split("\n").at(-1) ?? "")
+			initialWidth: require_text_layout.measureText(prefix).lastLineWidth
 		})}`);
 		return require_mode_dispatch.dispatchByMode(parser.mode, () => {
 			const result = callOnError(1, error);
@@ -886,17 +886,17 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		messageFormatter,
 		theme
 	});
-	const errorLabel = () => require_terminal_internal.renderTerminalTerm({
+	const errorLabel = () => require_text_layout.spaceAfterLabel(require_terminal_internal.renderTerminalTerm({
 		type: "errorLabel",
 		label: "Error:"
-	}, theme, colors) + " ";
+	}, theme, colors));
 	let usagePrefix;
-	const usageLabel = () => usagePrefix ??= require_terminal_internal.renderTerminalTerm({
+	const usageLabel = () => usagePrefix ??= require_text_layout.spaceAfterLabel(require_terminal_internal.renderTerminalTerm({
 		type: "label",
 		label: "Usage:",
 		kind: "usageSummary"
-	}, theme, colors) + " ";
-	const usageLabelWidth = () => require_displaywidth.getDisplayWidth(usageLabel().split("\n").at(-1) ?? "");
+	}, theme, colors));
+	const usageLabelWidth = () => require_text_layout.measureText(usageLabel()).lastLineWidth;
 	const norm = (c) => c === true ? {} : c;
 	const helpCommandConfig = norm(options.help?.command);
 	const helpOptionConfig = norm(options.help?.option);
@@ -1059,7 +1059,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 					}), usageLabelWidth())}`);
 					const prefix = errorLabel();
 					const errorMessage = formatMessage(validationError, {
-						initialWidth: require_displaywidth.getDisplayWidth(prefix.split("\n").at(-1) ?? ""),
+						initialWidth: require_text_layout.measureText(prefix).lastLineWidth,
 						maxWidth,
 						colors,
 						quotes: !colors
@@ -1179,7 +1179,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 					}), usageLabelWidth())}`);
 					const prefix = errorLabel();
 					const errorMessage = formatMessage(classified.error, {
-						initialWidth: require_displaywidth.getDisplayWidth(prefix.split("\n").at(-1) ?? ""),
+						initialWidth: require_text_layout.measureText(prefix).lastLineWidth,
 						maxWidth,
 						colors,
 						quotes: !colors

package/dist/facade.js

@@ -1,8 +1,8 @@
 import { injectAnnotations } from "./internal/annotations.js";
-import { getDisplayWidth } from "./displaywidth.js";
 import { renderTerminalTerm } from "./terminal-internal.js";
 import { commandLine, lineBreak, message, optionName, text, value } from "./message.js";
 import { resolveMessageFormatter } from "./message-renderer.js";
+import { measureText, spaceAfterLabel } from "./text-layout.js";
 import { validateCommandNames, validateContextIds, validateMetaNameCollisions, validateOptionNames, validateProgramName } from "./validate.js";
 import { cloneUsage, formatUsage, isSuggestionHidden, normalizeUsage } from "./usage.js";
 import { formatDocPage } from "./doc.js";
@@ -521,10 +521,10 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 		messageFormatter,
 		theme
 	});
-	const errorLabel = () => renderTerminalTerm({
+	const errorLabel = () => spaceAfterLabel(renderTerminalTerm({
 		type: "errorLabel",
 		label: "Error:"
-	}, theme, colors) + " ";
+	}, theme, colors));
 	const shellName = completionArgs[0] || "";
 	const args = completionArgs.slice(1);
 	const callOnError = (code, error) => onError(code, error);
@@ -536,7 +536,7 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 			colors,
 			quotes: !colors,
 			maxWidth,
-			initialWidth: getDisplayWidth(prefix.split("\n").at(-1) ?? "")
+			initialWidth: measureText(prefix).lastLineWidth
 		})}\n`);
 		if (completionParser) {
 			const displayName = isOptionMode ? completionOptionDisplayName ?? "--completion" : completionCommandDisplayName ?? "completion";
@@ -570,7 +570,7 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 			colors,
 			quotes: !colors,
 			maxWidth,
-			initialWidth: getDisplayWidth(prefix.split("\n").at(-1) ?? "")
+			initialWidth: measureText(prefix).lastLineWidth
 		})}`);
 		return dispatchByMode(parser.mode, () => {
 			const result = callOnError(1, error);
@@ -886,17 +886,17 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		messageFormatter,
 		theme
 	});
-	const errorLabel = () => renderTerminalTerm({
+	const errorLabel = () => spaceAfterLabel(renderTerminalTerm({
 		type: "errorLabel",
 		label: "Error:"
-	}, theme, colors) + " ";
+	}, theme, colors));
 	let usagePrefix;
-	const usageLabel = () => usagePrefix ??= renderTerminalTerm({
+	const usageLabel = () => usagePrefix ??= spaceAfterLabel(renderTerminalTerm({
 		type: "label",
 		label: "Usage:",
 		kind: "usageSummary"
-	}, theme, colors) + " ";
-	const usageLabelWidth = () => getDisplayWidth(usageLabel().split("\n").at(-1) ?? "");
+	}, theme, colors));
+	const usageLabelWidth = () => measureText(usageLabel()).lastLineWidth;
 	const norm = (c) => c === true ? {} : c;
 	const helpCommandConfig = norm(options.help?.command);
 	const helpOptionConfig = norm(options.help?.option);
@@ -1059,7 +1059,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 					}), usageLabelWidth())}`);
 					const prefix = errorLabel();
 					const errorMessage = formatMessage(validationError, {
-						initialWidth: getDisplayWidth(prefix.split("\n").at(-1) ?? ""),
+						initialWidth: measureText(prefix).lastLineWidth,
 						maxWidth,
 						colors,
 						quotes: !colors
@@ -1179,7 +1179,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 					}), usageLabelWidth())}`);
 					const prefix = errorLabel();
 					const errorMessage = formatMessage(classified.error, {
-						initialWidth: getDisplayWidth(prefix.split("\n").at(-1) ?? ""),
+						initialWidth: measureText(prefix).lastLineWidth,
 						maxWidth,
 						colors,
 						quotes: !colors

package/dist/internal/terminal.cjs

@@ -1,7 +1,11 @@
 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');
 
 exports.getDisplayWidth = require_displaywidth.getDisplayWidth;
+exports.measureText = require_text_layout.measureText;
+exports.placeText = require_text_layout.placeText;
 exports.renderTerminalTerm = require_terminal_internal.renderTerminalTerm;
-exports.resolveMessageFormatter = require_message_renderer.resolveMessageFormatter;
+exports.resolveMessageFormatter = require_message_renderer.resolveMessageFormatter;
+exports.spaceAfterLabel = require_text_layout.spaceAfterLabel;

package/dist/internal/terminal.d.cts

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

package/dist/internal/terminal.d.ts

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

package/dist/internal/terminal.js

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

package/dist/terminal-internal.d.cts

@@ -10,6 +10,8 @@ interface TerminalToken {
   readonly text: string;
   readonly width: number;
   readonly scopes: readonly Scope[];
+  /** Layout-owned space, removable beside an explicit hard break. */
+  readonly separator?: boolean;
 }
 declare function terminalText(text: string): TerminalFragment;
 declare function formatTerminalTerm(term: TerminalTerm, theme?: TerminalTheme, quotes?: boolean, usage?: TerminalFormatContext["usage"]): TerminalFragment;

package/dist/terminal-internal.d.ts

@@ -10,6 +10,8 @@ interface TerminalToken {
   readonly text: string;
   readonly width: number;
   readonly scopes: readonly Scope[];
+  /** Layout-owned space, removable beside an explicit hard break. */
+  readonly separator?: boolean;
 }
 declare function terminalText(text: string): TerminalFragment;
 declare function formatTerminalTerm(term: TerminalTerm, theme?: TerminalTheme, quotes?: boolean, usage?: TerminalFormatContext["usage"]): TerminalFragment;

package/dist/text-layout.cjs

@@ -0,0 +1,87 @@
+const require_displaywidth = require('./displaywidth.cjs');
+
+//#region src/text-layout.ts
+/**
+* Measures physical lines after removing terminal escape sequences.
+* Empty text occupies one empty line; a trailing LF adds an empty final line.
+* @param text Rendered text, possibly containing ANSI styles or OSC links.
+* @returns First, last and widest line widths, and the number of lines.
+* @internal
+*/
+function measureText(text) {
+	const lines = require_displaywidth.stripAnsi(text).split("\n");
+	const widths = lines.map(require_displaywidth.getDisplayWidth);
+	return {
+		firstLineWidth: widths[0],
+		lastLineWidth: widths[widths.length - 1],
+		maxLineWidth: widths.reduce((widest, width) => Math.max(widest, width), 0),
+		lineCount: lines.length
+	};
+}
+/**
+* Appends rendered text to a cursor, optionally moving it to a fresh line.
+* Measures the actual join so combining sequences crossing the boundary are
+* handled correctly. Hard breaks reset both the line and any external offset.
+* This never reflows the text itself or changes its escape sequences.
+* @param text Text to append.
+* @param cursor The current line and column.
+* @param maxWidth Optional column budget.
+* @param trailingRoom Space to leave after a single-line block. An annotation
+* prefix reserves one column for content; a multiline prefix already has a
+* hard break, so its first line needs no reservation.
+* @returns The placed text (possibly with a leading LF) and resulting cursor.
+* @internal
+*/
+function placeText(text, cursor, maxWidth, trailingRoom = 0) {
+	const plain = require_displaywidth.stripAnsi(text);
+	const lines = plain.split("\n");
+	const offset = cursor.column - require_displaywidth.getDisplayWidth(cursor.line);
+	const joinedWidth = offset + require_displaywidth.getDisplayWidth(cursor.line + lines[0]);
+	const room = lines.length === 1 ? trailingRoom : 0;
+	const breaks = maxWidth != null && (cursor.column > 0 || room > 0) && (joinedWidth > cursor.column || room > 0) && joinedWidth + room > maxWidth;
+	const lastLine = lines[lines.length - 1];
+	return {
+		text: breaks ? "\n" + text : text,
+		cursor: lines.length > 1 || breaks ? {
+			line: lastLine,
+			column: require_displaywidth.getDisplayWidth(lastLine)
+		} : {
+			line: cursor.line + plain,
+			column: joinedWidth
+		}
+	};
+}
+/**
+* Measures an annotation's fixed text without invoking theme callbacks.
+* @param prefix The already joined prefix and optional label.
+* @param suffix The closing text.
+* @returns Geometry reserving at least one content column after the suffix's
+* first-line width has been deducted from the formatter budget.
+* @internal
+*/
+function measureAnnotation(prefix, suffix) {
+	const prefixMetrics = measureText(prefix);
+	const suffixMetrics = measureText(suffix);
+	return {
+		prefix,
+		suffix,
+		prefixMetrics,
+		suffixMetrics,
+		minWidth: Math.max(prefixMetrics.maxLineWidth, suffixMetrics.maxLineWidth, suffixMetrics.firstLineWidth + 1)
+	};
+}
+/**
+* Adds a separating space only when a label occupies its final physical line.
+* @param label The rendered label, including any styles and hard breaks.
+* @returns The label with spacing for the text that follows it.
+* @internal
+*/
+function spaceAfterLabel(label) {
+	return measureText(label).lastLineWidth > 0 ? label + " " : label;
+}
+
+//#endregion
+exports.measureAnnotation = measureAnnotation;
+exports.measureText = measureText;
+exports.placeText = placeText;
+exports.spaceAfterLabel = spaceAfterLabel;

package/dist/text-layout.d.cts

@@ -0,0 +1,54 @@
+//#region src/text-layout.d.ts
+/** Physical-line geometry at a rendered-text assembly boundary. @internal */
+interface TextMetrics {
+  readonly firstLineWidth: number;
+  readonly lastLineWidth: number;
+  readonly maxLineWidth: number;
+  readonly lineCount: number;
+}
+/**
+ * Measures physical lines after removing terminal escape sequences.
+ * Empty text occupies one empty line; a trailing LF adds an empty final line.
+ * @param text Rendered text, possibly containing ANSI styles or OSC links.
+ * @returns First, last and widest line widths, and the number of lines.
+ * @internal
+ */
+declare function measureText(text: string): TextMetrics;
+/**
+ * The current visible line and its occupied column. The column may include
+ * an external offset for text unavailable to this renderer (initialWidth).
+ * @internal
+ */
+interface TextCursor {
+  readonly line: string;
+  readonly column: number;
+}
+/**
+ * Appends rendered text to a cursor, optionally moving it to a fresh line.
+ * Measures the actual join so combining sequences crossing the boundary are
+ * handled correctly. Hard breaks reset both the line and any external offset.
+ * This never reflows the text itself or changes its escape sequences.
+ * @param text Text to append.
+ * @param cursor The current line and column.
+ * @param maxWidth Optional column budget.
+ * @param trailingRoom Space to leave after a single-line block. An annotation
+ * prefix reserves one column for content; a multiline prefix already has a
+ * hard break, so its first line needs no reservation.
+ * @returns The placed text (possibly with a leading LF) and resulting cursor.
+ * @internal
+ */
+declare function placeText(text: string, cursor: TextCursor, maxWidth?: number, trailingRoom?: number): {
+  readonly text: string;
+  readonly cursor: TextCursor;
+};
+/** Fixed annotation geometry shared by preflight and placement. @internal */
+
+/**
+ * Adds a separating space only when a label occupies its final physical line.
+ * @param label The rendered label, including any styles and hard breaks.
+ * @returns The label with spacing for the text that follows it.
+ * @internal
+ */
+declare function spaceAfterLabel(label: string): string;
+//#endregion
+export { measureText, placeText, spaceAfterLabel };

package/dist/text-layout.d.ts

@@ -0,0 +1,54 @@
+//#region src/text-layout.d.ts
+/** Physical-line geometry at a rendered-text assembly boundary. @internal */
+interface TextMetrics {
+  readonly firstLineWidth: number;
+  readonly lastLineWidth: number;
+  readonly maxLineWidth: number;
+  readonly lineCount: number;
+}
+/**
+ * Measures physical lines after removing terminal escape sequences.
+ * Empty text occupies one empty line; a trailing LF adds an empty final line.
+ * @param text Rendered text, possibly containing ANSI styles or OSC links.
+ * @returns First, last and widest line widths, and the number of lines.
+ * @internal
+ */
+declare function measureText(text: string): TextMetrics;
+/**
+ * The current visible line and its occupied column. The column may include
+ * an external offset for text unavailable to this renderer (initialWidth).
+ * @internal
+ */
+interface TextCursor {
+  readonly line: string;
+  readonly column: number;
+}
+/**
+ * Appends rendered text to a cursor, optionally moving it to a fresh line.
+ * Measures the actual join so combining sequences crossing the boundary are
+ * handled correctly. Hard breaks reset both the line and any external offset.
+ * This never reflows the text itself or changes its escape sequences.
+ * @param text Text to append.
+ * @param cursor The current line and column.
+ * @param maxWidth Optional column budget.
+ * @param trailingRoom Space to leave after a single-line block. An annotation
+ * prefix reserves one column for content; a multiline prefix already has a
+ * hard break, so its first line needs no reservation.
+ * @returns The placed text (possibly with a leading LF) and resulting cursor.
+ * @internal
+ */
+declare function placeText(text: string, cursor: TextCursor, maxWidth?: number, trailingRoom?: number): {
+  readonly text: string;
+  readonly cursor: TextCursor;
+};
+/** Fixed annotation geometry shared by preflight and placement. @internal */
+
+/**
+ * Adds a separating space only when a label occupies its final physical line.
+ * @param label The rendered label, including any styles and hard breaks.
+ * @returns The label with spacing for the text that follows it.
+ * @internal
+ */
+declare function spaceAfterLabel(label: string): string;
+//#endregion
+export { measureText, placeText, spaceAfterLabel };

package/dist/text-layout.js

@@ -0,0 +1,84 @@
+import { getDisplayWidth, stripAnsi } from "./displaywidth.js";
+
+//#region src/text-layout.ts
+/**
+* Measures physical lines after removing terminal escape sequences.
+* Empty text occupies one empty line; a trailing LF adds an empty final line.
+* @param text Rendered text, possibly containing ANSI styles or OSC links.
+* @returns First, last and widest line widths, and the number of lines.
+* @internal
+*/
+function measureText(text) {
+	const lines = stripAnsi(text).split("\n");
+	const widths = lines.map(getDisplayWidth);
+	return {
+		firstLineWidth: widths[0],
+		lastLineWidth: widths[widths.length - 1],
+		maxLineWidth: widths.reduce((widest, width) => Math.max(widest, width), 0),
+		lineCount: lines.length
+	};
+}
+/**
+* Appends rendered text to a cursor, optionally moving it to a fresh line.
+* Measures the actual join so combining sequences crossing the boundary are
+* handled correctly. Hard breaks reset both the line and any external offset.
+* This never reflows the text itself or changes its escape sequences.
+* @param text Text to append.
+* @param cursor The current line and column.
+* @param maxWidth Optional column budget.
+* @param trailingRoom Space to leave after a single-line block. An annotation
+* prefix reserves one column for content; a multiline prefix already has a
+* hard break, so its first line needs no reservation.
+* @returns The placed text (possibly with a leading LF) and resulting cursor.
+* @internal
+*/
+function placeText(text, cursor, maxWidth, trailingRoom = 0) {
+	const plain = stripAnsi(text);
+	const lines = plain.split("\n");
+	const offset = cursor.column - getDisplayWidth(cursor.line);
+	const joinedWidth = offset + getDisplayWidth(cursor.line + lines[0]);
+	const room = lines.length === 1 ? trailingRoom : 0;
+	const breaks = maxWidth != null && (cursor.column > 0 || room > 0) && (joinedWidth > cursor.column || room > 0) && joinedWidth + room > maxWidth;
+	const lastLine = lines[lines.length - 1];
+	return {
+		text: breaks ? "\n" + text : text,
+		cursor: lines.length > 1 || breaks ? {
+			line: lastLine,
+			column: getDisplayWidth(lastLine)
+		} : {
+			line: cursor.line + plain,
+			column: joinedWidth
+		}
+	};
+}
+/**
+* Measures an annotation's fixed text without invoking theme callbacks.
+* @param prefix The already joined prefix and optional label.
+* @param suffix The closing text.
+* @returns Geometry reserving at least one content column after the suffix's
+* first-line width has been deducted from the formatter budget.
+* @internal
+*/
+function measureAnnotation(prefix, suffix) {
+	const prefixMetrics = measureText(prefix);
+	const suffixMetrics = measureText(suffix);
+	return {
+		prefix,
+		suffix,
+		prefixMetrics,
+		suffixMetrics,
+		minWidth: Math.max(prefixMetrics.maxLineWidth, suffixMetrics.maxLineWidth, suffixMetrics.firstLineWidth + 1)
+	};
+}
+/**
+* Adds a separating space only when a label occupies its final physical line.
+* @param label The rendered label, including any styles and hard breaks.
+* @returns The label with spacing for the text that follows it.
+* @internal
+*/
+function spaceAfterLabel(label) {
+	return measureText(label).lastLineWidth > 0 ? label + " " : label;
+}
+
+//#endregion
+export { measureAnnotation, measureText, placeText, spaceAfterLabel };

package/dist/usage.cjs

@@ -196,8 +196,8 @@ 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 = command[0];
-				if (firstTerm?.type === "command" && isUsageHidden(firstTerm.hidden)) continue;
+				const firstTerm$1 = command[0];
+				if (firstTerm$1?.type === "command" && isUsageHidden(firstTerm$1.hidden)) continue;
 				if (usage.length > 1) command = [...usage.slice(0, -1), ...command];
 				lines.push(formatUsage(programName, command, options));
 			}
@@ -208,10 +208,13 @@ function formatUsage(programName, usage, options = {}) {
 		type: "programName",
 		programName
 	}, options.theme)), options);
-	const terms = [...formatUsageTerms(usage, 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 separator = options.maxWidth != null && width + 1 + terms[0].width > options.maxWidth ? {
+	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: []
@@ -456,7 +459,8 @@ function* formatUsageTerms(terms, options) {
 		if (i > 0) yield {
 			text: " ",
 			width: 1,
-			scopes: []
+			scopes: [],
+			separator: true
 		};
 		yield* formatUsageTermInternal(t, options);
 		i++;
@@ -486,16 +490,37 @@ function formatUsageTerm(term, options = {}) {
 function wrapUsageTokens(input, options, initialWidth = 0) {
 	return require_terminal_internal.serializeTokens(layoutUsageTokens(input, options, initialWidth), options.colors);
 }
+/** Keeps one layout-owned space between nonempty outputs on the same line. */
+function* normalizeUsageSeparators(input) {
+	let previous;
+	let pending = [];
+	for (const token of input) {
+		if (token.separator || token.text === "") {
+			pending.push(token);
+			continue;
+		}
+		let separated = false;
+		for (const item of pending) if (!item.separator) yield item;
+		else if (!separated && previous != null && previous.width !== -1 && token.width !== -1) {
+			yield item;
+			separated = true;
+		}
+		pending = [];
+		yield token;
+		previous = token;
+	}
+	for (const item of pending) if (!item.separator) yield item;
+}
 function layoutUsageTokens(input, options, initialWidth = 0) {
 	let lineWidth = initialWidth;
 	const output = [];
-	for (const token of input) {
+	for (const token of normalizeUsageSeparators(input)) {
 		if (token.width === -1) {
 			output.push(token);
 			lineWidth = 0;
 			continue;
 		}
-		if (options.maxWidth != null && lineWidth > 0 && lineWidth + token.width > options.maxWidth) {
+		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] = {
 				...last,
@@ -529,7 +554,8 @@ function* formatUsageTermInternal(term, options) {
 	const space = {
 		text: " ",
 		width: 1,
-		scopes: []
+		scopes: [],
+		separator: true
 	};
 	if (term.type === "argument") yield* leaf({
 		type: "metavar",

package/dist/usage.js

@@ -196,8 +196,8 @@ 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 = command[0];
-				if (firstTerm?.type === "command" && isUsageHidden(firstTerm.hidden)) continue;
+				const firstTerm$1 = command[0];
+				if (firstTerm$1?.type === "command" && isUsageHidden(firstTerm$1.hidden)) continue;
 				if (usage.length > 1) command = [...usage.slice(0, -1), ...command];
 				lines.push(formatUsage(programName, command, options));
 			}
@@ -208,10 +208,13 @@ function formatUsage(programName, usage, options = {}) {
 		type: "programName",
 		programName
 	}, options.theme)), options);
-	const terms = [...formatUsageTerms(usage, 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 separator = options.maxWidth != null && width + 1 + terms[0].width > options.maxWidth ? {
+	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: []
@@ -456,7 +459,8 @@ function* formatUsageTerms(terms, options) {
 		if (i > 0) yield {
 			text: " ",
 			width: 1,
-			scopes: []
+			scopes: [],
+			separator: true
 		};
 		yield* formatUsageTermInternal(t, options);
 		i++;
@@ -486,16 +490,37 @@ function formatUsageTerm(term, options = {}) {
 function wrapUsageTokens(input, options, initialWidth = 0) {
 	return serializeTokens(layoutUsageTokens(input, options, initialWidth), options.colors);
 }
+/** Keeps one layout-owned space between nonempty outputs on the same line. */
+function* normalizeUsageSeparators(input) {
+	let previous;
+	let pending = [];
+	for (const token of input) {
+		if (token.separator || token.text === "") {
+			pending.push(token);
+			continue;
+		}
+		let separated = false;
+		for (const item of pending) if (!item.separator) yield item;
+		else if (!separated && previous != null && previous.width !== -1 && token.width !== -1) {
+			yield item;
+			separated = true;
+		}
+		pending = [];
+		yield token;
+		previous = token;
+	}
+	for (const item of pending) if (!item.separator) yield item;
+}
 function layoutUsageTokens(input, options, initialWidth = 0) {
 	let lineWidth = initialWidth;
 	const output = [];
-	for (const token of input) {
+	for (const token of normalizeUsageSeparators(input)) {
 		if (token.width === -1) {
 			output.push(token);
 			lineWidth = 0;
 			continue;
 		}
-		if (options.maxWidth != null && lineWidth > 0 && lineWidth + token.width > options.maxWidth) {
+		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] = {
 				...last,
@@ -529,7 +554,8 @@ function* formatUsageTermInternal(term, options) {
 	const space = {
 		text: " ",
 		width: 1,
-		scopes: []
+		scopes: [],
+		separator: true
 	};
 	if (term.type === "argument") yield* leaf({
 		type: "metavar",

package/package.json

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