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

package/dist/annotations.cjs

@@ -361,6 +361,20 @@ 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;
+}
+/**
 * Extracts annotations from parser state.
 *
 * @param state Parser state that may contain annotations
@@ -594,4 +608,5 @@ exports.hasMeaningfulAnnotations = hasMeaningfulAnnotations;
 exports.inheritAnnotations = inheritAnnotations;
 exports.injectAnnotations = injectAnnotations;
 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
@@ -169,4 +181,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, 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
@@ -169,4 +181,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, isInjectedAnnotationWrapper, normalizeRunAnnotationInput, unwrapInjectedAnnotationWrapper };

package/dist/annotations.js

@@ -360,6 +360,20 @@ 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;
+}
+/**
 * Extracts annotations from parser state.
 *
 * @param state Parser state that may contain annotations
@@ -583,4 +597,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, 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.injectAnnotations(state, require_annotations.normalizeRunAnnotationInput(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, injectAnnotations, isInjectedAnnotationWrapper, normalizeRunAnnotationInput, 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 injectAnnotations(state, normalizeRunAnnotationInput(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.1856+acef001b",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",