@optique/core 1.0.0-dev.1890 → 1.0.0-dev.1893

package/dist/annotation-state.cjs

@@ -58,6 +58,121 @@ function withAnnotationView(state, annotations) {
 function normalizeInjectedAnnotationState(state) {
 	return require_annotations.unwrapInjectedAnnotationWrapper(state);
 }
+function isNonPlainDelegatedObject(state) {
+	if (Array.isArray(state) || state instanceof Date || state instanceof Map || state instanceof Set || state instanceof RegExp) return false;
+	const proto = Object.getPrototypeOf(state);
+	return proto !== Object.prototype && proto !== null;
+}
+/**
+* Removes Optique's internal annotation carriers from a delegated state.
+*
+* This unwraps both primitive-state annotation wrappers and annotation-view
+* proxies used for non-plain object states.
+*
+* @param state The delegated state to normalize.
+* @returns The original underlying state value.
+* @internal
+*/
+function normalizeDelegatedAnnotationState(state) {
+	return normalizeInjectedAnnotationState(unwrapAnnotationView(state));
+}
+/**
+* Returns whether the given state uses an internal delegated annotation carrier.
+*
+* @param state The candidate state to inspect.
+* @returns `true` when the state is an injected primitive wrapper or an
+*          annotation-view proxy.
+* @internal
+*/
+function hasDelegatedAnnotationCarrier(state) {
+	return state != null && typeof state === "object" && (require_annotations.isInjectedAnnotationWrapper(state) || annotationViewTargets.has(state));
+}
+/**
+* Recursively removes delegated annotation carriers from plain-object and array
+* structures.
+*
+* Nested plain objects and arrays are shallow-cloned only when a delegated
+* carrier is found below them. Non-plain objects are unwrapped at the top
+* level and then preserved as-is to avoid mutating or reconstructing class
+* instances.
+*
+* @param value The candidate value to normalize.
+* @param seen Tracks already-normalized objects so cyclic values keep their
+*             shape.
+* @returns The original value when no delegated carriers are present, or a
+*          normalized clone with delegated carriers removed.
+* @internal
+*/
+function normalizeNestedDelegatedAnnotationState(value, seen = /* @__PURE__ */ new WeakMap()) {
+	const normalized = normalizeDelegatedAnnotationState(value);
+	if (normalized == null || typeof normalized !== "object") return normalized;
+	const source = normalized;
+	if (seen.has(source)) return seen.get(source);
+	if (Array.isArray(source)) {
+		let changed$1 = false;
+		const clone$1 = [...source];
+		seen.set(source, clone$1);
+		for (let i = 0; i < source.length; i++) {
+			const nextValue = normalizeNestedDelegatedAnnotationState(source[i], seen);
+			if (nextValue !== source[i]) {
+				clone$1[i] = nextValue;
+				changed$1 = true;
+			}
+		}
+		if (!changed$1) {
+			seen.set(source, source);
+			return source;
+		}
+		return clone$1;
+	}
+	const proto = Object.getPrototypeOf(source);
+	if (proto !== Object.prototype && proto !== null) return normalized;
+	const descriptors = Object.getOwnPropertyDescriptors(source);
+	let changed = false;
+	const clone = Object.create(proto);
+	seen.set(source, clone);
+	for (const key of Reflect.ownKeys(descriptors)) {
+		const descriptor = descriptors[key];
+		if (descriptor != null && "value" in descriptor) {
+			const nextValue = normalizeNestedDelegatedAnnotationState(descriptor.value, seen);
+			if (nextValue !== descriptor.value) {
+				descriptors[key] = {
+					...descriptor,
+					value: nextValue
+				};
+				changed = true;
+			}
+		}
+	}
+	if (!changed) {
+		seen.set(source, source);
+		return source;
+	}
+	Object.defineProperties(clone, descriptors);
+	return clone;
+}
+/**
+* Creates a short-lived delegated state that exposes the parent's annotations
+* regardless of the child state's runtime shape.
+*
+* Primitive and nullish states use `injectAnnotations()`, plain objects and
+* built-ins use `inheritAnnotations()`, and non-plain objects use an
+* annotation-view proxy so class invariants such as private fields remain
+* intact.
+*
+* @param parentState The state carrying the annotations to delegate.
+* @param childState The child state that should observe those annotations.
+* @returns A delegated child state that exposes the parent's annotations.
+* @internal
+*/
+function getDelegatedAnnotationState(parentState, childState) {
+	const annotations = require_annotations.getAnnotations(parentState);
+	if (annotations === void 0 || require_annotations.getAnnotations(childState) === annotations) return childState;
+	if (childState == null || typeof childState !== "object") return require_annotations.injectAnnotations(childState, annotations);
+	if (require_annotations.isInjectedAnnotationWrapper(childState)) return require_annotations.injectAnnotations(normalizeInjectedAnnotationState(childState), annotations);
+	if (isNonPlainDelegatedObject(childState)) return withAnnotationView(childState, annotations);
+	return require_annotations.inheritAnnotations(parentState, childState);
+}
 /**
 * Returns whether a state is still at the initial sentinel after normalizing
 * Optique's injected annotation wrapper.
@@ -143,9 +258,13 @@ function reconcileObjectChildState(parentState, childState) {
 
 //#endregion
 exports.annotationViewTargets = annotationViewTargets;
+exports.getDelegatedAnnotationState = getDelegatedAnnotationState;
 exports.getWrappedChildParseState = getWrappedChildParseState;
 exports.getWrappedChildState = getWrappedChildState;
+exports.hasDelegatedAnnotationCarrier = hasDelegatedAnnotationCarrier;
 exports.isAnnotationWrappedInitialState = isAnnotationWrappedInitialState;
+exports.normalizeDelegatedAnnotationState = normalizeDelegatedAnnotationState;
 exports.normalizeInjectedAnnotationState = normalizeInjectedAnnotationState;
+exports.normalizeNestedDelegatedAnnotationState = normalizeNestedDelegatedAnnotationState;
 exports.reconcileObjectChildState = reconcileObjectChildState;
 exports.unwrapAnnotationView = unwrapAnnotationView;

package/dist/annotation-state.js

@@ -1,4 +1,4 @@
-import { annotationKey, getAnnotations, inheritAnnotations, injectAnnotations, unwrapInjectedAnnotationWrapper } from "./annotations.js";
+import { annotationKey, getAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper } from "./annotations.js";
 import { inheritParentAnnotationsKey } from "./parser.js";
 
 //#region src/annotation-state.ts
@@ -58,6 +58,121 @@ function withAnnotationView(state, annotations) {
 function normalizeInjectedAnnotationState(state) {
 	return unwrapInjectedAnnotationWrapper(state);
 }
+function isNonPlainDelegatedObject(state) {
+	if (Array.isArray(state) || state instanceof Date || state instanceof Map || state instanceof Set || state instanceof RegExp) return false;
+	const proto = Object.getPrototypeOf(state);
+	return proto !== Object.prototype && proto !== null;
+}
+/**
+* Removes Optique's internal annotation carriers from a delegated state.
+*
+* This unwraps both primitive-state annotation wrappers and annotation-view
+* proxies used for non-plain object states.
+*
+* @param state The delegated state to normalize.
+* @returns The original underlying state value.
+* @internal
+*/
+function normalizeDelegatedAnnotationState(state) {
+	return normalizeInjectedAnnotationState(unwrapAnnotationView(state));
+}
+/**
+* Returns whether the given state uses an internal delegated annotation carrier.
+*
+* @param state The candidate state to inspect.
+* @returns `true` when the state is an injected primitive wrapper or an
+*          annotation-view proxy.
+* @internal
+*/
+function hasDelegatedAnnotationCarrier(state) {
+	return state != null && typeof state === "object" && (isInjectedAnnotationWrapper(state) || annotationViewTargets.has(state));
+}
+/**
+* Recursively removes delegated annotation carriers from plain-object and array
+* structures.
+*
+* Nested plain objects and arrays are shallow-cloned only when a delegated
+* carrier is found below them. Non-plain objects are unwrapped at the top
+* level and then preserved as-is to avoid mutating or reconstructing class
+* instances.
+*
+* @param value The candidate value to normalize.
+* @param seen Tracks already-normalized objects so cyclic values keep their
+*             shape.
+* @returns The original value when no delegated carriers are present, or a
+*          normalized clone with delegated carriers removed.
+* @internal
+*/
+function normalizeNestedDelegatedAnnotationState(value, seen = /* @__PURE__ */ new WeakMap()) {
+	const normalized = normalizeDelegatedAnnotationState(value);
+	if (normalized == null || typeof normalized !== "object") return normalized;
+	const source = normalized;
+	if (seen.has(source)) return seen.get(source);
+	if (Array.isArray(source)) {
+		let changed$1 = false;
+		const clone$1 = [...source];
+		seen.set(source, clone$1);
+		for (let i = 0; i < source.length; i++) {
+			const nextValue = normalizeNestedDelegatedAnnotationState(source[i], seen);
+			if (nextValue !== source[i]) {
+				clone$1[i] = nextValue;
+				changed$1 = true;
+			}
+		}
+		if (!changed$1) {
+			seen.set(source, source);
+			return source;
+		}
+		return clone$1;
+	}
+	const proto = Object.getPrototypeOf(source);
+	if (proto !== Object.prototype && proto !== null) return normalized;
+	const descriptors = Object.getOwnPropertyDescriptors(source);
+	let changed = false;
+	const clone = Object.create(proto);
+	seen.set(source, clone);
+	for (const key of Reflect.ownKeys(descriptors)) {
+		const descriptor = descriptors[key];
+		if (descriptor != null && "value" in descriptor) {
+			const nextValue = normalizeNestedDelegatedAnnotationState(descriptor.value, seen);
+			if (nextValue !== descriptor.value) {
+				descriptors[key] = {
+					...descriptor,
+					value: nextValue
+				};
+				changed = true;
+			}
+		}
+	}
+	if (!changed) {
+		seen.set(source, source);
+		return source;
+	}
+	Object.defineProperties(clone, descriptors);
+	return clone;
+}
+/**
+* Creates a short-lived delegated state that exposes the parent's annotations
+* regardless of the child state's runtime shape.
+*
+* Primitive and nullish states use `injectAnnotations()`, plain objects and
+* built-ins use `inheritAnnotations()`, and non-plain objects use an
+* annotation-view proxy so class invariants such as private fields remain
+* intact.
+*
+* @param parentState The state carrying the annotations to delegate.
+* @param childState The child state that should observe those annotations.
+* @returns A delegated child state that exposes the parent's annotations.
+* @internal
+*/
+function getDelegatedAnnotationState(parentState, childState) {
+	const annotations = getAnnotations(parentState);
+	if (annotations === void 0 || getAnnotations(childState) === annotations) return childState;
+	if (childState == null || typeof childState !== "object") return injectAnnotations(childState, annotations);
+	if (isInjectedAnnotationWrapper(childState)) return injectAnnotations(normalizeInjectedAnnotationState(childState), annotations);
+	if (isNonPlainDelegatedObject(childState)) return withAnnotationView(childState, annotations);
+	return inheritAnnotations(parentState, childState);
+}
 /**
 * Returns whether a state is still at the initial sentinel after normalizing
 * Optique's injected annotation wrapper.
@@ -142,4 +257,4 @@ function reconcileObjectChildState(parentState, childState) {
 }
 
 //#endregion
-export { annotationViewTargets, getWrappedChildParseState, getWrappedChildState, isAnnotationWrappedInitialState, normalizeInjectedAnnotationState, reconcileObjectChildState, unwrapAnnotationView };
+export { annotationViewTargets, getDelegatedAnnotationState, getWrappedChildParseState, getWrappedChildState, hasDelegatedAnnotationCarrier, isAnnotationWrappedInitialState, normalizeDelegatedAnnotationState, normalizeInjectedAnnotationState, normalizeNestedDelegatedAnnotationState, reconcileObjectChildState, unwrapAnnotationView };

package/dist/modifiers.cjs

@@ -4,6 +4,7 @@ const require_mode_dispatch = require('./mode-dispatch.cjs');
 const require_dependency_metadata = require('./dependency-metadata.cjs');
 const require_phase2_seed = require('./phase2-seed.cjs');
 const require_parser = require('./parser.cjs');
+const require_annotation_state = require('./annotation-state.cjs');
 
 //#region src/modifiers.ts
 function withChildExecPath(exec, segment) {
@@ -81,9 +82,77 @@ function unwrapMultipleItemState(state) {
 function isPromiseLike(value) {
 	return value != null && (typeof value === "object" || typeof value === "function") && "then" in value && typeof value.then === "function";
 }
+function normalizeOptionalLikeCompleteResult(result) {
+	return result.success ? {
+		...result,
+		value: require_annotation_state.normalizeNestedDelegatedAnnotationState(result.value)
+	} : result;
+}
+function completeOptionalLikeSync(parser, state, exec) {
+	const hasCarrier = require_annotation_state.hasDelegatedAnnotationCarrier(state);
+	try {
+		return normalizeOptionalLikeCompleteResult(parser.complete(state, exec));
+	} catch (error) {
+		if (!hasCarrier) throw error;
+		const fallbackState = require_annotation_state.normalizeDelegatedAnnotationState(state);
+		return normalizeOptionalLikeCompleteResult(parser.complete(fallbackState, exec));
+	}
+}
+async function completeOptionalLikeAsync(parser, state, exec) {
+	const hasCarrier = require_annotation_state.hasDelegatedAnnotationCarrier(state);
+	try {
+		return normalizeOptionalLikeCompleteResult(await parser.complete(state, exec));
+	} catch (error) {
+		if (!hasCarrier) throw error;
+		const fallbackState = require_annotation_state.normalizeDelegatedAnnotationState(state);
+		return normalizeOptionalLikeCompleteResult(await parser.complete(fallbackState, exec));
+	}
+}
+function normalizeOptionalLikePhase2Seed(seed) {
+	return seed == null ? null : {
+		...seed,
+		value: require_annotation_state.normalizeNestedDelegatedAnnotationState(seed.value)
+	};
+}
 function extractOptionalLikePhase2Seed(parser, state, exec) {
 	if (!Array.isArray(state) && !(state != null && typeof state === "object")) return require_mode_dispatch.wrapForMode(parser.$mode, null);
-	return require_phase2_seed.completeOrExtractPhase2Seed(parser, normalizeOptionalLikeInnerState(state, parser.initialState, parser), exec);
+	const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
+	const hasCarrier = require_annotation_state.hasDelegatedAnnotationCarrier(innerState);
+	return require_mode_dispatch.dispatchByMode(parser.$mode, () => {
+		try {
+			const result = parser.complete(innerState, exec);
+			if (result.success) return normalizeOptionalLikePhase2Seed(require_phase2_seed.phase2SeedFromValueResult(result));
+			const seed = require_phase2_seed.extractPhase2Seed(parser, innerState, exec);
+			if (seed == null && hasCarrier) {
+				const fallbackState = require_annotation_state.normalizeDelegatedAnnotationState(innerState);
+				return normalizeOptionalLikePhase2Seed(require_phase2_seed.extractPhase2Seed(parser, fallbackState, exec));
+			}
+			return normalizeOptionalLikePhase2Seed(seed);
+		} catch (error) {
+			if (!hasCarrier) throw error;
+			const fallbackState = require_annotation_state.normalizeDelegatedAnnotationState(innerState);
+			const result = parser.complete(fallbackState, exec);
+			if (result.success) return normalizeOptionalLikePhase2Seed(require_phase2_seed.phase2SeedFromValueResult(result));
+			return normalizeOptionalLikePhase2Seed(require_phase2_seed.extractPhase2Seed(parser, fallbackState, exec));
+		}
+	}, async () => {
+		try {
+			const result = await parser.complete(innerState, exec);
+			if (result.success) return normalizeOptionalLikePhase2Seed(require_phase2_seed.phase2SeedFromValueResult(result));
+			const seed = await require_phase2_seed.extractPhase2Seed(parser, innerState, exec);
+			if (seed == null && hasCarrier) {
+				const fallbackState = require_annotation_state.normalizeDelegatedAnnotationState(innerState);
+				return normalizeOptionalLikePhase2Seed(await require_phase2_seed.extractPhase2Seed(parser, fallbackState, exec));
+			}
+			return normalizeOptionalLikePhase2Seed(seed);
+		} catch (error) {
+			if (!hasCarrier) throw error;
+			const fallbackState = require_annotation_state.normalizeDelegatedAnnotationState(innerState);
+			const result = await parser.complete(fallbackState, exec);
+			if (result.success) return normalizeOptionalLikePhase2Seed(require_phase2_seed.phase2SeedFromValueResult(result));
+			return normalizeOptionalLikePhase2Seed(await require_phase2_seed.extractPhase2Seed(parser, fallbackState, exec));
+		}
+	});
 }
 /**
 * Computes the inner state to pass through to the wrapped parser inside
@@ -182,7 +251,15 @@ function processOptionalStyleResult(result, innerState, context) {
 */
 function adaptShouldDeferCompletion(innerCheck, parser) {
 	return (state, exec) => {
-		if (Array.isArray(state) || state != null && typeof state === "object") return innerCheck(normalizeOptionalLikeInnerState(state, parser.initialState, parser), exec);
+		if (Array.isArray(state) || state != null && typeof state === "object") {
+			const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
+			try {
+				return innerCheck(innerState, exec);
+			} catch (error) {
+				if (!require_annotation_state.hasDelegatedAnnotationCarrier(innerState)) throw error;
+				return innerCheck(require_annotation_state.normalizeDelegatedAnnotationState(innerState), exec);
+			}
+		}
 		return false;
 	};
 }
@@ -192,9 +269,9 @@ function isAnnotationOnlyObjectState(state) {
 	return require_annotations.getAnnotations(state) != null && keys.length === 1 && keys[0] === require_annotations.annotationKey;
 }
 function normalizeOptionalLikeInnerState(state, initialState, parser) {
-	if (Array.isArray(state)) return require_annotations.getAnnotations(state) != null && state[0] != null && typeof state[0] === "object" ? require_annotations.inheritAnnotations(state, state[0]) : state[0];
+	if (Array.isArray(state)) return require_annotation_state.getDelegatedAnnotationState(state, state[0]);
 	if (isAnnotationOnlyObjectState(state)) {
-		if (parser != null && (parser.dependencyMetadata?.source != null || typeof parser.shouldDeferCompletion === "function")) return require_annotations.inheritAnnotations(state, initialState);
+		if (parser != null && (parser.dependencyMetadata?.source != null || typeof parser.shouldDeferCompletion === "function")) return require_annotation_state.getDelegatedAnnotationState(state, initialState);
 		return initialState;
 	}
 	if (state != null && typeof state === "object") return state;
@@ -266,7 +343,7 @@ function optional(parser) {
 		complete(state, exec) {
 			if (!Array.isArray(state)) {
 				const delegateToInner = (resolvedInnerState) => {
-					const innerResult = require_mode_dispatch.dispatchByMode(parser.$mode, () => syncParser.complete(resolvedInnerState, exec), async () => await parser.complete(resolvedInnerState, exec));
+					const innerResult = require_mode_dispatch.dispatchByMode(parser.$mode, () => completeOptionalLikeSync(syncParser, resolvedInnerState, exec), async () => await completeOptionalLikeAsync(parser, resolvedInnerState, exec));
 					return require_mode_dispatch.mapModeValue(parser.$mode, innerResult, (result) => result.success ? result : {
 						success: true,
 						value: void 0
@@ -279,7 +356,7 @@ function optional(parser) {
 				const sourceMetadata = parser.dependencyMetadata?.source;
 				if (sourceMetadata?.preservesSourceValue !== false && sourceMetadata?.getMissingSourceValue != null) {
 					const delegatedState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
-					return require_mode_dispatch.dispatchByMode(parser.$mode, () => syncParser.complete(delegatedState, exec), async () => await parser.complete(delegatedState, exec));
+					return require_mode_dispatch.dispatchByMode(parser.$mode, () => completeOptionalLikeSync(syncParser, delegatedState, exec), async () => await completeOptionalLikeAsync(parser, delegatedState, exec));
 				}
 				if (parser[require_parser.unmatchedNonCliDependencySourceStateMarker] === true && state != null && typeof state === "object") {
 					const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
@@ -291,7 +368,7 @@ function optional(parser) {
 				};
 			}
 			const innerElement = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
-			return require_mode_dispatch.dispatchByMode(parser.$mode, () => syncParser.complete(innerElement, exec), async () => await parser.complete(innerElement, exec));
+			return require_mode_dispatch.dispatchByMode(parser.$mode, () => completeOptionalLikeSync(syncParser, innerElement, exec), async () => await completeOptionalLikeAsync(parser, innerElement, exec));
 		},
 		suggest(context, prefix) {
 			return require_mode_dispatch.dispatchIterableByMode(parser.$mode, () => suggestSync(context, prefix), () => suggestAsync(context, prefix));
@@ -442,12 +519,12 @@ function withDefault(parser, defaultValue, options) {
 			if (!Array.isArray(state)) {
 				if (typeof parser.shouldDeferCompletion === "function" && state != null && typeof state === "object") {
 					const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
-					const innerResult = require_mode_dispatch.dispatchByMode(parser.$mode, () => syncParser.complete(innerState, exec), async () => await parser.complete(innerState, exec));
+					const innerResult = require_mode_dispatch.dispatchByMode(parser.$mode, () => completeOptionalLikeSync(syncParser, innerState, exec), async () => await completeOptionalLikeAsync(parser, innerState, exec));
 					return innerResult;
 				}
 				if (parser[require_parser.unmatchedNonCliDependencySourceStateMarker] === true && state != null && typeof state === "object") {
 					const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
-					const innerResult = require_mode_dispatch.dispatchByMode(parser.$mode, () => syncParser.complete(innerState, exec), async () => await parser.complete(innerState, exec));
+					const innerResult = require_mode_dispatch.dispatchByMode(parser.$mode, () => completeOptionalLikeSync(syncParser, innerState, exec), async () => await completeOptionalLikeAsync(parser, innerState, exec));
 					const handleInnerResult = (result) => {
 						if (result.success && result.value !== void 0) return result;
 						try {
@@ -478,7 +555,7 @@ function withDefault(parser, defaultValue, options) {
 				}
 			}
 			const innerElement = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
-			return require_mode_dispatch.dispatchByMode(parser.$mode, () => syncParser.complete(innerElement, exec), async () => await parser.complete(innerElement, exec));
+			return require_mode_dispatch.dispatchByMode(parser.$mode, () => completeOptionalLikeSync(syncParser, innerElement, exec), async () => await completeOptionalLikeAsync(parser, innerElement, exec));
 		},
 		suggest(context, prefix) {
 			return require_mode_dispatch.dispatchIterableByMode(parser.$mode, () => suggestSync(context, prefix), () => suggestAsync(context, prefix));

package/dist/modifiers.js

@@ -2,8 +2,9 @@ import { annotateFreshArray, annotationKey, getAnnotations, inheritAnnotations,
 import { formatMessage, message, text } from "./message.js";
 import { dispatchByMode, dispatchIterableByMode, mapModeValue, wrapForMode } from "./mode-dispatch.js";
 import { composeDependencyMetadata } from "./dependency-metadata.js";
-import { completeOrExtractPhase2Seed, extractPhase2Seed, extractPhase2SeedKey } from "./phase2-seed.js";
+import { completeOrExtractPhase2Seed, extractPhase2Seed, extractPhase2SeedKey, phase2SeedFromValueResult } from "./phase2-seed.js";
 import { defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, unmatchedNonCliDependencySourceStateMarker } from "./parser.js";
+import { getDelegatedAnnotationState, hasDelegatedAnnotationCarrier, normalizeDelegatedAnnotationState, normalizeNestedDelegatedAnnotationState } from "./annotation-state.js";
 
 //#region src/modifiers.ts
 function withChildExecPath(exec, segment) {
@@ -81,9 +82,77 @@ function unwrapMultipleItemState(state) {
 function isPromiseLike(value) {
 	return value != null && (typeof value === "object" || typeof value === "function") && "then" in value && typeof value.then === "function";
 }
+function normalizeOptionalLikeCompleteResult(result) {
+	return result.success ? {
+		...result,
+		value: normalizeNestedDelegatedAnnotationState(result.value)
+	} : result;
+}
+function completeOptionalLikeSync(parser, state, exec) {
+	const hasCarrier = hasDelegatedAnnotationCarrier(state);
+	try {
+		return normalizeOptionalLikeCompleteResult(parser.complete(state, exec));
+	} catch (error) {
+		if (!hasCarrier) throw error;
+		const fallbackState = normalizeDelegatedAnnotationState(state);
+		return normalizeOptionalLikeCompleteResult(parser.complete(fallbackState, exec));
+	}
+}
+async function completeOptionalLikeAsync(parser, state, exec) {
+	const hasCarrier = hasDelegatedAnnotationCarrier(state);
+	try {
+		return normalizeOptionalLikeCompleteResult(await parser.complete(state, exec));
+	} catch (error) {
+		if (!hasCarrier) throw error;
+		const fallbackState = normalizeDelegatedAnnotationState(state);
+		return normalizeOptionalLikeCompleteResult(await parser.complete(fallbackState, exec));
+	}
+}
+function normalizeOptionalLikePhase2Seed(seed) {
+	return seed == null ? null : {
+		...seed,
+		value: normalizeNestedDelegatedAnnotationState(seed.value)
+	};
+}
 function extractOptionalLikePhase2Seed(parser, state, exec) {
 	if (!Array.isArray(state) && !(state != null && typeof state === "object")) return wrapForMode(parser.$mode, null);
-	return completeOrExtractPhase2Seed(parser, normalizeOptionalLikeInnerState(state, parser.initialState, parser), exec);
+	const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
+	const hasCarrier = hasDelegatedAnnotationCarrier(innerState);
+	return dispatchByMode(parser.$mode, () => {
+		try {
+			const result = parser.complete(innerState, exec);
+			if (result.success) return normalizeOptionalLikePhase2Seed(phase2SeedFromValueResult(result));
+			const seed = extractPhase2Seed(parser, innerState, exec);
+			if (seed == null && hasCarrier) {
+				const fallbackState = normalizeDelegatedAnnotationState(innerState);
+				return normalizeOptionalLikePhase2Seed(extractPhase2Seed(parser, fallbackState, exec));
+			}
+			return normalizeOptionalLikePhase2Seed(seed);
+		} catch (error) {
+			if (!hasCarrier) throw error;
+			const fallbackState = normalizeDelegatedAnnotationState(innerState);
+			const result = parser.complete(fallbackState, exec);
+			if (result.success) return normalizeOptionalLikePhase2Seed(phase2SeedFromValueResult(result));
+			return normalizeOptionalLikePhase2Seed(extractPhase2Seed(parser, fallbackState, exec));
+		}
+	}, async () => {
+		try {
+			const result = await parser.complete(innerState, exec);
+			if (result.success) return normalizeOptionalLikePhase2Seed(phase2SeedFromValueResult(result));
+			const seed = await extractPhase2Seed(parser, innerState, exec);
+			if (seed == null && hasCarrier) {
+				const fallbackState = normalizeDelegatedAnnotationState(innerState);
+				return normalizeOptionalLikePhase2Seed(await extractPhase2Seed(parser, fallbackState, exec));
+			}
+			return normalizeOptionalLikePhase2Seed(seed);
+		} catch (error) {
+			if (!hasCarrier) throw error;
+			const fallbackState = normalizeDelegatedAnnotationState(innerState);
+			const result = await parser.complete(fallbackState, exec);
+			if (result.success) return normalizeOptionalLikePhase2Seed(phase2SeedFromValueResult(result));
+			return normalizeOptionalLikePhase2Seed(await extractPhase2Seed(parser, fallbackState, exec));
+		}
+	});
 }
 /**
 * Computes the inner state to pass through to the wrapped parser inside
@@ -182,7 +251,15 @@ function processOptionalStyleResult(result, innerState, context) {
 */
 function adaptShouldDeferCompletion(innerCheck, parser) {
 	return (state, exec) => {
-		if (Array.isArray(state) || state != null && typeof state === "object") return innerCheck(normalizeOptionalLikeInnerState(state, parser.initialState, parser), exec);
+		if (Array.isArray(state) || state != null && typeof state === "object") {
+			const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
+			try {
+				return innerCheck(innerState, exec);
+			} catch (error) {
+				if (!hasDelegatedAnnotationCarrier(innerState)) throw error;
+				return innerCheck(normalizeDelegatedAnnotationState(innerState), exec);
+			}
+		}
 		return false;
 	};
 }
@@ -192,9 +269,9 @@ function isAnnotationOnlyObjectState(state) {
 	return getAnnotations(state) != null && keys.length === 1 && keys[0] === annotationKey;
 }
 function normalizeOptionalLikeInnerState(state, initialState, parser) {
-	if (Array.isArray(state)) return getAnnotations(state) != null && state[0] != null && typeof state[0] === "object" ? inheritAnnotations(state, state[0]) : state[0];
+	if (Array.isArray(state)) return getDelegatedAnnotationState(state, state[0]);
 	if (isAnnotationOnlyObjectState(state)) {
-		if (parser != null && (parser.dependencyMetadata?.source != null || typeof parser.shouldDeferCompletion === "function")) return inheritAnnotations(state, initialState);
+		if (parser != null && (parser.dependencyMetadata?.source != null || typeof parser.shouldDeferCompletion === "function")) return getDelegatedAnnotationState(state, initialState);
 		return initialState;
 	}
 	if (state != null && typeof state === "object") return state;
@@ -266,7 +343,7 @@ function optional(parser) {
 		complete(state, exec) {
 			if (!Array.isArray(state)) {
 				const delegateToInner = (resolvedInnerState) => {
-					const innerResult = dispatchByMode(parser.$mode, () => syncParser.complete(resolvedInnerState, exec), async () => await parser.complete(resolvedInnerState, exec));
+					const innerResult = dispatchByMode(parser.$mode, () => completeOptionalLikeSync(syncParser, resolvedInnerState, exec), async () => await completeOptionalLikeAsync(parser, resolvedInnerState, exec));
 					return mapModeValue(parser.$mode, innerResult, (result) => result.success ? result : {
 						success: true,
 						value: void 0
@@ -279,7 +356,7 @@ function optional(parser) {
 				const sourceMetadata = parser.dependencyMetadata?.source;
 				if (sourceMetadata?.preservesSourceValue !== false && sourceMetadata?.getMissingSourceValue != null) {
 					const delegatedState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
-					return dispatchByMode(parser.$mode, () => syncParser.complete(delegatedState, exec), async () => await parser.complete(delegatedState, exec));
+					return dispatchByMode(parser.$mode, () => completeOptionalLikeSync(syncParser, delegatedState, exec), async () => await completeOptionalLikeAsync(parser, delegatedState, exec));
 				}
 				if (parser[unmatchedNonCliDependencySourceStateMarker] === true && state != null && typeof state === "object") {
 					const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
@@ -291,7 +368,7 @@ function optional(parser) {
 				};
 			}
 			const innerElement = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
-			return dispatchByMode(parser.$mode, () => syncParser.complete(innerElement, exec), async () => await parser.complete(innerElement, exec));
+			return dispatchByMode(parser.$mode, () => completeOptionalLikeSync(syncParser, innerElement, exec), async () => await completeOptionalLikeAsync(parser, innerElement, exec));
 		},
 		suggest(context, prefix) {
 			return dispatchIterableByMode(parser.$mode, () => suggestSync(context, prefix), () => suggestAsync(context, prefix));
@@ -442,12 +519,12 @@ function withDefault(parser, defaultValue, options) {
 			if (!Array.isArray(state)) {
 				if (typeof parser.shouldDeferCompletion === "function" && state != null && typeof state === "object") {
 					const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
-					const innerResult = dispatchByMode(parser.$mode, () => syncParser.complete(innerState, exec), async () => await parser.complete(innerState, exec));
+					const innerResult = dispatchByMode(parser.$mode, () => completeOptionalLikeSync(syncParser, innerState, exec), async () => await completeOptionalLikeAsync(parser, innerState, exec));
 					return innerResult;
 				}
 				if (parser[unmatchedNonCliDependencySourceStateMarker] === true && state != null && typeof state === "object") {
 					const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
-					const innerResult = dispatchByMode(parser.$mode, () => syncParser.complete(innerState, exec), async () => await parser.complete(innerState, exec));
+					const innerResult = dispatchByMode(parser.$mode, () => completeOptionalLikeSync(syncParser, innerState, exec), async () => await completeOptionalLikeAsync(parser, innerState, exec));
 					const handleInnerResult = (result) => {
 						if (result.success && result.value !== void 0) return result;
 						try {
@@ -478,7 +555,7 @@ function withDefault(parser, defaultValue, options) {
 				}
 			}
 			const innerElement = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
-			return dispatchByMode(parser.$mode, () => syncParser.complete(innerElement, exec), async () => await parser.complete(innerElement, exec));
+			return dispatchByMode(parser.$mode, () => completeOptionalLikeSync(syncParser, innerElement, exec), async () => await completeOptionalLikeAsync(parser, innerElement, exec));
 		},
 		suggest(context, prefix) {
 			return dispatchIterableByMode(parser.$mode, () => suggestSync(context, prefix), () => suggestAsync(context, prefix));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.1890+0291e3fc",
+  "version": "1.0.0-dev.1893+e1c35f1a",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",