@optique/core 1.0.0-dev.407 → 1.0.0-dev.427

package/README.md

@@ -1,9 +1,6 @@
 @optique/core
 =============
 
-> [!WARNING]
-> The API is stabilizing, but may change before the 1.0 release.
-
 The core package of Optique which provides the shared types and parser
 combinators. It is designed to be used in universal JavaScript runtimes,
 including Node.js, Deno, Bun, edge functions, and web browsers—although

package/dist/doc.cjs

@@ -17,12 +17,22 @@ function classifySection(section) {
 	return 2;
 }
 /**
+* Scores a section for the default smart sort.  Untitled sections receive
+* a bonus of `-1` so that the main (untitled) section appears before titled
+* sections of a similar classification.
+*/
+function scoreSection(section) {
+	return classifySection(section) + (section.title == null ? -1 : 0);
+}
+/**
 * The default section comparator: command-only sections come first, then
-* mixed sections, then option/argument-only sections.  Sections with the
+* mixed sections, then option/argument-only sections.  Untitled sections
+* receive a slight priority boost so the main (untitled) section appears
+* before titled sections of a similar classification.  Sections with the
 * same score preserve their original relative order (stable sort).
 */
 function defaultSectionOrder(a, b) {
-	return classifySection(a) - classifySection(b);
+	return scoreSection(a) - scoreSection(b);
 }
 /**
 * Formats a documentation page into a human-readable string.
@@ -109,18 +119,37 @@ function formatDocPage(programName, page, options = {}) {
 				optionsSeparator: ", ",
 				maxWidth: options.maxWidth == null ? void 0 : options.maxWidth - termIndent
 			});
-			let description = entry.description == null ? "" : require_message.formatMessage(entry.description, {
+			const descColumnWidth = options.maxWidth == null ? void 0 : options.maxWidth - termIndent - termWidth - 2;
+			const termVisibleWidth = lastLineVisibleLength(term);
+			const extraTermOffset = descColumnWidth != null ? Math.max(0, termVisibleWidth - termWidth) : 0;
+			const currentExtraOffset = () => description.includes("\n") ? 0 : extraTermOffset;
+			const descFormatOptions = {
 				colors: options.colors,
 				quotes: !options.colors,
-				maxWidth: options.maxWidth == null ? void 0 : options.maxWidth - termIndent - termWidth - 2
-			});
+				maxWidth: descColumnWidth,
+				startWidth: extraTermOffset > 0 ? extraTermOffset : void 0
+			};
+			let description = entry.description == null ? "" : require_message.formatMessage(entry.description, descFormatOptions);
 			if (options.showDefault && entry.default != null) {
 				const prefix = typeof options.showDefault === "object" ? options.showDefault.prefix ?? " [" : " [";
 				const suffix = typeof options.showDefault === "object" ? options.showDefault.suffix ?? "]" : "]";
-				const defaultText = `${prefix}${require_message.formatMessage(entry.default, {
+				let defaultStartWidth;
+				if (descColumnWidth != null) {
+					const lastW = lastLineVisibleLength(description);
+					const effectiveLastW = lastW + currentExtraOffset();
+					if (effectiveLastW + prefix.length >= descColumnWidth) {
+						description += "\n";
+						defaultStartWidth = prefix.length;
+					} else defaultStartWidth = effectiveLastW + prefix.length;
+				}
+				const defaultFormatOptions = {
 					colors: options.colors ? { resetSuffix: "\x1B[2m" } : false,
-					quotes: !options.colors
-				})}${suffix}`;
+					quotes: !options.colors,
+					maxWidth: descColumnWidth == null ? void 0 : descColumnWidth - suffix.length,
+					startWidth: defaultStartWidth
+				};
+				const defaultContent = require_message.formatMessage(entry.default, defaultFormatOptions);
+				const defaultText = `${prefix}${defaultContent}${suffix}`;
 				const formattedDefault = options.colors ? `\x1b[2m${defaultText}\x1b[0m` : defaultText;
 				description += formattedDefault;
 			}
@@ -145,10 +174,23 @@ function formatDocPage(programName, page, options = {}) {
 					}
 					if (truncated) truncatedTerms = [...terms.slice(0, cutIndex), require_message.text(", ...")];
 				}
-				const choicesDisplay = require_message.formatMessage(truncatedTerms, {
+				let choicesStartWidth;
+				if (descColumnWidth != null) {
+					const lastW = lastLineVisibleLength(description);
+					const effectiveLastW = lastW + currentExtraOffset();
+					const prefixLabelLen = prefix.length + label.length;
+					if (effectiveLastW + prefixLabelLen >= descColumnWidth) {
+						description += "\n";
+						choicesStartWidth = prefixLabelLen;
+					} else choicesStartWidth = effectiveLastW + prefixLabelLen;
+				}
+				const choicesFormatOptions = {
 					colors: options.colors ? { resetSuffix: "\x1B[2m" } : false,
-					quotes: false
-				});
+					quotes: false,
+					maxWidth: descColumnWidth == null ? void 0 : descColumnWidth - suffix.length,
+					startWidth: choicesStartWidth
+				};
+				const choicesDisplay = require_message.formatMessage(truncatedTerms, choicesFormatOptions);
 				const choicesText = `${prefix}${label}${choicesDisplay}${suffix}`;
 				const formattedChoices = options.colors ? `\x1b[2m${choicesText}\x1b[0m` : choicesText;
 				description += formattedChoices;
@@ -205,12 +247,17 @@ function formatDocPage(programName, page, options = {}) {
 function indentLines(text$1, indent) {
 	return text$1.split("\n").join("\n" + " ".repeat(indent));
 }
+const ansiEscapeCodeRegex = /\x1B\[[0-9;]*[a-zA-Z]/g;
 function ansiAwareRightPad(text$1, length, char = " ") {
-	const ansiEscapeCodeRegex = /\x1B\[[0-9;]*[a-zA-Z]/g;
 	const strippedText = text$1.replace(ansiEscapeCodeRegex, "");
 	if (strippedText.length >= length) return text$1;
 	return text$1 + char.repeat(length - strippedText.length);
 }
+function lastLineVisibleLength(text$1) {
+	const lastNewline = text$1.lastIndexOf("\n");
+	const lastLine = lastNewline === -1 ? text$1 : text$1.slice(lastNewline + 1);
+	return lastLine.replace(ansiEscapeCodeRegex, "").length;
+}
 
 //#endregion
 exports.formatDocPage = formatDocPage;

package/dist/doc.js

@@ -17,12 +17,22 @@ function classifySection(section) {
 	return 2;
 }
 /**
+* Scores a section for the default smart sort.  Untitled sections receive
+* a bonus of `-1` so that the main (untitled) section appears before titled
+* sections of a similar classification.
+*/
+function scoreSection(section) {
+	return classifySection(section) + (section.title == null ? -1 : 0);
+}
+/**
 * The default section comparator: command-only sections come first, then
-* mixed sections, then option/argument-only sections.  Sections with the
+* mixed sections, then option/argument-only sections.  Untitled sections
+* receive a slight priority boost so the main (untitled) section appears
+* before titled sections of a similar classification.  Sections with the
 * same score preserve their original relative order (stable sort).
 */
 function defaultSectionOrder(a, b) {
-	return classifySection(a) - classifySection(b);
+	return scoreSection(a) - scoreSection(b);
 }
 /**
 * Formats a documentation page into a human-readable string.
@@ -109,18 +119,37 @@ function formatDocPage(programName, page, options = {}) {
 				optionsSeparator: ", ",
 				maxWidth: options.maxWidth == null ? void 0 : options.maxWidth - termIndent
 			});
-			let description = entry.description == null ? "" : formatMessage(entry.description, {
+			const descColumnWidth = options.maxWidth == null ? void 0 : options.maxWidth - termIndent - termWidth - 2;
+			const termVisibleWidth = lastLineVisibleLength(term);
+			const extraTermOffset = descColumnWidth != null ? Math.max(0, termVisibleWidth - termWidth) : 0;
+			const currentExtraOffset = () => description.includes("\n") ? 0 : extraTermOffset;
+			const descFormatOptions = {
 				colors: options.colors,
 				quotes: !options.colors,
-				maxWidth: options.maxWidth == null ? void 0 : options.maxWidth - termIndent - termWidth - 2
-			});
+				maxWidth: descColumnWidth,
+				startWidth: extraTermOffset > 0 ? extraTermOffset : void 0
+			};
+			let description = entry.description == null ? "" : formatMessage(entry.description, descFormatOptions);
 			if (options.showDefault && entry.default != null) {
 				const prefix = typeof options.showDefault === "object" ? options.showDefault.prefix ?? " [" : " [";
 				const suffix = typeof options.showDefault === "object" ? options.showDefault.suffix ?? "]" : "]";
-				const defaultText = `${prefix}${formatMessage(entry.default, {
+				let defaultStartWidth;
+				if (descColumnWidth != null) {
+					const lastW = lastLineVisibleLength(description);
+					const effectiveLastW = lastW + currentExtraOffset();
+					if (effectiveLastW + prefix.length >= descColumnWidth) {
+						description += "\n";
+						defaultStartWidth = prefix.length;
+					} else defaultStartWidth = effectiveLastW + prefix.length;
+				}
+				const defaultFormatOptions = {
 					colors: options.colors ? { resetSuffix: "\x1B[2m" } : false,
-					quotes: !options.colors
-				})}${suffix}`;
+					quotes: !options.colors,
+					maxWidth: descColumnWidth == null ? void 0 : descColumnWidth - suffix.length,
+					startWidth: defaultStartWidth
+				};
+				const defaultContent = formatMessage(entry.default, defaultFormatOptions);
+				const defaultText = `${prefix}${defaultContent}${suffix}`;
 				const formattedDefault = options.colors ? `\x1b[2m${defaultText}\x1b[0m` : defaultText;
 				description += formattedDefault;
 			}
@@ -145,10 +174,23 @@ function formatDocPage(programName, page, options = {}) {
 					}
 					if (truncated) truncatedTerms = [...terms.slice(0, cutIndex), text(", ...")];
 				}
-				const choicesDisplay = formatMessage(truncatedTerms, {
+				let choicesStartWidth;
+				if (descColumnWidth != null) {
+					const lastW = lastLineVisibleLength(description);
+					const effectiveLastW = lastW + currentExtraOffset();
+					const prefixLabelLen = prefix.length + label.length;
+					if (effectiveLastW + prefixLabelLen >= descColumnWidth) {
+						description += "\n";
+						choicesStartWidth = prefixLabelLen;
+					} else choicesStartWidth = effectiveLastW + prefixLabelLen;
+				}
+				const choicesFormatOptions = {
 					colors: options.colors ? { resetSuffix: "\x1B[2m" } : false,
-					quotes: false
-				});
+					quotes: false,
+					maxWidth: descColumnWidth == null ? void 0 : descColumnWidth - suffix.length,
+					startWidth: choicesStartWidth
+				};
+				const choicesDisplay = formatMessage(truncatedTerms, choicesFormatOptions);
 				const choicesText = `${prefix}${label}${choicesDisplay}${suffix}`;
 				const formattedChoices = options.colors ? `\x1b[2m${choicesText}\x1b[0m` : choicesText;
 				description += formattedChoices;
@@ -205,12 +247,17 @@ function formatDocPage(programName, page, options = {}) {
 function indentLines(text$1, indent) {
 	return text$1.split("\n").join("\n" + " ".repeat(indent));
 }
+const ansiEscapeCodeRegex = /\x1B\[[0-9;]*[a-zA-Z]/g;
 function ansiAwareRightPad(text$1, length, char = " ") {
-	const ansiEscapeCodeRegex = /\x1B\[[0-9;]*[a-zA-Z]/g;
 	const strippedText = text$1.replace(ansiEscapeCodeRegex, "");
 	if (strippedText.length >= length) return text$1;
 	return text$1 + char.repeat(length - strippedText.length);
 }
+function lastLineVisibleLength(text$1) {
+	const lastNewline = text$1.lastIndexOf("\n");
+	const lastLine = lastNewline === -1 ? text$1 : text$1.slice(lastNewline + 1);
+	return lastLine.replace(ansiEscapeCodeRegex, "").length;
+}
 
 //#endregion
 export { formatDocPage };

package/dist/facade.cjs

@@ -543,6 +543,9 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 				const helpAsCommand = help === "command" || help === "both";
 				const versionAsCommand = version === "command" || version === "both";
 				const completionAsCommand = completion === "command" || completion === "both";
+				const helpAsOption = help === "option" || help === "both";
+				const versionAsOption = version === "option" || version === "both";
+				const completionAsOption = completion === "option" || completion === "both";
 				const requestedCommand = classified.commands[0];
 				if ((requestedCommand === "completion" || requestedCommand === "completions") && completionAsCommand && completionParsers.completionCommand) helpGeneratorParser = completionParsers.completionCommand;
 				else if (requestedCommand === "help" && helpAsCommand && helpParsers.helpCommand) helpGeneratorParser = helpParsers.helpCommand;
@@ -561,6 +564,9 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 					commandParsers.push(...ungroupedMeta);
 					for (const [label, parsers] of Object.entries(groupedMeta)) if (parsers.length === 1) commandParsers.push(require_constructs.group(label, parsers[0]));
 					else commandParsers.push(require_constructs.group(label, require_constructs.longestMatch(...parsers)));
+					if (helpAsOption && helpParsers.helpOption) commandParsers.push(helpParsers.helpOption);
+					if (versionAsOption && versionParsers.versionOption) commandParsers.push(versionParsers.versionOption);
+					if (completionAsOption && completionParsers.completionOption) commandParsers.push(completionParsers.completionOption);
 					if (commandParsers.length === 1) helpGeneratorParser = commandParsers[0];
 					else if (commandParsers.length === 2) helpGeneratorParser = require_constructs.longestMatch(commandParsers[0], commandParsers[1]);
 					else helpGeneratorParser = require_constructs.longestMatch(...commandParsers);
@@ -1045,7 +1051,7 @@ function runWithAsync(parser, programName, contexts, options) {
 */
 function injectAnnotationsIntoParser(parser, annotations) {
 	const newInitialState = {
-		...parser.initialState,
+		...typeof parser.initialState === "object" && parser.initialState !== null ? parser.initialState : {},
 		[require_annotations.annotationKey]: annotations
 	};
 	return {

package/dist/facade.js

@@ -543,6 +543,9 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 				const helpAsCommand = help === "command" || help === "both";
 				const versionAsCommand = version === "command" || version === "both";
 				const completionAsCommand = completion === "command" || completion === "both";
+				const helpAsOption = help === "option" || help === "both";
+				const versionAsOption = version === "option" || version === "both";
+				const completionAsOption = completion === "option" || completion === "both";
 				const requestedCommand = classified.commands[0];
 				if ((requestedCommand === "completion" || requestedCommand === "completions") && completionAsCommand && completionParsers.completionCommand) helpGeneratorParser = completionParsers.completionCommand;
 				else if (requestedCommand === "help" && helpAsCommand && helpParsers.helpCommand) helpGeneratorParser = helpParsers.helpCommand;
@@ -561,6 +564,9 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 					commandParsers.push(...ungroupedMeta);
 					for (const [label, parsers] of Object.entries(groupedMeta)) if (parsers.length === 1) commandParsers.push(group(label, parsers[0]));
 					else commandParsers.push(group(label, longestMatch(...parsers)));
+					if (helpAsOption && helpParsers.helpOption) commandParsers.push(helpParsers.helpOption);
+					if (versionAsOption && versionParsers.versionOption) commandParsers.push(versionParsers.versionOption);
+					if (completionAsOption && completionParsers.completionOption) commandParsers.push(completionParsers.completionOption);
 					if (commandParsers.length === 1) helpGeneratorParser = commandParsers[0];
 					else if (commandParsers.length === 2) helpGeneratorParser = longestMatch(commandParsers[0], commandParsers[1]);
 					else helpGeneratorParser = longestMatch(...commandParsers);
@@ -1045,7 +1051,7 @@ function runWithAsync(parser, programName, contexts, options) {
 */
 function injectAnnotationsIntoParser(parser, annotations) {
 	const newInitialState = {
-		...parser.initialState,
+		...typeof parser.initialState === "object" && parser.initialState !== null ? parser.initialState : {},
 		[annotationKey]: annotations
 	};
 	return {

package/dist/message.cjs

@@ -237,14 +237,6 @@ function valueSet(values$1, options) {
 	});
 	return result;
 }
-/**
-* Formats a {@link Message} into a human-readable string for
-* the terminal.
-* @param msg The message to format, which is an array of
-*              {@link MessageTerm} objects.
-* @param options Optional formatting options to customize the output.
-* @returns A formatted string representation of the message.
-*/
 function formatMessage(msg, options = {}) {
 	const colorConfig = options.colors ?? false;
 	const useColors = typeof colorConfig === "boolean" ? colorConfig : true;
@@ -253,118 +245,130 @@ function formatMessage(msg, options = {}) {
 	const resetSequence = `\x1b[0m${resetSuffix}`;
 	function* stream() {
 		const wordPattern = /\s*\S+\s*/g;
-		for (const term of msg) if (term.type === "text") if (term.text.includes("\n\n")) {
-			const paragraphs = term.text.split(/\n\n+/);
-			for (let paragraphIndex = 0; paragraphIndex < paragraphs.length; paragraphIndex++) {
-				if (paragraphIndex > 0) yield {
-					text: "\n\n",
-					width: -1
-				};
-				const paragraph = paragraphs[paragraphIndex].replace(/\n/g, " ");
-				wordPattern.lastIndex = 0;
-				while (true) {
-					const match = wordPattern.exec(paragraph);
-					if (match == null) break;
-					yield {
-						text: match[0],
-						width: match[0].length
+		let prevWasLineBreak = false;
+		for (const term of msg) {
+			const isAfterLineBreak = prevWasLineBreak;
+			prevWasLineBreak = false;
+			if (term.type === "text") {
+				const rawText = isAfterLineBreak ? term.text.replace(/^\n(?!\n)/, "") : term.text;
+				if (rawText.includes("\n\n")) {
+					const paragraphs = rawText.split(/\n\n+/);
+					for (let paragraphIndex = 0; paragraphIndex < paragraphs.length; paragraphIndex++) {
+						if (paragraphIndex > 0) {
+							const breakText = isAfterLineBreak && paragraphIndex === 1 ? "\n" : "\n\n";
+							yield {
+								text: breakText,
+								width: -1
+							};
+						}
+						const paragraph = paragraphs[paragraphIndex].replace(/\n/g, " ");
+						wordPattern.lastIndex = 0;
+						while (true) {
+							const match = wordPattern.exec(paragraph);
+							if (match == null) break;
+							yield {
+								text: match[0],
+								width: match[0].length
+							};
+						}
+					}
+				} else {
+					const normalizedText = rawText.replace(/\n/g, " ");
+					if (normalizedText.trim() === "" && normalizedText.length > 0) yield {
+						text: " ",
+						width: 1
 					};
+					else {
+						wordPattern.lastIndex = 0;
+						while (true) {
+							const match = wordPattern.exec(normalizedText);
+							if (match == null) break;
+							yield {
+								text: match[0],
+								width: match[0].length
+							};
+						}
+					}
 				}
-			}
-		} else {
-			const normalizedText = term.text.replace(/\n/g, " ");
-			if (normalizedText.trim() === "" && normalizedText.length > 0) yield {
-				text: " ",
-				width: 1
-			};
-			else {
-				wordPattern.lastIndex = 0;
-				while (true) {
-					const match = wordPattern.exec(normalizedText);
-					if (match == null) break;
+			} else if (term.type === "optionName") {
+				const name = useQuotes ? `\`${term.optionName}\`` : term.optionName;
+				yield {
+					text: useColors ? `\x1b[3m${name}${resetSequence}` : name,
+					width: name.length
+				};
+			} else if (term.type === "optionNames") {
+				const names = term.optionNames.map((name) => useQuotes ? `\`${name}\`` : name);
+				let i = 0;
+				for (const name of names) {
+					if (i > 0) yield {
+						text: "/",
+						width: 1
+					};
 					yield {
-						text: match[0],
-						width: match[0].length
+						text: useColors ? `\x1b[3m${name}${resetSequence}` : name,
+						width: name.length
 					};
+					i++;
 				}
-			}
-		}
-		else if (term.type === "optionName") {
-			const name = useQuotes ? `\`${term.optionName}\`` : term.optionName;
-			yield {
-				text: useColors ? `\x1b[3m${name}${resetSequence}` : name,
-				width: name.length
-			};
-		} else if (term.type === "optionNames") {
-			const names = term.optionNames.map((name) => useQuotes ? `\`${name}\`` : name);
-			let i = 0;
-			for (const name of names) {
+			} else if (term.type === "metavar") {
+				const metavar$1 = useQuotes ? `\`${term.metavar}\`` : term.metavar;
+				yield {
+					text: useColors ? `\x1b[1m${metavar$1}${resetSequence}` : metavar$1,
+					width: metavar$1.length
+				};
+			} else if (term.type === "value") {
+				const value$1 = useQuotes ? `${JSON.stringify(term.value)}` : term.value;
+				yield {
+					text: useColors ? `\x1b[32m${value$1}${resetSequence}` : value$1,
+					width: value$1.length
+				};
+			} else if (term.type === "values") for (let i = 0; i < term.values.length; i++) {
 				if (i > 0) yield {
-					text: "/",
+					text: " ",
 					width: 1
 				};
+				const value$1 = useQuotes ? JSON.stringify(term.values[i]) : term.values[i];
 				yield {
-					text: useColors ? `\x1b[3m${name}${resetSequence}` : name,
-					width: name.length
+					text: useColors ? i <= 0 ? `\x1b[32m${value$1}` : i + 1 >= term.values.length ? `${value$1}${resetSequence}` : value$1 : value$1,
+					width: value$1.length
 				};
-				i++;
 			}
-		} else if (term.type === "metavar") {
-			const metavar$1 = useQuotes ? `\`${term.metavar}\`` : term.metavar;
-			yield {
-				text: useColors ? `\x1b[1m${metavar$1}${resetSequence}` : metavar$1,
-				width: metavar$1.length
-			};
-		} else if (term.type === "value") {
-			const value$1 = useQuotes ? `${JSON.stringify(term.value)}` : term.value;
-			yield {
-				text: useColors ? `\x1b[32m${value$1}${resetSequence}` : value$1,
-				width: value$1.length
-			};
-		} else if (term.type === "values") for (let i = 0; i < term.values.length; i++) {
-			if (i > 0) yield {
-				text: " ",
-				width: 1
-			};
-			const value$1 = useQuotes ? JSON.stringify(term.values[i]) : term.values[i];
-			yield {
-				text: useColors ? i <= 0 ? `\x1b[32m${value$1}` : i + 1 >= term.values.length ? `${value$1}${resetSequence}` : value$1 : value$1,
-				width: value$1.length
-			};
-		}
-		else if (term.type === "envVar") {
-			const envVar$1 = useQuotes ? `\`${term.envVar}\`` : term.envVar;
-			yield {
-				text: useColors ? `\x1b[1;4m${envVar$1}${resetSequence}` : envVar$1,
-				width: envVar$1.length
-			};
-		} else if (term.type === "commandLine") {
-			const cmd = useQuotes ? `\`${term.commandLine}\`` : term.commandLine;
-			yield {
-				text: useColors ? `\x1b[36m${cmd}${resetSequence}` : cmd,
-				width: cmd.length
-			};
-		} else if (term.type === "lineBreak") yield {
-			text: "\n",
-			width: -1
-		};
-		else if (term.type === "url") {
-			const urlString = term.url.href;
-			const displayText = useQuotes ? `<${urlString}>` : urlString;
-			if (useColors) {
-				const hyperlink = `\x1b]8;;${urlString}\x1b\\${displayText}\x1b]8;;\x1b\\${resetSuffix}`;
+			else if (term.type === "envVar") {
+				const envVar$1 = useQuotes ? `\`${term.envVar}\`` : term.envVar;
+				yield {
+					text: useColors ? `\x1b[1;4m${envVar$1}${resetSequence}` : envVar$1,
+					width: envVar$1.length
+				};
+			} else if (term.type === "commandLine") {
+				const cmd = useQuotes ? `\`${term.commandLine}\`` : term.commandLine;
 				yield {
-					text: hyperlink,
+					text: useColors ? `\x1b[36m${cmd}${resetSequence}` : cmd,
+					width: cmd.length
+				};
+			} else if (term.type === "lineBreak") {
+				yield {
+					text: "\n",
+					width: -1
+				};
+				prevWasLineBreak = true;
+			} else if (term.type === "url") {
+				const urlString = term.url.href;
+				const displayText = useQuotes ? `<${urlString}>` : urlString;
+				if (useColors) {
+					const hyperlink = `\x1b]8;;${urlString}\x1b\\${displayText}\x1b]8;;\x1b\\${resetSuffix}`;
+					yield {
+						text: hyperlink,
+						width: displayText.length
+					};
+				} else yield {
+					text: displayText,
 					width: displayText.length
 				};
-			} else yield {
-				text: displayText,
-				width: displayText.length
-			};
-		} else throw new TypeError(`Invalid MessageTerm type: ${term["type"]}.`);
+			} else throw new TypeError(`Invalid MessageTerm type: ${term["type"]}.`);
+		}
 	}
 	let output = "";
-	let totalWidth = 0;
+	let totalWidth = options.startWidth ?? 0;
 	for (const { text: text$1, width } of stream()) {
 		if (width === -1) {
 			output += text$1;

package/dist/message.js

@@ -236,14 +236,6 @@ function valueSet(values$1, options) {
 	});
 	return result;
 }
-/**
-* Formats a {@link Message} into a human-readable string for
-* the terminal.
-* @param msg The message to format, which is an array of
-*              {@link MessageTerm} objects.
-* @param options Optional formatting options to customize the output.
-* @returns A formatted string representation of the message.
-*/
 function formatMessage(msg, options = {}) {
 	const colorConfig = options.colors ?? false;
 	const useColors = typeof colorConfig === "boolean" ? colorConfig : true;
@@ -252,118 +244,130 @@ function formatMessage(msg, options = {}) {
 	const resetSequence = `\x1b[0m${resetSuffix}`;
 	function* stream() {
 		const wordPattern = /\s*\S+\s*/g;
-		for (const term of msg) if (term.type === "text") if (term.text.includes("\n\n")) {
-			const paragraphs = term.text.split(/\n\n+/);
-			for (let paragraphIndex = 0; paragraphIndex < paragraphs.length; paragraphIndex++) {
-				if (paragraphIndex > 0) yield {
-					text: "\n\n",
-					width: -1
-				};
-				const paragraph = paragraphs[paragraphIndex].replace(/\n/g, " ");
-				wordPattern.lastIndex = 0;
-				while (true) {
-					const match = wordPattern.exec(paragraph);
-					if (match == null) break;
-					yield {
-						text: match[0],
-						width: match[0].length
+		let prevWasLineBreak = false;
+		for (const term of msg) {
+			const isAfterLineBreak = prevWasLineBreak;
+			prevWasLineBreak = false;
+			if (term.type === "text") {
+				const rawText = isAfterLineBreak ? term.text.replace(/^\n(?!\n)/, "") : term.text;
+				if (rawText.includes("\n\n")) {
+					const paragraphs = rawText.split(/\n\n+/);
+					for (let paragraphIndex = 0; paragraphIndex < paragraphs.length; paragraphIndex++) {
+						if (paragraphIndex > 0) {
+							const breakText = isAfterLineBreak && paragraphIndex === 1 ? "\n" : "\n\n";
+							yield {
+								text: breakText,
+								width: -1
+							};
+						}
+						const paragraph = paragraphs[paragraphIndex].replace(/\n/g, " ");
+						wordPattern.lastIndex = 0;
+						while (true) {
+							const match = wordPattern.exec(paragraph);
+							if (match == null) break;
+							yield {
+								text: match[0],
+								width: match[0].length
+							};
+						}
+					}
+				} else {
+					const normalizedText = rawText.replace(/\n/g, " ");
+					if (normalizedText.trim() === "" && normalizedText.length > 0) yield {
+						text: " ",
+						width: 1
 					};
+					else {
+						wordPattern.lastIndex = 0;
+						while (true) {
+							const match = wordPattern.exec(normalizedText);
+							if (match == null) break;
+							yield {
+								text: match[0],
+								width: match[0].length
+							};
+						}
+					}
 				}
-			}
-		} else {
-			const normalizedText = term.text.replace(/\n/g, " ");
-			if (normalizedText.trim() === "" && normalizedText.length > 0) yield {
-				text: " ",
-				width: 1
-			};
-			else {
-				wordPattern.lastIndex = 0;
-				while (true) {
-					const match = wordPattern.exec(normalizedText);
-					if (match == null) break;
+			} else if (term.type === "optionName") {
+				const name = useQuotes ? `\`${term.optionName}\`` : term.optionName;
+				yield {
+					text: useColors ? `\x1b[3m${name}${resetSequence}` : name,
+					width: name.length
+				};
+			} else if (term.type === "optionNames") {
+				const names = term.optionNames.map((name) => useQuotes ? `\`${name}\`` : name);
+				let i = 0;
+				for (const name of names) {
+					if (i > 0) yield {
+						text: "/",
+						width: 1
+					};
 					yield {
-						text: match[0],
-						width: match[0].length
+						text: useColors ? `\x1b[3m${name}${resetSequence}` : name,
+						width: name.length
 					};
+					i++;
 				}
-			}
-		}
-		else if (term.type === "optionName") {
-			const name = useQuotes ? `\`${term.optionName}\`` : term.optionName;
-			yield {
-				text: useColors ? `\x1b[3m${name}${resetSequence}` : name,
-				width: name.length
-			};
-		} else if (term.type === "optionNames") {
-			const names = term.optionNames.map((name) => useQuotes ? `\`${name}\`` : name);
-			let i = 0;
-			for (const name of names) {
+			} else if (term.type === "metavar") {
+				const metavar$1 = useQuotes ? `\`${term.metavar}\`` : term.metavar;
+				yield {
+					text: useColors ? `\x1b[1m${metavar$1}${resetSequence}` : metavar$1,
+					width: metavar$1.length
+				};
+			} else if (term.type === "value") {
+				const value$1 = useQuotes ? `${JSON.stringify(term.value)}` : term.value;
+				yield {
+					text: useColors ? `\x1b[32m${value$1}${resetSequence}` : value$1,
+					width: value$1.length
+				};
+			} else if (term.type === "values") for (let i = 0; i < term.values.length; i++) {
 				if (i > 0) yield {
-					text: "/",
+					text: " ",
 					width: 1
 				};
+				const value$1 = useQuotes ? JSON.stringify(term.values[i]) : term.values[i];
 				yield {
-					text: useColors ? `\x1b[3m${name}${resetSequence}` : name,
-					width: name.length
+					text: useColors ? i <= 0 ? `\x1b[32m${value$1}` : i + 1 >= term.values.length ? `${value$1}${resetSequence}` : value$1 : value$1,
+					width: value$1.length
 				};
-				i++;
 			}
-		} else if (term.type === "metavar") {
-			const metavar$1 = useQuotes ? `\`${term.metavar}\`` : term.metavar;
-			yield {
-				text: useColors ? `\x1b[1m${metavar$1}${resetSequence}` : metavar$1,
-				width: metavar$1.length
-			};
-		} else if (term.type === "value") {
-			const value$1 = useQuotes ? `${JSON.stringify(term.value)}` : term.value;
-			yield {
-				text: useColors ? `\x1b[32m${value$1}${resetSequence}` : value$1,
-				width: value$1.length
-			};
-		} else if (term.type === "values") for (let i = 0; i < term.values.length; i++) {
-			if (i > 0) yield {
-				text: " ",
-				width: 1
-			};
-			const value$1 = useQuotes ? JSON.stringify(term.values[i]) : term.values[i];
-			yield {
-				text: useColors ? i <= 0 ? `\x1b[32m${value$1}` : i + 1 >= term.values.length ? `${value$1}${resetSequence}` : value$1 : value$1,
-				width: value$1.length
-			};
-		}
-		else if (term.type === "envVar") {
-			const envVar$1 = useQuotes ? `\`${term.envVar}\`` : term.envVar;
-			yield {
-				text: useColors ? `\x1b[1;4m${envVar$1}${resetSequence}` : envVar$1,
-				width: envVar$1.length
-			};
-		} else if (term.type === "commandLine") {
-			const cmd = useQuotes ? `\`${term.commandLine}\`` : term.commandLine;
-			yield {
-				text: useColors ? `\x1b[36m${cmd}${resetSequence}` : cmd,
-				width: cmd.length
-			};
-		} else if (term.type === "lineBreak") yield {
-			text: "\n",
-			width: -1
-		};
-		else if (term.type === "url") {
-			const urlString = term.url.href;
-			const displayText = useQuotes ? `<${urlString}>` : urlString;
-			if (useColors) {
-				const hyperlink = `\x1b]8;;${urlString}\x1b\\${displayText}\x1b]8;;\x1b\\${resetSuffix}`;
+			else if (term.type === "envVar") {
+				const envVar$1 = useQuotes ? `\`${term.envVar}\`` : term.envVar;
+				yield {
+					text: useColors ? `\x1b[1;4m${envVar$1}${resetSequence}` : envVar$1,
+					width: envVar$1.length
+				};
+			} else if (term.type === "commandLine") {
+				const cmd = useQuotes ? `\`${term.commandLine}\`` : term.commandLine;
 				yield {
-					text: hyperlink,
+					text: useColors ? `\x1b[36m${cmd}${resetSequence}` : cmd,
+					width: cmd.length
+				};
+			} else if (term.type === "lineBreak") {
+				yield {
+					text: "\n",
+					width: -1
+				};
+				prevWasLineBreak = true;
+			} else if (term.type === "url") {
+				const urlString = term.url.href;
+				const displayText = useQuotes ? `<${urlString}>` : urlString;
+				if (useColors) {
+					const hyperlink = `\x1b]8;;${urlString}\x1b\\${displayText}\x1b]8;;\x1b\\${resetSuffix}`;
+					yield {
+						text: hyperlink,
+						width: displayText.length
+					};
+				} else yield {
+					text: displayText,
 					width: displayText.length
 				};
-			} else yield {
-				text: displayText,
-				width: displayText.length
-			};
-		} else throw new TypeError(`Invalid MessageTerm type: ${term["type"]}.`);
+			} else throw new TypeError(`Invalid MessageTerm type: ${term["type"]}.`);
+		}
 	}
 	let output = "";
-	let totalWidth = 0;
+	let totalWidth = options.startWidth ?? 0;
 	for (const { text: text$1, width } of stream()) {
 		if (width === -1) {
 			output += text$1;

package/dist/modifiers.cjs

@@ -12,7 +12,7 @@ const require_mode_dispatch = require('./mode-dispatch.cjs');
 * @internal
 */
 function parseOptionalStyleSync(context, parser) {
-	const innerState = typeof context.state === "undefined" ? parser.initialState : context.state[0];
+	const innerState = Array.isArray(context.state) ? context.state[0] : parser.initialState;
 	const result = parser.parse({
 		...context,
 		state: innerState
@@ -24,7 +24,7 @@ function parseOptionalStyleSync(context, parser) {
 * @internal
 */
 async function parseOptionalStyleAsync(context, parser) {
-	const innerState = typeof context.state === "undefined" ? parser.initialState : context.state[0];
+	const innerState = Array.isArray(context.state) ? context.state[0] : parser.initialState;
 	const result = await parser.parse({
 		...context,
 		state: innerState
@@ -76,14 +76,14 @@ function processOptionalStyleResult(result, innerState, context) {
 function optional(parser) {
 	const syncParser = parser;
 	function* suggestSync(context, prefix) {
-		const innerState = typeof context.state === "undefined" ? syncParser.initialState : context.state[0];
+		const innerState = Array.isArray(context.state) ? context.state[0] : syncParser.initialState;
 		yield* syncParser.suggest({
 			...context,
 			state: innerState
 		}, prefix);
 	}
 	async function* suggestAsync(context, prefix) {
-		const innerState = typeof context.state === "undefined" ? syncParser.initialState : context.state[0];
+		const innerState = Array.isArray(context.state) ? context.state[0] : syncParser.initialState;
 		const suggestions = parser.suggest({
 			...context,
 			state: innerState
@@ -110,7 +110,7 @@ function optional(parser) {
 			return require_mode_dispatch.dispatchByMode(parser.$mode, () => parseOptionalStyleSync(context, syncParser), () => parseOptionalStyleAsync(context, parser));
 		},
 		complete(state) {
-			if (typeof state === "undefined") {
+			if (!Array.isArray(state)) {
 				if (innerHasWrappedDependency && wrappedPendingState) return require_mode_dispatch.dispatchByMode(parser.$mode, () => syncParser.complete([wrappedPendingState]), () => parser.complete([wrappedPendingState]));
 				return {
 					success: true,
@@ -175,14 +175,14 @@ var WithDefaultError = class extends Error {
 function withDefault(parser, defaultValue, options) {
 	const syncParser = parser;
 	function* suggestSync(context, prefix) {
-		const innerState = typeof context.state === "undefined" ? syncParser.initialState : context.state[0];
+		const innerState = Array.isArray(context.state) ? context.state[0] : syncParser.initialState;
 		yield* syncParser.suggest({
 			...context,
 			state: innerState
 		}, prefix);
 	}
 	async function* suggestAsync(context, prefix) {
-		const innerState = typeof context.state === "undefined" ? syncParser.initialState : context.state[0];
+		const innerState = Array.isArray(context.state) ? context.state[0] : syncParser.initialState;
 		const suggestions = parser.suggest({
 			...context,
 			state: innerState
@@ -206,7 +206,7 @@ function withDefault(parser, defaultValue, options) {
 			return require_mode_dispatch.dispatchByMode(parser.$mode, () => parseOptionalStyleSync(context, syncParser), () => parseOptionalStyleAsync(context, parser));
 		},
 		complete(state) {
-			if (typeof state === "undefined") {
+			if (!Array.isArray(state)) {
 				if (require_dependency.transformsDependencyValue(parser)) {
 					const innerResult = require_mode_dispatch.dispatchByMode(parser.$mode, () => syncParser.complete(void 0), () => parser.complete(void 0));
 					const handleInnerResult = (res) => {

package/dist/modifiers.js

@@ -12,7 +12,7 @@ import { dispatchByMode, dispatchIterableByMode } from "./mode-dispatch.js";
 * @internal
 */
 function parseOptionalStyleSync(context, parser) {
-	const innerState = typeof context.state === "undefined" ? parser.initialState : context.state[0];
+	const innerState = Array.isArray(context.state) ? context.state[0] : parser.initialState;
 	const result = parser.parse({
 		...context,
 		state: innerState
@@ -24,7 +24,7 @@ function parseOptionalStyleSync(context, parser) {
 * @internal
 */
 async function parseOptionalStyleAsync(context, parser) {
-	const innerState = typeof context.state === "undefined" ? parser.initialState : context.state[0];
+	const innerState = Array.isArray(context.state) ? context.state[0] : parser.initialState;
 	const result = await parser.parse({
 		...context,
 		state: innerState
@@ -76,14 +76,14 @@ function processOptionalStyleResult(result, innerState, context) {
 function optional(parser) {
 	const syncParser = parser;
 	function* suggestSync(context, prefix) {
-		const innerState = typeof context.state === "undefined" ? syncParser.initialState : context.state[0];
+		const innerState = Array.isArray(context.state) ? context.state[0] : syncParser.initialState;
 		yield* syncParser.suggest({
 			...context,
 			state: innerState
 		}, prefix);
 	}
 	async function* suggestAsync(context, prefix) {
-		const innerState = typeof context.state === "undefined" ? syncParser.initialState : context.state[0];
+		const innerState = Array.isArray(context.state) ? context.state[0] : syncParser.initialState;
 		const suggestions = parser.suggest({
 			...context,
 			state: innerState
@@ -110,7 +110,7 @@ function optional(parser) {
 			return dispatchByMode(parser.$mode, () => parseOptionalStyleSync(context, syncParser), () => parseOptionalStyleAsync(context, parser));
 		},
 		complete(state) {
-			if (typeof state === "undefined") {
+			if (!Array.isArray(state)) {
 				if (innerHasWrappedDependency && wrappedPendingState) return dispatchByMode(parser.$mode, () => syncParser.complete([wrappedPendingState]), () => parser.complete([wrappedPendingState]));
 				return {
 					success: true,
@@ -175,14 +175,14 @@ var WithDefaultError = class extends Error {
 function withDefault(parser, defaultValue, options) {
 	const syncParser = parser;
 	function* suggestSync(context, prefix) {
-		const innerState = typeof context.state === "undefined" ? syncParser.initialState : context.state[0];
+		const innerState = Array.isArray(context.state) ? context.state[0] : syncParser.initialState;
 		yield* syncParser.suggest({
 			...context,
 			state: innerState
 		}, prefix);
 	}
 	async function* suggestAsync(context, prefix) {
-		const innerState = typeof context.state === "undefined" ? syncParser.initialState : context.state[0];
+		const innerState = Array.isArray(context.state) ? context.state[0] : syncParser.initialState;
 		const suggestions = parser.suggest({
 			...context,
 			state: innerState
@@ -206,7 +206,7 @@ function withDefault(parser, defaultValue, options) {
 			return dispatchByMode(parser.$mode, () => parseOptionalStyleSync(context, syncParser), () => parseOptionalStyleAsync(context, parser));
 		},
 		complete(state) {
-			if (typeof state === "undefined") {
+			if (!Array.isArray(state)) {
 				if (transformsDependencyValue(parser)) {
 					const innerResult = dispatchByMode(parser.$mode, () => syncParser.complete(void 0), () => parser.complete(void 0));
 					const handleInnerResult = (res) => {

package/dist/parser.cjs

@@ -350,11 +350,11 @@ function getDocPageSyncImpl(parser, args, options) {
 		state: initialState,
 		usage: parser.usage
 	};
-	do {
+	while (context.buffer.length > 0) {
 		const result = parser.parse(context);
 		if (!result.success) break;
 		context = result.next;
-	} while (context.buffer.length > 0);
+	}
 	return buildDocPage(parser, context, args);
 }
 /**
@@ -372,11 +372,11 @@ async function getDocPageAsyncImpl(parser, args, options) {
 		state: initialState,
 		usage: parser.usage
 	};
-	do {
+	while (context.buffer.length > 0) {
 		const result = await parser.parse(context);
 		if (!result.success) break;
 		context = result.next;
-	} while (context.buffer.length > 0);
+	}
 	return buildDocPage(parser, context, args);
 }
 /**

package/dist/parser.js

@@ -350,11 +350,11 @@ function getDocPageSyncImpl(parser, args, options) {
 		state: initialState,
 		usage: parser.usage
 	};
-	do {
+	while (context.buffer.length > 0) {
 		const result = parser.parse(context);
 		if (!result.success) break;
 		context = result.next;
-	} while (context.buffer.length > 0);
+	}
 	return buildDocPage(parser, context, args);
 }
 /**
@@ -372,11 +372,11 @@ async function getDocPageAsyncImpl(parser, args, options) {
 		state: initialState,
 		usage: parser.usage
 	};
-	do {
+	while (context.buffer.length > 0) {
 		const result = await parser.parse(context);
 		if (!result.success) break;
 		context = result.next;
-	} while (context.buffer.length > 0);
+	}
 	return buildDocPage(parser, context, args);
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.407+21363ee4",
+  "version": "1.0.0-dev.427+497e26fe",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",