@optique/core 1.0.0-dev.908 → 1.0.0

package/dist/modifiers.js

@@ -1,20 +1,178 @@
-import { annotateFreshArray, getAnnotations, inheritAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper } from "./annotations.js";
+import { annotateFreshArray, annotationKey, getAnnotations, inheritAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper } from "./internal/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 { dispatchByMode, dispatchIterableByMode, mapModeValue, wrapForMode } from "./internal/mode-dispatch.js";
+import { defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, unmatchedNonCliDependencySourceStateMarker } from "./internal/parser.js";
+import { getDelegatedAnnotationState, hasDelegatedAnnotationCarrier, isAnnotationWrappedInitialState, normalizeDelegatedAnnotationState, normalizeNestedDelegatedAnnotationState } from "./annotation-state.js";
+import { mergeChildExec, withChildContext, withChildExecPath } from "./execution-context.js";
+import { completeOrExtractPhase2Seed, extractPhase2Seed, extractPhase2SeedKey, phase2SeedFromValueResult } from "./phase2-seed.js";
+import { composeDependencyMetadata } from "./dependency-metadata.js";
 
 //#region src/modifiers.ts
-const deferPromptUntilConfigResolvesKey = Symbol.for("@optique/config/deferPromptUntilResolved");
+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";
+}
+function normalizeOptionalLikeCompleteResult(result, shouldNormalize) {
+	return result.success && shouldNormalize ? {
+		...result,
+		value: normalizeNestedDelegatedAnnotationState(result.value)
+	} : result;
+}
+function shouldRetryOptionalLikeCompatibilityError(error, state) {
+	return error instanceof TypeError && state != null && typeof state === "object" && isInjectedAnnotationWrapper(state);
+}
+function completeOptionalLikeSync(parser, state, exec) {
+	const hasCarrier = hasDelegatedAnnotationCarrier(state);
+	const shouldRetryFalseResult = hasCarrier && isAnnotationWrappedInitialState(state);
+	const run = (candidate, shouldNormalize) => normalizeOptionalLikeCompleteResult(parser.complete(candidate, exec), shouldNormalize);
+	try {
+		const result = run(state, hasCarrier);
+		if (!result.success && shouldRetryFalseResult) return run(normalizeDelegatedAnnotationState(state), false);
+		return result;
+	} catch (error) {
+		if (!shouldRetryOptionalLikeCompatibilityError(error, state)) throw error;
+		return run(normalizeDelegatedAnnotationState(state), false);
+	}
+}
+async function completeOptionalLikeAsync(parser, state, exec) {
+	const hasCarrier = hasDelegatedAnnotationCarrier(state);
+	const shouldRetryFalseResult = hasCarrier && isAnnotationWrappedInitialState(state);
+	const run = async (candidate, shouldNormalize) => normalizeOptionalLikeCompleteResult(await parser.complete(candidate, exec), shouldNormalize);
+	try {
+		const result = await run(state, hasCarrier);
+		if (!result.success && shouldRetryFalseResult) return await run(normalizeDelegatedAnnotationState(state), false);
+		return result;
+	} catch (error) {
+		if (!shouldRetryOptionalLikeCompatibilityError(error, state)) throw error;
+		return await run(normalizeDelegatedAnnotationState(state), false);
+	}
+}
+function normalizeOptionalLikePhase2Seed(seed, shouldNormalize) {
+	return seed == null ? null : shouldNormalize ? {
+		...seed,
+		value: normalizeNestedDelegatedAnnotationState(seed.value)
+	} : seed;
+}
+function extractOptionalLikePhase2Seed(parser, state, exec) {
+	if (!Array.isArray(state) && !(state != null && typeof state === "object")) return wrapForMode(parser.mode, null);
+	const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
+	const hasCarrier = hasDelegatedAnnotationCarrier(innerState);
+	const shouldRetryFalseResult = hasCarrier && isAnnotationWrappedInitialState(innerState);
+	return dispatchByMode(parser.mode, () => {
+		try {
+			const result = parser.complete(innerState, exec);
+			if (result.success) return normalizeOptionalLikePhase2Seed(phase2SeedFromValueResult(result), hasCarrier);
+			if (shouldRetryFalseResult) {
+				const fallbackState = normalizeDelegatedAnnotationState(innerState);
+				const fallbackResult = parser.complete(fallbackState, exec);
+				if (fallbackResult.success) return normalizeOptionalLikePhase2Seed(phase2SeedFromValueResult(fallbackResult), false);
+			}
+			const seed = extractPhase2Seed(parser, innerState, exec);
+			if (seed == null && hasCarrier) {
+				const fallbackState = normalizeDelegatedAnnotationState(innerState);
+				return normalizeOptionalLikePhase2Seed(extractPhase2Seed(parser, fallbackState, exec), false);
+			}
+			return normalizeOptionalLikePhase2Seed(seed, hasCarrier);
+		} catch (error) {
+			if (!shouldRetryOptionalLikeCompatibilityError(error, innerState)) throw error;
+			const fallbackState = normalizeDelegatedAnnotationState(innerState);
+			const result = parser.complete(fallbackState, exec);
+			if (result.success) return normalizeOptionalLikePhase2Seed(phase2SeedFromValueResult(result), false);
+			return normalizeOptionalLikePhase2Seed(extractPhase2Seed(parser, fallbackState, exec), false);
+		}
+	}, async () => {
+		try {
+			const result = await parser.complete(innerState, exec);
+			if (result.success) return normalizeOptionalLikePhase2Seed(phase2SeedFromValueResult(result), hasCarrier);
+			if (shouldRetryFalseResult) {
+				const fallbackState = normalizeDelegatedAnnotationState(innerState);
+				const fallbackResult = await parser.complete(fallbackState, exec);
+				if (fallbackResult.success) return normalizeOptionalLikePhase2Seed(phase2SeedFromValueResult(fallbackResult), false);
+			}
+			const seed = await extractPhase2Seed(parser, innerState, exec);
+			if (seed == null && hasCarrier) {
+				const fallbackState = normalizeDelegatedAnnotationState(innerState);
+				return normalizeOptionalLikePhase2Seed(await extractPhase2Seed(parser, fallbackState, exec), false);
+			}
+			return normalizeOptionalLikePhase2Seed(seed, hasCarrier);
+		} catch (error) {
+			if (!shouldRetryOptionalLikeCompatibilityError(error, innerState)) throw error;
+			const fallbackState = normalizeDelegatedAnnotationState(innerState);
+			const result = await parser.complete(fallbackState, exec);
+			if (result.success) return normalizeOptionalLikePhase2Seed(phase2SeedFromValueResult(result), false);
+			return normalizeOptionalLikePhase2Seed(await extractPhase2Seed(parser, fallbackState, exec), false);
+		}
+	});
+}
+/**
+* Computes the inner state to pass through to the wrapped parser inside
+* {@link optional} / {@link withDefault}.  When the outer state is an
+* array, the inner state is `state[0]`.  Otherwise, including the
+* common case where `optional()` sits at top level and the outer state
+* is either `undefined` or an annotation wrapper from `parseOptionalLike`
+* / `parse({ annotations })`, we use the wrapped parser's
+* `initialState`, propagating annotations from the outer state so that
+* source-binding wrappers under `optional()` / `withDefault()` (e.g.,
+* `bindEnv()` / `bindConfig()`) can resolve their fallbacks.
+*
+* @internal
+*/
+function deriveOptionalInnerParseState(outerState, parser) {
+	if (Array.isArray(outerState)) {
+		const innerState = outerState[0];
+		if (getAnnotations(outerState) != null && innerState != null && typeof innerState === "object") return getDelegatedAnnotationState(outerState, innerState);
+		return innerState;
+	}
+	const initial = parser.initialState;
+	if (initial != null && typeof initial !== "object") return initial;
+	return initial != null && typeof initial === "object" ? getDelegatedAnnotationState(outerState, initial) : inheritAnnotations(outerState, initial);
+}
 /**
 * Internal helper for optional-style parsing logic shared by optional()
 * and withDefault(). Handles the common pattern of:
 * - Unwrapping optional state to inner parser state
-* - Detecting if inner parser actually matched (state changed or no consumption)
-* - Returning success with undefined state when inner parser fails without consuming
+* - Detecting if the inner parser actually matched (state changed or no consumption)
+* - Returning success with undefined state when the inner parser fails without consuming
 * @internal
 */
 function parseOptionalStyleSync(context, parser) {
-	const innerState = Array.isArray(context.state) ? context.state[0] : parser.initialState;
+	const innerState = deriveOptionalInnerParseState(context.state, parser);
 	const result = parser.parse({
 		...context,
 		state: innerState
@@ -26,7 +184,7 @@ function parseOptionalStyleSync(context, parser) {
 * @internal
 */
 async function parseOptionalStyleAsync(context, parser) {
-	const innerState = Array.isArray(context.state) ? context.state[0] : parser.initialState;
+	const innerState = deriveOptionalInnerParseState(context.state, parser);
 	const result = await parser.parse({
 		...context,
 		state: innerState
@@ -37,10 +195,14 @@ async function parseOptionalStyleAsync(context, parser) {
 * Internal helper to process optional-style parse results.
 * @internal
 */
+function hasOptionalLikeParseStateChanged(previousState, nextState) {
+	return previousState !== nextState && normalizeDelegatedAnnotationState(previousState) !== normalizeDelegatedAnnotationState(nextState);
+}
 function processOptionalStyleResult(result, innerState, context) {
 	if (result.success) {
-		if (result.next.state !== innerState || result.consumed.length === 0) return {
+		if (hasOptionalLikeParseStateChanged(innerState, result.next.state) || result.consumed.length === 0) return {
 			success: true,
+			...result.provisional ? { provisional: true } : {},
 			next: {
 				...result.next,
 				state: [result.next.state]
@@ -49,6 +211,7 @@ function processOptionalStyleResult(result, innerState, context) {
 		};
 		return {
 			success: true,
+			...result.provisional ? { provisional: true } : {},
 			next: {
 				...result.next,
 				state: context.state
@@ -64,6 +227,57 @@ function processOptionalStyleResult(result, innerState, context) {
 	return result;
 }
 /**
+* Creates a `shouldDeferCompletion` adapter that unwraps the outer state
+* shape (`[TState] | undefined`) used by {@link optional} and
+* {@link withDefault} before delegating to the inner parser's hook.
+*
+* When state is an array, the adapter unwraps `state[0]` and propagates
+* annotations from the outer array.  Non-array objects (e.g. PromptBindState
+* from `prompt()`) are passed through directly.  `undefined` returns `false`
+* without calling the inner hook.
+*
+* @internal
+*/
+function adaptShouldDeferCompletion(innerCheck, parser) {
+	return (state, exec) => {
+		if (Array.isArray(state) || state != null && typeof state === "object") {
+			const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
+			const hasCarrier = hasDelegatedAnnotationCarrier(innerState);
+			const shouldRetryFalseResult = hasCarrier && isAnnotationWrappedInitialState(innerState);
+			try {
+				const result = innerCheck(innerState, exec);
+				if (!result && shouldRetryFalseResult) return innerCheck(normalizeDelegatedAnnotationState(innerState), exec);
+				return result;
+			} catch (error) {
+				if (!shouldRetryOptionalLikeCompatibilityError(error, innerState)) throw error;
+				return innerCheck(normalizeDelegatedAnnotationState(innerState), 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 getDelegatedAnnotationState(state, state[0]);
+	if (isAnnotationOnlyObjectState(state)) {
+		if (parser != null && (parser.dependencyMetadata?.source != null || typeof parser.shouldDeferCompletion === "function")) return getDelegatedAnnotationState(state, initialState);
+		return initialState;
+	}
+	if (state != null && typeof state === "object") return state;
+	return initialState;
+}
+function normalizeOptionalLikeSuggestState(state, initialState, parser) {
+	if (Array.isArray(state)) {
+		const innerState = state[0];
+		return innerState != null && typeof innerState === "object" ? getDelegatedAnnotationState(state, innerState) : innerState;
+	}
+	return normalizeOptionalLikeInnerState(state, initialState, parser);
+}
+/**
 * Creates a parser that makes another parser optional, allowing it to succeed
 * without consuming input if the wrapped parser fails to match.
 * If the wrapped parser succeeds, this returns its value.
@@ -78,72 +292,86 @@ function processOptionalStyleResult(result, innerState, context) {
 function optional(parser) {
 	const syncParser = parser;
 	function* suggestSync(context, prefix) {
-		const innerState = Array.isArray(context.state) ? context.state[0] : syncParser.initialState;
+		const innerState = normalizeOptionalLikeSuggestState(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 = normalizeOptionalLikeSuggestState(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 deferPromptHook = Reflect.get(parser, deferPromptUntilConfigResolvesKey);
-	const deferPromptMarker = typeof deferPromptHook === "function" ? { [deferPromptUntilConfigResolvesKey]: deferPromptHook } : {};
-	return {
-		$mode: parser.$mode,
+	const optionalParser = {
+		mode: parser.mode,
 		$valueType: [],
 		$stateType: [],
+		...parser[unmatchedNonCliDependencySourceStateMarker] === true ? { [unmatchedNonCliDependencySourceStateMarker]: true } : {},
+		placeholder: void 0,
 		priority: parser.priority,
 		usage: [{
 			type: "optional",
 			terms: parser.usage
 		}],
+		leadingNames: parser.leadingNames,
+		acceptingAnyToken: false,
 		initialState: void 0,
-		...wrappedDependencyMarker,
-		...deferPromptMarker,
+		...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 = normalizeOptionalLikeSuggestState(state, parser.initialState, parser);
+			return parser.getSuggestRuntimeNodes?.(innerState, path) ?? (parser.dependencyMetadata?.source != null ? [{
+				path,
+				parser,
+				state: innerState
+			}] : []);
+		},
+		[extractPhase2SeedKey](state, exec) {
+			return extractOptionalLikePhase2Seed(parser, state, exec);
+		},
 		parse(context) {
-			return dispatchByMode(parser.$mode, () => parseOptionalStyleSync(context, syncParser), () => parseOptionalStyleAsync(context, parser));
+			return dispatchByMode(parser.mode, () => parseOptionalStyleSync(context, syncParser), () => parseOptionalStyleAsync(context, parser));
 		},
-		complete(state) {
+		complete(state, exec) {
 			if (!Array.isArray(state)) {
-				if (innerHasWrappedDependency && wrappedPendingState) return dispatchByMode(parser.$mode, () => syncParser.complete([wrappedPendingState]), () => parser.complete([wrappedPendingState]));
-				if (typeof deferPromptHook === "function" && state != null && typeof state === "object") {
-					const innerComplete = () => {
-						const innerResult = dispatchByMode(parser.$mode, () => syncParser.complete(state), () => parser.complete(state));
-						return mapModeValue(parser.$mode, innerResult, (result) => result.success ? result : {
-							success: true,
-							value: void 0
-						});
-					};
-					return innerComplete();
-				}
-				return {
-					success: true,
-					value: void 0
+				const delegateToInner = (resolvedInnerState) => {
+					const innerResult = dispatchByMode(parser.mode, () => completeOptionalLikeSync(syncParser, resolvedInnerState, exec), async () => await completeOptionalLikeAsync(parser, resolvedInnerState, exec));
+					return mapModeValue(parser.mode, innerResult, (result) => result.success ? result : {
+						success: true,
+						value: void 0
+					});
 				};
-			}
-			if (Array.isArray(state) && state.length === 1 && isPendingDependencySourceState(state[0])) {
-				if (innerHasWrappedDependency) return dispatchByMode(parser.$mode, () => syncParser.complete(state), () => parser.complete(state));
+				if (typeof parser.shouldDeferCompletion === "function" && state != null && typeof state === "object") {
+					const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
+					return delegateToInner(innerState);
+				}
+				const sourceMetadata = parser.dependencyMetadata?.source;
+				if (sourceMetadata?.preservesSourceValue !== false && sourceMetadata?.getMissingSourceValue != null) {
+					const delegatedState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
+					return dispatchByMode(parser.mode, () => completeOptionalLikeSync(syncParser, delegatedState, exec), async () => await completeOptionalLikeAsync(parser, delegatedState, exec));
+				}
+				if (parser[unmatchedNonCliDependencySourceStateMarker] === true && state != null && typeof state === "object") {
+					const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
+					return delegateToInner(innerState);
+				}
 				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), () => parser.complete(innerElement));
+			const innerElement = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
+			return dispatchByMode(parser.mode, () => completeOptionalLikeSync(syncParser, innerElement, exec), async () => await completeOptionalLikeAsync(parser, innerElement, exec));
 		},
 		suggest(context, prefix) {
-			return dispatchIterableByMode(parser.$mode, () => suggestSync(context, prefix), () => suggestAsync(context, prefix));
+			return dispatchIterableByMode(parser.mode, () => suggestSync(context, prefix), () => suggestAsync(context, prefix));
 		},
 		getDocFragments(state, defaultValue) {
 			const innerState = state.kind === "unavailable" ? { kind: "unavailable" } : state.state === void 0 ? { kind: "unavailable" } : {
@@ -153,6 +381,38 @@ function optional(parser) {
 			return syncParser.getDocFragments(innerState, defaultValue);
 		}
 	};
+	if (typeof parser.normalizeValue === "function") {
+		const innerNormalize = parser.normalizeValue.bind(parser);
+		Object.defineProperty(optionalParser, "normalizeValue", {
+			value(v) {
+				if (v == null) return v;
+				return innerNormalize(v);
+			},
+			configurable: true,
+			enumerable: false
+		});
+	}
+	if (typeof parser.validateValue === "function") {
+		const innerValidate = parser.validateValue.bind(parser);
+		Object.defineProperty(optionalParser, "validateValue", {
+			value(v) {
+				if (v === void 0) return wrapForMode(parser.mode, {
+					success: true,
+					value: v
+				});
+				return innerValidate(v);
+			},
+			configurable: true,
+			enumerable: false
+		});
+	}
+	if (parser.dependencyMetadata != null) {
+		const composed = composeDependencyMetadata(parser.dependencyMetadata, "optional");
+		if (composed != null) optionalParser.dependencyMetadata = composed;
+	}
+	defineInheritedAnnotationParser(optionalParser);
+	defineSourceBindingOnlyAnnotationCompletionParser(optionalParser);
+	return optionalParser;
 }
 /**
 * Error type for structured error messages in {@link withDefault} default value callbacks.
@@ -201,122 +461,76 @@ function withDefault(parser, defaultValue, options) {
 		}
 	};
 	function* suggestSync(context, prefix) {
-		const innerState = Array.isArray(context.state) ? context.state[0] : syncParser.initialState;
+		const innerState = normalizeOptionalLikeSuggestState(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 = normalizeOptionalLikeSuggestState(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 deferPromptHookDefault = Reflect.get(parser, deferPromptUntilConfigResolvesKey);
-	const deferPromptMarkerDefault = typeof deferPromptHookDefault === "function" ? { [deferPromptUntilConfigResolvesKey]: deferPromptHookDefault } : {};
-	return {
-		$mode: parser.$mode,
+	const withDefaultParser = {
+		mode: parser.mode,
 		$valueType: [],
 		$stateType: [],
+		...parser[unmatchedNonCliDependencySourceStateMarker] === true ? { [unmatchedNonCliDependencySourceStateMarker]: true } : {},
 		priority: parser.priority,
 		usage: [{
 			type: "optional",
 			terms: parser.usage
 		}],
+		leadingNames: parser.leadingNames,
+		acceptingAnyToken: false,
 		initialState: void 0,
-		...wrappedDependencyMarker,
-		...deferPromptMarkerDefault,
+		...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 = normalizeOptionalLikeSuggestState(state, parser.initialState, parser);
+			return parser.getSuggestRuntimeNodes?.(innerState, path) ?? (parser.dependencyMetadata?.source != null ? [{
+				path,
+				parser,
+				state: innerState
+			}] : []);
+		},
+		[extractPhase2SeedKey](state, exec) {
+			return extractOptionalLikePhase2Seed(parser, state, exec);
+		},
 		parse(context) {
-			return dispatchByMode(parser.$mode, () => parseOptionalStyleSync(context, syncParser), () => parseOptionalStyleAsync(context, parser));
+			return dispatchByMode(parser.mode, () => parseOptionalStyleSync(context, syncParser), () => parseOptionalStyleAsync(context, parser));
 		},
-		complete(state) {
+		complete(state, exec) {
+			function evaluateDefault() {
+				const raw = typeof defaultValue === "function" ? defaultValue() : defaultValue;
+				if (typeof parser.normalizeValue === "function") try {
+					return parser.normalizeValue(raw);
+				} catch {}
+				return raw;
+			}
 			if (!Array.isArray(state)) {
-				if (transformsDependencyValue(parser)) {
-					const innerResult = dispatchByMode(parser.$mode, () => syncParser.complete(void 0), () => parser.complete(void 0));
-					const handleInnerResult = (res) => {
-						if (isDependencySourceState(res)) try {
-							const value = typeof defaultValue === "function" ? defaultValue() : defaultValue;
-							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 = typeof defaultValue === "function" ? defaultValue() : defaultValue;
-							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 = typeof defaultValue === "function" ? defaultValue() : defaultValue;
-					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 deferPromptHookDefault === "function" && state != null && typeof state === "object") {
-					const innerResult = dispatchByMode(parser.$mode, () => syncParser.complete(state), () => parser.complete(state));
+				if (typeof parser.shouldDeferCompletion === "function" && state != null && typeof state === "object") {
+					const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
+					const innerResult = dispatchByMode(parser.mode, () => completeOptionalLikeSync(syncParser, innerState, exec), async () => await completeOptionalLikeAsync(parser, innerState, exec));
 					return innerResult;
 				}
-				try {
-					const value = typeof defaultValue === "function" ? defaultValue() : defaultValue;
-					return {
-						success: true,
-						value
-					};
-				} catch (error) {
-					return {
-						success: false,
-						error: error instanceof WithDefaultError ? error.errorMessage : message`${text(String(error))}`
-					};
-				}
-			}
-			if (isPendingDependencySourceState(state[0])) {
-				if (transformsDependencyValue(parser)) {
-					const innerResult = dispatchByMode(parser.$mode, () => syncParser.complete(state), () => parser.complete(state));
-					const handleInnerResult = (res) => {
-						if (isDependencySourceState(res)) try {
-							const value = typeof defaultValue === "function" ? defaultValue() : defaultValue;
-							return createDependencySourceState({
-								success: true,
-								value
-							}, res[dependencyId]);
-						} catch (error) {
-							return {
-								success: false,
-								error: error instanceof WithDefaultError ? error.errorMessage : message`${text(String(error))}`
-							};
-						}
+				if (parser[unmatchedNonCliDependencySourceStateMarker] === true && state != null && typeof state === "object") {
+					const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
+					const innerResult = dispatchByMode(parser.mode, () => completeOptionalLikeSync(syncParser, innerState, exec), async () => await completeOptionalLikeAsync(parser, innerState, exec));
+					const handleInnerResult = (result) => {
+						if (result.success && result.value !== void 0) return result;
 						try {
-							const value = typeof defaultValue === "function" ? defaultValue() : defaultValue;
 							return {
 								success: true,
-								value
+								value: evaluateDefault()
 							};
 						} catch (error) {
 							return {
@@ -325,14 +539,14 @@ function withDefault(parser, defaultValue, options) {
 							};
 						}
 					};
-					return mapModeValue(parser.$mode, innerResult, handleInnerResult);
+					return mapModeValue(parser.mode, innerResult, handleInnerResult);
 				}
 				try {
-					const value = typeof defaultValue === "function" ? defaultValue() : defaultValue;
-					return createDependencySourceState({
+					const value = evaluateDefault();
+					return {
 						success: true,
 						value
-					}, state[0][dependencyId]);
+					};
 				} catch (error) {
 					return {
 						success: false,
@@ -340,18 +554,22 @@ function withDefault(parser, defaultValue, options) {
 					};
 				}
 			}
-			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), () => parser.complete(innerElement));
+			const innerElement = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
+			return dispatchByMode(parser.mode, () => completeOptionalLikeSync(syncParser, innerElement, exec), async () => await completeOptionalLikeAsync(parser, innerElement, exec));
 		},
 		suggest(context, prefix) {
-			return dispatchIterableByMode(parser.$mode, () => suggestSync(context, prefix), () => suggestAsync(context, prefix));
+			return dispatchIterableByMode(parser.mode, () => suggestSync(context, prefix), () => suggestAsync(context, prefix));
 		},
 		getDocFragments(state, upperDefaultValue) {
 			const innerState = state.kind === "unavailable" ? { kind: "unavailable" } : state.state === void 0 ? { kind: "unavailable" } : {
 				kind: "available",
 				state: state.state[0]
 			};
-			const fragments = syncParser.getDocFragments(innerState, getDocDefaultValue(upperDefaultValue));
+			let docDefault = getDocDefaultValue(upperDefaultValue);
+			if (docDefault != null && typeof parser.normalizeValue === "function") try {
+				docDefault = parser.normalizeValue(docDefault);
+			} catch {}
+			const fragments = syncParser.getDocFragments(innerState, docDefault);
 			if (options?.message) {
 				const modifiedFragments = fragments.fragments.map((fragment) => {
 					if (fragment.type === "entry") return {
@@ -368,6 +586,62 @@ function withDefault(parser, defaultValue, options) {
 			return fragments;
 		}
 	};
+	if ("placeholder" in parser) Object.defineProperty(withDefaultParser, "placeholder", {
+		get() {
+			return parser.placeholder;
+		},
+		configurable: true,
+		enumerable: false
+	});
+	if (typeof parser.normalizeValue === "function") {
+		const innerNormalize = parser.normalizeValue.bind(parser);
+		Object.defineProperty(withDefaultParser, "normalizeValue", {
+			value(v) {
+				try {
+					return innerNormalize(v);
+				} catch {
+					return v;
+				}
+			},
+			configurable: true,
+			enumerable: false
+		});
+	}
+	if (typeof parser.validateValue === "function") {
+		const innerValidate = parser.validateValue.bind(parser);
+		Object.defineProperty(withDefaultParser, "validateValue", {
+			value(v) {
+				return innerValidate(v);
+			},
+			configurable: true,
+			enumerable: false
+		});
+	}
+	if (parser.dependencyMetadata != null) {
+		const composed = composeDependencyMetadata(parser.dependencyMetadata, "withDefault", { defaultValue: () => {
+			let v;
+			try {
+				v = typeof defaultValue === "function" ? defaultValue() : defaultValue;
+			} catch (e) {
+				const error = e instanceof WithDefaultError ? e.errorMessage : message`${e instanceof Error ? e.message : String(e)}`;
+				return {
+					success: false,
+					error
+				};
+			}
+			if (typeof parser.normalizeValue === "function") try {
+				v = parser.normalizeValue(v);
+			} catch {}
+			return {
+				success: true,
+				value: v
+			};
+		} });
+		if (composed != null) withDefaultParser.dependencyMetadata = composed;
+	}
+	defineInheritedAnnotationParser(withDefaultParser);
+	defineSourceBindingOnlyAnnotationCompletionParser(withDefaultParser);
+	return withDefaultParser;
 }
 /**
 * Creates a parser that transforms the result value of another parser using
@@ -388,6 +662,47 @@ function withDefault(parser, defaultValue, options) {
 * @param transform A function that transforms the parsed value from type T to type U.
 * @returns A {@link Parser} that produces the transformed value of type U
 *          while preserving the original parser's state type and parsing behavior.
+* @throws Any exception thrown by `transform` when completing a non-deferred
+*   value.  Errors from deferred placeholder transforms are caught and the
+*   mapped result falls back to `undefined` with `deferred: true`.
+*
+* ### Deferred prompt interaction
+*
+* During two-phase parsing, `map()` propagates the `deferred` flag from
+* inner results but intentionally drops per-field `deferredKeys`.  The
+* inner key set describes the *input* shape, but `transform` produces an
+* arbitrary *output* shape where keys may be renamed, dropped, or reused
+* with different semantics.  For `object()` results that are *not*
+* wrapped in `map()`, per-field deferred stripping works normally.
+*
+* Because the `deferred` flag is propagated conservatively, mapped scalar
+* results are treated as missing (`undefined`) during phase-two context
+* collection — even when `transform` only used non-deferred fields.
+* For example, `map(object({ apiKey: prompt(...), mode: option(...) }),
+* v => v.mode)` makes phase-two contexts see `undefined` instead of the
+* real `mode` value.  This is the intentional trade-off: the alternative
+* (not propagating `deferred`) would leak placeholder values into context
+* resolution when `transform` *does* use deferred fields.  The final
+* parse always produces the correct result regardless.
+*
+* If the transform throws on a deferred placeholder value, the mapped
+* result falls back to `undefined` with `deferred: true`, so the first
+* pass does not abort.
+*
+* ### Transform purity
+*
+* The `transform` function must not mutate its input.  Object and array
+* values may be shared placeholder references during deferred prompt
+* resolution, and in-place mutations would corrupt the placeholder for
+* subsequent parses.  Always return a new value:
+*
+* ```typescript
+* // ✅ Correct — creates a new object
+* map(parser, v => ({ ...v, host: "override" }))
+*
+* // ❌ Wrong — mutates the input in place
+* map(parser, v => { v.host = "override"; return v; })
+* ```
 *
 * @example
 * ```typescript
@@ -404,25 +719,116 @@ function withDefault(parser, defaultValue, options) {
 * ```
 */
 function map(parser, transform) {
-	const complete = (state) => {
-		return mapModeValue(parser.$mode, parser.complete(state), (result) => result.success ? {
-			success: true,
-			value: transform(result.value)
-		} : result);
+	const complete = (state, exec) => {
+		return mapModeValue(parser.mode, parser.complete(state, exec), (result) => {
+			if (!result.success) return result;
+			if (result.deferred) try {
+				return {
+					success: true,
+					value: transform(result.value),
+					deferred: true
+				};
+			} catch {
+				return {
+					success: true,
+					value: void 0,
+					deferred: true
+				};
+			}
+			return {
+				success: true,
+				value: transform(result.value)
+			};
+		});
 	};
-	const dependencyMarkers = isWrappedDependencySource(parser) ? {
-		[wrappedDependencySourceMarker]: parser[wrappedDependencySourceMarker],
-		[transformsDependencyValueMarker]: true
-	} : {};
-	return {
+	const mappedParser = {
 		...parser,
 		$valueType: [],
 		complete,
-		...dependencyMarkers,
+		[extractPhase2SeedKey](state, exec) {
+			return mapModeValue(parser.mode, completeOrExtractPhase2Seed(parser, state, exec), (seed) => {
+				if (seed == null) return null;
+				if (seed.deferred) try {
+					return {
+						value: transform(seed.value),
+						deferred: true
+					};
+				} catch {
+					return {
+						value: void 0,
+						deferred: true
+					};
+				}
+				return { value: transform(seed.value) };
+			});
+		},
+		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);
 		}
 	};
+	delete mappedParser.normalizeValue;
+	delete mappedParser.validateValue;
+	if ("placeholder" in parser) Object.defineProperty(mappedParser, "placeholder", {
+		get() {
+			try {
+				return transform(parser.placeholder);
+			} catch {
+				return void 0;
+			}
+		},
+		configurable: true,
+		enumerable: false
+	});
+	if (parser.dependencyMetadata != null) {
+		let composed = composeDependencyMetadata(parser.dependencyMetadata, "map");
+		if (composed?.derived != null) {
+			const innerReplay = composed.derived.replayParse;
+			const applyMappedReplay = (r) => {
+				if (!r.success) return r;
+				if (r.deferred) try {
+					return {
+						success: true,
+						value: transform(r.value),
+						deferred: true
+					};
+				} catch {
+					return {
+						success: true,
+						value: void 0,
+						deferred: true
+					};
+				}
+				return {
+					success: true,
+					value: transform(r.value)
+				};
+			};
+			composed = {
+				...composed,
+				derived: {
+					...composed.derived,
+					replayParse: (rawInput, depValues) => {
+						const result = innerReplay(rawInput, depValues);
+						return isPromiseLike(result) ? result.then(applyMappedReplay) : applyMappedReplay(result);
+					}
+				}
+			};
+		}
+		if (composed != null) mappedParser.dependencyMetadata = composed;
+	}
+	return mappedParser;
 }
 /**
 * Creates a parser that allows multiple occurrences of a given parser.
@@ -443,12 +849,14 @@ function multiple(parser, options = {}) {
 	const syncParser = parser;
 	const { min = 0, max = Infinity } = options;
 	const unwrapInjectedWrapper = unwrapInjectedAnnotationWrapper;
-	const completeSyncWithUnwrappedFallback = (state) => {
+	const completeSyncWithUnwrappedFallback = (state, exec) => {
 		try {
-			return syncParser.complete(state);
+			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));
+			return syncParser.complete(unwrapInjectedWrapper(state), exec);
 		}
 	};
 	const parseSyncWithUnwrappedFallback = (context) => {
@@ -467,12 +875,14 @@ function multiple(parser, options = {}) {
 			});
 		}
 	};
-	const completeAsyncWithUnwrappedFallback = async (state) => {
+	const completeAsyncWithUnwrappedFallback = async (state, exec) => {
 		try {
-			return await parser.complete(state);
+			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));
+			return await parser.complete(unwrapInjectedWrapper(state), exec);
 		}
 	};
 	const parseAsyncWithUnwrappedFallback = async (context) => {
@@ -491,62 +901,193 @@ function multiple(parser, options = {}) {
 			});
 		}
 	};
+	const extractPhase2SeedSyncWithUnwrappedFallback = (state, exec) => {
+		try {
+			const seed = completeOrExtractPhase2Seed(syncParser, state, exec);
+			if (seed == null && isInjectedAnnotationWrapper(state)) return completeOrExtractPhase2Seed(syncParser, unwrapInjectedWrapper(state), exec);
+			return seed;
+		} catch (error) {
+			if (!isInjectedAnnotationWrapper(state)) throw error;
+			return completeOrExtractPhase2Seed(syncParser, unwrapInjectedWrapper(state), exec);
+		}
+	};
+	const extractPhase2SeedAsyncWithUnwrappedFallback = async (state, exec) => {
+		try {
+			const seed = await completeOrExtractPhase2Seed(parser, state, exec);
+			if (seed == null && isInjectedAnnotationWrapper(state)) return await completeOrExtractPhase2Seed(parser, unwrapInjectedWrapper(state), exec);
+			return seed;
+		} catch (error) {
+			if (!isInjectedAnnotationWrapper(state)) throw error;
+			return await completeOrExtractPhase2Seed(parser, unwrapInjectedWrapper(state), exec);
+		}
+	};
+	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 nextInitialState = inheritAnnotations(context.state, syncParser.initialState);
-			result = parseSyncWithUnwrappedFallback({
-				...context,
-				state: nextInitialState
-			});
-			if (!result.success) return result;
-			added = true;
-		} else return result;
+		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 (result.consumed !== 0) return result;
+			if (!added && canOpenFreshItem) {
+				const nextInitialState = inheritAnnotations(context.state, syncParser.initialState);
+				itemIndex = context.state.length;
+				result = parseSyncWithUnwrappedFallback(withChildContext(context, itemIndex, nextInitialState));
+				if (!result.success) {
+					if (min === 0 && context.buffer.length === 0 && result.consumed === 0) return {
+						success: true,
+						next: context,
+						consumed: []
+					};
+					return result;
+				}
+				added = true;
+			} else if (min === 0 && context.buffer.length === 0) return {
+				success: true,
+				next: context,
+				consumed: []
+			};
+			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,
+			...result.provisional ? { provisional: 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,
+			...result.provisional ? { provisional: 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 nextInitialState = inheritAnnotations(context.state, parser.initialState);
-			result = await parseAsyncWithUnwrappedFallback({
-				...context,
-				state: nextInitialState
-			});
-			if (!result.success) return result;
-			added = true;
-		} else return result;
+		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 (result.consumed !== 0) return result;
+			if (!added && canOpenFreshItem) {
+				const nextInitialState = inheritAnnotations(context.state, parser.initialState);
+				itemIndex = context.state.length;
+				result = await parseAsyncWithUnwrappedFallback(withChildContext(context, itemIndex, nextInitialState));
+				if (!result.success) {
+					if (min === 0 && context.buffer.length === 0 && result.consumed === 0) return {
+						success: true,
+						next: context,
+						consumed: []
+					};
+					return result;
+				}
+				added = true;
+			} else if (min === 0 && context.buffer.length === 0) return {
+				success: true,
+				next: context,
+				consumed: []
+			};
+			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,
+			...result.provisional ? { provisional: 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,
+			...result.provisional ? { provisional: 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 resultParser = {
-		$mode: parser.$mode,
+		mode: parser.mode,
 		$valueType: [],
 		$stateType: [],
 		priority: parser.priority,
@@ -555,46 +1096,134 @@ function multiple(parser, options = {}) {
 			terms: parser.usage,
 			min
 		}],
+		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));
+			return dispatchByMode(parser.mode, () => parseSync(context), () => parseAsync(context));
 		},
-		complete(state) {
-			return dispatchByMode(parser.$mode, () => {
+		complete(state, exec) {
+			return dispatchByMode(parser.mode, () => {
 				const result = [];
-				for (const s of state) {
-					const valueResult = completeSyncWithUnwrappedFallback(s);
-					if (valueResult.success) result.push(unwrapInjectedWrapper(valueResult.value));
-					else return {
+				const deferredIndices = /* @__PURE__ */ new Map();
+				let hasDeferred = false;
+				for (let i = 0; i < state.length; i++) {
+					const valueResult = completeSyncWithUnwrappedFallback(state[i], withChildExecPath(exec, i));
+					if (valueResult.success) {
+						const unwrappedValue = unwrapInjectedWrapper(valueResult.value);
+						result.push(unwrappedValue);
+						if (valueResult.deferred) if (valueResult.deferredKeys) deferredIndices.set(i, valueResult.deferredKeys);
+						else if (unwrappedValue == null || typeof unwrappedValue !== "object") deferredIndices.set(i, null);
+						else hasDeferred = true;
+					} else return {
 						success: false,
 						error: valueResult.error
 					};
 				}
-				return validateMultipleResult(result);
+				return validateMultipleResult(result, deferredIndices, hasDeferred);
 			}, async () => {
-				const results = await Promise.all(state.map((s) => completeAsyncWithUnwrappedFallback(s)));
 				const values = [];
-				for (const valueResult of results) if (valueResult.success) values.push(unwrapInjectedWrapper(valueResult.value));
-				else return {
-					success: false,
-					error: valueResult.error
+				const deferredIndices = /* @__PURE__ */ new Map();
+				let hasDeferred = false;
+				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);
+						if (valueResult.deferred) if (valueResult.deferredKeys) deferredIndices.set(i, valueResult.deferredKeys);
+						else if (unwrappedValue == null || typeof unwrappedValue !== "object") deferredIndices.set(i, null);
+						else hasDeferred = true;
+					} else return {
+						success: false,
+						error: valueResult.error
+					};
+				}
+				return validateMultipleResult(values, deferredIndices, hasDeferred);
+			});
+		},
+		[extractPhase2SeedKey](state, exec) {
+			return dispatchByMode(parser.mode, () => {
+				const values = [];
+				const deferredIndices = /* @__PURE__ */ new Map();
+				let hasDeferred = false;
+				let hasAnySeed = false;
+				for (let i = 0; i < state.length; i++) {
+					const seed = extractPhase2SeedSyncWithUnwrappedFallback(state[i], withChildExecPath(exec, i));
+					if (seed == null) continue;
+					hasAnySeed = true;
+					values[i] = seed.value;
+					if (seed.deferred) if (seed.deferredKeys) deferredIndices.set(i, seed.deferredKeys);
+					else if (seed.value == null || typeof seed.value !== "object") deferredIndices.set(i, null);
+					else hasDeferred = true;
+				}
+				if (!hasAnySeed) return null;
+				return {
+					value: values,
+					...deferredIndices.size > 0 || hasDeferred ? {
+						deferred: true,
+						...deferredIndices.size > 0 ? { deferredKeys: deferredIndices } : {}
+					} : {}
+				};
+			}, async () => {
+				const values = [];
+				const deferredIndices = /* @__PURE__ */ new Map();
+				let hasDeferred = false;
+				let hasAnySeed = false;
+				for (let i = 0; i < state.length; i++) {
+					const seed = await extractPhase2SeedAsyncWithUnwrappedFallback(state[i], withChildExecPath(exec, i));
+					if (seed == null) continue;
+					hasAnySeed = true;
+					values[i] = seed.value;
+					if (seed.deferred) if (seed.deferredKeys) deferredIndices.set(i, seed.deferredKeys);
+					else if (seed.value == null || typeof seed.value !== "object") deferredIndices.set(i, null);
+					else hasDeferred = true;
+				}
+				if (!hasAnySeed) return null;
+				return {
+					value: values,
+					...deferredIndices.size > 0 || hasDeferred ? {
+						deferred: true,
+						...deferredIndices.size > 0 ? { deferredKeys: deferredIndices } : {}
+					} : {}
 				};
-				return validateMultipleResult(values);
 			});
 		},
 		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;
 			};
@@ -610,16 +1239,17 @@ function multiple(parser, options = {}) {
 					suggestion.type,
 					suggestion.pattern ?? "",
 					suggestion.includeHidden === true,
-					suggestion.extensions == null ? "" : suggestion.extensions.join("\0"),
+					suggestion.extensions == null ? "" : suggestion.extensions.toSorted().join("\0"),
 					description
 				]);
 			};
-			return dispatchIterableByMode(parser.$mode, function* () {
+			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;
 						}
@@ -627,24 +1257,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;
 						}
@@ -652,18 +1277,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) {
@@ -676,7 +1295,7 @@ function multiple(parser, options = {}) {
 			return syncParser.getDocFragments(innerState, defaultValue != null && defaultValue.length > 0 ? defaultValue[0] : void 0);
 		}
 	};
-	function validateMultipleResult(result) {
+	function validateMultipleResult(result, deferredIndices, hasDeferred = false) {
 		if (result.length < min) {
 			const customMessage = options.errors?.tooFew;
 			return {
@@ -690,10 +1309,139 @@ function multiple(parser, options = {}) {
 				error: customMessage ? typeof customMessage === "function" ? customMessage(max, result.length) : customMessage : message`Expected at most ${text(max.toLocaleString("en"))} values, but got ${text(result.length.toLocaleString("en"))}.`
 			};
 		}
+		const isDeferred = deferredIndices.size > 0 || hasDeferred;
 		return {
 			success: true,
-			value: result
+			value: result,
+			...isDeferred ? {
+				deferred: true,
+				...deferredIndices.size > 0 ? { deferredKeys: deferredIndices } : {}
+			} : {}
+		};
+	}
+	Object.defineProperty(resultParser, "placeholder", {
+		get() {
+			try {
+				if (min > 0 && "placeholder" in parser) return Array.from({ length: min }, () => parser.placeholder);
+			} catch {}
+			return [];
+		},
+		configurable: true,
+		enumerable: false
+	});
+	if (typeof parser.normalizeValue === "function") {
+		const innerNormalize = parser.normalizeValue.bind(parser);
+		Object.defineProperty(resultParser, "normalizeValue", {
+			value(values) {
+				if (!Array.isArray(values)) return values;
+				let changed = false;
+				const result = values.map((v) => {
+					try {
+						const n = innerNormalize(v);
+						if (n !== v) changed = true;
+						return n;
+					} catch {
+						return v;
+					}
+				});
+				return changed ? result : values;
+			},
+			configurable: true,
+			enumerable: false
+		});
+	}
+	{
+		const innerValidate = typeof parser.validateValue === "function" ? parser.validateValue.bind(parser) : void 0;
+		const validateArity = (values) => {
+			if (values.length < min) {
+				const customMessage = options.errors?.tooFew;
+				return {
+					success: false,
+					error: customMessage ? typeof customMessage === "function" ? customMessage(min, values.length) : customMessage : message`Expected at least ${text(min.toLocaleString("en"))} values, but got only ${text(values.length.toLocaleString("en"))}.`
+				};
+			}
+			if (values.length > max) {
+				const customMessage = options.errors?.tooMany;
+				return {
+					success: false,
+					error: customMessage ? typeof customMessage === "function" ? customMessage(max, values.length) : customMessage : message`Expected at most ${text(max.toLocaleString("en"))} values, but got ${text(values.length.toLocaleString("en"))}.`
+				};
+			}
+			return {
+				success: true,
+				value: values
+			};
 		};
+		Object.defineProperty(resultParser, "validateValue", {
+			value(values) {
+				if (!Array.isArray(values)) {
+					const actualType = values === null ? "null" : typeof values;
+					return wrapForMode(parser.mode, {
+						success: false,
+						error: message`Expected an array of values, but received ${actualType}.`
+					});
+				}
+				const arity = validateArity(values);
+				if (!arity.success) return wrapForMode(parser.mode, arity);
+				if (innerValidate == null) return wrapForMode(parser.mode, arity);
+				return dispatchByMode(parser.mode, () => {
+					let changed = false;
+					const normalized = [];
+					for (const v of values) {
+						const r = innerValidate(v);
+						if (!r.success) return r;
+						normalized.push(r.value);
+						if (r.value !== v) changed = true;
+					}
+					return {
+						success: true,
+						value: changed ? normalized : values
+					};
+				}, async () => {
+					let changed = false;
+					const normalized = [];
+					for (const v of values) {
+						const r = await innerValidate(v);
+						if (!r.success) return r;
+						normalized.push(r.value);
+						if (r.value !== v) changed = true;
+					}
+					return {
+						success: true,
+						value: changed ? normalized : values
+					};
+				});
+			},
+			configurable: true,
+			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;
 }
@@ -753,18 +1501,28 @@ function nonEmpty(parser) {
 		const result = await parser.parse(context);
 		return processNonEmptyResult(result);
 	};
-	return {
-		$mode: parser.$mode,
+	const nonEmptyParser = {
+		mode: parser.mode,
 		$valueType: parser.$valueType,
 		$stateType: parser.$stateType,
 		priority: parser.priority,
 		usage: parser.usage,
+		leadingNames: parser.leadingNames,
+		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));
+			return dispatchByMode(parser.mode, () => parseSync(context), () => parseAsync(context));
 		},
-		complete(state) {
-			return parser.complete(state);
+		complete(state, exec) {
+			return parser.complete(state, exec);
 		},
 		suggest(context, prefix) {
 			return parser.suggest(context, prefix);
@@ -773,6 +1531,31 @@ function nonEmpty(parser) {
 			return syncParser.getDocFragments(state, defaultValue);
 		}
 	};
+	if ("placeholder" in parser) Object.defineProperty(nonEmptyParser, "placeholder", {
+		get() {
+			return parser.placeholder;
+		},
+		configurable: true,
+		enumerable: false
+	});
+	Object.defineProperty(nonEmptyParser, extractPhase2SeedKey, {
+		value(state, exec) {
+			return extractPhase2Seed(parser, state, exec);
+		},
+		configurable: true,
+		enumerable: false
+	});
+	if (typeof parser.normalizeValue === "function") Object.defineProperty(nonEmptyParser, "normalizeValue", {
+		value: parser.normalizeValue.bind(parser),
+		configurable: true,
+		enumerable: false
+	});
+	if (typeof parser.validateValue === "function") Object.defineProperty(nonEmptyParser, "validateValue", {
+		value: parser.validateValue.bind(parser),
+		configurable: true,
+		enumerable: false
+	});
+	return nonEmptyParser;
 }
 
 //#endregion