@optique/core 1.3.2 → 1.3.4

package/dist/internal/command-doc-metadata.js

@@ -0,0 +1,87 @@
+//#region src/internal/command-doc-metadata.ts
+function withOrigin(metadata, origin) {
+	const result = { ...metadata };
+	Object.defineProperty(result, "origin", {
+		value: origin,
+		enumerable: false
+	});
+	return result;
+}
+const commandDocMetadata = Symbol.for("@optique/core/commandDocMetadata");
+const commandDocCarrier = Symbol.for("@optique/core/commandDocMetadataCarrier");
+/**
+* Reads effective page metadata, including custom collection-level fields.
+* @param docs The child's documentation.
+* @returns Its selected-command metadata, if any.
+*/
+function getCommandDocMetadata(docs) {
+	const carrier = docs.fragments[commandDocCarrier];
+	if (carrier != null) {
+		const brief = docs.brief === carrier.brief ? carrier.metadata.brief : docs.brief;
+		const origin = carrier.metadata.origin ?? "entry";
+		const customPage = origin === "entry" && (docs.brief !== carrier.brief || docs.footer !== carrier.footer);
+		const description = origin === "entry" && !customPage || docs.description === carrier.description ? carrier.metadata.description : docs.description;
+		const footer = docs.footer === carrier.footer ? carrier.metadata.footer : docs.footer;
+		return withOrigin({
+			...brief == null ? {} : { brief },
+			...description == null ? {} : { description },
+			...footer == null ? {} : { footer }
+		}, customPage ? "custom" : origin);
+	}
+	const metadata = docs[commandDocMetadata];
+	if (metadata != null) return metadata;
+	return docs.brief != null || docs.description != null || docs.footer != null ? withOrigin({
+		brief: docs.brief,
+		description: docs.description,
+		footer: docs.footer
+	}, "custom") : void 0;
+}
+/**
+* Preserves selected-command metadata when rebuilding documentation fragments.
+* @param docs The rebuilt documentation.
+* @param metadata The selected-command metadata to preserve.
+* @returns Documentation with the internal metadata attached.
+*/
+function withCommandDocMetadata(docs, metadata) {
+	if (metadata == null) return docs;
+	metadata = withOrigin(metadata, metadata.origin ?? "entry");
+	const fragments = [...docs.fragments];
+	Object.defineProperty(fragments, commandDocCarrier, { value: {
+		metadata,
+		brief: docs.brief,
+		description: docs.description,
+		footer: docs.footer
+	} });
+	const result = {
+		...docs,
+		fragments
+	};
+	Object.defineProperty(result, commandDocMetadata, { value: metadata });
+	return result;
+}
+/**
+* Collects selected-command metadata in documentation traversal order.
+* @param current Metadata from earlier children.
+* @param docs The next child's documentation.
+* @param includeCustom Whether to retain custom page fields inside merge().
+* @returns The first defined value from children with the same origin.
+*/
+function collectCommandDocMetadata(current, docs, includeCustom = false) {
+	const next = getCommandDocMetadata(docs);
+	if (next == null) return current;
+	const origin = next.origin ?? "entry";
+	if (origin === "entry" || origin === "custom" && !includeCustom) return current ?? withOrigin({}, "entry");
+	if (current?.origin === "command" && origin !== "command") return current;
+	if (current?.origin !== origin) current = void 0;
+	const brief = current?.brief ?? next.brief;
+	const description = current?.description ?? next.description;
+	const footer = current?.footer ?? next.footer;
+	return withOrigin({
+		...brief == null ? {} : { brief },
+		...description == null ? {} : { description },
+		...footer == null ? {} : { footer }
+	}, origin);
+}
+
+//#endregion
+export { collectCommandDocMetadata, getCommandDocMetadata, withCommandDocMetadata };

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

@@ -4,6 +4,7 @@ const require_mode_dispatch = require('./internal/mode-dispatch.cjs');
 const require_dependency_runtime = require('./dependency-runtime.cjs');
 const require_internal_parser = require('./internal/parser.cjs');
 const require_annotation_state = require('./annotation-state.cjs');
+const require_command_doc_metadata = require('./internal/command-doc-metadata.cjs');
 const require_passthrough = require('./internal/passthrough.cjs');
 const require_execution_context = require('./execution-context.cjs');
 const require_phase2_seed = require('./phase2-seed.cjs');
@@ -653,10 +654,10 @@ function withDefault(parser, defaultValue, options) {
 					};
 					return fragment;
 				});
-				return {
+				return require_command_doc_metadata.withCommandDocMetadata({
 					...fragments,
 					fragments: modifiedFragments
-				};
+				}, require_command_doc_metadata.getCommandDocMetadata(fragments));
 			}
 			return fragments;
 		}

package/dist/modifiers.js

@@ -4,6 +4,7 @@ import { dispatchByMode, dispatchIterableByMode, mapModeValue, wrapForMode } fro
 import { defineForwardedEffectfulSchedulingNodes } from "./dependency-runtime.js";
 import { defineInheritedAnnotationParser, defineParseLanes, defineSourceBindingOnlyAnnotationCompletionParser, getOwnParseLanes, unmatchedNonCliDependencySourceStateMarker } from "./internal/parser.js";
 import { getDelegatedAnnotationState, hasDelegatedAnnotationCarrier, isAnnotationWrappedInitialState, normalizeDelegatedAnnotationState, normalizeNestedDelegatedAnnotationState } from "./annotation-state.js";
+import { getCommandDocMetadata, withCommandDocMetadata } from "./internal/command-doc-metadata.js";
 import { defineKnownCompletionLookup, defineOptionMatch, definePassThroughPriority, getKnownCompletion, getOptionMatch, getPassThroughPriority } from "./internal/passthrough.js";
 import { mergeChildExec, withChildContext, withChildExecPath } from "./execution-context.js";
 import { completeOrExtractPhase2Seed, extractPhase2Seed, extractPhase2SeedKey, phase2SeedFromValueResult } from "./phase2-seed.js";
@@ -653,10 +654,10 @@ function withDefault(parser, defaultValue, options) {
 					};
 					return fragment;
 				});
-				return {
+				return withCommandDocMetadata({
 					...fragments,
 					fragments: modifiedFragments
-				};
+				}, getCommandDocMetadata(fragments));
 			}
 			return fragments;
 		}

package/dist/primitives.cjs

@@ -6,6 +6,7 @@ const require_mode_dispatch = require('./internal/mode-dispatch.cjs');
 const require_internal_dependency = require('./internal/dependency.cjs');
 const require_dependency_runtime = require('./dependency-runtime.cjs');
 const require_annotation_state = require('./annotation-state.cjs');
+const require_command_doc_metadata = require('./internal/command-doc-metadata.cjs');
 const require_passthrough = require('./internal/passthrough.cjs');
 const require_command_alias = require('./internal/command-alias.cjs');
 const require_execution_context = require('./execution-context.cjs');
@@ -646,10 +647,10 @@ function option(...args) {
 			return suggestOptionSync(optionNames$1, valueParser, require_usage.isSuggestionHidden(options.hidden), options.description, context, prefix);
 		},
 		getDocFragments(_state, defaultValue) {
-			if (require_usage.isDocHidden(options.hidden)) return {
+			if (require_usage.isDocHidden(options.hidden)) return require_command_doc_metadata.withCommandDocMetadata({
 				fragments: [],
 				description: options.description
-			};
+			}, {});
 			const choicesMessage = valueParser?.choices != null && valueParser.choices.length > 0 ? require_message.valueSet(valueParser.choices.map((c) => valueParser.format(c)), {
 				fallback: "",
 				type: "unit"
@@ -665,10 +666,10 @@ function option(...args) {
 				default: defaultValue != null && valueParser != null ? require_message.message`${valueParser.format(defaultValue)}` : void 0,
 				choices: choicesMessage
 			}];
-			return {
+			return require_command_doc_metadata.withCommandDocMetadata({
 				fragments,
 				description: options.description
-			};
+			}, {});
 		},
 		[Symbol.for("Deno.customInspect")]() {
 			return `option(${optionNames$1.map((o) => JSON.stringify(o)).join(", ")})`;
@@ -937,10 +938,10 @@ function flag(...args) {
 			return suggestions;
 		},
 		getDocFragments(_state, _defaultValue) {
-			if (require_usage.isDocHidden(options.hidden)) return {
+			if (require_usage.isDocHidden(options.hidden)) return require_command_doc_metadata.withCommandDocMetadata({
 				fragments: [],
 				description: options.description
-			};
+			}, {});
 			const fragments = [{
 				type: "entry",
 				term: {
@@ -949,10 +950,10 @@ function flag(...args) {
 				},
 				description: options.description
 			}];
-			return {
+			return require_command_doc_metadata.withCommandDocMetadata({
 				fragments,
 				description: options.description
-			};
+			}, {});
 		},
 		[Symbol.for("Deno.customInspect")]() {
 			return `flag(${optionNames$1.map((o) => JSON.stringify(o)).join(", ")})`;
@@ -1309,10 +1310,10 @@ function argument(valueParser, options = {}) {
 			return suggestArgumentSync(valueParser, require_usage.isSuggestionHidden(options.hidden), prefix, context.dependencyRegistry, context.exec);
 		},
 		getDocFragments(_state, defaultValue) {
-			if (require_usage.isDocHidden(options.hidden)) return {
+			if (require_usage.isDocHidden(options.hidden)) return require_command_doc_metadata.withCommandDocMetadata({
 				fragments: [],
 				description: options.description
-			};
+			}, {});
 			const choicesMessage = valueParser.choices != null && valueParser.choices.length > 0 ? require_message.valueSet(valueParser.choices.map((c) => valueParser.format(c)), {
 				fallback: "",
 				type: "unit"
@@ -1324,10 +1325,10 @@ function argument(valueParser, options = {}) {
 				default: defaultValue == null ? void 0 : require_message.message`${valueParser.format(defaultValue)}`,
 				choices: choicesMessage
 			}];
-			return {
+			return require_command_doc_metadata.withCommandDocMetadata({
 				fragments,
 				description: options.description
-			};
+			}, {});
 		},
 		[Symbol.for("Deno.customInspect")]() {
 			return `argument()`;
@@ -1678,11 +1679,11 @@ function command(name, parser, options = {}) {
 		getDocFragments(state, defaultValue) {
 			const commandState = state.kind === "available" ? normalizeCommandState(state.state) : void 0;
 			if (state.kind === "unavailable" || typeof commandState === "undefined") {
-				if (require_usage.isDocHidden(options.hidden)) return {
+				if (require_usage.isDocHidden(options.hidden)) return require_command_doc_metadata.withCommandDocMetadata({
 					fragments: [],
 					description: options.description
-				};
-				return {
+				}, {});
+				return require_command_doc_metadata.withCommandDocMetadata({
 					description: options.description,
 					fragments: [{
 						type: "entry",
@@ -1692,7 +1693,7 @@ function command(name, parser, options = {}) {
 						},
 						description: options.brief ?? options.description
 					}]
-				};
+				}, {});
 			}
 			const innerState = commandState[0] === "parsing" ? {
 				kind: "available",
@@ -1702,12 +1703,18 @@ function command(name, parser, options = {}) {
 				state: getCommandChildState(state.state, parser.initialState, parser)
 			};
 			const innerFragments = parser.getDocFragments(innerState, defaultValue);
-			return {
+			const innerMetadata = require_command_doc_metadata.getCommandDocMetadata(innerFragments) ?? innerFragments;
+			return require_command_doc_metadata.withCommandDocMetadata({
 				...innerFragments,
 				brief: innerFragments.brief ?? options.brief,
 				description: innerFragments.description ?? options.description,
 				footer: innerFragments.footer ?? options.footer
-			};
+			}, {
+				origin: "command",
+				brief: innerMetadata?.brief ?? options.brief,
+				description: innerMetadata?.description ?? options.description,
+				footer: innerMetadata?.footer ?? options.footer
+			});
 		},
 		[Symbol.for("Deno.customInspect")]() {
 			return `command(${JSON.stringify(name)})`;
@@ -1932,18 +1939,18 @@ function passThrough(options = {}) {
 			return [];
 		},
 		getDocFragments(_state, _defaultValue) {
-			if (require_usage.isDocHidden(options.hidden)) return {
+			if (require_usage.isDocHidden(options.hidden)) return require_command_doc_metadata.withCommandDocMetadata({
 				fragments: [],
 				description: options.description
-			};
-			return {
+			}, {});
+			return require_command_doc_metadata.withCommandDocMetadata({
 				fragments: [{
 					type: "entry",
 					term: { type: "passthrough" },
 					description: options.description
 				}],
 				description: options.description
-			};
+			}, {});
 		},
 		[Symbol.for("Deno.customInspect")]() {
 			return `passThrough(${format})`;

package/dist/primitives.js

@@ -6,6 +6,7 @@ import { dispatchByMode, dispatchIterableByMode, wrapForMode } from "./internal/
 import { getDefaultValuesFunction, getDependencyIds, getSnapshottedDefaultDependencyValues, isDerivedValueParser, suggestWithDependency } from "./internal/dependency.js";
 import { effectfulSchedulingNodesKey, exclusiveSourceScopeKey, includeSourceFailureChain, recordDerivedRawInput, replayDerivedParser, replayDerivedParserAsync, sourceCollectionExpansionKey } from "./dependency-runtime.js";
 import { getWrappedChildParseState, getWrappedChildState, isAnnotationWrappedInitialState, normalizeInjectedAnnotationState } from "./annotation-state.js";
+import { getCommandDocMetadata, withCommandDocMetadata } from "./internal/command-doc-metadata.js";
 import { defineKnownCompletion, defineOptionMatch, definePassThroughPriority, getOptionMatch, getPassThroughFailure, getPassThroughPriority } from "./internal/passthrough.js";
 import { hiddenCommandAliasesKey } from "./internal/command-alias.js";
 import { mergeChildExec, withChildContext, withChildExecPath } from "./execution-context.js";
@@ -646,10 +647,10 @@ function option(...args) {
 			return suggestOptionSync(optionNames$1, valueParser, isSuggestionHidden(options.hidden), options.description, context, prefix);
 		},
 		getDocFragments(_state, defaultValue) {
-			if (isDocHidden(options.hidden)) return {
+			if (isDocHidden(options.hidden)) return withCommandDocMetadata({
 				fragments: [],
 				description: options.description
-			};
+			}, {});
 			const choicesMessage = valueParser?.choices != null && valueParser.choices.length > 0 ? valueSet(valueParser.choices.map((c) => valueParser.format(c)), {
 				fallback: "",
 				type: "unit"
@@ -665,10 +666,10 @@ function option(...args) {
 				default: defaultValue != null && valueParser != null ? message`${valueParser.format(defaultValue)}` : void 0,
 				choices: choicesMessage
 			}];
-			return {
+			return withCommandDocMetadata({
 				fragments,
 				description: options.description
-			};
+			}, {});
 		},
 		[Symbol.for("Deno.customInspect")]() {
 			return `option(${optionNames$1.map((o) => JSON.stringify(o)).join(", ")})`;
@@ -937,10 +938,10 @@ function flag(...args) {
 			return suggestions;
 		},
 		getDocFragments(_state, _defaultValue) {
-			if (isDocHidden(options.hidden)) return {
+			if (isDocHidden(options.hidden)) return withCommandDocMetadata({
 				fragments: [],
 				description: options.description
-			};
+			}, {});
 			const fragments = [{
 				type: "entry",
 				term: {
@@ -949,10 +950,10 @@ function flag(...args) {
 				},
 				description: options.description
 			}];
-			return {
+			return withCommandDocMetadata({
 				fragments,
 				description: options.description
-			};
+			}, {});
 		},
 		[Symbol.for("Deno.customInspect")]() {
 			return `flag(${optionNames$1.map((o) => JSON.stringify(o)).join(", ")})`;
@@ -1309,10 +1310,10 @@ function argument(valueParser, options = {}) {
 			return suggestArgumentSync(valueParser, isSuggestionHidden(options.hidden), prefix, context.dependencyRegistry, context.exec);
 		},
 		getDocFragments(_state, defaultValue) {
-			if (isDocHidden(options.hidden)) return {
+			if (isDocHidden(options.hidden)) return withCommandDocMetadata({
 				fragments: [],
 				description: options.description
-			};
+			}, {});
 			const choicesMessage = valueParser.choices != null && valueParser.choices.length > 0 ? valueSet(valueParser.choices.map((c) => valueParser.format(c)), {
 				fallback: "",
 				type: "unit"
@@ -1324,10 +1325,10 @@ function argument(valueParser, options = {}) {
 				default: defaultValue == null ? void 0 : message`${valueParser.format(defaultValue)}`,
 				choices: choicesMessage
 			}];
-			return {
+			return withCommandDocMetadata({
 				fragments,
 				description: options.description
-			};
+			}, {});
 		},
 		[Symbol.for("Deno.customInspect")]() {
 			return `argument()`;
@@ -1678,11 +1679,11 @@ function command(name, parser, options = {}) {
 		getDocFragments(state, defaultValue) {
 			const commandState = state.kind === "available" ? normalizeCommandState(state.state) : void 0;
 			if (state.kind === "unavailable" || typeof commandState === "undefined") {
-				if (isDocHidden(options.hidden)) return {
+				if (isDocHidden(options.hidden)) return withCommandDocMetadata({
 					fragments: [],
 					description: options.description
-				};
-				return {
+				}, {});
+				return withCommandDocMetadata({
 					description: options.description,
 					fragments: [{
 						type: "entry",
@@ -1692,7 +1693,7 @@ function command(name, parser, options = {}) {
 						},
 						description: options.brief ?? options.description
 					}]
-				};
+				}, {});
 			}
 			const innerState = commandState[0] === "parsing" ? {
 				kind: "available",
@@ -1702,12 +1703,18 @@ function command(name, parser, options = {}) {
 				state: getCommandChildState(state.state, parser.initialState, parser)
 			};
 			const innerFragments = parser.getDocFragments(innerState, defaultValue);
-			return {
+			const innerMetadata = getCommandDocMetadata(innerFragments) ?? innerFragments;
+			return withCommandDocMetadata({
 				...innerFragments,
 				brief: innerFragments.brief ?? options.brief,
 				description: innerFragments.description ?? options.description,
 				footer: innerFragments.footer ?? options.footer
-			};
+			}, {
+				origin: "command",
+				brief: innerMetadata?.brief ?? options.brief,
+				description: innerMetadata?.description ?? options.description,
+				footer: innerMetadata?.footer ?? options.footer
+			});
 		},
 		[Symbol.for("Deno.customInspect")]() {
 			return `command(${JSON.stringify(name)})`;
@@ -1932,18 +1939,18 @@ function passThrough(options = {}) {
 			return [];
 		},
 		getDocFragments(_state, _defaultValue) {
-			if (isDocHidden(options.hidden)) return {
+			if (isDocHidden(options.hidden)) return withCommandDocMetadata({
 				fragments: [],
 				description: options.description
-			};
-			return {
+			}, {});
+			return withCommandDocMetadata({
 				fragments: [{
 					type: "entry",
 					term: { type: "passthrough" },
 					description: options.description
 				}],
 				description: options.description
-			};
+			}, {});
 		},
 		[Symbol.for("Deno.customInspect")]() {
 			return `passThrough(${format})`;

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;