@optique/core 1.0.0-dev.1899 → 1.0.0-dev.1903

package/dist/annotation-state.cjs

@@ -87,33 +87,36 @@ function normalizeDelegatedAnnotationState(state) {
 function hasDelegatedAnnotationCarrier(state) {
 	return state != null && typeof state === "object" && (require_annotations.isInjectedAnnotationWrapper(state) || annotationViewTargets.has(state));
 }
-function isPendingNestedNormalizationAlias(originalValue, normalizedValue, seen) {
-	if (originalValue == null || typeof originalValue !== "object") return false;
+function getPendingNestedNormalizationEntry(originalValue, normalizedValue, seen) {
+	if (originalValue == null || typeof originalValue !== "object") return void 0;
 	const entry = seen.get(originalValue);
-	return entry != null && !entry.finalized && entry.clone === normalizedValue;
+	return entry != null && entry.clone === normalizedValue && (!entry.finalized || entry.preferCloneOnRead) ? entry : void 0;
 }
 function createPendingNestedNormalizationClone(source) {
 	return Array.isArray(source) ? [] : Object.create(Object.getPrototypeOf(source));
 }
-function normalizeNestedDelegatedStructuredState(source, seen) {
+function normalizeNestedDelegatedStructuredState(source, seen, preferPendingClone) {
 	const clone = createPendingNestedNormalizationClone(source);
 	const entry = {
 		clone,
 		finalized: false,
-		result: clone
+		result: clone,
+		preferCloneOnRead: false
 	};
 	seen.set(source, entry);
 	const overrides = /* @__PURE__ */ new Map();
 	let changed = false;
+	let hasPendingAliasOverride = false;
 	for (const key of Reflect.ownKeys(source)) {
 		const descriptor = Object.getOwnPropertyDescriptor(source, key);
 		if (descriptor == null || !("value" in descriptor)) continue;
-		const nextValue = normalizeNestedDelegatedAnnotationState(descriptor.value, seen);
+		const nextValue = normalizeNestedDelegatedAnnotationState(descriptor.value, seen, true);
 		if (nextValue === descriptor.value) continue;
 		overrides.set(key, nextValue);
-		if (!isPendingNestedNormalizationAlias(descriptor.value, nextValue, seen)) changed = true;
+		if (getPendingNestedNormalizationEntry(descriptor.value, nextValue, seen) == null) changed = true;
+		else hasPendingAliasOverride = true;
 	}
-	if (!changed) {
+	if (!changed && !hasPendingAliasOverride) {
 		entry.finalized = true;
 		entry.result = source;
 		return source;
@@ -129,17 +132,120 @@ function normalizeNestedDelegatedStructuredState(source, seen) {
 	}
 	Object.defineProperties(clone, descriptors);
 	entry.finalized = true;
-	entry.result = clone;
-	return clone;
+	entry.preferCloneOnRead = !changed && hasPendingAliasOverride;
+	entry.result = changed ? clone : source;
+	return changed || preferPendingClone ? clone : source;
+}
+function normalizeNestedDelegatedMapState(source, seen, preferPendingClone) {
+	const clone = /* @__PURE__ */ new Map();
+	const entry = {
+		clone,
+		finalized: false,
+		result: clone,
+		preferCloneOnRead: false
+	};
+	seen.set(source, entry);
+	const normalizedEntries = [];
+	const overrides = /* @__PURE__ */ new Map();
+	let changed = false;
+	let hasPendingAliasOverride = false;
+	for (const [key, value] of source) {
+		const nextKey = normalizeNestedDelegatedAnnotationState(key, seen, true);
+		const nextValue = normalizeNestedDelegatedAnnotationState(value, seen, true);
+		normalizedEntries.push([nextKey, nextValue]);
+		if (nextKey !== key) if (getPendingNestedNormalizationEntry(key, nextKey, seen) == null) changed = true;
+		else hasPendingAliasOverride = true;
+		if (nextValue !== value) if (getPendingNestedNormalizationEntry(value, nextValue, seen) == null) changed = true;
+		else hasPendingAliasOverride = true;
+	}
+	for (const key of Reflect.ownKeys(source)) {
+		const descriptor = Object.getOwnPropertyDescriptor(source, key);
+		if (descriptor == null || !("value" in descriptor)) continue;
+		const nextValue = normalizeNestedDelegatedAnnotationState(descriptor.value, seen, true);
+		if (nextValue === descriptor.value) continue;
+		overrides.set(key, nextValue);
+		if (getPendingNestedNormalizationEntry(descriptor.value, nextValue, seen) == null) changed = true;
+		else hasPendingAliasOverride = true;
+	}
+	if (!changed && !hasPendingAliasOverride) {
+		entry.finalized = true;
+		entry.result = source;
+		return source;
+	}
+	for (const [key, value] of normalizedEntries) clone.set(key, value);
+	const descriptors = Object.getOwnPropertyDescriptors(source);
+	for (const [key, nextValue] of overrides) {
+		const descriptor = descriptors[key];
+		if (descriptor == null || !("value" in descriptor)) continue;
+		descriptors[key] = {
+			...descriptor,
+			value: nextValue
+		};
+	}
+	Object.defineProperties(clone, descriptors);
+	entry.finalized = true;
+	entry.preferCloneOnRead = !changed && hasPendingAliasOverride;
+	entry.result = changed ? clone : source;
+	return changed || preferPendingClone ? clone : source;
+}
+function normalizeNestedDelegatedSetState(source, seen, preferPendingClone) {
+	const clone = /* @__PURE__ */ new Set();
+	const entry = {
+		clone,
+		finalized: false,
+		result: clone,
+		preferCloneOnRead: false
+	};
+	seen.set(source, entry);
+	const normalizedValues = [];
+	const overrides = /* @__PURE__ */ new Map();
+	let changed = false;
+	let hasPendingAliasOverride = false;
+	for (const value of source) {
+		const nextValue = normalizeNestedDelegatedAnnotationState(value, seen, true);
+		normalizedValues.push(nextValue);
+		if (nextValue === value) continue;
+		if (getPendingNestedNormalizationEntry(value, nextValue, seen) == null) changed = true;
+		else hasPendingAliasOverride = true;
+	}
+	for (const key of Reflect.ownKeys(source)) {
+		const descriptor = Object.getOwnPropertyDescriptor(source, key);
+		if (descriptor == null || !("value" in descriptor)) continue;
+		const nextValue = normalizeNestedDelegatedAnnotationState(descriptor.value, seen, true);
+		if (nextValue === descriptor.value) continue;
+		overrides.set(key, nextValue);
+		if (getPendingNestedNormalizationEntry(descriptor.value, nextValue, seen) == null) changed = true;
+		else hasPendingAliasOverride = true;
+	}
+	if (!changed && !hasPendingAliasOverride) {
+		entry.finalized = true;
+		entry.result = source;
+		return source;
+	}
+	for (const value of normalizedValues) clone.add(value);
+	const descriptors = Object.getOwnPropertyDescriptors(source);
+	for (const [key, nextValue] of overrides) {
+		const descriptor = descriptors[key];
+		if (descriptor == null || !("value" in descriptor)) continue;
+		descriptors[key] = {
+			...descriptor,
+			value: nextValue
+		};
+	}
+	Object.defineProperties(clone, descriptors);
+	entry.finalized = true;
+	entry.preferCloneOnRead = !changed && hasPendingAliasOverride;
+	entry.result = changed ? clone : source;
+	return changed || preferPendingClone ? clone : source;
 }
 /**
-* Recursively removes delegated annotation carriers from plain-object and array
-* structures.
+* Recursively removes delegated annotation carriers from plain-object, array,
+* and built-in collection 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.
+* Nested plain objects, arrays, Maps, and Sets are shallow-cloned only when a
+* delegated carrier is found below them. Other 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
@@ -148,16 +254,21 @@ function normalizeNestedDelegatedStructuredState(source, seen) {
 *          normalized clone with delegated carriers removed.
 * @internal
 */
-function normalizeNestedDelegatedAnnotationState(value, seen = /* @__PURE__ */ new WeakMap()) {
+function normalizeNestedDelegatedAnnotationState(value, seen = /* @__PURE__ */ new WeakMap(), preferPendingClone = false) {
 	const normalized = normalizeDelegatedAnnotationState(value);
 	if (normalized == null || typeof normalized !== "object") return normalized;
 	const source = normalized;
 	const existing = seen.get(source);
-	if (existing != null) return existing.finalized ? existing.result : existing.clone;
-	if (Array.isArray(source)) return normalizeNestedDelegatedStructuredState(source, seen);
+	if (existing != null) {
+		if (!existing.finalized) return existing.clone;
+		return preferPendingClone && existing.preferCloneOnRead ? existing.clone : existing.result;
+	}
+	if (Array.isArray(source)) return normalizeNestedDelegatedStructuredState(source, seen, preferPendingClone);
+	if (source instanceof Map) return normalizeNestedDelegatedMapState(source, seen, preferPendingClone);
+	if (source instanceof Set) return normalizeNestedDelegatedSetState(source, seen, preferPendingClone);
 	const proto = Object.getPrototypeOf(source);
 	if (proto !== Object.prototype && proto !== null) return normalized;
-	return normalizeNestedDelegatedStructuredState(source, seen);
+	return normalizeNestedDelegatedStructuredState(source, seen, preferPendingClone);
 }
 /**
 * Creates a short-lived delegated state that exposes the parent's annotations

package/dist/annotation-state.js

@@ -87,33 +87,36 @@ function normalizeDelegatedAnnotationState(state) {
 function hasDelegatedAnnotationCarrier(state) {
 	return state != null && typeof state === "object" && (isInjectedAnnotationWrapper(state) || annotationViewTargets.has(state));
 }
-function isPendingNestedNormalizationAlias(originalValue, normalizedValue, seen) {
-	if (originalValue == null || typeof originalValue !== "object") return false;
+function getPendingNestedNormalizationEntry(originalValue, normalizedValue, seen) {
+	if (originalValue == null || typeof originalValue !== "object") return void 0;
 	const entry = seen.get(originalValue);
-	return entry != null && !entry.finalized && entry.clone === normalizedValue;
+	return entry != null && entry.clone === normalizedValue && (!entry.finalized || entry.preferCloneOnRead) ? entry : void 0;
 }
 function createPendingNestedNormalizationClone(source) {
 	return Array.isArray(source) ? [] : Object.create(Object.getPrototypeOf(source));
 }
-function normalizeNestedDelegatedStructuredState(source, seen) {
+function normalizeNestedDelegatedStructuredState(source, seen, preferPendingClone) {
 	const clone = createPendingNestedNormalizationClone(source);
 	const entry = {
 		clone,
 		finalized: false,
-		result: clone
+		result: clone,
+		preferCloneOnRead: false
 	};
 	seen.set(source, entry);
 	const overrides = /* @__PURE__ */ new Map();
 	let changed = false;
+	let hasPendingAliasOverride = false;
 	for (const key of Reflect.ownKeys(source)) {
 		const descriptor = Object.getOwnPropertyDescriptor(source, key);
 		if (descriptor == null || !("value" in descriptor)) continue;
-		const nextValue = normalizeNestedDelegatedAnnotationState(descriptor.value, seen);
+		const nextValue = normalizeNestedDelegatedAnnotationState(descriptor.value, seen, true);
 		if (nextValue === descriptor.value) continue;
 		overrides.set(key, nextValue);
-		if (!isPendingNestedNormalizationAlias(descriptor.value, nextValue, seen)) changed = true;
+		if (getPendingNestedNormalizationEntry(descriptor.value, nextValue, seen) == null) changed = true;
+		else hasPendingAliasOverride = true;
 	}
-	if (!changed) {
+	if (!changed && !hasPendingAliasOverride) {
 		entry.finalized = true;
 		entry.result = source;
 		return source;
@@ -129,17 +132,120 @@ function normalizeNestedDelegatedStructuredState(source, seen) {
 	}
 	Object.defineProperties(clone, descriptors);
 	entry.finalized = true;
-	entry.result = clone;
-	return clone;
+	entry.preferCloneOnRead = !changed && hasPendingAliasOverride;
+	entry.result = changed ? clone : source;
+	return changed || preferPendingClone ? clone : source;
+}
+function normalizeNestedDelegatedMapState(source, seen, preferPendingClone) {
+	const clone = /* @__PURE__ */ new Map();
+	const entry = {
+		clone,
+		finalized: false,
+		result: clone,
+		preferCloneOnRead: false
+	};
+	seen.set(source, entry);
+	const normalizedEntries = [];
+	const overrides = /* @__PURE__ */ new Map();
+	let changed = false;
+	let hasPendingAliasOverride = false;
+	for (const [key, value] of source) {
+		const nextKey = normalizeNestedDelegatedAnnotationState(key, seen, true);
+		const nextValue = normalizeNestedDelegatedAnnotationState(value, seen, true);
+		normalizedEntries.push([nextKey, nextValue]);
+		if (nextKey !== key) if (getPendingNestedNormalizationEntry(key, nextKey, seen) == null) changed = true;
+		else hasPendingAliasOverride = true;
+		if (nextValue !== value) if (getPendingNestedNormalizationEntry(value, nextValue, seen) == null) changed = true;
+		else hasPendingAliasOverride = true;
+	}
+	for (const key of Reflect.ownKeys(source)) {
+		const descriptor = Object.getOwnPropertyDescriptor(source, key);
+		if (descriptor == null || !("value" in descriptor)) continue;
+		const nextValue = normalizeNestedDelegatedAnnotationState(descriptor.value, seen, true);
+		if (nextValue === descriptor.value) continue;
+		overrides.set(key, nextValue);
+		if (getPendingNestedNormalizationEntry(descriptor.value, nextValue, seen) == null) changed = true;
+		else hasPendingAliasOverride = true;
+	}
+	if (!changed && !hasPendingAliasOverride) {
+		entry.finalized = true;
+		entry.result = source;
+		return source;
+	}
+	for (const [key, value] of normalizedEntries) clone.set(key, value);
+	const descriptors = Object.getOwnPropertyDescriptors(source);
+	for (const [key, nextValue] of overrides) {
+		const descriptor = descriptors[key];
+		if (descriptor == null || !("value" in descriptor)) continue;
+		descriptors[key] = {
+			...descriptor,
+			value: nextValue
+		};
+	}
+	Object.defineProperties(clone, descriptors);
+	entry.finalized = true;
+	entry.preferCloneOnRead = !changed && hasPendingAliasOverride;
+	entry.result = changed ? clone : source;
+	return changed || preferPendingClone ? clone : source;
+}
+function normalizeNestedDelegatedSetState(source, seen, preferPendingClone) {
+	const clone = /* @__PURE__ */ new Set();
+	const entry = {
+		clone,
+		finalized: false,
+		result: clone,
+		preferCloneOnRead: false
+	};
+	seen.set(source, entry);
+	const normalizedValues = [];
+	const overrides = /* @__PURE__ */ new Map();
+	let changed = false;
+	let hasPendingAliasOverride = false;
+	for (const value of source) {
+		const nextValue = normalizeNestedDelegatedAnnotationState(value, seen, true);
+		normalizedValues.push(nextValue);
+		if (nextValue === value) continue;
+		if (getPendingNestedNormalizationEntry(value, nextValue, seen) == null) changed = true;
+		else hasPendingAliasOverride = true;
+	}
+	for (const key of Reflect.ownKeys(source)) {
+		const descriptor = Object.getOwnPropertyDescriptor(source, key);
+		if (descriptor == null || !("value" in descriptor)) continue;
+		const nextValue = normalizeNestedDelegatedAnnotationState(descriptor.value, seen, true);
+		if (nextValue === descriptor.value) continue;
+		overrides.set(key, nextValue);
+		if (getPendingNestedNormalizationEntry(descriptor.value, nextValue, seen) == null) changed = true;
+		else hasPendingAliasOverride = true;
+	}
+	if (!changed && !hasPendingAliasOverride) {
+		entry.finalized = true;
+		entry.result = source;
+		return source;
+	}
+	for (const value of normalizedValues) clone.add(value);
+	const descriptors = Object.getOwnPropertyDescriptors(source);
+	for (const [key, nextValue] of overrides) {
+		const descriptor = descriptors[key];
+		if (descriptor == null || !("value" in descriptor)) continue;
+		descriptors[key] = {
+			...descriptor,
+			value: nextValue
+		};
+	}
+	Object.defineProperties(clone, descriptors);
+	entry.finalized = true;
+	entry.preferCloneOnRead = !changed && hasPendingAliasOverride;
+	entry.result = changed ? clone : source;
+	return changed || preferPendingClone ? clone : source;
 }
 /**
-* Recursively removes delegated annotation carriers from plain-object and array
-* structures.
+* Recursively removes delegated annotation carriers from plain-object, array,
+* and built-in collection 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.
+* Nested plain objects, arrays, Maps, and Sets are shallow-cloned only when a
+* delegated carrier is found below them. Other 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
@@ -148,16 +254,21 @@ function normalizeNestedDelegatedStructuredState(source, seen) {
 *          normalized clone with delegated carriers removed.
 * @internal
 */
-function normalizeNestedDelegatedAnnotationState(value, seen = /* @__PURE__ */ new WeakMap()) {
+function normalizeNestedDelegatedAnnotationState(value, seen = /* @__PURE__ */ new WeakMap(), preferPendingClone = false) {
 	const normalized = normalizeDelegatedAnnotationState(value);
 	if (normalized == null || typeof normalized !== "object") return normalized;
 	const source = normalized;
 	const existing = seen.get(source);
-	if (existing != null) return existing.finalized ? existing.result : existing.clone;
-	if (Array.isArray(source)) return normalizeNestedDelegatedStructuredState(source, seen);
+	if (existing != null) {
+		if (!existing.finalized) return existing.clone;
+		return preferPendingClone && existing.preferCloneOnRead ? existing.clone : existing.result;
+	}
+	if (Array.isArray(source)) return normalizeNestedDelegatedStructuredState(source, seen, preferPendingClone);
+	if (source instanceof Map) return normalizeNestedDelegatedMapState(source, seen, preferPendingClone);
+	if (source instanceof Set) return normalizeNestedDelegatedSetState(source, seen, preferPendingClone);
 	const proto = Object.getPrototypeOf(source);
 	if (proto !== Object.prototype && proto !== null) return normalized;
-	return normalizeNestedDelegatedStructuredState(source, seen);
+	return normalizeNestedDelegatedStructuredState(source, seen, preferPendingClone);
 }
 /**
 * Creates a short-lived delegated state that exposes the parent's annotations

package/dist/modifiers.cjs

@@ -82,85 +82,102 @@ 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 ? {
+function normalizeOptionalLikeCompleteResult(result, shouldNormalize) {
+	return result.success && shouldNormalize ? {
 		...result,
 		value: require_annotation_state.normalizeNestedDelegatedAnnotationState(result.value)
 	} : result;
 }
 function completeOptionalLikeSync(parser, state, exec) {
 	const hasCarrier = require_annotation_state.hasDelegatedAnnotationCarrier(state);
+	const shouldRetryFalseResult = hasCarrier && require_annotation_state.isAnnotationWrappedInitialState(state);
+	const run = (candidate, shouldNormalize) => normalizeOptionalLikeCompleteResult(parser.complete(candidate, exec), shouldNormalize);
 	try {
-		return normalizeOptionalLikeCompleteResult(parser.complete(state, exec));
+		const result = run(state, hasCarrier);
+		if (!result.success && shouldRetryFalseResult) return run(require_annotation_state.normalizeDelegatedAnnotationState(state), false);
+		return result;
 	} catch (error) {
 		if (!hasCarrier) throw error;
-		const fallbackState = require_annotation_state.normalizeDelegatedAnnotationState(state);
-		return normalizeOptionalLikeCompleteResult(parser.complete(fallbackState, exec));
+		return run(require_annotation_state.normalizeDelegatedAnnotationState(state), false);
 	}
 }
 async function completeOptionalLikeAsync(parser, state, exec) {
 	const hasCarrier = require_annotation_state.hasDelegatedAnnotationCarrier(state);
+	const shouldRetryFalseResult = hasCarrier && require_annotation_state.isAnnotationWrappedInitialState(state);
+	const run = async (candidate, shouldNormalize) => normalizeOptionalLikeCompleteResult(await parser.complete(candidate, exec), shouldNormalize);
 	try {
-		return normalizeOptionalLikeCompleteResult(await parser.complete(state, exec));
+		const result = await run(state, hasCarrier);
+		if (!result.success && shouldRetryFalseResult) return await run(require_annotation_state.normalizeDelegatedAnnotationState(state), false);
+		return result;
 	} catch (error) {
 		if (!hasCarrier) throw error;
-		const fallbackState = require_annotation_state.normalizeDelegatedAnnotationState(state);
-		return normalizeOptionalLikeCompleteResult(await parser.complete(fallbackState, exec));
+		return await run(require_annotation_state.normalizeDelegatedAnnotationState(state), false);
 	}
 }
-function normalizeOptionalLikePhase2Seed(seed) {
-	return seed == null ? null : {
+function normalizeOptionalLikePhase2Seed(seed, shouldNormalize) {
+	return seed == null ? null : shouldNormalize ? {
 		...seed,
 		value: require_annotation_state.normalizeNestedDelegatedAnnotationState(seed.value)
-	};
+	} : seed;
 }
 function extractOptionalLikePhase2Seed(parser, state, exec) {
 	if (!Array.isArray(state) && !(state != null && typeof state === "object")) return require_mode_dispatch.wrapForMode(parser.$mode, null);
 	const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
 	const hasCarrier = require_annotation_state.hasDelegatedAnnotationCarrier(innerState);
+	const shouldRetryFalseResult = hasCarrier && require_annotation_state.isAnnotationWrappedInitialState(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));
+			if (result.success) return normalizeOptionalLikePhase2Seed(require_phase2_seed.phase2SeedFromValueResult(result), hasCarrier);
+			if (shouldRetryFalseResult) {
+				const fallbackState = require_annotation_state.normalizeDelegatedAnnotationState(innerState);
+				const fallbackResult = parser.complete(fallbackState, exec);
+				if (fallbackResult.success) return normalizeOptionalLikePhase2Seed(require_phase2_seed.phase2SeedFromValueResult(fallbackResult), false);
+			}
 			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(require_phase2_seed.extractPhase2Seed(parser, fallbackState, exec), false);
 			}
-			return normalizeOptionalLikePhase2Seed(seed);
+			return normalizeOptionalLikePhase2Seed(seed, hasCarrier);
 		} 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));
+			if (result.success) return normalizeOptionalLikePhase2Seed(require_phase2_seed.phase2SeedFromValueResult(result), false);
+			return normalizeOptionalLikePhase2Seed(require_phase2_seed.extractPhase2Seed(parser, fallbackState, exec), false);
 		}
 	}, async () => {
 		try {
 			const result = await parser.complete(innerState, exec);
-			if (result.success) return normalizeOptionalLikePhase2Seed(require_phase2_seed.phase2SeedFromValueResult(result));
+			if (result.success) return normalizeOptionalLikePhase2Seed(require_phase2_seed.phase2SeedFromValueResult(result), hasCarrier);
+			if (shouldRetryFalseResult) {
+				const fallbackState = require_annotation_state.normalizeDelegatedAnnotationState(innerState);
+				const fallbackResult = await parser.complete(fallbackState, exec);
+				if (fallbackResult.success) return normalizeOptionalLikePhase2Seed(require_phase2_seed.phase2SeedFromValueResult(fallbackResult), false);
+			}
 			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(await require_phase2_seed.extractPhase2Seed(parser, fallbackState, exec), false);
 			}
-			return normalizeOptionalLikePhase2Seed(seed);
+			return normalizeOptionalLikePhase2Seed(seed, hasCarrier);
 		} 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));
+			if (result.success) return normalizeOptionalLikePhase2Seed(require_phase2_seed.phase2SeedFromValueResult(result), false);
+			return normalizeOptionalLikePhase2Seed(await require_phase2_seed.extractPhase2Seed(parser, fallbackState, exec), false);
 		}
 	});
 }
 /**
 * Computes the inner state to pass through to the wrapped parser inside
 * {@link optional} / {@link withDefault}.  When the outer state is an
-* array, the inner state is `state[0]`.  Otherwise — including the
+* array, the inner state is `state[0]`.  Otherwise, including the
 * common case where `optional()` sits at top level and the outer state
 * is either `undefined` or an annotation wrapper from `parseOptionalLike`
-* / `parse({ annotations })` — we use the wrapped parser's
+* / `parse({ annotations })`, we use the wrapped parser's
 * `initialState`, propagating annotations from the outer state so that
 * source-binding wrappers under `optional()` / `withDefault()` (e.g.,
 * `bindEnv()` / `bindConfig()`) can resolve their fallbacks.
@@ -181,8 +198,8 @@ function deriveOptionalInnerParseState(outerState, parser) {
 * Internal helper for optional-style parsing logic shared by optional()
 * and withDefault(). Handles the common pattern of:
 * - Unwrapping optional state to inner parser state
-* - Detecting if inner parser actually matched (state changed or no consumption)
-* - Returning success with undefined state when inner parser fails without consuming
+* - Detecting if the inner parser actually matched (state changed or no consumption)
+* - Returning success with undefined state when the inner parser fails without consuming
 * @internal
 */
 function parseOptionalStyleSync(context, parser) {
@@ -243,7 +260,7 @@ function processOptionalStyleResult(result, innerState, context) {
 * {@link withDefault} before delegating to the inner parser's hook.
 *
 * When state is an array, the adapter unwraps `state[0]` and propagates
-* annotations from the outer array.  Non-array objects (e.g., PromptBindState
+* annotations from the outer array.  Non-array objects (e.g. PromptBindState
 * from `prompt()`) are passed through directly.  `undefined` returns `false`
 * without calling the inner hook.
 *
@@ -253,10 +270,14 @@ function adaptShouldDeferCompletion(innerCheck, parser) {
 	return (state, exec) => {
 		if (Array.isArray(state) || state != null && typeof state === "object") {
 			const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
+			const hasCarrier = require_annotation_state.hasDelegatedAnnotationCarrier(innerState);
+			const shouldRetryFalseResult = hasCarrier && require_annotation_state.isAnnotationWrappedInitialState(innerState);
 			try {
-				return innerCheck(innerState, exec);
+				const result = innerCheck(innerState, exec);
+				if (!result && shouldRetryFalseResult) return innerCheck(require_annotation_state.normalizeDelegatedAnnotationState(innerState), exec);
+				return result;
 			} catch (error) {
-				if (!require_annotation_state.hasDelegatedAnnotationCarrier(innerState)) throw error;
+				if (!hasCarrier) throw error;
 				return innerCheck(require_annotation_state.normalizeDelegatedAnnotationState(innerState), exec);
 			}
 		}

package/dist/modifiers.js

@@ -4,7 +4,7 @@ import { dispatchByMode, dispatchIterableByMode, mapModeValue, wrapForMode } fro
 import { composeDependencyMetadata } from "./dependency-metadata.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";
+import { getDelegatedAnnotationState, hasDelegatedAnnotationCarrier, isAnnotationWrappedInitialState, normalizeDelegatedAnnotationState, normalizeNestedDelegatedAnnotationState } from "./annotation-state.js";
 
 //#region src/modifiers.ts
 function withChildExecPath(exec, segment) {
@@ -82,85 +82,102 @@ 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 ? {
+function normalizeOptionalLikeCompleteResult(result, shouldNormalize) {
+	return result.success && shouldNormalize ? {
 		...result,
 		value: normalizeNestedDelegatedAnnotationState(result.value)
 	} : result;
 }
 function completeOptionalLikeSync(parser, state, exec) {
 	const hasCarrier = hasDelegatedAnnotationCarrier(state);
+	const shouldRetryFalseResult = hasCarrier && isAnnotationWrappedInitialState(state);
+	const run = (candidate, shouldNormalize) => normalizeOptionalLikeCompleteResult(parser.complete(candidate, exec), shouldNormalize);
 	try {
-		return normalizeOptionalLikeCompleteResult(parser.complete(state, exec));
+		const result = run(state, hasCarrier);
+		if (!result.success && shouldRetryFalseResult) return run(normalizeDelegatedAnnotationState(state), false);
+		return result;
 	} catch (error) {
 		if (!hasCarrier) throw error;
-		const fallbackState = normalizeDelegatedAnnotationState(state);
-		return normalizeOptionalLikeCompleteResult(parser.complete(fallbackState, exec));
+		return run(normalizeDelegatedAnnotationState(state), false);
 	}
 }
 async function completeOptionalLikeAsync(parser, state, exec) {
 	const hasCarrier = hasDelegatedAnnotationCarrier(state);
+	const shouldRetryFalseResult = hasCarrier && isAnnotationWrappedInitialState(state);
+	const run = async (candidate, shouldNormalize) => normalizeOptionalLikeCompleteResult(await parser.complete(candidate, exec), shouldNormalize);
 	try {
-		return normalizeOptionalLikeCompleteResult(await parser.complete(state, exec));
+		const result = await run(state, hasCarrier);
+		if (!result.success && shouldRetryFalseResult) return await run(normalizeDelegatedAnnotationState(state), false);
+		return result;
 	} catch (error) {
 		if (!hasCarrier) throw error;
-		const fallbackState = normalizeDelegatedAnnotationState(state);
-		return normalizeOptionalLikeCompleteResult(await parser.complete(fallbackState, exec));
+		return await run(normalizeDelegatedAnnotationState(state), false);
 	}
 }
-function normalizeOptionalLikePhase2Seed(seed) {
-	return seed == null ? null : {
+function normalizeOptionalLikePhase2Seed(seed, shouldNormalize) {
+	return seed == null ? null : shouldNormalize ? {
 		...seed,
 		value: normalizeNestedDelegatedAnnotationState(seed.value)
-	};
+	} : seed;
 }
 function extractOptionalLikePhase2Seed(parser, state, exec) {
 	if (!Array.isArray(state) && !(state != null && typeof state === "object")) return wrapForMode(parser.$mode, null);
 	const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
 	const hasCarrier = hasDelegatedAnnotationCarrier(innerState);
+	const shouldRetryFalseResult = hasCarrier && isAnnotationWrappedInitialState(innerState);
 	return dispatchByMode(parser.$mode, () => {
 		try {
 			const result = parser.complete(innerState, exec);
-			if (result.success) return normalizeOptionalLikePhase2Seed(phase2SeedFromValueResult(result));
+			if (result.success) return normalizeOptionalLikePhase2Seed(phase2SeedFromValueResult(result), hasCarrier);
+			if (shouldRetryFalseResult) {
+				const fallbackState = normalizeDelegatedAnnotationState(innerState);
+				const fallbackResult = parser.complete(fallbackState, exec);
+				if (fallbackResult.success) return normalizeOptionalLikePhase2Seed(phase2SeedFromValueResult(fallbackResult), false);
+			}
 			const seed = extractPhase2Seed(parser, innerState, exec);
 			if (seed == null && hasCarrier) {
 				const fallbackState = normalizeDelegatedAnnotationState(innerState);
-				return normalizeOptionalLikePhase2Seed(extractPhase2Seed(parser, fallbackState, exec));
+				return normalizeOptionalLikePhase2Seed(extractPhase2Seed(parser, fallbackState, exec), false);
 			}
-			return normalizeOptionalLikePhase2Seed(seed);
+			return normalizeOptionalLikePhase2Seed(seed, hasCarrier);
 		} 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));
+			if (result.success) return normalizeOptionalLikePhase2Seed(phase2SeedFromValueResult(result), false);
+			return normalizeOptionalLikePhase2Seed(extractPhase2Seed(parser, fallbackState, exec), false);
 		}
 	}, async () => {
 		try {
 			const result = await parser.complete(innerState, exec);
-			if (result.success) return normalizeOptionalLikePhase2Seed(phase2SeedFromValueResult(result));
+			if (result.success) return normalizeOptionalLikePhase2Seed(phase2SeedFromValueResult(result), hasCarrier);
+			if (shouldRetryFalseResult) {
+				const fallbackState = normalizeDelegatedAnnotationState(innerState);
+				const fallbackResult = await parser.complete(fallbackState, exec);
+				if (fallbackResult.success) return normalizeOptionalLikePhase2Seed(phase2SeedFromValueResult(fallbackResult), false);
+			}
 			const seed = await extractPhase2Seed(parser, innerState, exec);
 			if (seed == null && hasCarrier) {
 				const fallbackState = normalizeDelegatedAnnotationState(innerState);
-				return normalizeOptionalLikePhase2Seed(await extractPhase2Seed(parser, fallbackState, exec));
+				return normalizeOptionalLikePhase2Seed(await extractPhase2Seed(parser, fallbackState, exec), false);
 			}
-			return normalizeOptionalLikePhase2Seed(seed);
+			return normalizeOptionalLikePhase2Seed(seed, hasCarrier);
 		} 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));
+			if (result.success) return normalizeOptionalLikePhase2Seed(phase2SeedFromValueResult(result), false);
+			return normalizeOptionalLikePhase2Seed(await extractPhase2Seed(parser, fallbackState, exec), false);
 		}
 	});
 }
 /**
 * Computes the inner state to pass through to the wrapped parser inside
 * {@link optional} / {@link withDefault}.  When the outer state is an
-* array, the inner state is `state[0]`.  Otherwise — including the
+* array, the inner state is `state[0]`.  Otherwise, including the
 * common case where `optional()` sits at top level and the outer state
 * is either `undefined` or an annotation wrapper from `parseOptionalLike`
-* / `parse({ annotations })` — we use the wrapped parser's
+* / `parse({ annotations })`, we use the wrapped parser's
 * `initialState`, propagating annotations from the outer state so that
 * source-binding wrappers under `optional()` / `withDefault()` (e.g.,
 * `bindEnv()` / `bindConfig()`) can resolve their fallbacks.
@@ -181,8 +198,8 @@ function deriveOptionalInnerParseState(outerState, parser) {
 * Internal helper for optional-style parsing logic shared by optional()
 * and withDefault(). Handles the common pattern of:
 * - Unwrapping optional state to inner parser state
-* - Detecting if inner parser actually matched (state changed or no consumption)
-* - Returning success with undefined state when inner parser fails without consuming
+* - Detecting if the inner parser actually matched (state changed or no consumption)
+* - Returning success with undefined state when the inner parser fails without consuming
 * @internal
 */
 function parseOptionalStyleSync(context, parser) {
@@ -243,7 +260,7 @@ function processOptionalStyleResult(result, innerState, context) {
 * {@link withDefault} before delegating to the inner parser's hook.
 *
 * When state is an array, the adapter unwraps `state[0]` and propagates
-* annotations from the outer array.  Non-array objects (e.g., PromptBindState
+* annotations from the outer array.  Non-array objects (e.g. PromptBindState
 * from `prompt()`) are passed through directly.  `undefined` returns `false`
 * without calling the inner hook.
 *
@@ -253,10 +270,14 @@ function adaptShouldDeferCompletion(innerCheck, parser) {
 	return (state, exec) => {
 		if (Array.isArray(state) || state != null && typeof state === "object") {
 			const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
+			const hasCarrier = hasDelegatedAnnotationCarrier(innerState);
+			const shouldRetryFalseResult = hasCarrier && isAnnotationWrappedInitialState(innerState);
 			try {
-				return innerCheck(innerState, exec);
+				const result = innerCheck(innerState, exec);
+				if (!result && shouldRetryFalseResult) return innerCheck(normalizeDelegatedAnnotationState(innerState), exec);
+				return result;
 			} catch (error) {
-				if (!hasDelegatedAnnotationCarrier(innerState)) throw error;
+				if (!hasCarrier) throw error;
 				return innerCheck(normalizeDelegatedAnnotationState(innerState), exec);
 			}
 		}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.1899+f70a2468",
+  "version": "1.0.0-dev.1903+af120cc5",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",