@optique/core 1.3.0-dev.2534 → 1.3.0-dev.2538

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/doc.cjs CHANGED
@@ -193,7 +193,8 @@ function defaultSectionOrder(a, b) {
193
193
  * control characters, or if `maxWidth` is not a finite integer.
194
194
  * @throws {RangeError} If any entry needs a description column and `maxWidth`
195
195
  * is too small to fit the minimum layout (less than `termIndent + 4`), or if
196
- * `showChoices.maxItems` is less than `1`.
196
+ * `showChoices.maxItems` is less than `1`, or if a theme color is invalid
197
+ * (even when colors are disabled).
197
198
  *
198
199
  * @example
199
200
  * ```typescript
@@ -251,7 +252,7 @@ function formatDocPage(programName, page, options = {}) {
251
252
  return rendered;
252
253
  };
253
254
  const usageLabel = page.usage != null && options.showUsage !== false ? label("Usage:", "usage") + " " : "";
254
- const usageLabelWidth = require_displaywidth.getDisplayWidth(usageLabel);
255
+ const usageLabelWidth = require_displaywidth.getDisplayWidth(usageLabel.split("\n").at(-1) ?? "");
255
256
  const defaultStyle = require_terminal_internal.styleCode(options.theme?.annotationStyles?.default ?? { dim: true });
256
257
  const choicesStyle = require_terminal_internal.styleCode(options.theme?.annotationStyles?.choices ?? { dim: true });
257
258
  require_validate.validateProgramName(programName);
package/dist/doc.d.cts CHANGED
@@ -339,7 +339,8 @@ interface DocPageFormatOptions {
339
339
  * control characters, or if `maxWidth` is not a finite integer.
340
340
  * @throws {RangeError} If any entry needs a description column and `maxWidth`
341
341
  * is too small to fit the minimum layout (less than `termIndent + 4`), or if
342
- * `showChoices.maxItems` is less than `1`.
342
+ * `showChoices.maxItems` is less than `1`, or if a theme color is invalid
343
+ * (even when colors are disabled).
343
344
  *
344
345
  * @example
345
346
  * ```typescript
package/dist/doc.d.ts CHANGED
@@ -339,7 +339,8 @@ interface DocPageFormatOptions {
339
339
  * control characters, or if `maxWidth` is not a finite integer.
340
340
  * @throws {RangeError} If any entry needs a description column and `maxWidth`
341
341
  * is too small to fit the minimum layout (less than `termIndent + 4`), or if
342
- * `showChoices.maxItems` is less than `1`.
342
+ * `showChoices.maxItems` is less than `1`, or if a theme color is invalid
343
+ * (even when colors are disabled).
343
344
  *
344
345
  * @example
345
346
  * ```typescript
package/dist/doc.js CHANGED
@@ -193,7 +193,8 @@ function defaultSectionOrder(a, b) {
193
193
  * control characters, or if `maxWidth` is not a finite integer.
194
194
  * @throws {RangeError} If any entry needs a description column and `maxWidth`
195
195
  * is too small to fit the minimum layout (less than `termIndent + 4`), or if
196
- * `showChoices.maxItems` is less than `1`.
196
+ * `showChoices.maxItems` is less than `1`, or if a theme color is invalid
197
+ * (even when colors are disabled).
197
198
  *
198
199
  * @example
199
200
  * ```typescript
@@ -251,7 +252,7 @@ function formatDocPage(programName, page, options = {}) {
251
252
  return rendered;
252
253
  };
253
254
  const usageLabel = page.usage != null && options.showUsage !== false ? label("Usage:", "usage") + " " : "";
254
- const usageLabelWidth = getDisplayWidth(usageLabel);
255
+ const usageLabelWidth = getDisplayWidth(usageLabel.split("\n").at(-1) ?? "");
255
256
  const defaultStyle = styleCode(options.theme?.annotationStyles?.default ?? { dim: true });
256
257
  const choicesStyle = styleCode(options.theme?.annotationStyles?.choices ?? { dim: true });
257
258
  validateProgramName(programName);
package/dist/facade.cjs CHANGED
@@ -531,10 +531,12 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
531
531
  const callOnCompletion = (code) => onCompletion(code);
532
532
  if (!shellName) {
533
533
  const error = require_message.message`Missing shell name for completion.`;
534
- stderr(`${errorLabel()}${formatMessage(error, {
534
+ const prefix = errorLabel();
535
+ stderr(`${prefix}${formatMessage(error, {
535
536
  colors,
536
537
  quotes: !colors,
537
- maxWidth
538
+ maxWidth,
539
+ initialWidth: require_displaywidth.getDisplayWidth(prefix.split("\n").at(-1) ?? "")
538
540
  })}\n`);
539
541
  if (completionParser) {
540
542
  const displayName = isOptionMode ? completionOptionDisplayName ?? "--completion" : completionCommandDisplayName ?? "completion";
@@ -563,10 +565,12 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
563
565
  available.push(require_message.value(name));
564
566
  }
565
567
  const error = require_message.message`Unsupported shell ${shellName}. Available shells: ${available}.`;
566
- stderr(`${errorLabel()}${formatMessage(error, {
568
+ const prefix = errorLabel();
569
+ stderr(`${prefix}${formatMessage(error, {
567
570
  colors,
568
571
  quotes: !colors,
569
- maxWidth
572
+ maxWidth,
573
+ initialWidth: require_displaywidth.getDisplayWidth(prefix.split("\n").at(-1) ?? "")
570
574
  })}`);
571
575
  return require_mode_dispatch.dispatchByMode(parser.mode, () => {
572
576
  const result = callOnError(1, error);
@@ -892,7 +896,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
892
896
  label: "Usage:",
893
897
  kind: "usageSummary"
894
898
  }, theme, colors) + " ";
895
- const usageLabelWidth = () => require_displaywidth.getDisplayWidth(usageLabel());
899
+ const usageLabelWidth = () => require_displaywidth.getDisplayWidth(usageLabel().split("\n").at(-1) ?? "");
896
900
  const norm = (c) => c === true ? {} : c;
897
901
  const helpCommandConfig = norm(options.help?.command);
898
902
  const helpOptionConfig = norm(options.help?.option);
@@ -1053,12 +1057,14 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
1053
1057
  maxWidth: maxWidth == null ? void 0 : maxWidth - usageLabelWidth(),
1054
1058
  expandCommands: true
1055
1059
  }), usageLabelWidth())}`);
1060
+ const prefix = errorLabel();
1056
1061
  const errorMessage = formatMessage(validationError, {
1062
+ initialWidth: require_displaywidth.getDisplayWidth(prefix.split("\n").at(-1) ?? ""),
1057
1063
  maxWidth,
1058
1064
  colors,
1059
1065
  quotes: !colors
1060
1066
  });
1061
- stderr(`${errorLabel()}${errorMessage}`);
1067
+ stderr(`${prefix}${errorMessage}`);
1062
1068
  return onError(1, validationError);
1063
1069
  };
1064
1070
  const displayHelp = (doc) => {
@@ -1171,12 +1177,14 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
1171
1177
  maxWidth: maxWidth == null ? void 0 : maxWidth - usageLabelWidth(),
1172
1178
  expandCommands: true
1173
1179
  }), usageLabelWidth())}`);
1180
+ const prefix = errorLabel();
1174
1181
  const errorMessage = formatMessage(classified.error, {
1182
+ initialWidth: require_displaywidth.getDisplayWidth(prefix.split("\n").at(-1) ?? ""),
1175
1183
  maxWidth,
1176
1184
  colors,
1177
1185
  quotes: !colors
1178
1186
  });
1179
- stderr(`${errorLabel()}${errorMessage}`);
1187
+ stderr(`${prefix}${errorMessage}`);
1180
1188
  return onError(1, classified.error);
1181
1189
  };
1182
1190
  if (aboveError === "help") {
@@ -1230,6 +1238,8 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
1230
1238
  * @param programName The name of the program for help messages.
1231
1239
  * @param args The command-line arguments to parse.
1232
1240
  * @param options Configuration options for customizing behavior.
1241
+ * @throws {RangeError} If rendering help or errors encounters an invalid theme
1242
+ * color, even when colors are disabled.
1233
1243
  * @returns The parsed result if successful.
1234
1244
  * @throws {TypeError} If an async parser is passed at runtime. Use
1235
1245
  * {@link runParser} or {@link runParserAsync} for async parsers.
@@ -1253,6 +1263,8 @@ function runParserSync(parser, programName, args, options) {
1253
1263
  * @param programName The name of the program for help messages.
1254
1264
  * @param args The command-line arguments to parse.
1255
1265
  * @param options Configuration options for customizing behavior.
1266
+ * @throws {RangeError} If rendering help or errors encounters an invalid theme
1267
+ * color, even when colors are disabled.
1256
1268
  * @returns A Promise of the parsed result if successful.
1257
1269
  * @since 0.9.0
1258
1270
  */
@@ -1602,6 +1614,8 @@ async function runWithBody(parser, programName, contexts, args, options) {
1602
1614
  * @param programName Name of the program for help/error output.
1603
1615
  * @param contexts Source contexts to use (priority: earlier overrides later).
1604
1616
  * @param options Run options including args, help, version, etc.
1617
+ * @throws {RangeError} If rendering help or errors encounters an invalid theme
1618
+ * color, even when colors are disabled.
1605
1619
  * @returns Promise that resolves to the parsed result.
1606
1620
  * @throws {TypeError} If two or more contexts share the same
1607
1621
  * {@link SourceContext.id}.
@@ -1700,6 +1714,8 @@ function runWithSyncBody(parser, programName, contexts, args, options) {
1700
1714
  * @param programName Name of the program for help/error output.
1701
1715
  * @param contexts Source contexts to use (priority: earlier overrides later).
1702
1716
  * @param options Run options including args, help, version, etc.
1717
+ * @throws {RangeError} If rendering help or errors encounters an invalid theme
1718
+ * color, even when colors are disabled.
1703
1719
  * @returns The parsed result.
1704
1720
  * @throws {TypeError} If an async parser is passed at runtime. Use
1705
1721
  * {@link runWith} or {@link runWithAsync} for async parsers.
@@ -1749,6 +1765,8 @@ function runWithSync(parser, programName, contexts, options) {
1749
1765
  * @param programName Name of the program for help/error output.
1750
1766
  * @param contexts Source contexts to use (priority: earlier overrides later).
1751
1767
  * @param options Run options including args, help, version, etc.
1768
+ * @throws {RangeError} If rendering help or errors encounters an invalid theme
1769
+ * color, even when colors are disabled.
1752
1770
  * @returns Promise that resolves to the parsed result.
1753
1771
  * @throws {TypeError} If two or more contexts share the same
1754
1772
  * {@link SourceContext.id}.
package/dist/facade.d.cts CHANGED
@@ -353,6 +353,8 @@ interface RunOptions<THelp, TError> {
353
353
  * @param args Command-line arguments to parse (typically from
354
354
  * `process.argv.slice(2)` on Node.js or `Deno.args` on Deno).
355
355
  * @param options Configuration options for output formatting and callbacks.
356
+ * @throws {RangeError} If rendering help or errors encounters an invalid theme
357
+ * color, even when colors are disabled.
356
358
  * @returns The parsed result value, or the return value of `onHelp`/`onError`
357
359
  * callbacks.
358
360
  * @throws {TypeError} If `programName` (or `program.metadata.name`) is not
@@ -385,6 +387,8 @@ declare function runParser<TParser extends Parser<Mode, unknown, unknown>, THelp
385
387
  * @param programName The name of the program for help messages.
386
388
  * @param args The command-line arguments to parse.
387
389
  * @param options Configuration options for customizing behavior.
390
+ * @throws {RangeError} If rendering help or errors encounters an invalid theme
391
+ * color, even when colors are disabled.
388
392
  * @returns The parsed result if successful.
389
393
  * @throws {TypeError} If an async parser is passed at runtime. Use
390
394
  * {@link runParser} or {@link runParserAsync} for async parsers.
@@ -405,6 +409,8 @@ declare function runParserSync<TParser extends Parser<"sync", unknown, unknown>,
405
409
  * @param programName The name of the program for help messages.
406
410
  * @param args The command-line arguments to parse.
407
411
  * @param options Configuration options for customizing behavior.
412
+ * @throws {RangeError} If rendering help or errors encounters an invalid theme
413
+ * color, even when colors are disabled.
408
414
  * @returns A Promise of the parsed result if successful.
409
415
  * @since 0.9.0
410
416
  */
@@ -519,6 +525,8 @@ type ContextOptionsParam<TContexts extends readonly SourceContext<unknown>[], TV
519
525
  * @param programName Name of the program for help/error output.
520
526
  * @param contexts Source contexts to use (priority: earlier overrides later).
521
527
  * @param options Run options including args, help, version, etc.
528
+ * @throws {RangeError} If rendering help or errors encounters an invalid theme
529
+ * color, even when colors are disabled.
522
530
  * @returns Promise that resolves to the parsed result.
523
531
  * @throws {TypeError} If two or more contexts share the same
524
532
  * {@link SourceContext.id}.
@@ -568,6 +576,8 @@ declare function runWith<TParser extends Parser<Mode, unknown, unknown>, TContex
568
576
  * @param programName Name of the program for help/error output.
569
577
  * @param contexts Source contexts to use (priority: earlier overrides later).
570
578
  * @param options Run options including args, help, version, etc.
579
+ * @throws {RangeError} If rendering help or errors encounters an invalid theme
580
+ * color, even when colors are disabled.
571
581
  * @returns The parsed result.
572
582
  * @throws {TypeError} If an async parser is passed at runtime. Use
573
583
  * {@link runWith} or {@link runWithAsync} for async parsers.
@@ -596,6 +606,8 @@ declare function runWithSync<TParser extends Parser<"sync", unknown, unknown>, T
596
606
  * @param programName Name of the program for help/error output.
597
607
  * @param contexts Source contexts to use (priority: earlier overrides later).
598
608
  * @param options Run options including args, help, version, etc.
609
+ * @throws {RangeError} If rendering help or errors encounters an invalid theme
610
+ * color, even when colors are disabled.
599
611
  * @returns Promise that resolves to the parsed result.
600
612
  * @throws {TypeError} If two or more contexts share the same
601
613
  * {@link SourceContext.id}.
package/dist/facade.d.ts CHANGED
@@ -353,6 +353,8 @@ interface RunOptions<THelp, TError> {
353
353
  * @param args Command-line arguments to parse (typically from
354
354
  * `process.argv.slice(2)` on Node.js or `Deno.args` on Deno).
355
355
  * @param options Configuration options for output formatting and callbacks.
356
+ * @throws {RangeError} If rendering help or errors encounters an invalid theme
357
+ * color, even when colors are disabled.
356
358
  * @returns The parsed result value, or the return value of `onHelp`/`onError`
357
359
  * callbacks.
358
360
  * @throws {TypeError} If `programName` (or `program.metadata.name`) is not
@@ -385,6 +387,8 @@ declare function runParser<TParser extends Parser<Mode, unknown, unknown>, THelp
385
387
  * @param programName The name of the program for help messages.
386
388
  * @param args The command-line arguments to parse.
387
389
  * @param options Configuration options for customizing behavior.
390
+ * @throws {RangeError} If rendering help or errors encounters an invalid theme
391
+ * color, even when colors are disabled.
388
392
  * @returns The parsed result if successful.
389
393
  * @throws {TypeError} If an async parser is passed at runtime. Use
390
394
  * {@link runParser} or {@link runParserAsync} for async parsers.
@@ -405,6 +409,8 @@ declare function runParserSync<TParser extends Parser<"sync", unknown, unknown>,
405
409
  * @param programName The name of the program for help messages.
406
410
  * @param args The command-line arguments to parse.
407
411
  * @param options Configuration options for customizing behavior.
412
+ * @throws {RangeError} If rendering help or errors encounters an invalid theme
413
+ * color, even when colors are disabled.
408
414
  * @returns A Promise of the parsed result if successful.
409
415
  * @since 0.9.0
410
416
  */
@@ -519,6 +525,8 @@ type ContextOptionsParam<TContexts extends readonly SourceContext<unknown>[], TV
519
525
  * @param programName Name of the program for help/error output.
520
526
  * @param contexts Source contexts to use (priority: earlier overrides later).
521
527
  * @param options Run options including args, help, version, etc.
528
+ * @throws {RangeError} If rendering help or errors encounters an invalid theme
529
+ * color, even when colors are disabled.
522
530
  * @returns Promise that resolves to the parsed result.
523
531
  * @throws {TypeError} If two or more contexts share the same
524
532
  * {@link SourceContext.id}.
@@ -568,6 +576,8 @@ declare function runWith<TParser extends Parser<Mode, unknown, unknown>, TContex
568
576
  * @param programName Name of the program for help/error output.
569
577
  * @param contexts Source contexts to use (priority: earlier overrides later).
570
578
  * @param options Run options including args, help, version, etc.
579
+ * @throws {RangeError} If rendering help or errors encounters an invalid theme
580
+ * color, even when colors are disabled.
571
581
  * @returns The parsed result.
572
582
  * @throws {TypeError} If an async parser is passed at runtime. Use
573
583
  * {@link runWith} or {@link runWithAsync} for async parsers.
@@ -596,6 +606,8 @@ declare function runWithSync<TParser extends Parser<"sync", unknown, unknown>, T
596
606
  * @param programName Name of the program for help/error output.
597
607
  * @param contexts Source contexts to use (priority: earlier overrides later).
598
608
  * @param options Run options including args, help, version, etc.
609
+ * @throws {RangeError} If rendering help or errors encounters an invalid theme
610
+ * color, even when colors are disabled.
599
611
  * @returns Promise that resolves to the parsed result.
600
612
  * @throws {TypeError} If two or more contexts share the same
601
613
  * {@link SourceContext.id}.
package/dist/facade.js CHANGED
@@ -531,10 +531,12 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
531
531
  const callOnCompletion = (code) => onCompletion(code);
532
532
  if (!shellName) {
533
533
  const error = message`Missing shell name for completion.`;
534
- stderr(`${errorLabel()}${formatMessage(error, {
534
+ const prefix = errorLabel();
535
+ stderr(`${prefix}${formatMessage(error, {
535
536
  colors,
536
537
  quotes: !colors,
537
- maxWidth
538
+ maxWidth,
539
+ initialWidth: getDisplayWidth(prefix.split("\n").at(-1) ?? "")
538
540
  })}\n`);
539
541
  if (completionParser) {
540
542
  const displayName = isOptionMode ? completionOptionDisplayName ?? "--completion" : completionCommandDisplayName ?? "completion";
@@ -563,10 +565,12 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
563
565
  available.push(value(name));
564
566
  }
565
567
  const error = message`Unsupported shell ${shellName}. Available shells: ${available}.`;
566
- stderr(`${errorLabel()}${formatMessage(error, {
568
+ const prefix = errorLabel();
569
+ stderr(`${prefix}${formatMessage(error, {
567
570
  colors,
568
571
  quotes: !colors,
569
- maxWidth
572
+ maxWidth,
573
+ initialWidth: getDisplayWidth(prefix.split("\n").at(-1) ?? "")
570
574
  })}`);
571
575
  return dispatchByMode(parser.mode, () => {
572
576
  const result = callOnError(1, error);
@@ -892,7 +896,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
892
896
  label: "Usage:",
893
897
  kind: "usageSummary"
894
898
  }, theme, colors) + " ";
895
- const usageLabelWidth = () => getDisplayWidth(usageLabel());
899
+ const usageLabelWidth = () => getDisplayWidth(usageLabel().split("\n").at(-1) ?? "");
896
900
  const norm = (c) => c === true ? {} : c;
897
901
  const helpCommandConfig = norm(options.help?.command);
898
902
  const helpOptionConfig = norm(options.help?.option);
@@ -1053,12 +1057,14 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
1053
1057
  maxWidth: maxWidth == null ? void 0 : maxWidth - usageLabelWidth(),
1054
1058
  expandCommands: true
1055
1059
  }), usageLabelWidth())}`);
1060
+ const prefix = errorLabel();
1056
1061
  const errorMessage = formatMessage(validationError, {
1062
+ initialWidth: getDisplayWidth(prefix.split("\n").at(-1) ?? ""),
1057
1063
  maxWidth,
1058
1064
  colors,
1059
1065
  quotes: !colors
1060
1066
  });
1061
- stderr(`${errorLabel()}${errorMessage}`);
1067
+ stderr(`${prefix}${errorMessage}`);
1062
1068
  return onError(1, validationError);
1063
1069
  };
1064
1070
  const displayHelp = (doc) => {
@@ -1171,12 +1177,14 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
1171
1177
  maxWidth: maxWidth == null ? void 0 : maxWidth - usageLabelWidth(),
1172
1178
  expandCommands: true
1173
1179
  }), usageLabelWidth())}`);
1180
+ const prefix = errorLabel();
1174
1181
  const errorMessage = formatMessage(classified.error, {
1182
+ initialWidth: getDisplayWidth(prefix.split("\n").at(-1) ?? ""),
1175
1183
  maxWidth,
1176
1184
  colors,
1177
1185
  quotes: !colors
1178
1186
  });
1179
- stderr(`${errorLabel()}${errorMessage}`);
1187
+ stderr(`${prefix}${errorMessage}`);
1180
1188
  return onError(1, classified.error);
1181
1189
  };
1182
1190
  if (aboveError === "help") {
@@ -1230,6 +1238,8 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
1230
1238
  * @param programName The name of the program for help messages.
1231
1239
  * @param args The command-line arguments to parse.
1232
1240
  * @param options Configuration options for customizing behavior.
1241
+ * @throws {RangeError} If rendering help or errors encounters an invalid theme
1242
+ * color, even when colors are disabled.
1233
1243
  * @returns The parsed result if successful.
1234
1244
  * @throws {TypeError} If an async parser is passed at runtime. Use
1235
1245
  * {@link runParser} or {@link runParserAsync} for async parsers.
@@ -1253,6 +1263,8 @@ function runParserSync(parser, programName, args, options) {
1253
1263
  * @param programName The name of the program for help messages.
1254
1264
  * @param args The command-line arguments to parse.
1255
1265
  * @param options Configuration options for customizing behavior.
1266
+ * @throws {RangeError} If rendering help or errors encounters an invalid theme
1267
+ * color, even when colors are disabled.
1256
1268
  * @returns A Promise of the parsed result if successful.
1257
1269
  * @since 0.9.0
1258
1270
  */
@@ -1602,6 +1614,8 @@ async function runWithBody(parser, programName, contexts, args, options) {
1602
1614
  * @param programName Name of the program for help/error output.
1603
1615
  * @param contexts Source contexts to use (priority: earlier overrides later).
1604
1616
  * @param options Run options including args, help, version, etc.
1617
+ * @throws {RangeError} If rendering help or errors encounters an invalid theme
1618
+ * color, even when colors are disabled.
1605
1619
  * @returns Promise that resolves to the parsed result.
1606
1620
  * @throws {TypeError} If two or more contexts share the same
1607
1621
  * {@link SourceContext.id}.
@@ -1700,6 +1714,8 @@ function runWithSyncBody(parser, programName, contexts, args, options) {
1700
1714
  * @param programName Name of the program for help/error output.
1701
1715
  * @param contexts Source contexts to use (priority: earlier overrides later).
1702
1716
  * @param options Run options including args, help, version, etc.
1717
+ * @throws {RangeError} If rendering help or errors encounters an invalid theme
1718
+ * color, even when colors are disabled.
1703
1719
  * @returns The parsed result.
1704
1720
  * @throws {TypeError} If an async parser is passed at runtime. Use
1705
1721
  * {@link runWith} or {@link runWithAsync} for async parsers.
@@ -1749,6 +1765,8 @@ function runWithSync(parser, programName, contexts, options) {
1749
1765
  * @param programName Name of the program for help/error output.
1750
1766
  * @param contexts Source contexts to use (priority: earlier overrides later).
1751
1767
  * @param options Run options including args, help, version, etc.
1768
+ * @throws {RangeError} If rendering help or errors encounters an invalid theme
1769
+ * color, even when colors are disabled.
1752
1770
  * @returns Promise that resolves to the parsed result.
1753
1771
  * @throws {TypeError} If two or more contexts share the same
1754
1772
  * {@link SourceContext.id}.
package/dist/message.cjs CHANGED
@@ -301,9 +301,9 @@ function formatMessage(msg, options = {}) {
301
301
  /**
302
302
  * Creates a message formatter using a snapshot of the supplied theme.
303
303
  * @param theme Semantic leaf formatters and annotation styles.
304
- * @returns A reusable message formatter.
305
- * @throws {TypeError} If initialWidth is not a finite integer.
306
- * @throws {RangeError} If initialWidth is negative or a color is invalid.
304
+ * @returns A reusable message formatter. Invoking it throws `TypeError` if
305
+ * `initialWidth` is not a finite integer, or `RangeError` if `initialWidth`
306
+ * is negative or a theme color is invalid (even with colors disabled).
307
307
  * @since 1.3.0
308
308
  */
309
309
  function createMessageFormatter(theme) {
@@ -443,9 +443,9 @@ type MessageFormatter = (message: Message, options?: MessageFormatterOptions) =>
443
443
  /**
444
444
  * Creates a message formatter using a snapshot of the supplied theme.
445
445
  * @param theme Semantic leaf formatters and annotation styles.
446
- * @returns A reusable message formatter.
447
- * @throws {TypeError} If initialWidth is not a finite integer.
448
- * @throws {RangeError} If initialWidth is negative or a color is invalid.
446
+ * @returns A reusable message formatter. Invoking it throws `TypeError` if
447
+ * `initialWidth` is not a finite integer, or `RangeError` if `initialWidth`
448
+ * is negative or a theme color is invalid (even with colors disabled).
449
449
  * @since 1.3.0
450
450
  */
451
451
  declare function createMessageFormatter(theme: TerminalTheme): MessageFormatter;
package/dist/message.d.ts CHANGED
@@ -443,9 +443,9 @@ type MessageFormatter = (message: Message, options?: MessageFormatterOptions) =>
443
443
  /**
444
444
  * Creates a message formatter using a snapshot of the supplied theme.
445
445
  * @param theme Semantic leaf formatters and annotation styles.
446
- * @returns A reusable message formatter.
447
- * @throws {TypeError} If initialWidth is not a finite integer.
448
- * @throws {RangeError} If initialWidth is negative or a color is invalid.
446
+ * @returns A reusable message formatter. Invoking it throws `TypeError` if
447
+ * `initialWidth` is not a finite integer, or `RangeError` if `initialWidth`
448
+ * is negative or a theme color is invalid (even with colors disabled).
449
449
  * @since 1.3.0
450
450
  */
451
451
  declare function createMessageFormatter(theme: TerminalTheme): MessageFormatter;
package/dist/message.js CHANGED
@@ -301,9 +301,9 @@ function formatMessage(msg, options = {}) {
301
301
  /**
302
302
  * Creates a message formatter using a snapshot of the supplied theme.
303
303
  * @param theme Semantic leaf formatters and annotation styles.
304
- * @returns A reusable message formatter.
305
- * @throws {TypeError} If initialWidth is not a finite integer.
306
- * @throws {RangeError} If initialWidth is negative or a color is invalid.
304
+ * @returns A reusable message formatter. Invoking it throws `TypeError` if
305
+ * `initialWidth` is not a finite integer, or `RangeError` if `initialWidth`
306
+ * is negative or a theme color is invalid (even with colors disabled).
307
307
  * @since 1.3.0
308
308
  */
309
309
  function createMessageFormatter(theme) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@optique/core",
3
- "version": "1.3.0-dev.2534",
3
+ "version": "1.3.0-dev.2538",
4
4
  "description": "Type-safe combinatorial command-line interface parser",
5
5
  "keywords": [
6
6
  "CLI",
@@ -237,7 +237,7 @@
237
237
  },
238
238
  "sideEffects": false,
239
239
  "devDependencies": {
240
- "@optique/env": "1.3.0-dev.2534+0daf40ee",
240
+ "@optique/env": "1.3.0-dev.2538+8e1487d7",
241
241
  "@types/node": "^24.0.0",
242
242
  "fast-check": "^4.7.0",
243
243
  "tsdown": "^0.13.0",