@optique/core 1.3.1 → 1.3.3

package/dist/doc.cjs

@@ -431,8 +431,16 @@ function formatDocPage(programName, page, options = {}) {
 				column: extraTermOffset
 			}).cursor;
 			const appendAnnotation = (content, layout, style, ambient, quotes) => {
-				const prefix = require_text_layout.placeText(layout.prefix, cursor, descColumnWidth, 1);
-				if (prefix.text !== layout.prefix) description += "\n";
+				let prefixText = layout.prefix;
+				let prefix = require_text_layout.placeText(prefixText, cursor, descColumnWidth, 1);
+				if (prefix.text !== layout.prefix) {
+					description += "\n";
+					prefixText = require_text_layout.trimLeadingSpace(layout.prefix);
+					prefix = require_text_layout.placeText(prefixText, {
+						line: "",
+						column: 0
+					});
+				}
 				const rendered = formatMessage(content, {
 					colors: options.colors ? { resetSuffix: style } : false,
 					quotes,
@@ -440,7 +448,7 @@ function formatDocPage(programName, page, options = {}) {
 					initialWidth: descColumnWidth != null || layout.prefixMetrics.lineCount > 1 ? prefix.cursor.column : void 0
 				}, ambient);
 				const suffix = require_text_layout.placeText(layout.suffix, require_text_layout.placeText(rendered, prefix.cursor).cursor, descColumnWidth);
-				const annotationText = `${layout.prefix}${rendered}${opaqueFormatter && options.colors ? style : ""}${suffix.text}`;
+				const annotationText = `${prefixText}${rendered}${opaqueFormatter && options.colors ? style : ""}${suffix.text}`;
 				description += options.colors ? `${style}${annotationText}${style ? "\x1B[0m" : ""}` : annotationText;
 				cursor = suffix.cursor;
 			};

package/dist/doc.js

@@ -1,5 +1,5 @@
 import { cacheTerminalTheme, renderTerminalTerm, styleCode } from "./terminal-internal.js";
-import { measureAnnotation, measureText, placeText, spaceAfterLabel } from "./text-layout.js";
+import { measureAnnotation, measureText, placeText, spaceAfterLabel, trimLeadingSpace } from "./text-layout.js";
 import { validateLabel, validateProgramName } from "./validate.js";
 import { cloneUsageTerm, formatUsage, formatUsageTerm, isDocHidden } from "./usage.js";
 import { hasAutomaticWidth, minimumUsageWidth, reportAutomaticWidth } from "./terminal-width.js";
@@ -431,8 +431,16 @@ function formatDocPage(programName, page, options = {}) {
 				column: extraTermOffset
 			}).cursor;
 			const appendAnnotation = (content, layout, style, ambient, quotes) => {
-				const prefix = placeText(layout.prefix, cursor, descColumnWidth, 1);
-				if (prefix.text !== layout.prefix) description += "\n";
+				let prefixText = layout.prefix;
+				let prefix = placeText(prefixText, cursor, descColumnWidth, 1);
+				if (prefix.text !== layout.prefix) {
+					description += "\n";
+					prefixText = trimLeadingSpace(layout.prefix);
+					prefix = placeText(prefixText, {
+						line: "",
+						column: 0
+					});
+				}
 				const rendered = formatMessage(content, {
 					colors: options.colors ? { resetSuffix: style } : false,
 					quotes,
@@ -440,7 +448,7 @@ function formatDocPage(programName, page, options = {}) {
 					initialWidth: descColumnWidth != null || layout.prefixMetrics.lineCount > 1 ? prefix.cursor.column : void 0
 				}, ambient);
 				const suffix = placeText(layout.suffix, placeText(rendered, prefix.cursor).cursor, descColumnWidth);
-				const annotationText = `${layout.prefix}${rendered}${opaqueFormatter && options.colors ? style : ""}${suffix.text}`;
+				const annotationText = `${prefixText}${rendered}${opaqueFormatter && options.colors ? style : ""}${suffix.text}`;
 				description += options.colors ? `${style}${annotationText}${style ? "\x1B[0m" : ""}` : annotationText;
 				cursor = suffix.cursor;
 			};

package/dist/extension.cjs

@@ -2,6 +2,7 @@ const require_internal_annotations = require('./internal/annotations.cjs');
 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_passthrough = require('./internal/passthrough.cjs');
 const require_phase2_seed = require('./phase2-seed.cjs');
 
 //#region src/extension.ts
@@ -72,9 +73,25 @@ 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.defineOptionMatch(wrapper, (state, token) => require_passthrough.getOptionMatch(inner, getInnerState(state), token));
+	require_passthrough.definePassThroughPriority(wrapper, [inner], (state, token) => require_passthrough.getPassThroughPriority(inner, getInnerState(state), token));
+}
 
 //#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

@@ -94,5 +94,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, injectAnnotations, isInjectedAnnotationState, mapModeValue, mapSourceMetadata, unwrapInjectedAnnotationState, withAnnotationView, wrapForMode };
+export { ParserSourceMetadata, ParserTraits, SuggestNode, defineTraits, delegateOptionParsing, delegateSuggestNodes, dispatchByMode, extractPhase2SeedKey, getTraits, inheritAnnotations, injectAnnotations, isInjectedAnnotationState, mapModeValue, mapSourceMetadata, unwrapInjectedAnnotationState, withAnnotationView, wrapForMode };

package/dist/extension.d.ts

@@ -94,5 +94,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, injectAnnotations, isInjectedAnnotationState, mapModeValue, mapSourceMetadata, unwrapInjectedAnnotationState, withAnnotationView, wrapForMode };
+export { ParserSourceMetadata, ParserTraits, SuggestNode, defineTraits, delegateOptionParsing, delegateSuggestNodes, dispatchByMode, extractPhase2SeedKey, getTraits, inheritAnnotations, injectAnnotations, isInjectedAnnotationState, mapModeValue, mapSourceMetadata, unwrapInjectedAnnotationState, withAnnotationView, wrapForMode };

package/dist/extension.js

@@ -2,6 +2,7 @@ import { inheritAnnotations, injectAnnotations, isInjectedAnnotationState, unwra
 import { dispatchByMode, mapModeValue, wrapForMode } from "./internal/mode-dispatch.js";
 import { annotationWrapperRequiresSourceBindingKey, composeWrappedSourceMetadata, defineInheritedAnnotationParser, getDelegatingSuggestRuntimeNodes, inheritParentAnnotationsKey, unmatchedNonCliDependencySourceStateMarker } from "./internal/parser.js";
 import { withAnnotationView } from "./annotation-state.js";
+import { defineOptionMatch, definePassThroughPriority, getOptionMatch, getPassThroughPriority } from "./internal/passthrough.js";
 import { extractPhase2SeedKey } from "./phase2-seed.js";
 
 //#region src/extension.ts
@@ -72,6 +73,21 @@ 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) {
+	defineOptionMatch(wrapper, (state, token) => getOptionMatch(inner, getInnerState(state), token));
+	definePassThroughPriority(wrapper, [inner], (state, token) => getPassThroughPriority(inner, getInnerState(state), token));
+}
 
 //#endregion
-export { defineTraits, delegateSuggestNodes, dispatchByMode, extractPhase2SeedKey, getTraits, inheritAnnotations, injectAnnotations, isInjectedAnnotationState, mapModeValue, mapSourceMetadata, unwrapInjectedAnnotationState, withAnnotationView, wrapForMode };
+export { defineTraits, delegateOptionParsing, delegateSuggestNodes, dispatchByMode, extractPhase2SeedKey, getTraits, inheritAnnotations, injectAnnotations, isInjectedAnnotationState, mapModeValue, mapSourceMetadata, unwrapInjectedAnnotationState, withAnnotationView, wrapForMode };

package/dist/internal/passthrough.cjs

@@ -0,0 +1,230 @@
+
+//#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 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;
+}
+/** Retains a child's rejected option failure only at the parent's cursor. @internal */
+function retainConsumingFailureHint(current, context, next) {
+	if (next.buffer !== context.buffer || next.optionsTerminated !== context.optionsTerminated) return current;
+	const hint = getPassThroughFailure(next);
+	return hint == null ? current : retainConsumingFailure(current, hint.failure, hint.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
+	});
+}
+
+//#endregion
+exports.combineOptionMatches = combineOptionMatches;
+exports.combinePassThroughPriorities = combinePassThroughPriorities;
+exports.defineKnownCompletion = defineKnownCompletion;
+exports.defineKnownCompletionLookup = defineKnownCompletionLookup;
+exports.defineOptionMatch = defineOptionMatch;
+exports.definePassThroughPriority = definePassThroughPriority;
+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;

package/dist/internal/passthrough.js

@@ -0,0 +1,213 @@
+//#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 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;
+}
+/** Retains a child's rejected option failure only at the parent's cursor. @internal */
+function retainConsumingFailureHint(current, context, next) {
+	if (next.buffer !== context.buffer || next.optionsTerminated !== context.optionsTerminated) return current;
+	const hint = getPassThroughFailure(next);
+	return hint == null ? current : retainConsumingFailure(current, hint.failure, hint.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
+	});
+}
+
+//#endregion
+export { combineOptionMatches, combinePassThroughPriorities, defineKnownCompletion, defineKnownCompletionLookup, defineOptionMatch, definePassThroughPriority, delegateKnownCompletion, getKnownCompletion, getOptionMatch, getPassThroughFailure, getPassThroughFailureHint, getPassThroughPriority, hasPassThroughUsage, matchesOptionToken, retainConsumingFailure, retainConsumingFailureHint, withPassThroughFailure };