@optique/core 1.1.0-dev.2086 → 1.1.0-dev.2096

package/dist/doc.cjs

@@ -497,6 +497,9 @@ function maxVisibleAtomicWidth(usage) {
 				max = Math.max(max, maxVisibleAtomicWidth(branch));
 			}
 			break;
+		case "sequence":
+			max = Math.max(max, maxVisibleAtomicWidth(term.terms));
+			break;
 		case "literal":
 			if (term.value !== "") max = Math.max(max, require_displaywidth.getDisplayWidth(term.value));
 			break;

package/dist/doc.js

@@ -497,6 +497,9 @@ function maxVisibleAtomicWidth(usage) {
 				max = Math.max(max, maxVisibleAtomicWidth(branch));
 			}
 			break;
+		case "sequence":
+			max = Math.max(max, maxVisibleAtomicWidth(term.terms));
+			break;
 		case "literal":
 			if (term.value !== "") max = Math.max(max, getDisplayWidth(term.value));
 			break;

package/dist/facade.cjs

@@ -824,6 +824,7 @@ function collectRootOptionNamesFromTerm(term, names, rootLeadingNames) {
 			return;
 		case "optional":
 		case "multiple":
+		case "sequence":
 			collectRootOptionNames(term.terms, names, rootLeadingNames);
 			return;
 		case "exclusive":
@@ -849,7 +850,7 @@ function collectActiveOptionNames(usage, commandPath, names, fromExclusive, incl
 			if (rest.length === 0) collectOptionNamesAtCurrentCommandDepth(remainingUsage, names, !fromExclusive && includeDirectAfterCommandOptions);
 			else collectActiveOptionNames(remainingUsage, rest, names, fromExclusive, includeDirectAfterCommandOptions);
 		} else if (term.type === "exclusive") for (const branch of term.terms) collectActiveOptionNames(branch, commandPath, names, true, includeDirectAfterCommandOptions);
-		else if (term.type === "optional" || term.type === "multiple") collectActiveOptionNames(term.terms, commandPath, names, fromExclusive, includeDirectAfterCommandOptions);
+		else if (term.type === "optional" || term.type === "multiple" || term.type === "sequence") collectActiveOptionNames(term.terms, commandPath, names, fromExclusive, includeDirectAfterCommandOptions);
 	}
 }
 function isRootOptionToken(token, rootOptionSuggestions) {
@@ -867,6 +868,7 @@ function collectOptionNamesAtCurrentCommandDepthFromTerm(term, names, afterMatch
 			return false;
 		case "optional":
 		case "multiple":
+		case "sequence":
 			collectOptionNamesAtCurrentCommandDepth(term.terms, names, afterMatchedCommand);
 			return false;
 		case "exclusive":

package/dist/facade.js

@@ -824,6 +824,7 @@ function collectRootOptionNamesFromTerm(term, names, rootLeadingNames) {
 			return;
 		case "optional":
 		case "multiple":
+		case "sequence":
 			collectRootOptionNames(term.terms, names, rootLeadingNames);
 			return;
 		case "exclusive":
@@ -849,7 +850,7 @@ function collectActiveOptionNames(usage, commandPath, names, fromExclusive, incl
 			if (rest.length === 0) collectOptionNamesAtCurrentCommandDepth(remainingUsage, names, !fromExclusive && includeDirectAfterCommandOptions);
 			else collectActiveOptionNames(remainingUsage, rest, names, fromExclusive, includeDirectAfterCommandOptions);
 		} else if (term.type === "exclusive") for (const branch of term.terms) collectActiveOptionNames(branch, commandPath, names, true, includeDirectAfterCommandOptions);
-		else if (term.type === "optional" || term.type === "multiple") collectActiveOptionNames(term.terms, commandPath, names, fromExclusive, includeDirectAfterCommandOptions);
+		else if (term.type === "optional" || term.type === "multiple" || term.type === "sequence") collectActiveOptionNames(term.terms, commandPath, names, fromExclusive, includeDirectAfterCommandOptions);
 	}
 }
 function isRootOptionToken(token, rootOptionSuggestions) {
@@ -867,6 +868,7 @@ function collectOptionNamesAtCurrentCommandDepthFromTerm(term, names, afterMatch
 			return false;
 		case "optional":
 		case "multiple":
+		case "sequence":
 			collectOptionNamesAtCurrentCommandDepth(term.terms, names, afterMatchedCommand);
 			return false;
 		case "exclusive":

package/dist/index.cjs

@@ -108,6 +108,7 @@ exports.runWith = require_facade.runWith;
 exports.runWithAsync = require_facade.runWithAsync;
 exports.runWithSync = require_facade.runWithSync;
 exports.semVer = require_valueparser.semVer;
+exports.seq = require_constructs.seq;
 exports.socketAddress = require_valueparser.socketAddress;
 exports.string = require_valueparser.string;
 exports.suggest = require_parser.suggest;

package/dist/index.d.cts

@@ -6,10 +6,10 @@ import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, Doc
 import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, LocaleOptions, MacAddressOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, color, domain, email, fileSize, float, hostname, integer, ip, ipv4, ipv6, isValueParser, json, locale, macAddress, port, portRange, semVer, socketAddress, string, url, uuid } from "./valueparser.cjs";
 import { CombineModes, DocState, ExecutionContext, ExecutionPhase, InferMode, InferValue, Mode, ModeIterable, ModeValue, ParseFrame, Parser, ParserContext, ParserResult, Result, Suggestion, createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./internal/parser.cjs";
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.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 { 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, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, dependency, deriveFrom, deriveFromAsync, deriveFromSync, isDependencySource, isDerivedValueParser } from "./internal/dependency.cjs";
 import { CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.cjs";
 import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.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, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, DeferredMap, DependencyMode, DependencySource, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FlagErrorOptions, FlagOptions, FloatOptions, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createParserContext, deduplicateDocEntries, deduplicateDocFragments, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, passThrough, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, socketAddress, string, suggest, suggestAsync, suggestSync, text, 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, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, DeferredMap, DependencyMode, DependencySource, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FlagErrorOptions, FlagOptions, FloatOptions, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createParserContext, deduplicateDocEntries, deduplicateDocFragments, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, passThrough, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, tuple, url, uuid, value, valueSet, values, withDefault, zsh };

package/dist/index.d.ts

@@ -6,10 +6,10 @@ import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, Doc
 import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, LocaleOptions, MacAddressOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, color, domain, email, fileSize, float, hostname, integer, ip, ipv4, ipv6, isValueParser, json, locale, macAddress, port, portRange, semVer, socketAddress, string, url, uuid } from "./valueparser.js";
 import { CombineModes, DocState, ExecutionContext, ExecutionPhase, InferMode, InferValue, Mode, ModeIterable, ModeValue, ParseFrame, Parser, ParserContext, ParserResult, Result, Suggestion, createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./internal/parser.js";
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.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 { 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, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, dependency, deriveFrom, deriveFromAsync, deriveFromSync, isDependencySource, isDerivedValueParser } from "./internal/dependency.js";
 import { CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
 import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.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, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, DeferredMap, DependencyMode, DependencySource, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FlagErrorOptions, FlagOptions, FloatOptions, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createParserContext, deduplicateDocEntries, deduplicateDocFragments, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, passThrough, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, socketAddress, string, suggest, suggestAsync, suggestSync, text, 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, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, DeferredMap, DependencyMode, DependencySource, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FlagErrorOptions, FlagOptions, FloatOptions, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createParserContext, deduplicateDocEntries, deduplicateDocFragments, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, passThrough, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, tuple, url, uuid, value, valueSet, values, withDefault, zsh };

package/dist/index.js

@@ -5,11 +5,11 @@ import { cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandName
 import { cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage, isDocEntryHidden } from "./doc.js";
 import { dependency, deriveFrom, deriveFromAsync, deriveFromSync, isDependencySource, isDerivedValueParser } from "./internal/dependency.js";
 import { createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./internal/parser.js";
-import { DuplicateOptionError, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
+import { DuplicateOptionError, concat, conditional, group, longestMatch, merge, object, or, seq, tuple } from "./constructs.js";
 import { WithDefaultError, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
 import { ensureNonEmptyString, isNonEmptyString } from "./nonempty.js";
 import { checkBooleanOption, checkEnumOption, choice, cidr, color, domain, email, fileSize, float, hostname, integer, ip, ipv4, ipv6, isValueParser, json, locale, macAddress, port, portRange, semVer, socketAddress, string, url, uuid } from "./valueparser.js";
 import { argument, command, constant, fail, flag, negatableFlag, option, passThrough } from "./primitives.js";
 import { RunParserError, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
 
-export { DuplicateOptionError, RunParserError, WithDefaultError, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createParserContext, deduplicateDocEntries, deduplicateDocFragments, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, passThrough, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, socketAddress, string, suggest, suggestAsync, suggestSync, text, tuple, url, uuid, value, valueSet, values, withDefault, zsh };
+export { DuplicateOptionError, RunParserError, WithDefaultError, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createParserContext, deduplicateDocEntries, deduplicateDocFragments, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, passThrough, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, tuple, url, uuid, value, valueSet, values, withDefault, zsh };

package/dist/internal/parser.cjs

@@ -501,14 +501,63 @@ function findCommandInExclusive(term, commandName) {
 	if (term.type !== "exclusive") return null;
 	for (const termGroup of term.terms) {
 		const firstTerm = termGroup[0];
-		if (firstTerm?.type === "command" && firstTerm.name === commandName) return termGroup;
-		if (firstTerm?.type === "exclusive") {
-			const found = findCommandInExclusive(firstTerm, commandName);
-			if (found) return [...found, ...termGroup.slice(1)];
-		}
+		if (firstTerm == null) continue;
+		const found = findCommandInCurrentUsageTerm(firstTerm, commandName, termGroup.slice(1));
+		if (found) return found;
+	}
+	return null;
+}
+/**
+* Searches for a command inside an ordered usage sequence and returns the
+* usage from the matched command onward.  This lets contextual command
+* documentation enter sequence terms while dropping sequence prefixes that
+* were skipped by parsing, such as optional positionals before a subcommand.
+*
+* @param usage The usage terms to search.
+* @param commandName The command name to find.
+* @returns The contextual usage terms if found, null otherwise.
+*/
+function findCommandInUsageSequence(usage, commandName) {
+	for (let index = 0; index < usage.length; index++) {
+		const found = findCommandInCurrentUsageTerm(usage[index], commandName, usage.slice(index + 1));
+		if (found) return found;
+	}
+	return null;
+}
+/**
+* Searches the current usage term for a command and appends the trailing
+* usage terms that remain valid after that current term.
+*
+* @param term The current usage term to search.
+* @param commandName The command name to find.
+* @param trailingUsage Usage terms that follow the current term.
+* @returns The contextual usage terms if found, null otherwise.
+*/
+function findCommandInCurrentUsageTerm(term, commandName, trailingUsage) {
+	if (term.type === "command" && term.name === commandName) return [term, ...trailingUsage];
+	if (term.type === "exclusive") {
+		const found = findCommandInExclusive(term, commandName);
+		if (found) return [...found, ...trailingUsage];
+	} else if (term.type === "sequence") {
+		const found = findCommandInUsageSequence(term.terms, commandName);
+		if (found) return [...found, ...trailingUsage];
 	}
 	return null;
 }
+function recordMatchedCommandArgIndices(consumed, previousCommandPath, nextCommandPath, consumedOffset, indices) {
+	const previousLength = previousCommandPath?.length ?? 0;
+	const next = nextCommandPath ?? [];
+	if (next.length <= previousLength || consumed.length < 1) return;
+	let searchEnd = consumed.length;
+	for (let index = next.length - 1; index >= previousLength; index--) {
+		if (searchEnd <= 0) break;
+		const commandName = next[index];
+		const localIndex = consumed.lastIndexOf(commandName, searchEnd - 1);
+		if (localIndex < 0) continue;
+		indices.add(consumedOffset + localIndex);
+		searchEnd = localIndex;
+	}
+}
 /**
 * Generates a documentation page for a synchronous parser.
 *
@@ -579,14 +628,18 @@ function getDocPageSyncImpl(parser, args, options) {
 		state: initialState,
 		optionsTerminated: false
 	}, exec);
+	const matchedCommandArgIndices = /* @__PURE__ */ new Set();
 	while (context.buffer.length > 0) {
 		const result = parser.parse(context);
 		if (!result.success) break;
+		const previousCommandPath = context.exec?.commandPath;
 		const previousBuffer = context.buffer;
 		context = result.next;
+		const consumedCount = previousBuffer.length - context.buffer.length;
+		recordMatchedCommandArgIndices(previousBuffer.slice(0, consumedCount), previousCommandPath, context.exec?.commandPath, args.length - previousBuffer.length, matchedCommandArgIndices);
 		if (isBufferUnchanged(previousBuffer, context.buffer)) break;
 	}
-	return buildDocPage(parser, context, args);
+	return buildDocPage(parser, context, args, matchedCommandArgIndices);
 }
 /**
 * Internal async implementation of getDocPage.
@@ -604,20 +657,24 @@ async function getDocPageAsyncImpl(parser, args, options) {
 		state: initialState,
 		optionsTerminated: false
 	}, exec);
+	const matchedCommandArgIndices = /* @__PURE__ */ new Set();
 	while (context.buffer.length > 0) {
 		const result = await parser.parse(context);
 		if (!result.success) break;
+		const previousCommandPath = context.exec?.commandPath;
 		const previousBuffer = context.buffer;
 		context = result.next;
+		const consumedCount = previousBuffer.length - context.buffer.length;
+		recordMatchedCommandArgIndices(previousBuffer.slice(0, consumedCount), previousCommandPath, context.exec?.commandPath, args.length - previousBuffer.length, matchedCommandArgIndices);
 		if (isBufferUnchanged(previousBuffer, context.buffer)) break;
 	}
-	return buildDocPage(parser, context, args);
+	return buildDocPage(parser, context, args, matchedCommandArgIndices);
 }
 /**
 * Builds a DocPage from the parser and context.
 * Shared by both sync and async implementations.
 */
-function buildDocPage(parser, context, args) {
+function buildDocPage(parser, context, args, matchedCommandArgIndices) {
 	let effectiveArgs = args;
 	let { brief, description, fragments, footer } = parser.getDocFragments({
 		kind: "available",
@@ -675,19 +732,25 @@ function buildDocPage(parser, context, args) {
 		usage.splice(usageIndex + 1, usage.length - (usageIndex + 1), ...normalizedCustomUsageLine);
 	};
 	let i = 0;
+	const consumedArgsCount = Math.max(0, effectiveArgs.length - context.buffer.length);
+	const commandArgIndices = args.length > 0 ? matchedCommandArgIndices : null;
 	for (let argIndex = 0; argIndex < effectiveArgs.length; argIndex++) {
 		const arg = effectiveArgs[argIndex];
 		if (i >= usage.length) break;
 		let term = usage[i];
-		if (term.type === "exclusive") {
-			const found = findCommandInExclusive(term, arg);
-			if (found) {
-				usage.splice(i, 1, ...found);
-				term = usage[i];
-			}
+		const canSearchCommand = commandArgIndices == null || commandArgIndices.has(argIndex);
+		if (!canSearchCommand) continue;
+		let found = null;
+		for (let searchIndex = i; searchIndex < usage.length; searchIndex++) {
+			found = findCommandInCurrentUsageTerm(usage[searchIndex], arg, usage.slice(searchIndex + 1));
+			if (found != null) break;
+		}
+		if (found) {
+			usage.splice(i, usage.length - i, ...found);
+			term = usage[i];
 		}
 		maybeApplyCommandUsageLine(term, arg, argIndex === effectiveArgs.length - 1, i);
-		i++;
+		if (found != null || term.type !== "sequence" || argIndex >= consumedArgsCount) i++;
 	}
 	if (effectiveArgs.length === 0 && usage.length > 0) {
 		const first = usage[0];

package/dist/internal/parser.d.cts

@@ -143,6 +143,20 @@ interface Parser<M extends Mode = "sync", TValue = unknown, TState = unknown> {
    * @since 1.0.0
    */
   readonly acceptingAnyToken: boolean;
+  /**
+   * Returns whether this parser can be skipped at the current state without
+   * consuming more CLI input or evaluating completion-time defaults.
+   *
+   * Sequential combinators use this as a lightweight boundary predicate.  It
+   * must be synchronous and side-effect free.  Custom parsers that omit this
+   * method are treated as not skippable.
+   *
+   * @param state The current parser state.
+   * @param exec Optional shared execution context.
+   * @returns `true` when parsing may advance past this parser.
+   * @since 1.1.0
+   */
+  canSkip?(state: TState, exec?: ExecutionContext): boolean;
   /**
    * The initial state for this parser.  This is used to initialize the
    * state when parsing starts.

package/dist/internal/parser.d.ts

@@ -143,6 +143,20 @@ interface Parser<M extends Mode = "sync", TValue = unknown, TState = unknown> {
    * @since 1.0.0
    */
   readonly acceptingAnyToken: boolean;
+  /**
+   * Returns whether this parser can be skipped at the current state without
+   * consuming more CLI input or evaluating completion-time defaults.
+   *
+   * Sequential combinators use this as a lightweight boundary predicate.  It
+   * must be synchronous and side-effect free.  Custom parsers that omit this
+   * method are treated as not skippable.
+   *
+   * @param state The current parser state.
+   * @param exec Optional shared execution context.
+   * @returns `true` when parsing may advance past this parser.
+   * @since 1.1.0
+   */
+  canSkip?(state: TState, exec?: ExecutionContext): boolean;
   /**
    * The initial state for this parser.  This is used to initialize the
    * state when parsing starts.

package/dist/internal/parser.js

@@ -501,14 +501,63 @@ function findCommandInExclusive(term, commandName) {
 	if (term.type !== "exclusive") return null;
 	for (const termGroup of term.terms) {
 		const firstTerm = termGroup[0];
-		if (firstTerm?.type === "command" && firstTerm.name === commandName) return termGroup;
-		if (firstTerm?.type === "exclusive") {
-			const found = findCommandInExclusive(firstTerm, commandName);
-			if (found) return [...found, ...termGroup.slice(1)];
-		}
+		if (firstTerm == null) continue;
+		const found = findCommandInCurrentUsageTerm(firstTerm, commandName, termGroup.slice(1));
+		if (found) return found;
+	}
+	return null;
+}
+/**
+* Searches for a command inside an ordered usage sequence and returns the
+* usage from the matched command onward.  This lets contextual command
+* documentation enter sequence terms while dropping sequence prefixes that
+* were skipped by parsing, such as optional positionals before a subcommand.
+*
+* @param usage The usage terms to search.
+* @param commandName The command name to find.
+* @returns The contextual usage terms if found, null otherwise.
+*/
+function findCommandInUsageSequence(usage, commandName) {
+	for (let index = 0; index < usage.length; index++) {
+		const found = findCommandInCurrentUsageTerm(usage[index], commandName, usage.slice(index + 1));
+		if (found) return found;
+	}
+	return null;
+}
+/**
+* Searches the current usage term for a command and appends the trailing
+* usage terms that remain valid after that current term.
+*
+* @param term The current usage term to search.
+* @param commandName The command name to find.
+* @param trailingUsage Usage terms that follow the current term.
+* @returns The contextual usage terms if found, null otherwise.
+*/
+function findCommandInCurrentUsageTerm(term, commandName, trailingUsage) {
+	if (term.type === "command" && term.name === commandName) return [term, ...trailingUsage];
+	if (term.type === "exclusive") {
+		const found = findCommandInExclusive(term, commandName);
+		if (found) return [...found, ...trailingUsage];
+	} else if (term.type === "sequence") {
+		const found = findCommandInUsageSequence(term.terms, commandName);
+		if (found) return [...found, ...trailingUsage];
 	}
 	return null;
 }
+function recordMatchedCommandArgIndices(consumed, previousCommandPath, nextCommandPath, consumedOffset, indices) {
+	const previousLength = previousCommandPath?.length ?? 0;
+	const next = nextCommandPath ?? [];
+	if (next.length <= previousLength || consumed.length < 1) return;
+	let searchEnd = consumed.length;
+	for (let index = next.length - 1; index >= previousLength; index--) {
+		if (searchEnd <= 0) break;
+		const commandName = next[index];
+		const localIndex = consumed.lastIndexOf(commandName, searchEnd - 1);
+		if (localIndex < 0) continue;
+		indices.add(consumedOffset + localIndex);
+		searchEnd = localIndex;
+	}
+}
 /**
 * Generates a documentation page for a synchronous parser.
 *
@@ -579,14 +628,18 @@ function getDocPageSyncImpl(parser, args, options) {
 		state: initialState,
 		optionsTerminated: false
 	}, exec);
+	const matchedCommandArgIndices = /* @__PURE__ */ new Set();
 	while (context.buffer.length > 0) {
 		const result = parser.parse(context);
 		if (!result.success) break;
+		const previousCommandPath = context.exec?.commandPath;
 		const previousBuffer = context.buffer;
 		context = result.next;
+		const consumedCount = previousBuffer.length - context.buffer.length;
+		recordMatchedCommandArgIndices(previousBuffer.slice(0, consumedCount), previousCommandPath, context.exec?.commandPath, args.length - previousBuffer.length, matchedCommandArgIndices);
 		if (isBufferUnchanged(previousBuffer, context.buffer)) break;
 	}
-	return buildDocPage(parser, context, args);
+	return buildDocPage(parser, context, args, matchedCommandArgIndices);
 }
 /**
 * Internal async implementation of getDocPage.
@@ -604,20 +657,24 @@ async function getDocPageAsyncImpl(parser, args, options) {
 		state: initialState,
 		optionsTerminated: false
 	}, exec);
+	const matchedCommandArgIndices = /* @__PURE__ */ new Set();
 	while (context.buffer.length > 0) {
 		const result = await parser.parse(context);
 		if (!result.success) break;
+		const previousCommandPath = context.exec?.commandPath;
 		const previousBuffer = context.buffer;
 		context = result.next;
+		const consumedCount = previousBuffer.length - context.buffer.length;
+		recordMatchedCommandArgIndices(previousBuffer.slice(0, consumedCount), previousCommandPath, context.exec?.commandPath, args.length - previousBuffer.length, matchedCommandArgIndices);
 		if (isBufferUnchanged(previousBuffer, context.buffer)) break;
 	}
-	return buildDocPage(parser, context, args);
+	return buildDocPage(parser, context, args, matchedCommandArgIndices);
 }
 /**
 * Builds a DocPage from the parser and context.
 * Shared by both sync and async implementations.
 */
-function buildDocPage(parser, context, args) {
+function buildDocPage(parser, context, args, matchedCommandArgIndices) {
 	let effectiveArgs = args;
 	let { brief, description, fragments, footer } = parser.getDocFragments({
 		kind: "available",
@@ -675,19 +732,25 @@ function buildDocPage(parser, context, args) {
 		usage.splice(usageIndex + 1, usage.length - (usageIndex + 1), ...normalizedCustomUsageLine);
 	};
 	let i = 0;
+	const consumedArgsCount = Math.max(0, effectiveArgs.length - context.buffer.length);
+	const commandArgIndices = args.length > 0 ? matchedCommandArgIndices : null;
 	for (let argIndex = 0; argIndex < effectiveArgs.length; argIndex++) {
 		const arg = effectiveArgs[argIndex];
 		if (i >= usage.length) break;
 		let term = usage[i];
-		if (term.type === "exclusive") {
-			const found = findCommandInExclusive(term, arg);
-			if (found) {
-				usage.splice(i, 1, ...found);
-				term = usage[i];
-			}
+		const canSearchCommand = commandArgIndices == null || commandArgIndices.has(argIndex);
+		if (!canSearchCommand) continue;
+		let found = null;
+		for (let searchIndex = i; searchIndex < usage.length; searchIndex++) {
+			found = findCommandInCurrentUsageTerm(usage[searchIndex], arg, usage.slice(searchIndex + 1));
+			if (found != null) break;
+		}
+		if (found) {
+			usage.splice(i, usage.length - i, ...found);
+			term = usage[i];
 		}
 		maybeApplyCommandUsageLine(term, arg, argIndex === effectiveArgs.length - 1, i);
-		i++;
+		if (found != null || term.type !== "sequence" || argIndex >= consumedArgsCount) i++;
 	}
 	if (effectiveArgs.length === 0 && usage.length > 0) {
 		const first = usage[0];

package/dist/modifiers.cjs

@@ -12,6 +12,11 @@ function isTerminalMultipleItemState(state) {
 	const unwrapped = unwrapMultipleItemState(state).value;
 	return unwrapped != null && typeof unwrapped === "object" && Object.hasOwn(unwrapped, "success") && typeof unwrapped.success === "boolean";
 }
+function isMatchedCommandParserState(parser, state) {
+	if (Reflect.get(parser, Symbol.for("@optique/core/commandParser")) !== true) return false;
+	const unwrapped = unwrapMultipleItemState(state).value;
+	return Array.isArray(unwrapped) && unwrapped.length === 2 && unwrapped[0] === "matched" && typeof unwrapped[1] === "string";
+}
 function isUnstartedMultipleItemState(state, originalState) {
 	const unwrappedState = unwrapMultipleItemState(state);
 	if (unwrappedState.value == null) return true;
@@ -320,6 +325,11 @@ function optional(parser) {
 		leadingNames: parser.leadingNames,
 		acceptingAnyToken: false,
 		initialState: void 0,
+		canSkip(state, exec) {
+			if (!Array.isArray(state)) return true;
+			const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
+			return parser.canSkip?.(innerState, exec) === true;
+		},
 		...typeof parser.shouldDeferCompletion === "function" ? { shouldDeferCompletion: adaptShouldDeferCompletion(parser.shouldDeferCompletion.bind(parser), parser) } : {},
 		getSuggestRuntimeNodes(state, path) {
 			if (optionalParser.dependencyMetadata?.source != null) return [{
@@ -488,6 +498,11 @@ function withDefault(parser, defaultValue, options) {
 		leadingNames: parser.leadingNames,
 		acceptingAnyToken: false,
 		initialState: void 0,
+		canSkip(state, exec) {
+			if (!Array.isArray(state)) return true;
+			const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
+			return parser.canSkip?.(innerState, exec) === true;
+		},
 		...typeof parser.shouldDeferCompletion === "function" ? { shouldDeferCompletion: adaptShouldDeferCompletion(parser.shouldDeferCompletion.bind(parser), parser) } : {},
 		getSuggestRuntimeNodes(state, path) {
 			if (withDefaultParser.dependencyMetadata?.source != null) return [{
@@ -926,9 +941,11 @@ function multiple(parser, options = {}) {
 		parser,
 		state
 	}] : []);
+	const canExtendMultipleItem = (state, itemIndex, exec) => state != null && !isTerminalMultipleItemState(state) && (isMatchedCommandParserState(parser, state) || parser.canSkip?.(state, require_execution_context.withChildExecPath(exec, itemIndex)) !== true);
 	const parseSync = (context) => {
 		const currentItemState = context.state.at(-1);
-		const canExtendCurrent = currentItemState != null && !isTerminalMultipleItemState(currentItemState);
+		const currentItemIndex = context.state.length - 1;
+		const canExtendCurrent = canExtendMultipleItem(currentItemState, currentItemIndex, context.exec);
 		const canOpenFreshItem = context.state.length < max;
 		if (!canExtendCurrent && !canOpenFreshItem) return {
 			success: true,
@@ -1008,7 +1025,8 @@ function multiple(parser, options = {}) {
 	};
 	const parseAsync = async (context) => {
 		const currentItemState = context.state.at(-1);
-		const canExtendCurrent = currentItemState != null && !isTerminalMultipleItemState(currentItemState);
+		const currentItemIndex = context.state.length - 1;
+		const canExtendCurrent = canExtendMultipleItem(currentItemState, currentItemIndex, context.exec);
 		const canOpenFreshItem = context.state.length < max;
 		if (!canExtendCurrent && !canOpenFreshItem) return {
 			success: true,
@@ -1099,6 +1117,11 @@ function multiple(parser, options = {}) {
 		leadingNames: parser.leadingNames,
 		acceptingAnyToken: min > 0 && (parser.acceptingAnyToken ?? false),
 		initialState: [],
+		canSkip(state, exec) {
+			if (state.length < min) return false;
+			const currentItemState = state.at(-1);
+			return !canExtendMultipleItem(currentItemState, state.length - 1, exec);
+		},
 		getSuggestRuntimeNodes(state, path) {
 			const innerNodes = state.flatMap((item, i) => [...getInnerSuggestRuntimeNodes(item, [...path, i])]);
 			return resultParser.dependencyMetadata?.source != null ? [{
@@ -1198,7 +1221,8 @@ function multiple(parser, options = {}) {
 		},
 		suggest(context, prefix) {
 			const currentItemState = context.state.at(-1);
-			const canExtendCurrent = currentItemState != null && !isTerminalMultipleItemState(currentItemState);
+			const currentItemIndex = context.state.length - 1;
+			const canExtendCurrent = canExtendMultipleItem(currentItemState, currentItemIndex, context.exec);
 			const canOpenNew = context.state.length < max;
 			if (!canExtendCurrent && !canOpenNew) return require_mode_dispatch.dispatchIterableByMode(parser.mode, function* () {}, async function* () {});
 			const itemIndex = canExtendCurrent ? context.state.length - 1 : context.state.length;
@@ -1484,6 +1508,7 @@ function multiple(parser, options = {}) {
 */
 function nonEmpty(parser) {
 	const syncParser = parser;
+	const initialState = parser.initialState;
 	const processNonEmptyResult = (result) => {
 		if (!result.success) return result;
 		if (result.consumed.length === 0) return {
@@ -1509,7 +1534,12 @@ function nonEmpty(parser) {
 		usage: parser.usage,
 		leadingNames: parser.leadingNames,
 		acceptingAnyToken: parser.acceptingAnyToken,
-		initialState: parser.initialState,
+		initialState,
+		...typeof parser.canSkip === "function" ? { canSkip(state, exec) {
+			const unwrappedState = require_annotations.unwrapInjectedAnnotationWrapper(state);
+			if (unwrappedState === initialState) return false;
+			return parser.canSkip?.(unwrappedState, exec) === true;
+		} } : {},
 		...typeof parser.shouldDeferCompletion === "function" ? { shouldDeferCompletion: parser.shouldDeferCompletion.bind(parser) } : {},
 		getSuggestRuntimeNodes(state, path) {
 			return parser.getSuggestRuntimeNodes?.(state, path) ?? (parser.dependencyMetadata?.source != null ? [{