@optique/core 1.4.0-dev.2638 → 1.4.0-dev.2662

package/dist/constructs.cjs

@@ -11,6 +11,7 @@ const require_annotation_state = require('./annotation-state.cjs');
 const require_execution_context = require('./execution-context.cjs');
 const require_usage_internals = require('./usage-internals.cjs');
 const require_short_option = require('./short-option.cjs');
+const require_passthrough = require('./internal/passthrough.cjs');
 const require_command_alias = require('./internal/command-alias.cjs');
 const require_phase2_seed = require('./phase2-seed.cjs');
 const require_modifiers = require('./modifiers.cjs');
@@ -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, require_passthrough.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 = require_passthrough.getPassThroughPriority(getParser(pair), getState(pair), token);
+		const match = matches.get(pair);
+		if (match != null && (priority == null || match.priority >= priority)) {
+			const unfiltered = require_passthrough.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.
@@ -970,12 +1028,16 @@ function analyzeNoMatchContext(parsers) {
 * construction. This is a programmer error, not a user error.
 */
 var DuplicateOptionError = class extends Error {
+	/** The option name shared by multiple fields. */
+	optionName;
+	/** The fields declaring the option. */
+	sources;
 	constructor(optionName$1, sources) {
 		const sourceNames = sources.map((s) => typeof s === "symbol" ? s.description ?? s.toString() : s);
 		super(`Duplicate option name "${optionName$1}" found in fields: ${sourceNames.join(", ")}. Each option name must be unique within a parser combinator.`);
+		this.name = "DuplicateOptionError";
 		this.optionName = optionName$1;
 		this.sources = sources;
-		this.name = "DuplicateOptionError";
 	}
 };
 /**
@@ -983,6 +1045,8 @@ var DuplicateOptionError = class extends Error {
 * during parser construction. This is a programmer error, not a user error.
 */
 var DuplicateCommandNameError = class extends TypeError {
+	commandName;
+	sources;
 	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.`);
@@ -1076,6 +1140,16 @@ function generateNoMatchError(context) {
 	else if (hasOptions && hasCommands && hasArguments) return require_message.message`No matching option, command, or argument found.`;
 	else return require_message.message`No value provided.`;
 }
+/** Potential alternatives; only parsing decides whether replay can switch. */
+function selectExclusiveChildren(parsers, state, activeFirst = false) {
+	const active = normalizeExclusiveState(state);
+	const children = parsers.map((parser, index) => ({
+		parser,
+		index,
+		state: require_annotation_state.getWrappedChildParseState(state, active?.[0] === index && active[1].success ? active[1].next.state : parser.initialState, parser)
+	}));
+	return activeFirst ? children.sort((a, b) => active?.[0] === a.index ? -1 : active?.[0] === b.index ? 1 : a.index - b.index) : children;
+}
 function normalizeExclusiveState(state) {
 	if (!Array.isArray(state) || state.length !== 2 || typeof state[0] !== "number") return void 0;
 	return state;
@@ -1114,6 +1188,7 @@ function preserveExclusiveStateAfterOptionsTerminator(context, result) {
 		success: true,
 		next: {
 			...context,
+			...require_passthrough.getPassThroughFailureHint(result.next),
 			buffer: result.next.buffer,
 			optionsTerminated: true,
 			state: context.state,
@@ -1404,15 +1479,19 @@ function or(...args) {
 	const parseSync = (context) => {
 		let error = getInitialError(context);
 		const activeState = normalizeExclusiveState(context.state);
-		const orderedParsers = syncParsers.map((p, i) => [p, i]);
-		orderedParsers.sort(([_, a], [__, b]) => activeState?.[0] === a ? -1 : activeState?.[0] === b ? 1 : a - b);
+		const orderedParsers = selectExclusiveChildren(syncParsers, context.state, true);
 		let zeroConsumedBranch = null;
 		let zeroConsumedCount = 0;
 		let provisionalConsuming = null;
 		let optionsTerminatorResult = null;
 		let provisionalAmbiguous = false;
-		for (const [parser, i] of orderedParsers) {
-			const result = parser.parse(withChildContext$1(require_short_option.forkOptionScope(context), i, activeState == null || activeState[0] !== i || !activeState[1].success ? parser.initialState : activeState[1].next.state, parser));
+		for (const { parser, index: i, state: childState } of orderedParsers) {
+			const childContext = withChildContext$1(require_short_option.forkOptionScope(context), i, childState, parser);
+			const result = parser.parse(childContext);
+			if (result.success && result.consumed.length === 0) {
+				const own = require_passthrough.retainConsumingFailureHint(void 0, childContext, result.next);
+				if (own != null && error.consumed < own.failure.consumed) error = own.failure;
+			}
 			if (isOptionsTerminatorOnlyResult(context, result)) {
 				if (activeState?.[0] === i && activeState[1].success && activeState[1].consumed.length > 0 && result.next.buffer.length < 1) return preserveExclusiveStateAfterOptionsTerminator(context, result);
 				optionsTerminatorResult ??= result;
@@ -1448,6 +1527,7 @@ function or(...args) {
 							success: true,
 							next: {
 								...require_short_option.adoptOptionScope(context, result.next),
+								...require_passthrough.getPassThroughFailureHint(result.next),
 								buffer: result.next.buffer,
 								optionsTerminated: result.next.optionsTerminated,
 								state: createExclusiveState(context.state, i, parser, result),
@@ -1484,6 +1564,7 @@ function or(...args) {
 						success: true,
 						next: {
 							...require_short_option.adoptOptionScope(context, replayedResult.next),
+							...require_passthrough.getPassThroughFailureHint(replayedResult.next),
 							buffer: replayedResult.next.buffer,
 							optionsTerminated: replayedResult.next.optionsTerminated,
 							state: createExclusiveState(context.state, i, parser, {
@@ -1503,6 +1584,7 @@ function or(...args) {
 					success: true,
 					next: {
 						...require_short_option.adoptOptionScope(context, result.next),
+						...require_passthrough.getPassThroughFailureHint(result.next),
 						buffer: result.next.buffer,
 						optionsTerminated: result.next.optionsTerminated,
 						state: createExclusiveState(context.state, i, parser, result),
@@ -1547,6 +1629,7 @@ function or(...args) {
 					provisional: true,
 					next: {
 						...require_short_option.adoptOptionScope(context, provisionalConsuming.result.next),
+						...require_passthrough.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 +1664,7 @@ function or(...args) {
 						provisional: true,
 						next: {
 							...require_short_option.adoptOptionScope(context, replayedResult.next),
+							...require_passthrough.getPassThroughFailureHint(replayedResult.next),
 							buffer: replayedResult.next.buffer,
 							optionsTerminated: replayedResult.next.optionsTerminated,
 							state: createExclusiveState(context.state, provisionalConsuming.index, provisionalConsuming.parser, {
@@ -1607,16 +1691,20 @@ function or(...args) {
 	const parseAsync = async (context) => {
 		let error = getInitialError(context);
 		const activeState = normalizeExclusiveState(context.state);
-		const orderedParsers = parsers.map((p, i) => [p, i]);
-		orderedParsers.sort(([_, a], [__, b]) => activeState?.[0] === a ? -1 : activeState?.[0] === b ? 1 : a - b);
+		const orderedParsers = selectExclusiveChildren(parsers, context.state, true);
 		let zeroConsumedBranch = null;
 		let zeroConsumedCount = 0;
 		let provisionalConsuming = null;
 		let optionsTerminatorResult = null;
 		let provisionalAmbiguous = false;
-		for (const [parser, i] of orderedParsers) {
-			const resultOrPromise = parser.parse(withChildContext$1(require_short_option.forkOptionScope(context), i, activeState == null || activeState[0] !== i || !activeState[1].success ? parser.initialState : activeState[1].next.state, parser));
+		for (const { parser, index: i, state: childState } of orderedParsers) {
+			const childContext = withChildContext$1(require_short_option.forkOptionScope(context), i, childState, parser);
+			const resultOrPromise = parser.parse(childContext);
 			const result = await resultOrPromise;
+			if (result.success && result.consumed.length === 0) {
+				const own = require_passthrough.retainConsumingFailureHint(void 0, childContext, result.next);
+				if (own != null && error.consumed < own.failure.consumed) error = own.failure;
+			}
 			if (isOptionsTerminatorOnlyResult(context, result)) {
 				if (activeState?.[0] === i && activeState[1].success && activeState[1].consumed.length > 0 && result.next.buffer.length < 1) return preserveExclusiveStateAfterOptionsTerminator(context, result);
 				optionsTerminatorResult ??= result;
@@ -1652,6 +1740,7 @@ function or(...args) {
 							success: true,
 							next: {
 								...require_short_option.adoptOptionScope(context, result.next),
+								...require_passthrough.getPassThroughFailureHint(result.next),
 								buffer: result.next.buffer,
 								optionsTerminated: result.next.optionsTerminated,
 								state: createExclusiveState(context.state, i, parser, result),
@@ -1690,6 +1779,7 @@ function or(...args) {
 						success: true,
 						next: {
 							...require_short_option.adoptOptionScope(context, replayedResult.next),
+							...require_passthrough.getPassThroughFailureHint(replayedResult.next),
 							buffer: replayedResult.next.buffer,
 							optionsTerminated: replayedResult.next.optionsTerminated,
 							state: createExclusiveState(context.state, i, parser, {
@@ -1709,6 +1799,7 @@ function or(...args) {
 					success: true,
 					next: {
 						...require_short_option.adoptOptionScope(context, result.next),
+						...require_passthrough.getPassThroughFailureHint(result.next),
 						buffer: result.next.buffer,
 						optionsTerminated: result.next.optionsTerminated,
 						state: createExclusiveState(context.state, i, parser, result),
@@ -1753,6 +1844,7 @@ function or(...args) {
 					provisional: true,
 					next: {
 						...require_short_option.adoptOptionScope(context, provisionalConsuming.result.next),
+						...require_passthrough.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 +1879,7 @@ function or(...args) {
 						provisional: true,
 						next: {
 							...require_short_option.adoptOptionScope(context, replayedResult.next),
+							...require_passthrough.getPassThroughFailureHint(replayedResult.next),
 							buffer: replayedResult.next.buffer,
 							optionsTerminated: replayedResult.next.optionsTerminated,
 							state: createExclusiveState(context.state, provisionalConsuming.index, provisionalConsuming.parser, {
@@ -1879,6 +1972,7 @@ function or(...args) {
 	if (singleDependencyMetadata != null) singleResult.dependencyMetadata = singleDependencyMetadata;
 	defineExclusiveSchedulingNodes(singleResult, parsers);
 	require_internal_parser.defineInheritedAnnotationParser(singleResult);
+	require_passthrough.defineReachableChildren(singleResult, parsers, (state) => selectExclusiveChildren(parsers, state, true));
 	return require_modifiers.fluent(require_short_option.scopeParser(singleResult, require_short_option.combinedOptionScope(parsers, parsers.map((_, index) => index))));
 }
 /**
@@ -1913,24 +2007,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,
+				...require_passthrough.getPassThroughFailureHint(optionsTerminatorResult.next),
 				buffer: optionsTerminatorResult.next.buffer,
 				optionsTerminated: true
 			},
 			consumed: [...optionsTerminatorResult.consumed, ...match.result.consumed]
 		};
+		const next = selectedResult.consumed.length === 0 ? require_passthrough.withReturnedConsumingFailure(selectedResult.next, consumingFailure) : selectedResult.next;
 		const parser = parsers[match.index];
-		const mergedExec = require_execution_context.mergeChildExec(context.exec, selectedResult.next.exec);
+		const mergedExec = require_execution_context.mergeChildExec(context.exec, next.exec);
 		return {
 			success: true,
 			next: {
-				...require_short_option.adoptOptionScope(context, selectedResult.next),
-				buffer: selectedResult.next.buffer,
-				optionsTerminated: selectedResult.next.optionsTerminated,
+				...require_short_option.adoptOptionScope(context, next),
+				...require_passthrough.getPassThroughFailureHint(next),
+				buffer: next.buffer,
+				optionsTerminated: next.optionsTerminated,
 				state: createExclusiveState(context.state, match.index, parser, selectedResult),
 				...mergedExec != null ? {
 					exec: mergedExec,
@@ -1965,10 +2062,9 @@ function createLongestMatch(...args) {
 		let bestMatch = null;
 		const optionsTerminatorMatches = [];
 		let error = getInitialError(context);
-		const activeState = normalizeExclusiveState(context.state);
-		for (let i = 0; i < syncParsers.length; i++) {
-			const parser = syncParsers[i];
-			const childContext = withChildContext$1(require_short_option.forkOptionScope(context), i, activeState == null || activeState[0] !== i || !activeState[1].success ? parser.initialState : activeState[1].next.state, parser);
+		let consumingFailure;
+		for (const { parser, index: i, state: childState } of selectExclusiveChildren(syncParsers, context.state)) {
+			const childContext = withChildContext$1(require_short_option.forkOptionScope(context), i, childState, parser);
 			const result = parser.parse(childContext);
 			if (isOptionsTerminatorOnlyResult(context, result)) {
 				optionsTerminatorMatches.push({
@@ -1980,6 +2076,8 @@ function createLongestMatch(...args) {
 				continue;
 			}
 			if (result.success) {
+				consumingFailure = require_passthrough.retainConsumingFailureHint(consumingFailure, context, result.next);
+				if (consumingFailure != null && error.consumed < consumingFailure.failure.consumed) error = consumingFailure.failure;
 				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 +2085,15 @@ function createLongestMatch(...args) {
 					result,
 					consumed
 				};
-			} else if (error.consumed < result.consumed) error = result;
+			} else {
+				const match = require_passthrough.getOptionMatch(parser, childContext.state, context.buffer[0]);
+				if (result.consumed > 0 && match != null) consumingFailure = require_passthrough.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,10 +2103,9 @@ function createLongestMatch(...args) {
 		let bestMatch = null;
 		const optionsTerminatorMatches = [];
 		let error = getInitialError(context);
-		const activeState = normalizeExclusiveState(context.state);
-		for (let i = 0; i < parsers.length; i++) {
-			const parser = parsers[i];
-			const childContext = withChildContext$1(require_short_option.forkOptionScope(context), i, activeState == null || activeState[0] !== i || !activeState[1].success ? parser.initialState : activeState[1].next.state, parser);
+		let consumingFailure;
+		for (const { parser, index: i, state: childState } of selectExclusiveChildren(parsers, context.state)) {
+			const childContext = withChildContext$1(require_short_option.forkOptionScope(context), i, childState, parser);
 			const resultOrPromise = parser.parse(childContext);
 			const result = await resultOrPromise;
 			if (isOptionsTerminatorOnlyResult(context, result)) {
@@ -2017,6 +2118,8 @@ function createLongestMatch(...args) {
 				continue;
 			}
 			if (result.success) {
+				consumingFailure = require_passthrough.retainConsumingFailureHint(consumingFailure, context, result.next);
+				if (consumingFailure != null && error.consumed < consumingFailure.failure.consumed) error = consumingFailure.failure;
 				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 +2127,15 @@ function createLongestMatch(...args) {
 					result,
 					consumed
 				};
-			} else if (error.consumed < result.consumed) error = result;
+			} else {
+				const match = require_passthrough.getOptionMatch(parser, childContext.state, context.buffer[0]);
+				if (result.consumed > 0 && match != null) consumingFailure = require_passthrough.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 +2208,7 @@ function createLongestMatch(...args) {
 	if (multiDependencyMetadata != null) multiResult.dependencyMetadata = multiDependencyMetadata;
 	defineExclusiveSchedulingNodes(multiResult, parsers);
 	require_internal_parser.defineInheritedAnnotationParser(multiResult);
+	require_passthrough.defineReachableChildren(multiResult, parsers, (state) => selectExclusiveChildren(parsers, state, false));
 	return require_modifiers.fluent(require_short_option.scopeParser(multiResult, require_short_option.combinedOptionScope(parsers, parsers.map((_, index) => index))));
 }
 /**
@@ -2504,6 +2612,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) => require_passthrough.hasPassThroughUsage(parser.usage)));
 	const createInitialState = () => {
 		const state = {};
 		for (const key of parserKeys) state[key] = parsers[key].initialState;
@@ -2541,7 +2650,10 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		if (!result.success) return result;
 		if (result.consumed.length === 0 && result.next.state === fieldState) return {
 			success: true,
-			next: context,
+			next: {
+				...context,
+				...require_passthrough.getPassThroughFailureHint(result.next)
+			},
 			consumed: []
 		};
 		require_short_option.adoptOptionScope(context, result.next);
@@ -2554,6 +2666,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			success: true,
 			next: {
 				...context,
+				...require_passthrough.getPassThroughFailureHint(result.next),
 				buffer: result.next.buffer,
 				optionsTerminated: result.next.optionsTerminated,
 				state: nextState,
@@ -2590,17 +2703,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(require_short_option.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(require_passthrough.withPassThroughFailure(withChildContext$1(require_short_option.forkOptionScope(currentContext), field, getFieldState(field, parser), parser), consumingFailure, require_passthrough.getPassThroughPriority(parser, getFieldState(field, parser), currentContext.buffer[0])));
 				if (result.success && result.consumed.length > 0) {
 					require_short_option.adoptOptionScope(currentContext, result.next);
 					const mergedExec = require_execution_context.mergeChildExec(currentContext.exec, result.next.exec);
 					currentContext = {
 						...currentContext,
+						...require_passthrough.getPassThroughFailureHint(result.next),
 						buffer: result.next.buffer,
 						optionsTerminated: result.next.optionsTerminated,
 						state: {
@@ -2618,7 +2734,14 @@ 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 = require_passthrough.retainConsumingFailureHint(consumingFailure, currentContext, result.next);
+					if (consumingFailure != null && error.consumed < consumingFailure.failure.consumed) error = consumingFailure.failure;
+				} else {
+					const match = require_passthrough.getOptionMatch(parser, getFieldState(field, parser), currentContext.buffer[0]);
+					if (result.consumed > 0 && match != null) consumingFailure = require_passthrough.retainConsumingFailure(consumingFailure, result, match.priority);
+					if (error.consumed < result.consumed) error = result;
+				}
 			}
 		}
 		{
@@ -2628,7 +2751,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(require_short_option.forkOptionScope(currentContext), field, fieldState, parser));
+				const result = typedParser.parse(require_passthrough.withPassThroughFailure(withChildContext$1(require_short_option.forkOptionScope(currentContext), field, fieldState, parser), consumingFailure, require_passthrough.getPassThroughPriority(parser, getFieldState(field, parser), currentContext.buffer[0])));
 				if (result.success && result.consumed.length === 0 && result.next.state !== fieldState) {
 					require_short_option.adoptOptionScope(currentContext, result.next);
 					const mergedExec = require_execution_context.mergeChildExec(currentContext.exec, result.next.exec);
@@ -2649,7 +2772,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		}
 		if (anySuccess) return {
 			success: true,
-			next: currentContext,
+			next: require_passthrough.withReturnedConsumingFailure(currentContext, consumingFailure),
 			consumed: allConsumed
 		};
 		if (currentContext.buffer.length === 0) {
@@ -2698,18 +2821,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(require_short_option.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(require_passthrough.withPassThroughFailure(withChildContext$1(require_short_option.forkOptionScope(currentContext), field, getFieldState(field, parser), parser), consumingFailure, require_passthrough.getPassThroughPriority(parser, getFieldState(field, parser), currentContext.buffer[0])));
 				const result = await resultOrPromise;
 				if (result.success && result.consumed.length > 0) {
 					require_short_option.adoptOptionScope(currentContext, result.next);
 					const mergedExec = require_execution_context.mergeChildExec(currentContext.exec, result.next.exec);
 					currentContext = {
 						...currentContext,
+						...require_passthrough.getPassThroughFailureHint(result.next),
 						buffer: result.next.buffer,
 						optionsTerminated: result.next.optionsTerminated,
 						state: {
@@ -2727,7 +2853,14 @@ 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 = require_passthrough.retainConsumingFailureHint(consumingFailure, currentContext, result.next);
+					if (consumingFailure != null && error.consumed < consumingFailure.failure.consumed) error = consumingFailure.failure;
+				} else {
+					const match = require_passthrough.getOptionMatch(parser, getFieldState(field, parser), currentContext.buffer[0]);
+					if (result.consumed > 0 && match != null) consumingFailure = require_passthrough.retainConsumingFailure(consumingFailure, result, match.priority);
+					if (error.consumed < result.consumed) error = result;
+				}
 			}
 		}
 		{
@@ -2736,7 +2869,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(require_short_option.forkOptionScope(currentContext), field, fieldState, parser));
+				const resultOrPromise = parser.parse(require_passthrough.withPassThroughFailure(withChildContext$1(require_short_option.forkOptionScope(currentContext), field, fieldState, parser), consumingFailure, require_passthrough.getPassThroughPriority(parser, getFieldState(field, parser), currentContext.buffer[0])));
 				const result = await resultOrPromise;
 				if (result.success && result.consumed.length === 0 && result.next.state !== fieldState) {
 					require_short_option.adoptOptionScope(currentContext, result.next);
@@ -2758,7 +2891,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		}
 		if (anySuccess) return {
 			success: true,
-			next: currentContext,
+			next: require_passthrough.withReturnedConsumingFailure(currentContext, consumingFailure),
 			consumed: allConsumed
 		};
 		if (currentContext.buffer.length === 0) {
@@ -3128,6 +3261,13 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 	});
 	require_internal_parser.defineParseLanes(objectParser, objectParseLanes);
 	require_internal_parser.defineInheritedAnnotationParser(objectParser);
+	require_passthrough.defineReachableChildren(objectParser, parserPairs.map(([, parser]) => parser), (state) => {
+		const getFieldState = createFieldStateGetter(state, getObjectParseChildState);
+		return parserPairs.map(([field, parser]) => ({
+			parser,
+			state: require_annotation_state.getWrappedChildParseState(state, getFieldState(field, parser), parser)
+		}));
+	});
 	return require_modifiers.fluent(require_short_option.scopeParser(objectParser, require_short_option.combinedOptionScope(parserPairs.map(([, p]) => p), parserPairs.map(([field]) => field)), void 0, true));
 }
 function isParserLike(value) {
@@ -3586,6 +3726,7 @@ function advanceTupleSuggestContextSync(context, parsers) {
 				const mergedExec = require_execution_context.mergeChildExec(currentContext.exec, result.next.exec);
 				currentContext = {
 					...currentContext,
+					...require_passthrough.getPassThroughFailureHint(result.next),
 					buffer: result.next.buffer,
 					optionsTerminated: result.next.optionsTerminated,
 					state: newStateArray,
@@ -3652,6 +3793,7 @@ async function advanceTupleSuggestContextAsync(context, parsers) {
 				const mergedExec = require_execution_context.mergeChildExec(currentContext.exec, result.next.exec);
 				currentContext = {
 					...currentContext,
+					...require_passthrough.getPassThroughFailureHint(result.next),
 					buffer: result.next.buffer,
 					optionsTerminated: result.next.optionsTerminated,
 					state: newStateArray,
@@ -3751,10 +3893,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) => require_passthrough.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 +3906,15 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 				error: require_message.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) || require_passthrough.getOptionMatch(parser, stateArray[index], currentContext.buffer[0])?.continuesCommand === true || passThroughParsers.size > 0 && !currentContext.optionsTerminated && require_passthrough.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(require_passthrough.withPassThroughFailure(withChildContext$1(currentContext, index, stateArray[index], parser), consumingFailure, require_passthrough.getPassThroughPriority(parser, stateArray[index], currentContext.buffer[0])));
 				if (result.success && result.consumed.length > 0) {
 					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,
+						...require_passthrough.getPassThroughFailureHint(result.next),
 						buffer: result.next.buffer,
 						optionsTerminated: result.next.optionsTerminated,
 						state: newStateArray,
@@ -3778,14 +3923,23 @@ 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 = require_passthrough.retainConsumingFailureHint(consumingFailure, currentContext, result.next);
+					if (consumingFailure != null && error.consumed < consumingFailure.failure.consumed) error = consumingFailure.failure;
+				} else {
+					const match = require_passthrough.getOptionMatch(parser, stateArray[index], currentContext.buffer[0]);
+					if (result.consumed > 0 && match != null) consumingFailure = require_passthrough.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(require_passthrough.withPassThroughFailure(withChildContext$1(currentContext, index, stateArray[index], parser), consumingFailure, require_passthrough.getPassThroughPriority(parser, stateArray[index], currentContext.buffer[0])));
 				if (result.success && result.consumed.length < 1) {
 					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);
@@ -3813,7 +3967,7 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		}
 		return {
 			success: true,
-			next: currentContext,
+			next: require_passthrough.withReturnedConsumingFailure(currentContext, consumingFailure),
 			consumed: allConsumed
 		};
 	};
@@ -3821,6 +3975,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 +3983,16 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 				error: require_message.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) || require_passthrough.getOptionMatch(parser, stateArray[index], currentContext.buffer[0])?.continuesCommand === true || passThroughParsers.size > 0 && !currentContext.optionsTerminated && require_passthrough.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(require_passthrough.withPassThroughFailure(withChildContext$1(currentContext, index, stateArray[index], parser), consumingFailure, require_passthrough.getPassThroughPriority(parser, stateArray[index], currentContext.buffer[0])));
 				const result = await resultOrPromise;
 				if (result.success && result.consumed.length > 0) {
 					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,
+						...require_passthrough.getPassThroughFailureHint(result.next),
 						buffer: result.next.buffer,
 						optionsTerminated: result.next.optionsTerminated,
 						state: newStateArray,
@@ -3845,14 +4001,23 @@ 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 = require_passthrough.retainConsumingFailureHint(consumingFailure, currentContext, result.next);
+					if (consumingFailure != null && error.consumed < consumingFailure.failure.consumed) error = consumingFailure.failure;
+				} else {
+					const match = require_passthrough.getOptionMatch(parser, stateArray[index], currentContext.buffer[0]);
+					if (result.consumed > 0 && match != null) consumingFailure = require_passthrough.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(require_passthrough.withPassThroughFailure(withChildContext$1(currentContext, index, stateArray[index], parser), consumingFailure, require_passthrough.getPassThroughPriority(parser, stateArray[index], currentContext.buffer[0])));
 				const result = await resultOrPromise;
 				if (result.success && result.consumed.length < 1) {
 					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));
@@ -3881,7 +4046,7 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		}
 		return {
 			success: true,
-			next: currentContext,
+			next: require_passthrough.withReturnedConsumingFailure(currentContext, consumingFailure),
 			consumed: allConsumed
 		};
 	};
@@ -4154,6 +4319,10 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		enumerable: false
 	});
 	require_internal_parser.defineInheritedAnnotationParser(tupleParser);
+	require_passthrough.defineReachableChildren(tupleParser, parsers, (state) => parsers.map((parser, index) => ({
+		parser,
+		state: require_annotation_state.getWrappedChildParseState(state, state[index], parser)
+	})));
 	return require_modifiers.fluent(require_short_option.scopeParser(tupleParser, require_short_option.combinedOptionScope(parsers, parsers.map((_, index) => index))));
 }
 function seq(...rawArgs) {
@@ -4648,6 +4817,7 @@ function merge(...args) {
 			success: true,
 			next: {
 				...context,
+				...require_passthrough.getPassThroughFailureHint(result.next),
 				buffer: result.next.buffer,
 				optionsTerminated: result.next.optionsTerminated,
 				state: newState,
@@ -4753,6 +4923,7 @@ function merge(...args) {
 			const mergedExec = require_execution_context.mergeChildExec(settledContext.exec, result.next.exec);
 			settledContext = {
 				...settledContext,
+				...require_passthrough.getPassThroughFailureHint(result.next),
 				buffer: result.next.buffer,
 				optionsTerminated: result.next.optionsTerminated,
 				state: nextState,
@@ -4785,6 +4956,7 @@ function merge(...args) {
 				const newState = mergeResultState(parser, currentContext, parserState, result, i);
 				const newContext = {
 					...currentContext,
+					...require_passthrough.getPassThroughFailureHint(result.next),
 					buffer: result.next.buffer,
 					optionsTerminated: result.next.optionsTerminated,
 					state: newState,
@@ -4830,6 +5002,7 @@ function merge(...args) {
 				const newState = mergeResultState(parser, currentContext, parserState, result, i);
 				const newContext = {
 					...currentContext,
+					...require_passthrough.getPassThroughFailureHint(result.next),
 					buffer: result.next.buffer,
 					optionsTerminated: result.next.optionsTerminated,
 					state: newState,
@@ -4869,17 +5042,20 @@ 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) {
 					if (!canTryPositionalLaneAfterFailure(lane, currentContext)) continue;
 				}
 				attemptedLane = true;
-				const result = lane.parse(currentContext);
+				const childContext = require_passthrough.withPassThroughFailure(currentContext, consumingFailure);
+				const result = lane.parse(childContext);
 				laneResults.set(lane, result);
 				if (result.success && result.consumed.length > 0) {
 					currentContext = result.next;
@@ -4889,7 +5065,18 @@ function merge(...args) {
 					madeProgress = true;
 					break;
 				}
+				if (result.success) {
+					const own = require_passthrough.retainConsumingFailureHint(void 0, childContext, result.next);
+					if (own != null) {
+						consumingFailure = require_passthrough.retainConsumingFailure(consumingFailure, own.failure, own.priority);
+						if (error.consumed < own.failure.consumed) error = own.failure;
+					}
+				}
 				if (!result.success) {
+					if (result.consumed > 0 && require_passthrough.matchesOptionToken({
+						leadingNames: lane.leadingNames,
+						usage: parsers.flatMap((parser) => parser.usage)
+					}, currentContext.buffer[0])) consumingFailure = require_passthrough.retainConsumingFailure(consumingFailure, result, lane.priority);
 					if (result.consumed > 0 && consumingError == null) consumingError = {
 						priority: lane.priority,
 						result
@@ -4921,7 +5108,7 @@ function merge(...args) {
 		}
 		return {
 			success: true,
-			next: currentContext,
+			next: require_passthrough.withReturnedConsumingFailure(currentContext, consumingFailure),
 			consumed: allConsumed
 		};
 	};
@@ -4932,17 +5119,20 @@ 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) {
 					if (!canTryPositionalLaneAfterFailure(lane, currentContext)) continue;
 				}
 				attemptedLane = true;
-				const result = await lane.parse(currentContext);
+				const childContext = require_passthrough.withPassThroughFailure(currentContext, consumingFailure);
+				const result = await lane.parse(childContext);
 				laneResults.set(lane, result);
 				if (result.success && result.consumed.length > 0) {
 					currentContext = result.next;
@@ -4952,7 +5142,18 @@ function merge(...args) {
 					madeProgress = true;
 					break;
 				}
+				if (result.success) {
+					const own = require_passthrough.retainConsumingFailureHint(void 0, childContext, result.next);
+					if (own != null) {
+						consumingFailure = require_passthrough.retainConsumingFailure(consumingFailure, own.failure, own.priority);
+						if (error.consumed < own.failure.consumed) error = own.failure;
+					}
+				}
 				if (!result.success) {
+					if (result.consumed > 0 && require_passthrough.matchesOptionToken({
+						leadingNames: lane.leadingNames,
+						usage: parsers.flatMap((parser) => parser.usage)
+					}, currentContext.buffer[0])) consumingFailure = require_passthrough.retainConsumingFailure(consumingFailure, result, lane.priority);
 					if (result.consumed > 0 && consumingError == null) consumingError = {
 						priority: lane.priority,
 						result
@@ -4984,7 +5185,7 @@ function merge(...args) {
 		}
 		return {
 			success: true,
-			next: currentContext,
+			next: require_passthrough.withReturnedConsumingFailure(currentContext, consumingFailure),
 			consumed: allConsumed
 		};
 	};
@@ -5527,6 +5728,10 @@ function merge(...args) {
 	};
 	require_internal_parser.defineParseLanes(mergeParser, mergeParseLanes);
 	require_internal_parser.defineInheritedAnnotationParser(mergeParser);
+	require_passthrough.defineReachableChildren(mergeParser, parsers, (state) => sorted.map(([parser], index) => ({
+		parser,
+		state: require_annotation_state.getWrappedChildParseState(state, extractParserStateFromState(parser, state, index), parser)
+	})));
 	return require_modifiers.fluent(require_short_option.scopeParser(mergeParser, require_short_option.combinedOptionScope(parsers, parsers.map((_, index) => index))));
 }
 /**
@@ -5717,6 +5922,7 @@ function tryParseSuggestList(context, stateArray, parsers, matchedParsers, remai
 					const mergedExec = require_execution_context.mergeChildExec(context.exec, result$1.next.exec);
 					return preParseSuggestLoop({
 						...context,
+						...require_passthrough.getPassThroughFailureHint(result$1.next),
 						buffer: result$1.next.buffer,
 						optionsTerminated: result$1.next.optionsTerminated,
 						state: stateArray,
@@ -5744,6 +5950,7 @@ function tryParseSuggestList(context, stateArray, parsers, matchedParsers, remai
 			const mergedExec = require_execution_context.mergeChildExec(context.exec, result.next.exec);
 			return {
 				...context,
+				...require_passthrough.getPassThroughFailureHint(result.next),
 				buffer: result.next.buffer,
 				optionsTerminated: result.next.optionsTerminated,
 				state: stateArray,
@@ -5763,10 +5970,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) => require_passthrough.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 +5983,15 @@ function concat(...parsers) {
 				error: require_message.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) || require_passthrough.getOptionMatch(parser, stateArray[index], currentContext.buffer[0])?.continuesCommand === true || passThroughParsers.size > 0 && !currentContext.optionsTerminated && require_passthrough.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(require_passthrough.withPassThroughFailure(withChildContext$1(currentContext, index, stateArray[index], parser), consumingFailure, require_passthrough.getPassThroughPriority(parser, stateArray[index], currentContext.buffer[0])));
 				if (result.success && result.consumed.length > 0) {
 					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,
+						...require_passthrough.getPassThroughFailureHint(result.next),
 						buffer: result.next.buffer,
 						optionsTerminated: result.next.optionsTerminated,
 						state: newStateArray,
@@ -5790,14 +6000,23 @@ 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 = require_passthrough.retainConsumingFailureHint(consumingFailure, currentContext, result.next);
+					if (consumingFailure != null && error.consumed < consumingFailure.failure.consumed) error = consumingFailure.failure;
+				} else {
+					const match = require_passthrough.getOptionMatch(parser, stateArray[index], currentContext.buffer[0]);
+					if (result.consumed > 0 && match != null) consumingFailure = require_passthrough.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(require_passthrough.withPassThroughFailure(withChildContext$1(currentContext, index, stateArray[index], parser), consumingFailure, require_passthrough.getPassThroughPriority(parser, stateArray[index], currentContext.buffer[0])));
 				if (result.success && result.consumed.length < 1) {
 					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);
@@ -5825,7 +6044,7 @@ function concat(...parsers) {
 		}
 		return {
 			success: true,
-			next: currentContext,
+			next: require_passthrough.withReturnedConsumingFailure(currentContext, consumingFailure),
 			consumed: allConsumed
 		};
 	};
@@ -5833,6 +6052,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 +6060,15 @@ function concat(...parsers) {
 				error: require_message.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) || require_passthrough.getOptionMatch(parser, stateArray[index], currentContext.buffer[0])?.continuesCommand === true || passThroughParsers.size > 0 && !currentContext.optionsTerminated && require_passthrough.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(require_passthrough.withPassThroughFailure(withChildContext$1(currentContext, index, stateArray[index], parser), consumingFailure, require_passthrough.getPassThroughPriority(parser, stateArray[index], currentContext.buffer[0])));
 				if (result.success && result.consumed.length > 0) {
 					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,
+						...require_passthrough.getPassThroughFailureHint(result.next),
 						buffer: result.next.buffer,
 						optionsTerminated: result.next.optionsTerminated,
 						state: newStateArray,
@@ -5856,14 +6077,23 @@ 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 = require_passthrough.retainConsumingFailureHint(consumingFailure, currentContext, result.next);
+					if (consumingFailure != null && error.consumed < consumingFailure.failure.consumed) error = consumingFailure.failure;
+				} else {
+					const match = require_passthrough.getOptionMatch(parser, stateArray[index], currentContext.buffer[0]);
+					if (result.consumed > 0 && match != null) consumingFailure = require_passthrough.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(require_passthrough.withPassThroughFailure(withChildContext$1(currentContext, index, stateArray[index], parser), consumingFailure, require_passthrough.getPassThroughPriority(parser, stateArray[index], currentContext.buffer[0])));
 				if (result.success && result.consumed.length < 1) {
 					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);
@@ -5891,7 +6121,7 @@ function concat(...parsers) {
 		}
 		return {
 			success: true,
-			next: currentContext,
+			next: require_passthrough.withReturnedConsumingFailure(currentContext, consumingFailure),
 			consumed: allConsumed
 		};
 	};
@@ -6162,6 +6392,10 @@ function concat(...parsers) {
 		}
 	};
 	require_internal_parser.defineInheritedAnnotationParser(concatParser);
+	require_passthrough.defineReachableChildren(concatParser, parsers, (state) => parsers.map((parser, index) => ({
+		parser,
+		state: require_annotation_state.getWrappedChildParseState(state, state[index], parser)
+	})));
 	return require_modifiers.fluent(require_short_option.scopeParser(concatParser, require_short_option.combinedOptionScope(parsers, parsers.map((_, index) => index))));
 }
 function group(label, parser, options = {}) {
@@ -6280,6 +6514,11 @@ function group(label, parser, options = {}) {
 		configurable: true,
 		enumerable: false
 	});
+	require_passthrough.delegateKnownCompletion(groupParser, parser);
+	require_passthrough.defineReachableChildren(groupParser, [parser], (state) => [{
+		parser,
+		state
+	}]);
 	return require_modifiers.fluent(require_short_option.scopeParser(groupParser, require_short_option.combinedOptionScope([parser])));
 }
 /**
@@ -6390,13 +6629,14 @@ function conditional(discriminator, branches, defaultBranch, options) {
 		return options?.errors?.noMatch ? typeof options.errors.noMatch === "function" ? options.errors.noMatch(noMatchContext) : options.errors.noMatch : generateNoMatchError(noMatchContext);
 	};
 	const optionScope = require_short_option.conditionalOptionScope(discriminator, defaultBranch, branchParsers.map(([, p]) => p));
+	const selectBranch = (selected, table, fallback) => selected.kind === "default" ? fallback : table[selected.key];
 	const parseSync = (context) => {
 		const state = context.state ?? initialState;
 		const syncDiscriminator = discriminator;
 		const syncBranches = branches;
 		const syncDefaultBranch = defaultBranch;
 		if (state.selectedBranch !== void 0) {
-			const branchParser = state.selectedBranch.kind === "default" ? syncDefaultBranch : syncBranches[state.selectedBranch.key];
+			const branchParser = selectBranch(state.selectedBranch, syncBranches, syncDefaultBranch);
 			const branchResult = branchParser.parse(withChildContext$1(context, "_branch", state.branchState, branchParser, branchParser.usage));
 			if (branchResult.success) {
 				const mergedExec = require_execution_context.mergeChildExec(context.exec, branchResult.next.exec);
@@ -6437,6 +6677,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 								dependencyRegistry: discriminatorExec.dependencyRegistry
 							} : {}
 						}, "_branch", branchParser.initialState, branchParser, branchParser.usage),
+						...require_passthrough.getPassThroughFailureHint(discriminatorResult.next),
 						buffer: discriminatorResult.next.buffer,
 						optionsTerminated: discriminatorResult.next.optionsTerminated
 					});
@@ -6536,7 +6777,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 	const parseAsync = async (context) => {
 		const state = context.state ?? initialState;
 		if (state.selectedBranch !== void 0) {
-			const branchParser = state.selectedBranch.kind === "default" ? defaultBranch : branches[state.selectedBranch.key];
+			const branchParser = selectBranch(state.selectedBranch, branches, defaultBranch);
 			const branchResult = await branchParser.parse(withChildContext$1(context, "_branch", state.branchState, branchParser, branchParser.usage));
 			if (branchResult.success) {
 				const mergedExec = require_execution_context.mergeChildExec(context.exec, branchResult.next.exec);
@@ -6565,6 +6806,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 				const discriminatorExec = require_execution_context.mergeChildExec(context.exec, discriminatorResult.next.exec);
 				const speculationContext = {
 					...require_short_option.withOptionScope(context, unionLeadingNames([...branchParsers.map(([, p]) => p), ...defaultBranch ? [defaultBranch] : []])),
+					...require_passthrough.getPassThroughFailureHint(discriminatorResult.next),
 					buffer: discriminatorResult.next.buffer,
 					optionsTerminated: discriminatorResult.next.optionsTerminated,
 					...discriminatorExec != null ? {
@@ -6696,6 +6938,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 								dependencyRegistry: discriminatorExec.dependencyRegistry
 							} : {}
 						}, "_branch", branchParser.initialState, branchParser, branchParser.usage),
+						...require_passthrough.getPassThroughFailureHint(discriminatorResult.next),
 						buffer: discriminatorResult.next.buffer,
 						optionsTerminated: discriminatorResult.next.optionsTerminated
 					});
@@ -7650,10 +7893,39 @@ function conditional(discriminator, branches, defaultBranch, options) {
 		configurable: true,
 		enumerable: false
 	});
+	const reachableBranches = (state) => {
+		if (state.selectedBranch != null) {
+			const branch = selectBranch(state.selectedBranch, branches, defaultBranch);
+			return branch == null ? [] : [{
+				branch,
+				state: state.branchState
+			}];
+		}
+		const known = require_passthrough.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
+		}));
+	};
+	require_passthrough.defineReachableChildren(conditionalParser, [discriminator, ...allBranchParsers], (state) => [...state.selectedBranch == null ? [{
+		parser: discriminator,
+		state: require_annotation_state.getWrappedChildParseState(state, state.discriminatorState, discriminator)
+	}] : [], ...reachableBranches(state).map(({ branch, state: childState }) => ({
+		parser: branch,
+		state: require_annotation_state.getWrappedChildParseState(state, childState, branch)
+	}))]);
 	return require_modifiers.fluent(require_short_option.scopeParser(conditionalParser, optionScope.source, (context) => {
 		const selected = context.state?.selectedBranch;
 		if (selected != null) {
-			const branch = selected.kind === "default" ? defaultBranch : branches[selected.key];
+			const branch = selectBranch(selected, branches, defaultBranch);
 			if (branch != null) optionScope.select(context, branch);
 		}
 	}));