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

package/dist/parser.d.cts

@@ -4,7 +4,7 @@ import { Usage } from "./usage.cjs";
 import { DocFragments, DocPage } from "./doc.cjs";
 import { DependencyRegistryLike } from "./registry-types.cjs";
 import { ValueParserResult } from "./valueparser.cjs";
-import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.cjs";
+import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, GroupOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.cjs";
 import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.cjs";
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, option, passThrough } from "./primitives.cjs";
 
@@ -534,4 +534,4 @@ declare function getDocPage(parser: Parser<"sync", unknown, unknown>, args?: rea
 declare function getDocPage(parser: Parser<"async", unknown, unknown>, args?: readonly string[], options?: ParseOptions): Promise<DocPage | undefined>;
 declare function getDocPage<M extends Mode>(parser: Parser<M, unknown, unknown>, args?: readonly string[], options?: ParseOptions): ModeValue<M, DocPage | undefined>;
 //#endregion
-export { ArgumentErrorOptions, ArgumentOptions, CombineModes, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocState, DuplicateOptionError, FlagErrorOptions, FlagOptions, InferMode, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OptionState, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, argument, command, concat, conditional, constant, fail, flag, getDocPage, getDocPageAsync, getDocPageSync, group, longestMatch, map, merge, multiple, nonEmpty, object, option, optional, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, withDefault };
+export { ArgumentErrorOptions, ArgumentOptions, CombineModes, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocState, DuplicateOptionError, FlagErrorOptions, FlagOptions, GroupOptions, InferMode, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OptionState, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, argument, command, concat, conditional, constant, fail, flag, getDocPage, getDocPageAsync, getDocPageSync, group, longestMatch, map, merge, multiple, nonEmpty, object, option, optional, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, withDefault };

package/dist/parser.d.ts

@@ -4,7 +4,7 @@ import { Usage } from "./usage.js";
 import { DocFragments, DocPage } from "./doc.js";
 import { DependencyRegistryLike } from "./registry-types.js";
 import { ValueParserResult } from "./valueparser.js";
-import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
+import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, GroupOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
 import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, option, passThrough } from "./primitives.js";
 
@@ -534,4 +534,4 @@ declare function getDocPage(parser: Parser<"sync", unknown, unknown>, args?: rea
 declare function getDocPage(parser: Parser<"async", unknown, unknown>, args?: readonly string[], options?: ParseOptions): Promise<DocPage | undefined>;
 declare function getDocPage<M extends Mode>(parser: Parser<M, unknown, unknown>, args?: readonly string[], options?: ParseOptions): ModeValue<M, DocPage | undefined>;
 //#endregion
-export { ArgumentErrorOptions, ArgumentOptions, CombineModes, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocState, DuplicateOptionError, FlagErrorOptions, FlagOptions, InferMode, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OptionState, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, argument, command, concat, conditional, constant, fail, flag, getDocPage, getDocPageAsync, getDocPageSync, group, longestMatch, map, merge, multiple, nonEmpty, object, option, optional, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, withDefault };
+export { ArgumentErrorOptions, ArgumentOptions, CombineModes, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocState, DuplicateOptionError, FlagErrorOptions, FlagOptions, GroupOptions, InferMode, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OptionState, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, argument, command, concat, conditional, constant, fail, flag, getDocPage, getDocPageAsync, getDocPageSync, group, longestMatch, map, merge, multiple, nonEmpty, object, option, optional, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, withDefault };

package/dist/primitives.cjs

@@ -313,13 +313,13 @@ function option(...args) {
 			terms: [{
 				type: "option",
 				names: optionNames$1,
-				...options.hidden && { hidden: true }
+				...options.hidden != null && { hidden: options.hidden }
 			}]
 		} : {
 			type: "option",
 			names: optionNames$1,
 			metavar: valueParser.metavar,
-			...options.hidden && { hidden: true }
+			...options.hidden != null && { hidden: options.hidden }
 		}],
 		initialState: valueParser == null ? {
 			success: true,
@@ -505,11 +505,11 @@ function option(...args) {
 			};
 		},
 		suggest(context, prefix) {
-			if (isAsync) return suggestOptionAsync(optionNames$1, valueParser, options.hidden ?? false, context, prefix);
-			return suggestOptionSync(optionNames$1, valueParser, options.hidden ?? false, context, prefix);
+			if (isAsync) return suggestOptionAsync(optionNames$1, valueParser, require_usage.isSuggestionHidden(options.hidden), context, prefix);
+			return suggestOptionSync(optionNames$1, valueParser, require_usage.isSuggestionHidden(options.hidden), context, prefix);
 		},
 		getDocFragments(_state, defaultValue) {
-			if (options.hidden) return {
+			if (require_usage.isDocHidden(options.hidden)) return {
 				fragments: [],
 				description: options.description
 			};
@@ -583,7 +583,7 @@ function flag(...args) {
 		usage: [{
 			type: "option",
 			names: optionNames$1,
-			...options.hidden && { hidden: true }
+			...options.hidden != null && { hidden: options.hidden }
 		}],
 		initialState: void 0,
 		parse(context) {
@@ -690,7 +690,7 @@ function flag(...args) {
 			};
 		},
 		suggest(_context, prefix) {
-			if (options.hidden) return [];
+			if (require_usage.isSuggestionHidden(options.hidden)) return [];
 			const suggestions = [];
 			if (prefix.startsWith("--") || prefix.startsWith("-") || prefix.startsWith("/")) {
 				for (const optionName$1 of optionNames$1) if (optionName$1.startsWith(prefix)) {
@@ -704,7 +704,7 @@ function flag(...args) {
 			return suggestions;
 		},
 		getDocFragments(_state, _defaultValue) {
-			if (options.hidden) return {
+			if (require_usage.isDocHidden(options.hidden)) return {
 				fragments: [],
 				description: options.description
 			};
@@ -745,7 +745,7 @@ function argument(valueParser, options = {}) {
 	const term = {
 		type: "argument",
 		metavar: valueParser.metavar,
-		...options.hidden && { hidden: true }
+		...options.hidden != null && { hidden: options.hidden }
 	};
 	const result = {
 		$mode: valueParser.$mode,
@@ -833,11 +833,11 @@ function argument(valueParser, options = {}) {
 			};
 		},
 		suggest(context, prefix) {
-			if (isAsync) return suggestArgumentAsync(valueParser, options.hidden ?? false, prefix, context.dependencyRegistry);
-			return suggestArgumentSync(valueParser, options.hidden ?? false, prefix, context.dependencyRegistry);
+			if (isAsync) return suggestArgumentAsync(valueParser, require_usage.isSuggestionHidden(options.hidden), prefix, context.dependencyRegistry);
+			return suggestArgumentSync(valueParser, require_usage.isSuggestionHidden(options.hidden), prefix, context.dependencyRegistry);
 		},
 		getDocFragments(_state, defaultValue) {
-			if (options.hidden) return {
+			if (require_usage.isDocHidden(options.hidden)) return {
 				fragments: [],
 				description: options.description
 			};
@@ -861,7 +861,7 @@ function argument(valueParser, options = {}) {
 	return result;
 }
 function* suggestCommandSync(context, prefix, name, parser, options) {
-	if (options.hidden) return;
+	if (require_usage.isSuggestionHidden(options.hidden)) return;
 	if (context.state === void 0) {
 		if (name.startsWith(prefix)) yield {
 			kind: "literal",
@@ -878,7 +878,7 @@ function* suggestCommandSync(context, prefix, name, parser, options) {
 	}, prefix);
 }
 async function* suggestCommandAsync(context, prefix, name, parser, options) {
-	if (options.hidden) return;
+	if (require_usage.isSuggestionHidden(options.hidden)) return;
 	if (context.state === void 0) {
 		if (name.startsWith(prefix)) yield {
 			kind: "literal",
@@ -923,7 +923,7 @@ function command(name, parser, options = {}) {
 		usage: [{
 			type: "command",
 			name,
-			...options.hidden && { hidden: true }
+			...options.hidden != null && { hidden: options.hidden }
 		}, ...parser.usage],
 		initialState: void 0,
 		parse(context) {
@@ -1023,7 +1023,7 @@ function command(name, parser, options = {}) {
 		},
 		getDocFragments(state, defaultValue) {
 			if (state.kind === "unavailable" || typeof state.state === "undefined") {
-				if (options.hidden) return {
+				if (require_usage.isDocHidden(options.hidden)) return {
 					fragments: [],
 					description: options.description
 				};
@@ -1117,7 +1117,7 @@ function passThrough(options = {}) {
 		priority: -10,
 		usage: [{
 			type: "passthrough",
-			...options.hidden && { hidden: true }
+			...options.hidden != null && { hidden: options.hidden }
 		}],
 		initialState: [],
 		parse(context) {
@@ -1215,7 +1215,7 @@ function passThrough(options = {}) {
 			return [];
 		},
 		getDocFragments(_state, _defaultValue) {
-			if (options.hidden) return {
+			if (require_usage.isDocHidden(options.hidden)) return {
 				fragments: [],
 				description: options.description
 			};

package/dist/primitives.d.cts

@@ -1,5 +1,5 @@
 import { Message } from "./message.cjs";
-import { OptionName } from "./usage.cjs";
+import { HiddenVisibility, OptionName } from "./usage.cjs";
 import { ValueParser, ValueParserResult } from "./valueparser.cjs";
 import { DeferredParseState, PendingDependencySourceState } from "./dependency.cjs";
 import { Mode, Parser } from "./parser.cjs";
@@ -47,12 +47,15 @@ interface OptionOptions {
    */
   readonly description?: Message;
   /**
-   * When `true`, hides the option from help text, shell completion
-   * suggestions, and "Did you mean?" error suggestions. The option
-   * remains fully functional for parsing.
+   * Controls option visibility:
+   *
+   * - `true`: hide from usage, docs, and suggestions
+   * - `"usage"`: hide from usage only
+   * - `"doc"`: hide from docs only
+   *
    * @since 0.9.0
    */
-  readonly hidden?: boolean;
+  readonly hidden?: HiddenVisibility;
   /**
    * Error message customization options.
    * @since 0.5.0
@@ -155,12 +158,15 @@ interface FlagOptions {
    */
   readonly description?: Message;
   /**
-   * When `true`, hides the flag from help text, shell completion
-   * suggestions, and "Did you mean?" error suggestions. The flag
-   * remains fully functional for parsing.
+   * Controls flag visibility:
+   *
+   * - `true`: hide from usage, docs, and suggestions
+   * - `"usage"`: hide from usage only
+   * - `"doc"`: hide from docs only
+   *
    * @since 0.9.0
    */
-  readonly hidden?: boolean;
+  readonly hidden?: HiddenVisibility;
   /**
    * Error message customization options.
    * @since 0.5.0
@@ -241,12 +247,15 @@ interface ArgumentOptions {
    */
   readonly description?: Message;
   /**
-   * When `true`, hides the argument from help text, shell completion
-   * suggestions, and error suggestions. The argument remains fully
-   * functional for parsing.
+   * Controls argument visibility:
+   *
+   * - `true`: hide from usage, docs, and suggestions
+   * - `"usage"`: hide from usage only
+   * - `"doc"`: hide from docs only
+   *
    * @since 0.9.0
    */
-  readonly hidden?: boolean;
+  readonly hidden?: HiddenVisibility;
   /**
    * Error message customization options.
    * @since 0.5.0
@@ -312,12 +321,15 @@ interface CommandOptions {
    */
   readonly footer?: Message;
   /**
-   * When `true`, hides the command from help text, shell completion
-   * suggestions, and "Did you mean?" error suggestions. The command
-   * remains fully functional for parsing.
+   * Controls command visibility:
+   *
+   * - `true`: hide from usage, docs, and suggestions
+   * - `"usage"`: hide from usage only
+   * - `"doc"`: hide from docs only
+   *
    * @since 0.9.0
    */
-  readonly hidden?: boolean;
+  readonly hidden?: HiddenVisibility;
   /**
    * Error messages customization.
    * @since 0.5.0
@@ -396,11 +408,15 @@ interface PassThroughOptions {
    */
   readonly description?: Message;
   /**
-   * When `true`, hides the pass-through from help text and shell
-   * completion suggestions. The parser remains fully functional.
+   * Controls pass-through visibility:
+   *
+   * - `true`: hide from usage, docs, and suggestions
+   * - `"usage"`: hide from usage only
+   * - `"doc"`: hide from docs only
+   *
    * @since 0.9.0
    */
-  readonly hidden?: boolean;
+  readonly hidden?: HiddenVisibility;
 }
 /**
  * Creates a parser that collects unrecognized options and passes them through.

package/dist/primitives.d.ts

@@ -1,5 +1,5 @@
 import { Message } from "./message.js";
-import { OptionName } from "./usage.js";
+import { HiddenVisibility, OptionName } from "./usage.js";
 import { ValueParser, ValueParserResult } from "./valueparser.js";
 import { DeferredParseState, PendingDependencySourceState } from "./dependency.js";
 import { Mode, Parser } from "./parser.js";
@@ -47,12 +47,15 @@ interface OptionOptions {
    */
   readonly description?: Message;
   /**
-   * When `true`, hides the option from help text, shell completion
-   * suggestions, and "Did you mean?" error suggestions. The option
-   * remains fully functional for parsing.
+   * Controls option visibility:
+   *
+   * - `true`: hide from usage, docs, and suggestions
+   * - `"usage"`: hide from usage only
+   * - `"doc"`: hide from docs only
+   *
    * @since 0.9.0
    */
-  readonly hidden?: boolean;
+  readonly hidden?: HiddenVisibility;
   /**
    * Error message customization options.
    * @since 0.5.0
@@ -155,12 +158,15 @@ interface FlagOptions {
    */
   readonly description?: Message;
   /**
-   * When `true`, hides the flag from help text, shell completion
-   * suggestions, and "Did you mean?" error suggestions. The flag
-   * remains fully functional for parsing.
+   * Controls flag visibility:
+   *
+   * - `true`: hide from usage, docs, and suggestions
+   * - `"usage"`: hide from usage only
+   * - `"doc"`: hide from docs only
+   *
    * @since 0.9.0
    */
-  readonly hidden?: boolean;
+  readonly hidden?: HiddenVisibility;
   /**
    * Error message customization options.
    * @since 0.5.0
@@ -241,12 +247,15 @@ interface ArgumentOptions {
    */
   readonly description?: Message;
   /**
-   * When `true`, hides the argument from help text, shell completion
-   * suggestions, and error suggestions. The argument remains fully
-   * functional for parsing.
+   * Controls argument visibility:
+   *
+   * - `true`: hide from usage, docs, and suggestions
+   * - `"usage"`: hide from usage only
+   * - `"doc"`: hide from docs only
+   *
    * @since 0.9.0
    */
-  readonly hidden?: boolean;
+  readonly hidden?: HiddenVisibility;
   /**
    * Error message customization options.
    * @since 0.5.0
@@ -312,12 +321,15 @@ interface CommandOptions {
    */
   readonly footer?: Message;
   /**
-   * When `true`, hides the command from help text, shell completion
-   * suggestions, and "Did you mean?" error suggestions. The command
-   * remains fully functional for parsing.
+   * Controls command visibility:
+   *
+   * - `true`: hide from usage, docs, and suggestions
+   * - `"usage"`: hide from usage only
+   * - `"doc"`: hide from docs only
+   *
    * @since 0.9.0
    */
-  readonly hidden?: boolean;
+  readonly hidden?: HiddenVisibility;
   /**
    * Error messages customization.
    * @since 0.5.0
@@ -396,11 +408,15 @@ interface PassThroughOptions {
    */
   readonly description?: Message;
   /**
-   * When `true`, hides the pass-through from help text and shell
-   * completion suggestions. The parser remains fully functional.
+   * Controls pass-through visibility:
+   *
+   * - `true`: hide from usage, docs, and suggestions
+   * - `"usage"`: hide from usage only
+   * - `"doc"`: hide from docs only
+   *
    * @since 0.9.0
    */
-  readonly hidden?: boolean;
+  readonly hidden?: HiddenVisibility;
 }
 /**
  * Creates a parser that collects unrecognized options and passes them through.

package/dist/primitives.js

@@ -1,6 +1,6 @@
 import { message, metavar, optionName, optionNames, text, valueSet } from "./message.js";
 import { createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, dependencyId, getDefaultValuesFunction, getDependencyIds, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isPendingDependencySourceState, suggestWithDependency } from "./dependency.js";
-import { extractOptionNames } from "./usage.js";
+import { extractOptionNames, isDocHidden, isSuggestionHidden } from "./usage.js";
 import { DEFAULT_FIND_SIMILAR_OPTIONS, createErrorWithSuggestions, createSuggestionMessage, findSimilar } from "./suggestion.js";
 import { extractLeadingCommandNames } from "./usage-internals.js";
 import { isValueParser } from "./valueparser.js";
@@ -313,13 +313,13 @@ function option(...args) {
 			terms: [{
 				type: "option",
 				names: optionNames$1,
-				...options.hidden && { hidden: true }
+				...options.hidden != null && { hidden: options.hidden }
 			}]
 		} : {
 			type: "option",
 			names: optionNames$1,
 			metavar: valueParser.metavar,
-			...options.hidden && { hidden: true }
+			...options.hidden != null && { hidden: options.hidden }
 		}],
 		initialState: valueParser == null ? {
 			success: true,
@@ -505,11 +505,11 @@ function option(...args) {
 			};
 		},
 		suggest(context, prefix) {
-			if (isAsync) return suggestOptionAsync(optionNames$1, valueParser, options.hidden ?? false, context, prefix);
-			return suggestOptionSync(optionNames$1, valueParser, options.hidden ?? false, context, prefix);
+			if (isAsync) return suggestOptionAsync(optionNames$1, valueParser, isSuggestionHidden(options.hidden), context, prefix);
+			return suggestOptionSync(optionNames$1, valueParser, isSuggestionHidden(options.hidden), context, prefix);
 		},
 		getDocFragments(_state, defaultValue) {
-			if (options.hidden) return {
+			if (isDocHidden(options.hidden)) return {
 				fragments: [],
 				description: options.description
 			};
@@ -583,7 +583,7 @@ function flag(...args) {
 		usage: [{
 			type: "option",
 			names: optionNames$1,
-			...options.hidden && { hidden: true }
+			...options.hidden != null && { hidden: options.hidden }
 		}],
 		initialState: void 0,
 		parse(context) {
@@ -690,7 +690,7 @@ function flag(...args) {
 			};
 		},
 		suggest(_context, prefix) {
-			if (options.hidden) return [];
+			if (isSuggestionHidden(options.hidden)) return [];
 			const suggestions = [];
 			if (prefix.startsWith("--") || prefix.startsWith("-") || prefix.startsWith("/")) {
 				for (const optionName$1 of optionNames$1) if (optionName$1.startsWith(prefix)) {
@@ -704,7 +704,7 @@ function flag(...args) {
 			return suggestions;
 		},
 		getDocFragments(_state, _defaultValue) {
-			if (options.hidden) return {
+			if (isDocHidden(options.hidden)) return {
 				fragments: [],
 				description: options.description
 			};
@@ -745,7 +745,7 @@ function argument(valueParser, options = {}) {
 	const term = {
 		type: "argument",
 		metavar: valueParser.metavar,
-		...options.hidden && { hidden: true }
+		...options.hidden != null && { hidden: options.hidden }
 	};
 	const result = {
 		$mode: valueParser.$mode,
@@ -833,11 +833,11 @@ function argument(valueParser, options = {}) {
 			};
 		},
 		suggest(context, prefix) {
-			if (isAsync) return suggestArgumentAsync(valueParser, options.hidden ?? false, prefix, context.dependencyRegistry);
-			return suggestArgumentSync(valueParser, options.hidden ?? false, prefix, context.dependencyRegistry);
+			if (isAsync) return suggestArgumentAsync(valueParser, isSuggestionHidden(options.hidden), prefix, context.dependencyRegistry);
+			return suggestArgumentSync(valueParser, isSuggestionHidden(options.hidden), prefix, context.dependencyRegistry);
 		},
 		getDocFragments(_state, defaultValue) {
-			if (options.hidden) return {
+			if (isDocHidden(options.hidden)) return {
 				fragments: [],
 				description: options.description
 			};
@@ -861,7 +861,7 @@ function argument(valueParser, options = {}) {
 	return result;
 }
 function* suggestCommandSync(context, prefix, name, parser, options) {
-	if (options.hidden) return;
+	if (isSuggestionHidden(options.hidden)) return;
 	if (context.state === void 0) {
 		if (name.startsWith(prefix)) yield {
 			kind: "literal",
@@ -878,7 +878,7 @@ function* suggestCommandSync(context, prefix, name, parser, options) {
 	}, prefix);
 }
 async function* suggestCommandAsync(context, prefix, name, parser, options) {
-	if (options.hidden) return;
+	if (isSuggestionHidden(options.hidden)) return;
 	if (context.state === void 0) {
 		if (name.startsWith(prefix)) yield {
 			kind: "literal",
@@ -923,7 +923,7 @@ function command(name, parser, options = {}) {
 		usage: [{
 			type: "command",
 			name,
-			...options.hidden && { hidden: true }
+			...options.hidden != null && { hidden: options.hidden }
 		}, ...parser.usage],
 		initialState: void 0,
 		parse(context) {
@@ -1023,7 +1023,7 @@ function command(name, parser, options = {}) {
 		},
 		getDocFragments(state, defaultValue) {
 			if (state.kind === "unavailable" || typeof state.state === "undefined") {
-				if (options.hidden) return {
+				if (isDocHidden(options.hidden)) return {
 					fragments: [],
 					description: options.description
 				};
@@ -1117,7 +1117,7 @@ function passThrough(options = {}) {
 		priority: -10,
 		usage: [{
 			type: "passthrough",
-			...options.hidden && { hidden: true }
+			...options.hidden != null && { hidden: options.hidden }
 		}],
 		initialState: [],
 		parse(context) {
@@ -1215,7 +1215,7 @@ function passThrough(options = {}) {
 			return [];
 		},
 		getDocFragments(_state, _defaultValue) {
-			if (options.hidden) return {
+			if (isDocHidden(options.hidden)) return {
 				fragments: [],
 				description: options.description
 			};

package/dist/usage.cjs

@@ -1,6 +1,34 @@
 
 //#region src/usage.ts
 /**
+* Returns whether the term should be hidden from usage output.
+*/
+function isUsageHidden(hidden) {
+	return hidden === true || hidden === "usage";
+}
+/**
+* Returns whether the term should be hidden from documentation output.
+*/
+function isDocHidden(hidden) {
+	return hidden === true || hidden === "doc";
+}
+/**
+* Returns whether the term should be hidden from suggestion/error candidates.
+*/
+function isSuggestionHidden(hidden) {
+	return hidden === true;
+}
+/**
+* Merges two hidden visibility settings by taking the union of restrictions.
+*/
+function mergeHidden(a, b) {
+	if (a == null) return b;
+	if (b == null) return a;
+	if (a === true || b === true) return true;
+	if (a !== b) return true;
+	return a;
+}
+/**
 * Extracts all option names from a usage description.
 *
 * This function recursively traverses a {@link Usage} tree and collects all
@@ -25,7 +53,7 @@ function extractOptionNames(usage) {
 	function traverseUsage(terms) {
 		if (!terms || !Array.isArray(terms)) return;
 		for (const term of terms) if (term.type === "option") {
-			if (term.hidden) continue;
+			if (isSuggestionHidden(term.hidden)) continue;
 			for (const name of term.names) names.add(name);
 		} else if (term.type === "optional" || term.type === "multiple") traverseUsage(term.terms);
 		else if (term.type === "exclusive") for (const exclusiveUsage of term.terms) traverseUsage(exclusiveUsage);
@@ -58,7 +86,7 @@ function extractCommandNames(usage) {
 	function traverseUsage(terms) {
 		if (!terms || !Array.isArray(terms)) return;
 		for (const term of terms) if (term.type === "command") {
-			if (term.hidden) continue;
+			if (isSuggestionHidden(term.hidden)) continue;
 			names.add(term.name);
 		} else if (term.type === "optional" || term.type === "multiple") traverseUsage(term.terms);
 		else if (term.type === "exclusive") for (const exclusiveUsage of term.terms) traverseUsage(exclusiveUsage);
@@ -92,7 +120,7 @@ function extractArgumentMetavars(usage) {
 	function traverseUsage(terms) {
 		if (!terms || !Array.isArray(terms)) return;
 		for (const term of terms) if (term.type === "argument") {
-			if (term.hidden) continue;
+			if (isSuggestionHidden(term.hidden)) continue;
 			metavars.add(term.metavar);
 		} else if (term.type === "optional" || term.type === "multiple") traverseUsage(term.terms);
 		else if (term.type === "exclusive") for (const exclusiveUsage of term.terms) traverseUsage(exclusiveUsage);
@@ -117,14 +145,14 @@ function extractArgumentMetavars(usage) {
 * @returns A formatted string representation of the usage description.
 */
 function formatUsage(programName, usage, options = {}) {
-	usage = normalizeUsage(usage);
+	usage = normalizeUsage(filterUsageForDisplay(usage));
 	if (options.expandCommands) {
 		const lastTerm = usage.at(-1);
 		if (usage.length > 0 && usage.slice(0, -1).every((t) => t.type === "command") && lastTerm.type === "exclusive" && lastTerm.terms.every((t) => t.length > 0 && (t[0].type === "command" || t[0].type === "option" || t[0].type === "argument" || t[0].type === "optional" && t[0].terms.length === 1 && (t[0].terms[0].type === "command" || t[0].terms[0].type === "option" || t[0].terms[0].type === "argument")))) {
 			const lines = [];
 			for (let command of lastTerm.terms) {
 				const firstTerm = command[0];
-				if (firstTerm?.type === "command" && firstTerm.hidden) continue;
+				if (firstTerm?.type === "command" && isUsageHidden(firstTerm.hidden)) continue;
 				if (usage.length > 1) command = [...usage.slice(0, -1), ...command];
 				lines.push(formatUsage(programName, command, options));
 			}
@@ -205,9 +233,47 @@ function normalizeUsageTerm(term) {
 		};
 	} else return term;
 }
+function filterUsageForDisplay(usage) {
+	const terms = [];
+	for (const term of usage) {
+		if ((term.type === "argument" || term.type === "option" || term.type === "command" || term.type === "passthrough") && isUsageHidden(term.hidden)) continue;
+		if (term.type === "optional") {
+			const filtered = filterUsageForDisplay(term.terms);
+			if (filtered.length > 0) terms.push({
+				type: "optional",
+				terms: filtered
+			});
+			continue;
+		}
+		if (term.type === "multiple") {
+			const filtered = filterUsageForDisplay(term.terms);
+			if (filtered.length > 0) terms.push({
+				type: "multiple",
+				terms: filtered,
+				min: term.min
+			});
+			continue;
+		}
+		if (term.type === "exclusive") {
+			const filteredBranches = term.terms.map((branch) => {
+				const first = branch[0];
+				if (first?.type === "command" && isUsageHidden(first.hidden)) return [];
+				return filterUsageForDisplay(branch);
+			}).filter((branch) => branch.length > 0);
+			if (filteredBranches.length > 0) terms.push({
+				type: "exclusive",
+				terms: filteredBranches
+			});
+			continue;
+		}
+		terms.push(term);
+	}
+	return terms;
+}
 function* formatUsageTerms(terms, options) {
 	let i = 0;
 	for (const t of terms) {
+		if ("hidden" in t && (t.type === "argument" || t.type === "option" || t.type === "command" || t.type === "passthrough") && isUsageHidden(t.hidden)) continue;
 		if (i > 0) yield {
 			text: " ",
 			width: 1
@@ -226,9 +292,11 @@ function* formatUsageTerms(terms, options) {
 * @returns A formatted string representation of the usage term.
 */
 function formatUsageTerm(term, options = {}) {
+	const visibleTerms = filterUsageForDisplay([term]);
+	if (visibleTerms.length < 1) return "";
 	let lineWidth = 0;
 	let output = "";
-	for (const { text, width } of formatUsageTermInternal(term, options)) {
+	for (const { text, width } of formatUsageTermInternal(visibleTerms[0], options)) {
 		if (options.maxWidth != null && lineWidth + width > options.maxWidth) {
 			output += "\n";
 			lineWidth = 0;
@@ -356,4 +424,8 @@ exports.extractCommandNames = extractCommandNames;
 exports.extractOptionNames = extractOptionNames;
 exports.formatUsage = formatUsage;
 exports.formatUsageTerm = formatUsageTerm;
+exports.isDocHidden = isDocHidden;
+exports.isSuggestionHidden = isSuggestionHidden;
+exports.isUsageHidden = isUsageHidden;
+exports.mergeHidden = mergeHidden;
 exports.normalizeUsage = normalizeUsage;