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

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.cjs

@@ -127,11 +127,19 @@ function sameStyle(a, b) {
 }
 function* fragmentTokens(fragment, scopes = [], inherited = {}) {
 	if (fragment.type === "text") {
-		yield {
-			text: fragment.text,
-			width: require_displaywidth.getDisplayWidth(fragment.text),
-			scopes
-		};
+		const lines = fragment.text.split("\n");
+		for (let i = 0; i < lines.length; i++) {
+			if (i > 0) yield {
+				text: "\n",
+				width: -1,
+				scopes
+			};
+			if (lines[i].length > 0 || lines.length === 1) yield {
+				text: lines[i],
+				width: require_displaywidth.getDisplayWidth(lines[i]),
+				scopes
+			};
+		}
 		return;
 	}
 	let next = scopes;
@@ -193,7 +201,7 @@ function serializeTokens(tokens, colors = false, resetSuffix = "", ambient = {})
 	const items = [...tokens];
 	for (let i = 0; i < items.length; i++) {
 		const token = items[i];
-		if (colors && token.width === -1) {
+		if (colors && token.width === -1 && token.scopes.length === 0) {
 			const next = items.slice(i + 1).find((t) => t.width !== -1)?.scopes ?? [];
 			let common = 0;
 			while (common < active.length && common < next.length && active[common] === next[common]) common++;

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/terminal-internal.js

@@ -127,11 +127,19 @@ function sameStyle(a, b) {
 }
 function* fragmentTokens(fragment, scopes = [], inherited = {}) {
 	if (fragment.type === "text") {
-		yield {
-			text: fragment.text,
-			width: getDisplayWidth(fragment.text),
-			scopes
-		};
+		const lines = fragment.text.split("\n");
+		for (let i = 0; i < lines.length; i++) {
+			if (i > 0) yield {
+				text: "\n",
+				width: -1,
+				scopes
+			};
+			if (lines[i].length > 0 || lines.length === 1) yield {
+				text: lines[i],
+				width: getDisplayWidth(lines[i]),
+				scopes
+			};
+		}
 		return;
 	}
 	let next = scopes;
@@ -193,7 +201,7 @@ function serializeTokens(tokens, colors = false, resetSuffix = "", ambient = {})
 	const items = [...tokens];
 	for (let i = 0; i < items.length; i++) {
 		const token = items[i];
-		if (colors && token.width === -1) {
+		if (colors && token.width === -1 && token.scopes.length === 0) {
 			const next = items.slice(i + 1).find((t) => t.width !== -1)?.scopes ?? [];
 			let common = 0;
 			while (common < active.length && common < next.length && active[common] === next[common]) common++;

package/dist/terminal.d.cts

@@ -61,7 +61,8 @@ interface TerminalStyle {
   readonly underline?: boolean;
 }
 /**
- * Structured output. Each text leaf is an indivisible wrapping unit.
+ * Structured output. Newlines in text leaves force line breaks; each line
+ * within a leaf is an indivisible wrapping unit.
  * @since 1.3.0
  */
 type TerminalFragment = {

package/dist/terminal.d.ts

@@ -61,7 +61,8 @@ interface TerminalStyle {
   readonly underline?: boolean;
 }
 /**
- * Structured output. Each text leaf is an indivisible wrapping unit.
+ * Structured output. Newlines in text leaves force line breaks; each line
+ * within a leaf is an indivisible wrapping unit.
  * @since 1.3.0
  */
 type 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 };