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

package/dist/doc.cjs

@@ -252,7 +252,7 @@ function formatDocPage(programName, page, options = {}) {
 		return rendered;
 	};
 	const usageLabel = page.usage != null && options.showUsage !== false ? label("Usage:", "usage") + " " : "";
-	const usageLabelWidth = require_displaywidth.getDisplayWidth(usageLabel);
+	const usageLabelWidth = require_displaywidth.getDisplayWidth(usageLabel.split("\n").at(-1) ?? "");
 	const defaultStyle = require_terminal_internal.styleCode(options.theme?.annotationStyles?.default ?? { dim: true });
 	const choicesStyle = require_terminal_internal.styleCode(options.theme?.annotationStyles?.choices ?? { dim: true });
 	require_validate.validateProgramName(programName);
@@ -323,9 +323,9 @@ function formatDocPage(programName, page, options = {}) {
 		}, options.theme))].map((token) => token.width)) : 0;
 		const usageMin = page.usage != null && showUsage ? usageLabelWidth + Math.max(programNameWidth, Math.min(maxVisibleAtomicWidth(page.usage, options.theme), programNameWidth + usageLabelWidth)) : 1;
 		let sectionMin = 1;
-		if (hasContent(page.examples)) sectionMin = Math.max(sectionMin, require_displaywidth.getDisplayWidth(label("Examples:", "examples")));
-		if (hasContent(page.author)) sectionMin = Math.max(sectionMin, require_displaywidth.getDisplayWidth(label("Author:", "author")));
-		if (hasContent(page.bugs)) sectionMin = Math.max(sectionMin, require_displaywidth.getDisplayWidth(label("Bugs:", "bugs")));
+		if (hasContent(page.examples)) sectionMin = Math.max(sectionMin, ...label("Examples:", "examples").split("\n").map((line) => require_displaywidth.getDisplayWidth(line)));
+		if (hasContent(page.author)) sectionMin = Math.max(sectionMin, ...label("Author:", "author").split("\n").map((line) => require_displaywidth.getDisplayWidth(line)));
+		if (hasContent(page.bugs)) sectionMin = Math.max(sectionMin, ...label("Bugs:", "bugs").split("\n").map((line) => require_displaywidth.getDisplayWidth(line)));
 		const minWidth = Math.max(entryMin, usageMin, sectionMin);
 		if (options.maxWidth < minWidth) throw new RangeError(`maxWidth must be at least ${minWidth}, got ${options.maxWidth}.`);
 		if (needsDescColumn && minDescWidth > 1) {

package/dist/doc.js

@@ -252,7 +252,7 @@ function formatDocPage(programName, page, options = {}) {
 		return rendered;
 	};
 	const usageLabel = page.usage != null && options.showUsage !== false ? label("Usage:", "usage") + " " : "";
-	const usageLabelWidth = getDisplayWidth(usageLabel);
+	const usageLabelWidth = getDisplayWidth(usageLabel.split("\n").at(-1) ?? "");
 	const defaultStyle = styleCode(options.theme?.annotationStyles?.default ?? { dim: true });
 	const choicesStyle = styleCode(options.theme?.annotationStyles?.choices ?? { dim: true });
 	validateProgramName(programName);
@@ -323,9 +323,9 @@ function formatDocPage(programName, page, options = {}) {
 		}, options.theme))].map((token) => token.width)) : 0;
 		const usageMin = page.usage != null && showUsage ? usageLabelWidth + Math.max(programNameWidth, Math.min(maxVisibleAtomicWidth(page.usage, options.theme), programNameWidth + usageLabelWidth)) : 1;
 		let sectionMin = 1;
-		if (hasContent(page.examples)) sectionMin = Math.max(sectionMin, getDisplayWidth(label("Examples:", "examples")));
-		if (hasContent(page.author)) sectionMin = Math.max(sectionMin, getDisplayWidth(label("Author:", "author")));
-		if (hasContent(page.bugs)) sectionMin = Math.max(sectionMin, getDisplayWidth(label("Bugs:", "bugs")));
+		if (hasContent(page.examples)) sectionMin = Math.max(sectionMin, ...label("Examples:", "examples").split("\n").map((line) => getDisplayWidth(line)));
+		if (hasContent(page.author)) sectionMin = Math.max(sectionMin, ...label("Author:", "author").split("\n").map((line) => getDisplayWidth(line)));
+		if (hasContent(page.bugs)) sectionMin = Math.max(sectionMin, ...label("Bugs:", "bugs").split("\n").map((line) => getDisplayWidth(line)));
 		const minWidth = Math.max(entryMin, usageMin, sectionMin);
 		if (options.maxWidth < minWidth) throw new RangeError(`maxWidth must be at least ${minWidth}, got ${options.maxWidth}.`);
 		if (needsDescColumn && minDescWidth > 1) {

package/dist/facade.cjs

@@ -896,7 +896,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		label: "Usage:",
 		kind: "usageSummary"
 	}, theme, colors) + " ";
-	const usageLabelWidth = () => require_displaywidth.getDisplayWidth(usageLabel());
+	const usageLabelWidth = () => require_displaywidth.getDisplayWidth(usageLabel().split("\n").at(-1) ?? "");
 	const norm = (c) => c === true ? {} : c;
 	const helpCommandConfig = norm(options.help?.command);
 	const helpOptionConfig = norm(options.help?.option);
@@ -1238,6 +1238,8 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 * @param programName The name of the program for help messages.
 * @param args The command-line arguments to parse.
 * @param options Configuration options for customizing behavior.
+* @throws {RangeError} If rendering help or errors encounters an invalid theme
+* color, even when colors are disabled.
 * @returns The parsed result if successful.
 * @throws {TypeError} If an async parser is passed at runtime.  Use
 * {@link runParser} or {@link runParserAsync} for async parsers.
@@ -1261,6 +1263,8 @@ function runParserSync(parser, programName, args, options) {
 * @param programName The name of the program for help messages.
 * @param args The command-line arguments to parse.
 * @param options Configuration options for customizing behavior.
+* @throws {RangeError} If rendering help or errors encounters an invalid theme
+* color, even when colors are disabled.
 * @returns A Promise of the parsed result if successful.
 * @since 0.9.0
 */
@@ -1610,6 +1614,8 @@ async function runWithBody(parser, programName, contexts, args, options) {
 * @param programName Name of the program for help/error output.
 * @param contexts Source contexts to use (priority: earlier overrides later).
 * @param options Run options including args, help, version, etc.
+* @throws {RangeError} If rendering help or errors encounters an invalid theme
+* color, even when colors are disabled.
 * @returns Promise that resolves to the parsed result.
 * @throws {TypeError} If two or more contexts share the same
 * {@link SourceContext.id}.
@@ -1708,6 +1714,8 @@ function runWithSyncBody(parser, programName, contexts, args, options) {
 * @param programName Name of the program for help/error output.
 * @param contexts Source contexts to use (priority: earlier overrides later).
 * @param options Run options including args, help, version, etc.
+* @throws {RangeError} If rendering help or errors encounters an invalid theme
+* color, even when colors are disabled.
 * @returns The parsed result.
 * @throws {TypeError} If an async parser is passed at runtime.  Use
 * {@link runWith} or {@link runWithAsync} for async parsers.
@@ -1757,6 +1765,8 @@ function runWithSync(parser, programName, contexts, options) {
 * @param programName Name of the program for help/error output.
 * @param contexts Source contexts to use (priority: earlier overrides later).
 * @param options Run options including args, help, version, etc.
+* @throws {RangeError} If rendering help or errors encounters an invalid theme
+* color, even when colors are disabled.
 * @returns Promise that resolves to the parsed result.
 * @throws {TypeError} If two or more contexts share the same
 * {@link SourceContext.id}.

package/dist/facade.d.cts

@@ -353,6 +353,8 @@ interface RunOptions<THelp, TError> {
  * @param args Command-line arguments to parse (typically from
  *             `process.argv.slice(2)` on Node.js or `Deno.args` on Deno).
  * @param options Configuration options for output formatting and callbacks.
+ * @throws {RangeError} If rendering help or errors encounters an invalid theme
+ * color, even when colors are disabled.
  * @returns The parsed result value, or the return value of `onHelp`/`onError`
  *          callbacks.
  * @throws {TypeError} If `programName` (or `program.metadata.name`) is not
@@ -385,6 +387,8 @@ declare function runParser<TParser extends Parser<Mode, unknown, unknown>, THelp
  * @param programName The name of the program for help messages.
  * @param args The command-line arguments to parse.
  * @param options Configuration options for customizing behavior.
+ * @throws {RangeError} If rendering help or errors encounters an invalid theme
+ * color, even when colors are disabled.
  * @returns The parsed result if successful.
  * @throws {TypeError} If an async parser is passed at runtime.  Use
  * {@link runParser} or {@link runParserAsync} for async parsers.
@@ -405,6 +409,8 @@ declare function runParserSync<TParser extends Parser<"sync", unknown, unknown>,
  * @param programName The name of the program for help messages.
  * @param args The command-line arguments to parse.
  * @param options Configuration options for customizing behavior.
+ * @throws {RangeError} If rendering help or errors encounters an invalid theme
+ * color, even when colors are disabled.
  * @returns A Promise of the parsed result if successful.
  * @since 0.9.0
  */
@@ -519,6 +525,8 @@ type ContextOptionsParam<TContexts extends readonly SourceContext<unknown>[], TV
  * @param programName Name of the program for help/error output.
  * @param contexts Source contexts to use (priority: earlier overrides later).
  * @param options Run options including args, help, version, etc.
+ * @throws {RangeError} If rendering help or errors encounters an invalid theme
+ * color, even when colors are disabled.
  * @returns Promise that resolves to the parsed result.
  * @throws {TypeError} If two or more contexts share the same
  * {@link SourceContext.id}.
@@ -568,6 +576,8 @@ declare function runWith<TParser extends Parser<Mode, unknown, unknown>, TContex
  * @param programName Name of the program for help/error output.
  * @param contexts Source contexts to use (priority: earlier overrides later).
  * @param options Run options including args, help, version, etc.
+ * @throws {RangeError} If rendering help or errors encounters an invalid theme
+ * color, even when colors are disabled.
  * @returns The parsed result.
  * @throws {TypeError} If an async parser is passed at runtime.  Use
  * {@link runWith} or {@link runWithAsync} for async parsers.
@@ -596,6 +606,8 @@ declare function runWithSync<TParser extends Parser<"sync", unknown, unknown>, T
  * @param programName Name of the program for help/error output.
  * @param contexts Source contexts to use (priority: earlier overrides later).
  * @param options Run options including args, help, version, etc.
+ * @throws {RangeError} If rendering help or errors encounters an invalid theme
+ * color, even when colors are disabled.
  * @returns Promise that resolves to the parsed result.
  * @throws {TypeError} If two or more contexts share the same
  * {@link SourceContext.id}.

package/dist/facade.d.ts

@@ -353,6 +353,8 @@ interface RunOptions<THelp, TError> {
  * @param args Command-line arguments to parse (typically from
  *             `process.argv.slice(2)` on Node.js or `Deno.args` on Deno).
  * @param options Configuration options for output formatting and callbacks.
+ * @throws {RangeError} If rendering help or errors encounters an invalid theme
+ * color, even when colors are disabled.
  * @returns The parsed result value, or the return value of `onHelp`/`onError`
  *          callbacks.
  * @throws {TypeError} If `programName` (or `program.metadata.name`) is not
@@ -385,6 +387,8 @@ declare function runParser<TParser extends Parser<Mode, unknown, unknown>, THelp
  * @param programName The name of the program for help messages.
  * @param args The command-line arguments to parse.
  * @param options Configuration options for customizing behavior.
+ * @throws {RangeError} If rendering help or errors encounters an invalid theme
+ * color, even when colors are disabled.
  * @returns The parsed result if successful.
  * @throws {TypeError} If an async parser is passed at runtime.  Use
  * {@link runParser} or {@link runParserAsync} for async parsers.
@@ -405,6 +409,8 @@ declare function runParserSync<TParser extends Parser<"sync", unknown, unknown>,
  * @param programName The name of the program for help messages.
  * @param args The command-line arguments to parse.
  * @param options Configuration options for customizing behavior.
+ * @throws {RangeError} If rendering help or errors encounters an invalid theme
+ * color, even when colors are disabled.
  * @returns A Promise of the parsed result if successful.
  * @since 0.9.0
  */
@@ -519,6 +525,8 @@ type ContextOptionsParam<TContexts extends readonly SourceContext<unknown>[], TV
  * @param programName Name of the program for help/error output.
  * @param contexts Source contexts to use (priority: earlier overrides later).
  * @param options Run options including args, help, version, etc.
+ * @throws {RangeError} If rendering help or errors encounters an invalid theme
+ * color, even when colors are disabled.
  * @returns Promise that resolves to the parsed result.
  * @throws {TypeError} If two or more contexts share the same
  * {@link SourceContext.id}.
@@ -568,6 +576,8 @@ declare function runWith<TParser extends Parser<Mode, unknown, unknown>, TContex
  * @param programName Name of the program for help/error output.
  * @param contexts Source contexts to use (priority: earlier overrides later).
  * @param options Run options including args, help, version, etc.
+ * @throws {RangeError} If rendering help or errors encounters an invalid theme
+ * color, even when colors are disabled.
  * @returns The parsed result.
  * @throws {TypeError} If an async parser is passed at runtime.  Use
  * {@link runWith} or {@link runWithAsync} for async parsers.
@@ -596,6 +606,8 @@ declare function runWithSync<TParser extends Parser<"sync", unknown, unknown>, T
  * @param programName Name of the program for help/error output.
  * @param contexts Source contexts to use (priority: earlier overrides later).
  * @param options Run options including args, help, version, etc.
+ * @throws {RangeError} If rendering help or errors encounters an invalid theme
+ * color, even when colors are disabled.
  * @returns Promise that resolves to the parsed result.
  * @throws {TypeError} If two or more contexts share the same
  * {@link SourceContext.id}.

package/dist/facade.js

@@ -896,7 +896,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		label: "Usage:",
 		kind: "usageSummary"
 	}, theme, colors) + " ";
-	const usageLabelWidth = () => getDisplayWidth(usageLabel());
+	const usageLabelWidth = () => getDisplayWidth(usageLabel().split("\n").at(-1) ?? "");
 	const norm = (c) => c === true ? {} : c;
 	const helpCommandConfig = norm(options.help?.command);
 	const helpOptionConfig = norm(options.help?.option);
@@ -1238,6 +1238,8 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 * @param programName The name of the program for help messages.
 * @param args The command-line arguments to parse.
 * @param options Configuration options for customizing behavior.
+* @throws {RangeError} If rendering help or errors encounters an invalid theme
+* color, even when colors are disabled.
 * @returns The parsed result if successful.
 * @throws {TypeError} If an async parser is passed at runtime.  Use
 * {@link runParser} or {@link runParserAsync} for async parsers.
@@ -1261,6 +1263,8 @@ function runParserSync(parser, programName, args, options) {
 * @param programName The name of the program for help messages.
 * @param args The command-line arguments to parse.
 * @param options Configuration options for customizing behavior.
+* @throws {RangeError} If rendering help or errors encounters an invalid theme
+* color, even when colors are disabled.
 * @returns A Promise of the parsed result if successful.
 * @since 0.9.0
 */
@@ -1610,6 +1614,8 @@ async function runWithBody(parser, programName, contexts, args, options) {
 * @param programName Name of the program for help/error output.
 * @param contexts Source contexts to use (priority: earlier overrides later).
 * @param options Run options including args, help, version, etc.
+* @throws {RangeError} If rendering help or errors encounters an invalid theme
+* color, even when colors are disabled.
 * @returns Promise that resolves to the parsed result.
 * @throws {TypeError} If two or more contexts share the same
 * {@link SourceContext.id}.
@@ -1708,6 +1714,8 @@ function runWithSyncBody(parser, programName, contexts, args, options) {
 * @param programName Name of the program for help/error output.
 * @param contexts Source contexts to use (priority: earlier overrides later).
 * @param options Run options including args, help, version, etc.
+* @throws {RangeError} If rendering help or errors encounters an invalid theme
+* color, even when colors are disabled.
 * @returns The parsed result.
 * @throws {TypeError} If an async parser is passed at runtime.  Use
 * {@link runWith} or {@link runWithAsync} for async parsers.
@@ -1757,6 +1765,8 @@ function runWithSync(parser, programName, contexts, options) {
 * @param programName Name of the program for help/error output.
 * @param contexts Source contexts to use (priority: earlier overrides later).
 * @param options Run options including args, help, version, etc.
+* @throws {RangeError} If rendering help or errors encounters an invalid theme
+* color, even when colors are disabled.
 * @returns Promise that resolves to the parsed result.
 * @throws {TypeError} If two or more contexts share the same
 * {@link SourceContext.id}.

package/dist/message.cjs

@@ -301,9 +301,9 @@ function formatMessage(msg, options = {}) {
 /**
 * Creates a message formatter using a snapshot of the supplied theme.
 * @param theme Semantic leaf formatters and annotation styles.
-* @returns A reusable message formatter.
-* @throws {TypeError} If initialWidth is not a finite integer.
-* @throws {RangeError} If initialWidth is negative or a color is invalid.
+* @returns A reusable message formatter. Invoking it throws `TypeError` if
+* `initialWidth` is not a finite integer, or `RangeError` if `initialWidth`
+* is negative or a theme color is invalid (even with colors disabled).
 * @since 1.3.0
 */
 function createMessageFormatter(theme) {

package/dist/message.d.cts

@@ -443,9 +443,9 @@ type MessageFormatter = (message: Message, options?: MessageFormatterOptions) =>
 /**
  * Creates a message formatter using a snapshot of the supplied theme.
  * @param theme Semantic leaf formatters and annotation styles.
- * @returns A reusable message formatter.
- * @throws {TypeError} If initialWidth is not a finite integer.
- * @throws {RangeError} If initialWidth is negative or a color is invalid.
+ * @returns A reusable message formatter. Invoking it throws `TypeError` if
+ * `initialWidth` is not a finite integer, or `RangeError` if `initialWidth`
+ * is negative or a theme color is invalid (even with colors disabled).
  * @since 1.3.0
  */
 declare function createMessageFormatter(theme: TerminalTheme): MessageFormatter;

package/dist/message.d.ts

@@ -443,9 +443,9 @@ type MessageFormatter = (message: Message, options?: MessageFormatterOptions) =>
 /**
  * Creates a message formatter using a snapshot of the supplied theme.
  * @param theme Semantic leaf formatters and annotation styles.
- * @returns A reusable message formatter.
- * @throws {TypeError} If initialWidth is not a finite integer.
- * @throws {RangeError} If initialWidth is negative or a color is invalid.
+ * @returns A reusable message formatter. Invoking it throws `TypeError` if
+ * `initialWidth` is not a finite integer, or `RangeError` if `initialWidth`
+ * is negative or a theme color is invalid (even with colors disabled).
  * @since 1.3.0
  */
 declare function createMessageFormatter(theme: TerminalTheme): MessageFormatter;

package/dist/message.js

@@ -301,9 +301,9 @@ function formatMessage(msg, options = {}) {
 /**
 * Creates a message formatter using a snapshot of the supplied theme.
 * @param theme Semantic leaf formatters and annotation styles.
-* @returns A reusable message formatter.
-* @throws {TypeError} If initialWidth is not a finite integer.
-* @throws {RangeError} If initialWidth is negative or a color is invalid.
+* @returns A reusable message formatter. Invoking it throws `TypeError` if
+* `initialWidth` is not a finite integer, or `RangeError` if `initialWidth`
+* is negative or a theme color is invalid (even with colors disabled).
 * @since 1.3.0
 */
 function createMessageFormatter(theme) {

package/package.json

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