@optique/core 1.3.0-dev.2540 → 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 };