@optique/core 1.3.2 → 1.3.3

package/dist/doc.cjs

@@ -431,8 +431,16 @@ function formatDocPage(programName, page, options = {}) {
 				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";
+				let prefixText = layout.prefix;
+				let prefix = require_text_layout.placeText(prefixText, cursor, descColumnWidth, 1);
+				if (prefix.text !== layout.prefix) {
+					description += "\n";
+					prefixText = require_text_layout.trimLeadingSpace(layout.prefix);
+					prefix = require_text_layout.placeText(prefixText, {
+						line: "",
+						column: 0
+					});
+				}
 				const rendered = formatMessage(content, {
 					colors: options.colors ? { resetSuffix: style } : false,
 					quotes,
@@ -440,7 +448,7 @@ function formatDocPage(programName, page, options = {}) {
 					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}`;
+				const annotationText = `${prefixText}${rendered}${opaqueFormatter && options.colors ? style : ""}${suffix.text}`;
 				description += options.colors ? `${style}${annotationText}${style ? "\x1B[0m" : ""}` : annotationText;
 				cursor = suffix.cursor;
 			};

package/dist/doc.js

@@ -1,5 +1,5 @@
 import { cacheTerminalTheme, renderTerminalTerm, styleCode } from "./terminal-internal.js";
-import { measureAnnotation, measureText, placeText, spaceAfterLabel } from "./text-layout.js";
+import { measureAnnotation, measureText, placeText, spaceAfterLabel, trimLeadingSpace } from "./text-layout.js";
 import { validateLabel, validateProgramName } from "./validate.js";
 import { cloneUsageTerm, formatUsage, formatUsageTerm, isDocHidden } from "./usage.js";
 import { hasAutomaticWidth, minimumUsageWidth, reportAutomaticWidth } from "./terminal-width.js";
@@ -431,8 +431,16 @@ function formatDocPage(programName, page, options = {}) {
 				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";
+				let prefixText = layout.prefix;
+				let prefix = placeText(prefixText, cursor, descColumnWidth, 1);
+				if (prefix.text !== layout.prefix) {
+					description += "\n";
+					prefixText = trimLeadingSpace(layout.prefix);
+					prefix = placeText(prefixText, {
+						line: "",
+						column: 0
+					});
+				}
 				const rendered = formatMessage(content, {
 					colors: options.colors ? { resetSuffix: style } : false,
 					quotes,
@@ -440,7 +448,7 @@ function formatDocPage(programName, page, options = {}) {
 					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}`;
+				const annotationText = `${prefixText}${rendered}${opaqueFormatter && options.colors ? style : ""}${suffix.text}`;
 				description += options.colors ? `${style}${annotationText}${style ? "\x1B[0m" : ""}` : annotationText;
 				cursor = suffix.cursor;
 			};

package/dist/message.cjs

@@ -347,7 +347,8 @@ function renderMessage(msg, options, theme, ambient) {
 							yield {
 								text: match[0],
 								width: require_displaywidth.getDisplayWidth(match[0]),
-								scopes: []
+								scopes: [],
+								trimOnWrap: true
 							};
 						}
 					}
@@ -356,7 +357,8 @@ function renderMessage(msg, options, theme, ambient) {
 					if (normalizedText.trim() === "" && normalizedText.length > 0) yield {
 						text: " ",
 						width: 1,
-						scopes: []
+						scopes: [],
+						trimOnWrap: true
 					};
 					else {
 						wordPattern.lastIndex = 0;
@@ -366,7 +368,8 @@ function renderMessage(msg, options, theme, ambient) {
 							yield {
 								text: match[0],
 								width: require_displaywidth.getDisplayWidth(match[0]),
-								scopes: []
+								scopes: [],
+								trimOnWrap: true
 							};
 						}
 					}
@@ -383,22 +386,46 @@ function renderMessage(msg, options, theme, ambient) {
 	}
 	const tokens = [];
 	let totalWidth = initialWidth;
-	for (const token of stream()) {
+	let pendingWrap = false;
+	let atWrappedLineStart = false;
+	for (let token of stream()) {
 		if (token.width === -1) {
 			tokens.push(token);
 			totalWidth = 0;
+			pendingWrap = false;
+			atWrappedLineStart = false;
+			continue;
+		}
+		const wraps = pendingWrap || options.maxWidth != null && totalWidth > 0 && totalWidth + token.width > options.maxWidth;
+		if ((wraps || atWrappedLineStart) && token.trimOnWrap) {
+			const text$1 = token.text.trimStart();
+			token = {
+				...token,
+				text: text$1,
+				width: token.width - require_displaywidth.getDisplayWidth(token.text.slice(0, token.text.length - text$1.length))
+			};
+			if (text$1 === "") {
+				if (wraps) pendingWrap = true;
+				continue;
+			}
+		}
+		if (pendingWrap && require_displaywidth.stripAnsi(token.text) === "") {
+			tokens.push(token);
 			continue;
 		}
-		if (options.maxWidth != null && totalWidth > 0 && totalWidth + token.width > options.maxWidth) {
+		if (wraps) {
 			tokens.push({
 				text: "\n",
 				width: -1,
 				scopes: []
 			});
 			totalWidth = 0;
+			pendingWrap = false;
+			atWrappedLineStart = true;
 		}
 		tokens.push(token);
 		totalWidth += token.width;
+		if (token.width > 0) atWrappedLineStart = false;
 	}
 	return require_terminal_internal.serializeTokens(tokens, useColors, ambient == null ? resetSuffix : "", ambient);
 }

package/dist/message.js

@@ -1,4 +1,4 @@
-import { getDisplayWidth } from "./displaywidth.js";
+import { getDisplayWidth, stripAnsi } from "./displaywidth.js";
 import { formatTerminalTerm, fragmentTokens, serializeTokens } from "./terminal-internal.js";
 import { messageRenderers } from "./message-registry.js";
 
@@ -347,7 +347,8 @@ function renderMessage(msg, options, theme, ambient) {
 							yield {
 								text: match[0],
 								width: getDisplayWidth(match[0]),
-								scopes: []
+								scopes: [],
+								trimOnWrap: true
 							};
 						}
 					}
@@ -356,7 +357,8 @@ function renderMessage(msg, options, theme, ambient) {
 					if (normalizedText.trim() === "" && normalizedText.length > 0) yield {
 						text: " ",
 						width: 1,
-						scopes: []
+						scopes: [],
+						trimOnWrap: true
 					};
 					else {
 						wordPattern.lastIndex = 0;
@@ -366,7 +368,8 @@ function renderMessage(msg, options, theme, ambient) {
 							yield {
 								text: match[0],
 								width: getDisplayWidth(match[0]),
-								scopes: []
+								scopes: [],
+								trimOnWrap: true
 							};
 						}
 					}
@@ -383,22 +386,46 @@ function renderMessage(msg, options, theme, ambient) {
 	}
 	const tokens = [];
 	let totalWidth = initialWidth;
-	for (const token of stream()) {
+	let pendingWrap = false;
+	let atWrappedLineStart = false;
+	for (let token of stream()) {
 		if (token.width === -1) {
 			tokens.push(token);
 			totalWidth = 0;
+			pendingWrap = false;
+			atWrappedLineStart = false;
+			continue;
+		}
+		const wraps = pendingWrap || options.maxWidth != null && totalWidth > 0 && totalWidth + token.width > options.maxWidth;
+		if ((wraps || atWrappedLineStart) && token.trimOnWrap) {
+			const text$1 = token.text.trimStart();
+			token = {
+				...token,
+				text: text$1,
+				width: token.width - getDisplayWidth(token.text.slice(0, token.text.length - text$1.length))
+			};
+			if (text$1 === "") {
+				if (wraps) pendingWrap = true;
+				continue;
+			}
+		}
+		if (pendingWrap && stripAnsi(token.text) === "") {
+			tokens.push(token);
 			continue;
 		}
-		if (options.maxWidth != null && totalWidth > 0 && totalWidth + token.width > options.maxWidth) {
+		if (wraps) {
 			tokens.push({
 				text: "\n",
 				width: -1,
 				scopes: []
 			});
 			totalWidth = 0;
+			pendingWrap = false;
+			atWrappedLineStart = true;
 		}
 		tokens.push(token);
 		totalWidth += token.width;
+		if (token.width > 0) atWrappedLineStart = false;
 	}
 	return serializeTokens(tokens, useColors, ambient == null ? resetSuffix : "", ambient);
 }

package/dist/terminal-internal.cjs

@@ -1,4 +1,5 @@
 const require_displaywidth = require('./displaywidth.cjs');
+const require_terminal_separators = require('./terminal-separators.cjs');
 const require_terminal = require('./terminal.cjs');
 
 //#region src/terminal-internal.ts
@@ -151,6 +152,7 @@ function sameStyle(a, b) {
 }
 function* fragmentTokens(fragment, scopes = [], inherited = {}) {
 	if (fragment.type === "text") {
+		const marks = require_terminal_separators.wrapTrimmableFragments.has(fragment) ? { trimOnWrap: true } : {};
 		const lines = fragment.text.split("\n");
 		for (let i = 0; i < lines.length; i++) {
 			if (i > 0) yield {
@@ -161,7 +163,8 @@ function* fragmentTokens(fragment, scopes = [], inherited = {}) {
 			if (lines[i].length > 0 || lines.length === 1) yield {
 				text: lines[i],
 				width: require_displaywidth.getDisplayWidth(lines[i]),
-				scopes
+				scopes,
+				...marks
 			};
 		}
 		return;

package/dist/terminal-internal.d.cts

@@ -16,6 +16,11 @@ interface TerminalToken {
   readonly programBoundary?: boolean;
   /** Enables only the legacy default formatter whitespace behavior. */
   readonly legacyWhitespace?: boolean;
+  /**
+   * Leading whitespace only separates the token from preceding content, so
+   * message wrapping may drop it when the token starts a wrapped line.
+   */
+  readonly trimOnWrap?: 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

@@ -16,6 +16,11 @@ interface TerminalToken {
   readonly programBoundary?: boolean;
   /** Enables only the legacy default formatter whitespace behavior. */
   readonly legacyWhitespace?: boolean;
+  /**
+   * Leading whitespace only separates the token from preceding content, so
+   * message wrapping may drop it when the token starts a wrapped line.
+   */
+  readonly trimOnWrap?: 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

@@ -1,4 +1,5 @@
 import { getDisplayWidth } from "./displaywidth.js";
+import { wrapTrimmableFragments } from "./terminal-separators.js";
 import { defaultTerminalTheme } from "./terminal.js";
 
 //#region src/terminal-internal.ts
@@ -151,6 +152,7 @@ function sameStyle(a, b) {
 }
 function* fragmentTokens(fragment, scopes = [], inherited = {}) {
 	if (fragment.type === "text") {
+		const marks = wrapTrimmableFragments.has(fragment) ? { trimOnWrap: true } : {};
 		const lines = fragment.text.split("\n");
 		for (let i = 0; i < lines.length; i++) {
 			if (i > 0) yield {
@@ -161,7 +163,8 @@ function* fragmentTokens(fragment, scopes = [], inherited = {}) {
 			if (lines[i].length > 0 || lines.length === 1) yield {
 				text: lines[i],
 				width: getDisplayWidth(lines[i]),
-				scopes
+				scopes,
+				...marks
 			};
 		}
 		return;

package/dist/terminal-separators.cjs

@@ -0,0 +1,13 @@
+
+//#region src/terminal-separators.ts
+/**
+* Text fragments that only separate the items around them, such as the
+* spaces the default `values` formatter puts between values.  When message
+* wrapping moves such a fragment to the start of a new line, its leading
+* whitespace may be dropped.
+* @internal
+*/
+const wrapTrimmableFragments = /* @__PURE__ */ new WeakSet();
+
+//#endregion
+exports.wrapTrimmableFragments = wrapTrimmableFragments;

package/dist/terminal-separators.js

@@ -0,0 +1,12 @@
+//#region src/terminal-separators.ts
+/**
+* Text fragments that only separate the items around them, such as the
+* spaces the default `values` formatter puts between values.  When message
+* wrapping moves such a fragment to the start of a new line, its leading
+* whitespace may be dropped.
+* @internal
+*/
+const wrapTrimmableFragments = /* @__PURE__ */ new WeakSet();
+
+//#endregion
+export { wrapTrimmableFragments };

package/dist/terminal.cjs

@@ -1,3 +1,4 @@
+const require_terminal_separators = require('./terminal-separators.cjs');
 
 //#region src/terminal.ts
 const plain = (text) => ({
@@ -9,6 +10,8 @@ const styled = (text, style) => ({
 	style,
 	children: [plain(text)]
 });
+const valuesSeparator = plain(" ");
+require_terminal_separators.wrapTrimmableFragments.add(valuesSeparator);
 /**
 * Optique's built-in terminal theme, with every formatter available for delegation.
 * @since 1.3.0
@@ -34,7 +37,7 @@ const defaultTerminalTheme = {
 	value: (_term, ctx) => ctx.usage === "literal" ? plain(ctx.text) : styled(ctx.text, { foreground: "green" }),
 	values: (term, ctx) => ({
 		type: "concat",
-		children: term.values.flatMap((value, i) => [...i === 0 ? [] : [plain(" ")], ctx.format({
+		children: term.values.flatMap((value, i) => [...i === 0 ? [] : [valuesSeparator], ctx.format({
 			type: "value",
 			value
 		})])

package/dist/terminal.js

@@ -1,3 +1,5 @@
+import { wrapTrimmableFragments } from "./terminal-separators.js";
+
 //#region src/terminal.ts
 const plain = (text) => ({
 	type: "text",
@@ -8,6 +10,8 @@ const styled = (text, style) => ({
 	style,
 	children: [plain(text)]
 });
+const valuesSeparator = plain(" ");
+wrapTrimmableFragments.add(valuesSeparator);
 /**
 * Optique's built-in terminal theme, with every formatter available for delegation.
 * @since 1.3.0
@@ -33,7 +37,7 @@ const defaultTerminalTheme = {
 	value: (_term, ctx) => ctx.usage === "literal" ? plain(ctx.text) : styled(ctx.text, { foreground: "green" }),
 	values: (term, ctx) => ({
 		type: "concat",
-		children: term.values.flatMap((value, i) => [...i === 0 ? [] : [plain(" ")], ctx.format({
+		children: term.values.flatMap((value, i) => [...i === 0 ? [] : [valuesSeparator], ctx.format({
 			type: "value",
 			value
 		})])

package/dist/text-layout.cjs

@@ -51,6 +51,18 @@ function placeText(text, cursor, maxWidth, trailingRoom = 0) {
 		}
 	};
 }
+const leadingSpacePattern = /^((?:\x1B(?:\[[0-9;:]*[@-~]|\][^\x1B\x07]*(?:\x1B\\|\x07)))*)[^\S\n]+/;
+/**
+* Removes the whitespace that begins a text's first line, keeping any
+* escape sequences before it.  Used when layout moves text that starts with
+* a separating space to a fresh line.
+* @param text Rendered text, possibly containing ANSI styles or OSC links.
+* @returns The text without its leading whitespace.
+* @internal
+*/
+function trimLeadingSpace(text) {
+	return text.replace(leadingSpacePattern, "$1");
+}
 /**
 * Measures an annotation's fixed text without invoking theme callbacks.
 * @param prefix The already joined prefix and optional label.
@@ -84,4 +96,5 @@ function spaceAfterLabel(label) {
 exports.measureAnnotation = measureAnnotation;
 exports.measureText = measureText;
 exports.placeText = placeText;
-exports.spaceAfterLabel = spaceAfterLabel;
+exports.spaceAfterLabel = spaceAfterLabel;
+exports.trimLeadingSpace = trimLeadingSpace;

package/dist/text-layout.d.cts

@@ -41,7 +41,14 @@ declare function placeText(text: string, cursor: TextCursor, maxWidth?: number,
   readonly text: string;
   readonly cursor: TextCursor;
 };
-/** Fixed annotation geometry shared by preflight and placement. @internal */
+/**
+ * Removes the whitespace that begins a text's first line, keeping any
+ * escape sequences before it.  Used when layout moves text that starts with
+ * a separating space to a fresh line.
+ * @param text Rendered text, possibly containing ANSI styles or OSC links.
+ * @returns The text without its leading whitespace.
+ * @internal
+ */
 
 /**
  * Adds a separating space only when a label occupies its final physical line.

package/dist/text-layout.d.ts

@@ -41,7 +41,14 @@ declare function placeText(text: string, cursor: TextCursor, maxWidth?: number,
   readonly text: string;
   readonly cursor: TextCursor;
 };
-/** Fixed annotation geometry shared by preflight and placement. @internal */
+/**
+ * Removes the whitespace that begins a text's first line, keeping any
+ * escape sequences before it.  Used when layout moves text that starts with
+ * a separating space to a fresh line.
+ * @param text Rendered text, possibly containing ANSI styles or OSC links.
+ * @returns The text without its leading whitespace.
+ * @internal
+ */
 
 /**
  * Adds a separating space only when a label occupies its final physical line.

package/dist/text-layout.js

@@ -51,6 +51,18 @@ function placeText(text, cursor, maxWidth, trailingRoom = 0) {
 		}
 	};
 }
+const leadingSpacePattern = /^((?:\x1B(?:\[[0-9;:]*[@-~]|\][^\x1B\x07]*(?:\x1B\\|\x07)))*)[^\S\n]+/;
+/**
+* Removes the whitespace that begins a text's first line, keeping any
+* escape sequences before it.  Used when layout moves text that starts with
+* a separating space to a fresh line.
+* @param text Rendered text, possibly containing ANSI styles or OSC links.
+* @returns The text without its leading whitespace.
+* @internal
+*/
+function trimLeadingSpace(text) {
+	return text.replace(leadingSpacePattern, "$1");
+}
 /**
 * Measures an annotation's fixed text without invoking theme callbacks.
 * @param prefix The already joined prefix and optional label.
@@ -81,4 +93,4 @@ function spaceAfterLabel(label) {
 }
 
 //#endregion
-export { measureAnnotation, measureText, placeText, spaceAfterLabel };
+export { measureAnnotation, measureText, placeText, spaceAfterLabel, trimLeadingSpace };

package/package.json

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