@optique/core 1.0.0-dev.1856 → 1.0.0-dev.1860

package/dist/annotations.cjs

@@ -50,14 +50,20 @@ const protectedAnnotationStateViews = /* @__PURE__ */ new WeakMap();
 function throwReadonlyAnnotationMutation() {
 	throw new TypeError("Cannot mutate read-only annotation data.");
 }
-function createAnnotationProtectionContext() {
-	return { cache: /* @__PURE__ */ new WeakMap() };
+function createAnnotationProtectionContext(rewrapProtectedViews = false) {
+	return {
+		cache: /* @__PURE__ */ new WeakMap(),
+		rewrapProtectedViews
+	};
 }
 function registerProtectedAnnotationView(context, target, view) {
 	context.cache.set(target, view);
 	protectedAnnotationTargets.set(view, target);
 	return view;
 }
+function cacheProtectedAnnotationViewAlias(context, alias, view) {
+	context.cache.set(alias, view);
+}
 function isProtectedAnnotationView(value) {
 	return value != null && typeof value === "object" && protectedAnnotationTargets.has(value);
 }
@@ -81,11 +87,11 @@ function defineProtectedDataProperty(context, target, key, descriptor) {
 		set: () => throwReadonlyAnnotationMutation()
 	});
 }
-function copyRegExpMetadata(source, target, transformValue) {
+function copyOwnProperties(source, target, transformValue, excludedKeys) {
 	const sourcePrototype = Object.getPrototypeOf(source);
 	if (Object.getPrototypeOf(target) !== sourcePrototype) Object.setPrototypeOf(target, sourcePrototype);
 	for (const key of Reflect.ownKeys(source)) {
-		if (key === "lastIndex") continue;
+		if (excludedKeys?.has(key) === true) continue;
 		const descriptor = Object.getOwnPropertyDescriptor(source, key);
 		if (descriptor == null) continue;
 		if ("value" in descriptor && transformValue != null) {
@@ -97,6 +103,13 @@ function copyRegExpMetadata(source, target, transformValue) {
 		}
 		Object.defineProperty(target, key, descriptor);
 	}
+}
+function normalizeProtectedCollectionItem(value, context) {
+	return context.rewrapProtectedViews && isProtectedAnnotationView(value) ? unwrapProtectedAnnotationTarget(value) : value;
+}
+const regExpExcludedKeys = new Set(["lastIndex"]);
+function copyRegExpMetadata(source, target, transformValue) {
+	copyOwnProperties(source, target, transformValue, regExpExcludedKeys);
 	target.lastIndex = source.lastIndex;
 }
 function cloneRegExpShape(source) {
@@ -106,7 +119,8 @@ function cloneRegExpShape(source) {
 }
 function createProtectedObjectView(target, context) {
 	if (Array.isArray(target)) {
-		const view$1 = new Array(target.length);
+		const view$1 = Object.setPrototypeOf([], Object.getPrototypeOf(target));
+		view$1.length = target.length;
 		registerProtectedAnnotationView(context, target, view$1);
 		for (const key of Reflect.ownKeys(target)) {
 			if (key === "length") continue;
@@ -145,26 +159,28 @@ function createProtectedObjectView(target, context) {
 }
 function createProtectedMapView(target, context) {
 	const methodCache = /* @__PURE__ */ new Map();
-	const view = new Proxy(target, {
-		get(target$1, key) {
-			if (key === "size") return target$1.size;
+	const cloned = /* @__PURE__ */ new Map();
+	for (const [entryKey, entryValue] of target.entries()) cloned.set(normalizeProtectedCollectionItem(entryKey, context), normalizeProtectedCollectionItem(entryValue, context));
+	const view = new Proxy(cloned, {
+		get(clonedTarget, key) {
+			if (key === "size") return clonedTarget.size;
 			if (key === "set" || key === "delete" || key === "clear") return cacheProtectedMethod(methodCache, key, () => (..._args) => throwReadonlyAnnotationMutation());
-			if (key === "get") return cacheProtectedMethod(methodCache, key, () => (lookup) => protectAnnotationValue(target$1.get(unwrapProtectedAnnotationTarget(lookup)), context));
-			if (key === "has") return cacheProtectedMethod(methodCache, key, () => (lookup) => target$1.has(unwrapProtectedAnnotationTarget(lookup)));
-			if (key === "forEach") return cacheProtectedMethod(methodCache, key, () => (callback, thisArg) => target$1.forEach((value$1, mapKey) => {
+			if (key === "get") return cacheProtectedMethod(methodCache, key, () => (lookup) => protectAnnotationValue(clonedTarget.get(unwrapProtectedAnnotationTarget(lookup)), context));
+			if (key === "has") return cacheProtectedMethod(methodCache, key, () => (lookup) => clonedTarget.has(unwrapProtectedAnnotationTarget(lookup)));
+			if (key === "forEach") return cacheProtectedMethod(methodCache, key, () => (callback, thisArg) => clonedTarget.forEach((value$1, mapKey) => {
 				callback.call(thisArg, protectAnnotationValue(value$1, context), protectAnnotationValue(mapKey, context), view);
 			}));
 			if (key === "keys") return cacheProtectedMethod(methodCache, key, () => function* () {
-				for (const value$1 of target$1.keys()) yield protectAnnotationValue(value$1, context);
+				for (const value$1 of clonedTarget.keys()) yield protectAnnotationValue(value$1, context);
 			});
 			if (key === "values") return cacheProtectedMethod(methodCache, key, () => function* () {
-				for (const value$1 of target$1.values()) yield protectAnnotationValue(value$1, context);
+				for (const value$1 of clonedTarget.values()) yield protectAnnotationValue(value$1, context);
 			});
 			if (key === "entries" || key === Symbol.iterator) return cacheProtectedMethod(methodCache, key, () => function* () {
-				for (const [entryKey, entryValue] of target$1.entries()) yield [protectAnnotationValue(entryKey, context), protectAnnotationValue(entryValue, context)];
+				for (const [entryKey, entryValue] of clonedTarget.entries()) yield [protectAnnotationValue(entryKey, context), protectAnnotationValue(entryValue, context)];
 			});
-			const value = Reflect.get(target$1, key, target$1);
-			return typeof value === "function" ? value.bind(target$1) : value;
+			const value = Reflect.get(clonedTarget, key, clonedTarget);
+			return typeof value === "function" ? value.bind(clonedTarget) : protectAnnotationValue(value, context);
 		},
 		set() {
 			throwReadonlyAnnotationMutation();
@@ -182,30 +198,35 @@ function createProtectedMapView(target, context) {
 			throwReadonlyAnnotationMutation();
 		}
 	});
-	return registerProtectedAnnotationView(context, target, view);
+	registerProtectedAnnotationView(context, target, view);
+	cacheProtectedAnnotationViewAlias(context, cloned, view);
+	copyOwnProperties(target, cloned, (value) => protectAnnotationValue(value, context));
+	return view;
 }
 function createProtectedSetView(target, context) {
 	const methodCache = /* @__PURE__ */ new Map();
-	const view = new Proxy(target, {
-		get(target$1, key) {
-			if (key === "size") return target$1.size;
+	const cloned = /* @__PURE__ */ new Set();
+	for (const value of target.values()) cloned.add(normalizeProtectedCollectionItem(value, context));
+	const view = new Proxy(cloned, {
+		get(clonedTarget, key) {
+			if (key === "size") return clonedTarget.size;
 			if (key === "add" || key === "delete" || key === "clear") return cacheProtectedMethod(methodCache, key, () => (..._args) => throwReadonlyAnnotationMutation());
-			if (key === "has") return cacheProtectedMethod(methodCache, key, () => (lookup) => target$1.has(unwrapProtectedAnnotationTarget(lookup)));
-			if (key === "forEach") return cacheProtectedMethod(methodCache, key, () => (callback, thisArg) => target$1.forEach((value$1) => {
+			if (key === "has") return cacheProtectedMethod(methodCache, key, () => (lookup) => clonedTarget.has(unwrapProtectedAnnotationTarget(lookup)));
+			if (key === "forEach") return cacheProtectedMethod(methodCache, key, () => (callback, thisArg) => clonedTarget.forEach((value$1) => {
 				const protectedValue = protectAnnotationValue(value$1, context);
 				callback.call(thisArg, protectedValue, protectedValue, view);
 			}));
 			if (key === "keys" || key === "values" || key === Symbol.iterator) return cacheProtectedMethod(methodCache, key, () => function* () {
-				for (const value$1 of target$1.values()) yield protectAnnotationValue(value$1, context);
+				for (const value$1 of clonedTarget.values()) yield protectAnnotationValue(value$1, context);
 			});
 			if (key === "entries") return cacheProtectedMethod(methodCache, key, () => function* () {
-				for (const value$1 of target$1.values()) {
+				for (const value$1 of clonedTarget.values()) {
 					const protectedValue = protectAnnotationValue(value$1, context);
 					yield [protectedValue, protectedValue];
 				}
 			});
-			const value = Reflect.get(target$1, key, target$1);
-			return typeof value === "function" ? value.bind(target$1) : value;
+			const value = Reflect.get(clonedTarget, key, clonedTarget);
+			return typeof value === "function" ? value.bind(clonedTarget) : protectAnnotationValue(value, context);
 		},
 		set() {
 			throwReadonlyAnnotationMutation();
@@ -223,15 +244,19 @@ function createProtectedSetView(target, context) {
 			throwReadonlyAnnotationMutation();
 		}
 	});
-	return registerProtectedAnnotationView(context, target, view);
+	registerProtectedAnnotationView(context, target, view);
+	cacheProtectedAnnotationViewAlias(context, cloned, view);
+	copyOwnProperties(target, cloned, (value) => protectAnnotationValue(value, context));
+	return view;
 }
 function createProtectedDateView(target, context) {
 	const methodCache = /* @__PURE__ */ new Map();
-	const view = new Proxy(target, {
-		get(target$1, key) {
-			const value = Reflect.get(target$1, key, target$1);
+	const cloned = new Date(target.getTime());
+	const view = new Proxy(cloned, {
+		get(clonedTarget, key) {
+			const value = Reflect.get(clonedTarget, key, clonedTarget);
 			if (typeof key === "string" && key.startsWith("set")) return cacheProtectedMethod(methodCache, key, () => (..._args) => throwReadonlyAnnotationMutation());
-			return typeof value === "function" ? value.bind(target$1) : value;
+			return typeof value === "function" ? value.bind(clonedTarget) : protectAnnotationValue(value, context);
 		},
 		set() {
 			throwReadonlyAnnotationMutation();
@@ -249,7 +274,10 @@ function createProtectedDateView(target, context) {
 			throwReadonlyAnnotationMutation();
 		}
 	});
-	return registerProtectedAnnotationView(context, target, view);
+	registerProtectedAnnotationView(context, target, view);
+	cacheProtectedAnnotationViewAlias(context, cloned, view);
+	copyOwnProperties(target, cloned, (value) => protectAnnotationValue(value, context));
+	return view;
 }
 function createProtectedRegExpView(target, context) {
 	const methodCache = /* @__PURE__ */ new Map();
@@ -279,26 +307,28 @@ function createProtectedRegExpView(target, context) {
 		}
 	});
 	registerProtectedAnnotationView(context, target, view);
+	cacheProtectedAnnotationViewAlias(context, cloned, view);
 	copyRegExpMetadata(target, cloned, (value) => protectAnnotationValue(value, context));
 	return view;
 }
 function createProtectedURLSearchParamsView(target, context) {
 	const methodCache = /* @__PURE__ */ new Map();
-	const view = new Proxy(target, {
-		get(target$1, key) {
+	const cloned = new URLSearchParams(target);
+	const view = new Proxy(cloned, {
+		get(clonedTarget, key) {
 			if (key === "append" || key === "delete" || key === "set" || key === "sort") return cacheProtectedMethod(methodCache, key, () => (..._args) => throwReadonlyAnnotationMutation());
-			if (key === "forEach") return cacheProtectedMethod(methodCache, key, () => (callback, thisArg) => target$1.forEach((value$1, name) => {
+			if (key === "forEach") return cacheProtectedMethod(methodCache, key, () => (callback, thisArg) => clonedTarget.forEach((value$1, name) => {
 				callback.call(thisArg, value$1, name, view);
 			}));
 			if (key === "keys" || key === "values") return cacheProtectedMethod(methodCache, key, () => function* () {
-				const iterator = key === "keys" ? target$1.keys() : target$1.values();
+				const iterator = key === "keys" ? clonedTarget.keys() : clonedTarget.values();
 				for (const value$1 of iterator) yield value$1;
 			});
 			if (key === "entries" || key === Symbol.iterator) return cacheProtectedMethod(methodCache, key, () => function* () {
-				for (const entry of target$1.entries()) yield entry;
+				for (const entry of clonedTarget.entries()) yield entry;
 			});
-			const value = Reflect.get(target$1, key, target$1);
-			return typeof value === "function" ? value.bind(target$1) : value;
+			const value = Reflect.get(clonedTarget, key, clonedTarget);
+			return typeof value === "function" ? value.bind(clonedTarget) : protectAnnotationValue(value, context);
 		},
 		set() {
 			throwReadonlyAnnotationMutation();
@@ -316,14 +346,18 @@ function createProtectedURLSearchParamsView(target, context) {
 			throwReadonlyAnnotationMutation();
 		}
 	});
-	return registerProtectedAnnotationView(context, target, view);
+	registerProtectedAnnotationView(context, target, view);
+	cacheProtectedAnnotationViewAlias(context, cloned, view);
+	copyOwnProperties(target, cloned, (value) => protectAnnotationValue(value, context));
+	return view;
 }
 function createProtectedURLView(target, context) {
-	const view = new Proxy(target, {
-		get(target$1, key) {
-			if (key === "searchParams") return protectAnnotationValue(target$1.searchParams, context);
-			const value = Reflect.get(target$1, key, target$1);
-			return typeof value === "function" ? value.bind(target$1) : value;
+	const cloned = new URL(target.href);
+	const view = new Proxy(cloned, {
+		get(clonedTarget, key) {
+			if (key === "searchParams") return protectAnnotationValue(clonedTarget.searchParams, context);
+			const value = Reflect.get(clonedTarget, key, clonedTarget);
+			return typeof value === "function" ? value.bind(clonedTarget) : protectAnnotationValue(value, context);
 		},
 		set() {
 			throwReadonlyAnnotationMutation();
@@ -341,12 +375,16 @@ function createProtectedURLView(target, context) {
 			throwReadonlyAnnotationMutation();
 		}
 	});
-	return registerProtectedAnnotationView(context, target, view);
+	registerProtectedAnnotationView(context, target, view);
+	cacheProtectedAnnotationViewAlias(context, cloned, view);
+	copyOwnProperties(target, cloned, (value) => protectAnnotationValue(value, context));
+	return view;
 }
 function protectAnnotationValue(value, context) {
 	if (value == null || typeof value !== "object") return value;
-	const target = value;
-	if (isProtectedAnnotationView(value)) return value;
+	const isProtectedView = isProtectedAnnotationView(value);
+	if (isProtectedView && !context.rewrapProtectedViews) return value;
+	const target = isProtectedView ? unwrapProtectedAnnotationTarget(value) : value;
 	const cached = context.cache.get(target);
 	if (cached !== void 0) return cached;
 	if (target instanceof Map) return createProtectedMapView(target, context);
@@ -374,6 +412,71 @@ function protectAnnotationValue(value, context) {
 function normalizeRunAnnotationInput(annotations) {
 	return isProtectedAnnotationView(annotations) ? unwrapProtectedAnnotationTarget(annotations) : annotations;
 }
+function injectAnnotationsWithContext(state, annotations, context) {
+	const protectedAnnotations = protectAnnotationValue(annotations, context);
+	if (state == null || typeof state !== "object") {
+		const wrapper = {};
+		Object.defineProperties(wrapper, {
+			[annotationKey]: {
+				value: protectedAnnotations,
+				enumerable: true,
+				writable: true,
+				configurable: true
+			},
+			[annotationStateValueKey]: {
+				value: state,
+				enumerable: false,
+				writable: true,
+				configurable: true
+			},
+			[annotationWrapperKey]: {
+				value: true,
+				enumerable: false,
+				writable: true,
+				configurable: true
+			}
+		});
+		injectedAnnotationWrappers.add(wrapper);
+		return wrapper;
+	}
+	if (Array.isArray(state)) {
+		const cloned$1 = [...state];
+		cloned$1[annotationKey] = protectedAnnotations;
+		return cloned$1;
+	}
+	if (isInjectedAnnotationWrapper(state)) {
+		state[annotationKey] = protectedAnnotations;
+		return state;
+	}
+	if (state instanceof Date) {
+		const cloned$1 = new Date(state.getTime());
+		cloned$1[annotationKey] = protectedAnnotations;
+		return cloned$1;
+	}
+	if (state instanceof Map) {
+		const cloned$1 = new Map(state);
+		cloned$1[annotationKey] = protectedAnnotations;
+		return cloned$1;
+	}
+	if (state instanceof Set) {
+		const cloned$1 = new Set(state);
+		cloned$1[annotationKey] = protectedAnnotations;
+		return cloned$1;
+	}
+	if (state instanceof RegExp) {
+		const cloned$1 = cloneRegExpShape(state);
+		cloned$1[annotationKey] = protectedAnnotations;
+		return cloned$1;
+	}
+	const proto = Object.getPrototypeOf(state);
+	if (proto === Object.prototype || proto === null) return {
+		...state,
+		[annotationKey]: protectedAnnotations
+	};
+	const cloned = Object.create(proto, Object.getOwnPropertyDescriptors(state));
+	cloned[annotationKey] = protectedAnnotations;
+	return cloned;
+}
 /**
 * Extracts annotations from parser state.
 *
@@ -505,69 +608,22 @@ function hasMeaningfulAnnotations(annotations) {
 */
 function injectAnnotations(state, annotations) {
 	if (!hasMeaningfulAnnotations(annotations)) return state;
-	const protectedAnnotations = protectAnnotationValue(annotations, createAnnotationProtectionContext());
-	if (state == null || typeof state !== "object") {
-		const wrapper = {};
-		Object.defineProperties(wrapper, {
-			[annotationKey]: {
-				value: protectedAnnotations,
-				enumerable: true,
-				writable: true,
-				configurable: true
-			},
-			[annotationStateValueKey]: {
-				value: state,
-				enumerable: false,
-				writable: true,
-				configurable: true
-			},
-			[annotationWrapperKey]: {
-				value: true,
-				enumerable: false,
-				writable: true,
-				configurable: true
-			}
-		});
-		injectedAnnotationWrappers.add(wrapper);
-		return wrapper;
-	}
-	if (Array.isArray(state)) {
-		const cloned$1 = [...state];
-		cloned$1[annotationKey] = protectedAnnotations;
-		return cloned$1;
-	}
-	if (isInjectedAnnotationWrapper(state)) {
-		state[annotationKey] = protectedAnnotations;
-		return state;
-	}
-	if (state instanceof Date) {
-		const cloned$1 = new Date(state.getTime());
-		cloned$1[annotationKey] = protectedAnnotations;
-		return cloned$1;
-	}
-	if (state instanceof Map) {
-		const cloned$1 = new Map(state);
-		cloned$1[annotationKey] = protectedAnnotations;
-		return cloned$1;
-	}
-	if (state instanceof Set) {
-		const cloned$1 = new Set(state);
-		cloned$1[annotationKey] = protectedAnnotations;
-		return cloned$1;
-	}
-	if (state instanceof RegExp) {
-		const cloned$1 = cloneRegExpShape(state);
-		cloned$1[annotationKey] = protectedAnnotations;
-		return cloned$1;
-	}
-	const proto = Object.getPrototypeOf(state);
-	if (proto === Object.prototype || proto === null) return {
-		...state,
-		[annotationKey]: protectedAnnotations
-	};
-	const cloned = Object.create(proto, Object.getOwnPropertyDescriptors(state));
-	cloned[annotationKey] = protectedAnnotations;
-	return cloned;
+	return injectAnnotationsWithContext(state, annotations, createAnnotationProtectionContext());
+}
+/**
+* Injects annotations for a fresh parse run.
+*
+* This path re-wraps protected views from previous runs so stateful container
+* internals remain isolated across parse entrypoints.
+*
+* @param state The parser state to annotate.
+* @param annotations The annotations to inject.
+* @returns Annotated state for the fresh run.
+* @internal
+*/
+function injectFreshRunAnnotations(state, annotations) {
+	if (!hasMeaningfulAnnotations(annotations)) return state;
+	return injectAnnotationsWithContext(state, normalizeRunAnnotationInput(annotations), createAnnotationProtectionContext(true));
 }
 /**
 * Unwraps a primitive-state annotation wrapper injected by Optique internals.
@@ -607,6 +663,7 @@ exports.getAnnotations = getAnnotations;
 exports.hasMeaningfulAnnotations = hasMeaningfulAnnotations;
 exports.inheritAnnotations = inheritAnnotations;
 exports.injectAnnotations = injectAnnotations;
+exports.injectFreshRunAnnotations = injectFreshRunAnnotations;
 exports.isInjectedAnnotationWrapper = isInjectedAnnotationWrapper;
 exports.normalizeRunAnnotationInput = normalizeRunAnnotationInput;
 exports.unwrapInjectedAnnotationWrapper = unwrapInjectedAnnotationWrapper;

package/dist/annotations.d.cts

@@ -88,7 +88,7 @@ interface ParseOptions {
    * Optique treats these values as immutable input and exposes them back to
    * parsers only through protected read-only views.
    */
-  annotations?: Annotations | ReadonlyAnnotations;
+  readonly annotations?: Annotations | ReadonlyAnnotations;
 }
 /**
  * Extracts annotations from parser state.
@@ -162,6 +162,18 @@ declare function hasMeaningfulAnnotations(annotations: AnnotationInput | null |
  * @internal
  */
 declare function injectAnnotations<TState>(state: TState, annotations: AnnotationInput): TState;
+/**
+ * Injects annotations for a fresh parse run.
+ *
+ * This path re-wraps protected views from previous runs so stateful container
+ * internals remain isolated across parse entrypoints.
+ *
+ * @param state The parser state to annotate.
+ * @param annotations The annotations to inject.
+ * @returns Annotated state for the fresh run.
+ * @internal
+ */
+declare function injectFreshRunAnnotations<TState>(state: TState, annotations: AnnotationInput): TState;
 /**
  * Unwraps a primitive-state annotation wrapper injected by Optique internals.
  *
@@ -181,4 +193,4 @@ declare function unwrapInjectedAnnotationWrapper<T>(value: T): T;
  */
 declare function isInjectedAnnotationWrapper(value: unknown): boolean;
 //#endregion
-export { Annotations, ParseOptions, ReadonlyAnnotations, annotateFreshArray, annotationKey, annotationStateValueKey, annotationWrapperKey, firstPassAnnotationKey, getAnnotations, hasMeaningfulAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationWrapper, normalizeRunAnnotationInput, unwrapInjectedAnnotationWrapper };
+export { Annotations, ParseOptions, ReadonlyAnnotations, annotateFreshArray, annotationKey, annotationStateValueKey, annotationWrapperKey, firstPassAnnotationKey, getAnnotations, hasMeaningfulAnnotations, inheritAnnotations, injectAnnotations, injectFreshRunAnnotations, isInjectedAnnotationWrapper, normalizeRunAnnotationInput, unwrapInjectedAnnotationWrapper };

package/dist/annotations.d.ts

@@ -88,7 +88,7 @@ interface ParseOptions {
    * Optique treats these values as immutable input and exposes them back to
    * parsers only through protected read-only views.
    */
-  annotations?: Annotations | ReadonlyAnnotations;
+  readonly annotations?: Annotations | ReadonlyAnnotations;
 }
 /**
  * Extracts annotations from parser state.
@@ -162,6 +162,18 @@ declare function hasMeaningfulAnnotations(annotations: AnnotationInput | null |
  * @internal
  */
 declare function injectAnnotations<TState>(state: TState, annotations: AnnotationInput): TState;
+/**
+ * Injects annotations for a fresh parse run.
+ *
+ * This path re-wraps protected views from previous runs so stateful container
+ * internals remain isolated across parse entrypoints.
+ *
+ * @param state The parser state to annotate.
+ * @param annotations The annotations to inject.
+ * @returns Annotated state for the fresh run.
+ * @internal
+ */
+declare function injectFreshRunAnnotations<TState>(state: TState, annotations: AnnotationInput): TState;
 /**
  * Unwraps a primitive-state annotation wrapper injected by Optique internals.
  *
@@ -181,4 +193,4 @@ declare function unwrapInjectedAnnotationWrapper<T>(value: T): T;
  */
 declare function isInjectedAnnotationWrapper(value: unknown): boolean;
 //#endregion
-export { Annotations, ParseOptions, ReadonlyAnnotations, annotateFreshArray, annotationKey, annotationStateValueKey, annotationWrapperKey, firstPassAnnotationKey, getAnnotations, hasMeaningfulAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationWrapper, normalizeRunAnnotationInput, unwrapInjectedAnnotationWrapper };
+export { Annotations, ParseOptions, ReadonlyAnnotations, annotateFreshArray, annotationKey, annotationStateValueKey, annotationWrapperKey, firstPassAnnotationKey, getAnnotations, hasMeaningfulAnnotations, inheritAnnotations, injectAnnotations, injectFreshRunAnnotations, isInjectedAnnotationWrapper, normalizeRunAnnotationInput, unwrapInjectedAnnotationWrapper };

package/dist/annotations.js

@@ -49,14 +49,20 @@ const protectedAnnotationStateViews = /* @__PURE__ */ new WeakMap();
 function throwReadonlyAnnotationMutation() {
 	throw new TypeError("Cannot mutate read-only annotation data.");
 }
-function createAnnotationProtectionContext() {
-	return { cache: /* @__PURE__ */ new WeakMap() };
+function createAnnotationProtectionContext(rewrapProtectedViews = false) {
+	return {
+		cache: /* @__PURE__ */ new WeakMap(),
+		rewrapProtectedViews
+	};
 }
 function registerProtectedAnnotationView(context, target, view) {
 	context.cache.set(target, view);
 	protectedAnnotationTargets.set(view, target);
 	return view;
 }
+function cacheProtectedAnnotationViewAlias(context, alias, view) {
+	context.cache.set(alias, view);
+}
 function isProtectedAnnotationView(value) {
 	return value != null && typeof value === "object" && protectedAnnotationTargets.has(value);
 }
@@ -80,11 +86,11 @@ function defineProtectedDataProperty(context, target, key, descriptor) {
 		set: () => throwReadonlyAnnotationMutation()
 	});
 }
-function copyRegExpMetadata(source, target, transformValue) {
+function copyOwnProperties(source, target, transformValue, excludedKeys) {
 	const sourcePrototype = Object.getPrototypeOf(source);
 	if (Object.getPrototypeOf(target) !== sourcePrototype) Object.setPrototypeOf(target, sourcePrototype);
 	for (const key of Reflect.ownKeys(source)) {
-		if (key === "lastIndex") continue;
+		if (excludedKeys?.has(key) === true) continue;
 		const descriptor = Object.getOwnPropertyDescriptor(source, key);
 		if (descriptor == null) continue;
 		if ("value" in descriptor && transformValue != null) {
@@ -96,6 +102,13 @@ function copyRegExpMetadata(source, target, transformValue) {
 		}
 		Object.defineProperty(target, key, descriptor);
 	}
+}
+function normalizeProtectedCollectionItem(value, context) {
+	return context.rewrapProtectedViews && isProtectedAnnotationView(value) ? unwrapProtectedAnnotationTarget(value) : value;
+}
+const regExpExcludedKeys = new Set(["lastIndex"]);
+function copyRegExpMetadata(source, target, transformValue) {
+	copyOwnProperties(source, target, transformValue, regExpExcludedKeys);
 	target.lastIndex = source.lastIndex;
 }
 function cloneRegExpShape(source) {
@@ -105,7 +118,8 @@ function cloneRegExpShape(source) {
 }
 function createProtectedObjectView(target, context) {
 	if (Array.isArray(target)) {
-		const view$1 = new Array(target.length);
+		const view$1 = Object.setPrototypeOf([], Object.getPrototypeOf(target));
+		view$1.length = target.length;
 		registerProtectedAnnotationView(context, target, view$1);
 		for (const key of Reflect.ownKeys(target)) {
 			if (key === "length") continue;
@@ -144,26 +158,28 @@ function createProtectedObjectView(target, context) {
 }
 function createProtectedMapView(target, context) {
 	const methodCache = /* @__PURE__ */ new Map();
-	const view = new Proxy(target, {
-		get(target$1, key) {
-			if (key === "size") return target$1.size;
+	const cloned = /* @__PURE__ */ new Map();
+	for (const [entryKey, entryValue] of target.entries()) cloned.set(normalizeProtectedCollectionItem(entryKey, context), normalizeProtectedCollectionItem(entryValue, context));
+	const view = new Proxy(cloned, {
+		get(clonedTarget, key) {
+			if (key === "size") return clonedTarget.size;
 			if (key === "set" || key === "delete" || key === "clear") return cacheProtectedMethod(methodCache, key, () => (..._args) => throwReadonlyAnnotationMutation());
-			if (key === "get") return cacheProtectedMethod(methodCache, key, () => (lookup) => protectAnnotationValue(target$1.get(unwrapProtectedAnnotationTarget(lookup)), context));
-			if (key === "has") return cacheProtectedMethod(methodCache, key, () => (lookup) => target$1.has(unwrapProtectedAnnotationTarget(lookup)));
-			if (key === "forEach") return cacheProtectedMethod(methodCache, key, () => (callback, thisArg) => target$1.forEach((value$1, mapKey) => {
+			if (key === "get") return cacheProtectedMethod(methodCache, key, () => (lookup) => protectAnnotationValue(clonedTarget.get(unwrapProtectedAnnotationTarget(lookup)), context));
+			if (key === "has") return cacheProtectedMethod(methodCache, key, () => (lookup) => clonedTarget.has(unwrapProtectedAnnotationTarget(lookup)));
+			if (key === "forEach") return cacheProtectedMethod(methodCache, key, () => (callback, thisArg) => clonedTarget.forEach((value$1, mapKey) => {
 				callback.call(thisArg, protectAnnotationValue(value$1, context), protectAnnotationValue(mapKey, context), view);
 			}));
 			if (key === "keys") return cacheProtectedMethod(methodCache, key, () => function* () {
-				for (const value$1 of target$1.keys()) yield protectAnnotationValue(value$1, context);
+				for (const value$1 of clonedTarget.keys()) yield protectAnnotationValue(value$1, context);
 			});
 			if (key === "values") return cacheProtectedMethod(methodCache, key, () => function* () {
-				for (const value$1 of target$1.values()) yield protectAnnotationValue(value$1, context);
+				for (const value$1 of clonedTarget.values()) yield protectAnnotationValue(value$1, context);
 			});
 			if (key === "entries" || key === Symbol.iterator) return cacheProtectedMethod(methodCache, key, () => function* () {
-				for (const [entryKey, entryValue] of target$1.entries()) yield [protectAnnotationValue(entryKey, context), protectAnnotationValue(entryValue, context)];
+				for (const [entryKey, entryValue] of clonedTarget.entries()) yield [protectAnnotationValue(entryKey, context), protectAnnotationValue(entryValue, context)];
 			});
-			const value = Reflect.get(target$1, key, target$1);
-			return typeof value === "function" ? value.bind(target$1) : value;
+			const value = Reflect.get(clonedTarget, key, clonedTarget);
+			return typeof value === "function" ? value.bind(clonedTarget) : protectAnnotationValue(value, context);
 		},
 		set() {
 			throwReadonlyAnnotationMutation();
@@ -181,30 +197,35 @@ function createProtectedMapView(target, context) {
 			throwReadonlyAnnotationMutation();
 		}
 	});
-	return registerProtectedAnnotationView(context, target, view);
+	registerProtectedAnnotationView(context, target, view);
+	cacheProtectedAnnotationViewAlias(context, cloned, view);
+	copyOwnProperties(target, cloned, (value) => protectAnnotationValue(value, context));
+	return view;
 }
 function createProtectedSetView(target, context) {
 	const methodCache = /* @__PURE__ */ new Map();
-	const view = new Proxy(target, {
-		get(target$1, key) {
-			if (key === "size") return target$1.size;
+	const cloned = /* @__PURE__ */ new Set();
+	for (const value of target.values()) cloned.add(normalizeProtectedCollectionItem(value, context));
+	const view = new Proxy(cloned, {
+		get(clonedTarget, key) {
+			if (key === "size") return clonedTarget.size;
 			if (key === "add" || key === "delete" || key === "clear") return cacheProtectedMethod(methodCache, key, () => (..._args) => throwReadonlyAnnotationMutation());
-			if (key === "has") return cacheProtectedMethod(methodCache, key, () => (lookup) => target$1.has(unwrapProtectedAnnotationTarget(lookup)));
-			if (key === "forEach") return cacheProtectedMethod(methodCache, key, () => (callback, thisArg) => target$1.forEach((value$1) => {
+			if (key === "has") return cacheProtectedMethod(methodCache, key, () => (lookup) => clonedTarget.has(unwrapProtectedAnnotationTarget(lookup)));
+			if (key === "forEach") return cacheProtectedMethod(methodCache, key, () => (callback, thisArg) => clonedTarget.forEach((value$1) => {
 				const protectedValue = protectAnnotationValue(value$1, context);
 				callback.call(thisArg, protectedValue, protectedValue, view);
 			}));
 			if (key === "keys" || key === "values" || key === Symbol.iterator) return cacheProtectedMethod(methodCache, key, () => function* () {
-				for (const value$1 of target$1.values()) yield protectAnnotationValue(value$1, context);
+				for (const value$1 of clonedTarget.values()) yield protectAnnotationValue(value$1, context);
 			});
 			if (key === "entries") return cacheProtectedMethod(methodCache, key, () => function* () {
-				for (const value$1 of target$1.values()) {
+				for (const value$1 of clonedTarget.values()) {
 					const protectedValue = protectAnnotationValue(value$1, context);
 					yield [protectedValue, protectedValue];
 				}
 			});
-			const value = Reflect.get(target$1, key, target$1);
-			return typeof value === "function" ? value.bind(target$1) : value;
+			const value = Reflect.get(clonedTarget, key, clonedTarget);
+			return typeof value === "function" ? value.bind(clonedTarget) : protectAnnotationValue(value, context);
 		},
 		set() {
 			throwReadonlyAnnotationMutation();
@@ -222,15 +243,19 @@ function createProtectedSetView(target, context) {
 			throwReadonlyAnnotationMutation();
 		}
 	});
-	return registerProtectedAnnotationView(context, target, view);
+	registerProtectedAnnotationView(context, target, view);
+	cacheProtectedAnnotationViewAlias(context, cloned, view);
+	copyOwnProperties(target, cloned, (value) => protectAnnotationValue(value, context));
+	return view;
 }
 function createProtectedDateView(target, context) {
 	const methodCache = /* @__PURE__ */ new Map();
-	const view = new Proxy(target, {
-		get(target$1, key) {
-			const value = Reflect.get(target$1, key, target$1);
+	const cloned = new Date(target.getTime());
+	const view = new Proxy(cloned, {
+		get(clonedTarget, key) {
+			const value = Reflect.get(clonedTarget, key, clonedTarget);
 			if (typeof key === "string" && key.startsWith("set")) return cacheProtectedMethod(methodCache, key, () => (..._args) => throwReadonlyAnnotationMutation());
-			return typeof value === "function" ? value.bind(target$1) : value;
+			return typeof value === "function" ? value.bind(clonedTarget) : protectAnnotationValue(value, context);
 		},
 		set() {
 			throwReadonlyAnnotationMutation();
@@ -248,7 +273,10 @@ function createProtectedDateView(target, context) {
 			throwReadonlyAnnotationMutation();
 		}
 	});
-	return registerProtectedAnnotationView(context, target, view);
+	registerProtectedAnnotationView(context, target, view);
+	cacheProtectedAnnotationViewAlias(context, cloned, view);
+	copyOwnProperties(target, cloned, (value) => protectAnnotationValue(value, context));
+	return view;
 }
 function createProtectedRegExpView(target, context) {
 	const methodCache = /* @__PURE__ */ new Map();
@@ -278,26 +306,28 @@ function createProtectedRegExpView(target, context) {
 		}
 	});
 	registerProtectedAnnotationView(context, target, view);
+	cacheProtectedAnnotationViewAlias(context, cloned, view);
 	copyRegExpMetadata(target, cloned, (value) => protectAnnotationValue(value, context));
 	return view;
 }
 function createProtectedURLSearchParamsView(target, context) {
 	const methodCache = /* @__PURE__ */ new Map();
-	const view = new Proxy(target, {
-		get(target$1, key) {
+	const cloned = new URLSearchParams(target);
+	const view = new Proxy(cloned, {
+		get(clonedTarget, key) {
 			if (key === "append" || key === "delete" || key === "set" || key === "sort") return cacheProtectedMethod(methodCache, key, () => (..._args) => throwReadonlyAnnotationMutation());
-			if (key === "forEach") return cacheProtectedMethod(methodCache, key, () => (callback, thisArg) => target$1.forEach((value$1, name) => {
+			if (key === "forEach") return cacheProtectedMethod(methodCache, key, () => (callback, thisArg) => clonedTarget.forEach((value$1, name) => {
 				callback.call(thisArg, value$1, name, view);
 			}));
 			if (key === "keys" || key === "values") return cacheProtectedMethod(methodCache, key, () => function* () {
-				const iterator = key === "keys" ? target$1.keys() : target$1.values();
+				const iterator = key === "keys" ? clonedTarget.keys() : clonedTarget.values();
 				for (const value$1 of iterator) yield value$1;
 			});
 			if (key === "entries" || key === Symbol.iterator) return cacheProtectedMethod(methodCache, key, () => function* () {
-				for (const entry of target$1.entries()) yield entry;
+				for (const entry of clonedTarget.entries()) yield entry;
 			});
-			const value = Reflect.get(target$1, key, target$1);
-			return typeof value === "function" ? value.bind(target$1) : value;
+			const value = Reflect.get(clonedTarget, key, clonedTarget);
+			return typeof value === "function" ? value.bind(clonedTarget) : protectAnnotationValue(value, context);
 		},
 		set() {
 			throwReadonlyAnnotationMutation();
@@ -315,14 +345,18 @@ function createProtectedURLSearchParamsView(target, context) {
 			throwReadonlyAnnotationMutation();
 		}
 	});
-	return registerProtectedAnnotationView(context, target, view);
+	registerProtectedAnnotationView(context, target, view);
+	cacheProtectedAnnotationViewAlias(context, cloned, view);
+	copyOwnProperties(target, cloned, (value) => protectAnnotationValue(value, context));
+	return view;
 }
 function createProtectedURLView(target, context) {
-	const view = new Proxy(target, {
-		get(target$1, key) {
-			if (key === "searchParams") return protectAnnotationValue(target$1.searchParams, context);
-			const value = Reflect.get(target$1, key, target$1);
-			return typeof value === "function" ? value.bind(target$1) : value;
+	const cloned = new URL(target.href);
+	const view = new Proxy(cloned, {
+		get(clonedTarget, key) {
+			if (key === "searchParams") return protectAnnotationValue(clonedTarget.searchParams, context);
+			const value = Reflect.get(clonedTarget, key, clonedTarget);
+			return typeof value === "function" ? value.bind(clonedTarget) : protectAnnotationValue(value, context);
 		},
 		set() {
 			throwReadonlyAnnotationMutation();
@@ -340,12 +374,16 @@ function createProtectedURLView(target, context) {
 			throwReadonlyAnnotationMutation();
 		}
 	});
-	return registerProtectedAnnotationView(context, target, view);
+	registerProtectedAnnotationView(context, target, view);
+	cacheProtectedAnnotationViewAlias(context, cloned, view);
+	copyOwnProperties(target, cloned, (value) => protectAnnotationValue(value, context));
+	return view;
 }
 function protectAnnotationValue(value, context) {
 	if (value == null || typeof value !== "object") return value;
-	const target = value;
-	if (isProtectedAnnotationView(value)) return value;
+	const isProtectedView = isProtectedAnnotationView(value);
+	if (isProtectedView && !context.rewrapProtectedViews) return value;
+	const target = isProtectedView ? unwrapProtectedAnnotationTarget(value) : value;
 	const cached = context.cache.get(target);
 	if (cached !== void 0) return cached;
 	if (target instanceof Map) return createProtectedMapView(target, context);
@@ -373,6 +411,71 @@ function protectAnnotationValue(value, context) {
 function normalizeRunAnnotationInput(annotations) {
 	return isProtectedAnnotationView(annotations) ? unwrapProtectedAnnotationTarget(annotations) : annotations;
 }
+function injectAnnotationsWithContext(state, annotations, context) {
+	const protectedAnnotations = protectAnnotationValue(annotations, context);
+	if (state == null || typeof state !== "object") {
+		const wrapper = {};
+		Object.defineProperties(wrapper, {
+			[annotationKey]: {
+				value: protectedAnnotations,
+				enumerable: true,
+				writable: true,
+				configurable: true
+			},
+			[annotationStateValueKey]: {
+				value: state,
+				enumerable: false,
+				writable: true,
+				configurable: true
+			},
+			[annotationWrapperKey]: {
+				value: true,
+				enumerable: false,
+				writable: true,
+				configurable: true
+			}
+		});
+		injectedAnnotationWrappers.add(wrapper);
+		return wrapper;
+	}
+	if (Array.isArray(state)) {
+		const cloned$1 = [...state];
+		cloned$1[annotationKey] = protectedAnnotations;
+		return cloned$1;
+	}
+	if (isInjectedAnnotationWrapper(state)) {
+		state[annotationKey] = protectedAnnotations;
+		return state;
+	}
+	if (state instanceof Date) {
+		const cloned$1 = new Date(state.getTime());
+		cloned$1[annotationKey] = protectedAnnotations;
+		return cloned$1;
+	}
+	if (state instanceof Map) {
+		const cloned$1 = new Map(state);
+		cloned$1[annotationKey] = protectedAnnotations;
+		return cloned$1;
+	}
+	if (state instanceof Set) {
+		const cloned$1 = new Set(state);
+		cloned$1[annotationKey] = protectedAnnotations;
+		return cloned$1;
+	}
+	if (state instanceof RegExp) {
+		const cloned$1 = cloneRegExpShape(state);
+		cloned$1[annotationKey] = protectedAnnotations;
+		return cloned$1;
+	}
+	const proto = Object.getPrototypeOf(state);
+	if (proto === Object.prototype || proto === null) return {
+		...state,
+		[annotationKey]: protectedAnnotations
+	};
+	const cloned = Object.create(proto, Object.getOwnPropertyDescriptors(state));
+	cloned[annotationKey] = protectedAnnotations;
+	return cloned;
+}
 /**
 * Extracts annotations from parser state.
 *
@@ -504,69 +607,22 @@ function hasMeaningfulAnnotations(annotations) {
 */
 function injectAnnotations(state, annotations) {
 	if (!hasMeaningfulAnnotations(annotations)) return state;
-	const protectedAnnotations = protectAnnotationValue(annotations, createAnnotationProtectionContext());
-	if (state == null || typeof state !== "object") {
-		const wrapper = {};
-		Object.defineProperties(wrapper, {
-			[annotationKey]: {
-				value: protectedAnnotations,
-				enumerable: true,
-				writable: true,
-				configurable: true
-			},
-			[annotationStateValueKey]: {
-				value: state,
-				enumerable: false,
-				writable: true,
-				configurable: true
-			},
-			[annotationWrapperKey]: {
-				value: true,
-				enumerable: false,
-				writable: true,
-				configurable: true
-			}
-		});
-		injectedAnnotationWrappers.add(wrapper);
-		return wrapper;
-	}
-	if (Array.isArray(state)) {
-		const cloned$1 = [...state];
-		cloned$1[annotationKey] = protectedAnnotations;
-		return cloned$1;
-	}
-	if (isInjectedAnnotationWrapper(state)) {
-		state[annotationKey] = protectedAnnotations;
-		return state;
-	}
-	if (state instanceof Date) {
-		const cloned$1 = new Date(state.getTime());
-		cloned$1[annotationKey] = protectedAnnotations;
-		return cloned$1;
-	}
-	if (state instanceof Map) {
-		const cloned$1 = new Map(state);
-		cloned$1[annotationKey] = protectedAnnotations;
-		return cloned$1;
-	}
-	if (state instanceof Set) {
-		const cloned$1 = new Set(state);
-		cloned$1[annotationKey] = protectedAnnotations;
-		return cloned$1;
-	}
-	if (state instanceof RegExp) {
-		const cloned$1 = cloneRegExpShape(state);
-		cloned$1[annotationKey] = protectedAnnotations;
-		return cloned$1;
-	}
-	const proto = Object.getPrototypeOf(state);
-	if (proto === Object.prototype || proto === null) return {
-		...state,
-		[annotationKey]: protectedAnnotations
-	};
-	const cloned = Object.create(proto, Object.getOwnPropertyDescriptors(state));
-	cloned[annotationKey] = protectedAnnotations;
-	return cloned;
+	return injectAnnotationsWithContext(state, annotations, createAnnotationProtectionContext());
+}
+/**
+* Injects annotations for a fresh parse run.
+*
+* This path re-wraps protected views from previous runs so stateful container
+* internals remain isolated across parse entrypoints.
+*
+* @param state The parser state to annotate.
+* @param annotations The annotations to inject.
+* @returns Annotated state for the fresh run.
+* @internal
+*/
+function injectFreshRunAnnotations(state, annotations) {
+	if (!hasMeaningfulAnnotations(annotations)) return state;
+	return injectAnnotationsWithContext(state, normalizeRunAnnotationInput(annotations), createAnnotationProtectionContext(true));
 }
 /**
 * Unwraps a primitive-state annotation wrapper injected by Optique internals.
@@ -597,4 +653,4 @@ function isInjectedAnnotationWrapper(value) {
 }
 
 //#endregion
-export { annotateFreshArray, annotationKey, annotationStateValueKey, annotationWrapperKey, firstPassAnnotationKey, getAnnotations, hasMeaningfulAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationWrapper, normalizeRunAnnotationInput, unwrapInjectedAnnotationWrapper };
+export { annotateFreshArray, annotationKey, annotationStateValueKey, annotationWrapperKey, firstPassAnnotationKey, getAnnotations, hasMeaningfulAnnotations, inheritAnnotations, injectAnnotations, injectFreshRunAnnotations, isInjectedAnnotationWrapper, normalizeRunAnnotationInput, unwrapInjectedAnnotationWrapper };

package/dist/parser.cjs

@@ -69,7 +69,7 @@ function createParserContext(frame, exec) {
 function injectAnnotationsIntoState(state, options) {
 	const annotations = options?.annotations;
 	if (!require_annotations.hasMeaningfulAnnotations(annotations)) return state;
-	return require_annotations.injectAnnotations(state, require_annotations.normalizeRunAnnotationInput(annotations));
+	return require_annotations.injectFreshRunAnnotations(state, annotations);
 }
 /**
 * Parses an array of command-line arguments using the provided combined parser.

package/dist/parser.js

@@ -1,4 +1,4 @@
-import { hasMeaningfulAnnotations, injectAnnotations, isInjectedAnnotationWrapper, normalizeRunAnnotationInput, unwrapInjectedAnnotationWrapper } from "./annotations.js";
+import { hasMeaningfulAnnotations, injectFreshRunAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper } from "./annotations.js";
 import { cloneMessage, message } from "./message.js";
 import { cloneUsage, normalizeUsage } from "./usage.js";
 import { cloneDocEntry, isDocEntryHidden } from "./doc.js";
@@ -69,7 +69,7 @@ function createParserContext(frame, exec) {
 function injectAnnotationsIntoState(state, options) {
 	const annotations = options?.annotations;
 	if (!hasMeaningfulAnnotations(annotations)) return state;
-	return injectAnnotations(state, normalizeRunAnnotationInput(annotations));
+	return injectFreshRunAnnotations(state, annotations);
 }
 /**
 * Parses an array of command-line arguments using the provided combined parser.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.1856+acef001b",
+  "version": "1.0.0-dev.1860+656f0c47",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",