@optique/core 1.0.0-dev.1616 → 1.0.0-dev.1659

package/dist/modifiers.js

@@ -1,10 +1,84 @@
-import { annotateFreshArray, getAnnotations, inheritAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper } from "./annotations.js";
+import { annotateFreshArray, annotationKey, getAnnotations, inheritAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper } from "./annotations.js";
 import { formatMessage, message, text } from "./message.js";
-import { createDependencySourceState, dependencyId, isDependencySourceState, isPendingDependencySourceState, isWrappedDependencySource, transformsDependencyValue, transformsDependencyValueMarker, wrappedDependencySourceMarker } from "./dependency.js";
 import { dispatchByMode, dispatchIterableByMode, mapModeValue } from "./mode-dispatch.js";
 import { composeDependencyMetadata } from "./dependency-metadata.js";
+import { defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser } from "./parser.js";
 
 //#region src/modifiers.ts
+function withChildExecPath(exec, segment) {
+	if (exec == null) return void 0;
+	return {
+		...exec,
+		path: [...exec.path ?? [], segment]
+	};
+}
+function mergeChildExec(parent, child) {
+	if (parent == null) return child;
+	if (child == null) return parent;
+	return {
+		...parent,
+		trace: child.trace ?? parent.trace,
+		dependencyRuntime: child.dependencyRuntime ?? parent.dependencyRuntime,
+		dependencyRegistry: child.dependencyRegistry ?? parent.dependencyRegistry,
+		preCompletedByParser: child.preCompletedByParser ?? parent.preCompletedByParser,
+		excludedSourceFields: child.excludedSourceFields ?? parent.excludedSourceFields
+	};
+}
+function withChildContext(context, segment, state) {
+	const exec = withChildExecPath(context.exec, segment);
+	const dependencyRegistry = context.dependencyRegistry ?? exec?.dependencyRegistry;
+	return {
+		...context,
+		state,
+		...exec != null ? {
+			exec: dependencyRegistry === exec.dependencyRegistry ? exec : {
+				...exec,
+				dependencyRegistry
+			},
+			dependencyRegistry
+		} : {}
+	};
+}
+function isTerminalMultipleItemState(state) {
+	const unwrapped = unwrapMultipleItemState(state).value;
+	return unwrapped != null && typeof unwrapped === "object" && Object.hasOwn(unwrapped, "success") && typeof unwrapped.success === "boolean";
+}
+function isUnstartedMultipleItemState(state, originalState) {
+	const unwrappedState = unwrapMultipleItemState(state);
+	if (unwrappedState.value == null) return true;
+	if (originalState === void 0) return false;
+	const unwrappedOriginalState = unwrapMultipleItemState(originalState);
+	return unwrappedState.value === unwrappedOriginalState.value && (unwrappedState.viaBoundCliWrapper || unwrappedOriginalState.viaBoundCliWrapper || unwrappedOriginalState.value != null && typeof unwrappedOriginalState.value === "object");
+}
+function isBoundCliWrapperState(state) {
+	return state != null && typeof state === "object" && Object.hasOwn(state, "hasCliValue") && typeof state.hasCliValue === "boolean" && (Object.hasOwn(state, "cliState") || state.hasCliValue === false);
+}
+function unwrapMultipleItemState(state) {
+	let unwrapped = state;
+	let viaBoundCliWrapper = false;
+	while (true) {
+		if (isInjectedAnnotationWrapper(unwrapped)) {
+			unwrapped = unwrapInjectedAnnotationWrapper(unwrapped);
+			continue;
+		}
+		if (Array.isArray(unwrapped) && unwrapped.length === 1) {
+			unwrapped = unwrapped[0];
+			continue;
+		}
+		if (isBoundCliWrapperState(unwrapped)) {
+			viaBoundCliWrapper = true;
+			unwrapped = unwrapped.cliState;
+			continue;
+		}
+		return {
+			value: unwrapped,
+			viaBoundCliWrapper
+		};
+	}
+}
+function isPromiseLike(value) {
+	return value != null && (typeof value === "object" || typeof value === "function") && "then" in value && typeof value.then === "function";
+}
 /**
 * Internal helper for optional-style parsing logic shared by optional()
 * and withDefault(). Handles the common pattern of:
@@ -75,16 +149,26 @@ function processOptionalStyleResult(result, innerState, context) {
 *
 * @internal
 */
-function adaptShouldDeferCompletion(innerCheck) {
+function adaptShouldDeferCompletion(innerCheck, parser) {
 	return (state, exec) => {
-		if (Array.isArray(state)) {
-			const inner = getAnnotations(state) != null && state[0] != null && typeof state[0] === "object" ? inheritAnnotations(state, state[0]) : state[0];
-			return innerCheck(inner, exec);
-		}
-		if (state != null && typeof state === "object") return innerCheck(state, exec);
+		if (Array.isArray(state) || state != null && typeof state === "object") return innerCheck(normalizeOptionalLikeInnerState(state, parser.initialState, parser), exec);
 		return false;
 	};
 }
+function isAnnotationOnlyObjectState(state) {
+	if (state == null || typeof state !== "object" || Array.isArray(state) || isInjectedAnnotationWrapper(state)) return false;
+	const keys = Reflect.ownKeys(state);
+	return getAnnotations(state) != null && keys.length === 1 && keys[0] === annotationKey;
+}
+function normalizeOptionalLikeInnerState(state, initialState, parser) {
+	if (Array.isArray(state)) return getAnnotations(state) != null && state[0] != null && typeof state[0] === "object" ? inheritAnnotations(state, state[0]) : state[0];
+	if (isAnnotationOnlyObjectState(state)) {
+		if (parser != null && (parser.dependencyMetadata?.source != null || typeof parser.shouldDeferCompletion === "function")) return inheritAnnotations(state, initialState);
+		return initialState;
+	}
+	if (state != null && typeof state === "object") return state;
+	return initialState;
+}
 /**
 * Creates a parser that makes another parser optional, allowing it to succeed
 * without consuming input if the wrapped parser fails to match.
@@ -100,25 +184,20 @@ function adaptShouldDeferCompletion(innerCheck) {
 function optional(parser) {
 	const syncParser = parser;
 	function* suggestSync(context, prefix) {
-		const innerState = Array.isArray(context.state) ? context.state[0] : syncParser.initialState;
+		const innerState = normalizeOptionalLikeInnerState(context.state, syncParser.initialState, parser);
 		yield* syncParser.suggest({
 			...context,
 			state: innerState
 		}, prefix);
 	}
 	async function* suggestAsync(context, prefix) {
-		const innerState = Array.isArray(context.state) ? context.state[0] : syncParser.initialState;
+		const innerState = normalizeOptionalLikeInnerState(context.state, syncParser.initialState, parser);
 		const suggestions = parser.suggest({
 			...context,
 			state: innerState
 		}, prefix);
 		for await (const s of suggestions) yield s;
 	}
-	const innerHasWrappedDependency = isWrappedDependencySource(parser);
-	const innerHasDirectDependency = isPendingDependencySourceState(syncParser.initialState);
-	const wrappedDependencyMarker = innerHasWrappedDependency ? { [wrappedDependencySourceMarker]: parser[wrappedDependencySourceMarker] } : innerHasDirectDependency ? { [wrappedDependencySourceMarker]: syncParser.initialState } : {};
-	const hasWrappedDependencySource = wrappedDependencySourceMarker in wrappedDependencyMarker;
-	const wrappedPendingState = hasWrappedDependencySource ? wrappedDependencyMarker[wrappedDependencySourceMarker] : void 0;
 	const optionalParser = {
 		$mode: parser.$mode,
 		$valueType: [],
@@ -132,17 +211,29 @@ function optional(parser) {
 		leadingNames: parser.leadingNames,
 		acceptingAnyToken: false,
 		initialState: void 0,
-		...wrappedDependencyMarker,
-		...typeof parser.shouldDeferCompletion === "function" ? { shouldDeferCompletion: adaptShouldDeferCompletion(parser.shouldDeferCompletion.bind(parser)) } : {},
+		...typeof parser.shouldDeferCompletion === "function" ? { shouldDeferCompletion: adaptShouldDeferCompletion(parser.shouldDeferCompletion.bind(parser), parser) } : {},
+		getSuggestRuntimeNodes(state, path) {
+			if (optionalParser.dependencyMetadata?.source != null) return [{
+				path,
+				parser: optionalParser,
+				state
+			}];
+			const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
+			return parser.getSuggestRuntimeNodes?.(innerState, path) ?? (parser.dependencyMetadata?.source != null ? [{
+				path,
+				parser,
+				state: innerState
+			}] : []);
+		},
 		parse(context) {
 			return dispatchByMode(parser.$mode, () => parseOptionalStyleSync(context, syncParser), () => parseOptionalStyleAsync(context, parser));
 		},
 		complete(state, exec) {
 			if (!Array.isArray(state)) {
-				if (innerHasWrappedDependency && wrappedPendingState) return dispatchByMode(parser.$mode, () => syncParser.complete([wrappedPendingState], exec), () => parser.complete([wrappedPendingState], exec));
 				if (typeof parser.shouldDeferCompletion === "function" && state != null && typeof state === "object") {
 					const innerComplete = () => {
-						const innerResult = dispatchByMode(parser.$mode, () => syncParser.complete(state, exec), () => parser.complete(state, exec));
+						const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
+						const innerResult = dispatchByMode(parser.$mode, () => syncParser.complete(innerState, exec), async () => await parser.complete(innerState, exec));
 						return mapModeValue(parser.$mode, innerResult, (result) => result.success ? result : {
 							success: true,
 							value: void 0
@@ -150,20 +241,18 @@ function optional(parser) {
 					};
 					return innerComplete();
 				}
+				const sourceMetadata = parser.dependencyMetadata?.source;
+				if (sourceMetadata?.preservesSourceValue !== false && sourceMetadata?.getMissingSourceValue != null) {
+					const delegatedState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
+					return dispatchByMode(parser.$mode, () => syncParser.complete(delegatedState, exec), async () => await parser.complete(delegatedState, exec));
+				}
 				return {
 					success: true,
 					value: void 0
 				};
 			}
-			if (Array.isArray(state) && state.length === 1 && isPendingDependencySourceState(state[0])) {
-				if (innerHasWrappedDependency) return dispatchByMode(parser.$mode, () => syncParser.complete(state, exec), () => parser.complete(state, exec));
-				return {
-					success: true,
-					value: void 0
-				};
-			}
-			const innerElement = getAnnotations(state) != null && state[0] != null && typeof state[0] === "object" ? inheritAnnotations(state, state[0]) : state[0];
-			return dispatchByMode(parser.$mode, () => syncParser.complete(innerElement, exec), () => parser.complete(innerElement, exec));
+			const innerElement = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
+			return dispatchByMode(parser.$mode, () => syncParser.complete(innerElement, exec), async () => await parser.complete(innerElement, exec));
 		},
 		suggest(context, prefix) {
 			return dispatchIterableByMode(parser.$mode, () => suggestSync(context, prefix), () => suggestAsync(context, prefix));
@@ -191,6 +280,8 @@ function optional(parser) {
 		const composed = composeDependencyMetadata(parser.dependencyMetadata, "optional");
 		if (composed != null) optionalParser.dependencyMetadata = composed;
 	}
+	defineInheritedAnnotationParser(optionalParser);
+	defineSourceBindingOnlyAnnotationCompletionParser(optionalParser);
 	return optionalParser;
 }
 /**
@@ -240,22 +331,20 @@ function withDefault(parser, defaultValue, options) {
 		}
 	};
 	function* suggestSync(context, prefix) {
-		const innerState = Array.isArray(context.state) ? context.state[0] : syncParser.initialState;
+		const innerState = normalizeOptionalLikeInnerState(context.state, syncParser.initialState, parser);
 		yield* syncParser.suggest({
 			...context,
 			state: innerState
 		}, prefix);
 	}
 	async function* suggestAsync(context, prefix) {
-		const innerState = Array.isArray(context.state) ? context.state[0] : syncParser.initialState;
+		const innerState = normalizeOptionalLikeInnerState(context.state, syncParser.initialState, parser);
 		const suggestions = parser.suggest({
 			...context,
 			state: innerState
 		}, prefix);
 		for await (const s of suggestions) yield s;
 	}
-	const innerInitialState = syncParser.initialState;
-	const wrappedDependencyMarker = isPendingDependencySourceState(innerInitialState) ? { [wrappedDependencySourceMarker]: innerInitialState } : isWrappedDependencySource(parser) ? { [wrappedDependencySourceMarker]: parser[wrappedDependencySourceMarker] } : {};
 	const withDefaultParser = {
 		$mode: parser.$mode,
 		$valueType: [],
@@ -268,8 +357,20 @@ function withDefault(parser, defaultValue, options) {
 		leadingNames: parser.leadingNames,
 		acceptingAnyToken: false,
 		initialState: void 0,
-		...wrappedDependencyMarker,
-		...typeof parser.shouldDeferCompletion === "function" ? { shouldDeferCompletion: adaptShouldDeferCompletion(parser.shouldDeferCompletion.bind(parser)) } : {},
+		...typeof parser.shouldDeferCompletion === "function" ? { shouldDeferCompletion: adaptShouldDeferCompletion(parser.shouldDeferCompletion.bind(parser), parser) } : {},
+		getSuggestRuntimeNodes(state, path) {
+			if (withDefaultParser.dependencyMetadata?.source != null) return [{
+				path,
+				parser: withDefaultParser,
+				state
+			}];
+			const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
+			return parser.getSuggestRuntimeNodes?.(innerState, path) ?? (parser.dependencyMetadata?.source != null ? [{
+				path,
+				parser,
+				state: innerState
+			}] : []);
+		},
 		parse(context) {
 			return dispatchByMode(parser.$mode, () => parseOptionalStyleSync(context, syncParser), () => parseOptionalStyleAsync(context, parser));
 		},
@@ -282,51 +383,9 @@ function withDefault(parser, defaultValue, options) {
 				return raw;
 			}
 			if (!Array.isArray(state)) {
-				if (transformsDependencyValue(parser)) {
-					const innerResult = dispatchByMode(parser.$mode, () => syncParser.complete(void 0, exec), () => parser.complete(void 0, exec));
-					const handleInnerResult = (res) => {
-						if (isDependencySourceState(res)) try {
-							const value = evaluateDefault();
-							return createDependencySourceState({
-								success: true,
-								value
-							}, res[dependencyId]);
-						} catch (error) {
-							return {
-								success: false,
-								error: error instanceof WithDefaultError ? error.errorMessage : message`${text(String(error))}`
-							};
-						}
-						try {
-							const value = evaluateDefault();
-							return {
-								success: true,
-								value
-							};
-						} catch (error) {
-							return {
-								success: false,
-								error: error instanceof WithDefaultError ? error.errorMessage : message`${text(String(error))}`
-							};
-						}
-					};
-					return mapModeValue(parser.$mode, innerResult, handleInnerResult);
-				}
-				if (isWrappedDependencySource(parser)) try {
-					const value = evaluateDefault();
-					const pendingState = parser[wrappedDependencySourceMarker];
-					return createDependencySourceState({
-						success: true,
-						value
-					}, pendingState[dependencyId]);
-				} catch (error) {
-					return {
-						success: false,
-						error: error instanceof WithDefaultError ? error.errorMessage : message`${text(String(error))}`
-					};
-				}
 				if (typeof parser.shouldDeferCompletion === "function" && state != null && typeof state === "object") {
-					const innerResult = dispatchByMode(parser.$mode, () => syncParser.complete(state, exec), () => parser.complete(state, exec));
+					const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
+					const innerResult = dispatchByMode(parser.$mode, () => syncParser.complete(innerState, exec), async () => await parser.complete(innerState, exec));
 					return innerResult;
 				}
 				try {
@@ -342,52 +401,8 @@ function withDefault(parser, defaultValue, options) {
 					};
 				}
 			}
-			if (isPendingDependencySourceState(state[0])) {
-				if (transformsDependencyValue(parser)) {
-					const innerResult = dispatchByMode(parser.$mode, () => syncParser.complete(state, exec), () => parser.complete(state, exec));
-					const handleInnerResult = (res) => {
-						if (isDependencySourceState(res)) try {
-							const value = evaluateDefault();
-							return createDependencySourceState({
-								success: true,
-								value
-							}, res[dependencyId]);
-						} catch (error) {
-							return {
-								success: false,
-								error: error instanceof WithDefaultError ? error.errorMessage : message`${text(String(error))}`
-							};
-						}
-						try {
-							const value = evaluateDefault();
-							return {
-								success: true,
-								value
-							};
-						} catch (error) {
-							return {
-								success: false,
-								error: error instanceof WithDefaultError ? error.errorMessage : message`${text(String(error))}`
-							};
-						}
-					};
-					return mapModeValue(parser.$mode, innerResult, handleInnerResult);
-				}
-				try {
-					const value = evaluateDefault();
-					return createDependencySourceState({
-						success: true,
-						value
-					}, state[0][dependencyId]);
-				} catch (error) {
-					return {
-						success: false,
-						error: error instanceof WithDefaultError ? error.errorMessage : message`${text(String(error))}`
-					};
-				}
-			}
-			const innerElement = getAnnotations(state) != null && state[0] != null && typeof state[0] === "object" ? inheritAnnotations(state, state[0]) : state[0];
-			return dispatchByMode(parser.$mode, () => syncParser.complete(innerElement, exec), () => parser.complete(innerElement, exec));
+			const innerElement = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
+			return dispatchByMode(parser.$mode, () => syncParser.complete(innerElement, exec), async () => await parser.complete(innerElement, exec));
 		},
 		suggest(context, prefix) {
 			return dispatchIterableByMode(parser.$mode, () => suggestSync(context, prefix), () => suggestAsync(context, prefix));
@@ -461,6 +476,8 @@ function withDefault(parser, defaultValue, options) {
 		} });
 		if (composed != null) withDefaultParser.dependencyMetadata = composed;
 	}
+	defineInheritedAnnotationParser(withDefaultParser);
+	defineSourceBindingOnlyAnnotationCompletionParser(withDefaultParser);
 	return withDefaultParser;
 }
 /**
@@ -561,15 +578,22 @@ function map(parser, transform) {
 			};
 		});
 	};
-	const dependencyMarkers = isWrappedDependencySource(parser) ? {
-		[wrappedDependencySourceMarker]: parser[wrappedDependencySourceMarker],
-		[transformsDependencyValueMarker]: true
-	} : {};
 	const mappedParser = {
 		...parser,
 		$valueType: [],
 		complete,
-		...dependencyMarkers,
+		getSuggestRuntimeNodes(state, path) {
+			if (mappedParser.dependencyMetadata?.source != null) return [{
+				path,
+				parser: mappedParser,
+				state
+			}];
+			return parser.getSuggestRuntimeNodes?.(state, path) ?? (parser.dependencyMetadata?.source != null ? [{
+				path,
+				parser,
+				state
+			}] : []);
+		},
 		getDocFragments(state, _defaultValue) {
 			return parser.getDocFragments(state, void 0);
 		}
@@ -616,7 +640,7 @@ function map(parser, transform) {
 					...composed.derived,
 					replayParse: (rawInput, depValues) => {
 						const result = innerReplay(rawInput, depValues);
-						return result instanceof Promise ? result.then(applyMappedReplay) : applyMappedReplay(result);
+						return isPromiseLike(result) ? result.then(applyMappedReplay) : applyMappedReplay(result);
 					}
 				}
 			};
@@ -646,7 +670,9 @@ function multiple(parser, options = {}) {
 	const unwrapInjectedWrapper = unwrapInjectedAnnotationWrapper;
 	const completeSyncWithUnwrappedFallback = (state, exec) => {
 		try {
-			return syncParser.complete(state, exec);
+			const result = syncParser.complete(state, exec);
+			if (!result.success && isInjectedAnnotationWrapper(state)) return syncParser.complete(unwrapInjectedWrapper(state), exec);
+			return result;
 		} catch (error) {
 			if (!isInjectedAnnotationWrapper(state)) throw error;
 			return syncParser.complete(unwrapInjectedWrapper(state), exec);
@@ -670,7 +696,9 @@ function multiple(parser, options = {}) {
 	};
 	const completeAsyncWithUnwrappedFallback = async (state, exec) => {
 		try {
-			return await parser.complete(state, exec);
+			const result = await parser.complete(state, exec);
+			if (!result.success && isInjectedAnnotationWrapper(state)) return await parser.complete(unwrapInjectedWrapper(state), exec);
+			return result;
 		} catch (error) {
 			if (!isInjectedAnnotationWrapper(state)) throw error;
 			return await parser.complete(unwrapInjectedWrapper(state), exec);
@@ -692,56 +720,133 @@ function multiple(parser, options = {}) {
 			});
 		}
 	};
+	const getInnerSuggestRuntimeNodes = (state, path) => parser.getSuggestRuntimeNodes?.(state, path) ?? (parser.dependencyMetadata?.source != null ? [{
+		path,
+		parser,
+		state
+	}] : []);
 	const parseSync = (context) => {
-		let added = context.state.length < 1;
-		const currentItemStateWithAnnotations = context.state.at(-1) ?? inheritAnnotations(context.state, syncParser.initialState);
-		let result = parseSyncWithUnwrappedFallback({
-			...context,
-			state: currentItemStateWithAnnotations
-		});
-		if (!result.success) if (!added) {
+		const currentItemState = context.state.at(-1);
+		const canExtendCurrent = currentItemState != null && !isTerminalMultipleItemState(currentItemState);
+		const canOpenFreshItem = context.state.length < max;
+		if (!canExtendCurrent && !canOpenFreshItem) return {
+			success: true,
+			next: context,
+			consumed: []
+		};
+		let added = !canExtendCurrent;
+		let itemIndex = canExtendCurrent ? context.state.length - 1 : context.state.length;
+		const currentItemStateWithAnnotations = canExtendCurrent ? currentItemState : inheritAnnotations(context.state, syncParser.initialState);
+		let result = parseSyncWithUnwrappedFallback(withChildContext(context, itemIndex, currentItemStateWithAnnotations));
+		if (!result.success) if (!added && canOpenFreshItem && result.consumed === 0) {
 			const nextInitialState = inheritAnnotations(context.state, syncParser.initialState);
-			result = parseSyncWithUnwrappedFallback({
-				...context,
-				state: nextInitialState
-			});
+			itemIndex = context.state.length;
+			result = parseSyncWithUnwrappedFallback(withChildContext(context, itemIndex, nextInitialState));
 			if (!result.success) return result;
 			added = true;
 		} else return result;
+		const mergedExec = mergeChildExec(context.exec, result.next.exec);
+		if (added && result.consumed.length === 0 && result.next.optionsTerminated === context.optionsTerminated && isUnstartedMultipleItemState(result.next.state, currentItemStateWithAnnotations)) return {
+			success: true,
+			next: {
+				...result.next,
+				state: context.state,
+				...mergedExec != null ? {
+					trace: mergedExec.trace,
+					exec: mergedExec,
+					dependencyRegistry: mergedExec.dependencyRegistry
+				} : {}
+			},
+			consumed: result.consumed
+		};
 		const itemAnnotationSource = added ? context.state : currentItemStateWithAnnotations;
+		if (result.next.state === currentItemStateWithAnnotations && result.consumed.length > 0 && (!added || result.next.optionsTerminated !== context.optionsTerminated)) return {
+			success: true,
+			next: {
+				...result.next,
+				state: context.state,
+				...mergedExec != null ? {
+					trace: mergedExec.trace,
+					exec: mergedExec,
+					dependencyRegistry: mergedExec.dependencyRegistry
+				} : {}
+			},
+			consumed: result.consumed
+		};
 		const nextItemState = inheritAnnotations(itemAnnotationSource, result.next.state);
 		return {
 			success: true,
 			next: {
 				...result.next,
-				state: annotateFreshArray(context.state, [...added ? context.state : context.state.slice(0, -1), nextItemState])
+				state: annotateFreshArray(context.state, [...added ? context.state : context.state.slice(0, -1), nextItemState]),
+				...mergedExec != null ? {
+					trace: mergedExec.trace,
+					exec: mergedExec,
+					dependencyRegistry: mergedExec.dependencyRegistry
+				} : {}
 			},
 			consumed: result.consumed
 		};
 	};
 	const parseAsync = async (context) => {
-		let added = context.state.length < 1;
-		const currentItemStateWithAnnotations = context.state.at(-1) ?? inheritAnnotations(context.state, parser.initialState);
-		let result = await parseAsyncWithUnwrappedFallback({
-			...context,
-			state: currentItemStateWithAnnotations
-		});
-		if (!result.success) if (!added) {
+		const currentItemState = context.state.at(-1);
+		const canExtendCurrent = currentItemState != null && !isTerminalMultipleItemState(currentItemState);
+		const canOpenFreshItem = context.state.length < max;
+		if (!canExtendCurrent && !canOpenFreshItem) return {
+			success: true,
+			next: context,
+			consumed: []
+		};
+		let added = !canExtendCurrent;
+		let itemIndex = canExtendCurrent ? context.state.length - 1 : context.state.length;
+		const currentItemStateWithAnnotations = canExtendCurrent ? currentItemState : inheritAnnotations(context.state, parser.initialState);
+		let result = await parseAsyncWithUnwrappedFallback(withChildContext(context, itemIndex, currentItemStateWithAnnotations));
+		if (!result.success) if (!added && canOpenFreshItem && result.consumed === 0) {
 			const nextInitialState = inheritAnnotations(context.state, parser.initialState);
-			result = await parseAsyncWithUnwrappedFallback({
-				...context,
-				state: nextInitialState
-			});
+			itemIndex = context.state.length;
+			result = await parseAsyncWithUnwrappedFallback(withChildContext(context, itemIndex, nextInitialState));
 			if (!result.success) return result;
 			added = true;
 		} else return result;
+		const mergedExec = mergeChildExec(context.exec, result.next.exec);
+		if (added && result.consumed.length === 0 && result.next.optionsTerminated === context.optionsTerminated && isUnstartedMultipleItemState(result.next.state, currentItemStateWithAnnotations)) return {
+			success: true,
+			next: {
+				...result.next,
+				state: context.state,
+				...mergedExec != null ? {
+					trace: mergedExec.trace,
+					exec: mergedExec,
+					dependencyRegistry: mergedExec.dependencyRegistry
+				} : {}
+			},
+			consumed: result.consumed
+		};
 		const itemAnnotationSource = added ? context.state : currentItemStateWithAnnotations;
+		if (result.next.state === currentItemStateWithAnnotations && result.consumed.length > 0 && (!added || result.next.optionsTerminated !== context.optionsTerminated)) return {
+			success: true,
+			next: {
+				...result.next,
+				state: context.state,
+				...mergedExec != null ? {
+					trace: mergedExec.trace,
+					exec: mergedExec,
+					dependencyRegistry: mergedExec.dependencyRegistry
+				} : {}
+			},
+			consumed: result.consumed
+		};
 		const nextItemState = inheritAnnotations(itemAnnotationSource, result.next.state);
 		return {
 			success: true,
 			next: {
 				...result.next,
-				state: annotateFreshArray(context.state, [...added ? context.state : context.state.slice(0, -1), nextItemState])
+				state: annotateFreshArray(context.state, [...added ? context.state : context.state.slice(0, -1), nextItemState]),
+				...mergedExec != null ? {
+					trace: mergedExec.trace,
+					exec: mergedExec,
+					dependencyRegistry: mergedExec.dependencyRegistry
+				} : {}
 			},
 			consumed: result.consumed
 		};
@@ -759,6 +864,14 @@ function multiple(parser, options = {}) {
 		leadingNames: parser.leadingNames,
 		acceptingAnyToken: min > 0 && (parser.acceptingAnyToken ?? false),
 		initialState: [],
+		getSuggestRuntimeNodes(state, path) {
+			const innerNodes = state.flatMap((item, i) => [...getInnerSuggestRuntimeNodes(item, [...path, i])]);
+			return resultParser.dependencyMetadata?.source != null ? [{
+				path,
+				parser: resultParser,
+				state
+			}, ...innerNodes] : innerNodes;
+		},
 		parse(context) {
 			return dispatchByMode(parser.$mode, () => parseSync(context), () => parseAsync(context));
 		},
@@ -768,7 +881,7 @@ function multiple(parser, options = {}) {
 				const deferredIndices = /* @__PURE__ */ new Map();
 				let hasDeferred = false;
 				for (let i = 0; i < state.length; i++) {
-					const valueResult = completeSyncWithUnwrappedFallback(state[i], exec);
+					const valueResult = completeSyncWithUnwrappedFallback(state[i], withChildExecPath(exec, i));
 					if (valueResult.success) {
 						const unwrappedValue = unwrapInjectedWrapper(valueResult.value);
 						result.push(unwrappedValue);
@@ -782,12 +895,11 @@ function multiple(parser, options = {}) {
 				}
 				return validateMultipleResult(result, deferredIndices, hasDeferred);
 			}, async () => {
-				const results = await Promise.all(state.map((s) => completeAsyncWithUnwrappedFallback(s, exec)));
 				const values = [];
 				const deferredIndices = /* @__PURE__ */ new Map();
 				let hasDeferred = false;
-				for (let i = 0; i < results.length; i++) {
-					const valueResult = results[i];
+				for (let i = 0; i < state.length; i++) {
+					const valueResult = await completeAsyncWithUnwrappedFallback(state[i], withChildExecPath(exec, i));
 					if (valueResult.success) {
 						const unwrappedValue = unwrapInjectedWrapper(valueResult.value);
 						values.push(unwrappedValue);
@@ -803,18 +915,33 @@ function multiple(parser, options = {}) {
 			});
 		},
 		suggest(context, prefix) {
-			const selectedValues = /* @__PURE__ */ new Set();
-			const suggestInitialState = inheritAnnotations(context.state, parser.initialState);
+			const currentItemState = context.state.at(-1);
+			const canExtendCurrent = currentItemState != null && !isTerminalMultipleItemState(currentItemState);
+			const canOpenNew = context.state.length < max;
+			if (!canExtendCurrent && !canOpenNew) return dispatchIterableByMode(parser.$mode, function* () {}, async function* () {});
+			const itemIndex = canExtendCurrent ? context.state.length - 1 : context.state.length;
+			const suggestInitialState = canExtendCurrent ? currentItemState : inheritAnnotations(context.state, parser.initialState);
 			const suggestFallbackState = unwrapInjectedWrapper(suggestInitialState);
 			const hasSuggestFallbackState = suggestFallbackState !== suggestInitialState;
-			for (const s of context.state) {
-				const completed = completeSyncWithUnwrappedFallback(s);
-				if (completed.success) {
-					const valueStr = String(unwrapInjectedWrapper(completed.value));
-					selectedValues.add(valueStr);
+			const collectSelectedValuesSync = () => {
+				const selectedValues = /* @__PURE__ */ new Set();
+				for (let i = 0; i < context.state.length; i++) {
+					const childContext = withChildContext(context, i, context.state[i]);
+					const completed = completeSyncWithUnwrappedFallback(childContext.state, childContext.exec);
+					if (completed.success) selectedValues.add(String(unwrapInjectedWrapper(completed.value)));
 				}
-			}
-			const shouldInclude = (suggestion) => {
+				return selectedValues;
+			};
+			const collectSelectedValuesAsync = async () => {
+				const selectedValues = /* @__PURE__ */ new Set();
+				for (let i = 0; i < context.state.length; i++) {
+					const childContext = withChildContext(context, i, context.state[i]);
+					const completed = await completeAsyncWithUnwrappedFallback(childContext.state, childContext.exec);
+					if (completed.success) selectedValues.add(String(unwrapInjectedWrapper(completed.value)));
+				}
+				return selectedValues;
+			};
+			const shouldInclude = (selectedValues, suggestion) => {
 				if (suggestion.kind === "literal") return !selectedValues.has(suggestion.text);
 				return true;
 			};
@@ -835,11 +962,12 @@ function multiple(parser, options = {}) {
 				]);
 			};
 			return dispatchIterableByMode(parser.$mode, function* () {
+				const selectedValues = collectSelectedValuesSync();
 				const emitted = /* @__PURE__ */ new Set();
 				const yieldUnique = function* (suggestions) {
 					for (const s of suggestions) {
 						const key = suggestionKey(s);
-						if (shouldInclude(s) && !emitted.has(key)) {
+						if (shouldInclude(selectedValues, s) && !emitted.has(key)) {
 							emitted.add(key);
 							yield s;
 						}
@@ -847,24 +975,19 @@ function multiple(parser, options = {}) {
 				};
 				let shouldTryFallback = false;
 				try {
-					yield* yieldUnique(syncParser.suggest({
-						...context,
-						state: suggestInitialState
-					}, prefix));
+					yield* yieldUnique(syncParser.suggest(withChildContext(context, itemIndex, suggestInitialState), prefix));
 				} catch (error) {
 					if (!hasSuggestFallbackState) throw error;
 					shouldTryFallback = true;
 				}
-				if (shouldTryFallback) yield* yieldUnique(syncParser.suggest({
-					...context,
-					state: suggestFallbackState
-				}, prefix));
+				if (shouldTryFallback) yield* yieldUnique(syncParser.suggest(withChildContext(context, itemIndex, suggestFallbackState), prefix));
 			}, async function* () {
+				const selectedValues = await collectSelectedValuesAsync();
 				const emitted = /* @__PURE__ */ new Set();
 				const yieldUnique = async function* (suggestions) {
 					for await (const s of suggestions) {
 						const key = suggestionKey(s);
-						if (shouldInclude(s) && !emitted.has(key)) {
+						if (shouldInclude(selectedValues, s) && !emitted.has(key)) {
 							emitted.add(key);
 							yield s;
 						}
@@ -872,18 +995,12 @@ function multiple(parser, options = {}) {
 				};
 				let shouldTryFallback = false;
 				try {
-					yield* yieldUnique(parser.suggest({
-						...context,
-						state: suggestInitialState
-					}, prefix));
+					yield* yieldUnique(parser.suggest(withChildContext(context, itemIndex, suggestInitialState), prefix));
 				} catch (error) {
 					if (!hasSuggestFallbackState) throw error;
 					shouldTryFallback = true;
 				}
-				if (shouldTryFallback) yield* yieldUnique(parser.suggest({
-					...context,
-					state: suggestFallbackState
-				}, prefix));
+				if (shouldTryFallback) yield* yieldUnique(parser.suggest(withChildContext(context, itemIndex, suggestFallbackState), prefix));
 			});
 		},
 		getDocFragments(state, defaultValue) {
@@ -951,6 +1068,33 @@ function multiple(parser, options = {}) {
 			enumerable: false
 		});
 	}
+	if (parser.dependencyMetadata?.source != null) {
+		const innerSource = parser.dependencyMetadata.source;
+		Object.defineProperty(resultParser, "dependencyMetadata", {
+			value: {
+				...parser.dependencyMetadata,
+				source: {
+					...innerSource,
+					preservesSourceValue: false,
+					extractSourceValue: (state) => {
+						if (!Array.isArray(state)) return innerSource.extractSourceValue(state);
+						const scan = (index) => {
+							for (let i = index; i >= 0; i--) {
+								const result = innerSource.extractSourceValue(state[i]);
+								if (result == null) continue;
+								if (isPromiseLike(result)) return Promise.resolve(result).then((resolved) => resolved ?? scan(i - 1));
+								return result;
+							}
+							return void 0;
+						};
+						return scan(state.length - 1);
+					}
+				}
+			},
+			configurable: true,
+			enumerable: false
+		});
+	}
 	return resultParser;
 }
 /**
@@ -1019,6 +1163,13 @@ function nonEmpty(parser) {
 		acceptingAnyToken: parser.acceptingAnyToken,
 		initialState: parser.initialState,
 		...typeof parser.shouldDeferCompletion === "function" ? { shouldDeferCompletion: parser.shouldDeferCompletion.bind(parser) } : {},
+		getSuggestRuntimeNodes(state, path) {
+			return parser.getSuggestRuntimeNodes?.(state, path) ?? (parser.dependencyMetadata?.source != null ? [{
+				path,
+				parser,
+				state
+			}] : []);
+		},
 		parse(context) {
 			return dispatchByMode(parser.$mode, () => parseSync(context), () => parseAsync(context));
 		},