@optique/core 1.0.0-dev.661 → 1.0.0-dev.667

package/dist/annotations.cjs

@@ -16,6 +16,13 @@
 */
 const annotationKey = Symbol.for("@optique/core/parser/annotation");
 /**
+* Internal marker attached during the first pass of `runWith()` so wrappers
+* with side effects can defer work until dynamic contexts have resolved.
+*
+* @internal
+*/
+const firstPassAnnotationKey = Symbol.for("@optique/core/parser/firstPass");
+/**
 * Internal key for preserving primitive parser state values when annotations
 * are injected into non-object states.
 * @internal
@@ -234,6 +241,7 @@ exports.annotateFreshArray = annotateFreshArray;
 exports.annotationKey = annotationKey;
 exports.annotationStateValueKey = annotationStateValueKey;
 exports.annotationWrapperKey = annotationWrapperKey;
+exports.firstPassAnnotationKey = firstPassAnnotationKey;
 exports.getAnnotations = getAnnotations;
 exports.inheritAnnotations = inheritAnnotations;
 exports.injectAnnotations = injectAnnotations;

package/dist/annotations.d.cts

@@ -14,6 +14,13 @@
  * @since 0.10.0
  */
 declare const annotationKey: unique symbol;
+/**
+ * Internal marker attached during the first pass of `runWith()` so wrappers
+ * with side effects can defer work until dynamic contexts have resolved.
+ *
+ * @internal
+ */
+declare const firstPassAnnotationKey: unique symbol;
 /**
  * Internal key for preserving primitive parser state values when annotations
  * are injected into non-object states.
@@ -127,4 +134,4 @@ declare function unwrapInjectedAnnotationWrapper<T>(value: T): T;
  */
 declare function isInjectedAnnotationWrapper(value: unknown): boolean;
 //#endregion
-export { Annotations, ParseOptions, annotateFreshArray, annotationKey, annotationStateValueKey, annotationWrapperKey, getAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper };
+export { Annotations, ParseOptions, annotateFreshArray, annotationKey, annotationStateValueKey, annotationWrapperKey, firstPassAnnotationKey, getAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper };

package/dist/annotations.d.ts

@@ -14,6 +14,13 @@
  * @since 0.10.0
  */
 declare const annotationKey: unique symbol;
+/**
+ * Internal marker attached during the first pass of `runWith()` so wrappers
+ * with side effects can defer work until dynamic contexts have resolved.
+ *
+ * @internal
+ */
+declare const firstPassAnnotationKey: unique symbol;
 /**
  * Internal key for preserving primitive parser state values when annotations
  * are injected into non-object states.
@@ -127,4 +134,4 @@ declare function unwrapInjectedAnnotationWrapper<T>(value: T): T;
  */
 declare function isInjectedAnnotationWrapper(value: unknown): boolean;
 //#endregion
-export { Annotations, ParseOptions, annotateFreshArray, annotationKey, annotationStateValueKey, annotationWrapperKey, getAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper };
+export { Annotations, ParseOptions, annotateFreshArray, annotationKey, annotationStateValueKey, annotationWrapperKey, firstPassAnnotationKey, getAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper };

package/dist/annotations.js

@@ -15,6 +15,13 @@
 */
 const annotationKey = Symbol.for("@optique/core/parser/annotation");
 /**
+* Internal marker attached during the first pass of `runWith()` so wrappers
+* with side effects can defer work until dynamic contexts have resolved.
+*
+* @internal
+*/
+const firstPassAnnotationKey = Symbol.for("@optique/core/parser/firstPass");
+/**
 * Internal key for preserving primitive parser state values when annotations
 * are injected into non-object states.
 * @internal
@@ -229,4 +236,4 @@ function isInjectedAnnotationWrapper(value) {
 }
 
 //#endregion
-export { annotateFreshArray, annotationKey, annotationStateValueKey, annotationWrapperKey, getAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper };
+export { annotateFreshArray, annotationKey, annotationStateValueKey, annotationWrapperKey, firstPassAnnotationKey, getAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper };

package/dist/constructs.cjs

@@ -1,3 +1,4 @@
+const require_annotations = require('./annotations.cjs');
 const require_message = require('./message.cjs');
 const require_dependency = require('./dependency.cjs');
 const require_mode_dispatch = require('./mode-dispatch.cjs');
@@ -6,6 +7,7 @@ const require_suggestion = require('./suggestion.cjs');
 const require_usage_internals = require('./usage-internals.cjs');
 
 //#region src/constructs.ts
+const inheritParentAnnotationsKey = Symbol.for("@optique/core/inheritParentAnnotations");
 function createUnexpectedInputErrorWithScopedSuggestions(baseError, invalidInput, parsers, customFormatter) {
 	const options = /* @__PURE__ */ new Set();
 	const commands = /* @__PURE__ */ new Set();
@@ -842,6 +844,31 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		for (const key of parserKeys) state[key] = parsers[key].initialState;
 		return state;
 	};
+	const inheritedFieldStateCache = /* @__PURE__ */ new WeakMap();
+	const createFieldStateGetter = (parentState) => {
+		return (field, parser) => {
+			const fieldKey = field;
+			const cache = parentState != null && typeof parentState === "object" ? inheritedFieldStateCache.get(parentState) ?? (() => {
+				const stateCache = /* @__PURE__ */ new Map();
+				inheritedFieldStateCache.set(parentState, stateCache);
+				return stateCache;
+			})() : void 0;
+			if (cache?.has(fieldKey)) return cache.get(fieldKey);
+			const sourceState = parentState != null && typeof parentState === "object" && fieldKey in parentState ? parentState[fieldKey] : parser.initialState;
+			if (sourceState == null || typeof sourceState !== "object") {
+				cache?.set(fieldKey, sourceState);
+				return sourceState;
+			}
+			const annotations = require_annotations.getAnnotations(parentState);
+			if (annotations === void 0 || require_annotations.getAnnotations(sourceState) === annotations) {
+				cache?.set(fieldKey, sourceState);
+				return sourceState;
+			}
+			const inheritedState = Reflect.get(parser, inheritParentAnnotationsKey) === true ? require_annotations.injectAnnotations(sourceState, annotations) : require_annotations.inheritAnnotations(parentState, sourceState);
+			cache?.set(fieldKey, inheritedState);
+			return inheritedState;
+		};
+	};
 	if (!options.allowDuplicates) checkDuplicateOptionNames(parserPairs.map(([field, parser]) => [field, parser.usage]));
 	const noMatchContext = analyzeNoMatchContext(parserKeys.map((k) => parsers[k]));
 	const combinedMode = parserKeys.some((k) => parsers[k].$mode === "async") ? "async" : "sync";
@@ -866,10 +893,11 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		let madeProgress = true;
 		while (madeProgress && currentContext.buffer.length > 0) {
 			madeProgress = false;
+			const getFieldState = createFieldStateGetter(currentContext.state);
 			for (const [field, parser] of parserPairs) {
 				const result = parser.parse({
 					...currentContext,
-					state: currentContext.state && typeof currentContext.state === "object" && field in currentContext.state ? currentContext.state[field] : parser.initialState
+					state: getFieldState(field, parser)
 				});
 				if (result.success && result.consumed.length > 0) {
 					currentContext = {
@@ -895,8 +923,9 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		};
 		if (context.buffer.length === 0) {
 			let allCanComplete = true;
+			const getFieldState = createFieldStateGetter(context.state);
 			for (const [field, parser] of parserPairs) {
-				const fieldState = context.state && typeof context.state === "object" && field in context.state ? context.state[field] : parser.initialState;
+				const fieldState = getFieldState(field, parser);
 				const completeResult = parser.complete(fieldState);
 				if (!completeResult.success) {
 					allCanComplete = false;
@@ -922,10 +951,11 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		let madeProgress = true;
 		while (madeProgress && currentContext.buffer.length > 0) {
 			madeProgress = false;
+			const getFieldState = createFieldStateGetter(currentContext.state);
 			for (const [field, parser] of parserPairs) {
 				const resultOrPromise = parser.parse({
 					...currentContext,
-					state: currentContext.state && typeof currentContext.state === "object" && field in currentContext.state ? currentContext.state[field] : parser.initialState
+					state: getFieldState(field, parser)
 				});
 				const result = await resultOrPromise;
 				if (result.success && result.consumed.length > 0) {
@@ -952,8 +982,9 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		};
 		if (context.buffer.length === 0) {
 			let allCanComplete = true;
+			const getFieldState = createFieldStateGetter(context.state);
 			for (const [field, parser] of parserPairs) {
-				const fieldState = context.state && typeof context.state === "object" && field in context.state ? context.state[field] : parser.initialState;
+				const fieldState = getFieldState(field, parser);
 				const completeResult = await parser.complete(fieldState);
 				if (!completeResult.success) {
 					allCanComplete = false;
@@ -987,6 +1018,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			return require_mode_dispatch.dispatchByMode(combinedMode, () => {
 				const preCompletedState = {};
 				const preCompletedKeys = /* @__PURE__ */ new Set();
+				const getFieldState = createFieldStateGetter(state);
 				for (const field of parserKeys) {
 					const fieldKey = field;
 					const fieldState = state[fieldKey];
@@ -1006,10 +1038,11 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 							preCompletedState[fieldKey] = completed;
 							preCompletedKeys.add(fieldKey);
 						} else preCompletedState[fieldKey] = fieldState;
-					} else preCompletedState[fieldKey] = fieldState;
+					} else preCompletedState[fieldKey] = getFieldState(field, fieldParser);
 				}
 				const resolvedState = resolveDeferredParseStates(preCompletedState);
 				const result = {};
+				const getCompletionFieldState = createFieldStateGetter(state);
 				for (const field of parserKeys) {
 					const fieldKey = field;
 					const fieldResolvedState = resolvedState[fieldKey];
@@ -1023,7 +1056,8 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 						};
 						continue;
 					}
-					const valueResult = fieldParser.complete(fieldResolvedState);
+					const completionState = fieldResolvedState === void 0 ? getCompletionFieldState(field, fieldParser) : fieldResolvedState;
+					const valueResult = fieldParser.complete(completionState);
 					if (valueResult.success) result[fieldKey] = valueResult.value;
 					else return {
 						success: false,
@@ -1037,6 +1071,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			}, async () => {
 				const preCompletedState = {};
 				const preCompletedKeys = /* @__PURE__ */ new Set();
+				const getFieldState = createFieldStateGetter(state);
 				for (const field of parserKeys) {
 					const fieldKey = field;
 					const fieldState = state[fieldKey];
@@ -1056,10 +1091,11 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 							preCompletedState[fieldKey] = completed;
 							preCompletedKeys.add(fieldKey);
 						} else preCompletedState[fieldKey] = fieldState;
-					} else preCompletedState[fieldKey] = fieldState;
+					} else preCompletedState[fieldKey] = getFieldState(field, fieldParser);
 				}
 				const resolvedState = await resolveDeferredParseStatesAsync(preCompletedState);
 				const result = {};
+				const getCompletionFieldState = createFieldStateGetter(state);
 				for (const field of parserKeys) {
 					const fieldKey = field;
 					const fieldResolvedState = resolvedState[fieldKey];
@@ -1073,7 +1109,8 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 						};
 						continue;
 					}
-					const valueResult = await fieldParser.complete(fieldResolvedState);
+					const completionState = fieldResolvedState === void 0 ? getCompletionFieldState(field, fieldParser) : fieldResolvedState;
+					const valueResult = await fieldParser.complete(completionState);
 					if (valueResult.success) result[fieldKey] = valueResult.value;
 					else return {
 						success: false,

package/dist/constructs.js

@@ -1,3 +1,4 @@
+import { getAnnotations, inheritAnnotations, injectAnnotations } from "./annotations.js";
 import { message, optionName, text, values } from "./message.js";
 import { DependencyRegistry, dependencyId, isDeferredParseState, isDependencySourceState, isPendingDependencySourceState, isWrappedDependencySource, parseWithDependency, wrappedDependencySourceMarker } from "./dependency.js";
 import { dispatchByMode, dispatchIterableByMode } from "./mode-dispatch.js";
@@ -6,6 +7,7 @@ import { DEFAULT_FIND_SIMILAR_OPTIONS, createErrorWithSuggestions, createSuggest
 import { collectLeadingCandidates } from "./usage-internals.js";
 
 //#region src/constructs.ts
+const inheritParentAnnotationsKey = Symbol.for("@optique/core/inheritParentAnnotations");
 function createUnexpectedInputErrorWithScopedSuggestions(baseError, invalidInput, parsers, customFormatter) {
 	const options = /* @__PURE__ */ new Set();
 	const commands = /* @__PURE__ */ new Set();
@@ -842,6 +844,31 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		for (const key of parserKeys) state[key] = parsers[key].initialState;
 		return state;
 	};
+	const inheritedFieldStateCache = /* @__PURE__ */ new WeakMap();
+	const createFieldStateGetter = (parentState) => {
+		return (field, parser) => {
+			const fieldKey = field;
+			const cache = parentState != null && typeof parentState === "object" ? inheritedFieldStateCache.get(parentState) ?? (() => {
+				const stateCache = /* @__PURE__ */ new Map();
+				inheritedFieldStateCache.set(parentState, stateCache);
+				return stateCache;
+			})() : void 0;
+			if (cache?.has(fieldKey)) return cache.get(fieldKey);
+			const sourceState = parentState != null && typeof parentState === "object" && fieldKey in parentState ? parentState[fieldKey] : parser.initialState;
+			if (sourceState == null || typeof sourceState !== "object") {
+				cache?.set(fieldKey, sourceState);
+				return sourceState;
+			}
+			const annotations = getAnnotations(parentState);
+			if (annotations === void 0 || getAnnotations(sourceState) === annotations) {
+				cache?.set(fieldKey, sourceState);
+				return sourceState;
+			}
+			const inheritedState = Reflect.get(parser, inheritParentAnnotationsKey) === true ? injectAnnotations(sourceState, annotations) : inheritAnnotations(parentState, sourceState);
+			cache?.set(fieldKey, inheritedState);
+			return inheritedState;
+		};
+	};
 	if (!options.allowDuplicates) checkDuplicateOptionNames(parserPairs.map(([field, parser]) => [field, parser.usage]));
 	const noMatchContext = analyzeNoMatchContext(parserKeys.map((k) => parsers[k]));
 	const combinedMode = parserKeys.some((k) => parsers[k].$mode === "async") ? "async" : "sync";
@@ -866,10 +893,11 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		let madeProgress = true;
 		while (madeProgress && currentContext.buffer.length > 0) {
 			madeProgress = false;
+			const getFieldState = createFieldStateGetter(currentContext.state);
 			for (const [field, parser] of parserPairs) {
 				const result = parser.parse({
 					...currentContext,
-					state: currentContext.state && typeof currentContext.state === "object" && field in currentContext.state ? currentContext.state[field] : parser.initialState
+					state: getFieldState(field, parser)
 				});
 				if (result.success && result.consumed.length > 0) {
 					currentContext = {
@@ -895,8 +923,9 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		};
 		if (context.buffer.length === 0) {
 			let allCanComplete = true;
+			const getFieldState = createFieldStateGetter(context.state);
 			for (const [field, parser] of parserPairs) {
-				const fieldState = context.state && typeof context.state === "object" && field in context.state ? context.state[field] : parser.initialState;
+				const fieldState = getFieldState(field, parser);
 				const completeResult = parser.complete(fieldState);
 				if (!completeResult.success) {
 					allCanComplete = false;
@@ -922,10 +951,11 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		let madeProgress = true;
 		while (madeProgress && currentContext.buffer.length > 0) {
 			madeProgress = false;
+			const getFieldState = createFieldStateGetter(currentContext.state);
 			for (const [field, parser] of parserPairs) {
 				const resultOrPromise = parser.parse({
 					...currentContext,
-					state: currentContext.state && typeof currentContext.state === "object" && field in currentContext.state ? currentContext.state[field] : parser.initialState
+					state: getFieldState(field, parser)
 				});
 				const result = await resultOrPromise;
 				if (result.success && result.consumed.length > 0) {
@@ -952,8 +982,9 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		};
 		if (context.buffer.length === 0) {
 			let allCanComplete = true;
+			const getFieldState = createFieldStateGetter(context.state);
 			for (const [field, parser] of parserPairs) {
-				const fieldState = context.state && typeof context.state === "object" && field in context.state ? context.state[field] : parser.initialState;
+				const fieldState = getFieldState(field, parser);
 				const completeResult = await parser.complete(fieldState);
 				if (!completeResult.success) {
 					allCanComplete = false;
@@ -987,6 +1018,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			return dispatchByMode(combinedMode, () => {
 				const preCompletedState = {};
 				const preCompletedKeys = /* @__PURE__ */ new Set();
+				const getFieldState = createFieldStateGetter(state);
 				for (const field of parserKeys) {
 					const fieldKey = field;
 					const fieldState = state[fieldKey];
@@ -1006,10 +1038,11 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 							preCompletedState[fieldKey] = completed;
 							preCompletedKeys.add(fieldKey);
 						} else preCompletedState[fieldKey] = fieldState;
-					} else preCompletedState[fieldKey] = fieldState;
+					} else preCompletedState[fieldKey] = getFieldState(field, fieldParser);
 				}
 				const resolvedState = resolveDeferredParseStates(preCompletedState);
 				const result = {};
+				const getCompletionFieldState = createFieldStateGetter(state);
 				for (const field of parserKeys) {
 					const fieldKey = field;
 					const fieldResolvedState = resolvedState[fieldKey];
@@ -1023,7 +1056,8 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 						};
 						continue;
 					}
-					const valueResult = fieldParser.complete(fieldResolvedState);
+					const completionState = fieldResolvedState === void 0 ? getCompletionFieldState(field, fieldParser) : fieldResolvedState;
+					const valueResult = fieldParser.complete(completionState);
 					if (valueResult.success) result[fieldKey] = valueResult.value;
 					else return {
 						success: false,
@@ -1037,6 +1071,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			}, async () => {
 				const preCompletedState = {};
 				const preCompletedKeys = /* @__PURE__ */ new Set();
+				const getFieldState = createFieldStateGetter(state);
 				for (const field of parserKeys) {
 					const fieldKey = field;
 					const fieldState = state[fieldKey];
@@ -1056,10 +1091,11 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 							preCompletedState[fieldKey] = completed;
 							preCompletedKeys.add(fieldKey);
 						} else preCompletedState[fieldKey] = fieldState;
-					} else preCompletedState[fieldKey] = fieldState;
+					} else preCompletedState[fieldKey] = getFieldState(field, fieldParser);
 				}
 				const resolvedState = await resolveDeferredParseStatesAsync(preCompletedState);
 				const result = {};
+				const getCompletionFieldState = createFieldStateGetter(state);
 				for (const field of parserKeys) {
 					const fieldKey = field;
 					const fieldResolvedState = resolvedState[fieldKey];
@@ -1073,7 +1109,8 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 						};
 						continue;
 					}
-					const valueResult = await fieldParser.complete(fieldResolvedState);
+					const completionState = fieldResolvedState === void 0 ? getCompletionFieldState(field, fieldParser) : fieldResolvedState;
+					const valueResult = await fieldParser.complete(completionState);
 					if (valueResult.success) result[fieldKey] = valueResult.value;
 					else return {
 						success: false,

package/dist/facade.cjs

@@ -11,6 +11,159 @@ const require_primitives = require('./primitives.cjs');
 const require_parser = require('./parser.cjs');
 
 //#region src/facade.ts
+const phase1ConfigAnnotationsKey = Symbol.for("@optique/config/phase1PromptAnnotations");
+const phase2UndefinedParsedValueKey = Symbol.for("@optique/config/phase2UndefinedParsedValue");
+const deferredPromptValueKey = Symbol.for("@optique/inquirer/deferredPromptValue");
+function isDeferredPromptValue(value$1) {
+	return value$1 != null && typeof value$1 === "object" && deferredPromptValueKey in value$1;
+}
+function isPlainObject(value$1) {
+	const proto = Object.getPrototypeOf(value$1);
+	return proto === Object.prototype || proto === null;
+}
+function shouldSkipCollectionOwnKey(value$1, key) {
+	if (Array.isArray(value$1)) return key === "length" || typeof key === "string" && Number.isInteger(Number(key)) && String(Number(key)) === key;
+	return false;
+}
+function containsDeferredPromptValuesInOwnProperties(value$1, seen) {
+	for (const key of Reflect.ownKeys(value$1)) {
+		if (shouldSkipCollectionOwnKey(value$1, key)) continue;
+		const descriptor = Object.getOwnPropertyDescriptor(value$1, key);
+		if (descriptor != null && "value" in descriptor && containsDeferredPromptValuesForContexts(descriptor.value, seen)) return true;
+	}
+	return false;
+}
+function copySanitizedOwnProperties(source, target, seen) {
+	for (const key of Reflect.ownKeys(source)) {
+		if (shouldSkipCollectionOwnKey(source, key)) continue;
+		const descriptor = Object.getOwnPropertyDescriptor(source, key);
+		if (descriptor == null) continue;
+		if ("value" in descriptor) descriptor.value = stripDeferredPromptValuesForContexts(descriptor.value, seen);
+		Object.defineProperty(target, key, descriptor);
+	}
+}
+function createArrayCloneLike(value$1) {
+	try {
+		const arrayCtor = value$1.constructor;
+		return Reflect.construct(Array, [value$1.length], arrayCtor);
+	} catch {
+		return new Array(value$1.length);
+	}
+}
+function createSetCloneLike(value$1) {
+	try {
+		const setCtor = value$1.constructor;
+		return Reflect.construct(Set, [], setCtor);
+	} catch {
+		return /* @__PURE__ */ new Set();
+	}
+}
+function createMapCloneLike(value$1) {
+	try {
+		const mapCtor = value$1.constructor;
+		return Reflect.construct(Map, [], mapCtor);
+	} catch {
+		return /* @__PURE__ */ new Map();
+	}
+}
+function containsDeferredPromptValuesForContexts(value$1, seen = /* @__PURE__ */ new WeakSet()) {
+	if (isDeferredPromptValue(value$1)) return true;
+	if (value$1 == null || typeof value$1 !== "object") return false;
+	if (seen.has(value$1)) return false;
+	seen.add(value$1);
+	if (Array.isArray(value$1)) {
+		if (value$1.some((item) => containsDeferredPromptValuesForContexts(item, seen))) return true;
+		return containsDeferredPromptValuesInOwnProperties(value$1, seen);
+	}
+	if (value$1 instanceof Set) {
+		for (const entryValue of value$1) if (containsDeferredPromptValuesForContexts(entryValue, seen)) return true;
+		return containsDeferredPromptValuesInOwnProperties(value$1, seen);
+	}
+	if (value$1 instanceof Map) {
+		for (const [key, entryValue] of value$1) if (containsDeferredPromptValuesForContexts(key, seen) || containsDeferredPromptValuesForContexts(entryValue, seen)) return true;
+		return containsDeferredPromptValuesInOwnProperties(value$1, seen);
+	}
+	return containsDeferredPromptValuesInOwnProperties(value$1, seen);
+}
+function stripDeferredPromptValuesForContexts(value$1, seen = /* @__PURE__ */ new WeakMap()) {
+	if (isDeferredPromptValue(value$1)) return void 0;
+	if (value$1 == null || typeof value$1 !== "object") return value$1;
+	const cached = seen.get(value$1);
+	if (cached !== void 0) return cached;
+	if (Array.isArray(value$1)) {
+		if (!containsDeferredPromptValuesForContexts(value$1)) return value$1;
+		const clone$1 = createArrayCloneLike(value$1);
+		seen.set(value$1, clone$1);
+		for (let i = 0; i < value$1.length; i++) clone$1[i] = stripDeferredPromptValuesForContexts(value$1[i], seen);
+		copySanitizedOwnProperties(value$1, clone$1, seen);
+		return clone$1;
+	}
+	if (value$1 instanceof Set) {
+		if (!containsDeferredPromptValuesForContexts(value$1)) return value$1;
+		const clone$1 = createSetCloneLike(value$1);
+		seen.set(value$1, clone$1);
+		for (const entryValue of value$1) clone$1.add(stripDeferredPromptValuesForContexts(entryValue, seen));
+		copySanitizedOwnProperties(value$1, clone$1, seen);
+		return clone$1;
+	}
+	if (value$1 instanceof Map) {
+		if (!containsDeferredPromptValuesForContexts(value$1)) return value$1;
+		const clone$1 = createMapCloneLike(value$1);
+		seen.set(value$1, clone$1);
+		for (const [key, entryValue] of value$1) clone$1.set(stripDeferredPromptValuesForContexts(key, seen), stripDeferredPromptValuesForContexts(entryValue, seen));
+		copySanitizedOwnProperties(value$1, clone$1, seen);
+		return clone$1;
+	}
+	if (!isPlainObject(value$1)) {
+		if (!containsDeferredPromptValuesForContexts(value$1)) return value$1;
+		return createSanitizedNonPlainContextView(value$1, seen);
+	}
+	const clone = Object.create(Object.getPrototypeOf(value$1));
+	seen.set(value$1, clone);
+	for (const key of Reflect.ownKeys(value$1)) {
+		const descriptor = Object.getOwnPropertyDescriptor(value$1, key);
+		if (descriptor == null) continue;
+		if ("value" in descriptor) descriptor.value = stripDeferredPromptValuesForContexts(descriptor.value, seen);
+		Object.defineProperty(clone, key, descriptor);
+	}
+	return clone;
+}
+function finalizeParsedForContext(context, parsed) {
+	if (parsed !== void 0 || !Reflect.has(context, phase1ConfigAnnotationsKey)) return parsed;
+	return { [phase2UndefinedParsedValueKey]: true };
+}
+function createSanitizedNonPlainContextView(value$1, seen) {
+	const proxy = new Proxy(value$1, {
+		get(target, key, receiver) {
+			const descriptor = Object.getOwnPropertyDescriptor(target, key);
+			if (descriptor != null && "value" in descriptor) return stripDeferredPromptValuesForContexts(descriptor.value, seen);
+			return Reflect.get(target, key, receiver);
+		},
+		getOwnPropertyDescriptor(target, key) {
+			const descriptor = Object.getOwnPropertyDescriptor(target, key);
+			if (descriptor == null || !("value" in descriptor)) return descriptor;
+			return {
+				...descriptor,
+				value: stripDeferredPromptValuesForContexts(descriptor.value, seen)
+			};
+		}
+	});
+	seen.set(value$1, proxy);
+	return proxy;
+}
+function prepareParsedForContexts(parsed) {
+	if (parsed == null || typeof parsed !== "object") return stripDeferredPromptValuesForContexts(parsed);
+	if (isDeferredPromptValue(parsed)) return void 0;
+	if (Array.isArray(parsed) || isPlainObject(parsed) || parsed instanceof Set || parsed instanceof Map) {
+		if (!containsDeferredPromptValuesForContexts(parsed)) return parsed;
+		return stripDeferredPromptValuesForContexts(parsed);
+	}
+	if (!containsDeferredPromptValuesForContexts(parsed)) return parsed;
+	return createSanitizedNonPlainContextView(parsed, /* @__PURE__ */ new WeakMap());
+}
+function withPreparedParsedForContext(context, preparedParsed, run) {
+	return run(finalizeParsedForContext(context, preparedParsed));
+}
 /**
 * Creates help parsers based on the sub-config.
 */
@@ -850,10 +1003,14 @@ async function collectPhase1Annotations(contexts, options) {
 	for (const context of contexts) {
 		const result = context.getAnnotations(void 0, options);
 		hasDynamic ||= needsTwoPhaseContext(context, result);
-		annotationsList.push(result instanceof Promise ? await result : result);
+		const annotations = result instanceof Promise ? await result : result;
+		const internalAnnotationsGetter = Reflect.get(context, phase1ConfigAnnotationsKey);
+		const internalAnnotations = typeof internalAnnotationsGetter === "function" ? internalAnnotationsGetter.call(context, void 0, annotations) : void 0;
+		annotationsList.push(internalAnnotations == null ? annotations : mergeAnnotations([annotations, internalAnnotations]));
 	}
 	return {
 		annotations: mergeAnnotations(annotationsList),
+		annotationsList,
 		hasDynamic
 	};
 }
@@ -867,11 +1024,21 @@ async function collectPhase1Annotations(contexts, options) {
 */
 async function collectAnnotations(contexts, parsed, options) {
 	const annotationsList = [];
+	const preparedParsed = prepareParsedForContexts(parsed);
 	for (const context of contexts) {
-		const result = context.getAnnotations(parsed, options);
-		annotationsList.push(result instanceof Promise ? await result : result);
+		const mergedAnnotations = await withPreparedParsedForContext(context, preparedParsed, async (contextParsed) => {
+			const result = context.getAnnotations(contextParsed, options);
+			const annotations = result instanceof Promise ? await result : result;
+			const internalAnnotationsGetter = Reflect.get(context, phase1ConfigAnnotationsKey);
+			const internalAnnotations = typeof internalAnnotationsGetter === "function" ? internalAnnotationsGetter.call(context, contextParsed, annotations) : void 0;
+			return internalAnnotations == null ? annotations : mergeAnnotations([annotations, internalAnnotations]);
+		});
+		annotationsList.push(mergedAnnotations);
 	}
-	return mergeAnnotations(annotationsList);
+	return {
+		annotations: mergeAnnotations(annotationsList),
+		annotationsList
+	};
 }
 /**
 * Collects phase 1 annotations from all contexts synchronously and determines
@@ -889,10 +1056,13 @@ function collectPhase1AnnotationsSync(contexts, options) {
 		const result = context.getAnnotations(void 0, options);
 		if (result instanceof Promise) throw new Error(`Context ${String(context.id)} returned a Promise in sync mode. Use runWith() or runWithAsync() for async contexts.`);
 		hasDynamic ||= needsTwoPhaseContext(context, result);
-		annotationsList.push(result);
+		const internalAnnotationsGetter = Reflect.get(context, phase1ConfigAnnotationsKey);
+		const internalAnnotations = typeof internalAnnotationsGetter === "function" ? internalAnnotationsGetter.call(context, void 0, result) : void 0;
+		annotationsList.push(internalAnnotations == null ? result : mergeAnnotations([result, internalAnnotations]));
 	}
 	return {
 		annotations: mergeAnnotations(annotationsList),
+		annotationsList,
 		hasDynamic
 	};
 }
@@ -919,12 +1089,27 @@ function needsTwoPhaseContext(context, result) {
 */
 function collectAnnotationsSync(contexts, parsed, options) {
 	const annotationsList = [];
+	const preparedParsed = prepareParsedForContexts(parsed);
 	for (const context of contexts) {
-		const result = context.getAnnotations(parsed, options);
-		if (result instanceof Promise) throw new Error(`Context ${String(context.id)} returned a Promise in sync mode. Use runWith() or runWithAsync() for async contexts.`);
-		annotationsList.push(result);
+		const mergedAnnotations = withPreparedParsedForContext(context, preparedParsed, (contextParsed) => {
+			const result = context.getAnnotations(contextParsed, options);
+			if (result instanceof Promise) throw new Error(`Context ${String(context.id)} returned a Promise in sync mode. Use runWith() or runWithAsync() for async contexts.`);
+			const internalAnnotationsGetter = Reflect.get(context, phase1ConfigAnnotationsKey);
+			const internalAnnotations = typeof internalAnnotationsGetter === "function" ? internalAnnotationsGetter.call(context, contextParsed, result) : void 0;
+			return internalAnnotations == null ? result : mergeAnnotations([result, internalAnnotations]);
+		});
+		annotationsList.push(mergedAnnotations);
 	}
-	return mergeAnnotations(annotationsList);
+	return {
+		annotations: mergeAnnotations(annotationsList),
+		annotationsList
+	};
+}
+function mergeTwoPhaseAnnotations(phase1AnnotationsList, phase2AnnotationsList) {
+	const mergedPerContext = [];
+	const length = Math.max(phase1AnnotationsList.length, phase2AnnotationsList.length);
+	for (let i = 0; i < length; i++) mergedPerContext.push(mergeAnnotations([phase2AnnotationsList[i] ?? {}, phase1AnnotationsList[i] ?? {}]));
+	return mergeAnnotations(mergedPerContext);
 }
 /**
 * Disposes all contexts that implement `AsyncDisposable` or `Disposable`.
@@ -1022,7 +1207,7 @@ async function runWith(parser, programName, contexts, options) {
 		return Promise.resolve(runParser(parser, programName, args, options));
 	}
 	try {
-		const { annotations: phase1Annotations, hasDynamic: needsTwoPhase } = await collectPhase1Annotations(contexts, options);
+		const { annotations: phase1Annotations, annotationsList: phase1AnnotationsList, hasDynamic: needsTwoPhase } = await collectPhase1Annotations(contexts, options);
 		if (!needsTwoPhase) {
 			const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
 			if (parser.$mode === "async") return runParser(augmentedParser, programName, args, options);
@@ -1047,8 +1232,8 @@ async function runWith(parser, programName, contexts, options) {
 			if (parser.$mode === "async") return runParser(augmentedParser, programName, args, options);
 			return Promise.resolve(runParser(augmentedParser, programName, args, options));
 		}
-		const phase2Annotations = await collectAnnotations(contexts, firstPassResult, options);
-		const finalAnnotations = mergeAnnotations([phase1Annotations, phase2Annotations]);
+		const { annotationsList: phase2AnnotationsList } = await collectAnnotations(contexts, firstPassResult, options);
+		const finalAnnotations = mergeTwoPhaseAnnotations(phase1AnnotationsList, phase2AnnotationsList);
 		const augmentedParser2 = injectAnnotationsIntoParser(parser, finalAnnotations);
 		if (parser.$mode === "async") return runParser(augmentedParser2, programName, args, options);
 		return Promise.resolve(runParser(augmentedParser2, programName, args, options));
@@ -1079,7 +1264,7 @@ function runWithSync(parser, programName, contexts, options) {
 	if (needsEarlyExit(args, options)) return runParser(parser, programName, args, options);
 	if (contexts.length === 0) return runParser(parser, programName, args, options);
 	try {
-		const { annotations: phase1Annotations, hasDynamic: needsTwoPhase } = collectPhase1AnnotationsSync(contexts, options);
+		const { annotations: phase1Annotations, annotationsList: phase1AnnotationsList, hasDynamic: needsTwoPhase } = collectPhase1AnnotationsSync(contexts, options);
 		if (!needsTwoPhase) {
 			const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
 			return runParser(augmentedParser, programName, args, options);
@@ -1093,8 +1278,8 @@ function runWithSync(parser, programName, contexts, options) {
 		} catch {
 			return runParser(augmentedParser1, programName, args, options);
 		}
-		const phase2Annotations = collectAnnotationsSync(contexts, firstPassResult, options);
-		const finalAnnotations = mergeAnnotations([phase1Annotations, phase2Annotations]);
+		const { annotationsList: phase2AnnotationsList } = collectAnnotationsSync(contexts, firstPassResult, options);
+		const finalAnnotations = mergeTwoPhaseAnnotations(phase1AnnotationsList, phase2AnnotationsList);
 		const augmentedParser2 = injectAnnotationsIntoParser(parser, finalAnnotations);
 		return runParser(augmentedParser2, programName, args, options);
 	} finally {

package/dist/facade.js

@@ -11,6 +11,159 @@ import { argument, command, constant, flag, option } from "./primitives.js";
 import { getDocPage, parseAsync, parseSync, suggest, suggestAsync } from "./parser.js";
 
 //#region src/facade.ts
+const phase1ConfigAnnotationsKey = Symbol.for("@optique/config/phase1PromptAnnotations");
+const phase2UndefinedParsedValueKey = Symbol.for("@optique/config/phase2UndefinedParsedValue");
+const deferredPromptValueKey = Symbol.for("@optique/inquirer/deferredPromptValue");
+function isDeferredPromptValue(value$1) {
+	return value$1 != null && typeof value$1 === "object" && deferredPromptValueKey in value$1;
+}
+function isPlainObject(value$1) {
+	const proto = Object.getPrototypeOf(value$1);
+	return proto === Object.prototype || proto === null;
+}
+function shouldSkipCollectionOwnKey(value$1, key) {
+	if (Array.isArray(value$1)) return key === "length" || typeof key === "string" && Number.isInteger(Number(key)) && String(Number(key)) === key;
+	return false;
+}
+function containsDeferredPromptValuesInOwnProperties(value$1, seen) {
+	for (const key of Reflect.ownKeys(value$1)) {
+		if (shouldSkipCollectionOwnKey(value$1, key)) continue;
+		const descriptor = Object.getOwnPropertyDescriptor(value$1, key);
+		if (descriptor != null && "value" in descriptor && containsDeferredPromptValuesForContexts(descriptor.value, seen)) return true;
+	}
+	return false;
+}
+function copySanitizedOwnProperties(source, target, seen) {
+	for (const key of Reflect.ownKeys(source)) {
+		if (shouldSkipCollectionOwnKey(source, key)) continue;
+		const descriptor = Object.getOwnPropertyDescriptor(source, key);
+		if (descriptor == null) continue;
+		if ("value" in descriptor) descriptor.value = stripDeferredPromptValuesForContexts(descriptor.value, seen);
+		Object.defineProperty(target, key, descriptor);
+	}
+}
+function createArrayCloneLike(value$1) {
+	try {
+		const arrayCtor = value$1.constructor;
+		return Reflect.construct(Array, [value$1.length], arrayCtor);
+	} catch {
+		return new Array(value$1.length);
+	}
+}
+function createSetCloneLike(value$1) {
+	try {
+		const setCtor = value$1.constructor;
+		return Reflect.construct(Set, [], setCtor);
+	} catch {
+		return /* @__PURE__ */ new Set();
+	}
+}
+function createMapCloneLike(value$1) {
+	try {
+		const mapCtor = value$1.constructor;
+		return Reflect.construct(Map, [], mapCtor);
+	} catch {
+		return /* @__PURE__ */ new Map();
+	}
+}
+function containsDeferredPromptValuesForContexts(value$1, seen = /* @__PURE__ */ new WeakSet()) {
+	if (isDeferredPromptValue(value$1)) return true;
+	if (value$1 == null || typeof value$1 !== "object") return false;
+	if (seen.has(value$1)) return false;
+	seen.add(value$1);
+	if (Array.isArray(value$1)) {
+		if (value$1.some((item) => containsDeferredPromptValuesForContexts(item, seen))) return true;
+		return containsDeferredPromptValuesInOwnProperties(value$1, seen);
+	}
+	if (value$1 instanceof Set) {
+		for (const entryValue of value$1) if (containsDeferredPromptValuesForContexts(entryValue, seen)) return true;
+		return containsDeferredPromptValuesInOwnProperties(value$1, seen);
+	}
+	if (value$1 instanceof Map) {
+		for (const [key, entryValue] of value$1) if (containsDeferredPromptValuesForContexts(key, seen) || containsDeferredPromptValuesForContexts(entryValue, seen)) return true;
+		return containsDeferredPromptValuesInOwnProperties(value$1, seen);
+	}
+	return containsDeferredPromptValuesInOwnProperties(value$1, seen);
+}
+function stripDeferredPromptValuesForContexts(value$1, seen = /* @__PURE__ */ new WeakMap()) {
+	if (isDeferredPromptValue(value$1)) return void 0;
+	if (value$1 == null || typeof value$1 !== "object") return value$1;
+	const cached = seen.get(value$1);
+	if (cached !== void 0) return cached;
+	if (Array.isArray(value$1)) {
+		if (!containsDeferredPromptValuesForContexts(value$1)) return value$1;
+		const clone$1 = createArrayCloneLike(value$1);
+		seen.set(value$1, clone$1);
+		for (let i = 0; i < value$1.length; i++) clone$1[i] = stripDeferredPromptValuesForContexts(value$1[i], seen);
+		copySanitizedOwnProperties(value$1, clone$1, seen);
+		return clone$1;
+	}
+	if (value$1 instanceof Set) {
+		if (!containsDeferredPromptValuesForContexts(value$1)) return value$1;
+		const clone$1 = createSetCloneLike(value$1);
+		seen.set(value$1, clone$1);
+		for (const entryValue of value$1) clone$1.add(stripDeferredPromptValuesForContexts(entryValue, seen));
+		copySanitizedOwnProperties(value$1, clone$1, seen);
+		return clone$1;
+	}
+	if (value$1 instanceof Map) {
+		if (!containsDeferredPromptValuesForContexts(value$1)) return value$1;
+		const clone$1 = createMapCloneLike(value$1);
+		seen.set(value$1, clone$1);
+		for (const [key, entryValue] of value$1) clone$1.set(stripDeferredPromptValuesForContexts(key, seen), stripDeferredPromptValuesForContexts(entryValue, seen));
+		copySanitizedOwnProperties(value$1, clone$1, seen);
+		return clone$1;
+	}
+	if (!isPlainObject(value$1)) {
+		if (!containsDeferredPromptValuesForContexts(value$1)) return value$1;
+		return createSanitizedNonPlainContextView(value$1, seen);
+	}
+	const clone = Object.create(Object.getPrototypeOf(value$1));
+	seen.set(value$1, clone);
+	for (const key of Reflect.ownKeys(value$1)) {
+		const descriptor = Object.getOwnPropertyDescriptor(value$1, key);
+		if (descriptor == null) continue;
+		if ("value" in descriptor) descriptor.value = stripDeferredPromptValuesForContexts(descriptor.value, seen);
+		Object.defineProperty(clone, key, descriptor);
+	}
+	return clone;
+}
+function finalizeParsedForContext(context, parsed) {
+	if (parsed !== void 0 || !Reflect.has(context, phase1ConfigAnnotationsKey)) return parsed;
+	return { [phase2UndefinedParsedValueKey]: true };
+}
+function createSanitizedNonPlainContextView(value$1, seen) {
+	const proxy = new Proxy(value$1, {
+		get(target, key, receiver) {
+			const descriptor = Object.getOwnPropertyDescriptor(target, key);
+			if (descriptor != null && "value" in descriptor) return stripDeferredPromptValuesForContexts(descriptor.value, seen);
+			return Reflect.get(target, key, receiver);
+		},
+		getOwnPropertyDescriptor(target, key) {
+			const descriptor = Object.getOwnPropertyDescriptor(target, key);
+			if (descriptor == null || !("value" in descriptor)) return descriptor;
+			return {
+				...descriptor,
+				value: stripDeferredPromptValuesForContexts(descriptor.value, seen)
+			};
+		}
+	});
+	seen.set(value$1, proxy);
+	return proxy;
+}
+function prepareParsedForContexts(parsed) {
+	if (parsed == null || typeof parsed !== "object") return stripDeferredPromptValuesForContexts(parsed);
+	if (isDeferredPromptValue(parsed)) return void 0;
+	if (Array.isArray(parsed) || isPlainObject(parsed) || parsed instanceof Set || parsed instanceof Map) {
+		if (!containsDeferredPromptValuesForContexts(parsed)) return parsed;
+		return stripDeferredPromptValuesForContexts(parsed);
+	}
+	if (!containsDeferredPromptValuesForContexts(parsed)) return parsed;
+	return createSanitizedNonPlainContextView(parsed, /* @__PURE__ */ new WeakMap());
+}
+function withPreparedParsedForContext(context, preparedParsed, run) {
+	return run(finalizeParsedForContext(context, preparedParsed));
+}
 /**
 * Creates help parsers based on the sub-config.
 */
@@ -850,10 +1003,14 @@ async function collectPhase1Annotations(contexts, options) {
 	for (const context of contexts) {
 		const result = context.getAnnotations(void 0, options);
 		hasDynamic ||= needsTwoPhaseContext(context, result);
-		annotationsList.push(result instanceof Promise ? await result : result);
+		const annotations = result instanceof Promise ? await result : result;
+		const internalAnnotationsGetter = Reflect.get(context, phase1ConfigAnnotationsKey);
+		const internalAnnotations = typeof internalAnnotationsGetter === "function" ? internalAnnotationsGetter.call(context, void 0, annotations) : void 0;
+		annotationsList.push(internalAnnotations == null ? annotations : mergeAnnotations([annotations, internalAnnotations]));
 	}
 	return {
 		annotations: mergeAnnotations(annotationsList),
+		annotationsList,
 		hasDynamic
 	};
 }
@@ -867,11 +1024,21 @@ async function collectPhase1Annotations(contexts, options) {
 */
 async function collectAnnotations(contexts, parsed, options) {
 	const annotationsList = [];
+	const preparedParsed = prepareParsedForContexts(parsed);
 	for (const context of contexts) {
-		const result = context.getAnnotations(parsed, options);
-		annotationsList.push(result instanceof Promise ? await result : result);
+		const mergedAnnotations = await withPreparedParsedForContext(context, preparedParsed, async (contextParsed) => {
+			const result = context.getAnnotations(contextParsed, options);
+			const annotations = result instanceof Promise ? await result : result;
+			const internalAnnotationsGetter = Reflect.get(context, phase1ConfigAnnotationsKey);
+			const internalAnnotations = typeof internalAnnotationsGetter === "function" ? internalAnnotationsGetter.call(context, contextParsed, annotations) : void 0;
+			return internalAnnotations == null ? annotations : mergeAnnotations([annotations, internalAnnotations]);
+		});
+		annotationsList.push(mergedAnnotations);
 	}
-	return mergeAnnotations(annotationsList);
+	return {
+		annotations: mergeAnnotations(annotationsList),
+		annotationsList
+	};
 }
 /**
 * Collects phase 1 annotations from all contexts synchronously and determines
@@ -889,10 +1056,13 @@ function collectPhase1AnnotationsSync(contexts, options) {
 		const result = context.getAnnotations(void 0, options);
 		if (result instanceof Promise) throw new Error(`Context ${String(context.id)} returned a Promise in sync mode. Use runWith() or runWithAsync() for async contexts.`);
 		hasDynamic ||= needsTwoPhaseContext(context, result);
-		annotationsList.push(result);
+		const internalAnnotationsGetter = Reflect.get(context, phase1ConfigAnnotationsKey);
+		const internalAnnotations = typeof internalAnnotationsGetter === "function" ? internalAnnotationsGetter.call(context, void 0, result) : void 0;
+		annotationsList.push(internalAnnotations == null ? result : mergeAnnotations([result, internalAnnotations]));
 	}
 	return {
 		annotations: mergeAnnotations(annotationsList),
+		annotationsList,
 		hasDynamic
 	};
 }
@@ -919,12 +1089,27 @@ function needsTwoPhaseContext(context, result) {
 */
 function collectAnnotationsSync(contexts, parsed, options) {
 	const annotationsList = [];
+	const preparedParsed = prepareParsedForContexts(parsed);
 	for (const context of contexts) {
-		const result = context.getAnnotations(parsed, options);
-		if (result instanceof Promise) throw new Error(`Context ${String(context.id)} returned a Promise in sync mode. Use runWith() or runWithAsync() for async contexts.`);
-		annotationsList.push(result);
+		const mergedAnnotations = withPreparedParsedForContext(context, preparedParsed, (contextParsed) => {
+			const result = context.getAnnotations(contextParsed, options);
+			if (result instanceof Promise) throw new Error(`Context ${String(context.id)} returned a Promise in sync mode. Use runWith() or runWithAsync() for async contexts.`);
+			const internalAnnotationsGetter = Reflect.get(context, phase1ConfigAnnotationsKey);
+			const internalAnnotations = typeof internalAnnotationsGetter === "function" ? internalAnnotationsGetter.call(context, contextParsed, result) : void 0;
+			return internalAnnotations == null ? result : mergeAnnotations([result, internalAnnotations]);
+		});
+		annotationsList.push(mergedAnnotations);
 	}
-	return mergeAnnotations(annotationsList);
+	return {
+		annotations: mergeAnnotations(annotationsList),
+		annotationsList
+	};
+}
+function mergeTwoPhaseAnnotations(phase1AnnotationsList, phase2AnnotationsList) {
+	const mergedPerContext = [];
+	const length = Math.max(phase1AnnotationsList.length, phase2AnnotationsList.length);
+	for (let i = 0; i < length; i++) mergedPerContext.push(mergeAnnotations([phase2AnnotationsList[i] ?? {}, phase1AnnotationsList[i] ?? {}]));
+	return mergeAnnotations(mergedPerContext);
 }
 /**
 * Disposes all contexts that implement `AsyncDisposable` or `Disposable`.
@@ -1022,7 +1207,7 @@ async function runWith(parser, programName, contexts, options) {
 		return Promise.resolve(runParser(parser, programName, args, options));
 	}
 	try {
-		const { annotations: phase1Annotations, hasDynamic: needsTwoPhase } = await collectPhase1Annotations(contexts, options);
+		const { annotations: phase1Annotations, annotationsList: phase1AnnotationsList, hasDynamic: needsTwoPhase } = await collectPhase1Annotations(contexts, options);
 		if (!needsTwoPhase) {
 			const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
 			if (parser.$mode === "async") return runParser(augmentedParser, programName, args, options);
@@ -1047,8 +1232,8 @@ async function runWith(parser, programName, contexts, options) {
 			if (parser.$mode === "async") return runParser(augmentedParser, programName, args, options);
 			return Promise.resolve(runParser(augmentedParser, programName, args, options));
 		}
-		const phase2Annotations = await collectAnnotations(contexts, firstPassResult, options);
-		const finalAnnotations = mergeAnnotations([phase1Annotations, phase2Annotations]);
+		const { annotationsList: phase2AnnotationsList } = await collectAnnotations(contexts, firstPassResult, options);
+		const finalAnnotations = mergeTwoPhaseAnnotations(phase1AnnotationsList, phase2AnnotationsList);
 		const augmentedParser2 = injectAnnotationsIntoParser(parser, finalAnnotations);
 		if (parser.$mode === "async") return runParser(augmentedParser2, programName, args, options);
 		return Promise.resolve(runParser(augmentedParser2, programName, args, options));
@@ -1079,7 +1264,7 @@ function runWithSync(parser, programName, contexts, options) {
 	if (needsEarlyExit(args, options)) return runParser(parser, programName, args, options);
 	if (contexts.length === 0) return runParser(parser, programName, args, options);
 	try {
-		const { annotations: phase1Annotations, hasDynamic: needsTwoPhase } = collectPhase1AnnotationsSync(contexts, options);
+		const { annotations: phase1Annotations, annotationsList: phase1AnnotationsList, hasDynamic: needsTwoPhase } = collectPhase1AnnotationsSync(contexts, options);
 		if (!needsTwoPhase) {
 			const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
 			return runParser(augmentedParser, programName, args, options);
@@ -1093,8 +1278,8 @@ function runWithSync(parser, programName, contexts, options) {
 		} catch {
 			return runParser(augmentedParser1, programName, args, options);
 		}
-		const phase2Annotations = collectAnnotationsSync(contexts, firstPassResult, options);
-		const finalAnnotations = mergeAnnotations([phase1Annotations, phase2Annotations]);
+		const { annotationsList: phase2AnnotationsList } = collectAnnotationsSync(contexts, firstPassResult, options);
+		const finalAnnotations = mergeTwoPhaseAnnotations(phase1AnnotationsList, phase2AnnotationsList);
 		const augmentedParser2 = injectAnnotationsIntoParser(parser, finalAnnotations);
 		return runParser(augmentedParser2, programName, args, options);
 	} finally {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.661+a4060a75",
+  "version": "1.0.0-dev.667+b4962990",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",