@optique/core 1.1.0-dev.2087 → 1.1.0-dev.2146

package/dist/constructs.cjs

@@ -1,13 +1,14 @@
-const require_annotations = require('./internal/annotations.cjs');
+const require_internal_annotations = require('./internal/annotations.cjs');
 const require_message = require('./message.cjs');
 const require_validate = require('./validate.cjs');
 const require_usage = require('./usage.cjs');
 const require_doc = require('./doc.cjs');
 const require_mode_dispatch = require('./internal/mode-dispatch.cjs');
-const require_dependency = require('./internal/dependency.cjs');
+const require_internal_dependency = require('./internal/dependency.cjs');
 const require_dependency_runtime = require('./dependency-runtime.cjs');
-const require_parser = require('./internal/parser.cjs');
+const require_internal_parser = require('./internal/parser.cjs');
 const require_annotation_state = require('./annotation-state.cjs');
+const require_command_alias = require('./internal/command-alias.cjs');
 const require_execution_context = require('./execution-context.cjs');
 const require_phase2_seed = require('./phase2-seed.cjs');
 const require_suggestion = require('./suggestion.cjs');
@@ -20,7 +21,7 @@ const require_usage_internals = require('./usage-internals.cjs');
 */
 const EMPTY_LEADING_NAMES = /* @__PURE__ */ new Set();
 function isNonCliBoundSourceState(state, parser) {
-	return parser[require_parser.unmatchedNonCliDependencySourceStateMarker] === true && state != null && typeof state === "object" && Object.hasOwn(state, "hasCliValue") && state.hasCliValue === false;
+	return parser[require_internal_parser.unmatchedNonCliDependencySourceStateMarker] === true && state != null && typeof state === "object" && Object.hasOwn(state, "hasCliValue") && state.hasCliValue === false;
 }
 function withDependencyRuntimeExec(usage, exec, runtime) {
 	if (exec == null) return {
@@ -43,8 +44,8 @@ function withChildContext$1(context, segment, state, parser, usage) {
 }
 function isUnmatchedDependencyState(state, parser) {
 	if (state === void 0) return true;
-	if (Array.isArray(state) && state.length === 1 && require_dependency.isPendingDependencySourceState(state[0])) return true;
-	if (require_dependency.isPendingDependencySourceState(state)) return true;
+	if (Array.isArray(state) && state.length === 1 && require_internal_dependency.isPendingDependencySourceState(state[0])) return true;
+	if (require_internal_dependency.isPendingDependencySourceState(state)) return true;
 	if (isNonCliBoundSourceState(state, parser)) return true;
 	return state === parser.initialState;
 }
@@ -61,7 +62,7 @@ function buildIndexedParserPairs(parsers) {
 }
 function createAnnotatedArrayStateRecord(stateArray) {
 	const stateRecord = Object.fromEntries(stateArray.map((state, index) => [String(index), state]));
-	return require_annotations.inheritAnnotations(stateArray, stateRecord);
+	return require_internal_annotations.inheritAnnotations(stateArray, stateRecord);
 }
 /**
 * Computes the union of `leadingNames` from all given parsers.
@@ -173,7 +174,7 @@ function unwrapNestedAnnotationViews(value, seen = /* @__PURE__ */ new WeakMap()
 	return clone;
 }
 function unwrapCompleteResult(result) {
-	const unwrappedResult = require_dependency.isDependencySourceState(result) ? result.result : result;
+	const unwrappedResult = require_internal_dependency.isDependencySourceState(result) ? result.result : result;
 	if (!unwrappedResult.success || !containsAnnotationView(unwrappedResult.value)) return unwrappedResult;
 	const value = unwrapNestedAnnotationViews(unwrappedResult.value);
 	return value === unwrappedResult.value ? unwrappedResult : {
@@ -257,8 +258,8 @@ function combineTuplePhase2Seeds(first, second) {
 */
 function prepareStateForCompletion(fieldState, parser) {
 	if (fieldState !== void 0) return fieldState;
-	if (require_dependency.isPendingDependencySourceState(parser.initialState)) return [parser.initialState];
-	if (require_dependency.isWrappedDependencySource(parser)) return [parser[require_dependency.wrappedDependencySourceMarker]];
+	if (require_internal_dependency.isPendingDependencySourceState(parser.initialState)) return [parser.initialState];
+	if (require_internal_dependency.isWrappedDependencySource(parser)) return [parser[require_internal_dependency.wrappedDependencySourceMarker]];
 	return fieldState;
 }
 /**
@@ -281,7 +282,7 @@ function buildSuggestRuntimeNodesFromPairs(pairs, state, parentPath) {
 	const nodes = [];
 	for (const [field, parser] of pairs) {
 		const fieldState = Object.hasOwn(state, field) ? state[field] : parser.initialState;
-		nodes.push(...require_parser.getParserSuggestRuntimeNodes(parser, require_annotation_state.getWrappedChildState(state, fieldState, parser), [...prefix, field]));
+		nodes.push(...require_internal_parser.getParserSuggestRuntimeNodes(parser, require_annotation_state.getWrappedChildState(state, fieldState, parser), [...prefix, field]));
 	}
 	return nodes;
 }
@@ -291,7 +292,7 @@ function buildSuggestRuntimeNodesFromArray(parsers, stateArray, parentPath) {
 	for (let i = 0; i < parsers.length; i++) {
 		const parser = parsers[i];
 		const elementState = i < stateArray.length ? stateArray[i] : void 0;
-		nodes.push(...require_parser.getParserSuggestRuntimeNodes(parser, require_annotation_state.getWrappedChildState(stateArray, elementState, parser), [...prefix, i]));
+		nodes.push(...require_internal_parser.getParserSuggestRuntimeNodes(parser, require_annotation_state.getWrappedChildState(stateArray, elementState, parser), [...prefix, i]));
 	}
 	return nodes;
 }
@@ -301,7 +302,12 @@ function createUnexpectedInputErrorWithScopedSuggestions(baseError, invalidInput
 	for (const parser of parsers) require_usage_internals.collectLeadingCandidates(parser.usage, options, commands);
 	const candidates = new Set([...options, ...commands]);
 	const suggestions = require_suggestion.findSimilar(invalidInput, candidates, require_suggestion.DEFAULT_FIND_SIMILAR_OPTIONS);
-	const suggestionMsg = customFormatter ? customFormatter(suggestions) : require_suggestion.createSuggestionMessage(suggestions);
+	const aliasUsage = [{
+		type: "exclusive",
+		terms: parsers.map((parser) => parser.usage)
+	}];
+	const displaySuggestions = require_suggestion.expandCommandAliasSuggestions(aliasUsage, suggestions);
+	const suggestionMsg = customFormatter ? customFormatter(displaySuggestions) : require_suggestion.createSuggestionMessage(displaySuggestions);
 	return suggestionMsg.length > 0 ? [
 		...baseError,
 		require_message.text("\n\n"),
@@ -319,6 +325,10 @@ function applyHiddenToUsageTerm(term, hidden) {
 		terms: applyHiddenToUsage(term.terms, hidden),
 		min: term.min
 	};
+	if (term.type === "sequence") return {
+		type: "sequence",
+		terms: applyHiddenToUsage(term.terms, hidden)
+	};
 	if (term.type === "exclusive") return {
 		type: "exclusive",
 		terms: term.terms.map((u) => applyHiddenToUsage(u, hidden))
@@ -374,7 +384,7 @@ function isOptionRequiringValue(usage, token) {
 		if (!terms || !Array.isArray(terms)) return false;
 		for (const term of terms) if (term.type === "option") {
 			if (term.metavar && term.names.includes(token)) return true;
-		} else if (term.type === "optional" || term.type === "multiple") {
+		} else if (term.type === "optional" || term.type === "multiple" || term.type === "sequence") {
 			if (traverse(term.terms)) return true;
 		} else if (term.type === "exclusive") {
 			for (const exclusiveUsage of term.terms) if (traverse(exclusiveUsage)) return true;
@@ -453,6 +463,18 @@ var DuplicateOptionError = class extends Error {
 	}
 };
 /**
+* Error class thrown when duplicate command names or aliases are detected
+* during parser construction. This is a programmer error, not a user error.
+*/
+var DuplicateCommandNameError = class extends TypeError {
+	constructor(commandName, sources) {
+		const sourceNames = sources.map((s) => typeof s === "symbol" ? s.description ?? s.toString() : s);
+		super(`Duplicate command name "${commandName}" found in parsers: ${sourceNames.join(", ")}. Each command name or alias must be unique within active parser alternatives.`);
+		this.commandName = commandName;
+		this.sources = sources;
+	}
+};
+/**
 * Checks for duplicate option names across parser sources and throws an error
 * if duplicates are found. This should be called at construction time.
 * @param parserSources Array of [source, usage] tuples
@@ -469,6 +491,48 @@ function checkDuplicateOptionNames(parserSources) {
 	}
 	for (const [name, sources] of optionNameSources) if (sources.length > 1) throw new DuplicateOptionError(name, sources);
 }
+function checkDuplicateLeadingCommandNames(parserSources) {
+	const commandNameSources = /* @__PURE__ */ new Map();
+	for (const [source, parser] of parserSources) {
+		const commandNames = require_usage.extractCommandNames(parser.usage, true);
+		for (const name of parser.leadingNames) {
+			if (!commandNames.has(name)) continue;
+			const sources = commandNameSources.get(name);
+			commandNameSources.set(name, sources == null ? [source] : [...sources, source]);
+		}
+	}
+	for (const [name, sources] of commandNameSources) if (sources.length > 1) throw new DuplicateCommandNameError(name, sources);
+}
+function checkDuplicateReachableLeadingCommandNames(parserSources) {
+	const commandNameSources = /* @__PURE__ */ new Map();
+	const sortedSources = [...parserSources].sort(([, parserA], [, parserB]) => parserB.priority - parserA.priority);
+	const blockedNames = /* @__PURE__ */ new Set();
+	let positionalBlocked = false;
+	for (let i = 0; i < sortedSources.length;) {
+		const priority = sortedSources[i][1].priority;
+		const priorityGroup = [];
+		while (i < sortedSources.length && sortedSources[i][1].priority === priority) {
+			priorityGroup.push(sortedSources[i]);
+			i++;
+		}
+		const groupNames = /* @__PURE__ */ new Set();
+		let groupAcceptsAnyToken = false;
+		for (const [source, parser] of priorityGroup) {
+			if (parser.acceptingAnyToken) groupAcceptsAnyToken = true;
+			const commandNames = require_usage.extractCommandNames(parser.usage, true);
+			for (const name of parser.leadingNames) {
+				if (!commandNames.has(name)) continue;
+				if (positionalBlocked || blockedNames.has(name)) continue;
+				groupNames.add(name);
+				const sources = commandNameSources.get(name);
+				commandNameSources.set(name, sources == null ? [source] : [...sources, source]);
+			}
+		}
+		for (const name of groupNames) blockedNames.add(name);
+		if (groupAcceptsAnyToken) positionalBlocked = true;
+	}
+	for (const [name, sources] of commandNameSources) if (sources.length > 1) throw new DuplicateCommandNameError(name, sources);
+}
 /**
 * Extracts option names that participate in CLI syntax.
 *
@@ -514,7 +578,7 @@ function annotateExclusiveParserResult(parentState, parser, result) {
 }
 function createExclusiveState(parentState, index, parser, result) {
 	const annotatedResult = annotateExclusiveParserResult(parentState, parser, result);
-	return require_annotations.annotateFreshArray(parentState, [index, annotatedResult]);
+	return require_internal_annotations.annotateFreshArray(parentState, [index, annotatedResult]);
 }
 /**
 * Creates a complete() method shared by or() and longestMatch().
@@ -610,7 +674,7 @@ function getExclusiveSuggestRuntimeNodes(parsers, state, path) {
 	const [index, parserResult] = activeState;
 	if (!parserResult?.success || index < 0 || index >= parsers.length) return [];
 	const parser = parsers[index];
-	return require_parser.getParserSuggestRuntimeNodes(parser, parserResult.next.state, [...path, index]);
+	return require_internal_parser.getParserSuggestRuntimeNodes(parser, parserResult.next.state, [...path, index]);
 }
 function findExclusiveZeroInputCandidateSync(parsers, state, exec) {
 	const emptyCtx = {
@@ -733,6 +797,7 @@ function or(...args) {
 	}
 	if (parsers.length < 1) throw new TypeError("or() requires at least one parser argument.");
 	assertParsers(parsers, "or()");
+	checkDuplicateLeadingCommandNames(parsers.map((parser, index) => [String(index), parser]));
 	const noMatchContext = analyzeNoMatchContext(parsers);
 	const combinedMode = parsers.some((p) => p.mode === "async") ? "async" : "sync";
 	const syncParsers = parsers;
@@ -1152,6 +1217,15 @@ function or(...args) {
 		leadingNames: unionLeadingNames(parsers),
 		acceptingAnyToken: parsers.some((p) => p.acceptingAnyToken),
 		initialState: void 0,
+		canSkip(state, exec) {
+			const activeState = normalizeExclusiveState(state);
+			if (activeState != null) {
+				const [index, result] = activeState;
+				const parser = parsers[index];
+				return result.success && parser?.canSkip?.(result.next.state, exec) === true;
+			}
+			return parsers.some((parser) => parser.canSkip?.(parser.initialState, exec) === true);
+		},
 		complete: createExclusiveComplete(parsers, options, noMatchContext, combinedMode),
 		[require_phase2_seed.extractPhase2SeedKey](state, exec) {
 			return extractExclusivePhase2Seed(parsers, state, exec, combinedMode);
@@ -1192,13 +1266,16 @@ function or(...args) {
 	};
 	const singleDependencyMetadata = composeExclusiveDependencyMetadata(parsers);
 	if (singleDependencyMetadata != null) singleResult.dependencyMetadata = singleDependencyMetadata;
-	require_parser.defineInheritedAnnotationParser(singleResult);
+	require_internal_parser.defineInheritedAnnotationParser(singleResult);
 	return singleResult;
 }
 /**
 * @since 0.5.0
 */
 function longestMatch(...args) {
+	return createLongestMatch(...args);
+}
+function createLongestMatch(...args) {
 	let parsers;
 	let options;
 	if (args.length > 0 && args[args.length - 1] && typeof args[args.length - 1] === "object" && !("$valueType" in args[args.length - 1])) {
@@ -1210,6 +1287,8 @@ function longestMatch(...args) {
 	}
 	if (parsers.length < 1) throw new TypeError("longestMatch() requires at least one parser argument.");
 	assertParsers(parsers, "longestMatch()");
+	const allowDuplicateLeadingCommandNames = options?.[require_command_alias.allowDuplicateLeadingCommandNamesKey] === true;
+	if (!allowDuplicateLeadingCommandNames) checkDuplicateLeadingCommandNames(parsers.map((parser, index) => [String(index), parser]));
 	const noMatchContext = analyzeNoMatchContext(parsers);
 	const combinedMode = parsers.some((p) => p.mode === "async") ? "async" : "sync";
 	const syncParsers = parsers;
@@ -1362,7 +1441,7 @@ function longestMatch(...args) {
 	};
 	const multiDependencyMetadata = composeExclusiveDependencyMetadata(parsers);
 	if (multiDependencyMetadata != null) multiResult.dependencyMetadata = multiDependencyMetadata;
-	require_parser.defineInheritedAnnotationParser(multiResult);
+	require_internal_parser.defineInheritedAnnotationParser(multiResult);
 	return multiResult;
 }
 /**
@@ -1445,7 +1524,7 @@ async function* suggestObjectAsync(context, prefix, parserPairs) {
 * @internal
 */
 function registerCompletedDependency(completed, registry) {
-	if (require_dependency.isDependencySourceState(completed) && completed.result.success && !registry.has(completed[require_dependency.dependencyId])) registry.set(completed[require_dependency.dependencyId], completed.result.value);
+	if (require_internal_dependency.isDependencySourceState(completed) && completed.result.success && !registry.has(completed[require_internal_dependency.dependencyId])) registry.set(completed[require_internal_dependency.dependencyId], completed.result.value);
 }
 /**
 * Yields `(parser, state)` pairs for dependency source parsers whose field
@@ -1456,7 +1535,7 @@ function registerCompletedDependency(completed, registry) {
 */
 function* pendingDependencyDefaults(context, parserPairs, registry) {
 	for (const [field, fieldParser] of parserPairs) {
-		const sourceId = fieldParser.dependencyMetadata?.source?.sourceId ?? (require_dependency.isWrappedDependencySource(fieldParser) ? fieldParser[require_dependency.wrappedDependencySourceMarker][require_dependency.dependencyId] : require_dependency.isPendingDependencySourceState(fieldParser.initialState) ? fieldParser.initialState[require_dependency.dependencyId] : void 0);
+		const sourceId = fieldParser.dependencyMetadata?.source?.sourceId ?? (require_internal_dependency.isWrappedDependencySource(fieldParser) ? fieldParser[require_internal_dependency.wrappedDependencySourceMarker][require_internal_dependency.dependencyId] : require_internal_dependency.isPendingDependencySourceState(fieldParser.initialState) ? fieldParser.initialState[require_internal_dependency.dependencyId] : void 0);
 		if (sourceId != null && registry?.has(sourceId)) continue;
 		const fieldState = context.state != null && typeof context.state === "object" && field in context.state ? context.state[field] : void 0;
 		const annotatedFieldState = getAnnotatedFieldState(context.state, field, fieldParser);
@@ -1475,19 +1554,19 @@ function* pendingDependencyDefaults(context, parserPairs, registry) {
 			continue;
 		}
 		if (fieldState != null) {
-			if (!Array.isArray(fieldState) && !require_dependency.isDependencySourceState(fieldState) && (require_dependency.isWrappedDependencySource(fieldParser) || require_dependency.isPendingDependencySourceState(fieldParser.initialState))) yield {
+			if (!Array.isArray(fieldState) && !require_internal_dependency.isDependencySourceState(fieldState) && (require_internal_dependency.isWrappedDependencySource(fieldParser) || require_internal_dependency.isPendingDependencySourceState(fieldParser.initialState))) yield {
 				parser: fieldParser,
 				state: getAnnotatedFieldState(context.state, field, fieldParser)
 			};
 			continue;
 		}
-		if (require_dependency.isPendingDependencySourceState(fieldParser.initialState)) yield {
+		if (require_internal_dependency.isPendingDependencySourceState(fieldParser.initialState)) yield {
 			parser: fieldParser,
 			state: fieldParser.initialState
 		};
-		else if (require_dependency.isWrappedDependencySource(fieldParser)) yield {
+		else if (require_internal_dependency.isWrappedDependencySource(fieldParser)) yield {
 			parser: fieldParser,
-			state: [fieldParser[require_dependency.wrappedDependencySourceMarker]]
+			state: [fieldParser[require_internal_dependency.wrappedDependencySourceMarker]]
 		};
 	}
 }
@@ -1519,13 +1598,13 @@ function completeDependencySourceDefaults(context, parserPairs, registry, exec)
 * @internal
 */
 function wrapAsDependencySourceState(completed, parser) {
-	if (require_dependency.isDependencySourceState(completed)) return completed;
+	if (require_internal_dependency.isDependencySourceState(completed)) return completed;
 	const metadataSource = parser.dependencyMetadata?.source;
 	if (metadataSource?.preservesSourceValue === false) return void 0;
-	const hasDep = metadataSource != null || require_dependency.isWrappedDependencySource(parser) || require_dependency.isPendingDependencySourceState(parser.initialState);
+	const hasDep = metadataSource != null || require_internal_dependency.isWrappedDependencySource(parser) || require_internal_dependency.isPendingDependencySourceState(parser.initialState);
 	if (hasDep && typeof completed === "object" && completed !== null && "success" in completed && completed.success && "value" in completed && completed.value !== void 0) {
-		const depId = metadataSource?.sourceId ?? (require_dependency.isWrappedDependencySource(parser) ? parser[require_dependency.wrappedDependencySourceMarker][require_dependency.dependencyId] : parser.initialState[require_dependency.dependencyId]);
-		return require_dependency.createDependencySourceState(completed, depId);
+		const depId = metadataSource?.sourceId ?? (require_internal_dependency.isWrappedDependencySource(parser) ? parser[require_internal_dependency.wrappedDependencySourceMarker][require_internal_dependency.dependencyId] : parser.initialState[require_internal_dependency.dependencyId]);
+		return require_internal_dependency.createDependencySourceState(completed, depId);
 	}
 	return void 0;
 }
@@ -1635,20 +1714,20 @@ function preCompleteAndRegisterDependencies(state, fieldParserPairs, registry, e
 			if (depState) registerCompletedDependency(depState, registry);
 			continue;
 		}
-		if (Array.isArray(fieldState) && fieldState.length === 1 && require_dependency.isPendingDependencySourceState(fieldState[0])) {
+		if (Array.isArray(fieldState) && fieldState.length === 1 && require_internal_dependency.isPendingDependencySourceState(fieldState[0])) {
 			const completed = fieldParser.complete(fieldState, require_execution_context.withChildExecPath(exec, field));
 			preCompleted.set(field, completed);
-			if (require_dependency.isDependencySourceState(completed)) registerCompletedDependency(completed, registry);
-		} else if (fieldState === void 0 && require_dependency.isPendingDependencySourceState(fieldParser.initialState)) {
+			if (require_internal_dependency.isDependencySourceState(completed)) registerCompletedDependency(completed, registry);
+		} else if (fieldState === void 0 && require_internal_dependency.isPendingDependencySourceState(fieldParser.initialState)) {
 			const completed = fieldParser.complete([fieldParser.initialState], require_execution_context.withChildExecPath(exec, field));
 			preCompleted.set(field, completed);
-			if (require_dependency.isDependencySourceState(completed)) registerCompletedDependency(completed, registry);
-		} else if (fieldState === void 0 && require_dependency.isWrappedDependencySource(fieldParser)) {
-			const pendingState = fieldParser[require_dependency.wrappedDependencySourceMarker];
+			if (require_internal_dependency.isDependencySourceState(completed)) registerCompletedDependency(completed, registry);
+		} else if (fieldState === void 0 && require_internal_dependency.isWrappedDependencySource(fieldParser)) {
+			const pendingState = fieldParser[require_internal_dependency.wrappedDependencySourceMarker];
 			const completed = fieldParser.complete([pendingState], require_execution_context.withChildExecPath(exec, field));
 			preCompleted.set(field, completed);
-			if (require_dependency.isDependencySourceState(completed)) registerCompletedDependency(completed, registry);
-		} else if (fieldState != null && !Array.isArray(fieldState) && !require_dependency.isDependencySourceState(fieldState) && (require_dependency.isWrappedDependencySource(fieldParser) || require_dependency.isPendingDependencySourceState(fieldParser.initialState))) {
+			if (require_internal_dependency.isDependencySourceState(completed)) registerCompletedDependency(completed, registry);
+		} else if (fieldState != null && !Array.isArray(fieldState) && !require_internal_dependency.isDependencySourceState(fieldState) && (require_internal_dependency.isWrappedDependencySource(fieldParser) || require_internal_dependency.isPendingDependencySourceState(fieldParser.initialState))) {
 			const annotatedFieldState$1 = getAnnotatedFieldState(state, field, fieldParser);
 			const completed = fieldParser.complete(annotatedFieldState$1, require_execution_context.withChildExecPath(exec, field));
 			preCompleted.set(field, completed);
@@ -1688,20 +1767,20 @@ async function preCompleteAndRegisterDependenciesAsync(state, fieldParserPairs,
 			if (depState) registerCompletedDependency(depState, registry);
 			continue;
 		}
-		if (Array.isArray(fieldState) && fieldState.length === 1 && require_dependency.isPendingDependencySourceState(fieldState[0])) {
+		if (Array.isArray(fieldState) && fieldState.length === 1 && require_internal_dependency.isPendingDependencySourceState(fieldState[0])) {
 			const completed = await fieldParser.complete(fieldState, require_execution_context.withChildExecPath(exec, field));
 			preCompleted.set(field, completed);
-			if (require_dependency.isDependencySourceState(completed)) registerCompletedDependency(completed, registry);
-		} else if (fieldState === void 0 && require_dependency.isPendingDependencySourceState(fieldParser.initialState)) {
+			if (require_internal_dependency.isDependencySourceState(completed)) registerCompletedDependency(completed, registry);
+		} else if (fieldState === void 0 && require_internal_dependency.isPendingDependencySourceState(fieldParser.initialState)) {
 			const completed = await fieldParser.complete([fieldParser.initialState], require_execution_context.withChildExecPath(exec, field));
 			preCompleted.set(field, completed);
-			if (require_dependency.isDependencySourceState(completed)) registerCompletedDependency(completed, registry);
-		} else if (fieldState === void 0 && require_dependency.isWrappedDependencySource(fieldParser)) {
-			const pendingState = fieldParser[require_dependency.wrappedDependencySourceMarker];
+			if (require_internal_dependency.isDependencySourceState(completed)) registerCompletedDependency(completed, registry);
+		} else if (fieldState === void 0 && require_internal_dependency.isWrappedDependencySource(fieldParser)) {
+			const pendingState = fieldParser[require_internal_dependency.wrappedDependencySourceMarker];
 			const completed = await fieldParser.complete([pendingState], require_execution_context.withChildExecPath(exec, field));
 			preCompleted.set(field, completed);
-			if (require_dependency.isDependencySourceState(completed)) registerCompletedDependency(completed, registry);
-		} else if (fieldState != null && !Array.isArray(fieldState) && !require_dependency.isDependencySourceState(fieldState) && (require_dependency.isWrappedDependencySource(fieldParser) || require_dependency.isPendingDependencySourceState(fieldParser.initialState))) {
+			if (require_internal_dependency.isDependencySourceState(completed)) registerCompletedDependency(completed, registry);
+		} else if (fieldState != null && !Array.isArray(fieldState) && !require_internal_dependency.isDependencySourceState(fieldState) && (require_internal_dependency.isWrappedDependencySource(fieldParser) || require_internal_dependency.isPendingDependencySourceState(fieldParser.initialState))) {
 			const annotatedFieldState$1 = getAnnotatedFieldState(state, field, fieldParser);
 			const completed = await fieldParser.complete(annotatedFieldState$1, require_execution_context.withChildExecPath(exec, field));
 			preCompleted.set(field, completed);
@@ -1755,6 +1834,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		};
 	};
 	if (!options.allowDuplicates) checkDuplicateOptionNames(parserPairs.map(([field, parser]) => [field, parser.usage]));
+	checkDuplicateReachableLeadingCommandNames(parserPairs.map(([field, parser]) => [field, parser]));
 	const noMatchContext = analyzeNoMatchContext(parserKeys.map((k) => parsers[k]));
 	const combinedMode = parserKeys.some((k) => parsers[k].mode === "async") ? "async" : "sync";
 	const getInitialError = (context) => ({
@@ -1992,6 +2072,13 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		usage: applyHiddenToUsage(parserPairs.flatMap(([_, p]) => p.usage), options.hidden),
 		leadingNames: sharedBufferLeadingNames(parserPairs.map(([_, p]) => p)),
 		acceptingAnyToken: parserPairs.some(([_, p]) => p.acceptingAnyToken),
+		canSkip(state, exec) {
+			const getFieldState = createFieldStateGetter(state);
+			return parserKeys.every((field) => {
+				const parser = parsers[field];
+				return parser.canSkip?.(getFieldState(field, parser), require_execution_context.withChildExecPath(exec, field)) === true;
+			});
+		},
 		get initialState() {
 			return createInitialState();
 		},
@@ -2281,9 +2368,372 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		configurable: true,
 		enumerable: false
 	});
-	require_parser.defineInheritedAnnotationParser(objectParser);
+	require_internal_parser.defineInheritedAnnotationParser(objectParser);
 	return objectParser;
 }
+function isParserLike(value) {
+	return value != null && (typeof value === "object" || typeof value === "function") && "parse" in value && "$valueType" in value && "$stateType" in value;
+}
+function tokenMatchesLeadingName(token, candidates) {
+	if (token == null) return false;
+	for (const name of candidates.optionNames) if (token === name) return true;
+	for (const name of candidates.joinedOptionNames) if (name.startsWith("/") && token.startsWith(`${name}:`) || (name.startsWith("--") || name.startsWith("-") && name.length > 2) && token.startsWith(`${name}=`)) return true;
+	for (const name of candidates.commandNames) if (token === name) return true;
+	return false;
+}
+function parserCanSkipAt(parser, state, exec, index) {
+	return parser.canSkip?.(require_annotation_state.getWrappedChildState(void 0, state, parser), require_execution_context.withChildExecPath(exec, index)) === true;
+}
+function collectLeadingJoinedOptionNames(terms, optionNames) {
+	for (const term of terms) {
+		if (term.type === "option") {
+			if (term.metavar != null) for (const name of term.names) optionNames.add(name);
+			return false;
+		}
+		if (term.type === "command" || term.type === "argument") return false;
+		if (term.type === "optional") {
+			collectLeadingJoinedOptionNames(term.terms, optionNames);
+			continue;
+		}
+		if (term.type === "multiple") {
+			collectLeadingJoinedOptionNames(term.terms, optionNames);
+			if (term.min === 0) continue;
+			return false;
+		}
+		if (term.type === "sequence") {
+			if (collectLeadingJoinedOptionNames(term.terms, optionNames)) continue;
+			return false;
+		}
+		if (term.type === "exclusive") {
+			let allSkippable = true;
+			for (const branch of term.terms) {
+				const branchSkippable = collectLeadingJoinedOptionNames(branch, optionNames);
+				allSkippable = allSkippable && branchSkippable;
+			}
+			if (allSkippable) continue;
+			return false;
+		}
+	}
+	return true;
+}
+function sequenceLeadingCandidates(parsers) {
+	const optionNames = /* @__PURE__ */ new Set();
+	const joinedOptionNames = /* @__PURE__ */ new Set();
+	const commandNames = /* @__PURE__ */ new Set();
+	let positionalBlocked = false;
+	for (let i = 0; i < parsers.length; i++) {
+		const parser = parsers[i];
+		const parserOptions = /* @__PURE__ */ new Set();
+		const parserJoinedOptions = /* @__PURE__ */ new Set();
+		const parserCommands = /* @__PURE__ */ new Set();
+		require_usage_internals.collectLeadingCandidates(parser.usage, parserOptions, parserCommands);
+		collectLeadingJoinedOptionNames(parser.usage, parserJoinedOptions);
+		for (const name of parserOptions) optionNames.add(name);
+		for (const name of parserJoinedOptions) joinedOptionNames.add(name);
+		if (!positionalBlocked) {
+			for (const name of parserCommands) commandNames.add(name);
+			for (const name of parser.leadingNames) if (!parserOptions.has(name)) commandNames.add(name);
+		} else for (const name of parser.leadingNames) if (!parserOptions.has(name) && name.startsWith("-")) commandNames.add(name);
+		if (parser.acceptingAnyToken) positionalBlocked = true;
+		if (!parserCanSkipAt(parser, parser.initialState, void 0, i)) break;
+	}
+	return {
+		optionNames: optionNames.size === 0 ? EMPTY_LEADING_NAMES : optionNames,
+		joinedOptionNames: joinedOptionNames.size === 0 ? EMPTY_LEADING_NAMES : joinedOptionNames,
+		commandNames: commandNames.size === 0 ? EMPTY_LEADING_NAMES : commandNames
+	};
+}
+function sequenceLeadingNames(parsers) {
+	const candidates = sequenceLeadingCandidates(parsers);
+	const names = new Set([
+		...candidates.optionNames,
+		...candidates.joinedOptionNames,
+		...candidates.commandNames
+	]);
+	return names.size === 0 ? EMPTY_LEADING_NAMES : names;
+}
+function sequenceAcceptingAnyToken(parsers) {
+	for (let i = 0; i < parsers.length; i++) {
+		const parser = parsers[i];
+		if (parser.acceptingAnyToken) return true;
+		if (!parserCanSkipAt(parser, parser.initialState, void 0, i)) break;
+	}
+	return false;
+}
+function sequencePriority(parsers) {
+	let priority = 0;
+	for (let i = 0; i < parsers.length; i++) {
+		const parser = parsers[i];
+		priority = Math.max(priority, parser.priority);
+		if (!parserCanSkipAt(parser, parser.initialState, void 0, i)) break;
+	}
+	return priority;
+}
+function leadingCandidatesAfter(parsers, startIndex) {
+	return sequenceLeadingCandidates(parsers.slice(startIndex));
+}
+function checkSequentialDuplicateOptionNames(parsers) {
+	const active = /* @__PURE__ */ new Map();
+	for (let i = 0; i < parsers.length; i++) {
+		const parser = parsers[i];
+		const optionNames = /* @__PURE__ */ new Set();
+		require_usage_internals.collectLeadingCandidates(parser.usage, optionNames, /* @__PURE__ */ new Set(), true);
+		const retainedOptionNames = collectRetainedLeadingCandidates(parser.usage).optionNames;
+		for (const name of optionNames) {
+			const sources = active.get(name);
+			if (sources != null) throw new DuplicateOptionError(name, [...sources, String(i)]);
+		}
+		for (const name of optionNames) {
+			const sources = active.get(name);
+			active.set(name, sources == null ? [String(i)] : [...sources, String(i)]);
+		}
+		if (!parserCanSkipAt(parser, parser.initialState, void 0, i)) active.clear();
+		for (const name of retainedOptionNames) {
+			const sources = active.get(name);
+			active.set(name, sources == null ? [String(i)] : [...sources, String(i)]);
+		}
+	}
+}
+function collectRetainedLeadingCandidates(terms) {
+	const optionNames = /* @__PURE__ */ new Set();
+	const joinedOptionNames = /* @__PURE__ */ new Set();
+	collectRetainedLeadingCandidatesInto(terms, optionNames, joinedOptionNames);
+	return {
+		optionNames,
+		joinedOptionNames,
+		commandNames: EMPTY_LEADING_NAMES
+	};
+}
+function collectRetainedLeadingCandidatesInto(terms, optionNames, joinedOptionNames) {
+	for (const term of terms) {
+		if (term.type === "optional") {
+			collectLeadingOptionCandidates(term.terms, optionNames, joinedOptionNames);
+			collectRetainedLeadingCandidatesInto(term.terms, optionNames, joinedOptionNames);
+			continue;
+		}
+		if (term.type === "multiple") {
+			collectLeadingOptionCandidates(term.terms, optionNames, joinedOptionNames);
+			collectRetainedLeadingCandidatesInto(term.terms, optionNames, joinedOptionNames);
+			continue;
+		}
+		if (term.type === "sequence") {
+			collectRetainedLeadingCandidatesInto(term.terms, optionNames, joinedOptionNames);
+			continue;
+		}
+		if (term.type === "exclusive") {
+			let canSkipBranch = false;
+			const branchOptionNames = [];
+			const branchJoinedOptionNames = [];
+			for (const branch of term.terms) {
+				const branchOptions = /* @__PURE__ */ new Set();
+				const branchJoinedOptions = /* @__PURE__ */ new Set();
+				const branchCanSkip = require_usage_internals.collectLeadingCandidates(branch, branchOptions, /* @__PURE__ */ new Set(), true);
+				collectLeadingJoinedOptionNames(branch, branchJoinedOptions);
+				canSkipBranch = canSkipBranch || branchCanSkip;
+				branchOptionNames.push(branchOptions);
+				branchJoinedOptionNames.push(branchJoinedOptions);
+				collectRetainedLeadingCandidatesInto(branch, optionNames, joinedOptionNames);
+			}
+			if (canSkipBranch) {
+				for (const branchOptions of branchOptionNames) for (const name of branchOptions) optionNames.add(name);
+				for (const branchJoinedOptions of branchJoinedOptionNames) for (const name of branchJoinedOptions) joinedOptionNames.add(name);
+			}
+		}
+	}
+}
+function collectLeadingOptionCandidates(terms, optionNames, joinedOptionNames) {
+	require_usage_internals.collectLeadingCandidates(terms, optionNames, /* @__PURE__ */ new Set(), true);
+	collectLeadingJoinedOptionNames(terms, joinedOptionNames);
+}
+function collectRetainedLeadingCandidatesAtState(terms, state) {
+	if (terms.length === 1 && terms[0].type === "optional" && Array.isArray(state)) return collectRetainedLeadingCandidates(terms[0].terms);
+	return collectRetainedLeadingCandidates(terms);
+}
+function createSeqState(sourceState, index, states) {
+	const seqState = {
+		index,
+		states: require_internal_annotations.annotateFreshArray(sourceState, states)
+	};
+	return require_internal_annotations.inheritAnnotations(sourceState, seqState);
+}
+function getSeqChildState(seqState, index, parser) {
+	return require_annotation_state.getWrappedChildState(seqState, seqState.states[index], parser);
+}
+function updateSeqChildState(sourceState, index, childState, parser) {
+	return require_internal_annotations.annotateFreshArray(sourceState.states, sourceState.states.map((state, stateIndex) => stateIndex === index ? require_annotation_state.getWrappedChildState(sourceState.states, childState, parser) : state));
+}
+function shouldAdvanceSeqBeforeParse(parser, parserState, initialParserState, currentContext, index, parsers) {
+	const token = currentContext.buffer[0];
+	if (token !== "--") {
+		const laterLeadingCandidates = leadingCandidatesAfter(parsers, index + 1);
+		if (!tokenMatchesLeadingName(token, laterLeadingCandidates)) return false;
+	}
+	if (!parserCanSkipAt(parser, parserState, currentContext.exec, index)) return false;
+	if (token === "--") return true;
+	if (currentContext.state.states[index] === initialParserState) {
+		const currentLeadingCandidates = sequenceLeadingCandidates([parser]);
+		return !tokenMatchesLeadingName(token, currentLeadingCandidates);
+	}
+	return !tokenMatchesLeadingName(token, collectRetainedLeadingCandidatesAtState(parser.usage, currentContext.state.states[index]));
+}
+function advanceSeqContext(currentContext, nextIndex, consumedTerminator) {
+	return {
+		...currentContext,
+		buffer: consumedTerminator ? currentContext.buffer.slice(1) : currentContext.buffer,
+		optionsTerminated: consumedTerminator ? true : currentContext.optionsTerminated,
+		state: createSeqState(currentContext.state, nextIndex, currentContext.state.states)
+	};
+}
+function updateSeqContextFromChildResult(currentContext, index, parser, result, nextIndex) {
+	const states = updateSeqChildState(currentContext.state, index, result.next.state, parser);
+	const mergedExec = require_execution_context.mergeChildExec(currentContext.exec, result.next.exec);
+	return {
+		...currentContext,
+		buffer: result.next.buffer,
+		optionsTerminated: result.next.optionsTerminated,
+		state: createSeqState(currentContext.state, nextIndex, states),
+		...mergedExec != null ? {
+			exec: mergedExec,
+			dependencyRegistry: mergedExec.dependencyRegistry
+		} : {}
+	};
+}
+function advanceSeqSuggestContextSync(context, parsers, initialStates) {
+	let currentContext = context;
+	while (currentContext.state.index < parsers.length) {
+		const index = currentContext.state.index;
+		const parser = parsers[index];
+		const parserState = getSeqChildState(currentContext.state, index, parser);
+		if (currentContext.buffer.length < 1) break;
+		if (shouldAdvanceSeqBeforeParse(parser, parserState, initialStates[index], currentContext, index, parsers)) {
+			const consumedTerminator = currentContext.buffer[0] === "--";
+			currentContext = advanceSeqContext(currentContext, index + 1, consumedTerminator);
+			continue;
+		}
+		const result = parser.parse(withChildContext$1(currentContext, index, parserState, parser));
+		if (!result.success) {
+			if (result.consumed > 0) break;
+			if (parserCanSkipAt(parser, parserState, currentContext.exec, index)) {
+				currentContext = advanceSeqContext(currentContext, index + 1, false);
+				continue;
+			}
+			break;
+		}
+		const nextIndex = result.consumed.length > 0 ? index : index + 1;
+		currentContext = updateSeqContextFromChildResult(currentContext, index, parser, result, nextIndex);
+	}
+	return currentContext;
+}
+async function advanceSeqSuggestContextAsync(context, parsers, initialStates) {
+	let currentContext = context;
+	while (currentContext.state.index < parsers.length) {
+		const index = currentContext.state.index;
+		const parser = parsers[index];
+		const parserState = getSeqChildState(currentContext.state, index, parser);
+		if (currentContext.buffer.length < 1) break;
+		if (shouldAdvanceSeqBeforeParse(parser, parserState, initialStates[index], currentContext, index, parsers)) {
+			const consumedTerminator = currentContext.buffer[0] === "--";
+			currentContext = advanceSeqContext(currentContext, index + 1, consumedTerminator);
+			continue;
+		}
+		const result = await parser.parse(withChildContext$1(currentContext, index, parserState, parser));
+		if (!result.success) {
+			if (result.consumed > 0) break;
+			if (parserCanSkipAt(parser, parserState, currentContext.exec, index)) {
+				currentContext = advanceSeqContext(currentContext, index + 1, false);
+				continue;
+			}
+			break;
+		}
+		const nextIndex = result.consumed.length > 0 ? index : index + 1;
+		currentContext = updateSeqContextFromChildResult(currentContext, index, parser, result, nextIndex);
+	}
+	return currentContext;
+}
+function createSeqComplete(parsers, combinedMode) {
+	const syncParsers = parsers;
+	return (state, exec) => require_mode_dispatch.dispatchByMode(combinedMode, () => {
+		const stateArray = require_internal_annotations.annotateFreshArray(state, state.states);
+		const runtime = exec?.dependencyRuntime ?? require_dependency_runtime.createDependencyRuntimeContext(exec?.dependencyRegistry);
+		const childExec = {
+			...exec,
+			dependencyRuntime: runtime
+		};
+		const pairs = buildIndexedParserPairs(syncParsers);
+		const stateRecord = createAnnotatedArrayStateRecord(stateArray);
+		const preCompleted = preCompleteAndRegisterDependencies(stateRecord, pairs, runtime.registry, childExec);
+		require_dependency_runtime.collectExplicitSourceValues(filterPreCompletedRuntimeNodes(require_dependency_runtime.buildRuntimeNodesFromArray(syncParsers, stateArray, exec?.path), new Set(preCompleted.keys())), runtime);
+		const phase3Exec = {
+			...childExec,
+			preCompletedByParser: void 0
+		};
+		const resolvedArray = require_dependency_runtime.resolveStateWithRuntime(stateArray, runtime);
+		const result = [];
+		const deferredKeys = /* @__PURE__ */ new Map();
+		let hasDeferred = false;
+		for (let i = 0; i < syncParsers.length; i++) {
+			const elementParser = syncParsers[i];
+			const preCompletedResult = preCompleted.get(String(i));
+			const valueResult = preCompletedResult !== void 0 ? unwrapCompleteResult(preCompletedResult) : unwrapCompleteResult(elementParser.complete(prepareStateForCompletion(require_annotation_state.getWrappedChildState(stateArray, resolvedArray[i], elementParser), elementParser), require_execution_context.withChildExecPath(phase3Exec, i)));
+			if (!valueResult.success) return {
+				success: false,
+				error: valueResult.error
+			};
+			result[i] = valueResult.value;
+			if (valueResult.deferred) if (valueResult.deferredKeys) deferredKeys.set(i, valueResult.deferredKeys);
+			else if (valueResult.value == null || typeof valueResult.value !== "object") deferredKeys.set(i, null);
+			else hasDeferred = true;
+		}
+		return {
+			success: true,
+			value: result,
+			...deferredKeys.size > 0 || hasDeferred ? {
+				deferred: true,
+				...deferredKeys.size > 0 ? { deferredKeys } : {}
+			} : {}
+		};
+	}, async () => {
+		const stateArray = require_internal_annotations.annotateFreshArray(state, state.states);
+		const runtime = exec?.dependencyRuntime ?? require_dependency_runtime.createDependencyRuntimeContext(exec?.dependencyRegistry);
+		const childExec = {
+			...exec,
+			dependencyRuntime: runtime
+		};
+		const pairs = buildIndexedParserPairs(parsers);
+		const stateRecord = createAnnotatedArrayStateRecord(stateArray);
+		const preCompleted = await preCompleteAndRegisterDependenciesAsync(stateRecord, pairs, runtime.registry, childExec);
+		await require_dependency_runtime.collectExplicitSourceValuesAsync(filterPreCompletedRuntimeNodes(require_dependency_runtime.buildRuntimeNodesFromArray(parsers, stateArray, exec?.path), new Set(preCompleted.keys())), runtime);
+		const phase3Exec = {
+			...childExec,
+			preCompletedByParser: void 0
+		};
+		const resolvedArray = await require_dependency_runtime.resolveStateWithRuntimeAsync(stateArray, runtime);
+		const result = [];
+		const deferredKeys = /* @__PURE__ */ new Map();
+		let hasDeferred = false;
+		for (let i = 0; i < parsers.length; i++) {
+			const elementParser = parsers[i];
+			const preCompletedResult = preCompleted.get(String(i));
+			const valueResult = preCompletedResult !== void 0 ? unwrapCompleteResult(preCompletedResult) : unwrapCompleteResult(await elementParser.complete(prepareStateForCompletion(require_annotation_state.getWrappedChildState(stateArray, resolvedArray[i], elementParser), elementParser), require_execution_context.withChildExecPath(phase3Exec, i)));
+			if (!valueResult.success) return {
+				success: false,
+				error: valueResult.error
+			};
+			result[i] = valueResult.value;
+			if (valueResult.deferred) if (valueResult.deferredKeys) deferredKeys.set(i, valueResult.deferredKeys);
+			else if (valueResult.value == null || typeof valueResult.value !== "object") deferredKeys.set(i, null);
+			else hasDeferred = true;
+		}
+		return {
+			success: true,
+			value: result,
+			...deferredKeys.size > 0 || hasDeferred ? {
+				deferred: true,
+				...deferredKeys.size > 0 ? { deferredKeys } : {}
+			} : {}
+		};
+	});
+}
 function suggestTupleSync(context, prefix, parsers) {
 	const suggestions = [];
 	const advanced = advanceTupleSuggestContextSync(context, parsers);
@@ -2365,7 +2815,7 @@ function advanceTupleSuggestContextSync(context, parsers) {
 		for (const [parser, index] of remainingParsers) {
 			const result = parser.parse(withChildContext$1(currentContext, index, stateArray[index], parser));
 			if (result.success && result.consumed.length > 0) {
-				const newStateArray = require_annotations.annotateFreshArray(currentContext.state, stateArray.map((state, idx) => idx === index ? require_annotation_state.getWrappedChildState(currentContext.state, result.next.state, parser) : state));
+				const newStateArray = require_internal_annotations.annotateFreshArray(currentContext.state, stateArray.map((state, idx) => idx === index ? require_annotation_state.getWrappedChildState(currentContext.state, result.next.state, parser) : state));
 				const mergedExec = require_execution_context.mergeChildExec(currentContext.exec, result.next.exec);
 				currentContext = {
 					...currentContext,
@@ -2390,7 +2840,7 @@ function advanceTupleSuggestContextSync(context, parsers) {
 		if (!foundMatch) for (const [parser, index] of remainingParsers) {
 			const result = parser.parse(withChildContext$1(currentContext, index, stateArray[index], parser));
 			if (result.success && result.consumed.length < 1) {
-				const newStateArray = require_annotations.annotateFreshArray(currentContext.state, stateArray.map((state, idx) => idx === index ? require_annotation_state.getWrappedChildState(currentContext.state, result.next.state, parser) : state));
+				const newStateArray = require_internal_annotations.annotateFreshArray(currentContext.state, stateArray.map((state, idx) => idx === index ? require_annotation_state.getWrappedChildState(currentContext.state, result.next.state, parser) : state));
 				const mergedExec = require_execution_context.mergeChildExec(currentContext.exec, result.next.exec);
 				currentContext = {
 					...currentContext,
@@ -2431,7 +2881,7 @@ async function advanceTupleSuggestContextAsync(context, parsers) {
 		for (const [parser, index] of remainingParsers) {
 			const result = await parser.parse(withChildContext$1(currentContext, index, stateArray[index], parser));
 			if (result.success && result.consumed.length > 0) {
-				const newStateArray = require_annotations.annotateFreshArray(currentContext.state, stateArray.map((state, idx) => idx === index ? require_annotation_state.getWrappedChildState(currentContext.state, result.next.state, parser) : state));
+				const newStateArray = require_internal_annotations.annotateFreshArray(currentContext.state, stateArray.map((state, idx) => idx === index ? require_annotation_state.getWrappedChildState(currentContext.state, result.next.state, parser) : state));
 				const mergedExec = require_execution_context.mergeChildExec(currentContext.exec, result.next.exec);
 				currentContext = {
 					...currentContext,
@@ -2456,7 +2906,7 @@ async function advanceTupleSuggestContextAsync(context, parsers) {
 		if (!foundMatch) for (const [parser, index] of remainingParsers) {
 			const result = await parser.parse(withChildContext$1(currentContext, index, stateArray[index], parser));
 			if (result.success && result.consumed.length < 1) {
-				const newStateArray = require_annotations.annotateFreshArray(currentContext.state, stateArray.map((state, idx) => idx === index ? require_annotation_state.getWrappedChildState(currentContext.state, result.next.state, parser) : state));
+				const newStateArray = require_internal_annotations.annotateFreshArray(currentContext.state, stateArray.map((state, idx) => idx === index ? require_annotation_state.getWrappedChildState(currentContext.state, result.next.state, parser) : state));
 				const mergedExec = require_execution_context.mergeChildExec(currentContext.exec, result.next.exec);
 				currentContext = {
 					...currentContext,
@@ -2492,7 +2942,7 @@ function markFailedTupleSuggestSources(parsers, stateArray, failedParserIndexes,
 		const parser = parsers[index];
 		if (parser == null) continue;
 		const parserState = stateArray && Array.isArray(stateArray) ? stateArray[index] : parser.initialState;
-		const nodes = require_parser.getParserSuggestRuntimeNodes(parser, require_annotation_state.getWrappedChildState(stateArray, parserState, parser), [...prefix, index]);
+		const nodes = require_internal_parser.getParserSuggestRuntimeNodes(parser, require_annotation_state.getWrappedChildState(stateArray, parserState, parser), [...prefix, index]);
 		if (nodes.length < 1) continue;
 		const failedRuntime = require_dependency_runtime.createDependencyRuntimeContext();
 		require_dependency_runtime.collectExplicitSourceValues(nodes, failedRuntime);
@@ -2509,7 +2959,7 @@ async function markFailedTupleSuggestSourcesAsync(parsers, stateArray, failedPar
 		const parser = parsers[index];
 		if (parser == null) continue;
 		const parserState = stateArray && Array.isArray(stateArray) ? stateArray[index] : parser.initialState;
-		const nodes = require_parser.getParserSuggestRuntimeNodes(parser, require_annotation_state.getWrappedChildState(stateArray, parserState, parser), [...prefix, index]);
+		const nodes = require_internal_parser.getParserSuggestRuntimeNodes(parser, require_annotation_state.getWrappedChildState(stateArray, parserState, parser), [...prefix, index]);
 		if (nodes.length < 1) continue;
 		const failedRuntime = require_dependency_runtime.createDependencyRuntimeContext();
 		await require_dependency_runtime.collectExplicitSourceValuesAsync(nodes, failedRuntime);
@@ -2549,7 +2999,7 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			for (const [parser, index] of remainingParsers) {
 				const result = parser.parse(withChildContext$1(currentContext, index, stateArray[index], parser));
 				if (result.success && result.consumed.length > 0) {
-					const newStateArray = require_annotations.annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? require_annotation_state.getWrappedChildState(currentContext.state, result.next.state, parser) : s));
+					const newStateArray = require_internal_annotations.annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? require_annotation_state.getWrappedChildState(currentContext.state, result.next.state, parser) : s));
 					const mergedExec = require_execution_context.mergeChildExec(currentContext.exec, result.next.exec);
 					currentContext = {
 						...currentContext,
@@ -2570,7 +3020,7 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			if (!foundMatch) for (const [parser, index] of remainingParsers) {
 				const result = parser.parse(withChildContext$1(currentContext, index, stateArray[index], parser));
 				if (result.success && result.consumed.length < 1) {
-					const newStateArray = require_annotations.annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? require_annotation_state.getWrappedChildState(currentContext.state, result.next.state, parser) : s));
+					const newStateArray = require_internal_annotations.annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? require_annotation_state.getWrappedChildState(currentContext.state, result.next.state, parser) : s));
 					const mergedExec = require_execution_context.mergeChildExec(currentContext.exec, result.next.exec);
 					currentContext = {
 						...currentContext,
@@ -2616,7 +3066,7 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 				const resultOrPromise = parser.parse(withChildContext$1(currentContext, index, stateArray[index], parser));
 				const result = await resultOrPromise;
 				if (result.success && result.consumed.length > 0) {
-					const newStateArray = require_annotations.annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? require_annotation_state.getWrappedChildState(currentContext.state, result.next.state, parser) : s));
+					const newStateArray = require_internal_annotations.annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? require_annotation_state.getWrappedChildState(currentContext.state, result.next.state, parser) : s));
 					const mergedExec = require_execution_context.mergeChildExec(currentContext.exec, result.next.exec);
 					currentContext = {
 						...currentContext,
@@ -2638,7 +3088,7 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 				const resultOrPromise = parser.parse(withChildContext$1(currentContext, index, stateArray[index], parser));
 				const result = await resultOrPromise;
 				if (result.success && result.consumed.length < 1) {
-					const newStateArray = require_annotations.annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? require_annotation_state.getWrappedChildState(currentContext.state, result.next.state, parser) : s));
+					const newStateArray = require_internal_annotations.annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? require_annotation_state.getWrappedChildState(currentContext.state, result.next.state, parser) : s));
 					const mergedExec = require_execution_context.mergeChildExec(currentContext.exec, result.next.exec);
 					currentContext = {
 						...currentContext,
@@ -2678,6 +3128,10 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		acceptingAnyToken: parsers.some((p) => p.acceptingAnyToken),
 		priority: parsers.length > 0 ? Math.max(...parsers.map((p) => p.priority)) : 0,
 		initialState: parsers.map((parser) => parser.initialState),
+		canSkip(state, exec) {
+			const stateArray = state;
+			return parsers.every((parser, index) => parser.canSkip?.(require_annotation_state.getWrappedChildState(stateArray, stateArray[index], parser), require_execution_context.withChildExecPath(exec, index)) === true);
+		},
 		parse(context) {
 			return require_mode_dispatch.dispatchByMode(combinedMode, () => parseSync(context), () => parseAsync(context));
 		},
@@ -2912,9 +3366,337 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		configurable: true,
 		enumerable: false
 	});
-	require_parser.defineInheritedAnnotationParser(tupleParser);
+	require_internal_parser.defineInheritedAnnotationParser(tupleParser);
 	return tupleParser;
 }
+function seq(...rawArgs) {
+	const label = typeof rawArgs[0] === "string" ? rawArgs[0] : void 0;
+	if (label != null) require_validate.validateLabel(label);
+	const args = label == null ? rawArgs : rawArgs.slice(1);
+	const lastArg = args.at(-1);
+	const hasOptions = lastArg != null && !isParserLike(lastArg);
+	const options = hasOptions ? lastArg : {};
+	const parsers = hasOptions ? args.slice(0, -1) : args;
+	const combinedMode = parsers.some((p) => p.mode === "async") ? "async" : "sync";
+	const syncParsers = parsers;
+	if (!options.allowDuplicates) checkSequentialDuplicateOptionNames(parsers);
+	const initialState = createSeqState(void 0, 0, parsers.map((parser) => parser.initialState));
+	const withSeqConsumedDepth = (result, consumed) => ({
+		...result,
+		consumed: consumed.length + result.consumed
+	});
+	const parseSync = (context) => {
+		let currentContext = context;
+		const allConsumed = [];
+		while (currentContext.state.index < syncParsers.length) {
+			const index = currentContext.state.index;
+			const parser = syncParsers[index];
+			const parserState = getSeqChildState(currentContext.state, index, parser);
+			if (currentContext.buffer.length < 1) break;
+			if (shouldAdvanceSeqBeforeParse(parser, parserState, initialState.states[index], currentContext, index, syncParsers)) {
+				const consumedTerminator = currentContext.buffer[0] === "--";
+				if (consumedTerminator) allConsumed.push("--");
+				currentContext = advanceSeqContext(currentContext, index + 1, consumedTerminator);
+				continue;
+			}
+			const result = parser.parse(withChildContext$1(currentContext, index, parserState, parser));
+			if (!result.success) {
+				if (result.consumed > 0) return withSeqConsumedDepth(result, allConsumed);
+				if (!parserCanSkipAt(parser, parserState, currentContext.exec, index)) return withSeqConsumedDepth(result, allConsumed);
+				currentContext = advanceSeqContext(currentContext, index + 1, false);
+				continue;
+			}
+			const states = updateSeqChildState(currentContext.state, index, result.next.state, parser);
+			const nextIndex = result.consumed.length > 0 ? index : index + 1;
+			const mergedExec = require_execution_context.mergeChildExec(currentContext.exec, result.next.exec);
+			currentContext = {
+				...currentContext,
+				buffer: result.next.buffer,
+				optionsTerminated: result.next.optionsTerminated,
+				state: createSeqState(currentContext.state, nextIndex, states),
+				...mergedExec != null ? {
+					exec: mergedExec,
+					dependencyRegistry: mergedExec.dependencyRegistry
+				} : {}
+			};
+			allConsumed.push(...result.consumed);
+		}
+		return {
+			success: true,
+			next: currentContext,
+			consumed: allConsumed
+		};
+	};
+	const parseAsync = async (context) => {
+		let currentContext = context;
+		const allConsumed = [];
+		while (currentContext.state.index < parsers.length) {
+			const index = currentContext.state.index;
+			const parser = parsers[index];
+			const parserState = getSeqChildState(currentContext.state, index, parser);
+			if (currentContext.buffer.length < 1) break;
+			if (shouldAdvanceSeqBeforeParse(parser, parserState, initialState.states[index], currentContext, index, parsers)) {
+				const consumedTerminator = currentContext.buffer[0] === "--";
+				if (consumedTerminator) allConsumed.push("--");
+				currentContext = advanceSeqContext(currentContext, index + 1, consumedTerminator);
+				continue;
+			}
+			const result = await parser.parse(withChildContext$1(currentContext, index, parserState, parser));
+			if (!result.success) {
+				if (result.consumed > 0) return withSeqConsumedDepth(result, allConsumed);
+				if (!parserCanSkipAt(parser, parserState, currentContext.exec, index)) return withSeqConsumedDepth(result, allConsumed);
+				currentContext = advanceSeqContext(currentContext, index + 1, false);
+				continue;
+			}
+			const states = updateSeqChildState(currentContext.state, index, result.next.state, parser);
+			const nextIndex = result.consumed.length > 0 ? index : index + 1;
+			const mergedExec = require_execution_context.mergeChildExec(currentContext.exec, result.next.exec);
+			currentContext = {
+				...currentContext,
+				buffer: result.next.buffer,
+				optionsTerminated: result.next.optionsTerminated,
+				state: createSeqState(currentContext.state, nextIndex, states),
+				...mergedExec != null ? {
+					exec: mergedExec,
+					dependencyRegistry: mergedExec.dependencyRegistry
+				} : {}
+			};
+			allConsumed.push(...result.consumed);
+		}
+		return {
+			success: true,
+			next: currentContext,
+			consumed: allConsumed
+		};
+	};
+	const leadingNames = sequenceLeadingNames(parsers);
+	const seqParser = {
+		mode: combinedMode,
+		$valueType: [],
+		$stateType: [],
+		[fieldParsersKey]: parsers.map((parser, index) => [String(index), parser]),
+		usage: [{
+			type: "sequence",
+			terms: parsers.flatMap((parser) => parser.usage)
+		}],
+		leadingNames,
+		acceptingAnyToken: sequenceAcceptingAnyToken(parsers),
+		priority: sequencePriority(parsers),
+		initialState,
+		canSkip(state, exec) {
+			for (let i = state.index; i < parsers.length; i++) {
+				const parser = parsers[i];
+				if (parser.canSkip?.(getSeqChildState(state, i, parser), require_execution_context.withChildExecPath(exec, i)) !== true) return false;
+			}
+			return true;
+		},
+		parse(context) {
+			return require_mode_dispatch.dispatchByMode(combinedMode, () => parseSync(context), () => parseAsync(context));
+		},
+		complete: void 0,
+		[require_phase2_seed.extractPhase2SeedKey](state, exec) {
+			return require_mode_dispatch.dispatchByMode(combinedMode, () => {
+				const stateArray = state.states;
+				const runtime = exec?.dependencyRuntime ?? require_dependency_runtime.createDependencyRuntimeContext(exec?.dependencyRegistry);
+				const childExec = withDependencyRuntimeExec(seqParser.usage, exec, runtime);
+				const pairs = buildIndexedParserPairs(syncParsers);
+				const stateRecord = createAnnotatedArrayStateRecord(stateArray);
+				const preCompleted = preCompleteAndRegisterDependencies(stateRecord, pairs, runtime.registry, childExec);
+				require_dependency_runtime.collectExplicitSourceValues(filterPreCompletedRuntimeNodes(require_dependency_runtime.buildRuntimeNodesFromArray(syncParsers, stateArray, exec?.path), new Set(preCompleted.keys())), runtime);
+				const phase3Exec = {
+					...childExec,
+					preCompletedByParser: void 0
+				};
+				const resolvedArray = require_dependency_runtime.resolveStateWithRuntime(stateArray, runtime);
+				const result = [];
+				const deferredKeys = /* @__PURE__ */ new Map();
+				let hasDeferred = false;
+				let hasAnySeed = false;
+				for (let i = 0; i < syncParsers.length; i++) {
+					const elementParser = syncParsers[i];
+					const childExec$1 = require_execution_context.withChildExecPath(phase3Exec, i);
+					const preCompletedResult = preCompleted.get(String(i));
+					const seed = preCompletedResult !== void 0 ? reusePreCompletedPhase2Seed(elementParser, prepareStateForCompletion(resolvedArray[i], elementParser), preCompletedResult, childExec$1) : require_phase2_seed.completeOrExtractPhase2Seed(elementParser, prepareStateForCompletion(resolvedArray[i], elementParser), childExec$1);
+					if (seed == null) continue;
+					hasAnySeed = true;
+					result[i] = seed.value;
+					if (seed.deferred) if (seed.deferredKeys) deferredKeys.set(i, seed.deferredKeys);
+					else if (seed.value == null || typeof seed.value !== "object") deferredKeys.set(i, null);
+					else hasDeferred = true;
+				}
+				if (!hasAnySeed) return null;
+				return {
+					value: result,
+					...deferredKeys.size > 0 || hasDeferred ? {
+						deferred: true,
+						...deferredKeys.size > 0 ? { deferredKeys } : {}
+					} : {}
+				};
+			}, async () => {
+				const stateArray = state.states;
+				const runtime = exec?.dependencyRuntime ?? require_dependency_runtime.createDependencyRuntimeContext(exec?.dependencyRegistry);
+				const childExec = withDependencyRuntimeExec(seqParser.usage, exec, runtime);
+				const pairs = buildIndexedParserPairs(parsers);
+				const stateRecord = createAnnotatedArrayStateRecord(stateArray);
+				const preCompleted = await preCompleteAndRegisterDependenciesAsync(stateRecord, pairs, runtime.registry, childExec);
+				await require_dependency_runtime.collectExplicitSourceValuesAsync(filterPreCompletedRuntimeNodes(require_dependency_runtime.buildRuntimeNodesFromArray(parsers, stateArray, exec?.path), new Set(preCompleted.keys())), runtime);
+				const phase3Exec = {
+					...childExec,
+					preCompletedByParser: void 0
+				};
+				const resolvedArray = await require_dependency_runtime.resolveStateWithRuntimeAsync(stateArray, runtime);
+				const result = [];
+				const deferredKeys = /* @__PURE__ */ new Map();
+				let hasDeferred = false;
+				let hasAnySeed = false;
+				for (let i = 0; i < parsers.length; i++) {
+					const elementParser = parsers[i];
+					const childExec$1 = require_execution_context.withChildExecPath(phase3Exec, i);
+					const preCompletedResult = preCompleted.get(String(i));
+					const seed = preCompletedResult !== void 0 ? await reusePreCompletedPhase2SeedAsync(elementParser, prepareStateForCompletion(resolvedArray[i], elementParser), preCompletedResult, childExec$1) : await require_phase2_seed.completeOrExtractPhase2Seed(elementParser, prepareStateForCompletion(resolvedArray[i], elementParser), childExec$1);
+					if (seed == null) continue;
+					hasAnySeed = true;
+					result[i] = seed.value;
+					if (seed.deferred) if (seed.deferredKeys) deferredKeys.set(i, seed.deferredKeys);
+					else if (seed.value == null || typeof seed.value !== "object") deferredKeys.set(i, null);
+					else hasDeferred = true;
+				}
+				if (!hasAnySeed) return null;
+				return {
+					value: result,
+					...deferredKeys.size > 0 || hasDeferred ? {
+						deferred: true,
+						...deferredKeys.size > 0 ? { deferredKeys } : {}
+					} : {}
+				};
+			});
+		},
+		suggest(context, prefix) {
+			return require_mode_dispatch.dispatchIterableByMode(combinedMode, () => {
+				const suggestions = [];
+				const advancedContext = advanceSeqSuggestContextSync(context, syncParsers, initialState.states);
+				const runtime = require_dependency_runtime.createDependencyRuntimeContext(advancedContext.dependencyRegistry?.clone());
+				const state = advancedContext.state;
+				const stateArray = state.states;
+				const nodes = buildSuggestRuntimeNodesFromArray(syncParsers, stateArray, advancedContext.exec?.path);
+				require_dependency_runtime.collectExplicitSourceValues(nodes, runtime);
+				require_dependency_runtime.fillMissingSourceDefaults(nodes, runtime);
+				require_dependency_runtime.collectSourcesFromState(stateArray, runtime);
+				completeDependencySourceDefaults({
+					...advancedContext,
+					state: createAnnotatedArrayStateRecord(stateArray)
+				}, buildIndexedParserPairs(syncParsers), runtime.registry, advancedContext.exec);
+				const contextWithRegistry = {
+					...advancedContext,
+					dependencyRegistry: runtime.registry,
+					...advancedContext.exec != null ? { exec: {
+						...advancedContext.exec,
+						dependencyRuntime: runtime,
+						dependencyRegistry: runtime.registry
+					} } : {}
+				};
+				for (let i = state.index; i < syncParsers.length; i++) {
+					const parser = syncParsers[i];
+					const parserState = getSeqChildState(state, i, parser);
+					suggestions.push(...parser.suggest(withChildContext$1(contextWithRegistry, i, parserState, parser), prefix));
+					if (parser.canSkip?.(parserState, require_execution_context.withChildExecPath(contextWithRegistry.exec, i)) !== true) break;
+				}
+				return require_suggestion.deduplicateSuggestions(suggestions);
+			}, async function* () {
+				const suggestions = [];
+				const advancedContext = await advanceSeqSuggestContextAsync(context, parsers, initialState.states);
+				const runtime = require_dependency_runtime.createDependencyRuntimeContext(advancedContext.dependencyRegistry?.clone());
+				const state = advancedContext.state;
+				const stateArray = state.states;
+				const nodes = buildSuggestRuntimeNodesFromArray(parsers, stateArray, advancedContext.exec?.path);
+				await require_dependency_runtime.collectExplicitSourceValuesAsync(nodes, runtime);
+				await require_dependency_runtime.fillMissingSourceDefaultsAsync(nodes, runtime);
+				require_dependency_runtime.collectSourcesFromState(stateArray, runtime);
+				await completeDependencySourceDefaultsAsync({
+					...advancedContext,
+					state: createAnnotatedArrayStateRecord(stateArray)
+				}, buildIndexedParserPairs(parsers), runtime.registry, advancedContext.exec);
+				const contextWithRegistry = {
+					...advancedContext,
+					dependencyRegistry: runtime.registry,
+					...advancedContext.exec != null ? { exec: {
+						...advancedContext.exec,
+						dependencyRuntime: runtime,
+						dependencyRegistry: runtime.registry
+					} } : {}
+				};
+				for (let i = state.index; i < parsers.length; i++) {
+					const parser = parsers[i];
+					const parserState = getSeqChildState(state, i, parser);
+					const parserSuggestions = parser.suggest(withChildContext$1(contextWithRegistry, i, parserState, parser), prefix);
+					if (parser.mode === "async") for await (const suggestion of parserSuggestions) suggestions.push(suggestion);
+					else suggestions.push(...parserSuggestions);
+					if (parser.canSkip?.(parserState, require_execution_context.withChildExecPath(contextWithRegistry.exec, i)) !== true) break;
+				}
+				yield* require_suggestion.deduplicateSuggestions(suggestions);
+			});
+		},
+		getDocFragments(state, defaultValue) {
+			const fragments = syncParsers.flatMap((parser, index) => {
+				const indexState = state.kind === "unavailable" ? { kind: "unavailable" } : {
+					kind: "available",
+					state: state.state.states[index]
+				};
+				return parser.getDocFragments(indexState, defaultValue?.[index]).fragments;
+			});
+			const entries = fragments.filter((d) => d.type === "entry");
+			const sections = [];
+			for (const fragment of fragments) {
+				if (fragment.type !== "section") continue;
+				if (fragment.title == null) entries.push(...fragment.entries);
+				else sections.push(fragment);
+			}
+			sections.push({
+				title: label,
+				entries
+			});
+			return { fragments: sections.map((s) => ({
+				...s,
+				type: "section"
+			})) };
+		},
+		[Symbol.for("Deno.customInspect")]() {
+			const parsersStr = parsers.length === 1 ? "1 parser" : `${parsers.length} parsers`;
+			return label == null ? `seq(${parsersStr})` : `seq(${JSON.stringify(label)}, ${parsersStr})`;
+		}
+	};
+	Object.defineProperty(seqParser, "complete", {
+		value: createSeqComplete(parsers, combinedMode),
+		configurable: true,
+		enumerable: true
+	});
+	const normalizers = [];
+	for (let i = 0; i < parsers.length; i++) {
+		const parser = parsers[i];
+		if (typeof parser.normalizeValue === "function") normalizers.push([i, parser.normalizeValue.bind(parser)]);
+	}
+	if (normalizers.length > 0) Object.defineProperty(seqParser, "normalizeValue", {
+		value(arr) {
+			if (!Array.isArray(arr)) return arr;
+			let changed = false;
+			let result;
+			for (const [index, normalize] of normalizers) if (index < arr.length && Object.hasOwn(arr, index)) try {
+				const original = arr[index];
+				const normalized = normalize(original);
+				if (normalized !== original) {
+					result ??= [...arr];
+					result[index] = normalized;
+					changed = true;
+				}
+			} catch {}
+			return changed ? result : arr;
+		},
+		configurable: true,
+		enumerable: false
+	});
+	require_internal_parser.defineInheritedAnnotationParser(seqParser);
+	return seqParser;
+}
 function merge(...args) {
 	const label = typeof args[0] === "string" ? args[0] : void 0;
 	if (label != null) require_validate.validateLabel(label);
@@ -2936,6 +3718,7 @@ function merge(...args) {
 	const syncSorted = syncWithIndex.toSorted(([a], [b]) => b.priority - a.priority);
 	const syncParsers = syncSorted.map(([p]) => p);
 	if (!options.allowDuplicates) checkDuplicateOptionNames(sorted.map(([parser, originalIndex]) => [String(originalIndex), parser.usage]));
+	checkDuplicateReachableLeadingCommandNames(sorted.map(([parser, originalIndex]) => [String(originalIndex), parser]));
 	const mergedFieldParsers = collectChildFieldParsers(parsers);
 	const duplicateOutputFieldNames = collectDuplicateFieldNames(mergedFieldParsers);
 	const parserStateKey = (index) => `__parser_${index}`;
@@ -2947,23 +3730,24 @@ function merge(...args) {
 		if (parser.initialState === void 0) initialState[parserStateKey(i)] = void 0;
 		else if (parser.initialState && typeof parser.initialState === "object") for (const field in parser.initialState) initialState[field] = parser.initialState[field];
 	}
-	const extractParserState = (parser, context, index) => {
+	const extractParserStateFromState = (parser, state, index) => {
 		if (parser.initialState === void 0) {
 			const key = parserStateKey(index);
-			if (context.state && typeof context.state === "object" && key in context.state) return context.state[key];
+			if (state && typeof state === "object" && key in state) return state[key];
 			return void 0;
 		} else if (parser.initialState && typeof parser.initialState === "object") {
 			const localStateKey = localObjectStateKey(index);
-			if (shouldPreserveLocalChildState(parser) && context.state && typeof context.state === "object" && localStateKey in context.state) return context.state[localStateKey];
-			if (context.state && typeof context.state === "object") {
+			if (shouldPreserveLocalChildState(parser) && state && typeof state === "object" && localStateKey in state) return state[localStateKey];
+			if (state && typeof state === "object") {
 				const extractedState = {};
-				for (const field in parser.initialState) extractedState[field] = field in context.state ? context.state[field] : parser.initialState[field];
+				for (const field in parser.initialState) extractedState[field] = field in state ? state[field] : parser.initialState[field];
 				return extractedState;
 			}
 			return parser.initialState;
 		}
 		return parser.initialState;
 	};
+	const extractParserState = (parser, context, index) => extractParserStateFromState(parser, context.state, index);
 	const mergeResultState = (parser, context, parserState, result, index) => {
 		if (parser.initialState === void 0) {
 			const key = parserStateKey(index);
@@ -3088,6 +3872,12 @@ function merge(...args) {
 		leadingNames: sharedBufferLeadingNames(parsers),
 		acceptingAnyToken: parsers.some((p) => p.acceptingAnyToken),
 		initialState,
+		canSkip(state, exec) {
+			return parsers.every((parser, index) => {
+				const parserState = extractParserStateFromState(parser, state, index);
+				return parser.canSkip?.(require_annotation_state.getWrappedChildState(state, parserState, parser), require_execution_context.withChildExecPath(exec, index)) === true;
+			});
+		},
 		parse(context) {
 			if (isAsync) return parseAsync(context);
 			return parseSync(context);
@@ -3104,8 +3894,8 @@ function merge(...args) {
 					if (resolvedState && typeof resolvedState === "object") {
 						const extractedState = {};
 						for (const field in parser.initialState) extractedState[field] = field in resolvedState ? resolvedState[field] : parser.initialState[field];
-						const annotations = require_annotations.getAnnotations(resolvedState);
-						if (annotations !== void 0) return require_annotations.inheritAnnotations(resolvedState, extractedState);
+						const annotations = require_internal_annotations.getAnnotations(resolvedState);
+						if (annotations !== void 0) return require_internal_annotations.inheritAnnotations(resolvedState, extractedState);
 						return extractedState;
 					}
 					return parser.initialState;
@@ -3258,7 +4048,7 @@ function merge(...args) {
 					if (resolvedState && typeof resolvedState === "object") {
 						const extractedState = {};
 						for (const field in parser.initialState) extractedState[field] = field in resolvedState ? resolvedState[field] : parser.initialState[field];
-						return require_annotations.inheritAnnotations(resolvedState, extractedState);
+						return require_internal_annotations.inheritAnnotations(resolvedState, extractedState);
 					}
 					return parser.initialState;
 				}
@@ -3555,7 +4345,7 @@ function merge(...args) {
 			};
 		}
 	};
-	require_parser.defineInheritedAnnotationParser(mergeParser);
+	require_internal_parser.defineInheritedAnnotationParser(mergeParser);
 	return mergeParser;
 }
 /**
@@ -3691,7 +4481,7 @@ async function seedSuggestRuntimeFromFieldParsersAsync(parser, state, runtime, p
 */
 function preParseSuggestContext(context, parsers) {
 	if (context.buffer.length < 1 || !Array.isArray(context.state)) return context;
-	return preParseSuggestLoop(context, require_annotations.annotateFreshArray(context.state, context.state.slice()), parsers);
+	return preParseSuggestLoop(context, require_internal_annotations.annotateFreshArray(context.state, context.state.slice()), parsers);
 }
 /**
 * Async variant of {@link preParseSuggestContext} that awaits async child
@@ -3700,7 +4490,7 @@ function preParseSuggestContext(context, parsers) {
 */
 async function preParseSuggestContextAsync(context, parsers) {
 	if (context.buffer.length < 1 || !Array.isArray(context.state)) return context;
-	return await preParseSuggestLoop(context, require_annotations.annotateFreshArray(context.state, context.state.slice()), parsers);
+	return await preParseSuggestLoop(context, require_internal_annotations.annotateFreshArray(context.state, context.state.slice()), parsers);
 }
 /**
 * Shared loop for sync and async concat suggest pre-parse.  When a child
@@ -3807,7 +4597,7 @@ function concat(...parsers) {
 			for (const [parser, index] of remainingParsers) {
 				const result = parser.parse(withChildContext$1(currentContext, index, stateArray[index], parser));
 				if (result.success && result.consumed.length > 0) {
-					const newStateArray = require_annotations.annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? require_annotation_state.getWrappedChildState(currentContext.state, result.next.state, parser) : s));
+					const newStateArray = require_internal_annotations.annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? require_annotation_state.getWrappedChildState(currentContext.state, result.next.state, parser) : s));
 					const mergedExec = require_execution_context.mergeChildExec(currentContext.exec, result.next.exec);
 					currentContext = {
 						...currentContext,
@@ -3828,7 +4618,7 @@ function concat(...parsers) {
 			if (!foundMatch) for (const [parser, index] of remainingParsers) {
 				const result = parser.parse(withChildContext$1(currentContext, index, stateArray[index], parser));
 				if (result.success && result.consumed.length < 1) {
-					const newStateArray = require_annotations.annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? require_annotation_state.getWrappedChildState(currentContext.state, result.next.state, parser) : s));
+					const newStateArray = require_internal_annotations.annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? require_annotation_state.getWrappedChildState(currentContext.state, result.next.state, parser) : s));
 					const mergedExec = require_execution_context.mergeChildExec(currentContext.exec, result.next.exec);
 					currentContext = {
 						...currentContext,
@@ -3873,7 +4663,7 @@ function concat(...parsers) {
 			for (const [parser, index] of remainingParsers) {
 				const result = await parser.parse(withChildContext$1(currentContext, index, stateArray[index], parser));
 				if (result.success && result.consumed.length > 0) {
-					const newStateArray = require_annotations.annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? require_annotation_state.getWrappedChildState(currentContext.state, result.next.state, parser) : s));
+					const newStateArray = require_internal_annotations.annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? require_annotation_state.getWrappedChildState(currentContext.state, result.next.state, parser) : s));
 					const mergedExec = require_execution_context.mergeChildExec(currentContext.exec, result.next.exec);
 					currentContext = {
 						...currentContext,
@@ -3894,7 +4684,7 @@ function concat(...parsers) {
 			if (!foundMatch) for (const [parser, index] of remainingParsers) {
 				const result = await parser.parse(withChildContext$1(currentContext, index, stateArray[index], parser));
 				if (result.success && result.consumed.length < 1) {
-					const newStateArray = require_annotations.annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? require_annotation_state.getWrappedChildState(currentContext.state, result.next.state, parser) : s));
+					const newStateArray = require_internal_annotations.annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? require_annotation_state.getWrappedChildState(currentContext.state, result.next.state, parser) : s));
 					const mergedExec = require_execution_context.mergeChildExec(currentContext.exec, result.next.exec);
 					currentContext = {
 						...currentContext,
@@ -4033,6 +4823,10 @@ function concat(...parsers) {
 		leadingNames: sharedBufferLeadingNames(parsers),
 		acceptingAnyToken: parsers.some((p) => p.acceptingAnyToken),
 		initialState,
+		canSkip(state, exec) {
+			const stateArray = state;
+			return parsers.every((parser, index) => parser.canSkip?.(require_annotation_state.getWrappedChildState(stateArray, stateArray[index], parser), require_execution_context.withChildExecPath(exec, index)) === true);
+		},
 		parse(context) {
 			if (isAsync) return parseAsync(context);
 			return parseSync(context);
@@ -4165,7 +4959,7 @@ function concat(...parsers) {
 			return { fragments: result };
 		}
 	};
-	require_parser.defineInheritedAnnotationParser(concatParser);
+	require_internal_parser.defineInheritedAnnotationParser(concatParser);
 	return concatParser;
 }
 function group(label, parser, options = {}) {
@@ -4181,6 +4975,7 @@ function group(label, parser, options = {}) {
 		initialState: parser.initialState,
 		...fieldParsersKey in parser ? { [fieldParsersKey]: parser[fieldParsersKey] } : {},
 		...typeof parser.shouldDeferCompletion === "function" ? { shouldDeferCompletion: parser.shouldDeferCompletion.bind(parser) } : {},
+		...typeof parser.canSkip === "function" ? { canSkip: parser.canSkip.bind(parser) } : {},
 		getSuggestRuntimeNodes(state, path) {
 			return parser.getSuggestRuntimeNodes?.(state, path) ?? (parser.dependencyMetadata?.source != null ? [{
 				path,
@@ -4338,6 +5133,10 @@ function conditional(discriminator, branches, defaultBranch, options) {
 			...term,
 			terms: appendLiteralToUsage(term.terms, literalValue)
 		});
+		else if (term.type === "sequence") result.push({
+			...term,
+			terms: appendLiteralToUsage(term.terms, literalValue)
+		});
 		else if (term.type === "exclusive") result.push({
 			...term,
 			terms: term.terms.map((t) => appendLiteralToUsage(t, literalValue))
@@ -5220,7 +6019,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 			return { fragments };
 		}
 	};
-	require_parser.defineInheritedAnnotationParser(conditionalParser);
+	require_internal_parser.defineInheritedAnnotationParser(conditionalParser);
 	return conditionalParser;
 }
 
@@ -5233,4 +6032,5 @@ exports.longestMatch = longestMatch;
 exports.merge = merge;
 exports.object = object;
 exports.or = or;
+exports.seq = seq;
 exports.tuple = tuple;