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

package/dist/terminal-internal.js

@@ -17,11 +17,29 @@ function valuesFormatter(theme) {
 		children: [defaultTerminalTheme.values(term, context)]
 	});
 }
+/** Default callback identity survives any number of per-pass caches. */
+const defaultFormatters = new WeakSet(Object.values(defaultTerminalTheme).filter((value) => typeof value === "function"));
 function formatTerminalTerm(term, theme = {}, quotes = false, usage) {
+	return formatTerminalLeaf(term, theme, quotes, usage).fragment;
+}
+/**
+* Renders a semantic leaf and records the selected callback's provenance.
+* @param term The semantic leaf to render.
+* @param theme The optional role overrides.
+* @param quotes Whether values should use their quoted representation.
+* @param usage The leaf's position within a usage expression.
+* @returns The fragment and whether its callback has default origin.
+* @throws {TypeError} If the term is invalid or is a message-level hard break.
+* @internal
+*/
+function formatTerminalLeaf(term, theme = {}, quotes = false, usage) {
 	const quote = (s) => quotes ? `\`${s}\`` : s;
 	let text;
 	switch (term.type) {
-		case "text": return terminalText(term.text);
+		case "text": return {
+			fragment: terminalText(term.text),
+			defaultOrigin: true
+		};
 		case "lineBreak": throw new TypeError("Hard breaks must be rendered at the message level.");
 		case "optionName":
 			text = quote(term.optionName);
@@ -65,19 +83,25 @@ function formatTerminalTerm(term, theme = {}, quotes = false, usage) {
 		usage,
 		format: (child) => formatTerminalTerm(child, theme, quotes, usage)
 	};
+	function render(formatter, value) {
+		return {
+			fragment: formatter(value, ctx),
+			defaultOrigin: defaultFormatters.has(formatter)
+		};
+	}
 	switch (term.type) {
-		case "optionName": return (theme.optionName ?? defaultTerminalTheme.optionName)(term, ctx);
-		case "optionNames": return (theme.optionNames ?? defaultTerminalTheme.optionNames)(term, ctx);
-		case "metavar": return (theme.metavar ?? defaultTerminalTheme.metavar)(term, ctx);
-		case "value": return (theme.value ?? defaultTerminalTheme.value)(term, ctx);
-		case "values": return valuesFormatter(theme)(term, ctx);
-		case "envVar": return (theme.envVar ?? defaultTerminalTheme.envVar)(term, ctx);
-		case "commandLine": return (theme.commandLine ?? defaultTerminalTheme.commandLine)(term, ctx);
-		case "url": return (theme.url ?? defaultTerminalTheme.url)(term, ctx);
-		case "programName": return (theme.programName ?? defaultTerminalTheme.programName)(term, ctx);
-		case "label": return (theme.label ?? defaultTerminalTheme.label)(term, ctx);
-		case "syntaxPunctuation": return (theme.syntaxPunctuation ?? defaultTerminalTheme.syntaxPunctuation)(term, ctx);
-		case "errorLabel": return (theme.errorLabel ?? defaultTerminalTheme.errorLabel)(term, ctx);
+		case "optionName": return render(theme.optionName ?? defaultTerminalTheme.optionName, term);
+		case "optionNames": return render(theme.optionNames ?? defaultTerminalTheme.optionNames, term);
+		case "metavar": return render(theme.metavar ?? defaultTerminalTheme.metavar, term);
+		case "value": return render(theme.value ?? defaultTerminalTheme.value, term);
+		case "values": return render(valuesFormatter(theme), term);
+		case "envVar": return render(theme.envVar ?? defaultTerminalTheme.envVar, term);
+		case "commandLine": return render(theme.commandLine ?? defaultTerminalTheme.commandLine, term);
+		case "url": return render(theme.url ?? defaultTerminalTheme.url, term);
+		case "programName": return render(theme.programName ?? defaultTerminalTheme.programName, term);
+		case "label": return render(theme.label ?? defaultTerminalTheme.label, term);
+		case "syntaxPunctuation": return render(theme.syntaxPunctuation ?? defaultTerminalTheme.syntaxPunctuation, term);
+		case "errorLabel": return render(theme.errorLabel ?? defaultTerminalTheme.errorLabel, term);
 	}
 }
 const colorNames = [
@@ -225,14 +249,14 @@ function serializeTokens(tokens, colors = false, resetSuffix = "", ambient = {})
 * @since 1.3.0
 * @internal
 */
-function renderTerminalTerm(term, theme, colors, usage, ambient) {
-	return serializeTokens(fragmentTokens(formatTerminalTerm(term, theme, false, usage)), colors, "", ambient);
+function renderTerminalTerm(term, theme, colors, usage, ambient, resetSuffix = "") {
+	return serializeTokens(fragmentTokens(formatTerminalTerm(term, theme, false, usage)), colors, resetSuffix, ambient);
 }
 /** Memoizes semantic leaves for one layout pass, including measurement. */
 function cacheTerminalTheme(theme = {}) {
 	function cache(formatter) {
 		const fragments = /* @__PURE__ */ new Map();
-		return (term, context) => {
+		const cached = (term, context) => {
 			const key = JSON.stringify([
 				term,
 				context.quotes,
@@ -245,6 +269,8 @@ function cacheTerminalTheme(theme = {}) {
 			}
 			return fragment;
 		};
+		if (defaultFormatters.has(formatter)) defaultFormatters.add(cached);
+		return cached;
 	}
 	return {
 		optionName: cache(theme.optionName ?? defaultTerminalTheme.optionName),
@@ -267,4 +293,4 @@ function cacheTerminalTheme(theme = {}) {
 }
 
 //#endregion
-export { cacheTerminalTheme, formatTerminalTerm, fragmentTokens, renderTerminalTerm, serializeTokens, styleCode, terminalText };
+export { cacheTerminalTheme, formatTerminalLeaf, formatTerminalTerm, fragmentTokens, renderTerminalTerm, serializeTokens, styleCode, terminalText };

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

@@ -204,23 +204,17 @@ function formatUsage(programName, usage, options = {}) {
 			if (lines.length > 0) return lines.join("\n");
 		}
 	}
-	const programTokens = layoutUsageTokens(require_terminal_internal.fragmentTokens(require_terminal_internal.formatTerminalTerm({
-		type: "programName",
-		programName
-	}, options.theme)), options);
-	const terms = [...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 ? {
-		text: "\n",
-		width: -1,
-		scopes: []
-	} : {
-		text: " ",
-		width: 1,
-		scopes: []
-	};
-	return require_terminal_internal.serializeTokens([...programTokens, separator], options.colors) + wrapUsageTokens(terms, options, separator.width === -1 ? 0 : width + 1);
+	return wrapUsageTokens(function* () {
+		yield* usageLeafTokens({
+			type: "programName",
+			programName
+		}, options);
+		yield {
+			...usageSpace,
+			programBoundary: true
+		};
+		yield* formatUsageTerms(usage, options);
+	}(), options);
 }
 /**
 * Normalizes a usage description by flattening nested exclusive terms,
@@ -450,14 +444,23 @@ function filterUsageForDisplay(usage, isHidden = isUsageHidden) {
 	}
 	return terms;
 }
+const usageSpace = {
+	text: " ",
+	width: 1,
+	scopes: [],
+	separator: true
+};
+function* usageLeafTokens(term, options, usage) {
+	const { fragment, defaultOrigin } = require_terminal_internal.formatTerminalLeaf(term, options.theme, false, usage);
+	for (const token of require_terminal_internal.fragmentTokens(fragment)) yield {
+		...token,
+		legacyWhitespace: defaultOrigin
+	};
+}
 function* formatUsageTerms(terms, options) {
 	let i = 0;
 	for (const t of terms) {
-		if (i > 0) yield {
-			text: " ",
-			width: 1,
-			scopes: []
-		};
+		if (i > 0) yield usageSpace;
 		yield* formatUsageTermInternal(t, options);
 		i++;
 	}
@@ -483,21 +486,57 @@ function formatUsageTerm(term, options = {}) {
 	if (visibleTerms.length < 1) return "";
 	return wrapUsageTokens(formatUsageTermInternal(visibleTerms[0], options), options);
 }
-function wrapUsageTokens(input, options, initialWidth = 0) {
-	return require_terminal_internal.serializeTokens(layoutUsageTokens(input, options, initialWidth), options.colors);
+function wrapUsageTokens(input, options) {
+	return require_terminal_internal.serializeTokens(layoutUsageTokens(input, options), options.colors);
 }
-function layoutUsageTokens(input, options, initialWidth = 0) {
-	let lineWidth = initialWidth;
-	const output = [];
+/** 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) {
+	let lineWidth = 0;
+	const output = [];
+	const tokens = [...normalizeUsageSeparators(input)];
+	for (const [index, token] of tokens.entries()) {
+		if (token.programBoundary && options.maxWidth != null) {
+			const next = tokens.find((item, i) => i > index && item.text !== "");
+			if (next != null && lineWidth + token.width + next.width > options.maxWidth) {
+				output.push({
+					text: "\n",
+					width: -1,
+					scopes: []
+				});
+				lineWidth = 0;
+				continue;
+			}
+		}
 		if (token.width === -1) {
 			output.push(token);
 			lineWidth = 0;
 			continue;
 		}
-		if (options.maxWidth != null && lineWidth > 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] = {
+		if (options.maxWidth != null && lineWidth > 0 && token.width > 0 && lineWidth + token.width > options.maxWidth) {
+			let lastIndex = output.length - 1;
+			while (lastIndex >= 0 && output[lastIndex].text === "") lastIndex--;
+			const last = output[lastIndex];
+			if (last?.text.endsWith(" ") && (last.separator || last.legacyWhitespace && (!options.colors || last.scopes.length === 0))) output[lastIndex] = {
 				...last,
 				text: last.text.slice(0, -1),
 				width: last.width - 1
@@ -508,7 +547,7 @@ function layoutUsageTokens(input, options, initialWidth = 0) {
 				scopes: []
 			});
 			lineWidth = 0;
-			if (token.text === " ") continue;
+			if (token.separator || token.legacyWhitespace && token.text === " ") continue;
 		}
 		output.push(token);
 		lineWidth += token.width;
@@ -517,7 +556,7 @@ function layoutUsageTokens(input, options, initialWidth = 0) {
 }
 function* formatUsageTermInternal(term, options) {
 	function leaf(t, usage) {
-		return require_terminal_internal.fragmentTokens(require_terminal_internal.formatTerminalTerm(t, options.theme, false, usage));
+		return usageLeafTokens(t, options, usage);
 	}
 	function punctuation(punctuation$1, kind) {
 		return leaf({
@@ -526,11 +565,7 @@ function* formatUsageTermInternal(term, options) {
 			kind
 		});
 	}
-	const space = {
-		text: " ",
-		width: 1,
-		scopes: []
-	};
+	const space = usageSpace;
 	if (term.type === "argument") yield* leaf({
 		type: "metavar",
 		metavar: term.metavar