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

package/dist/extension.cjs

@@ -3,6 +3,7 @@ const require_mode_dispatch = require('./internal/mode-dispatch.cjs');
 const require_internal_parser = require('./internal/parser.cjs');
 const require_annotation_state = require('./annotation-state.cjs');
 const require_short_option = require('./short-option.cjs');
+const require_passthrough = require('./internal/passthrough.cjs');
 const require_phase2_seed = require('./phase2-seed.cjs');
 
 //#region src/extension.ts
@@ -86,9 +87,27 @@ function delegateSuggestNodes(innerParser, outerParser, state, path, innerState,
 function mapSourceMetadata(parser, mapSource) {
 	return require_internal_parser.composeWrappedSourceMetadata(parser.dependencyMetadata, mapSource);
 }
+/**
+* Delegates CLI option matching and capture priority through a parser wrapper.
+* Use the same child-state projection as the wrapper's parse method. This
+* preserves selected command options without changing public leading names.
+*
+* @param wrapper The parser being constructed.
+* @param inner Its wrapped CLI parser.
+* @param getInnerState Projects the wrapper state to the CLI parser state.
+* @throws {TypeError} If metadata cannot be defined on the wrapper.
+* @since 1.0.11
+*/
+function delegateOptionParsing(wrapper, inner, getInnerState) {
+	require_passthrough.defineReachableChildren(wrapper, [inner], (state) => [{
+		parser: inner,
+		state: getInnerState(state)
+	}]);
+}
 
 //#endregion
 exports.defineTraits = defineTraits;
+exports.delegateOptionParsing = delegateOptionParsing;
 exports.delegateSuggestNodes = delegateSuggestNodes;
 exports.dispatchByMode = require_mode_dispatch.dispatchByMode;
 exports.extractPhase2SeedKey = require_phase2_seed.extractPhase2SeedKey;

package/dist/extension.d.cts

@@ -105,5 +105,17 @@ declare function delegateSuggestNodes<TInnerState>(innerParser: Parser<Mode, unk
  * @since 1.0.0
  */
 declare function mapSourceMetadata<M extends Mode, TValue, TState>(parser: Pick<Parser<M, TValue, TState>, "dependencyMetadata">, mapSource: (source: ParserSourceMetadata<M, TValue, TState>) => ParserSourceMetadata<M, TValue, TState>): Parser<M, TValue, TState>["dependencyMetadata"] | undefined;
+/**
+ * Delegates CLI option matching and capture priority through a parser wrapper.
+ * Use the same child-state projection as the wrapper's parse method. This
+ * preserves selected command options without changing public leading names.
+ *
+ * @param wrapper The parser being constructed.
+ * @param inner Its wrapped CLI parser.
+ * @param getInnerState Projects the wrapper state to the CLI parser state.
+ * @throws {TypeError} If metadata cannot be defined on the wrapper.
+ * @since 1.0.11
+ */
+declare function delegateOptionParsing<TOuterState, TInnerState>(wrapper: Parser<Mode, unknown, TOuterState>, inner: Parser<Mode, unknown, TInnerState>, getInnerState: (state: TOuterState) => TInnerState): void;
 //#endregion
-export { ParserSourceMetadata, ParserTraits, SuggestNode, defineTraits, delegateSuggestNodes, dispatchByMode, extractPhase2SeedKey, getTraits, inheritAnnotations, inheritOptionScope, injectAnnotations, isInjectedAnnotationState, mapModeValue, mapSourceMetadata, unwrapInjectedAnnotationState, withAnnotationView, wrapForMode };
+export { ParserSourceMetadata, ParserTraits, SuggestNode, defineTraits, delegateOptionParsing, delegateSuggestNodes, dispatchByMode, extractPhase2SeedKey, getTraits, inheritAnnotations, inheritOptionScope, injectAnnotations, isInjectedAnnotationState, mapModeValue, mapSourceMetadata, unwrapInjectedAnnotationState, withAnnotationView, wrapForMode };

package/dist/extension.d.ts

@@ -105,5 +105,17 @@ declare function delegateSuggestNodes<TInnerState>(innerParser: Parser<Mode, unk
  * @since 1.0.0
  */
 declare function mapSourceMetadata<M extends Mode, TValue, TState>(parser: Pick<Parser<M, TValue, TState>, "dependencyMetadata">, mapSource: (source: ParserSourceMetadata<M, TValue, TState>) => ParserSourceMetadata<M, TValue, TState>): Parser<M, TValue, TState>["dependencyMetadata"] | undefined;
+/**
+ * Delegates CLI option matching and capture priority through a parser wrapper.
+ * Use the same child-state projection as the wrapper's parse method. This
+ * preserves selected command options without changing public leading names.
+ *
+ * @param wrapper The parser being constructed.
+ * @param inner Its wrapped CLI parser.
+ * @param getInnerState Projects the wrapper state to the CLI parser state.
+ * @throws {TypeError} If metadata cannot be defined on the wrapper.
+ * @since 1.0.11
+ */
+declare function delegateOptionParsing<TOuterState, TInnerState>(wrapper: Parser<Mode, unknown, TOuterState>, inner: Parser<Mode, unknown, TInnerState>, getInnerState: (state: TOuterState) => TInnerState): void;
 //#endregion
-export { ParserSourceMetadata, ParserTraits, SuggestNode, defineTraits, delegateSuggestNodes, dispatchByMode, extractPhase2SeedKey, getTraits, inheritAnnotations, inheritOptionScope, injectAnnotations, isInjectedAnnotationState, mapModeValue, mapSourceMetadata, unwrapInjectedAnnotationState, withAnnotationView, wrapForMode };
+export { ParserSourceMetadata, ParserTraits, SuggestNode, defineTraits, delegateOptionParsing, delegateSuggestNodes, dispatchByMode, extractPhase2SeedKey, getTraits, inheritAnnotations, inheritOptionScope, injectAnnotations, isInjectedAnnotationState, mapModeValue, mapSourceMetadata, unwrapInjectedAnnotationState, withAnnotationView, wrapForMode };

package/dist/extension.js

@@ -3,6 +3,7 @@ import { dispatchByMode, mapModeValue, wrapForMode } from "./internal/mode-dispa
 import { annotationWrapperRequiresSourceBindingKey, composeWrappedSourceMetadata, defineInheritedAnnotationParser, getDelegatingSuggestRuntimeNodes, inheritParentAnnotationsKey, unmatchedNonCliDependencySourceStateMarker } from "./internal/parser.js";
 import { withAnnotationView } from "./annotation-state.js";
 import { inheritOptionScope } from "./short-option.js";
+import { defineReachableChildren } from "./internal/passthrough.js";
 import { extractPhase2SeedKey } from "./phase2-seed.js";
 
 //#region src/extension.ts
@@ -86,6 +87,23 @@ function delegateSuggestNodes(innerParser, outerParser, state, path, innerState,
 function mapSourceMetadata(parser, mapSource) {
 	return composeWrappedSourceMetadata(parser.dependencyMetadata, mapSource);
 }
+/**
+* Delegates CLI option matching and capture priority through a parser wrapper.
+* Use the same child-state projection as the wrapper's parse method. This
+* preserves selected command options without changing public leading names.
+*
+* @param wrapper The parser being constructed.
+* @param inner Its wrapped CLI parser.
+* @param getInnerState Projects the wrapper state to the CLI parser state.
+* @throws {TypeError} If metadata cannot be defined on the wrapper.
+* @since 1.0.11
+*/
+function delegateOptionParsing(wrapper, inner, getInnerState) {
+	defineReachableChildren(wrapper, [inner], (state) => [{
+		parser: inner,
+		state: getInnerState(state)
+	}]);
+}
 
 //#endregion
-export { defineTraits, delegateSuggestNodes, dispatchByMode, extractPhase2SeedKey, getTraits, inheritAnnotations, inheritOptionScope$1 as inheritOptionScope, injectAnnotations, isInjectedAnnotationState, mapModeValue, mapSourceMetadata, unwrapInjectedAnnotationState, withAnnotationView, wrapForMode };
+export { defineTraits, delegateOptionParsing, delegateSuggestNodes, dispatchByMode, extractPhase2SeedKey, getTraits, inheritAnnotations, inheritOptionScope$1 as inheritOptionScope, injectAnnotations, isInjectedAnnotationState, mapModeValue, mapSourceMetadata, unwrapInjectedAnnotationState, withAnnotationView, wrapForMode };

package/dist/internal/passthrough.cjs

@@ -0,0 +1,284 @@
+
+//#region src/internal/passthrough.ts
+/** Retains the deepest diagnostic and highest matching lane priority. @internal */
+function retainConsumingFailure(current, failure, priority) {
+	return {
+		failure: current != null && current.failure.consumed >= failure.consumed ? current.failure : failure,
+		priority: Math.max(current?.priority ?? -Infinity, priority)
+	};
+}
+const passThroughFailure = Symbol("passThroughFailure");
+/**
+* Gets the sibling failure that prevents pass-through capture at this cursor.
+* Stale hints inherited through a successful child do not block later input.
+* @param context The pass-through parser's context.
+* @returns The failure at this cursor, or undefined if capture is allowed.
+* @internal
+*/
+function getPassThroughFailure(context, capturePriority$1 = -Infinity) {
+	const hinted = context;
+	const hint = hinted[passThroughFailure];
+	return hint?.buffer === context.buffer && hint.optionsTerminated === context.optionsTerminated && hint.failure.priority >= capturePriority$1 ? hint.failure : void 0;
+}
+/**
+* Carries a sibling's consuming failure into a child parse call. Only
+* passThrough consults the hint; ordinary alternatives may still recover.
+* @param context The child context, without modifying the parent's context.
+* @param failure The deepest matching consuming failure at this input position.
+* @returns A context with a hint for active option-like input, or the original.
+* @internal
+*/
+function withPassThroughFailure(context, failure, capturePriority$1 = -Infinity) {
+	const incoming = context;
+	if (incoming[passThroughFailure]?.own != null) {
+		const { own: _own,...hint } = incoming[passThroughFailure];
+		const stripped = {
+			...context,
+			[passThroughFailure]: hint
+		};
+		context = stripped;
+	}
+	const token = context.buffer[0];
+	const existing = getPassThroughFailure(context);
+	if (existing != null && existing.priority < capturePriority$1) {
+		const hinted$1 = context;
+		const { [passThroughFailure]: _discarded,...rest } = hinted$1;
+		context = rest;
+	}
+	if (failure == null || failure.failure.consumed < 1 || failure.priority < capturePriority$1 || context.optionsTerminated || token == null || token === "--" || !/^[-/+]/.test(token)) return context;
+	const retained = getPassThroughFailure(context);
+	const combined = retainConsumingFailure(retained, failure.failure, failure.priority);
+	const hinted = {
+		...context,
+		[passThroughFailure]: {
+			buffer: context.buffer,
+			optionsTerminated: context.optionsTerminated,
+			failure: combined
+		}
+	};
+	return hinted;
+}
+/** Reads locally originated diagnostics at the same cursor. @internal */
+function getOwnConsumingFailure(context) {
+	const hinted = context;
+	const hint = hinted[passThroughFailure];
+	return hint?.buffer === context.buffer && hint.optionsTerminated === context.optionsTerminated ? hint.own : void 0;
+}
+/**
+* Returns a successful child's local diagnostic to its parent without merging
+* its provenance with an inherited sibling diagnostic. Both share a cursor.
+* @internal
+*/
+function withReturnedConsumingFailure(context, failure) {
+	const next = withPassThroughFailure(context, failure);
+	if (failure == null || getPassThroughFailure(next) == null) return next;
+	const token = next.buffer[0];
+	if (next.optionsTerminated || token == null || token === "--" || !/^[-/+]/.test(token) || failure.failure.consumed < 1) return next;
+	const hinted = next;
+	const hint = hinted[passThroughFailure];
+	if (hint == null) return next;
+	const returned = {
+		...next,
+		[passThroughFailure]: {
+			...hint,
+			own: failure
+		}
+	};
+	return returned;
+}
+/** Retains a child's own rejected option failure at the parent's cursor. @internal */
+function retainConsumingFailureHint(current, context, next) {
+	if (next.buffer !== context.buffer || next.optionsTerminated !== context.optionsTerminated) return current;
+	const own = getOwnConsumingFailure(next);
+	return own == null || own === getOwnConsumingFailure(context) ? current : retainConsumingFailure(current, own.failure, own.priority);
+}
+const capturePriority = Symbol("capturePriority");
+/** Checks for capture through usage-preserving wrappers. @internal */
+function hasPassThroughUsage(usage) {
+	return usage.some((term) => term.type === "passthrough" || (term.type === "optional" || term.type === "multiple") && hasPassThroughUsage(term.terms) || term.type === "exclusive" && term.terms.some(hasPassThroughUsage));
+}
+/**
+* Gets the priority of reachable capture, respecting an explicit override.
+* @param parser The parser whose capture priority is needed.
+* @param state The current parser state.
+* @param token The current token, omitted for an unfiltered priority lookup.
+* @returns The capture priority, or undefined when capture is absent.
+* @internal
+*/
+function getPassThroughPriority(parser, state = parser.initialState, token) {
+	if (!hasPassThroughUsage(parser.usage)) return void 0;
+	const annotated = parser;
+	const hint = annotated[capturePriority];
+	if (hint == null) return parser.priority;
+	const priority = hint.getPriority == null ? hint.priority : hint.getPriority(state, token);
+	return priority == null ? void 0 : hint.ownerPriority === parser.priority ? priority : parser.priority;
+}
+/**
+* Records capture priority separately from unrelated children's priorities.
+* @param parser The newly constructed parser.
+* @param children Its transparent children.
+* @param getPriority Optional state-aware capture priority lookup.
+* @internal
+*/
+function definePassThroughPriority(parser, children, getPriority) {
+	const priorities = children.filter((child) => hasPassThroughUsage(child.usage)).map((child) => getPassThroughPriority(child) ?? child.priority);
+	if (priorities.length === 0) return;
+	Object.defineProperty(parser, capturePriority, {
+		value: {
+			ownerPriority: parser.priority,
+			priority: Math.max(...priorities),
+			getPriority
+		},
+		enumerable: true
+	});
+}
+/**
+* Copies only a cursor-valid hint when rebuilding a child context.
+* @param context The successful child's context.
+* @returns Private hint properties, or an empty object for stale hints.
+* @internal
+*/
+function getPassThroughFailureHint(context) {
+	const hinted = context;
+	const hint = hinted[passThroughFailure];
+	return hint != null && getPassThroughFailure(context) != null ? { [passThroughFailure]: hint } : {};
+}
+/** Finds a Boolean option through usage-preserving wrappers. */
+function hasFlagUsage(usage, name) {
+	return usage.some((term) => term.type === "option" && term.metavar == null && term.names.some((optionName) => optionName === name) || (term.type === "optional" || term.type === "multiple") && hasFlagUsage(term.terms, name) || term.type === "exclusive" && term.terms.some((terms) => hasFlagUsage(terms, name)));
+}
+/** Matches exact options, attached values, and leading bundled flags. */
+function matchesOptionToken(parser, token) {
+	if (token == null || token === "--" || !/^[-/+]/.test(token)) return false;
+	if (parser.leadingNames.has(token)) return true;
+	const slashOption = token.startsWith("/");
+	const separator = slashOption ? token.indexOf(":") : token.startsWith("-") ? token.indexOf("=") : -1;
+	if (separator > (slashOption ? 0 : 2) && parser.leadingNames.has(token.slice(0, separator))) return true;
+	const shortName = token.slice(0, 2);
+	return token.length > 2 && /^-[^-]$/.test(shortName) && parser.leadingNames.has(shortName) && hasFlagUsage(parser.usage, shortName);
+}
+const optionMatchKey = Symbol("optionMatch");
+/**
+* Records state-aware option matching without changing public leading names.
+* @param parser The newly constructed transparent parser.
+* @param match Finds a reachable known-option lane.
+* @internal
+*/
+function defineOptionMatch(parser, match) {
+	Object.defineProperty(parser, optionMatchKey, {
+		value: {
+			ownerPriority: parser.priority,
+			match
+		},
+		enumerable: true
+	});
+}
+/**
+* Finds a matching option's actual priority, including selected command children.
+* @param parser The parser to inspect.
+* @param state Its current state.
+* @param token The current token.
+* @returns A reachable option match, or undefined.
+* @internal
+*/
+function getOptionMatch(parser, state, token) {
+	if (token == null || token === "--" || !/^[-/+]/.test(token)) return void 0;
+	const annotated = parser;
+	const matcher = annotated[optionMatchKey];
+	if (matcher != null) {
+		const match = matcher.match(state, token);
+		return match == null || matcher.ownerPriority === parser.priority ? match : {
+			...match,
+			priority: parser.priority
+		};
+	}
+	return matchesOptionToken(parser, token) ? {
+		priority: parser.priority,
+		continuesCommand: false
+	} : void 0;
+}
+/**
+* Combines option matches while retaining active command continuation.
+* @param matches Matches from transparent children.
+* @returns Their highest priority and whether any matching command continues.
+* @internal
+*/
+function combineOptionMatches(matches) {
+	const found = matches.filter((match) => match != null);
+	return found.length === 0 ? void 0 : {
+		priority: Math.max(...found.map((match) => match.priority)),
+		continuesCommand: found.some((match) => match.continuesCommand)
+	};
+}
+const knownCompletionKey = Symbol("knownCompletion");
+/** Marks a completion value that can be inspected without running user code. @internal */
+function defineKnownCompletion(parser, value) {
+	defineKnownCompletionLookup(parser, (state) => ({ value: value(state) }));
+}
+/** Registers a known-value lookup that may decline unknown completion. @internal */
+function defineKnownCompletionLookup(parser, value) {
+	Object.defineProperty(parser, knownCompletionKey, {
+		value: {
+			complete: parser.complete,
+			value
+		},
+		enumerable: true
+	});
+}
+/** Looks up a known value only while the original completion is intact. @internal */
+function getKnownCompletion(parser, state) {
+	const annotated = parser;
+	const hint = annotated[knownCompletionKey];
+	return hint != null && hint.complete === parser.complete ? hint.value(state) : void 0;
+}
+/** Combines the priorities of currently reachable capture lanes. @internal */
+function combinePassThroughPriorities(priorities) {
+	const found = priorities.filter((priority) => priority != null);
+	return found.length === 0 ? void 0 : Math.max(...found);
+}
+/** Forwards known completion through a state-preserving wrapper. @internal */
+function delegateKnownCompletion(wrapper, inner) {
+	Object.defineProperty(wrapper, knownCompletionKey, {
+		value: {
+			complete: wrapper.complete,
+			value: (state) => getKnownCompletion(inner, state)
+		},
+		enumerable: true
+	});
+}
+/**
+* Installs option and capture inspection from one pure child-state selector.
+* Static children retain capture metadata even when no child is selected yet.
+* Selection must not execute parsing, completion, or user callbacks. Potential
+* alternatives remain candidates until parse-time replay or canSkip resolves
+* them; inspection cannot safely predict opaque custom parser callbacks.
+* @internal
+*/
+function defineReachableChildren(parser, children, select) {
+	defineOptionMatch(parser, (state, token) => combineOptionMatches(select(state).map((child) => {
+		const match = getOptionMatch(child.parser, child.state, token);
+		return match == null || !child.continuesCommand ? match : {
+			...match,
+			continuesCommand: true
+		};
+	})));
+	definePassThroughPriority(parser, children, (state, token) => combinePassThroughPriorities(select(state).map((child) => getPassThroughPriority(child.parser, child.state, token))));
+}
+
+//#endregion
+exports.defineKnownCompletion = defineKnownCompletion;
+exports.defineKnownCompletionLookup = defineKnownCompletionLookup;
+exports.definePassThroughPriority = definePassThroughPriority;
+exports.defineReachableChildren = defineReachableChildren;
+exports.delegateKnownCompletion = delegateKnownCompletion;
+exports.getKnownCompletion = getKnownCompletion;
+exports.getOptionMatch = getOptionMatch;
+exports.getPassThroughFailure = getPassThroughFailure;
+exports.getPassThroughFailureHint = getPassThroughFailureHint;
+exports.getPassThroughPriority = getPassThroughPriority;
+exports.hasPassThroughUsage = hasPassThroughUsage;
+exports.matchesOptionToken = matchesOptionToken;
+exports.retainConsumingFailure = retainConsumingFailure;
+exports.retainConsumingFailureHint = retainConsumingFailureHint;
+exports.withPassThroughFailure = withPassThroughFailure;
+exports.withReturnedConsumingFailure = withReturnedConsumingFailure;

package/dist/internal/passthrough.js

@@ -0,0 +1,268 @@
+//#region src/internal/passthrough.ts
+/** Retains the deepest diagnostic and highest matching lane priority. @internal */
+function retainConsumingFailure(current, failure, priority) {
+	return {
+		failure: current != null && current.failure.consumed >= failure.consumed ? current.failure : failure,
+		priority: Math.max(current?.priority ?? -Infinity, priority)
+	};
+}
+const passThroughFailure = Symbol("passThroughFailure");
+/**
+* Gets the sibling failure that prevents pass-through capture at this cursor.
+* Stale hints inherited through a successful child do not block later input.
+* @param context The pass-through parser's context.
+* @returns The failure at this cursor, or undefined if capture is allowed.
+* @internal
+*/
+function getPassThroughFailure(context, capturePriority$1 = -Infinity) {
+	const hinted = context;
+	const hint = hinted[passThroughFailure];
+	return hint?.buffer === context.buffer && hint.optionsTerminated === context.optionsTerminated && hint.failure.priority >= capturePriority$1 ? hint.failure : void 0;
+}
+/**
+* Carries a sibling's consuming failure into a child parse call. Only
+* passThrough consults the hint; ordinary alternatives may still recover.
+* @param context The child context, without modifying the parent's context.
+* @param failure The deepest matching consuming failure at this input position.
+* @returns A context with a hint for active option-like input, or the original.
+* @internal
+*/
+function withPassThroughFailure(context, failure, capturePriority$1 = -Infinity) {
+	const incoming = context;
+	if (incoming[passThroughFailure]?.own != null) {
+		const { own: _own,...hint } = incoming[passThroughFailure];
+		const stripped = {
+			...context,
+			[passThroughFailure]: hint
+		};
+		context = stripped;
+	}
+	const token = context.buffer[0];
+	const existing = getPassThroughFailure(context);
+	if (existing != null && existing.priority < capturePriority$1) {
+		const hinted$1 = context;
+		const { [passThroughFailure]: _discarded,...rest } = hinted$1;
+		context = rest;
+	}
+	if (failure == null || failure.failure.consumed < 1 || failure.priority < capturePriority$1 || context.optionsTerminated || token == null || token === "--" || !/^[-/+]/.test(token)) return context;
+	const retained = getPassThroughFailure(context);
+	const combined = retainConsumingFailure(retained, failure.failure, failure.priority);
+	const hinted = {
+		...context,
+		[passThroughFailure]: {
+			buffer: context.buffer,
+			optionsTerminated: context.optionsTerminated,
+			failure: combined
+		}
+	};
+	return hinted;
+}
+/** Reads locally originated diagnostics at the same cursor. @internal */
+function getOwnConsumingFailure(context) {
+	const hinted = context;
+	const hint = hinted[passThroughFailure];
+	return hint?.buffer === context.buffer && hint.optionsTerminated === context.optionsTerminated ? hint.own : void 0;
+}
+/**
+* Returns a successful child's local diagnostic to its parent without merging
+* its provenance with an inherited sibling diagnostic. Both share a cursor.
+* @internal
+*/
+function withReturnedConsumingFailure(context, failure) {
+	const next = withPassThroughFailure(context, failure);
+	if (failure == null || getPassThroughFailure(next) == null) return next;
+	const token = next.buffer[0];
+	if (next.optionsTerminated || token == null || token === "--" || !/^[-/+]/.test(token) || failure.failure.consumed < 1) return next;
+	const hinted = next;
+	const hint = hinted[passThroughFailure];
+	if (hint == null) return next;
+	const returned = {
+		...next,
+		[passThroughFailure]: {
+			...hint,
+			own: failure
+		}
+	};
+	return returned;
+}
+/** Retains a child's own rejected option failure at the parent's cursor. @internal */
+function retainConsumingFailureHint(current, context, next) {
+	if (next.buffer !== context.buffer || next.optionsTerminated !== context.optionsTerminated) return current;
+	const own = getOwnConsumingFailure(next);
+	return own == null || own === getOwnConsumingFailure(context) ? current : retainConsumingFailure(current, own.failure, own.priority);
+}
+const capturePriority = Symbol("capturePriority");
+/** Checks for capture through usage-preserving wrappers. @internal */
+function hasPassThroughUsage(usage) {
+	return usage.some((term) => term.type === "passthrough" || (term.type === "optional" || term.type === "multiple") && hasPassThroughUsage(term.terms) || term.type === "exclusive" && term.terms.some(hasPassThroughUsage));
+}
+/**
+* Gets the priority of reachable capture, respecting an explicit override.
+* @param parser The parser whose capture priority is needed.
+* @param state The current parser state.
+* @param token The current token, omitted for an unfiltered priority lookup.
+* @returns The capture priority, or undefined when capture is absent.
+* @internal
+*/
+function getPassThroughPriority(parser, state = parser.initialState, token) {
+	if (!hasPassThroughUsage(parser.usage)) return void 0;
+	const annotated = parser;
+	const hint = annotated[capturePriority];
+	if (hint == null) return parser.priority;
+	const priority = hint.getPriority == null ? hint.priority : hint.getPriority(state, token);
+	return priority == null ? void 0 : hint.ownerPriority === parser.priority ? priority : parser.priority;
+}
+/**
+* Records capture priority separately from unrelated children's priorities.
+* @param parser The newly constructed parser.
+* @param children Its transparent children.
+* @param getPriority Optional state-aware capture priority lookup.
+* @internal
+*/
+function definePassThroughPriority(parser, children, getPriority) {
+	const priorities = children.filter((child) => hasPassThroughUsage(child.usage)).map((child) => getPassThroughPriority(child) ?? child.priority);
+	if (priorities.length === 0) return;
+	Object.defineProperty(parser, capturePriority, {
+		value: {
+			ownerPriority: parser.priority,
+			priority: Math.max(...priorities),
+			getPriority
+		},
+		enumerable: true
+	});
+}
+/**
+* Copies only a cursor-valid hint when rebuilding a child context.
+* @param context The successful child's context.
+* @returns Private hint properties, or an empty object for stale hints.
+* @internal
+*/
+function getPassThroughFailureHint(context) {
+	const hinted = context;
+	const hint = hinted[passThroughFailure];
+	return hint != null && getPassThroughFailure(context) != null ? { [passThroughFailure]: hint } : {};
+}
+/** Finds a Boolean option through usage-preserving wrappers. */
+function hasFlagUsage(usage, name) {
+	return usage.some((term) => term.type === "option" && term.metavar == null && term.names.some((optionName) => optionName === name) || (term.type === "optional" || term.type === "multiple") && hasFlagUsage(term.terms, name) || term.type === "exclusive" && term.terms.some((terms) => hasFlagUsage(terms, name)));
+}
+/** Matches exact options, attached values, and leading bundled flags. */
+function matchesOptionToken(parser, token) {
+	if (token == null || token === "--" || !/^[-/+]/.test(token)) return false;
+	if (parser.leadingNames.has(token)) return true;
+	const slashOption = token.startsWith("/");
+	const separator = slashOption ? token.indexOf(":") : token.startsWith("-") ? token.indexOf("=") : -1;
+	if (separator > (slashOption ? 0 : 2) && parser.leadingNames.has(token.slice(0, separator))) return true;
+	const shortName = token.slice(0, 2);
+	return token.length > 2 && /^-[^-]$/.test(shortName) && parser.leadingNames.has(shortName) && hasFlagUsage(parser.usage, shortName);
+}
+const optionMatchKey = Symbol("optionMatch");
+/**
+* Records state-aware option matching without changing public leading names.
+* @param parser The newly constructed transparent parser.
+* @param match Finds a reachable known-option lane.
+* @internal
+*/
+function defineOptionMatch(parser, match) {
+	Object.defineProperty(parser, optionMatchKey, {
+		value: {
+			ownerPriority: parser.priority,
+			match
+		},
+		enumerable: true
+	});
+}
+/**
+* Finds a matching option's actual priority, including selected command children.
+* @param parser The parser to inspect.
+* @param state Its current state.
+* @param token The current token.
+* @returns A reachable option match, or undefined.
+* @internal
+*/
+function getOptionMatch(parser, state, token) {
+	if (token == null || token === "--" || !/^[-/+]/.test(token)) return void 0;
+	const annotated = parser;
+	const matcher = annotated[optionMatchKey];
+	if (matcher != null) {
+		const match = matcher.match(state, token);
+		return match == null || matcher.ownerPriority === parser.priority ? match : {
+			...match,
+			priority: parser.priority
+		};
+	}
+	return matchesOptionToken(parser, token) ? {
+		priority: parser.priority,
+		continuesCommand: false
+	} : void 0;
+}
+/**
+* Combines option matches while retaining active command continuation.
+* @param matches Matches from transparent children.
+* @returns Their highest priority and whether any matching command continues.
+* @internal
+*/
+function combineOptionMatches(matches) {
+	const found = matches.filter((match) => match != null);
+	return found.length === 0 ? void 0 : {
+		priority: Math.max(...found.map((match) => match.priority)),
+		continuesCommand: found.some((match) => match.continuesCommand)
+	};
+}
+const knownCompletionKey = Symbol("knownCompletion");
+/** Marks a completion value that can be inspected without running user code. @internal */
+function defineKnownCompletion(parser, value) {
+	defineKnownCompletionLookup(parser, (state) => ({ value: value(state) }));
+}
+/** Registers a known-value lookup that may decline unknown completion. @internal */
+function defineKnownCompletionLookup(parser, value) {
+	Object.defineProperty(parser, knownCompletionKey, {
+		value: {
+			complete: parser.complete,
+			value
+		},
+		enumerable: true
+	});
+}
+/** Looks up a known value only while the original completion is intact. @internal */
+function getKnownCompletion(parser, state) {
+	const annotated = parser;
+	const hint = annotated[knownCompletionKey];
+	return hint != null && hint.complete === parser.complete ? hint.value(state) : void 0;
+}
+/** Combines the priorities of currently reachable capture lanes. @internal */
+function combinePassThroughPriorities(priorities) {
+	const found = priorities.filter((priority) => priority != null);
+	return found.length === 0 ? void 0 : Math.max(...found);
+}
+/** Forwards known completion through a state-preserving wrapper. @internal */
+function delegateKnownCompletion(wrapper, inner) {
+	Object.defineProperty(wrapper, knownCompletionKey, {
+		value: {
+			complete: wrapper.complete,
+			value: (state) => getKnownCompletion(inner, state)
+		},
+		enumerable: true
+	});
+}
+/**
+* Installs option and capture inspection from one pure child-state selector.
+* Static children retain capture metadata even when no child is selected yet.
+* Selection must not execute parsing, completion, or user callbacks. Potential
+* alternatives remain candidates until parse-time replay or canSkip resolves
+* them; inspection cannot safely predict opaque custom parser callbacks.
+* @internal
+*/
+function defineReachableChildren(parser, children, select) {
+	defineOptionMatch(parser, (state, token) => combineOptionMatches(select(state).map((child) => {
+		const match = getOptionMatch(child.parser, child.state, token);
+		return match == null || !child.continuesCommand ? match : {
+			...match,
+			continuesCommand: true
+		};
+	})));
+	definePassThroughPriority(parser, children, (state, token) => combinePassThroughPriorities(select(state).map((child) => getPassThroughPriority(child.parser, child.state, token))));
+}
+
+//#endregion
+export { defineKnownCompletion, defineKnownCompletionLookup, definePassThroughPriority, defineReachableChildren, delegateKnownCompletion, getKnownCompletion, getOptionMatch, getPassThroughFailure, getPassThroughFailureHint, getPassThroughPriority, hasPassThroughUsage, matchesOptionToken, retainConsumingFailure, retainConsumingFailureHint, withPassThroughFailure, withReturnedConsumingFailure };