@optique/core 1.0.0-dev.1854 → 1.0.0-dev.1858

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,10 @@ function copyRegExpMetadata(source, target, transformValue) {
 		}
 		Object.defineProperty(target, key, descriptor);
 	}
+}
+const regExpExcludedKeys = new Set(["lastIndex"]);
+function copyRegExpMetadata(source, target, transformValue) {
+	copyOwnProperties(source, target, transformValue, regExpExcludedKeys);
 	target.lastIndex = source.lastIndex;
 }
 function cloneRegExpShape(source) {
@@ -106,7 +116,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 +156,27 @@ 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 = new Map(target);
+	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 +194,34 @@ 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 = new Set(target);
+	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 +239,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 +269,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 +302,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 +341,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 +370,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);
@@ -361,6 +394,85 @@ function protectAnnotationValue(value, context) {
 	return value;
 }
 /**
+* Normalizes annotation input for a fresh parse run.
+*
+* When callers feed a protected annotation view returned by `getAnnotations()`
+* back into a new parse entrypoint, Optique unwraps it to the caller-owned
+* record first so the new run gets its own protected views.
+*
+* @param annotations The caller-supplied annotations input.
+* @returns The raw annotation record to inject for the new run.
+* @internal
+*/
+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.
 *
 * @param state Parser state that may contain annotations
@@ -491,69 +603,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.
@@ -593,5 +658,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

@@ -64,6 +64,18 @@ type Annotations = Record<symbol, unknown>;
  */
 type ReadonlyAnnotations = Readonly<Annotations>;
 type AnnotationInput = Annotations | ReadonlyAnnotations;
+/**
+ * Normalizes annotation input for a fresh parse run.
+ *
+ * When callers feed a protected annotation view returned by `getAnnotations()`
+ * back into a new parse entrypoint, Optique unwraps it to the caller-owned
+ * record first so the new run gets its own protected views.
+ *
+ * @param annotations The caller-supplied annotations input.
+ * @returns The raw annotation record to inject for the new run.
+ * @internal
+ */
+declare function normalizeRunAnnotationInput(annotations: AnnotationInput): AnnotationInput;
 /**
  * Options for parse functions.
  * @since 0.10.0
@@ -150,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.
  *
@@ -169,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, unwrapInjectedAnnotationWrapper };
+export { Annotations, ParseOptions, ReadonlyAnnotations, annotateFreshArray, annotationKey, annotationStateValueKey, annotationWrapperKey, firstPassAnnotationKey, getAnnotations, hasMeaningfulAnnotations, inheritAnnotations, injectAnnotations, injectFreshRunAnnotations, isInjectedAnnotationWrapper, normalizeRunAnnotationInput, unwrapInjectedAnnotationWrapper };

package/dist/annotations.d.ts

@@ -64,6 +64,18 @@ type Annotations = Record<symbol, unknown>;
  */
 type ReadonlyAnnotations = Readonly<Annotations>;
 type AnnotationInput = Annotations | ReadonlyAnnotations;
+/**
+ * Normalizes annotation input for a fresh parse run.
+ *
+ * When callers feed a protected annotation view returned by `getAnnotations()`
+ * back into a new parse entrypoint, Optique unwraps it to the caller-owned
+ * record first so the new run gets its own protected views.
+ *
+ * @param annotations The caller-supplied annotations input.
+ * @returns The raw annotation record to inject for the new run.
+ * @internal
+ */
+declare function normalizeRunAnnotationInput(annotations: AnnotationInput): AnnotationInput;
 /**
  * Options for parse functions.
  * @since 0.10.0
@@ -150,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.
  *
@@ -169,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, 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,10 @@ function copyRegExpMetadata(source, target, transformValue) {
 		}
 		Object.defineProperty(target, key, descriptor);
 	}
+}
+const regExpExcludedKeys = new Set(["lastIndex"]);
+function copyRegExpMetadata(source, target, transformValue) {
+	copyOwnProperties(source, target, transformValue, regExpExcludedKeys);
 	target.lastIndex = source.lastIndex;
 }
 function cloneRegExpShape(source) {
@@ -105,7 +115,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 +155,27 @@ 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 = new Map(target);
+	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 +193,34 @@ 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 = new Set(target);
+	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 +238,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 +268,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 +301,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 +340,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 +369,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);
@@ -360,6 +393,85 @@ function protectAnnotationValue(value, context) {
 	return value;
 }
 /**
+* Normalizes annotation input for a fresh parse run.
+*
+* When callers feed a protected annotation view returned by `getAnnotations()`
+* back into a new parse entrypoint, Optique unwraps it to the caller-owned
+* record first so the new run gets its own protected views.
+*
+* @param annotations The caller-supplied annotations input.
+* @returns The raw annotation record to inject for the new run.
+* @internal
+*/
+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.
 *
 * @param state Parser state that may contain annotations
@@ -490,69 +602,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.
@@ -583,4 +648,4 @@ function isInjectedAnnotationWrapper(value) {
 }
 
 //#endregion
-export { annotateFreshArray, annotationKey, annotationStateValueKey, annotationWrapperKey, firstPassAnnotationKey, getAnnotations, hasMeaningfulAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationWrapper, 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, 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, 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, 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.1854+f15dcfec",
+  "version": "1.0.0-dev.1858+fbabb36b",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",