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

package/dist/internal/parser.d.ts

@@ -475,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.
  *
@@ -823,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,
@@ -958,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.js

@@ -123,6 +123,7 @@ 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);
@@ -195,6 +196,7 @@ 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);
@@ -534,7 +536,7 @@ function findCommandInUsageSequence(usage, commandName) {
 * @returns The contextual usage terms if found, null otherwise.
 */
 function findCommandInCurrentUsageTerm(term, commandName, trailingUsage) {
-	if (term.type === "command" && term.name === commandName) return [term, ...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];
@@ -544,7 +546,27 @@ function findCommandInCurrentUsageTerm(term, commandName, trailingUsage) {
 	}
 	return null;
 }
-function recordMatchedCommandArgIndices(consumed, previousCommandPath, nextCommandPath, consumedOffset, indices) {
+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;
@@ -552,7 +574,7 @@ function recordMatchedCommandArgIndices(consumed, previousCommandPath, nextComma
 	for (let index = next.length - 1; index >= previousLength; index--) {
 		if (searchEnd <= 0) break;
 		const commandName = next[index];
-		const localIndex = consumed.lastIndexOf(commandName, searchEnd - 1);
+		const localIndex = findLastCommandInputIndex(consumed, commandName, usage, searchEnd);
 		if (localIndex < 0) continue;
 		indices.add(consumedOffset + localIndex);
 		searchEnd = localIndex;
@@ -636,7 +658,7 @@ function getDocPageSyncImpl(parser, args, options) {
 		const previousBuffer = context.buffer;
 		context = result.next;
 		const consumedCount = previousBuffer.length - context.buffer.length;
-		recordMatchedCommandArgIndices(previousBuffer.slice(0, consumedCount), previousCommandPath, context.exec?.commandPath, args.length - previousBuffer.length, matchedCommandArgIndices);
+		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, matchedCommandArgIndices);
@@ -665,7 +687,7 @@ async function getDocPageAsyncImpl(parser, args, options) {
 		const previousBuffer = context.buffer;
 		context = result.next;
 		const consumedCount = previousBuffer.length - context.buffer.length;
-		recordMatchedCommandArgIndices(previousBuffer.slice(0, consumedCount), previousCommandPath, context.exec?.commandPath, args.length - previousBuffer.length, matchedCommandArgIndices);
+		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, matchedCommandArgIndices);
@@ -725,7 +747,7 @@ function buildDocPage(parser, context, args, matchedCommandArgIndices) {
 	const sections = buildingSections;
 	const 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 = cloneUsage(usage.slice(usageIndex + 1));
 		const customUsageLine = typeof term.usageLine === "function" ? term.usageLine(defaultUsageLine) : term.usageLine;
 		const normalizedCustomUsageLine = normalizeUsage(customUsageLine);

package/dist/modifiers.cjs

@@ -1,7 +1,7 @@
-const require_annotations = require('./internal/annotations.cjs');
+const require_internal_annotations = require('./internal/annotations.cjs');
 const require_message = require('./message.cjs');
 const require_mode_dispatch = require('./internal/mode-dispatch.cjs');
-const require_parser = require('./internal/parser.cjs');
+const require_internal_parser = require('./internal/parser.cjs');
 const require_annotation_state = require('./annotation-state.cjs');
 const require_execution_context = require('./execution-context.cjs');
 const require_phase2_seed = require('./phase2-seed.cjs');
@@ -31,8 +31,8 @@ function unwrapMultipleItemState(state) {
 	let unwrapped = state;
 	let viaBoundCliWrapper = false;
 	while (true) {
-		if (require_annotations.isInjectedAnnotationWrapper(unwrapped)) {
-			unwrapped = require_annotations.unwrapInjectedAnnotationWrapper(unwrapped);
+		if (require_internal_annotations.isInjectedAnnotationWrapper(unwrapped)) {
+			unwrapped = require_internal_annotations.unwrapInjectedAnnotationWrapper(unwrapped);
 			continue;
 		}
 		if (Array.isArray(unwrapped) && unwrapped.length === 1) {
@@ -60,7 +60,7 @@ function normalizeOptionalLikeCompleteResult(result, shouldNormalize) {
 	} : result;
 }
 function shouldRetryOptionalLikeCompatibilityError(error, state) {
-	return error instanceof TypeError && state != null && typeof state === "object" && require_annotations.isInjectedAnnotationWrapper(state);
+	return error instanceof TypeError && state != null && typeof state === "object" && require_internal_annotations.isInjectedAnnotationWrapper(state);
 }
 function completeOptionalLikeSync(parser, state, exec) {
 	const hasCarrier = require_annotation_state.hasDelegatedAnnotationCarrier(state);
@@ -161,12 +161,12 @@ function extractOptionalLikePhase2Seed(parser, state, exec) {
 function deriveOptionalInnerParseState(outerState, parser) {
 	if (Array.isArray(outerState)) {
 		const innerState = outerState[0];
-		if (require_annotations.getAnnotations(outerState) != null && innerState != null && typeof innerState === "object") return require_annotation_state.getDelegatedAnnotationState(outerState, innerState);
+		if (require_internal_annotations.getAnnotations(outerState) != null && innerState != null && typeof innerState === "object") return require_annotation_state.getDelegatedAnnotationState(outerState, innerState);
 		return innerState;
 	}
 	const initial = parser.initialState;
 	if (initial != null && typeof initial !== "object") return initial;
-	return initial != null && typeof initial === "object" ? require_annotation_state.getDelegatedAnnotationState(outerState, initial) : require_annotations.inheritAnnotations(outerState, initial);
+	return initial != null && typeof initial === "object" ? require_annotation_state.getDelegatedAnnotationState(outerState, initial) : require_internal_annotations.inheritAnnotations(outerState, initial);
 }
 /**
 * Internal helper for optional-style parsing logic shared by optional()
@@ -262,9 +262,9 @@ function adaptShouldDeferCompletion(innerCheck, parser) {
 	};
 }
 function isAnnotationOnlyObjectState(state) {
-	if (state == null || typeof state !== "object" || Array.isArray(state) || require_annotations.isInjectedAnnotationWrapper(state)) return false;
+	if (state == null || typeof state !== "object" || Array.isArray(state) || require_internal_annotations.isInjectedAnnotationWrapper(state)) return false;
 	const keys = Reflect.ownKeys(state);
-	return require_annotations.getAnnotations(state) != null && keys.length === 1 && keys[0] === require_annotations.annotationKey;
+	return require_internal_annotations.getAnnotations(state) != null && keys.length === 1 && keys[0] === require_internal_annotations.annotationKey;
 }
 function normalizeOptionalLikeInnerState(state, initialState, parser) {
 	if (Array.isArray(state)) return require_annotation_state.getDelegatedAnnotationState(state, state[0]);
@@ -315,7 +315,7 @@ function optional(parser) {
 		mode: parser.mode,
 		$valueType: [],
 		$stateType: [],
-		...parser[require_parser.unmatchedNonCliDependencySourceStateMarker] === true ? { [require_parser.unmatchedNonCliDependencySourceStateMarker]: true } : {},
+		...parser[require_internal_parser.unmatchedNonCliDependencySourceStateMarker] === true ? { [require_internal_parser.unmatchedNonCliDependencySourceStateMarker]: true } : {},
 		placeholder: void 0,
 		priority: parser.priority,
 		usage: [{
@@ -368,7 +368,7 @@ function optional(parser) {
 					const delegatedState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
 					return require_mode_dispatch.dispatchByMode(parser.mode, () => completeOptionalLikeSync(syncParser, delegatedState, exec), async () => await completeOptionalLikeAsync(parser, delegatedState, exec));
 				}
-				if (parser[require_parser.unmatchedNonCliDependencySourceStateMarker] === true && state != null && typeof state === "object") {
+				if (parser[require_internal_parser.unmatchedNonCliDependencySourceStateMarker] === true && state != null && typeof state === "object") {
 					const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
 					return delegateToInner(innerState);
 				}
@@ -420,8 +420,8 @@ function optional(parser) {
 		const composed = require_dependency_metadata.composeDependencyMetadata(parser.dependencyMetadata, "optional");
 		if (composed != null) optionalParser.dependencyMetadata = composed;
 	}
-	require_parser.defineInheritedAnnotationParser(optionalParser);
-	require_parser.defineSourceBindingOnlyAnnotationCompletionParser(optionalParser);
+	require_internal_parser.defineInheritedAnnotationParser(optionalParser);
+	require_internal_parser.defineSourceBindingOnlyAnnotationCompletionParser(optionalParser);
 	return optionalParser;
 }
 /**
@@ -489,7 +489,7 @@ function withDefault(parser, defaultValue, options) {
 		mode: parser.mode,
 		$valueType: [],
 		$stateType: [],
-		...parser[require_parser.unmatchedNonCliDependencySourceStateMarker] === true ? { [require_parser.unmatchedNonCliDependencySourceStateMarker]: true } : {},
+		...parser[require_internal_parser.unmatchedNonCliDependencySourceStateMarker] === true ? { [require_internal_parser.unmatchedNonCliDependencySourceStateMarker]: true } : {},
 		priority: parser.priority,
 		usage: [{
 			type: "optional",
@@ -537,7 +537,7 @@ function withDefault(parser, defaultValue, options) {
 					const innerResult = require_mode_dispatch.dispatchByMode(parser.mode, () => completeOptionalLikeSync(syncParser, innerState, exec), async () => await completeOptionalLikeAsync(parser, innerState, exec));
 					return innerResult;
 				}
-				if (parser[require_parser.unmatchedNonCliDependencySourceStateMarker] === true && state != null && typeof state === "object") {
+				if (parser[require_internal_parser.unmatchedNonCliDependencySourceStateMarker] === true && state != null && typeof state === "object") {
 					const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
 					const innerResult = require_mode_dispatch.dispatchByMode(parser.mode, () => completeOptionalLikeSync(syncParser, innerState, exec), async () => await completeOptionalLikeAsync(parser, innerState, exec));
 					const handleInnerResult = (result) => {
@@ -654,8 +654,8 @@ function withDefault(parser, defaultValue, options) {
 		} });
 		if (composed != null) withDefaultParser.dependencyMetadata = composed;
 	}
-	require_parser.defineInheritedAnnotationParser(withDefaultParser);
-	require_parser.defineSourceBindingOnlyAnnotationCompletionParser(withDefaultParser);
+	require_internal_parser.defineInheritedAnnotationParser(withDefaultParser);
+	require_internal_parser.defineSourceBindingOnlyAnnotationCompletionParser(withDefaultParser);
 	return withDefaultParser;
 }
 /**
@@ -863,27 +863,27 @@ function map(parser, transform) {
 function multiple(parser, options = {}) {
 	const syncParser = parser;
 	const { min = 0, max = Infinity } = options;
-	const unwrapInjectedWrapper = require_annotations.unwrapInjectedAnnotationWrapper;
+	const unwrapInjectedWrapper = require_internal_annotations.unwrapInjectedAnnotationWrapper;
 	const completeSyncWithUnwrappedFallback = (state, exec) => {
 		try {
 			const result = syncParser.complete(state, exec);
-			if (!result.success && require_annotations.isInjectedAnnotationWrapper(state)) return syncParser.complete(unwrapInjectedWrapper(state), exec);
+			if (!result.success && require_internal_annotations.isInjectedAnnotationWrapper(state)) return syncParser.complete(unwrapInjectedWrapper(state), exec);
 			return result;
 		} catch (error) {
-			if (!require_annotations.isInjectedAnnotationWrapper(state)) throw error;
+			if (!require_internal_annotations.isInjectedAnnotationWrapper(state)) throw error;
 			return syncParser.complete(unwrapInjectedWrapper(state), exec);
 		}
 	};
 	const parseSyncWithUnwrappedFallback = (context) => {
 		try {
 			const result = syncParser.parse(context);
-			if (result.success || result.consumed !== 0 || !require_annotations.isInjectedAnnotationWrapper(context.state)) return result;
+			if (result.success || result.consumed !== 0 || !require_internal_annotations.isInjectedAnnotationWrapper(context.state)) return result;
 			return syncParser.parse({
 				...context,
 				state: unwrapInjectedWrapper(context.state)
 			});
 		} catch (error) {
-			if (!require_annotations.isInjectedAnnotationWrapper(context.state)) throw error;
+			if (!require_internal_annotations.isInjectedAnnotationWrapper(context.state)) throw error;
 			return syncParser.parse({
 				...context,
 				state: unwrapInjectedWrapper(context.state)
@@ -893,23 +893,23 @@ function multiple(parser, options = {}) {
 	const completeAsyncWithUnwrappedFallback = async (state, exec) => {
 		try {
 			const result = await parser.complete(state, exec);
-			if (!result.success && require_annotations.isInjectedAnnotationWrapper(state)) return await parser.complete(unwrapInjectedWrapper(state), exec);
+			if (!result.success && require_internal_annotations.isInjectedAnnotationWrapper(state)) return await parser.complete(unwrapInjectedWrapper(state), exec);
 			return result;
 		} catch (error) {
-			if (!require_annotations.isInjectedAnnotationWrapper(state)) throw error;
+			if (!require_internal_annotations.isInjectedAnnotationWrapper(state)) throw error;
 			return await parser.complete(unwrapInjectedWrapper(state), exec);
 		}
 	};
 	const parseAsyncWithUnwrappedFallback = async (context) => {
 		try {
 			const result = await parser.parse(context);
-			if (result.success || result.consumed !== 0 || !require_annotations.isInjectedAnnotationWrapper(context.state)) return result;
+			if (result.success || result.consumed !== 0 || !require_internal_annotations.isInjectedAnnotationWrapper(context.state)) return result;
 			return await parser.parse({
 				...context,
 				state: unwrapInjectedWrapper(context.state)
 			});
 		} catch (error) {
-			if (!require_annotations.isInjectedAnnotationWrapper(context.state)) throw error;
+			if (!require_internal_annotations.isInjectedAnnotationWrapper(context.state)) throw error;
 			return await parser.parse({
 				...context,
 				state: unwrapInjectedWrapper(context.state)
@@ -919,20 +919,20 @@ function multiple(parser, options = {}) {
 	const extractPhase2SeedSyncWithUnwrappedFallback = (state, exec) => {
 		try {
 			const seed = require_phase2_seed.completeOrExtractPhase2Seed(syncParser, state, exec);
-			if (seed == null && require_annotations.isInjectedAnnotationWrapper(state)) return require_phase2_seed.completeOrExtractPhase2Seed(syncParser, unwrapInjectedWrapper(state), exec);
+			if (seed == null && require_internal_annotations.isInjectedAnnotationWrapper(state)) return require_phase2_seed.completeOrExtractPhase2Seed(syncParser, unwrapInjectedWrapper(state), exec);
 			return seed;
 		} catch (error) {
-			if (!require_annotations.isInjectedAnnotationWrapper(state)) throw error;
+			if (!require_internal_annotations.isInjectedAnnotationWrapper(state)) throw error;
 			return require_phase2_seed.completeOrExtractPhase2Seed(syncParser, unwrapInjectedWrapper(state), exec);
 		}
 	};
 	const extractPhase2SeedAsyncWithUnwrappedFallback = async (state, exec) => {
 		try {
 			const seed = await require_phase2_seed.completeOrExtractPhase2Seed(parser, state, exec);
-			if (seed == null && require_annotations.isInjectedAnnotationWrapper(state)) return await require_phase2_seed.completeOrExtractPhase2Seed(parser, unwrapInjectedWrapper(state), exec);
+			if (seed == null && require_internal_annotations.isInjectedAnnotationWrapper(state)) return await require_phase2_seed.completeOrExtractPhase2Seed(parser, unwrapInjectedWrapper(state), exec);
 			return seed;
 		} catch (error) {
-			if (!require_annotations.isInjectedAnnotationWrapper(state)) throw error;
+			if (!require_internal_annotations.isInjectedAnnotationWrapper(state)) throw error;
 			return await require_phase2_seed.completeOrExtractPhase2Seed(parser, unwrapInjectedWrapper(state), exec);
 		}
 	};
@@ -954,12 +954,12 @@ function multiple(parser, options = {}) {
 		};
 		let added = !canExtendCurrent;
 		let itemIndex = canExtendCurrent ? context.state.length - 1 : context.state.length;
-		const currentItemStateWithAnnotations = canExtendCurrent ? currentItemState : require_annotations.inheritAnnotations(context.state, syncParser.initialState);
+		const currentItemStateWithAnnotations = canExtendCurrent ? currentItemState : require_internal_annotations.inheritAnnotations(context.state, syncParser.initialState);
 		let result = parseSyncWithUnwrappedFallback(require_execution_context.withChildContext(context, itemIndex, currentItemStateWithAnnotations));
 		if (!result.success) {
 			if (result.consumed !== 0) return result;
 			if (!added && canOpenFreshItem) {
-				const nextInitialState = require_annotations.inheritAnnotations(context.state, syncParser.initialState);
+				const nextInitialState = require_internal_annotations.inheritAnnotations(context.state, syncParser.initialState);
 				itemIndex = context.state.length;
 				result = parseSyncWithUnwrappedFallback(require_execution_context.withChildContext(context, itemIndex, nextInitialState));
 				if (!result.success) {
@@ -1007,13 +1007,13 @@ function multiple(parser, options = {}) {
 			},
 			consumed: result.consumed
 		};
-		const nextItemState = require_annotations.inheritAnnotations(itemAnnotationSource, result.next.state);
+		const nextItemState = require_internal_annotations.inheritAnnotations(itemAnnotationSource, result.next.state);
 		return {
 			success: true,
 			...result.provisional ? { provisional: true } : {},
 			next: {
 				...result.next,
-				state: require_annotations.annotateFreshArray(context.state, [...added ? context.state : context.state.slice(0, -1), nextItemState]),
+				state: require_internal_annotations.annotateFreshArray(context.state, [...added ? context.state : context.state.slice(0, -1), nextItemState]),
 				...mergedExec != null ? {
 					trace: mergedExec.trace,
 					exec: mergedExec,
@@ -1035,12 +1035,12 @@ function multiple(parser, options = {}) {
 		};
 		let added = !canExtendCurrent;
 		let itemIndex = canExtendCurrent ? context.state.length - 1 : context.state.length;
-		const currentItemStateWithAnnotations = canExtendCurrent ? currentItemState : require_annotations.inheritAnnotations(context.state, parser.initialState);
+		const currentItemStateWithAnnotations = canExtendCurrent ? currentItemState : require_internal_annotations.inheritAnnotations(context.state, parser.initialState);
 		let result = await parseAsyncWithUnwrappedFallback(require_execution_context.withChildContext(context, itemIndex, currentItemStateWithAnnotations));
 		if (!result.success) {
 			if (result.consumed !== 0) return result;
 			if (!added && canOpenFreshItem) {
-				const nextInitialState = require_annotations.inheritAnnotations(context.state, parser.initialState);
+				const nextInitialState = require_internal_annotations.inheritAnnotations(context.state, parser.initialState);
 				itemIndex = context.state.length;
 				result = await parseAsyncWithUnwrappedFallback(require_execution_context.withChildContext(context, itemIndex, nextInitialState));
 				if (!result.success) {
@@ -1088,13 +1088,13 @@ function multiple(parser, options = {}) {
 			},
 			consumed: result.consumed
 		};
-		const nextItemState = require_annotations.inheritAnnotations(itemAnnotationSource, result.next.state);
+		const nextItemState = require_internal_annotations.inheritAnnotations(itemAnnotationSource, result.next.state);
 		return {
 			success: true,
 			...result.provisional ? { provisional: true } : {},
 			next: {
 				...result.next,
-				state: require_annotations.annotateFreshArray(context.state, [...added ? context.state : context.state.slice(0, -1), nextItemState]),
+				state: require_internal_annotations.annotateFreshArray(context.state, [...added ? context.state : context.state.slice(0, -1), nextItemState]),
 				...mergedExec != null ? {
 					trace: mergedExec.trace,
 					exec: mergedExec,
@@ -1226,7 +1226,7 @@ function multiple(parser, options = {}) {
 			const canOpenNew = context.state.length < max;
 			if (!canExtendCurrent && !canOpenNew) return require_mode_dispatch.dispatchIterableByMode(parser.mode, function* () {}, async function* () {});
 			const itemIndex = canExtendCurrent ? context.state.length - 1 : context.state.length;
-			const suggestInitialState = canExtendCurrent ? currentItemState : require_annotations.inheritAnnotations(context.state, parser.initialState);
+			const suggestInitialState = canExtendCurrent ? currentItemState : require_internal_annotations.inheritAnnotations(context.state, parser.initialState);
 			const suggestFallbackState = unwrapInjectedWrapper(suggestInitialState);
 			const hasSuggestFallbackState = suggestFallbackState !== suggestInitialState;
 			const collectSelectedValuesSync = () => {
@@ -1311,7 +1311,7 @@ function multiple(parser, options = {}) {
 		},
 		getDocFragments(state, defaultValue) {
 			const latestState = state.kind === "available" && state.state.length > 0 ? state.state.at(-1) : void 0;
-			const latestInnerState = latestState != null && require_annotations.isInjectedAnnotationWrapper(latestState) ? unwrapInjectedWrapper(latestState) : latestState;
+			const latestInnerState = latestState != null && require_internal_annotations.isInjectedAnnotationWrapper(latestState) ? unwrapInjectedWrapper(latestState) : latestState;
 			const innerState = state.kind === "unavailable" ? { kind: "unavailable" } : latestInnerState !== void 0 ? {
 				kind: "available",
 				state: latestInnerState
@@ -1536,7 +1536,7 @@ function nonEmpty(parser) {
 		acceptingAnyToken: parser.acceptingAnyToken,
 		initialState,
 		...typeof parser.canSkip === "function" ? { canSkip(state, exec) {
-			const unwrappedState = require_annotations.unwrapInjectedAnnotationWrapper(state);
+			const unwrappedState = require_internal_annotations.unwrapInjectedAnnotationWrapper(state);
 			if (unwrappedState === initialState) return false;
 			return parser.canSkip?.(unwrappedState, exec) === true;
 		} } : {},

package/dist/parser.cjs

@@ -1,12 +1,12 @@
-const require_parser = require('./internal/parser.cjs');
+const require_internal_parser = require('./internal/parser.cjs');
 
-exports.createParserContext = require_parser.createParserContext;
-exports.getDocPage = require_parser.getDocPage;
-exports.getDocPageAsync = require_parser.getDocPageAsync;
-exports.getDocPageSync = require_parser.getDocPageSync;
-exports.parse = require_parser.parse;
-exports.parseAsync = require_parser.parseAsync;
-exports.parseSync = require_parser.parseSync;
-exports.suggest = require_parser.suggest;
-exports.suggestAsync = require_parser.suggestAsync;
-exports.suggestSync = require_parser.suggestSync;
+exports.createParserContext = require_internal_parser.createParserContext;
+exports.getDocPage = require_internal_parser.getDocPage;
+exports.getDocPageAsync = require_internal_parser.getDocPageAsync;
+exports.getDocPageSync = require_internal_parser.getDocPageSync;
+exports.parse = require_internal_parser.parse;
+exports.parseAsync = require_internal_parser.parseAsync;
+exports.parseSync = require_internal_parser.parseSync;
+exports.suggest = require_internal_parser.suggest;
+exports.suggestAsync = require_internal_parser.suggestAsync;
+exports.suggestSync = require_internal_parser.suggestSync;

package/dist/phase2-seed.cjs

@@ -1,4 +1,4 @@
-const require_annotations = require('./internal/annotations.cjs');
+const require_internal_annotations = require('./internal/annotations.cjs');
 const require_mode_dispatch = require('./internal/mode-dispatch.cjs');
 
 //#region src/phase2-seed.ts
@@ -15,7 +15,7 @@ const extractPhase2SeedKey = Symbol("@optique/core/extractPhase2Seed");
 */
 function phase2SeedFromValueResult(result) {
 	return {
-		value: require_annotations.unwrapInjectedAnnotationWrapper(result.value),
+		value: require_internal_annotations.unwrapInjectedAnnotationWrapper(result.value),
 		...result.deferred ? { deferred: true } : {},
 		...result.deferredKeys != null ? { deferredKeys: result.deferredKeys } : {}
 	};

package/dist/phase2-seed.d.cts

@@ -0,0 +1,50 @@
+import { DeferredMap, ValueParserResult } from "./valueparser.cjs";
+import { ExecutionContext, Mode, ModeValue, Parser } from "./internal/parser.cjs";
+
+//#region src/phase2-seed.d.ts
+
+/**
+ * Best-effort parser value used for phase-two context collection.
+ *
+ * @internal
+ */
+interface Phase2Seed<T = unknown> {
+  readonly value: T;
+  readonly deferred?: true;
+  readonly deferredKeys?: DeferredMap;
+}
+/**
+ * Internal hook for extracting a best-effort phase-two seed from parser state.
+ *
+ * @internal
+ */
+type Phase2SeedExtractor<M extends Mode = Mode, TState = unknown, TValue = unknown> = (state: TState, exec?: ExecutionContext) => ModeValue<M, Phase2Seed<TValue> | null>;
+/**
+ * Internal parser hook key for phase-two seed extraction.
+ *
+ * @internal
+ */
+declare const extractPhase2SeedKey: unique symbol;
+/**
+ * Converts a successful complete() result into a phase-two seed.
+ *
+ * @internal
+ */
+declare function phase2SeedFromValueResult<T>(result: Extract<ValueParserResult<T>, {
+  readonly success: true;
+}>): Phase2Seed<T>;
+/**
+ * Invokes a parser's internal phase-two seed hook when present.
+ *
+ * @internal
+ */
+declare function extractPhase2Seed<M extends Mode, TValue, TState>(parser: Parser<M, TValue, TState>, state: TState, exec?: ExecutionContext): ModeValue<M, Phase2Seed<TValue> | null>;
+/**
+ * Attempts to complete a parser and falls back to the internal phase-two
+ * seed hook when completion returns an unsuccessful result.
+ *
+ * @internal
+ */
+declare function completeOrExtractPhase2Seed<M extends Mode, TValue, TState>(parser: Parser<M, TValue, TState>, state: TState, exec?: ExecutionContext): ModeValue<M, Phase2Seed<TValue> | null>;
+//#endregion
+export { Phase2Seed, Phase2SeedExtractor, completeOrExtractPhase2Seed, extractPhase2Seed, extractPhase2SeedKey, phase2SeedFromValueResult };

package/dist/phase2-seed.d.ts

@@ -0,0 +1,50 @@
+import { DeferredMap, ValueParserResult } from "./valueparser.js";
+import { ExecutionContext, Mode, ModeValue, Parser } from "./internal/parser.js";
+
+//#region src/phase2-seed.d.ts
+
+/**
+ * Best-effort parser value used for phase-two context collection.
+ *
+ * @internal
+ */
+interface Phase2Seed<T = unknown> {
+  readonly value: T;
+  readonly deferred?: true;
+  readonly deferredKeys?: DeferredMap;
+}
+/**
+ * Internal hook for extracting a best-effort phase-two seed from parser state.
+ *
+ * @internal
+ */
+type Phase2SeedExtractor<M extends Mode = Mode, TState = unknown, TValue = unknown> = (state: TState, exec?: ExecutionContext) => ModeValue<M, Phase2Seed<TValue> | null>;
+/**
+ * Internal parser hook key for phase-two seed extraction.
+ *
+ * @internal
+ */
+declare const extractPhase2SeedKey: unique symbol;
+/**
+ * Converts a successful complete() result into a phase-two seed.
+ *
+ * @internal
+ */
+declare function phase2SeedFromValueResult<T>(result: Extract<ValueParserResult<T>, {
+  readonly success: true;
+}>): Phase2Seed<T>;
+/**
+ * Invokes a parser's internal phase-two seed hook when present.
+ *
+ * @internal
+ */
+declare function extractPhase2Seed<M extends Mode, TValue, TState>(parser: Parser<M, TValue, TState>, state: TState, exec?: ExecutionContext): ModeValue<M, Phase2Seed<TValue> | null>;
+/**
+ * Attempts to complete a parser and falls back to the internal phase-two
+ * seed hook when completion returns an unsuccessful result.
+ *
+ * @internal
+ */
+declare function completeOrExtractPhase2Seed<M extends Mode, TValue, TState>(parser: Parser<M, TValue, TState>, state: TState, exec?: ExecutionContext): ModeValue<M, Phase2Seed<TValue> | null>;
+//#endregion
+export { Phase2Seed, Phase2SeedExtractor, completeOrExtractPhase2Seed, extractPhase2Seed, extractPhase2SeedKey, phase2SeedFromValueResult };