@optique/core 1.4.0-dev.2636 → 1.4.0-dev.2661

package/dist/constructs.js

@@ -11,6 +11,7 @@ import { annotationViewTargets, getWrappedChildParseState, getWrappedChildState,
 import { mergeChildExec, withChildContext, withChildExecPath } from "./execution-context.js";
 import { collectLeadingCandidates } from "./usage-internals.js";
 import { adoptOptionScope, combinedOptionScope, conditionalOptionScope, forkOptionScope, restoreOptionScope, scopeParser, selectableOptionScope, withOptionScope, withParserOptionScope } from "./short-option.js";
+import { combineOptionMatches, combinePassThroughPriorities, defineOptionMatch, definePassThroughPriority, delegateKnownCompletion, getKnownCompletion, getOptionMatch, getPassThroughFailureHint, getPassThroughPriority, hasPassThroughUsage, matchesOptionToken, retainConsumingFailure, retainConsumingFailureHint, withPassThroughFailure } from "./internal/passthrough.js";
 import { allowDuplicateLeadingCommandNamesKey } from "./internal/command-alias.js";
 import { completeOrExtractPhase2Seed, extractPhase2Seed, extractPhase2SeedKey, phase2SeedFromValueResult } from "./phase2-seed.js";
 import { fluent } from "./modifiers.js";
@@ -605,6 +606,63 @@ function sharedBufferLeadingNames(parsers) {
 	return names.size === 0 ? EMPTY_LEADING_NAMES : names;
 }
 /**
+* Defers capture until a known option at an equal or higher lane priority
+* has been tried.
+* Other siblings retain their relative order, and explicit priorities win.
+*/
+function orderBeforePassThrough(pairs, context, getParser, getState, passThroughParsers) {
+	const token = context.buffer[0];
+	if (passThroughParsers.size === 0 || context.optionsTerminated || token == null || token === "--" || !/^[-/+]/.test(token)) return pairs;
+	const matches = new Map(pairs.map((pair) => [pair, getOptionMatch(getParser(pair), getState(pair), token)]));
+	const normalizedOptions = /* @__PURE__ */ new Map();
+	const captures = new Map(pairs.flatMap((pair) => {
+		if (!passThroughParsers.has(getParser(pair))) return [];
+		const priority = getPassThroughPriority(getParser(pair), getState(pair), token);
+		const match = matches.get(pair);
+		if (match != null && (priority == null || match.priority >= priority)) {
+			const unfiltered = getPassThroughPriority(getParser(pair), getState(pair));
+			if (priority == null || unfiltered != null && unfiltered > match.priority) normalizedOptions.set(pair, match.priority);
+			return [];
+		}
+		return priority == null ? [] : [[pair, priority]];
+	}));
+	const matching = pairs.filter((pair) => !captures.has(pair)).flatMap((pair) => {
+		const match = matches.get(pair);
+		return match == null ? [] : [match];
+	});
+	const orderedCaptures = [...captures].sort((a, b) => b[1] - a[1]);
+	if (matching.length === 0) {
+		let captureIndex = 0;
+		return pairs.map((pair) => captures.has(pair) ? orderedCaptures[captureIndex++][0] : pair);
+	}
+	const matchingPriority = Math.max(...matching.map((match) => match.priority));
+	const ordinary = pairs.filter((pair) => !captures.has(pair) && !normalizedOptions.has(pair));
+	const positions = new Map(pairs.map((pair, index) => [pair, index]));
+	for (const [pair, priority] of [...normalizedOptions].sort((a, b) => b[1] - a[1])) {
+		let insertion = ordinary.findIndex((candidate) => {
+			const match = matches.get(candidate);
+			return match != null && (match.priority < priority || match.priority === priority && positions.get(pair) < positions.get(candidate));
+		});
+		if (insertion < 0) {
+			const lastMatch = ordinary.findLastIndex((candidate) => matches.get(candidate) != null);
+			insertion = lastMatch >= 0 ? lastMatch + 1 : ordinary.findIndex((candidate) => positions.get(candidate) > positions.get(pair));
+			if (insertion < 0) insertion = ordinary.length;
+		}
+		ordinary.splice(insertion, 0, pair);
+	}
+	const first = ordinary.findIndex((pair) => matches.get(pair) != null);
+	const last = ordinary.findLastIndex((pair) => matches.get(pair) != null);
+	const before = orderedCaptures.filter(([, priority]) => priority > matchingPriority).map(([pair]) => pair);
+	const after = orderedCaptures.filter(([, priority]) => priority <= matchingPriority).map(([pair]) => pair);
+	return [
+		...ordinary.slice(0, first),
+		...before,
+		...ordinary.slice(first, last + 1),
+		...after,
+		...ordinary.slice(last + 1)
+	];
+}
+/**
 * Internal symbol for exposing field-level parser pairs from `object()`
 * and `merge()` parsers.  This allows `merge()` to pre-complete dependency
 * source fields from child parsers before resolving deferred states.
@@ -1114,6 +1172,7 @@ function preserveExclusiveStateAfterOptionsTerminator(context, result) {
 		success: true,
 		next: {
 			...context,
+			...getPassThroughFailureHint(result.next),
 			buffer: result.next.buffer,
 			optionsTerminated: true,
 			state: context.state,
@@ -1448,6 +1507,7 @@ function or(...args) {
 							success: true,
 							next: {
 								...adoptOptionScope(context, result.next),
+								...getPassThroughFailureHint(result.next),
 								buffer: result.next.buffer,
 								optionsTerminated: result.next.optionsTerminated,
 								state: createExclusiveState(context.state, i, parser, result),
@@ -1484,6 +1544,7 @@ function or(...args) {
 						success: true,
 						next: {
 							...adoptOptionScope(context, replayedResult.next),
+							...getPassThroughFailureHint(replayedResult.next),
 							buffer: replayedResult.next.buffer,
 							optionsTerminated: replayedResult.next.optionsTerminated,
 							state: createExclusiveState(context.state, i, parser, {
@@ -1503,6 +1564,7 @@ function or(...args) {
 					success: true,
 					next: {
 						...adoptOptionScope(context, result.next),
+						...getPassThroughFailureHint(result.next),
 						buffer: result.next.buffer,
 						optionsTerminated: result.next.optionsTerminated,
 						state: createExclusiveState(context.state, i, parser, result),
@@ -1547,6 +1609,7 @@ function or(...args) {
 					provisional: true,
 					next: {
 						...adoptOptionScope(context, provisionalConsuming.result.next),
+						...getPassThroughFailureHint(provisionalConsuming.result.next),
 						buffer: provisionalConsuming.result.next.buffer,
 						optionsTerminated: provisionalConsuming.result.next.optionsTerminated,
 						state: createExclusiveState(context.state, provisionalConsuming.index, provisionalConsuming.parser, provisionalConsuming.result),
@@ -1581,6 +1644,7 @@ function or(...args) {
 						provisional: true,
 						next: {
 							...adoptOptionScope(context, replayedResult.next),
+							...getPassThroughFailureHint(replayedResult.next),
 							buffer: replayedResult.next.buffer,
 							optionsTerminated: replayedResult.next.optionsTerminated,
 							state: createExclusiveState(context.state, provisionalConsuming.index, provisionalConsuming.parser, {
@@ -1652,6 +1716,7 @@ function or(...args) {
 							success: true,
 							next: {
 								...adoptOptionScope(context, result.next),
+								...getPassThroughFailureHint(result.next),
 								buffer: result.next.buffer,
 								optionsTerminated: result.next.optionsTerminated,
 								state: createExclusiveState(context.state, i, parser, result),
@@ -1690,6 +1755,7 @@ function or(...args) {
 						success: true,
 						next: {
 							...adoptOptionScope(context, replayedResult.next),
+							...getPassThroughFailureHint(replayedResult.next),
 							buffer: replayedResult.next.buffer,
 							optionsTerminated: replayedResult.next.optionsTerminated,
 							state: createExclusiveState(context.state, i, parser, {
@@ -1709,6 +1775,7 @@ function or(...args) {
 					success: true,
 					next: {
 						...adoptOptionScope(context, result.next),
+						...getPassThroughFailureHint(result.next),
 						buffer: result.next.buffer,
 						optionsTerminated: result.next.optionsTerminated,
 						state: createExclusiveState(context.state, i, parser, result),
@@ -1753,6 +1820,7 @@ function or(...args) {
 					provisional: true,
 					next: {
 						...adoptOptionScope(context, provisionalConsuming.result.next),
+						...getPassThroughFailureHint(provisionalConsuming.result.next),
 						buffer: provisionalConsuming.result.next.buffer,
 						optionsTerminated: provisionalConsuming.result.next.optionsTerminated,
 						state: createExclusiveState(context.state, provisionalConsuming.index, provisionalConsuming.parser, provisionalConsuming.result),
@@ -1787,6 +1855,7 @@ function or(...args) {
 						provisional: true,
 						next: {
 							...adoptOptionScope(context, replayedResult.next),
+							...getPassThroughFailureHint(replayedResult.next),
 							buffer: replayedResult.next.buffer,
 							optionsTerminated: replayedResult.next.optionsTerminated,
 							state: createExclusiveState(context.state, provisionalConsuming.index, provisionalConsuming.parser, {
@@ -1879,6 +1948,14 @@ function or(...args) {
 	if (singleDependencyMetadata != null) singleResult.dependencyMetadata = singleDependencyMetadata;
 	defineExclusiveSchedulingNodes(singleResult, parsers);
 	defineInheritedAnnotationParser(singleResult);
+	defineOptionMatch(singleResult, (state, token) => combineOptionMatches(parsers.map((parser, index) => {
+		const active = normalizeExclusiveState(state);
+		return getOptionMatch(parser, active?.[0] === index && active[1].success ? active[1].next.state : parser.initialState, token);
+	})));
+	definePassThroughPriority(singleResult, parsers, (state, token) => {
+		const active = normalizeExclusiveState(state);
+		return combinePassThroughPriorities(parsers.map((parser, index) => getPassThroughPriority(parser, active?.[0] === index && active[1].success ? active[1].next.state : parser.initialState, token)));
+	});
 	return fluent(scopeParser(singleResult, combinedOptionScope(parsers, parsers.map((_, index) => index))));
 }
 /**
@@ -1913,24 +1990,27 @@ function createLongestMatch(...args) {
 			return createUnexpectedInputErrorWithScopedSuggestions(defaultMsg, token, parsers, options?.errors?.suggestions);
 		})()
 	});
-	const commitLongestMatch = (context, match, optionsTerminatorResult) => {
+	const commitLongestMatch = (context, match, optionsTerminatorResult, consumingFailure) => {
 		const selectedResult = optionsTerminatorResult == null ? match.result : {
 			...match.result,
 			next: {
 				...match.result.next,
+				...getPassThroughFailureHint(optionsTerminatorResult.next),
 				buffer: optionsTerminatorResult.next.buffer,
 				optionsTerminated: true
 			},
 			consumed: [...optionsTerminatorResult.consumed, ...match.result.consumed]
 		};
+		const next = selectedResult.consumed.length === 0 ? withPassThroughFailure(selectedResult.next, consumingFailure) : selectedResult.next;
 		const parser = parsers[match.index];
-		const mergedExec = mergeChildExec(context.exec, selectedResult.next.exec);
+		const mergedExec = mergeChildExec(context.exec, next.exec);
 		return {
 			success: true,
 			next: {
-				...adoptOptionScope(context, selectedResult.next),
-				buffer: selectedResult.next.buffer,
-				optionsTerminated: selectedResult.next.optionsTerminated,
+				...adoptOptionScope(context, next),
+				...getPassThroughFailureHint(next),
+				buffer: next.buffer,
+				optionsTerminated: next.optionsTerminated,
 				state: createExclusiveState(context.state, match.index, parser, selectedResult),
 				...mergedExec != null ? {
 					exec: mergedExec,
@@ -1965,6 +2045,7 @@ function createLongestMatch(...args) {
 		let bestMatch = null;
 		const optionsTerminatorMatches = [];
 		let error = getInitialError(context);
+		let consumingFailure;
 		const activeState = normalizeExclusiveState(context.state);
 		for (let i = 0; i < syncParsers.length; i++) {
 			const parser = syncParsers[i];
@@ -1980,6 +2061,7 @@ function createLongestMatch(...args) {
 				continue;
 			}
 			if (result.success) {
+				consumingFailure = retainConsumingFailureHint(consumingFailure, context, result.next);
 				const consumed = context.buffer.length - result.next.buffer.length;
 				const bestIsProvisional = bestMatch != null && bestMatch.result.success && !!bestMatch.result.provisional;
 				if (bestMatch === null || consumed > bestMatch.consumed || consumed === bestMatch.consumed && bestIsProvisional && !result.provisional) bestMatch = {
@@ -1987,11 +2069,15 @@ function createLongestMatch(...args) {
 					result,
 					consumed
 				};
-			} else if (error.consumed < result.consumed) error = result;
+			} else {
+				const match = getOptionMatch(parser, childContext.state, context.buffer[0]);
+				if (result.consumed > 0 && match != null) consumingFailure = retainConsumingFailure(consumingFailure, result, match.priority);
+				if (error.consumed < result.consumed) error = result;
+			}
 		}
 		const optionsTerminatorResolution = resolveLongestMatchOptionsTerminator(context, bestMatch, optionsTerminatorMatches);
 		if (optionsTerminatorResolution != null) return optionsTerminatorResolution;
-		if (bestMatch != null) return commitLongestMatch(context, bestMatch);
+		if (bestMatch != null) return commitLongestMatch(context, bestMatch, void 0, consumingFailure);
 		return {
 			...error,
 			success: false
@@ -2001,6 +2087,7 @@ function createLongestMatch(...args) {
 		let bestMatch = null;
 		const optionsTerminatorMatches = [];
 		let error = getInitialError(context);
+		let consumingFailure;
 		const activeState = normalizeExclusiveState(context.state);
 		for (let i = 0; i < parsers.length; i++) {
 			const parser = parsers[i];
@@ -2017,6 +2104,7 @@ function createLongestMatch(...args) {
 				continue;
 			}
 			if (result.success) {
+				consumingFailure = retainConsumingFailureHint(consumingFailure, context, result.next);
 				const consumed = context.buffer.length - result.next.buffer.length;
 				const bestIsProvisional = bestMatch != null && bestMatch.result.success && !!bestMatch.result.provisional;
 				if (bestMatch === null || consumed > bestMatch.consumed || consumed === bestMatch.consumed && bestIsProvisional && !result.provisional) bestMatch = {
@@ -2024,11 +2112,15 @@ function createLongestMatch(...args) {
 					result,
 					consumed
 				};
-			} else if (error.consumed < result.consumed) error = result;
+			} else {
+				const match = getOptionMatch(parser, childContext.state, context.buffer[0]);
+				if (result.consumed > 0 && match != null) consumingFailure = retainConsumingFailure(consumingFailure, result, match.priority);
+				if (error.consumed < result.consumed) error = result;
+			}
 		}
 		const optionsTerminatorResolution = resolveLongestMatchOptionsTerminator(context, bestMatch, optionsTerminatorMatches);
 		if (optionsTerminatorResolution != null) return optionsTerminatorResolution;
-		if (bestMatch != null) return commitLongestMatch(context, bestMatch);
+		if (bestMatch != null) return commitLongestMatch(context, bestMatch, void 0, consumingFailure);
 		return {
 			...error,
 			success: false
@@ -2101,6 +2193,14 @@ function createLongestMatch(...args) {
 	if (multiDependencyMetadata != null) multiResult.dependencyMetadata = multiDependencyMetadata;
 	defineExclusiveSchedulingNodes(multiResult, parsers);
 	defineInheritedAnnotationParser(multiResult);
+	defineOptionMatch(multiResult, (state, token) => combineOptionMatches(parsers.map((parser, index) => {
+		const active = normalizeExclusiveState(state);
+		return getOptionMatch(parser, active?.[0] === index && active[1].success ? active[1].next.state : parser.initialState, token);
+	})));
+	definePassThroughPriority(multiResult, parsers, (state, token) => {
+		const active = normalizeExclusiveState(state);
+		return combinePassThroughPriorities(parsers.map((parser, index) => getPassThroughPriority(parser, active?.[0] === index && active[1].success ? active[1].next.state : parser.initialState, token)));
+	});
 	return fluent(scopeParser(multiResult, combinedOptionScope(parsers, parsers.map((_, index) => index))));
 }
 /**
@@ -2504,6 +2604,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 	const parserKeys = Reflect.ownKeys(parsers);
 	const parserPairs = parserKeys.map((k) => [k, parsers[k]]);
 	parserPairs.sort(([_, parserA], [__, parserB]) => parserB.priority - parserA.priority);
+	const passThroughParsers = new Set(parserPairs.map(([, parser]) => parser).filter((parser) => hasPassThroughUsage(parser.usage)));
 	const createInitialState = () => {
 		const state = {};
 		for (const key of parserKeys) state[key] = parsers[key].initialState;
@@ -2554,6 +2655,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			success: true,
 			next: {
 				...context,
+				...getPassThroughFailureHint(result.next),
 				buffer: result.next.buffer,
 				optionsTerminated: result.next.optionsTerminated,
 				state: nextState,
@@ -2590,17 +2692,20 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		let anySuccess = false;
 		const allConsumed = [];
 		const consumedFields = /* @__PURE__ */ new Set();
+		let consumingFailure;
 		let madeProgress = true;
 		while (madeProgress && currentContext.buffer.length > 0) {
 			madeProgress = false;
+			consumingFailure = void 0;
 			const getFieldState = createFieldStateGetter(currentContext.state, getObjectParseChildState);
-			for (const [field, parser] of parserPairs) {
-				const result = parser.parse(withChildContext$1(forkOptionScope(currentContext), field, getFieldState(field, parser), parser));
+			for (const [field, parser] of orderBeforePassThrough(parserPairs, currentContext, ([, parser$1]) => parser$1, ([field$1, parser$1]) => getFieldState(field$1, parser$1), passThroughParsers)) {
+				const result = parser.parse(withPassThroughFailure(withChildContext$1(forkOptionScope(currentContext), field, getFieldState(field, parser), parser), consumingFailure, getPassThroughPriority(parser, getFieldState(field, parser), currentContext.buffer[0])));
 				if (result.success && result.consumed.length > 0) {
 					adoptOptionScope(currentContext, result.next);
 					const mergedExec = mergeChildExec(currentContext.exec, result.next.exec);
 					currentContext = {
 						...currentContext,
+						...getPassThroughFailureHint(result.next),
 						buffer: result.next.buffer,
 						optionsTerminated: result.next.optionsTerminated,
 						state: {
@@ -2618,7 +2723,12 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 					madeProgress = true;
 					consumedFields.add(field);
 					break;
-				} else if (!result.success && error.consumed < result.consumed) error = result;
+				} else if (result.success) consumingFailure = retainConsumingFailureHint(consumingFailure, currentContext, result.next);
+				else {
+					const match = getOptionMatch(parser, getFieldState(field, parser), currentContext.buffer[0]);
+					if (result.consumed > 0 && match != null) consumingFailure = retainConsumingFailure(consumingFailure, result, match.priority);
+					if (error.consumed < result.consumed) error = result;
+				}
 			}
 		}
 		{
@@ -2628,7 +2738,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 				const typedParser = parser;
 				if (parser.leadingNames.size > 0 || typedParser.acceptingAnyToken) continue;
 				const fieldState = getFieldState(field, parser);
-				const result = typedParser.parse(withChildContext$1(forkOptionScope(currentContext), field, fieldState, parser));
+				const result = typedParser.parse(withPassThroughFailure(withChildContext$1(forkOptionScope(currentContext), field, fieldState, parser), consumingFailure, getPassThroughPriority(parser, getFieldState(field, parser), currentContext.buffer[0])));
 				if (result.success && result.consumed.length === 0 && result.next.state !== fieldState) {
 					adoptOptionScope(currentContext, result.next);
 					const mergedExec = mergeChildExec(currentContext.exec, result.next.exec);
@@ -2649,7 +2759,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		}
 		if (anySuccess) return {
 			success: true,
-			next: currentContext,
+			next: withPassThroughFailure(currentContext, consumingFailure),
 			consumed: allConsumed
 		};
 		if (currentContext.buffer.length === 0) {
@@ -2698,18 +2808,21 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		let anySuccess = false;
 		const allConsumed = [];
 		const consumedFields = /* @__PURE__ */ new Set();
+		let consumingFailure;
 		let madeProgress = true;
 		while (madeProgress && currentContext.buffer.length > 0) {
 			madeProgress = false;
+			consumingFailure = void 0;
 			const getFieldState = createFieldStateGetter(currentContext.state, getObjectParseChildState);
-			for (const [field, parser] of parserPairs) {
-				const resultOrPromise = parser.parse(withChildContext$1(forkOptionScope(currentContext), field, getFieldState(field, parser), parser));
+			for (const [field, parser] of orderBeforePassThrough(parserPairs, currentContext, ([, parser$1]) => parser$1, ([field$1, parser$1]) => getFieldState(field$1, parser$1), passThroughParsers)) {
+				const resultOrPromise = parser.parse(withPassThroughFailure(withChildContext$1(forkOptionScope(currentContext), field, getFieldState(field, parser), parser), consumingFailure, getPassThroughPriority(parser, getFieldState(field, parser), currentContext.buffer[0])));
 				const result = await resultOrPromise;
 				if (result.success && result.consumed.length > 0) {
 					adoptOptionScope(currentContext, result.next);
 					const mergedExec = mergeChildExec(currentContext.exec, result.next.exec);
 					currentContext = {
 						...currentContext,
+						...getPassThroughFailureHint(result.next),
 						buffer: result.next.buffer,
 						optionsTerminated: result.next.optionsTerminated,
 						state: {
@@ -2727,7 +2840,12 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 					madeProgress = true;
 					consumedFields.add(field);
 					break;
-				} else if (!result.success && error.consumed < result.consumed) error = result;
+				} else if (result.success) consumingFailure = retainConsumingFailureHint(consumingFailure, currentContext, result.next);
+				else {
+					const match = getOptionMatch(parser, getFieldState(field, parser), currentContext.buffer[0]);
+					if (result.consumed > 0 && match != null) consumingFailure = retainConsumingFailure(consumingFailure, result, match.priority);
+					if (error.consumed < result.consumed) error = result;
+				}
 			}
 		}
 		{
@@ -2736,7 +2854,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 				if (consumedFields.has(field)) continue;
 				if (parser.leadingNames.size > 0 || parser.acceptingAnyToken) continue;
 				const fieldState = getFieldState(field, parser);
-				const resultOrPromise = parser.parse(withChildContext$1(forkOptionScope(currentContext), field, fieldState, parser));
+				const resultOrPromise = parser.parse(withPassThroughFailure(withChildContext$1(forkOptionScope(currentContext), field, fieldState, parser), consumingFailure, getPassThroughPriority(parser, getFieldState(field, parser), currentContext.buffer[0])));
 				const result = await resultOrPromise;
 				if (result.success && result.consumed.length === 0 && result.next.state !== fieldState) {
 					adoptOptionScope(currentContext, result.next);
@@ -2758,7 +2876,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		}
 		if (anySuccess) return {
 			success: true,
-			next: currentContext,
+			next: withPassThroughFailure(currentContext, consumingFailure),
 			consumed: allConsumed
 		};
 		if (currentContext.buffer.length === 0) {
@@ -3128,6 +3246,8 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 	});
 	defineParseLanes(objectParser, objectParseLanes);
 	defineInheritedAnnotationParser(objectParser);
+	defineOptionMatch(objectParser, (state, token) => combineOptionMatches(parserPairs.map(([field, parser]) => getOptionMatch(parser, getAnnotatedFieldState(state, typeof field === "number" ? String(field) : field, parser), token))));
+	definePassThroughPriority(objectParser, parserPairs.map(([, parser]) => parser), (state, token) => combinePassThroughPriorities(parserPairs.map(([field, parser]) => getPassThroughPriority(parser, getAnnotatedFieldState(state, typeof field === "number" ? String(field) : field, parser), token))));
 	return fluent(scopeParser(objectParser, combinedOptionScope(parserPairs.map(([, p]) => p), parserPairs.map(([field]) => field)), void 0, true));
 }
 function isParserLike(value) {
@@ -3586,6 +3706,7 @@ function advanceTupleSuggestContextSync(context, parsers) {
 				const mergedExec = mergeChildExec(currentContext.exec, result.next.exec);
 				currentContext = {
 					...currentContext,
+					...getPassThroughFailureHint(result.next),
 					buffer: result.next.buffer,
 					optionsTerminated: result.next.optionsTerminated,
 					state: newStateArray,
@@ -3652,6 +3773,7 @@ async function advanceTupleSuggestContextAsync(context, parsers) {
 				const mergedExec = mergeChildExec(currentContext.exec, result.next.exec);
 				currentContext = {
 					...currentContext,
+					...getPassThroughFailureHint(result.next),
 					buffer: result.next.buffer,
 					optionsTerminated: result.next.optionsTerminated,
 					state: newStateArray,
@@ -3751,10 +3873,12 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 	const combinedMode = parsers.some((p) => p.mode === "async") ? "async" : "sync";
 	const syncParsers = parsers;
 	if (!options.allowDuplicates) checkDuplicateOptionNames(parsers.map((parser, index) => [String(index), parser.usage]));
+	const passThroughParsers = new Set(parsers.filter((parser) => hasPassThroughUsage(parser.usage)));
 	const parseSync = (context) => {
 		let currentContext = context;
 		const allConsumed = [];
 		const matchedParsers = /* @__PURE__ */ new Set();
+		let consumingFailure;
 		while (matchedParsers.size < syncParsers.length) {
 			let foundMatch = false;
 			let error = {
@@ -3762,14 +3886,15 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 				error: message`No remaining parsers could match the input.`
 			};
 			const stateArray = currentContext.state;
-			const remainingParsers = syncParsers.map((parser, index) => [parser, index]).filter(([_, index]) => !matchedParsers.has(index)).sort(([parserA], [parserB]) => parserB.priority - parserA.priority);
+			const remainingParsers = orderBeforePassThrough(syncParsers.map((parser, index) => [parser, index]).filter(([parser, index]) => !matchedParsers.has(index) || getOptionMatch(parser, stateArray[index], currentContext.buffer[0])?.continuesCommand === true || passThroughParsers.size > 0 && !currentContext.optionsTerminated && getOptionMatch(parser, stateArray[index], currentContext.buffer[0]) != null).sort(([parserA], [parserB]) => parserB.priority - parserA.priority), currentContext, ([parser]) => parser, ([, index]) => stateArray[index], passThroughParsers);
 			for (const [parser, index] of remainingParsers) {
-				const result = parser.parse(withChildContext$1(currentContext, index, stateArray[index], parser));
+				const result = parser.parse(withPassThroughFailure(withChildContext$1(currentContext, index, stateArray[index], parser), consumingFailure, getPassThroughPriority(parser, stateArray[index], currentContext.buffer[0])));
 				if (result.success && result.consumed.length > 0) {
 					const newStateArray = annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? getWrappedChildState(currentContext.state, result.next.state, parser) : s));
 					const mergedExec = mergeChildExec(currentContext.exec, result.next.exec);
 					currentContext = {
 						...currentContext,
+						...getPassThroughFailureHint(result.next),
 						buffer: result.next.buffer,
 						optionsTerminated: result.next.optionsTerminated,
 						state: newStateArray,
@@ -3778,14 +3903,21 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 							dependencyRegistry: mergedExec.dependencyRegistry
 						} : {}
 					};
+					consumingFailure = void 0;
 					allConsumed.push(...result.consumed);
 					matchedParsers.add(index);
 					foundMatch = true;
 					break;
-				} else if (!result.success && error.consumed < result.consumed) error = result;
+				} else if (result.success) consumingFailure = retainConsumingFailureHint(consumingFailure, currentContext, result.next);
+				else {
+					const match = getOptionMatch(parser, stateArray[index], currentContext.buffer[0]);
+					if (result.consumed > 0 && match != null) consumingFailure = retainConsumingFailure(consumingFailure, result, match.priority);
+					if (error.consumed < result.consumed) error = result;
+				}
 			}
 			if (!foundMatch) for (const [parser, index] of remainingParsers) {
-				const result = parser.parse(withChildContext$1(currentContext, index, stateArray[index], parser));
+				if (matchedParsers.has(index)) continue;
+				const result = parser.parse(withPassThroughFailure(withChildContext$1(currentContext, index, stateArray[index], parser), consumingFailure, getPassThroughPriority(parser, stateArray[index], currentContext.buffer[0])));
 				if (result.success && result.consumed.length < 1) {
 					const newStateArray = annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? getWrappedChildState(currentContext.state, result.next.state, parser) : s));
 					const mergedExec = mergeChildExec(currentContext.exec, result.next.exec);
@@ -3813,7 +3945,7 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		}
 		return {
 			success: true,
-			next: currentContext,
+			next: withPassThroughFailure(currentContext, consumingFailure),
 			consumed: allConsumed
 		};
 	};
@@ -3821,6 +3953,7 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		let currentContext = context;
 		const allConsumed = [];
 		const matchedParsers = /* @__PURE__ */ new Set();
+		let consumingFailure;
 		while (matchedParsers.size < parsers.length) {
 			let foundMatch = false;
 			let error = {
@@ -3828,15 +3961,16 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 				error: message`No remaining parsers could match the input.`
 			};
 			const stateArray = currentContext.state;
-			const remainingParsers = parsers.map((parser, index) => [parser, index]).filter(([_, index]) => !matchedParsers.has(index)).sort(([parserA], [parserB]) => parserB.priority - parserA.priority);
+			const remainingParsers = orderBeforePassThrough(parsers.map((parser, index) => [parser, index]).filter(([parser, index]) => !matchedParsers.has(index) || getOptionMatch(parser, stateArray[index], currentContext.buffer[0])?.continuesCommand === true || passThroughParsers.size > 0 && !currentContext.optionsTerminated && getOptionMatch(parser, stateArray[index], currentContext.buffer[0]) != null).sort(([parserA], [parserB]) => parserB.priority - parserA.priority), currentContext, ([parser]) => parser, ([, index]) => stateArray[index], passThroughParsers);
 			for (const [parser, index] of remainingParsers) {
-				const resultOrPromise = parser.parse(withChildContext$1(currentContext, index, stateArray[index], parser));
+				const resultOrPromise = parser.parse(withPassThroughFailure(withChildContext$1(currentContext, index, stateArray[index], parser), consumingFailure, getPassThroughPriority(parser, stateArray[index], currentContext.buffer[0])));
 				const result = await resultOrPromise;
 				if (result.success && result.consumed.length > 0) {
 					const newStateArray = annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? getWrappedChildState(currentContext.state, result.next.state, parser) : s));
 					const mergedExec = mergeChildExec(currentContext.exec, result.next.exec);
 					currentContext = {
 						...currentContext,
+						...getPassThroughFailureHint(result.next),
 						buffer: result.next.buffer,
 						optionsTerminated: result.next.optionsTerminated,
 						state: newStateArray,
@@ -3845,14 +3979,21 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 							dependencyRegistry: mergedExec.dependencyRegistry
 						} : {}
 					};
+					consumingFailure = void 0;
 					allConsumed.push(...result.consumed);
 					matchedParsers.add(index);
 					foundMatch = true;
 					break;
-				} else if (!result.success && error.consumed < result.consumed) error = result;
+				} else if (result.success) consumingFailure = retainConsumingFailureHint(consumingFailure, currentContext, result.next);
+				else {
+					const match = getOptionMatch(parser, stateArray[index], currentContext.buffer[0]);
+					if (result.consumed > 0 && match != null) consumingFailure = retainConsumingFailure(consumingFailure, result, match.priority);
+					if (error.consumed < result.consumed) error = result;
+				}
 			}
 			if (!foundMatch) for (const [parser, index] of remainingParsers) {
-				const resultOrPromise = parser.parse(withChildContext$1(currentContext, index, stateArray[index], parser));
+				if (matchedParsers.has(index)) continue;
+				const resultOrPromise = parser.parse(withPassThroughFailure(withChildContext$1(currentContext, index, stateArray[index], parser), consumingFailure, getPassThroughPriority(parser, stateArray[index], currentContext.buffer[0])));
 				const result = await resultOrPromise;
 				if (result.success && result.consumed.length < 1) {
 					const newStateArray = annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? getWrappedChildState(currentContext.state, result.next.state, parser) : s));
@@ -3881,7 +4022,7 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		}
 		return {
 			success: true,
-			next: currentContext,
+			next: withPassThroughFailure(currentContext, consumingFailure),
 			consumed: allConsumed
 		};
 	};
@@ -4154,6 +4295,8 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		enumerable: false
 	});
 	defineInheritedAnnotationParser(tupleParser);
+	defineOptionMatch(tupleParser, (state, token) => combineOptionMatches(parsers.map((parser, index) => getOptionMatch(parser, getWrappedChildState(state, state[index], parser), token))));
+	definePassThroughPriority(tupleParser, parsers, (state, token) => combinePassThroughPriorities(parsers.map((parser, index) => getPassThroughPriority(parser, getWrappedChildState(state, state[index], parser), token))));
 	return fluent(scopeParser(tupleParser, combinedOptionScope(parsers, parsers.map((_, index) => index))));
 }
 function seq(...rawArgs) {
@@ -4648,6 +4791,7 @@ function merge(...args) {
 			success: true,
 			next: {
 				...context,
+				...getPassThroughFailureHint(result.next),
 				buffer: result.next.buffer,
 				optionsTerminated: result.next.optionsTerminated,
 				state: newState,
@@ -4753,6 +4897,7 @@ function merge(...args) {
 			const mergedExec = mergeChildExec(settledContext.exec, result.next.exec);
 			settledContext = {
 				...settledContext,
+				...getPassThroughFailureHint(result.next),
 				buffer: result.next.buffer,
 				optionsTerminated: result.next.optionsTerminated,
 				state: nextState,
@@ -4785,6 +4930,7 @@ function merge(...args) {
 				const newState = mergeResultState(parser, currentContext, parserState, result, i);
 				const newContext = {
 					...currentContext,
+					...getPassThroughFailureHint(result.next),
 					buffer: result.next.buffer,
 					optionsTerminated: result.next.optionsTerminated,
 					state: newState,
@@ -4830,6 +4976,7 @@ function merge(...args) {
 				const newState = mergeResultState(parser, currentContext, parserState, result, i);
 				const newContext = {
 					...currentContext,
+					...getPassThroughFailureHint(result.next),
 					buffer: result.next.buffer,
 					optionsTerminated: result.next.optionsTerminated,
 					state: newState,
@@ -4869,10 +5016,12 @@ function merge(...args) {
 		const consumedLanes = /* @__PURE__ */ new Set();
 		const consumedGroups = /* @__PURE__ */ new Set();
 		const laneResults = /* @__PURE__ */ new Map();
+		let consumingFailure;
 		let attemptedLane = false;
 		let madeProgress = true;
 		while (madeProgress && currentContext.buffer.length > 0) {
 			madeProgress = false;
+			consumingFailure = void 0;
 			let consumingError = null;
 			for (const lane of mergeParseLanes) {
 				if (consumingError != null && lane.priority < consumingError.priority) {
@@ -4890,6 +5039,10 @@ function merge(...args) {
 					break;
 				}
 				if (!result.success) {
+					if (result.consumed > 0 && matchesOptionToken({
+						leadingNames: lane.leadingNames,
+						usage: parsers.flatMap((parser) => parser.usage)
+					}, currentContext.buffer[0])) consumingFailure = retainConsumingFailure(consumingFailure, result, lane.priority);
 					if (result.consumed > 0 && consumingError == null) consumingError = {
 						priority: lane.priority,
 						result
@@ -4921,7 +5074,7 @@ function merge(...args) {
 		}
 		return {
 			success: true,
-			next: currentContext,
+			next: withPassThroughFailure(currentContext, consumingFailure),
 			consumed: allConsumed
 		};
 	};
@@ -4932,10 +5085,12 @@ function merge(...args) {
 		const consumedLanes = /* @__PURE__ */ new Set();
 		const consumedGroups = /* @__PURE__ */ new Set();
 		const laneResults = /* @__PURE__ */ new Map();
+		let consumingFailure;
 		let attemptedLane = false;
 		let madeProgress = true;
 		while (madeProgress && currentContext.buffer.length > 0) {
 			madeProgress = false;
+			consumingFailure = void 0;
 			let consumingError = null;
 			for (const lane of mergeParseLanes) {
 				if (consumingError != null && lane.priority < consumingError.priority) {
@@ -4953,6 +5108,10 @@ function merge(...args) {
 					break;
 				}
 				if (!result.success) {
+					if (result.consumed > 0 && matchesOptionToken({
+						leadingNames: lane.leadingNames,
+						usage: parsers.flatMap((parser) => parser.usage)
+					}, currentContext.buffer[0])) consumingFailure = retainConsumingFailure(consumingFailure, result, lane.priority);
 					if (result.consumed > 0 && consumingError == null) consumingError = {
 						priority: lane.priority,
 						result
@@ -4984,7 +5143,7 @@ function merge(...args) {
 		}
 		return {
 			success: true,
-			next: currentContext,
+			next: withPassThroughFailure(currentContext, consumingFailure),
 			consumed: allConsumed
 		};
 	};
@@ -5527,6 +5686,8 @@ function merge(...args) {
 	};
 	defineParseLanes(mergeParser, mergeParseLanes);
 	defineInheritedAnnotationParser(mergeParser);
+	defineOptionMatch(mergeParser, (state, token) => combineOptionMatches(sorted.map(([parser], index) => getOptionMatch(parser, extractParserStateFromState(parser, state, index), token))));
+	definePassThroughPriority(mergeParser, parsers, (state, token) => combinePassThroughPriorities(sorted.map(([parser], index) => getPassThroughPriority(parser, extractParserStateFromState(parser, state, index), token))));
 	return fluent(scopeParser(mergeParser, combinedOptionScope(parsers, parsers.map((_, index) => index))));
 }
 /**
@@ -5717,6 +5878,7 @@ function tryParseSuggestList(context, stateArray, parsers, matchedParsers, remai
 					const mergedExec = mergeChildExec(context.exec, result$1.next.exec);
 					return preParseSuggestLoop({
 						...context,
+						...getPassThroughFailureHint(result$1.next),
 						buffer: result$1.next.buffer,
 						optionsTerminated: result$1.next.optionsTerminated,
 						state: stateArray,
@@ -5744,6 +5906,7 @@ function tryParseSuggestList(context, stateArray, parsers, matchedParsers, remai
 			const mergedExec = mergeChildExec(context.exec, result.next.exec);
 			return {
 				...context,
+				...getPassThroughFailureHint(result.next),
 				buffer: result.next.buffer,
 				optionsTerminated: result.next.optionsTerminated,
 				state: stateArray,
@@ -5763,10 +5926,12 @@ function concat(...parsers) {
 	const isAsync = combinedMode === "async";
 	const syncParsers = parsers;
 	const initialState = parsers.map((parser) => parser.initialState);
+	const passThroughParsers = new Set(parsers.filter((parser) => hasPassThroughUsage(parser.usage)));
 	const parseSync = (context) => {
 		let currentContext = context;
 		const allConsumed = [];
 		const matchedParsers = /* @__PURE__ */ new Set();
+		let consumingFailure;
 		while (matchedParsers.size < syncParsers.length) {
 			let foundMatch = false;
 			let error = {
@@ -5774,14 +5939,15 @@ function concat(...parsers) {
 				error: message`No remaining parsers could match the input.`
 			};
 			const stateArray = currentContext.state;
-			const remainingParsers = syncParsers.map((parser, index) => [parser, index]).filter(([_, index]) => !matchedParsers.has(index)).sort(([parserA], [parserB]) => parserB.priority - parserA.priority);
+			const remainingParsers = orderBeforePassThrough(syncParsers.map((parser, index) => [parser, index]).filter(([parser, index]) => !matchedParsers.has(index) || getOptionMatch(parser, stateArray[index], currentContext.buffer[0])?.continuesCommand === true || passThroughParsers.size > 0 && !currentContext.optionsTerminated && getOptionMatch(parser, stateArray[index], currentContext.buffer[0]) != null).sort(([parserA], [parserB]) => parserB.priority - parserA.priority), currentContext, ([parser]) => parser, ([, index]) => stateArray[index], passThroughParsers);
 			for (const [parser, index] of remainingParsers) {
-				const result = parser.parse(withChildContext$1(currentContext, index, stateArray[index], parser));
+				const result = parser.parse(withPassThroughFailure(withChildContext$1(currentContext, index, stateArray[index], parser), consumingFailure, getPassThroughPriority(parser, stateArray[index], currentContext.buffer[0])));
 				if (result.success && result.consumed.length > 0) {
 					const newStateArray = annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? getWrappedChildState(currentContext.state, result.next.state, parser) : s));
 					const mergedExec = mergeChildExec(currentContext.exec, result.next.exec);
 					currentContext = {
 						...currentContext,
+						...getPassThroughFailureHint(result.next),
 						buffer: result.next.buffer,
 						optionsTerminated: result.next.optionsTerminated,
 						state: newStateArray,
@@ -5790,14 +5956,21 @@ function concat(...parsers) {
 							dependencyRegistry: mergedExec.dependencyRegistry
 						} : {}
 					};
+					consumingFailure = void 0;
 					allConsumed.push(...result.consumed);
 					matchedParsers.add(index);
 					foundMatch = true;
 					break;
-				} else if (!result.success && error.consumed < result.consumed) error = result;
+				} else if (result.success) consumingFailure = retainConsumingFailureHint(consumingFailure, currentContext, result.next);
+				else {
+					const match = getOptionMatch(parser, stateArray[index], currentContext.buffer[0]);
+					if (result.consumed > 0 && match != null) consumingFailure = retainConsumingFailure(consumingFailure, result, match.priority);
+					if (error.consumed < result.consumed) error = result;
+				}
 			}
 			if (!foundMatch) for (const [parser, index] of remainingParsers) {
-				const result = parser.parse(withChildContext$1(currentContext, index, stateArray[index], parser));
+				if (matchedParsers.has(index)) continue;
+				const result = parser.parse(withPassThroughFailure(withChildContext$1(currentContext, index, stateArray[index], parser), consumingFailure, getPassThroughPriority(parser, stateArray[index], currentContext.buffer[0])));
 				if (result.success && result.consumed.length < 1) {
 					const newStateArray = annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? getWrappedChildState(currentContext.state, result.next.state, parser) : s));
 					const mergedExec = mergeChildExec(currentContext.exec, result.next.exec);
@@ -5825,7 +5998,7 @@ function concat(...parsers) {
 		}
 		return {
 			success: true,
-			next: currentContext,
+			next: withPassThroughFailure(currentContext, consumingFailure),
 			consumed: allConsumed
 		};
 	};
@@ -5833,6 +6006,7 @@ function concat(...parsers) {
 		let currentContext = context;
 		const allConsumed = [];
 		const matchedParsers = /* @__PURE__ */ new Set();
+		let consumingFailure;
 		while (matchedParsers.size < parsers.length) {
 			let foundMatch = false;
 			let error = {
@@ -5840,14 +6014,15 @@ function concat(...parsers) {
 				error: message`No remaining parsers could match the input.`
 			};
 			const stateArray = currentContext.state;
-			const remainingParsers = parsers.map((parser, index) => [parser, index]).filter(([_, index]) => !matchedParsers.has(index)).sort(([parserA], [parserB]) => parserB.priority - parserA.priority);
+			const remainingParsers = orderBeforePassThrough(parsers.map((parser, index) => [parser, index]).filter(([parser, index]) => !matchedParsers.has(index) || getOptionMatch(parser, stateArray[index], currentContext.buffer[0])?.continuesCommand === true || passThroughParsers.size > 0 && !currentContext.optionsTerminated && getOptionMatch(parser, stateArray[index], currentContext.buffer[0]) != null).sort(([parserA], [parserB]) => parserB.priority - parserA.priority), currentContext, ([parser]) => parser, ([, index]) => stateArray[index], passThroughParsers);
 			for (const [parser, index] of remainingParsers) {
-				const result = await parser.parse(withChildContext$1(currentContext, index, stateArray[index], parser));
+				const result = await parser.parse(withPassThroughFailure(withChildContext$1(currentContext, index, stateArray[index], parser), consumingFailure, getPassThroughPriority(parser, stateArray[index], currentContext.buffer[0])));
 				if (result.success && result.consumed.length > 0) {
 					const newStateArray = annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? getWrappedChildState(currentContext.state, result.next.state, parser) : s));
 					const mergedExec = mergeChildExec(currentContext.exec, result.next.exec);
 					currentContext = {
 						...currentContext,
+						...getPassThroughFailureHint(result.next),
 						buffer: result.next.buffer,
 						optionsTerminated: result.next.optionsTerminated,
 						state: newStateArray,
@@ -5856,14 +6031,21 @@ function concat(...parsers) {
 							dependencyRegistry: mergedExec.dependencyRegistry
 						} : {}
 					};
+					consumingFailure = void 0;
 					allConsumed.push(...result.consumed);
 					matchedParsers.add(index);
 					foundMatch = true;
 					break;
-				} else if (!result.success && error.consumed < result.consumed) error = result;
+				} else if (result.success) consumingFailure = retainConsumingFailureHint(consumingFailure, currentContext, result.next);
+				else {
+					const match = getOptionMatch(parser, stateArray[index], currentContext.buffer[0]);
+					if (result.consumed > 0 && match != null) consumingFailure = retainConsumingFailure(consumingFailure, result, match.priority);
+					if (error.consumed < result.consumed) error = result;
+				}
 			}
 			if (!foundMatch) for (const [parser, index] of remainingParsers) {
-				const result = await parser.parse(withChildContext$1(currentContext, index, stateArray[index], parser));
+				if (matchedParsers.has(index)) continue;
+				const result = await parser.parse(withPassThroughFailure(withChildContext$1(currentContext, index, stateArray[index], parser), consumingFailure, getPassThroughPriority(parser, stateArray[index], currentContext.buffer[0])));
 				if (result.success && result.consumed.length < 1) {
 					const newStateArray = annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? getWrappedChildState(currentContext.state, result.next.state, parser) : s));
 					const mergedExec = mergeChildExec(currentContext.exec, result.next.exec);
@@ -5891,7 +6073,7 @@ function concat(...parsers) {
 		}
 		return {
 			success: true,
-			next: currentContext,
+			next: withPassThroughFailure(currentContext, consumingFailure),
 			consumed: allConsumed
 		};
 	};
@@ -6162,6 +6344,8 @@ function concat(...parsers) {
 		}
 	};
 	defineInheritedAnnotationParser(concatParser);
+	defineOptionMatch(concatParser, (state, token) => combineOptionMatches(parsers.map((parser, index) => getOptionMatch(parser, getWrappedChildState(state, state[index], parser), token))));
+	definePassThroughPriority(concatParser, parsers, (state, token) => combinePassThroughPriorities(parsers.map((parser, index) => getPassThroughPriority(parser, getWrappedChildState(state, state[index], parser), token))));
 	return fluent(scopeParser(concatParser, combinedOptionScope(parsers, parsers.map((_, index) => index))));
 }
 function group(label, parser, options = {}) {
@@ -6280,6 +6464,9 @@ function group(label, parser, options = {}) {
 		configurable: true,
 		enumerable: false
 	});
+	delegateKnownCompletion(groupParser, parser);
+	defineOptionMatch(groupParser, (state, token) => getOptionMatch(parser, state, token));
+	definePassThroughPriority(groupParser, [parser], (state, token) => getPassThroughPriority(parser, state, token));
 	return fluent(scopeParser(groupParser, combinedOptionScope([parser])));
 }
 /**
@@ -6437,6 +6624,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 								dependencyRegistry: discriminatorExec.dependencyRegistry
 							} : {}
 						}, "_branch", branchParser.initialState, branchParser, branchParser.usage),
+						...getPassThroughFailureHint(discriminatorResult.next),
 						buffer: discriminatorResult.next.buffer,
 						optionsTerminated: discriminatorResult.next.optionsTerminated
 					});
@@ -6565,6 +6753,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 				const discriminatorExec = mergeChildExec(context.exec, discriminatorResult.next.exec);
 				const speculationContext = {
 					...withOptionScope(context, unionLeadingNames([...branchParsers.map(([, p]) => p), ...defaultBranch ? [defaultBranch] : []])),
+					...getPassThroughFailureHint(discriminatorResult.next),
 					buffer: discriminatorResult.next.buffer,
 					optionsTerminated: discriminatorResult.next.optionsTerminated,
 					...discriminatorExec != null ? {
@@ -6696,6 +6885,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 								dependencyRegistry: discriminatorExec.dependencyRegistry
 							} : {}
 						}, "_branch", branchParser.initialState, branchParser, branchParser.usage),
+						...getPassThroughFailureHint(discriminatorResult.next),
 						buffer: discriminatorResult.next.buffer,
 						optionsTerminated: discriminatorResult.next.optionsTerminated
 					});
@@ -7650,6 +7840,36 @@ function conditional(discriminator, branches, defaultBranch, options) {
 		configurable: true,
 		enumerable: false
 	});
+	const reachableBranches = (state) => {
+		if (state.selectedBranch != null) {
+			const branch = state.selectedBranch.kind === "default" ? defaultBranch : branches[state.selectedBranch.key];
+			return branch == null ? [] : [{
+				branch,
+				state: state.branchState
+			}];
+		}
+		const known = getKnownCompletion(discriminator, state.discriminatorState);
+		if (known != null) {
+			const branch = typeof known.value === "string" ? branches[known.value] : void 0;
+			const reachable = branch ?? defaultBranch;
+			return reachable == null ? [] : [{
+				branch: reachable,
+				state: reachable.initialState
+			}];
+		}
+		return allBranchParsers.map((branch) => ({
+			branch,
+			state: branch.initialState
+		}));
+	};
+	definePassThroughPriority(conditionalParser, [discriminator, ...allBranchParsers], (state, token) => combinePassThroughPriorities([...state.selectedBranch == null ? [getPassThroughPriority(discriminator, state.discriminatorState, token)] : [], ...reachableBranches(state).map(({ branch, state: state$1 }) => getPassThroughPriority(branch, state$1, token))]));
+	defineOptionMatch(conditionalParser, (state, token) => {
+		if (state.selectedBranch != null) {
+			const branch = state.selectedBranch.kind === "default" ? defaultBranch : branches[state.selectedBranch.key];
+			return branch == null ? void 0 : getOptionMatch(branch, state.branchState, token);
+		}
+		return combineOptionMatches([getOptionMatch(discriminator, state.discriminatorState, token), ...reachableBranches(state).map(({ branch, state: state$1 }) => getOptionMatch(branch, state$1, token))]);
+	});
 	return fluent(scopeParser(conditionalParser, optionScope.source, (context) => {
 		const selected = context.state?.selectedBranch;
 		if (selected != null) {