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

package/dist/internal/dependency.js

@@ -885,6 +885,37 @@ function getDefaultValuesFunction(parser) {
 	return void 0;
 }
 /**
+* Creates a deferred parse state for a DerivedValueParser.
+*
+* @template T The type of value the parser will produce.
+* @template S The type of the source dependency value.
+* @param rawInput The raw input string to be parsed.
+* @param parser The DerivedValueParser that will parse the input.
+* @param preliminaryResult The parse result using default dependency value.
+* @returns A DeferredParseState object.
+* @since 0.10.0
+*/
+function createDeferredParseState(rawInput, parser, preliminaryResult) {
+	const multipleIds = dependencyIds in parser ? parser[dependencyIds] : void 0;
+	const defaultValuesFn = getDefaultValuesFunction(parser);
+	let defaultVals = getSnapshottedDefaultDependencyValues(preliminaryResult);
+	if (defaultVals != null) defaultVals = [...defaultVals];
+	if (defaultVals == null && defaultValuesFn != null) try {
+		defaultVals = [...defaultValuesFn()];
+	} catch {
+		defaultVals = void 0;
+	}
+	return {
+		[deferredParseMarker]: true,
+		rawInput,
+		parser,
+		dependencyId: parser[dependencyId],
+		dependencyIds: multipleIds,
+		defaultValues: defaultVals,
+		preliminaryResult
+	};
+}
+/**
 * A unique symbol used to identify dependency source parse states.
 * @since 0.10.0
 */
@@ -931,6 +962,19 @@ function isPendingDependencySourceState(value) {
 	return typeof value === "object" && value !== null && pendingDependencySourceStateMarker in value && value[pendingDependencySourceStateMarker] === true;
 }
 /**
+* Creates a pending dependency source state.
+*
+* @param depId The dependency ID.
+* @returns A PendingDependencySourceState object.
+* @since 0.10.0
+*/
+function createPendingDependencySourceState(depId) {
+	return {
+		[pendingDependencySourceStateMarker]: true,
+		[dependencyId]: depId
+	};
+}
+/**
 * A unique symbol used to identify parsers that wrap a dependency source.
 * This is used by withDefault to indicate it contains an inner parser
 * with a PendingDependencySourceState initialState.
@@ -950,6 +994,16 @@ const wrappedDependencySourceMarker = Symbol.for("@optique/core/dependency/wrapp
 */
 const transformsDependencyValueMarker = Symbol.for("@optique/core/dependency/transformsDependencyValueMarker");
 /**
+* Checks if a parser transforms the dependency value (has transformsDependencyValueMarker).
+*
+* @param parser The parser to check.
+* @returns `true` if the parser transforms the dependency value.
+* @since 0.10.0
+*/
+function transformsDependencyValue(parser) {
+	return typeof parser === "object" && parser !== null && transformsDependencyValueMarker in parser && parser[transformsDependencyValueMarker] === true;
+}
+/**
 * Checks if a parser wraps a dependency source (has wrappedDependencySourceMarker).
 *
 * @param parser The parser to check.
@@ -959,6 +1013,70 @@ const transformsDependencyValueMarker = Symbol.for("@optique/core/dependency/tra
 function isWrappedDependencySource(parser) {
 	return typeof parser === "object" && parser !== null && wrappedDependencySourceMarker in parser;
 }
+/**
+* A registry for storing resolved dependency values during parsing.
+* This is used to pass dependency values from DependencySource options
+* to DerivedValueParser options.
+* @since 0.10.0
+*/
+var DependencyRegistry = class DependencyRegistry {
+	values = /* @__PURE__ */ new Map();
+	/**
+	* Registers a resolved dependency value.
+	* @param id The dependency ID.
+	* @param value The resolved value.
+	*/
+	set(id, value) {
+		this.values.set(id, value);
+	}
+	/**
+	* Gets a resolved dependency value.
+	* @param id The dependency ID.
+	* @returns The resolved value, or undefined if not found.
+	*/
+	get(id) {
+		return this.values.get(id);
+	}
+	/**
+	* Checks if a dependency has been resolved.
+	* @param id The dependency ID.
+	* @returns `true` if the dependency has been resolved.
+	*/
+	has(id) {
+		return this.values.has(id);
+	}
+	/**
+	* Creates a copy of the registry.
+	*/
+	clone() {
+		const copy = new DependencyRegistry();
+		for (const [id, value] of this.values) copy.values.set(id, value);
+		return copy;
+	}
+};
+/**
+* Formats a {@link DependencyError} into a human-readable {@link Message}.
+*
+* @param error The dependency error to format.
+* @returns A Message describing the error.
+* @since 0.10.0
+*/
+function formatDependencyError(error) {
+	switch (error.kind) {
+		case "duplicate": return [{
+			type: "text",
+			text: `Dependency used in multiple locations: ${error.locations.join(", ")}.`
+		}];
+		case "unresolved": return [{
+			type: "text",
+			text: `Unresolved dependency for ${error.derivedParserMetavar}: the dependency was not provided.`
+		}];
+		case "circular": return [{
+			type: "text",
+			text: `Circular dependency detected.`
+		}];
+	}
+}
 
 //#endregion
-export { createDependencySourceState, defaultValues, dependency, dependencyId, dependencyIds, deriveFrom, deriveFromAsync, deriveFromSync, getDefaultValuesFunction, getDependencyIds, getSnapshottedDefaultDependencyValues, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isPendingDependencySourceState, isWrappedDependencySource, parseWithDependency, singleDefaultValue, suggestWithDependency, wrappedDependencySourceMarker };
+export { DependencyRegistry, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultDependencyValueSnapshot, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, formatDependencyError, getDefaultValuesFunction, getDependencyIds, getSnapshottedDefaultDependencyValues, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isPendingDependencySourceState, isWrappedDependencySource, parseWithDependency, pendingDependencySourceStateMarker, singleDefaultValue, snapshotDefaultDependencyValues, suggestWithDependency, transformsDependencyValue, transformsDependencyValueMarker, wrappedDependencySourceMarker };

package/dist/internal/parser.cjs

@@ -1,4 +1,4 @@
-const require_annotations = require('./annotations.cjs');
+const require_internal_annotations = require('./annotations.cjs');
 const require_message = require('../message.cjs');
 const require_usage = require('../usage.cjs');
 const require_doc = require('../doc.cjs');
@@ -64,7 +64,7 @@ function createParserContext(frame, exec) {
 	};
 }
 function injectAnnotationsIntoState(state, options) {
-	return require_annotations.injectAnnotations(state, options?.annotations);
+	return require_internal_annotations.injectAnnotations(state, options?.annotations);
 }
 /**
 * Parses an array of command-line arguments using the provided combined parser.
@@ -92,7 +92,7 @@ function injectAnnotationsIntoState(state, options) {
 */
 function parseSync(parser, args, options) {
 	const initialState = injectAnnotationsIntoState(parser.initialState, options);
-	const shouldUnwrapAnnotatedValue = require_annotations.hasMeaningfulAnnotations(options?.annotations) || require_annotations.isInjectedAnnotationWrapper(parser.initialState);
+	const shouldUnwrapAnnotatedValue = require_internal_annotations.hasMeaningfulAnnotations(options?.annotations) || require_internal_annotations.isInjectedAnnotationWrapper(parser.initialState);
 	const exec = {
 		usage: parser.usage,
 		phase: "parse",
@@ -123,12 +123,13 @@ function parseSync(parser, args, options) {
 		phase: "complete",
 		dependencyRuntime: runtime,
 		dependencyRegistry: runtime.registry,
+		commandPath: context.exec?.commandPath ?? exec.commandPath,
 		trace: context.exec?.trace ?? context.trace ?? exec.trace
 	};
 	const endResult = parser.complete(context.state, completeExec);
 	return endResult.success ? {
 		success: true,
-		value: shouldUnwrapAnnotatedValue ? require_annotations.unwrapInjectedAnnotationWrapper(endResult.value) : endResult.value,
+		value: shouldUnwrapAnnotatedValue ? require_internal_annotations.unwrapInjectedAnnotationWrapper(endResult.value) : endResult.value,
 		...endResult.deferred ? { deferred: true } : {},
 		...endResult.deferredKeys ? { deferredKeys: endResult.deferredKeys } : {}
 	} : {
@@ -164,7 +165,7 @@ function isBufferUnchanged(previous, current) {
 */
 async function parseAsync(parser, args, options) {
 	const initialState = injectAnnotationsIntoState(parser.initialState, options);
-	const shouldUnwrapAnnotatedValue = require_annotations.hasMeaningfulAnnotations(options?.annotations) || require_annotations.isInjectedAnnotationWrapper(parser.initialState);
+	const shouldUnwrapAnnotatedValue = require_internal_annotations.hasMeaningfulAnnotations(options?.annotations) || require_internal_annotations.isInjectedAnnotationWrapper(parser.initialState);
 	const exec = {
 		usage: parser.usage,
 		phase: "parse",
@@ -195,12 +196,13 @@ async function parseAsync(parser, args, options) {
 		phase: "complete",
 		dependencyRuntime: runtime,
 		dependencyRegistry: runtime.registry,
+		commandPath: context.exec?.commandPath ?? exec.commandPath,
 		trace: context.exec?.trace ?? context.trace ?? exec.trace
 	};
 	const endResult = await parser.complete(context.state, completeExec);
 	return endResult.success ? {
 		success: true,
-		value: shouldUnwrapAnnotatedValue ? require_annotations.unwrapInjectedAnnotationWrapper(endResult.value) : endResult.value,
+		value: shouldUnwrapAnnotatedValue ? require_internal_annotations.unwrapInjectedAnnotationWrapper(endResult.value) : endResult.value,
 		...endResult.deferred ? { deferred: true } : {},
 		...endResult.deferredKeys ? { deferredKeys: endResult.deferredKeys } : {}
 	} : {
@@ -501,14 +503,83 @@ function findCommandInExclusive(term, commandName) {
 	if (term.type !== "exclusive") return null;
 	for (const termGroup of term.terms) {
 		const firstTerm = termGroup[0];
-		if (firstTerm?.type === "command" && firstTerm.name === commandName) return termGroup;
-		if (firstTerm?.type === "exclusive") {
-			const found = findCommandInExclusive(firstTerm, commandName);
-			if (found) return [...found, ...termGroup.slice(1)];
-		}
+		if (firstTerm == null) continue;
+		const found = findCommandInCurrentUsageTerm(firstTerm, commandName, termGroup.slice(1));
+		if (found) return found;
+	}
+	return null;
+}
+/**
+* Searches for a command inside an ordered usage sequence and returns the
+* usage from the matched command onward.  This lets contextual command
+* documentation enter sequence terms while dropping sequence prefixes that
+* were skipped by parsing, such as optional positionals before a subcommand.
+*
+* @param usage The usage terms to search.
+* @param commandName The command name to find.
+* @returns The contextual usage terms if found, null otherwise.
+*/
+function findCommandInUsageSequence(usage, commandName) {
+	for (let index = 0; index < usage.length; index++) {
+		const found = findCommandInCurrentUsageTerm(usage[index], commandName, usage.slice(index + 1));
+		if (found) return found;
+	}
+	return null;
+}
+/**
+* Searches the current usage term for a command and appends the trailing
+* usage terms that remain valid after that current term.
+*
+* @param term The current usage term to search.
+* @param commandName The command name to find.
+* @param trailingUsage Usage terms that follow the current term.
+* @returns The contextual usage terms if found, null otherwise.
+*/
+function findCommandInCurrentUsageTerm(term, commandName, trailingUsage) {
+	if (term.type === "command" && commandTermMatches(term, commandName)) return [term, ...trailingUsage];
+	if (term.type === "exclusive") {
+		const found = findCommandInExclusive(term, commandName);
+		if (found) return [...found, ...trailingUsage];
+	} else if (term.type === "sequence") {
+		const found = findCommandInUsageSequence(term.terms, commandName);
+		if (found) return [...found, ...trailingUsage];
 	}
 	return null;
 }
+function commandTermMatches(term, commandName) {
+	return term?.type === "command" && (term.name === commandName || term.aliases?.includes(commandName) === true || term.hiddenAliases?.includes(commandName) === true);
+}
+function collectCommandInputNames(usage, commandName, names) {
+	for (const term of usage) if (term.type === "command") {
+		if (commandTermMatches(term, commandName)) {
+			names.add(term.name);
+			for (const alias of term.aliases ?? []) names.add(alias);
+			for (const alias of term.hiddenAliases ?? []) names.add(alias);
+		}
+	} else if (term.type === "exclusive") for (const branch of term.terms) collectCommandInputNames(branch, commandName, names);
+	else if (term.type === "sequence") collectCommandInputNames(term.terms, commandName, names);
+	else if (term.type === "optional" || term.type === "multiple") collectCommandInputNames(term.terms, commandName, names);
+}
+function findLastCommandInputIndex(consumed, commandName, usage, searchEnd) {
+	const names = new Set([commandName]);
+	collectCommandInputNames(usage, commandName, names);
+	for (let index = searchEnd - 1; index >= 0; index--) if (names.has(consumed[index])) return index;
+	return -1;
+}
+function recordMatchedCommandArgIndices(usage, consumed, previousCommandPath, nextCommandPath, consumedOffset, indices) {
+	const previousLength = previousCommandPath?.length ?? 0;
+	const next = nextCommandPath ?? [];
+	if (next.length <= previousLength || consumed.length < 1) return;
+	let searchEnd = consumed.length;
+	for (let index = next.length - 1; index >= previousLength; index--) {
+		if (searchEnd <= 0) break;
+		const commandName = next[index];
+		const localIndex = findLastCommandInputIndex(consumed, commandName, usage, searchEnd);
+		if (localIndex < 0) continue;
+		indices.add(consumedOffset + localIndex);
+		searchEnd = localIndex;
+	}
+}
 /**
 * Generates a documentation page for a synchronous parser.
 *
@@ -579,14 +650,18 @@ function getDocPageSyncImpl(parser, args, options) {
 		state: initialState,
 		optionsTerminated: false
 	}, exec);
+	const matchedCommandArgIndices = /* @__PURE__ */ new Set();
 	while (context.buffer.length > 0) {
 		const result = parser.parse(context);
 		if (!result.success) break;
+		const previousCommandPath = context.exec?.commandPath;
 		const previousBuffer = context.buffer;
 		context = result.next;
+		const consumedCount = previousBuffer.length - context.buffer.length;
+		recordMatchedCommandArgIndices(parser.usage, previousBuffer.slice(0, consumedCount), previousCommandPath, context.exec?.commandPath, args.length - previousBuffer.length, matchedCommandArgIndices);
 		if (isBufferUnchanged(previousBuffer, context.buffer)) break;
 	}
-	return buildDocPage(parser, context, args);
+	return buildDocPage(parser, context, args, matchedCommandArgIndices);
 }
 /**
 * Internal async implementation of getDocPage.
@@ -604,20 +679,24 @@ async function getDocPageAsyncImpl(parser, args, options) {
 		state: initialState,
 		optionsTerminated: false
 	}, exec);
+	const matchedCommandArgIndices = /* @__PURE__ */ new Set();
 	while (context.buffer.length > 0) {
 		const result = await parser.parse(context);
 		if (!result.success) break;
+		const previousCommandPath = context.exec?.commandPath;
 		const previousBuffer = context.buffer;
 		context = result.next;
+		const consumedCount = previousBuffer.length - context.buffer.length;
+		recordMatchedCommandArgIndices(parser.usage, previousBuffer.slice(0, consumedCount), previousCommandPath, context.exec?.commandPath, args.length - previousBuffer.length, matchedCommandArgIndices);
 		if (isBufferUnchanged(previousBuffer, context.buffer)) break;
 	}
-	return buildDocPage(parser, context, args);
+	return buildDocPage(parser, context, args, matchedCommandArgIndices);
 }
 /**
 * Builds a DocPage from the parser and context.
 * Shared by both sync and async implementations.
 */
-function buildDocPage(parser, context, args) {
+function buildDocPage(parser, context, args, matchedCommandArgIndices) {
 	let effectiveArgs = args;
 	let { brief, description, fragments, footer } = parser.getDocFragments({
 		kind: "available",
@@ -625,7 +704,7 @@ function buildDocPage(parser, context, args) {
 	}, void 0);
 	if (args.length === 0 && Reflect.get(parser, Symbol.for("@optique/core/commandParser")) === true && fragments.length === 1 && fragments[0].type === "entry" && fragments[0].term.type === "command") {
 		const cmdName = fragments[0].term.name;
-		const matchedState = require_annotations.inheritAnnotations(context.state, ["matched", cmdName]);
+		const matchedState = require_internal_annotations.inheritAnnotations(context.state, ["matched", cmdName]);
 		const matched = parser.getDocFragments({
 			kind: "available",
 			state: matchedState
@@ -668,26 +747,32 @@ function buildDocPage(parser, context, args) {
 	const sections = buildingSections;
 	const usage = [...require_usage.normalizeUsage(parser.usage)];
 	const maybeApplyCommandUsageLine = (term, arg, isLastArg, usageIndex) => {
-		if (term?.type !== "command" || term.name !== arg || !isLastArg || term.usageLine == null) return;
+		if (term?.type !== "command" || !commandTermMatches(term, arg) || !isLastArg || term.usageLine == null) return;
 		const defaultUsageLine = require_usage.cloneUsage(usage.slice(usageIndex + 1));
 		const customUsageLine = typeof term.usageLine === "function" ? term.usageLine(defaultUsageLine) : term.usageLine;
 		const normalizedCustomUsageLine = require_usage.normalizeUsage(customUsageLine);
 		usage.splice(usageIndex + 1, usage.length - (usageIndex + 1), ...normalizedCustomUsageLine);
 	};
 	let i = 0;
+	const consumedArgsCount = Math.max(0, effectiveArgs.length - context.buffer.length);
+	const commandArgIndices = args.length > 0 ? matchedCommandArgIndices : null;
 	for (let argIndex = 0; argIndex < effectiveArgs.length; argIndex++) {
 		const arg = effectiveArgs[argIndex];
 		if (i >= usage.length) break;
 		let term = usage[i];
-		if (term.type === "exclusive") {
-			const found = findCommandInExclusive(term, arg);
-			if (found) {
-				usage.splice(i, 1, ...found);
-				term = usage[i];
-			}
+		const canSearchCommand = commandArgIndices == null || commandArgIndices.has(argIndex);
+		if (!canSearchCommand) continue;
+		let found = null;
+		for (let searchIndex = i; searchIndex < usage.length; searchIndex++) {
+			found = findCommandInCurrentUsageTerm(usage[searchIndex], arg, usage.slice(searchIndex + 1));
+			if (found != null) break;
+		}
+		if (found) {
+			usage.splice(i, usage.length - i, ...found);
+			term = usage[i];
 		}
 		maybeApplyCommandUsageLine(term, arg, argIndex === effectiveArgs.length - 1, i);
-		i++;
+		if (found != null || term.type !== "sequence" || argIndex >= consumedArgsCount) i++;
 	}
 	if (effectiveArgs.length === 0 && usage.length > 0) {
 		const first = usage[0];

package/dist/internal/parser.d.cts

@@ -143,6 +143,20 @@ interface Parser<M extends Mode = "sync", TValue = unknown, TState = unknown> {
    * @since 1.0.0
    */
   readonly acceptingAnyToken: boolean;
+  /**
+   * Returns whether this parser can be skipped at the current state without
+   * consuming more CLI input or evaluating completion-time defaults.
+   *
+   * Sequential combinators use this as a lightweight boundary predicate.  It
+   * must be synchronous and side-effect free.  Custom parsers that omit this
+   * method are treated as not skippable.
+   *
+   * @param state The current parser state.
+   * @param exec Optional shared execution context.
+   * @returns `true` when parsing may advance past this parser.
+   * @since 1.1.0
+   */
+  canSkip?(state: TState, exec?: ExecutionContext): boolean;
   /**
    * The initial state for this parser.  This is used to initialize the
    * state when parsing starts.
@@ -461,7 +475,15 @@ declare const unmatchedNonCliDependencySourceStateMarker: unique symbol;
  *
  * @internal
  */
-
+declare const inheritParentAnnotationsKey: unique symbol;
+/**
+ * Internal marker for wrapper parsers that should only treat annotation-only
+ * primitive wrapper states as completable when a nested source-binding wrapper
+ * produced them.
+ *
+ * @internal
+ */
+declare const annotationWrapperRequiresSourceBindingKey: unique symbol;
 /**
  * The context of the parser, which includes the input buffer and the state.
  *
@@ -809,7 +831,40 @@ declare function suggestSync<T>(parser: Parser<"sync", T, unknown>, args: readon
  * @returns The runtime nodes used to seed suggest-time dependency resolution.
  * @internal
  */
-
+declare function getParserSuggestRuntimeNodes<TState>(parser: Parser<Mode, unknown, TState>, state: TState, path: readonly PropertyKey[]): readonly RuntimeNode[];
+/**
+ * Returns wrapper-aware suggest-time runtime nodes for parsers that delegate
+ * to an inner parser while also exposing their own source metadata.
+ *
+ * The inner parser's nodes are always preserved so nested wrappers and
+ * constructs can continue to seed the dependency runtime recursively. When
+ * the outer parser itself owns source metadata, its `(path, parser, state)`
+ * node is appended so outer precedence rules still apply.
+ *
+ * @internal
+ */
+declare function getDelegatingSuggestRuntimeNodes<TInnerState>(innerParser: Parser<Mode, unknown, TInnerState>, outerParser: Parser<Mode, unknown, unknown>, state: unknown, path: readonly PropertyKey[], innerState: TInnerState, outerPosition?: "append" | "prepend"): readonly RuntimeNode[];
+/**
+ * Composes source metadata for a wrapper parser while preserving any derived
+ * or transform capabilities from the inner parser unchanged.
+ *
+ * @internal
+ */
+declare function composeWrappedSourceMetadata(dependencyMetadata: ParserDependencyMetadata | undefined, wrapSource: (source: NonNullable<ParserDependencyMetadata["source"]>) => NonNullable<ParserDependencyMetadata["source"]>): ParserDependencyMetadata | undefined;
+/**
+ * Marks a parser as inheriting parent-state annotations through wrapper-state
+ * reconstruction.
+ *
+ * @internal
+ */
+declare function defineInheritedAnnotationParser(parser: object): void;
+/**
+ * Marks a wrapper parser as requiring a real source-binding state before
+ * annotation-only primitive wrappers should trigger completion.
+ *
+ * @internal
+ */
+declare function defineSourceBindingOnlyAnnotationCompletionParser(parser: object): void;
 /**
  * Generates command-line suggestions based on current parsing state.
  * This function processes the input arguments up to the last argument,
@@ -944,4 +999,4 @@ declare function getDocPage(parser: Parser<"sync", unknown, unknown>, argsOrOpti
 declare function getDocPage(parser: Parser<"async", unknown, unknown>, argsOrOptions?: readonly string[] | ParseOptions, options?: ParseOptions): Promise<DocPage | undefined>;
 declare function getDocPage<M extends Mode>(parser: Parser<M, unknown, unknown>, argsOrOptions?: readonly string[] | ParseOptions, options?: ParseOptions): ModeValue<M, DocPage | undefined>;
 //#endregion
-export { CombineModes, DocState, ExecutionContext, ExecutionPhase, InferMode, InferValue, Mode, ModeIterable, ModeValue, ParseFrame, Parser, ParserContext, ParserResult, Result, Suggestion, createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync };
+export { CombineModes, DocState, ExecutionContext, ExecutionPhase, InferMode, InferValue, Mode, ModeIterable, ModeValue, ParseFrame, type ParseOptions, Parser, ParserContext, ParserResult, Result, Suggestion, annotationWrapperRequiresSourceBindingKey, composeWrappedSourceMetadata, createParserContext, defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, getDelegatingSuggestRuntimeNodes, getDocPage, getDocPageAsync, getDocPageSync, getParserSuggestRuntimeNodes, inheritParentAnnotationsKey, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync, unmatchedNonCliDependencySourceStateMarker };

package/dist/internal/parser.d.ts

@@ -143,6 +143,20 @@ interface Parser<M extends Mode = "sync", TValue = unknown, TState = unknown> {
    * @since 1.0.0
    */
   readonly acceptingAnyToken: boolean;
+  /**
+   * Returns whether this parser can be skipped at the current state without
+   * consuming more CLI input or evaluating completion-time defaults.
+   *
+   * Sequential combinators use this as a lightweight boundary predicate.  It
+   * must be synchronous and side-effect free.  Custom parsers that omit this
+   * method are treated as not skippable.
+   *
+   * @param state The current parser state.
+   * @param exec Optional shared execution context.
+   * @returns `true` when parsing may advance past this parser.
+   * @since 1.1.0
+   */
+  canSkip?(state: TState, exec?: ExecutionContext): boolean;
   /**
    * The initial state for this parser.  This is used to initialize the
    * state when parsing starts.
@@ -461,7 +475,15 @@ declare const unmatchedNonCliDependencySourceStateMarker: unique symbol;
  *
  * @internal
  */
-
+declare const inheritParentAnnotationsKey: unique symbol;
+/**
+ * Internal marker for wrapper parsers that should only treat annotation-only
+ * primitive wrapper states as completable when a nested source-binding wrapper
+ * produced them.
+ *
+ * @internal
+ */
+declare const annotationWrapperRequiresSourceBindingKey: unique symbol;
 /**
  * The context of the parser, which includes the input buffer and the state.
  *
@@ -809,7 +831,40 @@ declare function suggestSync<T>(parser: Parser<"sync", T, unknown>, args: readon
  * @returns The runtime nodes used to seed suggest-time dependency resolution.
  * @internal
  */
-
+declare function getParserSuggestRuntimeNodes<TState>(parser: Parser<Mode, unknown, TState>, state: TState, path: readonly PropertyKey[]): readonly RuntimeNode[];
+/**
+ * Returns wrapper-aware suggest-time runtime nodes for parsers that delegate
+ * to an inner parser while also exposing their own source metadata.
+ *
+ * The inner parser's nodes are always preserved so nested wrappers and
+ * constructs can continue to seed the dependency runtime recursively. When
+ * the outer parser itself owns source metadata, its `(path, parser, state)`
+ * node is appended so outer precedence rules still apply.
+ *
+ * @internal
+ */
+declare function getDelegatingSuggestRuntimeNodes<TInnerState>(innerParser: Parser<Mode, unknown, TInnerState>, outerParser: Parser<Mode, unknown, unknown>, state: unknown, path: readonly PropertyKey[], innerState: TInnerState, outerPosition?: "append" | "prepend"): readonly RuntimeNode[];
+/**
+ * Composes source metadata for a wrapper parser while preserving any derived
+ * or transform capabilities from the inner parser unchanged.
+ *
+ * @internal
+ */
+declare function composeWrappedSourceMetadata(dependencyMetadata: ParserDependencyMetadata | undefined, wrapSource: (source: NonNullable<ParserDependencyMetadata["source"]>) => NonNullable<ParserDependencyMetadata["source"]>): ParserDependencyMetadata | undefined;
+/**
+ * Marks a parser as inheriting parent-state annotations through wrapper-state
+ * reconstruction.
+ *
+ * @internal
+ */
+declare function defineInheritedAnnotationParser(parser: object): void;
+/**
+ * Marks a wrapper parser as requiring a real source-binding state before
+ * annotation-only primitive wrappers should trigger completion.
+ *
+ * @internal
+ */
+declare function defineSourceBindingOnlyAnnotationCompletionParser(parser: object): void;
 /**
  * Generates command-line suggestions based on current parsing state.
  * This function processes the input arguments up to the last argument,
@@ -944,4 +999,4 @@ declare function getDocPage(parser: Parser<"sync", unknown, unknown>, argsOrOpti
 declare function getDocPage(parser: Parser<"async", unknown, unknown>, argsOrOptions?: readonly string[] | ParseOptions, options?: ParseOptions): Promise<DocPage | undefined>;
 declare function getDocPage<M extends Mode>(parser: Parser<M, unknown, unknown>, argsOrOptions?: readonly string[] | ParseOptions, options?: ParseOptions): ModeValue<M, DocPage | undefined>;
 //#endregion
-export { CombineModes, DocState, ExecutionContext, ExecutionPhase, InferMode, InferValue, Mode, ModeIterable, ModeValue, ParseFrame, Parser, ParserContext, ParserResult, Result, Suggestion, createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync };
+export { CombineModes, DocState, ExecutionContext, ExecutionPhase, InferMode, InferValue, Mode, ModeIterable, ModeValue, ParseFrame, type ParseOptions, Parser, ParserContext, ParserResult, Result, Suggestion, annotationWrapperRequiresSourceBindingKey, composeWrappedSourceMetadata, createParserContext, defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, getDelegatingSuggestRuntimeNodes, getDocPage, getDocPageAsync, getDocPageSync, getParserSuggestRuntimeNodes, inheritParentAnnotationsKey, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync, unmatchedNonCliDependencySourceStateMarker };