@optique/core 1.4.0-dev.2619 → 1.4.0-dev.2623

package/dist/facade.cjs

@@ -818,7 +818,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		options = optionsParam ?? {};
 	}
 	require_validate.validateProgramName(programName);
-	const { colors, messageFormatter, theme: requestedTheme, maxWidth: requestedMaxWidth, termWidth, showDefault, showChoices, sectionOrder, showUsage, usageLine, commandList = "recursive", aboveError = "usage", onError = () => {
+	const { colors, messageFormatter, theme: requestedTheme, maxWidth: requestedMaxWidth, termWidth, showDefault, showChoices, sectionOrder, helpSections, showUsage, usageLine, commandList = "recursive", aboveError = "usage", onError = () => {
 		throw new RunParserError("Failed to parse command line arguments.");
 	}, stderr = console.error, stdout = console.log, brief, description, examples, author, bugs, footer } = options;
 	let maxWidth = requestedMaxWidth;
@@ -850,6 +850,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 	const onCompletion = options.completion?.onShow ?? (() => ({}));
 	const onCompletionResult = (code) => onCompletion(code);
 	const onErrorResult = (code, error) => onError(code, error);
+	for (const label of [helpSections?.commands, helpSections?.options]) if (label !== void 0) require_validate.validateLabel(label);
 	if (helpOptionConfig?.names) require_validate.validateOptionNames(helpOptionConfig.names, "Help option");
 	if (helpCommandConfig?.names) require_validate.validateCommandNames(helpCommandConfig.names, "Help command");
 	if (versionOptionConfig?.names) require_validate.validateOptionNames(versionOptionConfig.names, "Version option");
@@ -1022,7 +1023,8 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							bugs: isTopLevel && !isMetaCommandHelp ? bugs ?? doc.bugs : void 0,
 							footer: shouldOverride ? footer ?? doc.footer : doc.footer ?? footer
 						}, commandList, isTopLevel);
-						const renderedDoc = isTopLevel && usageLine != null ? applyUsageLine(augmentedDoc, usageLine) : augmentedDoc;
+						const groupedDoc = applyHelpSections(augmentedDoc, helpSections);
+						const renderedDoc = isTopLevel && usageLine != null ? applyUsageLine(groupedDoc, usageLine) : groupedDoc;
 						stdout(require_doc.formatDocPage(programName, renderedDoc, formatOptions({
 							messageFormatter,
 							theme,
@@ -1098,7 +1100,8 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							footer: footer ?? doc.footer
 						}, commandList, isTopLevel);
 						const defaultRootUsage = typeof usageLine === "function" && (options.help || options.version || options.completion) ? require_usage.normalizeUsage(getRootHelpGeneratorParser().usage) : augmentedDoc.usage ?? [];
-						const renderedDoc = isTopLevel && usageLine != null ? applyUsageLine(augmentedDoc, usageLine, defaultRootUsage) : augmentedDoc;
+						const groupedDoc = applyHelpSections(augmentedDoc, helpSections);
+						const renderedDoc = isTopLevel && usageLine != null ? applyUsageLine(groupedDoc, usageLine, defaultRootUsage) : groupedDoc;
 						stderr(require_doc.formatDocPage(programName, renderedDoc, formatOptions({
 							messageFormatter,
 							theme,
@@ -1185,6 +1188,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 * @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.
+* @throws {TypeError} If a `helpSections` label is invalid.
 * @since 0.9.0
 */
 function runParserSync(parser, programName, args, options) {
@@ -1207,6 +1211,7 @@ function runParserSync(parser, programName, args, options) {
 * @param options Configuration options for customizing behavior.
 * @throws {RangeError} If rendering help or errors encounters an invalid theme
 * color, even when colors are disabled.
+* @throws {TypeError} If a `helpSections` label is invalid.
 * @returns A Promise of the parsed result if successful.
 * @since 0.9.0
 */
@@ -1221,6 +1226,66 @@ function applyUsageLine(doc, usageLine, defaultUsageLine = doc.usage ?? []) {
 		usage: require_usage.normalizeUsage(customUsageLine)
 	};
 }
+/** Prepares the runner's final page without changing parser documentation. */
+function applyHelpSections(doc, labels) {
+	if (labels == null || labels.commands == null && labels.options == null) return doc;
+	const visible = (entry) => !require_doc.isDocEntryHidden(entry) && require_usage.formatUsageTerm(entry.term, { context: "doc" }).trim() !== "";
+	if (!doc.sections.some((section) => section.entries.some((entry) => entry.term.type === "command" && visible(entry)))) return doc;
+	const existingTitles = new Set(doc.sections.flatMap((section) => section.title == null ? [] : [section.title]));
+	const additions = /* @__PURE__ */ new Map();
+	const residuals = /* @__PURE__ */ new Map();
+	const newSections = /* @__PURE__ */ new Map();
+	for (const section of doc.sections) {
+		if (section.title != null) continue;
+		const commands = [];
+		const options = [];
+		const remaining = [];
+		for (const entry of section.entries) if (entry.term.type === "command" && labels.commands != null && visible(entry)) commands.push(entry);
+		else if (entry.term.type === "option" && labels.options != null && visible(entry)) options.push(entry);
+		else remaining.push(entry);
+		if (commands.length === 0 && options.length === 0) continue;
+		residuals.set(section, remaining);
+		for (const [label, entries] of [[labels.commands, commands], [labels.options, options]]) {
+			if (label == null || entries.length === 0) continue;
+			const previous = additions.get(label);
+			if (previous != null) previous.push(...entries);
+			else {
+				additions.set(label, entries);
+				if (!existingTitles.has(label)) {
+					const titles = newSections.get(section) ?? [];
+					titles.push(label);
+					newSections.set(section, titles);
+				}
+			}
+		}
+	}
+	if (additions.size === 0) return doc;
+	const sections = [];
+	for (const section of doc.sections) {
+		if (section.title != null) {
+			const entries$1 = additions.get(section.title);
+			sections.push(entries$1 == null ? section : {
+				...section,
+				entries: [...section.entries, ...entries$1]
+			});
+			continue;
+		}
+		for (const title of newSections.get(section) ?? []) sections.push({
+			title,
+			entries: additions.get(title) ?? []
+		});
+		const entries = residuals.get(section);
+		if (entries == null) sections.push(section);
+		else if (entries.length > 0) sections.push({
+			...section,
+			entries
+		});
+	}
+	return {
+		...doc,
+		sections
+	};
+}
 function maybeCollapseCommandList(doc, commandList, isTopLevel) {
 	if (commandList !== "top-level" || !isTopLevel) return doc;
 	return {
@@ -1556,6 +1621,7 @@ 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 {TypeError} If a `helpSections` label is invalid.
 * @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.
@@ -1656,6 +1722,7 @@ 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 {TypeError} If a `helpSections` label is invalid.
 * @throws {RangeError} If rendering help or errors encounters an invalid theme
 * color, even when colors are disabled.
 * @returns The parsed result.
@@ -1707,6 +1774,7 @@ 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 {TypeError} If a `helpSections` label is invalid.
 * @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.

package/dist/facade.d.cts

@@ -20,6 +20,19 @@ import { Program } from "./program.cjs";
  * @since 1.2.0
  */
 type CommandListMode = "recursive" | "top-level";
+/**
+ * Labels for automatically grouping untitled help entries on pages that
+ * contain visible commands. Explicitly titled sections keep their titles.
+ * Missing labels leave the corresponding entries untitled.
+ *
+ * @since 1.4.0
+ */
+interface HelpSectionsOptions {
+  /** Heading for untitled command entries. */
+  readonly commands?: string;
+  /** Heading for untitled option entries, including built-in meta options. */
+  readonly options?: string;
+}
 /**
  * Sub-configuration for a meta command's command form.
  *
@@ -184,6 +197,16 @@ interface RunOptions<THelp, TError> {
    * @since 1.0.0
    */
   readonly sectionOrder?: (a: DocSection, b: DocSection) => number;
+  /**
+   * Groups untitled command and option entries when the help page contains
+   * visible commands. Pages without commands receive no automatic headings.
+   * Existing titled sections are preserved; matching automatic entries are
+   * appended to them. Applies to help callbacks and help above errors too.
+   * Supplied labels must be nonempty and contain no control characters.
+   *
+   * @since 1.4.0
+   */
+  readonly helpSections?: HelpSectionsOptions;
   /**
    * Help configuration.  When provided, enables help functionality.
    * At least one of `command` or `option` must be specified.
@@ -382,7 +405,9 @@ interface RunOptions<THelp, TError> {
  *          non-empty string without ASCII control characters, or if any
  *          meta command/option name is empty, whitespace-only, contains
  *          whitespace or control characters, or (for option names) lacks a
- *          valid prefix (`--`, `-`, `/`, or `+`).
+ *          valid prefix (`--`, `-`, `/`, or `+`). Also thrown if a
+ *          `helpSections` label is empty, whitespace-only, or contains
+ *          control characters.
  * @throws {RunParserError} When parsing fails and no `onError` callback is
  *          provided, or if the requested help page cannot be generated.
  * @since 0.10.0 Added support for {@link Program} objects.
@@ -411,6 +436,7 @@ declare function runParser<TParser extends Parser<Mode, unknown, unknown>, THelp
  * @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.
+ * @throws {TypeError} If a `helpSections` label is invalid.
  * @since 0.9.0
  */
 declare function runParserSync<TParser extends Parser<"sync", unknown, unknown>, THelp = void, TError = never>(parser: TParser, programName: string, args: readonly string[], options?: RunOptions<THelp, TError>): InferValue<TParser>;
@@ -430,6 +456,7 @@ declare function runParserSync<TParser extends Parser<"sync", unknown, unknown>,
  * @param options Configuration options for customizing behavior.
  * @throws {RangeError} If rendering help or errors encounters an invalid theme
  * color, even when colors are disabled.
+ * @throws {TypeError} If a `helpSections` label is invalid.
  * @returns A Promise of the parsed result if successful.
  * @since 0.9.0
  */
@@ -544,6 +571,7 @@ 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 {TypeError} If a `helpSections` label is invalid.
  * @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.
@@ -595,6 +623,7 @@ 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 {TypeError} If a `helpSections` label is invalid.
  * @throws {RangeError} If rendering help or errors encounters an invalid theme
  * color, even when colors are disabled.
  * @returns The parsed result.
@@ -625,6 +654,7 @@ 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 {TypeError} If a `helpSections` label is invalid.
  * @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.
@@ -637,4 +667,4 @@ declare function runWithSync<TParser extends Parser<"sync", unknown, unknown>, T
  */
 declare function runWithAsync<TParser extends Parser<Mode, unknown, unknown>, TContexts extends readonly SourceContext<unknown>[], THelp = void, TError = never>(parser: TParser, programName: string, contexts: TContexts, options: RunWithOptions<THelp, TError> & ContextOptionsParam<TContexts, InferValue<TParser>>): Promise<InferValue<TParser>>;
 //#endregion
-export { CommandListMode, CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, type ParserValuePlaceholder, RunOptions, RunParserError, RunWithOptions, type SourceContext, type SourceContextRequest, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync };
+export { CommandListMode, CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, HelpSectionsOptions, OptionSubConfig, type ParserValuePlaceholder, RunOptions, RunParserError, RunWithOptions, type SourceContext, type SourceContextRequest, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync };

package/dist/facade.d.ts

@@ -20,6 +20,19 @@ import { Program } from "./program.js";
  * @since 1.2.0
  */
 type CommandListMode = "recursive" | "top-level";
+/**
+ * Labels for automatically grouping untitled help entries on pages that
+ * contain visible commands. Explicitly titled sections keep their titles.
+ * Missing labels leave the corresponding entries untitled.
+ *
+ * @since 1.4.0
+ */
+interface HelpSectionsOptions {
+  /** Heading for untitled command entries. */
+  readonly commands?: string;
+  /** Heading for untitled option entries, including built-in meta options. */
+  readonly options?: string;
+}
 /**
  * Sub-configuration for a meta command's command form.
  *
@@ -184,6 +197,16 @@ interface RunOptions<THelp, TError> {
    * @since 1.0.0
    */
   readonly sectionOrder?: (a: DocSection, b: DocSection) => number;
+  /**
+   * Groups untitled command and option entries when the help page contains
+   * visible commands. Pages without commands receive no automatic headings.
+   * Existing titled sections are preserved; matching automatic entries are
+   * appended to them. Applies to help callbacks and help above errors too.
+   * Supplied labels must be nonempty and contain no control characters.
+   *
+   * @since 1.4.0
+   */
+  readonly helpSections?: HelpSectionsOptions;
   /**
    * Help configuration.  When provided, enables help functionality.
    * At least one of `command` or `option` must be specified.
@@ -382,7 +405,9 @@ interface RunOptions<THelp, TError> {
  *          non-empty string without ASCII control characters, or if any
  *          meta command/option name is empty, whitespace-only, contains
  *          whitespace or control characters, or (for option names) lacks a
- *          valid prefix (`--`, `-`, `/`, or `+`).
+ *          valid prefix (`--`, `-`, `/`, or `+`). Also thrown if a
+ *          `helpSections` label is empty, whitespace-only, or contains
+ *          control characters.
  * @throws {RunParserError} When parsing fails and no `onError` callback is
  *          provided, or if the requested help page cannot be generated.
  * @since 0.10.0 Added support for {@link Program} objects.
@@ -411,6 +436,7 @@ declare function runParser<TParser extends Parser<Mode, unknown, unknown>, THelp
  * @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.
+ * @throws {TypeError} If a `helpSections` label is invalid.
  * @since 0.9.0
  */
 declare function runParserSync<TParser extends Parser<"sync", unknown, unknown>, THelp = void, TError = never>(parser: TParser, programName: string, args: readonly string[], options?: RunOptions<THelp, TError>): InferValue<TParser>;
@@ -430,6 +456,7 @@ declare function runParserSync<TParser extends Parser<"sync", unknown, unknown>,
  * @param options Configuration options for customizing behavior.
  * @throws {RangeError} If rendering help or errors encounters an invalid theme
  * color, even when colors are disabled.
+ * @throws {TypeError} If a `helpSections` label is invalid.
  * @returns A Promise of the parsed result if successful.
  * @since 0.9.0
  */
@@ -544,6 +571,7 @@ 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 {TypeError} If a `helpSections` label is invalid.
  * @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.
@@ -595,6 +623,7 @@ 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 {TypeError} If a `helpSections` label is invalid.
  * @throws {RangeError} If rendering help or errors encounters an invalid theme
  * color, even when colors are disabled.
  * @returns The parsed result.
@@ -625,6 +654,7 @@ 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 {TypeError} If a `helpSections` label is invalid.
  * @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.
@@ -637,4 +667,4 @@ declare function runWithSync<TParser extends Parser<"sync", unknown, unknown>, T
  */
 declare function runWithAsync<TParser extends Parser<Mode, unknown, unknown>, TContexts extends readonly SourceContext<unknown>[], THelp = void, TError = never>(parser: TParser, programName: string, contexts: TContexts, options: RunWithOptions<THelp, TError> & ContextOptionsParam<TContexts, InferValue<TParser>>): Promise<InferValue<TParser>>;
 //#endregion
-export { CommandListMode, CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, type ParserValuePlaceholder, RunOptions, RunParserError, RunWithOptions, type SourceContext, type SourceContextRequest, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync };
+export { CommandListMode, CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, HelpSectionsOptions, OptionSubConfig, type ParserValuePlaceholder, RunOptions, RunParserError, RunWithOptions, type SourceContext, type SourceContextRequest, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync };

package/dist/facade.js

@@ -1,12 +1,12 @@
 import { injectAnnotations } from "./internal/annotations.js";
 import { cacheTerminalTheme, renderTerminalTerm } from "./terminal-internal.js";
 import { measureText, spaceAfterLabel } from "./text-layout.js";
-import { validateCommandNames, validateContextIds, validateMetaNameCollisions, validateOptionNames, validateProgramName } from "./validate.js";
-import { cloneUsage, formatUsage, isSuggestionHidden, normalizeUsage } from "./usage.js";
+import { validateCommandNames, validateContextIds, validateLabel, validateMetaNameCollisions, validateOptionNames, validateProgramName } from "./validate.js";
+import { cloneUsage, formatUsage, formatUsageTerm, isSuggestionHidden, normalizeUsage } from "./usage.js";
 import { hasAutomaticWidth, minimumUsageWidth, withAutomaticWidth } from "./terminal-width.js";
 import { commandLine, lineBreak, message, optionName, text, value } from "./message.js";
 import { renderErrorMessage } from "./message-renderer.js";
-import { formatDocPage } from "./doc.js";
+import { formatDocPage, isDocEntryHidden } from "./doc.js";
 import { dispatchByMode } from "./internal/mode-dispatch.js";
 import { collectExplicitSourceValues, collectExplicitSourceValuesAsync, createDependencyRuntimeContext } from "./dependency-runtime.js";
 import { createInputTrace } from "./input-trace.js";
@@ -818,7 +818,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		options = optionsParam ?? {};
 	}
 	validateProgramName(programName);
-	const { colors, messageFormatter, theme: requestedTheme, maxWidth: requestedMaxWidth, termWidth, showDefault, showChoices, sectionOrder, showUsage, usageLine, commandList = "recursive", aboveError = "usage", onError = () => {
+	const { colors, messageFormatter, theme: requestedTheme, maxWidth: requestedMaxWidth, termWidth, showDefault, showChoices, sectionOrder, helpSections, showUsage, usageLine, commandList = "recursive", aboveError = "usage", onError = () => {
 		throw new RunParserError("Failed to parse command line arguments.");
 	}, stderr = console.error, stdout = console.log, brief, description, examples, author, bugs, footer } = options;
 	let maxWidth = requestedMaxWidth;
@@ -850,6 +850,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 	const onCompletion = options.completion?.onShow ?? (() => ({}));
 	const onCompletionResult = (code) => onCompletion(code);
 	const onErrorResult = (code, error) => onError(code, error);
+	for (const label of [helpSections?.commands, helpSections?.options]) if (label !== void 0) validateLabel(label);
 	if (helpOptionConfig?.names) validateOptionNames(helpOptionConfig.names, "Help option");
 	if (helpCommandConfig?.names) validateCommandNames(helpCommandConfig.names, "Help command");
 	if (versionOptionConfig?.names) validateOptionNames(versionOptionConfig.names, "Version option");
@@ -1022,7 +1023,8 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							bugs: isTopLevel && !isMetaCommandHelp ? bugs ?? doc.bugs : void 0,
 							footer: shouldOverride ? footer ?? doc.footer : doc.footer ?? footer
 						}, commandList, isTopLevel);
-						const renderedDoc = isTopLevel && usageLine != null ? applyUsageLine(augmentedDoc, usageLine) : augmentedDoc;
+						const groupedDoc = applyHelpSections(augmentedDoc, helpSections);
+						const renderedDoc = isTopLevel && usageLine != null ? applyUsageLine(groupedDoc, usageLine) : groupedDoc;
 						stdout(formatDocPage(programName, renderedDoc, formatOptions({
 							messageFormatter,
 							theme,
@@ -1098,7 +1100,8 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							footer: footer ?? doc.footer
 						}, commandList, isTopLevel);
 						const defaultRootUsage = typeof usageLine === "function" && (options.help || options.version || options.completion) ? normalizeUsage(getRootHelpGeneratorParser().usage) : augmentedDoc.usage ?? [];
-						const renderedDoc = isTopLevel && usageLine != null ? applyUsageLine(augmentedDoc, usageLine, defaultRootUsage) : augmentedDoc;
+						const groupedDoc = applyHelpSections(augmentedDoc, helpSections);
+						const renderedDoc = isTopLevel && usageLine != null ? applyUsageLine(groupedDoc, usageLine, defaultRootUsage) : groupedDoc;
 						stderr(formatDocPage(programName, renderedDoc, formatOptions({
 							messageFormatter,
 							theme,
@@ -1185,6 +1188,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 * @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.
+* @throws {TypeError} If a `helpSections` label is invalid.
 * @since 0.9.0
 */
 function runParserSync(parser, programName, args, options) {
@@ -1207,6 +1211,7 @@ function runParserSync(parser, programName, args, options) {
 * @param options Configuration options for customizing behavior.
 * @throws {RangeError} If rendering help or errors encounters an invalid theme
 * color, even when colors are disabled.
+* @throws {TypeError} If a `helpSections` label is invalid.
 * @returns A Promise of the parsed result if successful.
 * @since 0.9.0
 */
@@ -1221,6 +1226,66 @@ function applyUsageLine(doc, usageLine, defaultUsageLine = doc.usage ?? []) {
 		usage: normalizeUsage(customUsageLine)
 	};
 }
+/** Prepares the runner's final page without changing parser documentation. */
+function applyHelpSections(doc, labels) {
+	if (labels == null || labels.commands == null && labels.options == null) return doc;
+	const visible = (entry) => !isDocEntryHidden(entry) && formatUsageTerm(entry.term, { context: "doc" }).trim() !== "";
+	if (!doc.sections.some((section) => section.entries.some((entry) => entry.term.type === "command" && visible(entry)))) return doc;
+	const existingTitles = new Set(doc.sections.flatMap((section) => section.title == null ? [] : [section.title]));
+	const additions = /* @__PURE__ */ new Map();
+	const residuals = /* @__PURE__ */ new Map();
+	const newSections = /* @__PURE__ */ new Map();
+	for (const section of doc.sections) {
+		if (section.title != null) continue;
+		const commands = [];
+		const options = [];
+		const remaining = [];
+		for (const entry of section.entries) if (entry.term.type === "command" && labels.commands != null && visible(entry)) commands.push(entry);
+		else if (entry.term.type === "option" && labels.options != null && visible(entry)) options.push(entry);
+		else remaining.push(entry);
+		if (commands.length === 0 && options.length === 0) continue;
+		residuals.set(section, remaining);
+		for (const [label, entries] of [[labels.commands, commands], [labels.options, options]]) {
+			if (label == null || entries.length === 0) continue;
+			const previous = additions.get(label);
+			if (previous != null) previous.push(...entries);
+			else {
+				additions.set(label, entries);
+				if (!existingTitles.has(label)) {
+					const titles = newSections.get(section) ?? [];
+					titles.push(label);
+					newSections.set(section, titles);
+				}
+			}
+		}
+	}
+	if (additions.size === 0) return doc;
+	const sections = [];
+	for (const section of doc.sections) {
+		if (section.title != null) {
+			const entries$1 = additions.get(section.title);
+			sections.push(entries$1 == null ? section : {
+				...section,
+				entries: [...section.entries, ...entries$1]
+			});
+			continue;
+		}
+		for (const title of newSections.get(section) ?? []) sections.push({
+			title,
+			entries: additions.get(title) ?? []
+		});
+		const entries = residuals.get(section);
+		if (entries == null) sections.push(section);
+		else if (entries.length > 0) sections.push({
+			...section,
+			entries
+		});
+	}
+	return {
+		...doc,
+		sections
+	};
+}
 function maybeCollapseCommandList(doc, commandList, isTopLevel) {
 	if (commandList !== "top-level" || !isTopLevel) return doc;
 	return {
@@ -1556,6 +1621,7 @@ 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 {TypeError} If a `helpSections` label is invalid.
 * @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.
@@ -1656,6 +1722,7 @@ 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 {TypeError} If a `helpSections` label is invalid.
 * @throws {RangeError} If rendering help or errors encounters an invalid theme
 * color, even when colors are disabled.
 * @returns The parsed result.
@@ -1707,6 +1774,7 @@ 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 {TypeError} If a `helpSections` label is invalid.
 * @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.

package/dist/index.d.cts

@@ -11,6 +11,6 @@ import { DeferredValue, DeferredValueOptions, DeferredValueSource, FluentParser,
 import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, GroupOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, SeqOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, seq, tuple } from "./constructs.cjs";
 import { ParserValuePlaceholder, SourceContext, SourceContextRequest } from "./context.cjs";
 import { AnyDependencySource, CombineMode, CombinedDependencyMode, DependencyMode, DependencySource, DependencySourceInfo, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, dependency, deriveFrom, deriveFromAsync, deriveFromSync, getDependencySourceInfo, isDependencySource, isDerivedValueParser } from "./internal/dependency.cjs";
-import { CommandListMode, CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.cjs";
+import { CommandListMode, CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, HelpSectionsOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.cjs";
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, negatableFlag, option, passThrough } from "./primitives.cjs";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandListMode, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DeferredValue, DeferredValueOptions, DeferredValueSource, DependencyMode, DependencySource, DependencySourceInfo, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DetailedParseResult, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EffectfulCompletionSession, EmailOptions, ErrorLabelTerm, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FlagErrorOptions, FlagOptions, FloatOptions, FluentParser, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LabelTerm, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageFormatter, type MessageFormatterOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, OriginOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserModifiers, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ProgramNameTerm, RegExpOptions, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, SyntaxPunctuationTerm, TerminalColor, TerminalFormatContext, TerminalFormatter, TerminalFragment, TerminalStyle, TerminalTerm, TerminalTheme, TransformMapping, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, biject, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createMessageFormatter, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, defaultTerminalTheme, deferredValue, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDependencySourceInfo, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, origin, parse, parseAsync, parseDetailed, parseSync, passThrough, port, portRange, pwsh, regExp, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, transform, tuple, url, uuid, value, valueSet, values, withDefault, zsh };
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandListMode, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DeferredValue, DeferredValueOptions, DeferredValueSource, DependencyMode, DependencySource, DependencySourceInfo, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DetailedParseResult, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EffectfulCompletionSession, EmailOptions, ErrorLabelTerm, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FlagErrorOptions, FlagOptions, FloatOptions, FluentParser, GroupOptions, HelpSectionsOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LabelTerm, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageFormatter, type MessageFormatterOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, OriginOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserModifiers, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ProgramNameTerm, RegExpOptions, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, SyntaxPunctuationTerm, TerminalColor, TerminalFormatContext, TerminalFormatter, TerminalFragment, TerminalStyle, TerminalTerm, TerminalTheme, TransformMapping, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, biject, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createMessageFormatter, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, defaultTerminalTheme, deferredValue, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDependencySourceInfo, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, origin, parse, parseAsync, parseDetailed, parseSync, passThrough, port, portRange, pwsh, regExp, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, transform, tuple, url, uuid, value, valueSet, values, withDefault, zsh };

package/dist/index.d.ts

@@ -11,6 +11,6 @@ import { DeferredValue, DeferredValueOptions, DeferredValueSource, FluentParser,
 import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, GroupOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, SeqOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, seq, tuple } from "./constructs.js";
 import { ParserValuePlaceholder, SourceContext, SourceContextRequest } from "./context.js";
 import { AnyDependencySource, CombineMode, CombinedDependencyMode, DependencyMode, DependencySource, DependencySourceInfo, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, dependency, deriveFrom, deriveFromAsync, deriveFromSync, getDependencySourceInfo, isDependencySource, isDerivedValueParser } from "./internal/dependency.js";
-import { CommandListMode, CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
+import { CommandListMode, CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, HelpSectionsOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, negatableFlag, option, passThrough } from "./primitives.js";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandListMode, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DeferredValue, DeferredValueOptions, DeferredValueSource, DependencyMode, DependencySource, DependencySourceInfo, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DetailedParseResult, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EffectfulCompletionSession, EmailOptions, ErrorLabelTerm, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FlagErrorOptions, FlagOptions, FloatOptions, FluentParser, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LabelTerm, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageFormatter, type MessageFormatterOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, OriginOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserModifiers, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ProgramNameTerm, RegExpOptions, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, SyntaxPunctuationTerm, TerminalColor, TerminalFormatContext, TerminalFormatter, TerminalFragment, TerminalStyle, TerminalTerm, TerminalTheme, TransformMapping, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, biject, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createMessageFormatter, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, defaultTerminalTheme, deferredValue, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDependencySourceInfo, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, origin, parse, parseAsync, parseDetailed, parseSync, passThrough, port, portRange, pwsh, regExp, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, transform, tuple, url, uuid, value, valueSet, values, withDefault, zsh };
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandListMode, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DeferredValue, DeferredValueOptions, DeferredValueSource, DependencyMode, DependencySource, DependencySourceInfo, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DetailedParseResult, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EffectfulCompletionSession, EmailOptions, ErrorLabelTerm, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FlagErrorOptions, FlagOptions, FloatOptions, FluentParser, GroupOptions, HelpSectionsOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LabelTerm, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageFormatter, type MessageFormatterOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, OriginOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserModifiers, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ProgramNameTerm, RegExpOptions, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, SyntaxPunctuationTerm, TerminalColor, TerminalFormatContext, TerminalFormatter, TerminalFragment, TerminalStyle, TerminalTerm, TerminalTheme, TransformMapping, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, biject, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createMessageFormatter, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, defaultTerminalTheme, deferredValue, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDependencySourceInfo, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, origin, parse, parseAsync, parseDetailed, parseSync, passThrough, port, portRange, pwsh, regExp, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, transform, tuple, url, uuid, value, valueSet, values, withDefault, zsh };

package/package.json

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

package/skills/optique/SKILL.md

@@ -11,8 +11,7 @@ description: >
 license: MIT
 ---
 
-Start at <https://optique.dev/llms.txt> when online. These rules cover the
-combinatorial parser model and common pitfalls offline.
+Start at <https://optique.dev/llms.txt> online; these rules also work offline.
 
 
 Core rules
@@ -30,11 +29,14 @@ Core rules
     Pin `colors`/`maxWidth` in tests; defaults use terminal and environment.
  -  Compose parsers with `object()`, `tuple()`, `seq()`, `or()`, `merge()`, and
     modifiers. Do not hand-write argument scanners around Optique parsers.
- -  Let TypeScript infer parser result types. Only write a separate result
-    interface when another API boundary requires it.
- -  Most parsers are required. `optional(p)` yields `undefined`, and
-    `withDefault(p, value)` supplies a fallback. For absent Boolean flags,
-    use `withDefault(flag("--name"), false)`.
+ -  For command/option help headings, set the runner's
+    `helpSections: { commands: "Commands", options: "Options" }`.
+    It groups untitled entries only on pages with visible commands. See
+    <https://optique.dev/cookbook.md#command-and-option-headings-in-help>.
+ -  Let TypeScript infer results unless another API needs a separate interface.
+ -  Parsers are usually required. `optional(p)` yields `undefined`, and
+    `withDefault(p, value)` supplies a fallback. Use
+    `withDefault(flag("--name"), false)` for optional Boolean flags.
  -  Use semantic `message` helpers for descriptions and errors. Since 1.3.0,
     customize terminal output with `theme` or `messageFormatter`, preserving
     `initialWidth`, quoting, and width options. Keep canonical errors unthemed.
@@ -43,10 +45,9 @@ Core rules
     parsing. Use `regExp({ flags })` for user-supplied sources, `biject()` for
     one-to-one string-to-value choices, and `transform()` when an existing
     value parser describes the accepted CLI spelling but your app needs a
-    different result type. Use `path()` from
-    `@optique/run/valueparser` for file-system paths. Write a custom
-    `{ mode, metavar, parse, format }` value parser only when the catalog does
-    not cover the domain.
+    different result type. Use `path()` from `@optique/run/valueparser` for
+    file-system paths. Write a custom `{ mode, metavar, parse, format }` value
+    parser only when the catalog does not cover the domain.
  -  Since 1.4.0, `-p8080`/`-vp8080` accept attached values. Values consume
     the literal suffix (`-p=5` gives `"=5"`); full single-dash names win.
  -  Async value parsers like *@optique/git* make containing parsers async.
@@ -231,9 +232,8 @@ const parser = logLevel();
 Common mistakes checklist
 -------------------------
 
- -  Do not parse `process.argv` manually before calling Optique. Pass the parser
-    to `run()` for applications, or pass explicit argument arrays to `parse()`
-    in tests and embedded use.
+ -  Pass parsers to `run()` for apps; use explicit argument arrays with
+    `parse()` in tests and embedded use. Do not pre-parse `process.argv`.
  -  Do not treat `or(a, b)` as “zero or more alternatives.” It requires one
     matching branch unless the whole `or()` is wrapped in `optional()` or
     `withDefault()`.