@optique/inquirer 1.0.0-dev.921 → 1.0.1

package/README.md

@@ -9,7 +9,7 @@ when no CLI value is provided.  The fallback priority is:
 CLI arguments > interactive prompt.
 
 Because interactive prompts are inherently asynchronous, the returned parser
-always has `$mode: "async"`.
+always has `mode: "async"`.
 
 [Optique]: https://optique.dev/
 [Inquirer.js]: https://github.com/SBoudrias/Inquirer.js

package/dist/index.cjs

@@ -23,6 +23,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 //#endregion
 const __inquirer_prompts = __toESM(require("@inquirer/prompts"));
 const __optique_core_annotations = __toESM(require("@optique/core/annotations"));
+const __optique_core_extension = __toESM(require("@optique/core/extension"));
 const __optique_core_message = __toESM(require("@optique/core/message"));
 
 //#region src/index.ts
@@ -69,41 +70,34 @@ function getPromptFunctions() {
 function isExitPromptError(error) {
 	return typeof error === "object" && error != null && "name" in error && error.name === "ExitPromptError";
 }
-const deferredPromptValueKey = Symbol.for("@optique/inquirer/deferredPromptValue");
-const deferPromptUntilConfigResolvesKey = Symbol.for("@optique/config/deferPromptUntilResolved");
-const inheritParentAnnotationsKey = Symbol.for("@optique/core/inheritParentAnnotations");
-var DeferredPromptValue = class {
-	[deferredPromptValueKey] = true;
-};
-function shouldDeferPrompt(parser, state) {
-	const maybeShouldDefer = Reflect.get(parser, deferPromptUntilConfigResolvesKey);
-	return typeof maybeShouldDefer === "function" && maybeShouldDefer(state) === true;
+function shouldDeferPrompt(parser, state, exec) {
+	return typeof parser.shouldDeferCompletion === "function" && parser.shouldDeferCompletion(state, exec) === true;
 }
-function deferredPromptResult() {
+function deferredPromptResult(placeholderValue) {
+	if (placeholderValue == null || typeof placeholderValue !== "object") return {
+		success: true,
+		value: placeholderValue,
+		deferred: true
+	};
+	const isArray = Array.isArray(placeholderValue);
+	const keys = /* @__PURE__ */ new Map();
+	for (const key of Reflect.ownKeys(placeholderValue)) {
+		if (isArray && key === "length") continue;
+		keys.set(key, null);
+	}
 	return {
 		success: true,
-		value: new DeferredPromptValue()
+		value: placeholderValue,
+		deferred: true,
+		deferredKeys: keys
 	};
 }
-function withAnnotationView(state, annotations, run) {
-	const annotatedState = new Proxy(state, {
-		get(target, key) {
-			if (key === __optique_core_annotations.annotationKey) return annotations;
-			const value = Reflect.get(target, key, target);
-			return typeof value === "function" ? value.bind(target) : value;
-		},
-		has(target, key) {
-			return key === __optique_core_annotations.annotationKey || Reflect.has(target, key);
-		}
-	});
-	return run(annotatedState);
-}
 function withAnnotatedInnerState(sourceState, innerState, run) {
 	const annotations = (0, __optique_core_annotations.getAnnotations)(sourceState);
-	if (annotations == null || innerState == null || typeof innerState !== "object" || typeof innerState === "object" && __optique_core_annotations.annotationKey in innerState) return run(innerState);
-	const inheritedState = (0, __optique_core_annotations.inheritAnnotations)(sourceState, innerState);
+	if (annotations == null || innerState == null || typeof innerState !== "object" || (0, __optique_core_annotations.getAnnotations)(innerState) != null) return run(innerState);
+	const inheritedState = (0, __optique_core_extension.inheritAnnotations)(sourceState, innerState);
 	if (inheritedState !== innerState) return run(inheritedState);
-	return withAnnotationView(innerState, annotations, (annotatedState) => run(annotatedState));
+	return run((0, __optique_core_extension.withAnnotationView)(innerState, annotations));
 }
 /**
 * Wraps a parser with an interactive Inquirer.js prompt fallback.
@@ -112,7 +106,7 @@ function withAnnotatedInnerState(sourceState, innerState, run) {
 * that value is used directly. When no CLI value is found, an interactive
 * prompt is shown to the user.
 *
-* The returned parser always has `$mode: "async"` because Inquirer.js prompts
+* The returned parser always has `mode: "async"` because Inquirer.js prompts
 * are inherently asynchronous.
 *
 * Example:
@@ -141,21 +135,26 @@ function prompt(parser, config) {
 		return value != null && typeof value === "object" && promptBindStateKey in value;
 	}
 	const cfg = config;
-	const PromptBindInitialStateClass = class {
-		[promptBindStateKey] = true;
-		hasCliValue = false;
-	};
-	let promptCache = null;
 	function shouldAttemptInnerCompletion(cliState, state) {
-		if (cliState == null || cliState instanceof PromptBindInitialStateClass) return false;
-		const cliStateHasAnnotations = typeof cliState === "object" && __optique_core_annotations.annotationKey in cliState;
+		if (cliState == null) return false;
+		const cliStateHasAnnotations = (0, __optique_core_annotations.getAnnotations)(cliState) != null;
 		if (cliStateHasAnnotations) return true;
 		if ((0, __optique_core_annotations.getAnnotations)(state) == null || typeof cliState !== "object") return false;
 		if ("hasCliValue" in cliState) return true;
-		if (Array.isArray(cliState)) return typeof Reflect.get(parser, deferPromptUntilConfigResolvesKey) === "function";
+		if (Array.isArray(cliState)) return typeof parser.shouldDeferCompletion === "function";
 		const prototype = Object.getPrototypeOf(cliState);
 		return prototype !== Object.prototype && prototype !== null;
 	}
+	function hasSourceBindingMarker(state) {
+		return state != null && typeof state === "object" && "hasCliValue" in state && Object.getOwnPropertySymbols(state).length > 0;
+	}
+	function shouldCompleteFromSourceBinding(cliState, state) {
+		const cliStateIsInjectedAnnotationWrapper = cliState != null && typeof cliState === "object" && (0, __optique_core_extension.unwrapInjectedAnnotationState)(cliState) !== cliState;
+		const requiresSourceBindingForAnnotationWrapper = (0, __optique_core_extension.getTraits)(parser).requiresSourceBinding === true;
+		const hasNestedSourceBinding = hasSourceBindingMarker(cliState) || Array.isArray(cliState) && cliState.length === 1 && (hasSourceBindingMarker(cliState[0]) || cliState[0] != null && typeof cliState[0] === "object" && (0, __optique_core_annotations.getAnnotations)(cliState[0]) != null);
+		if (cliStateIsInjectedAnnotationWrapper && requiresSourceBindingForAnnotationWrapper) return hasNestedSourceBinding;
+		return shouldAttemptInnerCompletion(cliState, state) || hasNestedSourceBinding;
+	}
 	/**
 	* Executes the configured prompt and normalizes its result.
 	*
@@ -166,9 +165,24 @@ function prompt(parser, config) {
 	* @throws {Error} Rethrows unexpected prompt failures after converting
 	*                 `ExitPromptError` cancellations into parse failures.
 	*/
-	async function executePrompt() {
+	function validatePromptedValue(result) {
+		return result;
+	}
+	const validPromptTypes = new Set([
+		"confirm",
+		"number",
+		"input",
+		"password",
+		"editor",
+		"select",
+		"rawlist",
+		"expand",
+		"checkbox"
+	]);
+	async function executePromptRaw() {
 		const prompts = getPromptFunctions();
 		try {
+			if (!validPromptTypes.has(cfg.type)) throw new TypeError(`Unsupported prompt type: ${cfg.type}`);
 			if ("prompter" in cfg && cfg.prompter != null) {
 				const value = await cfg.prompter();
 				if (cfg.type === "number" && value === void 0) return {
@@ -269,22 +283,31 @@ function prompt(parser, config) {
 			throw error;
 		}
 	}
-	function usePromptOrDefer(state, result) {
-		if (result.success) return Promise.resolve(result);
-		return shouldDeferPrompt(parser, state) ? Promise.resolve(deferredPromptResult()) : executePrompt();
+	async function executePrompt() {
+		const result = await executePromptRaw();
+		return validatePromptedValue(result);
 	}
 	const promptedParser = {
-		$mode: "async",
+		mode: "async",
 		$valueType: parser.$valueType,
 		$stateType: parser.$stateType,
 		priority: parser.priority,
-		[inheritParentAnnotationsKey]: true,
-		usage: [{
+		usage: parser.usage.length === 1 && parser.usage[0].type === "optional" ? parser.usage : [{
 			type: "optional",
 			terms: parser.usage
 		}],
-		get initialState() {
-			return new PromptBindInitialStateClass();
+		leadingNames: parser.leadingNames,
+		acceptingAnyToken: parser.acceptingAnyToken,
+		shouldDeferCompletion(state) {
+			return !isPromptBindState(state) || !state.hasCliValue;
+		},
+		getSuggestRuntimeNodes(state, path) {
+			const innerState = isPromptBindState(state) ? state.cliState === void 0 ? parser.initialState : state.cliState : state;
+			return (0, __optique_core_extension.delegateSuggestNodes)(parser, promptedParser, state, path, innerState, "prepend");
+		},
+		initialState: {
+			[promptBindStateKey]: true,
+			hasCliValue: false
 		},
 		parse: (context) => {
 			const annotations = (0, __optique_core_annotations.getAnnotations)(context.state);
@@ -293,17 +316,19 @@ function prompt(parser, config) {
 				...context,
 				state: innerState
 			} : context;
+			const effectiveInnerState = annotations != null && innerState == null && (0, __optique_core_extension.getTraits)(parser).inheritsAnnotations === true ? (0, __optique_core_extension.injectAnnotations)(innerState, annotations) : innerState;
 			const processResult = (result$1) => {
 				if (result$1.success) {
+					const cliState = annotations != null && result$1.next.state != null && typeof result$1.next.state === "object" && (0, __optique_core_annotations.getAnnotations)(result$1.next.state) !== annotations ? (0, __optique_core_extension.injectAnnotations)(result$1.next.state, annotations) : result$1.next.state;
 					const cliConsumed = result$1.consumed.length > 0;
-					const nextState$1 = {
+					const nextState$1 = (0, __optique_core_extension.injectAnnotations)({
 						[promptBindStateKey]: true,
 						hasCliValue: cliConsumed,
-						cliState: result$1.next.state,
-						...annotations != null ? { [__optique_core_annotations.annotationKey]: annotations } : {}
-					};
+						cliState
+					}, annotations);
 					return {
 						success: true,
+						...result$1.provisional ? { provisional: true } : {},
 						next: {
 							...result$1.next,
 							state: nextState$1
@@ -312,11 +337,10 @@ function prompt(parser, config) {
 					};
 				}
 				if (result$1.consumed > 0) return result$1;
-				const nextState = {
+				const nextState = (0, __optique_core_extension.injectAnnotations)({
 					[promptBindStateKey]: true,
-					hasCliValue: false,
-					...annotations != null ? { [__optique_core_annotations.annotationKey]: annotations } : {}
-				};
+					hasCliValue: false
+				}, annotations);
 				return {
 					success: true,
 					next: {
@@ -326,7 +350,7 @@ function prompt(parser, config) {
 					consumed: []
 				};
 			};
-			const result = withAnnotatedInnerState(context.state, innerState, (annotatedInnerState) => {
+			const result = withAnnotatedInnerState(context.state, effectiveInnerState, (annotatedInnerState) => {
 				const innerContext = annotatedInnerState !== context.state ? {
 					...context,
 					state: annotatedInnerState
@@ -336,85 +360,71 @@ function prompt(parser, config) {
 			if (result instanceof Promise) return result.then(processResult);
 			return Promise.resolve(processResult(result));
 		},
-		complete: (state) => {
+		complete: (state, exec) => {
 			if (isPromptBindState(state) && state.hasCliValue) {
-				const r = withAnnotatedInnerState(state, state.cliState, (annotatedInnerState) => parser.complete(annotatedInnerState));
+				const r = withAnnotatedInnerState(state, state.cliState, (annotatedInnerState) => parser.complete(annotatedInnerState, exec));
 				if (r instanceof Promise) return r;
 				return Promise.resolve(r);
 			}
-			if (state instanceof PromptBindInitialStateClass) {
-				if (promptCache?.state === state) {
-					const cached = promptCache.result;
-					promptCache = null;
-					return cached;
+			const isProbe = exec != null && exec.phase !== "complete";
+			const annotations = (0, __optique_core_annotations.getAnnotations)(state);
+			const innerInitialState = parser.initialState;
+			const shouldInheritInitialStateAnnotations = annotations != null && (innerInitialState == null || typeof innerInitialState === "object");
+			const effectiveInitialState = shouldInheritInitialStateAnnotations ? (0, __optique_core_extension.inheritAnnotations)(state, innerInitialState) : innerInitialState;
+			const readPlaceholder = () => {
+				try {
+					return "placeholder" in parser ? parser.placeholder : void 0;
+				} catch {
+					return void 0;
 				}
-				const hasDeferHook = typeof Reflect.get(parser, deferPromptUntilConfigResolvesKey) === "function";
-				const annotations = (0, __optique_core_annotations.getAnnotations)(state);
-				const innerInitialState = parser.initialState;
-				const effectiveInitialState = annotations != null && innerInitialState == null ? (0, __optique_core_annotations.injectAnnotations)(innerInitialState, annotations) : innerInitialState;
-				if (hasDeferHook) {
-					const annotatedR = withAnnotatedInnerState(state, effectiveInitialState, (annotatedInnerState) => parser.complete(annotatedInnerState));
-					const usePromptOrDeferSentinel = (res) => {
-						if (res.success && res.value === void 0) return usePromptOrDefer(state, {
-							success: false,
-							error: []
-						});
-						return usePromptOrDefer(state, res);
-					};
-					const cachedResult$1 = annotatedR instanceof Promise ? annotatedR.then(usePromptOrDeferSentinel) : usePromptOrDeferSentinel(annotatedR);
-					promptCache = {
-						state,
-						result: cachedResult$1
-					};
-					return cachedResult$1;
-				}
-				const simParseR = withAnnotatedInnerState(state, effectiveInitialState, (annotatedState) => parser.parse({
-					buffer: [],
-					state: annotatedState,
-					optionsTerminated: false,
-					usage: parser.usage
-				}));
-				const decideFromParse = (parseResult) => {
-					const consumed = parseResult.success ? parseResult.consumed.length : 0;
-					const cliState$1 = parseResult.success && consumed === 0 ? parseResult.next.state : void 0;
-					const hasSourceBindingMarker = (s) => s != null && typeof s === "object" && "hasCliValue" in s && Object.getOwnPropertySymbols(s).length > 0;
-					const cliStateIsPassthrough = cliState$1 != null && typeof cliState$1 === "object" && (0, __optique_core_annotations.unwrapInjectedAnnotationWrapper)(cliState$1) !== cliState$1;
-					const isSourceBinding = shouldAttemptInnerCompletion(cliState$1, state) && !cliStateIsPassthrough || hasSourceBindingMarker(cliState$1) || Array.isArray(cliState$1) && cliState$1.length === 1 && (hasSourceBindingMarker(cliState$1[0]) || typeof cliState$1[0] === "object" && cliState$1[0] != null && __optique_core_annotations.annotationKey in cliState$1[0]);
-					if (isSourceBinding) {
-						const cliStateIsInjected = cliState$1 != null && typeof cliState$1 === "object" && (0, __optique_core_annotations.unwrapInjectedAnnotationWrapper)(cliState$1) !== cliState$1;
-						const handleCompleteResult = (res) => {
-							if (res.success && res.value === void 0 && cliStateIsInjected) return executePrompt();
-							return usePromptOrDefer(state, res);
-						};
-						const completeState = parseResult.success ? parseResult.next.state : effectiveInitialState;
-						const completeR = parser.complete(completeState);
-						if (completeR instanceof Promise) return completeR.then(handleCompleteResult);
-						return handleCompleteResult(completeR);
-					}
-					return executePrompt();
-				};
-				const cachedResult = simParseR instanceof Promise ? simParseR.then(decideFromParse) : decideFromParse(simParseR);
-				promptCache = {
-					state,
-					result: cachedResult
+			};
+			const finalizePrompt = () => {
+				const shouldDefer = withAnnotatedInnerState(state, effectiveInitialState, (annotatedInnerState) => shouldDeferPrompt(parser, annotatedInnerState, exec));
+				if (shouldDefer) return Promise.resolve(deferredPromptResult(readPlaceholder()));
+				if (isProbe) return Promise.resolve({
+					success: true,
+					value: readPlaceholder()
+				});
+				return executePrompt();
+			};
+			const hasDeferHook = typeof parser.shouldDeferCompletion === "function";
+			const decideFromParse = (parseResult) => {
+				const consumed = parseResult.success ? parseResult.consumed.length : 0;
+				const cliState = parseResult.success && consumed === 0 ? parseResult.next.state : void 0;
+				const cliStateIsInjected = cliState != null && typeof cliState === "object" && (0, __optique_core_extension.unwrapInjectedAnnotationState)(cliState) !== cliState;
+				const isSourceBinding = shouldCompleteFromSourceBinding(cliState, state);
+				if (!isSourceBinding) return finalizePrompt();
+				const completeState = parseResult.success ? parseResult.next.state : effectiveInitialState;
+				const innerR = parser.complete(completeState, exec);
+				const handleCompleteResult = (res) => {
+					if (res.success && res.value === void 0 && cliStateIsInjected) return finalizePrompt();
+					if (!res.success) return finalizePrompt();
+					return Promise.resolve(res);
 				};
-				return cachedResult;
-			}
-			const cliState = isPromptBindState(state) ? state.cliState : void 0;
-			const cliStateIsInjectedAnnotationWrapper = cliState != null && typeof cliState === "object" && (0, __optique_core_annotations.unwrapInjectedAnnotationWrapper)(cliState) !== cliState;
-			if (shouldAttemptInnerCompletion(cliState, state)) {
-				const useCompleteResultOrPrompt = (result) => {
-					if (result.success && result.value === void 0 && cliStateIsInjectedAnnotationWrapper) return executePrompt();
-					return usePromptOrDefer(state, result);
+				if (innerR instanceof Promise) return innerR.then(handleCompleteResult);
+				return handleCompleteResult(innerR);
+			};
+			if (hasDeferHook) {
+				const innerR = withAnnotatedInnerState(state, effectiveInitialState, (annotatedInnerState) => parser.complete(annotatedInnerState, exec));
+				const handleDeferHookResult = (res) => {
+					if (res.success && res.value === void 0) return finalizePrompt();
+					if (!res.success) return finalizePrompt();
+					return Promise.resolve(res);
 				};
-				const r = withAnnotatedInnerState(state, cliState, (annotatedInnerState) => parser.complete(annotatedInnerState));
-				if (r instanceof Promise) return r.then(useCompleteResultOrPrompt);
-				return useCompleteResultOrPrompt(r);
+				if (innerR instanceof Promise) return innerR.then(handleDeferHookResult);
+				return handleDeferHookResult(innerR);
 			}
-			return shouldDeferPrompt(parser, state) ? Promise.resolve(deferredPromptResult()) : executePrompt();
+			const simParseR = withAnnotatedInnerState(state, effectiveInitialState, (annotatedState) => parser.parse({
+				buffer: [],
+				state: annotatedState,
+				optionsTerminated: false,
+				usage: parser.usage
+			}));
+			if (simParseR instanceof Promise) return simParseR.then(decideFromParse);
+			return decideFromParse(simParseR);
 		},
 		suggest: (context, prefix) => {
-			const innerState = isPromptBindState(context.state) ? context.state.hasCliValue ? context.state.cliState : parser.initialState : context.state;
+			const innerState = isPromptBindState(context.state) ? context.state.cliState === void 0 ? parser.initialState : context.state.cliState : context.state;
 			const innerContext = innerState !== context.state ? {
 				...context,
 				state: innerState
@@ -430,6 +440,35 @@ function prompt(parser, config) {
 			return parser.getDocFragments(state, defaultValue);
 		}
 	};
+	(0, __optique_core_extension.defineTraits)(promptedParser, { inheritsAnnotations: true });
+	if ("placeholder" in parser) Object.defineProperty(promptedParser, "placeholder", {
+		get() {
+			try {
+				return parser.placeholder;
+			} catch {
+				return void 0;
+			}
+		},
+		configurable: true,
+		enumerable: false
+	});
+	if (typeof parser.normalizeValue === "function") Object.defineProperty(promptedParser, "normalizeValue", {
+		value: parser.normalizeValue.bind(parser),
+		configurable: true,
+		enumerable: false
+	});
+	const dependencyMetadata = (0, __optique_core_extension.mapSourceMetadata)(parser, (source) => ({
+		...source,
+		extractSourceValue: (state) => {
+			if (!isPromptBindState(state)) return source.extractSourceValue(state);
+			return source.extractSourceValue(state.cliState ?? state);
+		}
+	}));
+	if (dependencyMetadata != null) Object.defineProperty(promptedParser, "dependencyMetadata", {
+		value: dependencyMetadata,
+		configurable: true,
+		enumerable: false
+	});
 	return promptedParser;
 }
 /** Normalize choices to the format Inquirer.js expects. */

package/dist/index.d.cts

@@ -328,7 +328,7 @@ type BasePromptConfig<T> = T extends boolean ? ConfirmConfig : T extends number
  * that value is used directly. When no CLI value is found, an interactive
  * prompt is shown to the user.
  *
- * The returned parser always has `$mode: "async"` because Inquirer.js prompts
+ * The returned parser always has `mode: "async"` because Inquirer.js prompts
  * are inherently asynchronous.
  *
  * Example:

package/dist/index.d.ts

@@ -328,7 +328,7 @@ type BasePromptConfig<T> = T extends boolean ? ConfirmConfig : T extends number
  * that value is used directly. When no CLI value is found, an interactive
  * prompt is shown to the user.
  *
- * The returned parser always has `$mode: "async"` because Inquirer.js prompts
+ * The returned parser always has `mode: "async"` because Inquirer.js prompts
  * are inherently asynchronous.
  *
  * Example:

package/dist/index.js

@@ -1,5 +1,6 @@
 import { Separator, checkbox, confirm, editor, expand, input, number, password, rawlist, select } from "@inquirer/prompts";
-import { annotationKey, getAnnotations, inheritAnnotations, injectAnnotations, unwrapInjectedAnnotationWrapper } from "@optique/core/annotations";
+import { getAnnotations } from "@optique/core/annotations";
+import { defineTraits, delegateSuggestNodes, getTraits, inheritAnnotations, injectAnnotations, mapSourceMetadata, unwrapInjectedAnnotationState, withAnnotationView } from "@optique/core/extension";
 import { message } from "@optique/core/message";
 
 //#region src/index.ts
@@ -46,41 +47,34 @@ function getPromptFunctions() {
 function isExitPromptError(error) {
 	return typeof error === "object" && error != null && "name" in error && error.name === "ExitPromptError";
 }
-const deferredPromptValueKey = Symbol.for("@optique/inquirer/deferredPromptValue");
-const deferPromptUntilConfigResolvesKey = Symbol.for("@optique/config/deferPromptUntilResolved");
-const inheritParentAnnotationsKey = Symbol.for("@optique/core/inheritParentAnnotations");
-var DeferredPromptValue = class {
-	[deferredPromptValueKey] = true;
-};
-function shouldDeferPrompt(parser, state) {
-	const maybeShouldDefer = Reflect.get(parser, deferPromptUntilConfigResolvesKey);
-	return typeof maybeShouldDefer === "function" && maybeShouldDefer(state) === true;
+function shouldDeferPrompt(parser, state, exec) {
+	return typeof parser.shouldDeferCompletion === "function" && parser.shouldDeferCompletion(state, exec) === true;
 }
-function deferredPromptResult() {
+function deferredPromptResult(placeholderValue) {
+	if (placeholderValue == null || typeof placeholderValue !== "object") return {
+		success: true,
+		value: placeholderValue,
+		deferred: true
+	};
+	const isArray = Array.isArray(placeholderValue);
+	const keys = /* @__PURE__ */ new Map();
+	for (const key of Reflect.ownKeys(placeholderValue)) {
+		if (isArray && key === "length") continue;
+		keys.set(key, null);
+	}
 	return {
 		success: true,
-		value: new DeferredPromptValue()
+		value: placeholderValue,
+		deferred: true,
+		deferredKeys: keys
 	};
 }
-function withAnnotationView(state, annotations, run) {
-	const annotatedState = new Proxy(state, {
-		get(target, key) {
-			if (key === annotationKey) return annotations;
-			const value = Reflect.get(target, key, target);
-			return typeof value === "function" ? value.bind(target) : value;
-		},
-		has(target, key) {
-			return key === annotationKey || Reflect.has(target, key);
-		}
-	});
-	return run(annotatedState);
-}
 function withAnnotatedInnerState(sourceState, innerState, run) {
 	const annotations = getAnnotations(sourceState);
-	if (annotations == null || innerState == null || typeof innerState !== "object" || typeof innerState === "object" && annotationKey in innerState) return run(innerState);
+	if (annotations == null || innerState == null || typeof innerState !== "object" || getAnnotations(innerState) != null) return run(innerState);
 	const inheritedState = inheritAnnotations(sourceState, innerState);
 	if (inheritedState !== innerState) return run(inheritedState);
-	return withAnnotationView(innerState, annotations, (annotatedState) => run(annotatedState));
+	return run(withAnnotationView(innerState, annotations));
 }
 /**
 * Wraps a parser with an interactive Inquirer.js prompt fallback.
@@ -89,7 +83,7 @@ function withAnnotatedInnerState(sourceState, innerState, run) {
 * that value is used directly. When no CLI value is found, an interactive
 * prompt is shown to the user.
 *
-* The returned parser always has `$mode: "async"` because Inquirer.js prompts
+* The returned parser always has `mode: "async"` because Inquirer.js prompts
 * are inherently asynchronous.
 *
 * Example:
@@ -118,21 +112,26 @@ function prompt(parser, config) {
 		return value != null && typeof value === "object" && promptBindStateKey in value;
 	}
 	const cfg = config;
-	const PromptBindInitialStateClass = class {
-		[promptBindStateKey] = true;
-		hasCliValue = false;
-	};
-	let promptCache = null;
 	function shouldAttemptInnerCompletion(cliState, state) {
-		if (cliState == null || cliState instanceof PromptBindInitialStateClass) return false;
-		const cliStateHasAnnotations = typeof cliState === "object" && annotationKey in cliState;
+		if (cliState == null) return false;
+		const cliStateHasAnnotations = getAnnotations(cliState) != null;
 		if (cliStateHasAnnotations) return true;
 		if (getAnnotations(state) == null || typeof cliState !== "object") return false;
 		if ("hasCliValue" in cliState) return true;
-		if (Array.isArray(cliState)) return typeof Reflect.get(parser, deferPromptUntilConfigResolvesKey) === "function";
+		if (Array.isArray(cliState)) return typeof parser.shouldDeferCompletion === "function";
 		const prototype = Object.getPrototypeOf(cliState);
 		return prototype !== Object.prototype && prototype !== null;
 	}
+	function hasSourceBindingMarker(state) {
+		return state != null && typeof state === "object" && "hasCliValue" in state && Object.getOwnPropertySymbols(state).length > 0;
+	}
+	function shouldCompleteFromSourceBinding(cliState, state) {
+		const cliStateIsInjectedAnnotationWrapper = cliState != null && typeof cliState === "object" && unwrapInjectedAnnotationState(cliState) !== cliState;
+		const requiresSourceBindingForAnnotationWrapper = getTraits(parser).requiresSourceBinding === true;
+		const hasNestedSourceBinding = hasSourceBindingMarker(cliState) || Array.isArray(cliState) && cliState.length === 1 && (hasSourceBindingMarker(cliState[0]) || cliState[0] != null && typeof cliState[0] === "object" && getAnnotations(cliState[0]) != null);
+		if (cliStateIsInjectedAnnotationWrapper && requiresSourceBindingForAnnotationWrapper) return hasNestedSourceBinding;
+		return shouldAttemptInnerCompletion(cliState, state) || hasNestedSourceBinding;
+	}
 	/**
 	* Executes the configured prompt and normalizes its result.
 	*
@@ -143,9 +142,24 @@ function prompt(parser, config) {
 	* @throws {Error} Rethrows unexpected prompt failures after converting
 	*                 `ExitPromptError` cancellations into parse failures.
 	*/
-	async function executePrompt() {
+	function validatePromptedValue(result) {
+		return result;
+	}
+	const validPromptTypes = new Set([
+		"confirm",
+		"number",
+		"input",
+		"password",
+		"editor",
+		"select",
+		"rawlist",
+		"expand",
+		"checkbox"
+	]);
+	async function executePromptRaw() {
 		const prompts = getPromptFunctions();
 		try {
+			if (!validPromptTypes.has(cfg.type)) throw new TypeError(`Unsupported prompt type: ${cfg.type}`);
 			if ("prompter" in cfg && cfg.prompter != null) {
 				const value = await cfg.prompter();
 				if (cfg.type === "number" && value === void 0) return {
@@ -246,22 +260,31 @@ function prompt(parser, config) {
 			throw error;
 		}
 	}
-	function usePromptOrDefer(state, result) {
-		if (result.success) return Promise.resolve(result);
-		return shouldDeferPrompt(parser, state) ? Promise.resolve(deferredPromptResult()) : executePrompt();
+	async function executePrompt() {
+		const result = await executePromptRaw();
+		return validatePromptedValue(result);
 	}
 	const promptedParser = {
-		$mode: "async",
+		mode: "async",
 		$valueType: parser.$valueType,
 		$stateType: parser.$stateType,
 		priority: parser.priority,
-		[inheritParentAnnotationsKey]: true,
-		usage: [{
+		usage: parser.usage.length === 1 && parser.usage[0].type === "optional" ? parser.usage : [{
 			type: "optional",
 			terms: parser.usage
 		}],
-		get initialState() {
-			return new PromptBindInitialStateClass();
+		leadingNames: parser.leadingNames,
+		acceptingAnyToken: parser.acceptingAnyToken,
+		shouldDeferCompletion(state) {
+			return !isPromptBindState(state) || !state.hasCliValue;
+		},
+		getSuggestRuntimeNodes(state, path) {
+			const innerState = isPromptBindState(state) ? state.cliState === void 0 ? parser.initialState : state.cliState : state;
+			return delegateSuggestNodes(parser, promptedParser, state, path, innerState, "prepend");
+		},
+		initialState: {
+			[promptBindStateKey]: true,
+			hasCliValue: false
 		},
 		parse: (context) => {
 			const annotations = getAnnotations(context.state);
@@ -270,17 +293,19 @@ function prompt(parser, config) {
 				...context,
 				state: innerState
 			} : context;
+			const effectiveInnerState = annotations != null && innerState == null && getTraits(parser).inheritsAnnotations === true ? injectAnnotations(innerState, annotations) : innerState;
 			const processResult = (result$1) => {
 				if (result$1.success) {
+					const cliState = annotations != null && result$1.next.state != null && typeof result$1.next.state === "object" && getAnnotations(result$1.next.state) !== annotations ? injectAnnotations(result$1.next.state, annotations) : result$1.next.state;
 					const cliConsumed = result$1.consumed.length > 0;
-					const nextState$1 = {
+					const nextState$1 = injectAnnotations({
 						[promptBindStateKey]: true,
 						hasCliValue: cliConsumed,
-						cliState: result$1.next.state,
-						...annotations != null ? { [annotationKey]: annotations } : {}
-					};
+						cliState
+					}, annotations);
 					return {
 						success: true,
+						...result$1.provisional ? { provisional: true } : {},
 						next: {
 							...result$1.next,
 							state: nextState$1
@@ -289,11 +314,10 @@ function prompt(parser, config) {
 					};
 				}
 				if (result$1.consumed > 0) return result$1;
-				const nextState = {
+				const nextState = injectAnnotations({
 					[promptBindStateKey]: true,
-					hasCliValue: false,
-					...annotations != null ? { [annotationKey]: annotations } : {}
-				};
+					hasCliValue: false
+				}, annotations);
 				return {
 					success: true,
 					next: {
@@ -303,7 +327,7 @@ function prompt(parser, config) {
 					consumed: []
 				};
 			};
-			const result = withAnnotatedInnerState(context.state, innerState, (annotatedInnerState) => {
+			const result = withAnnotatedInnerState(context.state, effectiveInnerState, (annotatedInnerState) => {
 				const innerContext = annotatedInnerState !== context.state ? {
 					...context,
 					state: annotatedInnerState
@@ -313,85 +337,71 @@ function prompt(parser, config) {
 			if (result instanceof Promise) return result.then(processResult);
 			return Promise.resolve(processResult(result));
 		},
-		complete: (state) => {
+		complete: (state, exec) => {
 			if (isPromptBindState(state) && state.hasCliValue) {
-				const r = withAnnotatedInnerState(state, state.cliState, (annotatedInnerState) => parser.complete(annotatedInnerState));
+				const r = withAnnotatedInnerState(state, state.cliState, (annotatedInnerState) => parser.complete(annotatedInnerState, exec));
 				if (r instanceof Promise) return r;
 				return Promise.resolve(r);
 			}
-			if (state instanceof PromptBindInitialStateClass) {
-				if (promptCache?.state === state) {
-					const cached = promptCache.result;
-					promptCache = null;
-					return cached;
+			const isProbe = exec != null && exec.phase !== "complete";
+			const annotations = getAnnotations(state);
+			const innerInitialState = parser.initialState;
+			const shouldInheritInitialStateAnnotations = annotations != null && (innerInitialState == null || typeof innerInitialState === "object");
+			const effectiveInitialState = shouldInheritInitialStateAnnotations ? inheritAnnotations(state, innerInitialState) : innerInitialState;
+			const readPlaceholder = () => {
+				try {
+					return "placeholder" in parser ? parser.placeholder : void 0;
+				} catch {
+					return void 0;
 				}
-				const hasDeferHook = typeof Reflect.get(parser, deferPromptUntilConfigResolvesKey) === "function";
-				const annotations = getAnnotations(state);
-				const innerInitialState = parser.initialState;
-				const effectiveInitialState = annotations != null && innerInitialState == null ? injectAnnotations(innerInitialState, annotations) : innerInitialState;
-				if (hasDeferHook) {
-					const annotatedR = withAnnotatedInnerState(state, effectiveInitialState, (annotatedInnerState) => parser.complete(annotatedInnerState));
-					const usePromptOrDeferSentinel = (res) => {
-						if (res.success && res.value === void 0) return usePromptOrDefer(state, {
-							success: false,
-							error: []
-						});
-						return usePromptOrDefer(state, res);
-					};
-					const cachedResult$1 = annotatedR instanceof Promise ? annotatedR.then(usePromptOrDeferSentinel) : usePromptOrDeferSentinel(annotatedR);
-					promptCache = {
-						state,
-						result: cachedResult$1
-					};
-					return cachedResult$1;
-				}
-				const simParseR = withAnnotatedInnerState(state, effectiveInitialState, (annotatedState) => parser.parse({
-					buffer: [],
-					state: annotatedState,
-					optionsTerminated: false,
-					usage: parser.usage
-				}));
-				const decideFromParse = (parseResult) => {
-					const consumed = parseResult.success ? parseResult.consumed.length : 0;
-					const cliState$1 = parseResult.success && consumed === 0 ? parseResult.next.state : void 0;
-					const hasSourceBindingMarker = (s) => s != null && typeof s === "object" && "hasCliValue" in s && Object.getOwnPropertySymbols(s).length > 0;
-					const cliStateIsPassthrough = cliState$1 != null && typeof cliState$1 === "object" && unwrapInjectedAnnotationWrapper(cliState$1) !== cliState$1;
-					const isSourceBinding = shouldAttemptInnerCompletion(cliState$1, state) && !cliStateIsPassthrough || hasSourceBindingMarker(cliState$1) || Array.isArray(cliState$1) && cliState$1.length === 1 && (hasSourceBindingMarker(cliState$1[0]) || typeof cliState$1[0] === "object" && cliState$1[0] != null && annotationKey in cliState$1[0]);
-					if (isSourceBinding) {
-						const cliStateIsInjected = cliState$1 != null && typeof cliState$1 === "object" && unwrapInjectedAnnotationWrapper(cliState$1) !== cliState$1;
-						const handleCompleteResult = (res) => {
-							if (res.success && res.value === void 0 && cliStateIsInjected) return executePrompt();
-							return usePromptOrDefer(state, res);
-						};
-						const completeState = parseResult.success ? parseResult.next.state : effectiveInitialState;
-						const completeR = parser.complete(completeState);
-						if (completeR instanceof Promise) return completeR.then(handleCompleteResult);
-						return handleCompleteResult(completeR);
-					}
-					return executePrompt();
-				};
-				const cachedResult = simParseR instanceof Promise ? simParseR.then(decideFromParse) : decideFromParse(simParseR);
-				promptCache = {
-					state,
-					result: cachedResult
+			};
+			const finalizePrompt = () => {
+				const shouldDefer = withAnnotatedInnerState(state, effectiveInitialState, (annotatedInnerState) => shouldDeferPrompt(parser, annotatedInnerState, exec));
+				if (shouldDefer) return Promise.resolve(deferredPromptResult(readPlaceholder()));
+				if (isProbe) return Promise.resolve({
+					success: true,
+					value: readPlaceholder()
+				});
+				return executePrompt();
+			};
+			const hasDeferHook = typeof parser.shouldDeferCompletion === "function";
+			const decideFromParse = (parseResult) => {
+				const consumed = parseResult.success ? parseResult.consumed.length : 0;
+				const cliState = parseResult.success && consumed === 0 ? parseResult.next.state : void 0;
+				const cliStateIsInjected = cliState != null && typeof cliState === "object" && unwrapInjectedAnnotationState(cliState) !== cliState;
+				const isSourceBinding = shouldCompleteFromSourceBinding(cliState, state);
+				if (!isSourceBinding) return finalizePrompt();
+				const completeState = parseResult.success ? parseResult.next.state : effectiveInitialState;
+				const innerR = parser.complete(completeState, exec);
+				const handleCompleteResult = (res) => {
+					if (res.success && res.value === void 0 && cliStateIsInjected) return finalizePrompt();
+					if (!res.success) return finalizePrompt();
+					return Promise.resolve(res);
 				};
-				return cachedResult;
-			}
-			const cliState = isPromptBindState(state) ? state.cliState : void 0;
-			const cliStateIsInjectedAnnotationWrapper = cliState != null && typeof cliState === "object" && unwrapInjectedAnnotationWrapper(cliState) !== cliState;
-			if (shouldAttemptInnerCompletion(cliState, state)) {
-				const useCompleteResultOrPrompt = (result) => {
-					if (result.success && result.value === void 0 && cliStateIsInjectedAnnotationWrapper) return executePrompt();
-					return usePromptOrDefer(state, result);
+				if (innerR instanceof Promise) return innerR.then(handleCompleteResult);
+				return handleCompleteResult(innerR);
+			};
+			if (hasDeferHook) {
+				const innerR = withAnnotatedInnerState(state, effectiveInitialState, (annotatedInnerState) => parser.complete(annotatedInnerState, exec));
+				const handleDeferHookResult = (res) => {
+					if (res.success && res.value === void 0) return finalizePrompt();
+					if (!res.success) return finalizePrompt();
+					return Promise.resolve(res);
 				};
-				const r = withAnnotatedInnerState(state, cliState, (annotatedInnerState) => parser.complete(annotatedInnerState));
-				if (r instanceof Promise) return r.then(useCompleteResultOrPrompt);
-				return useCompleteResultOrPrompt(r);
+				if (innerR instanceof Promise) return innerR.then(handleDeferHookResult);
+				return handleDeferHookResult(innerR);
 			}
-			return shouldDeferPrompt(parser, state) ? Promise.resolve(deferredPromptResult()) : executePrompt();
+			const simParseR = withAnnotatedInnerState(state, effectiveInitialState, (annotatedState) => parser.parse({
+				buffer: [],
+				state: annotatedState,
+				optionsTerminated: false,
+				usage: parser.usage
+			}));
+			if (simParseR instanceof Promise) return simParseR.then(decideFromParse);
+			return decideFromParse(simParseR);
 		},
 		suggest: (context, prefix) => {
-			const innerState = isPromptBindState(context.state) ? context.state.hasCliValue ? context.state.cliState : parser.initialState : context.state;
+			const innerState = isPromptBindState(context.state) ? context.state.cliState === void 0 ? parser.initialState : context.state.cliState : context.state;
 			const innerContext = innerState !== context.state ? {
 				...context,
 				state: innerState
@@ -407,6 +417,35 @@ function prompt(parser, config) {
 			return parser.getDocFragments(state, defaultValue);
 		}
 	};
+	defineTraits(promptedParser, { inheritsAnnotations: true });
+	if ("placeholder" in parser) Object.defineProperty(promptedParser, "placeholder", {
+		get() {
+			try {
+				return parser.placeholder;
+			} catch {
+				return void 0;
+			}
+		},
+		configurable: true,
+		enumerable: false
+	});
+	if (typeof parser.normalizeValue === "function") Object.defineProperty(promptedParser, "normalizeValue", {
+		value: parser.normalizeValue.bind(parser),
+		configurable: true,
+		enumerable: false
+	});
+	const dependencyMetadata = mapSourceMetadata(parser, (source) => ({
+		...source,
+		extractSourceValue: (state) => {
+			if (!isPromptBindState(state)) return source.extractSourceValue(state);
+			return source.extractSourceValue(state.cliState ?? state);
+		}
+	}));
+	if (dependencyMetadata != null) Object.defineProperty(promptedParser, "dependencyMetadata", {
+		value: dependencyMetadata,
+		configurable: true,
+		enumerable: false
+	});
 	return promptedParser;
 }
 /** Normalize choices to the format Inquirer.js expects. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/inquirer",
-  "version": "1.0.0-dev.921+754748bd",
+  "version": "1.0.1",
   "description": "Interactive prompt support for Optique via Inquirer.js",
   "keywords": [
     "CLI",
@@ -56,13 +56,13 @@
   "sideEffects": false,
   "dependencies": {
     "@inquirer/prompts": "^8.3.0",
-    "@optique/core": "1.0.0-dev.921+754748bd"
+    "@optique/core": "1.0.1"
   },
   "devDependencies": {
     "@types/node": "^20.19.9",
     "tsdown": "^0.13.0",
     "typescript": "^5.8.3",
-    "@optique/env": "1.0.0-dev.921+754748bd"
+    "@optique/env": "1.0.1"
   },
   "scripts": {
     "build": "tsdown",