@optique/core 1.0.0-dev.524 → 1.0.0-dev.555

package/dist/facade.js

@@ -1,4 +1,4 @@
-import { annotationKey } from "./annotations.js";
+import { injectAnnotations } from "./annotations.js";
 import { commandLine, formatMessage, lineBreak, message, optionName, text, value } from "./message.js";
 import { bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { dispatchByMode } from "./mode-dispatch.js";
@@ -870,13 +870,8 @@ async function collectPhase1Annotations(contexts, options) {
 	let hasDynamic = false;
 	for (const context of contexts) {
 		const result = context.getAnnotations(void 0, options);
-		if (result instanceof Promise) {
-			hasDynamic = true;
-			annotationsList.push(await result);
-		} else {
-			if (Object.getOwnPropertySymbols(result).length === 0) hasDynamic = true;
-			annotationsList.push(result);
-		}
+		hasDynamic ||= needsTwoPhaseContext(context, result);
+		annotationsList.push(result instanceof Promise ? await result : result);
 	}
 	return {
 		annotations: mergeAnnotations(annotationsList),
@@ -914,7 +909,7 @@ function collectPhase1AnnotationsSync(contexts, options) {
 	for (const context of contexts) {
 		const result = context.getAnnotations(void 0, options);
 		if (result instanceof Promise) throw new Error(`Context ${String(context.id)} returned a Promise in sync mode. Use runWith() or runWithAsync() for async contexts.`);
-		if (Object.getOwnPropertySymbols(result).length === 0) hasDynamic = true;
+		hasDynamic ||= needsTwoPhaseContext(context, result);
 		annotationsList.push(result);
 	}
 	return {
@@ -923,6 +918,18 @@ function collectPhase1AnnotationsSync(contexts, options) {
 	};
 }
 /**
+* Determines whether a context requires a second parse pass.
+*
+* Explicit `mode` declarations take precedence over legacy heuristics so
+* static contexts are not forced into two-phase parsing when they return
+* empty annotations or a Promise.
+*/
+function needsTwoPhaseContext(context, result) {
+	if (context.mode !== void 0) return context.mode === "dynamic";
+	if (result instanceof Promise) return true;
+	return Object.getOwnPropertySymbols(result).length === 0;
+}
+/**
 * Collects annotations from all contexts synchronously.
 *
 * @param contexts Source contexts to collect annotations from.
@@ -1122,10 +1129,7 @@ function runWithAsync(parser, programName, contexts, options) {
 * @returns A new parser with annotations in its initial state.
 */
 function injectAnnotationsIntoParser(parser, annotations) {
-	const newInitialState = {
-		...typeof parser.initialState === "object" && parser.initialState !== null ? parser.initialState : {},
-		[annotationKey]: annotations
-	};
+	const newInitialState = injectAnnotations(parser.initialState, annotations);
 	return {
 		...parser,
 		initialState: newInitialState

package/dist/modifiers.cjs

@@ -1,3 +1,4 @@
+const require_annotations = require('./annotations.cjs');
 const require_message = require('./message.cjs');
 const require_dependency = require('./dependency.cjs');
 const require_mode_dispatch = require('./mode-dispatch.cjs');
@@ -409,50 +410,112 @@ function map(parser, transform) {
 function multiple(parser, options = {}) {
 	const syncParser = parser;
 	const { min = 0, max = Infinity } = options;
+	const unwrapInjectedWrapper = require_annotations.unwrapInjectedAnnotationWrapper;
+	const annotateFreshArray = (source, target) => {
+		const annotations = require_annotations.getAnnotations(source);
+		if (annotations === void 0) return target;
+		const annotated = target;
+		annotated[require_annotations.annotationKey] = annotations;
+		return annotated;
+	};
+	const completeSyncWithUnwrappedFallback = (state) => {
+		try {
+			return syncParser.complete(state);
+		} catch (error) {
+			if (!require_annotations.isInjectedAnnotationWrapper(state)) throw error;
+			return syncParser.complete(unwrapInjectedWrapper(state));
+		}
+	};
+	const parseSyncWithUnwrappedFallback = (context) => {
+		try {
+			const result = syncParser.parse(context);
+			if (result.success || result.consumed !== 0 || !require_annotations.isInjectedAnnotationWrapper(context.state)) return result;
+			return syncParser.parse({
+				...context,
+				state: unwrapInjectedWrapper(context.state)
+			});
+		} catch (error) {
+			if (!require_annotations.isInjectedAnnotationWrapper(context.state)) throw error;
+			return syncParser.parse({
+				...context,
+				state: unwrapInjectedWrapper(context.state)
+			});
+		}
+	};
+	const completeAsyncWithUnwrappedFallback = async (state) => {
+		try {
+			return await parser.complete(state);
+		} catch (error) {
+			if (!require_annotations.isInjectedAnnotationWrapper(state)) throw error;
+			return await parser.complete(unwrapInjectedWrapper(state));
+		}
+	};
+	const parseAsyncWithUnwrappedFallback = async (context) => {
+		try {
+			const result = await parser.parse(context);
+			if (result.success || result.consumed !== 0 || !require_annotations.isInjectedAnnotationWrapper(context.state)) return result;
+			return await parser.parse({
+				...context,
+				state: unwrapInjectedWrapper(context.state)
+			});
+		} catch (error) {
+			if (!require_annotations.isInjectedAnnotationWrapper(context.state)) throw error;
+			return await parser.parse({
+				...context,
+				state: unwrapInjectedWrapper(context.state)
+			});
+		}
+	};
 	const parseSync = (context) => {
 		let added = context.state.length < 1;
-		let result = syncParser.parse({
+		const currentItemStateWithAnnotations = context.state.at(-1) ?? require_annotations.inheritAnnotations(context.state, syncParser.initialState);
+		let result = parseSyncWithUnwrappedFallback({
 			...context,
-			state: context.state.at(-1) ?? syncParser.initialState
+			state: currentItemStateWithAnnotations
 		});
 		if (!result.success) if (!added) {
-			result = syncParser.parse({
+			const nextInitialState = require_annotations.inheritAnnotations(context.state, syncParser.initialState);
+			result = parseSyncWithUnwrappedFallback({
 				...context,
-				state: syncParser.initialState
+				state: nextInitialState
 			});
 			if (!result.success) return result;
 			added = true;
 		} else return result;
+		const itemAnnotationSource = added ? context.state : currentItemStateWithAnnotations;
+		const nextItemState = require_annotations.inheritAnnotations(itemAnnotationSource, result.next.state);
 		return {
 			success: true,
 			next: {
 				...result.next,
-				state: [...added ? context.state : context.state.slice(0, -1), result.next.state]
+				state: annotateFreshArray(context.state, [...added ? context.state : context.state.slice(0, -1), nextItemState])
 			},
 			consumed: result.consumed
 		};
 	};
 	const parseAsync = async (context) => {
 		let added = context.state.length < 1;
-		let resultOrPromise = parser.parse({
+		const currentItemStateWithAnnotations = context.state.at(-1) ?? require_annotations.inheritAnnotations(context.state, parser.initialState);
+		let result = await parseAsyncWithUnwrappedFallback({
 			...context,
-			state: context.state.at(-1) ?? parser.initialState
+			state: currentItemStateWithAnnotations
 		});
-		let result = await resultOrPromise;
 		if (!result.success) if (!added) {
-			resultOrPromise = parser.parse({
+			const nextInitialState = require_annotations.inheritAnnotations(context.state, parser.initialState);
+			result = await parseAsyncWithUnwrappedFallback({
 				...context,
-				state: parser.initialState
+				state: nextInitialState
 			});
-			result = await resultOrPromise;
 			if (!result.success) return result;
 			added = true;
 		} else return result;
+		const itemAnnotationSource = added ? context.state : currentItemStateWithAnnotations;
+		const nextItemState = require_annotations.inheritAnnotations(itemAnnotationSource, result.next.state);
 		return {
 			success: true,
 			next: {
 				...result.next,
-				state: [...added ? context.state : context.state.slice(0, -1), result.next.state]
+				state: annotateFreshArray(context.state, [...added ? context.state : context.state.slice(0, -1), nextItemState])
 			},
 			consumed: result.consumed
 		};
@@ -475,8 +538,8 @@ function multiple(parser, options = {}) {
 			return require_mode_dispatch.dispatchByMode(parser.$mode, () => {
 				const result = [];
 				for (const s of state) {
-					const valueResult = syncParser.complete(s);
-					if (valueResult.success) result.push(valueResult.value);
+					const valueResult = completeSyncWithUnwrappedFallback(s);
+					if (valueResult.success) result.push(unwrapInjectedWrapper(valueResult.value));
 					else return {
 						success: false,
 						error: valueResult.error
@@ -484,9 +547,9 @@ function multiple(parser, options = {}) {
 				}
 				return validateMultipleResult(result);
 			}, async () => {
-				const results = await Promise.all(state.map((s) => parser.complete(s)));
+				const results = await Promise.all(state.map((s) => completeAsyncWithUnwrappedFallback(s)));
 				const values = [];
-				for (const valueResult of results) if (valueResult.success) values.push(valueResult.value);
+				for (const valueResult of results) if (valueResult.success) values.push(unwrapInjectedWrapper(valueResult.value));
 				else return {
 					success: false,
 					error: valueResult.error
@@ -496,10 +559,13 @@ function multiple(parser, options = {}) {
 		},
 		suggest(context, prefix) {
 			const selectedValues = /* @__PURE__ */ new Set();
+			const suggestInitialState = require_annotations.inheritAnnotations(context.state, parser.initialState);
+			const suggestFallbackState = unwrapInjectedWrapper(suggestInitialState);
+			const hasSuggestFallbackState = suggestFallbackState !== suggestInitialState;
 			for (const s of context.state) {
-				const completed = syncParser.complete(s);
+				const completed = completeSyncWithUnwrappedFallback(s);
 				if (completed.success) {
-					const valueStr = String(completed.value);
+					const valueStr = String(unwrapInjectedWrapper(completed.value));
 					selectedValues.add(valueStr);
 				}
 			}
@@ -507,23 +573,80 @@ function multiple(parser, options = {}) {
 				if (suggestion.kind === "literal") return !selectedValues.has(suggestion.text);
 				return true;
 			};
+			const suggestionKey = (suggestion) => {
+				const description = suggestion.description == null ? "" : require_message.formatMessage(suggestion.description);
+				if (suggestion.kind === "literal") return JSON.stringify([
+					"literal",
+					suggestion.text,
+					description
+				]);
+				return JSON.stringify([
+					"file",
+					suggestion.type,
+					suggestion.pattern ?? "",
+					suggestion.includeHidden === true,
+					suggestion.extensions == null ? "" : suggestion.extensions.join("\0"),
+					description
+				]);
+			};
 			return require_mode_dispatch.dispatchIterableByMode(parser.$mode, function* () {
-				for (const s of syncParser.suggest({
+				const emitted = /* @__PURE__ */ new Set();
+				const yieldUnique = function* (suggestions) {
+					for (const s of suggestions) {
+						const key = suggestionKey(s);
+						if (shouldInclude(s) && !emitted.has(key)) {
+							emitted.add(key);
+							yield s;
+						}
+					}
+				};
+				let shouldTryFallback = false;
+				try {
+					yield* yieldUnique(syncParser.suggest({
+						...context,
+						state: suggestInitialState
+					}, prefix));
+				} catch (error) {
+					if (!hasSuggestFallbackState) throw error;
+					shouldTryFallback = true;
+				}
+				if (shouldTryFallback) yield* yieldUnique(syncParser.suggest({
 					...context,
-					state: parser.initialState
-				}, prefix)) if (shouldInclude(s)) yield s;
+					state: suggestFallbackState
+				}, prefix));
 			}, async function* () {
-				const suggestions = parser.suggest({
+				const emitted = /* @__PURE__ */ new Set();
+				const yieldUnique = async function* (suggestions) {
+					for await (const s of suggestions) {
+						const key = suggestionKey(s);
+						if (shouldInclude(s) && !emitted.has(key)) {
+							emitted.add(key);
+							yield s;
+						}
+					}
+				};
+				let shouldTryFallback = false;
+				try {
+					yield* yieldUnique(parser.suggest({
+						...context,
+						state: suggestInitialState
+					}, prefix));
+				} catch (error) {
+					if (!hasSuggestFallbackState) throw error;
+					shouldTryFallback = true;
+				}
+				if (shouldTryFallback) yield* yieldUnique(parser.suggest({
 					...context,
-					state: parser.initialState
-				}, prefix);
-				for await (const s of suggestions) if (shouldInclude(s)) yield s;
+					state: suggestFallbackState
+				}, prefix));
 			});
 		},
 		getDocFragments(state, defaultValue) {
-			const innerState = state.kind === "unavailable" ? { kind: "unavailable" } : state.state.length > 0 ? {
+			const latestState = state.kind === "available" && state.state.length > 0 ? state.state.at(-1) : void 0;
+			const latestInnerState = latestState != null && require_annotations.isInjectedAnnotationWrapper(latestState) ? unwrapInjectedWrapper(latestState) : latestState;
+			const innerState = state.kind === "unavailable" ? { kind: "unavailable" } : latestInnerState !== void 0 ? {
 				kind: "available",
-				state: state.state.at(-1)
+				state: latestInnerState
 			} : { kind: "unavailable" };
 			return syncParser.getDocFragments(innerState, defaultValue != null && defaultValue.length > 0 ? defaultValue[0] : void 0);
 		}

package/dist/modifiers.js

@@ -1,3 +1,4 @@
+import { annotationKey, getAnnotations, inheritAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper } from "./annotations.js";
 import { formatMessage, message, text } from "./message.js";
 import { createDependencySourceState, dependencyId, isDependencySourceState, isPendingDependencySourceState, isWrappedDependencySource, transformsDependencyValue, transformsDependencyValueMarker, wrappedDependencySourceMarker } from "./dependency.js";
 import { dispatchByMode, dispatchIterableByMode, mapModeValue } from "./mode-dispatch.js";
@@ -409,50 +410,112 @@ function map(parser, transform) {
 function multiple(parser, options = {}) {
 	const syncParser = parser;
 	const { min = 0, max = Infinity } = options;
+	const unwrapInjectedWrapper = unwrapInjectedAnnotationWrapper;
+	const annotateFreshArray = (source, target) => {
+		const annotations = getAnnotations(source);
+		if (annotations === void 0) return target;
+		const annotated = target;
+		annotated[annotationKey] = annotations;
+		return annotated;
+	};
+	const completeSyncWithUnwrappedFallback = (state) => {
+		try {
+			return syncParser.complete(state);
+		} catch (error) {
+			if (!isInjectedAnnotationWrapper(state)) throw error;
+			return syncParser.complete(unwrapInjectedWrapper(state));
+		}
+	};
+	const parseSyncWithUnwrappedFallback = (context) => {
+		try {
+			const result = syncParser.parse(context);
+			if (result.success || result.consumed !== 0 || !isInjectedAnnotationWrapper(context.state)) return result;
+			return syncParser.parse({
+				...context,
+				state: unwrapInjectedWrapper(context.state)
+			});
+		} catch (error) {
+			if (!isInjectedAnnotationWrapper(context.state)) throw error;
+			return syncParser.parse({
+				...context,
+				state: unwrapInjectedWrapper(context.state)
+			});
+		}
+	};
+	const completeAsyncWithUnwrappedFallback = async (state) => {
+		try {
+			return await parser.complete(state);
+		} catch (error) {
+			if (!isInjectedAnnotationWrapper(state)) throw error;
+			return await parser.complete(unwrapInjectedWrapper(state));
+		}
+	};
+	const parseAsyncWithUnwrappedFallback = async (context) => {
+		try {
+			const result = await parser.parse(context);
+			if (result.success || result.consumed !== 0 || !isInjectedAnnotationWrapper(context.state)) return result;
+			return await parser.parse({
+				...context,
+				state: unwrapInjectedWrapper(context.state)
+			});
+		} catch (error) {
+			if (!isInjectedAnnotationWrapper(context.state)) throw error;
+			return await parser.parse({
+				...context,
+				state: unwrapInjectedWrapper(context.state)
+			});
+		}
+	};
 	const parseSync = (context) => {
 		let added = context.state.length < 1;
-		let result = syncParser.parse({
+		const currentItemStateWithAnnotations = context.state.at(-1) ?? inheritAnnotations(context.state, syncParser.initialState);
+		let result = parseSyncWithUnwrappedFallback({
 			...context,
-			state: context.state.at(-1) ?? syncParser.initialState
+			state: currentItemStateWithAnnotations
 		});
 		if (!result.success) if (!added) {
-			result = syncParser.parse({
+			const nextInitialState = inheritAnnotations(context.state, syncParser.initialState);
+			result = parseSyncWithUnwrappedFallback({
 				...context,
-				state: syncParser.initialState
+				state: nextInitialState
 			});
 			if (!result.success) return result;
 			added = true;
 		} else return result;
+		const itemAnnotationSource = added ? context.state : currentItemStateWithAnnotations;
+		const nextItemState = inheritAnnotations(itemAnnotationSource, result.next.state);
 		return {
 			success: true,
 			next: {
 				...result.next,
-				state: [...added ? context.state : context.state.slice(0, -1), result.next.state]
+				state: annotateFreshArray(context.state, [...added ? context.state : context.state.slice(0, -1), nextItemState])
 			},
 			consumed: result.consumed
 		};
 	};
 	const parseAsync = async (context) => {
 		let added = context.state.length < 1;
-		let resultOrPromise = parser.parse({
+		const currentItemStateWithAnnotations = context.state.at(-1) ?? inheritAnnotations(context.state, parser.initialState);
+		let result = await parseAsyncWithUnwrappedFallback({
 			...context,
-			state: context.state.at(-1) ?? parser.initialState
+			state: currentItemStateWithAnnotations
 		});
-		let result = await resultOrPromise;
 		if (!result.success) if (!added) {
-			resultOrPromise = parser.parse({
+			const nextInitialState = inheritAnnotations(context.state, parser.initialState);
+			result = await parseAsyncWithUnwrappedFallback({
 				...context,
-				state: parser.initialState
+				state: nextInitialState
 			});
-			result = await resultOrPromise;
 			if (!result.success) return result;
 			added = true;
 		} else return result;
+		const itemAnnotationSource = added ? context.state : currentItemStateWithAnnotations;
+		const nextItemState = inheritAnnotations(itemAnnotationSource, result.next.state);
 		return {
 			success: true,
 			next: {
 				...result.next,
-				state: [...added ? context.state : context.state.slice(0, -1), result.next.state]
+				state: annotateFreshArray(context.state, [...added ? context.state : context.state.slice(0, -1), nextItemState])
 			},
 			consumed: result.consumed
 		};
@@ -475,8 +538,8 @@ function multiple(parser, options = {}) {
 			return dispatchByMode(parser.$mode, () => {
 				const result = [];
 				for (const s of state) {
-					const valueResult = syncParser.complete(s);
-					if (valueResult.success) result.push(valueResult.value);
+					const valueResult = completeSyncWithUnwrappedFallback(s);
+					if (valueResult.success) result.push(unwrapInjectedWrapper(valueResult.value));
 					else return {
 						success: false,
 						error: valueResult.error
@@ -484,9 +547,9 @@ function multiple(parser, options = {}) {
 				}
 				return validateMultipleResult(result);
 			}, async () => {
-				const results = await Promise.all(state.map((s) => parser.complete(s)));
+				const results = await Promise.all(state.map((s) => completeAsyncWithUnwrappedFallback(s)));
 				const values = [];
-				for (const valueResult of results) if (valueResult.success) values.push(valueResult.value);
+				for (const valueResult of results) if (valueResult.success) values.push(unwrapInjectedWrapper(valueResult.value));
 				else return {
 					success: false,
 					error: valueResult.error
@@ -496,10 +559,13 @@ function multiple(parser, options = {}) {
 		},
 		suggest(context, prefix) {
 			const selectedValues = /* @__PURE__ */ new Set();
+			const suggestInitialState = inheritAnnotations(context.state, parser.initialState);
+			const suggestFallbackState = unwrapInjectedWrapper(suggestInitialState);
+			const hasSuggestFallbackState = suggestFallbackState !== suggestInitialState;
 			for (const s of context.state) {
-				const completed = syncParser.complete(s);
+				const completed = completeSyncWithUnwrappedFallback(s);
 				if (completed.success) {
-					const valueStr = String(completed.value);
+					const valueStr = String(unwrapInjectedWrapper(completed.value));
 					selectedValues.add(valueStr);
 				}
 			}
@@ -507,23 +573,80 @@ function multiple(parser, options = {}) {
 				if (suggestion.kind === "literal") return !selectedValues.has(suggestion.text);
 				return true;
 			};
+			const suggestionKey = (suggestion) => {
+				const description = suggestion.description == null ? "" : formatMessage(suggestion.description);
+				if (suggestion.kind === "literal") return JSON.stringify([
+					"literal",
+					suggestion.text,
+					description
+				]);
+				return JSON.stringify([
+					"file",
+					suggestion.type,
+					suggestion.pattern ?? "",
+					suggestion.includeHidden === true,
+					suggestion.extensions == null ? "" : suggestion.extensions.join("\0"),
+					description
+				]);
+			};
 			return dispatchIterableByMode(parser.$mode, function* () {
-				for (const s of syncParser.suggest({
+				const emitted = /* @__PURE__ */ new Set();
+				const yieldUnique = function* (suggestions) {
+					for (const s of suggestions) {
+						const key = suggestionKey(s);
+						if (shouldInclude(s) && !emitted.has(key)) {
+							emitted.add(key);
+							yield s;
+						}
+					}
+				};
+				let shouldTryFallback = false;
+				try {
+					yield* yieldUnique(syncParser.suggest({
+						...context,
+						state: suggestInitialState
+					}, prefix));
+				} catch (error) {
+					if (!hasSuggestFallbackState) throw error;
+					shouldTryFallback = true;
+				}
+				if (shouldTryFallback) yield* yieldUnique(syncParser.suggest({
 					...context,
-					state: parser.initialState
-				}, prefix)) if (shouldInclude(s)) yield s;
+					state: suggestFallbackState
+				}, prefix));
 			}, async function* () {
-				const suggestions = parser.suggest({
+				const emitted = /* @__PURE__ */ new Set();
+				const yieldUnique = async function* (suggestions) {
+					for await (const s of suggestions) {
+						const key = suggestionKey(s);
+						if (shouldInclude(s) && !emitted.has(key)) {
+							emitted.add(key);
+							yield s;
+						}
+					}
+				};
+				let shouldTryFallback = false;
+				try {
+					yield* yieldUnique(parser.suggest({
+						...context,
+						state: suggestInitialState
+					}, prefix));
+				} catch (error) {
+					if (!hasSuggestFallbackState) throw error;
+					shouldTryFallback = true;
+				}
+				if (shouldTryFallback) yield* yieldUnique(parser.suggest({
 					...context,
-					state: parser.initialState
-				}, prefix);
-				for await (const s of suggestions) if (shouldInclude(s)) yield s;
+					state: suggestFallbackState
+				}, prefix));
 			});
 		},
 		getDocFragments(state, defaultValue) {
-			const innerState = state.kind === "unavailable" ? { kind: "unavailable" } : state.state.length > 0 ? {
+			const latestState = state.kind === "available" && state.state.length > 0 ? state.state.at(-1) : void 0;
+			const latestInnerState = latestState != null && isInjectedAnnotationWrapper(latestState) ? unwrapInjectedWrapper(latestState) : latestState;
+			const innerState = state.kind === "unavailable" ? { kind: "unavailable" } : latestInnerState !== void 0 ? {
 				kind: "available",
-				state: state.state.at(-1)
+				state: latestInnerState
 			} : { kind: "unavailable" };
 			return syncParser.getDocFragments(innerState, defaultValue != null && defaultValue.length > 0 ? defaultValue[0] : void 0);
 		}

package/dist/parser.cjs

@@ -7,6 +7,11 @@ const require_modifiers = require('./modifiers.cjs');
 const require_primitives = require('./primitives.cjs');
 
 //#region src/parser.ts
+function injectAnnotationsIntoState(state, options) {
+	const annotations = options?.annotations;
+	if (annotations == null) return state;
+	return require_annotations.injectAnnotations(state, annotations);
+}
 /**
 * Parses an array of command-line arguments using the provided combined parser.
 * This function processes the input arguments, applying the parser to each
@@ -30,11 +35,8 @@ const require_primitives = require('./primitives.cjs');
 * @since 0.10.0 Added optional `options` parameter for annotations support.
 */
 function parseSync(parser, args, options) {
-	let initialState = parser.initialState;
-	if (options?.annotations) initialState = {
-		...typeof initialState === "object" && initialState !== null ? initialState : {},
-		[require_annotations.annotationKey]: options.annotations
-	};
+	const initialState = injectAnnotationsIntoState(parser.initialState, options);
+	const shouldUnwrapAnnotatedValue = options?.annotations != null || require_annotations.isInjectedAnnotationWrapper(parser.initialState);
 	let context = {
 		buffer: args,
 		optionsTerminated: false,
@@ -57,7 +59,7 @@ function parseSync(parser, args, options) {
 	const endResult = parser.complete(context.state);
 	return endResult.success ? {
 		success: true,
-		value: endResult.value
+		value: shouldUnwrapAnnotatedValue ? require_annotations.unwrapInjectedAnnotationWrapper(endResult.value) : endResult.value
 	} : {
 		success: false,
 		error: endResult.error
@@ -83,11 +85,8 @@ function parseSync(parser, args, options) {
 * @since 0.10.0 Added optional `options` parameter for annotations support.
 */
 async function parseAsync(parser, args, options) {
-	let initialState = parser.initialState;
-	if (options?.annotations) initialState = {
-		...typeof initialState === "object" && initialState !== null ? initialState : {},
-		[require_annotations.annotationKey]: options.annotations
-	};
+	const initialState = injectAnnotationsIntoState(parser.initialState, options);
+	const shouldUnwrapAnnotatedValue = options?.annotations != null || require_annotations.isInjectedAnnotationWrapper(parser.initialState);
 	let context = {
 		buffer: args,
 		optionsTerminated: false,
@@ -110,7 +109,7 @@ async function parseAsync(parser, args, options) {
 	const endResult = await parser.complete(context.state);
 	return endResult.success ? {
 		success: true,
-		value: endResult.value
+		value: shouldUnwrapAnnotatedValue ? require_annotations.unwrapInjectedAnnotationWrapper(endResult.value) : endResult.value
 	} : {
 		success: false,
 		error: endResult.error
@@ -180,11 +179,7 @@ function parse(parser, args, options) {
 function suggestSync(parser, args, options) {
 	const allButLast = args.slice(0, -1);
 	const prefix = args[args.length - 1];
-	let initialState = parser.initialState;
-	if (options?.annotations) initialState = {
-		...typeof initialState === "object" && initialState !== null ? initialState : {},
-		[require_annotations.annotationKey]: options.annotations
-	};
+	const initialState = injectAnnotationsIntoState(parser.initialState, options);
 	let context = {
 		buffer: allButLast,
 		optionsTerminated: false,
@@ -223,11 +218,7 @@ function suggestSync(parser, args, options) {
 async function suggestAsync(parser, args, options) {
 	const allButLast = args.slice(0, -1);
 	const prefix = args[args.length - 1];
-	let initialState = parser.initialState;
-	if (options?.annotations) initialState = {
-		...typeof initialState === "object" && initialState !== null ? initialState : {},
-		[require_annotations.annotationKey]: options.annotations
-	};
+	const initialState = injectAnnotationsIntoState(parser.initialState, options);
 	let context = {
 		buffer: allButLast,
 		optionsTerminated: false,
@@ -338,11 +329,7 @@ function getDocPage(parser, args = [], options) {
 * Internal sync implementation of getDocPage.
 */
 function getDocPageSyncImpl(parser, args, options) {
-	let initialState = parser.initialState;
-	if (options?.annotations) initialState = {
-		...typeof initialState === "object" && initialState !== null ? initialState : {},
-		[require_annotations.annotationKey]: options.annotations
-	};
+	const initialState = injectAnnotationsIntoState(parser.initialState, options);
 	let context = {
 		buffer: args,
 		optionsTerminated: false,
@@ -360,11 +347,7 @@ function getDocPageSyncImpl(parser, args, options) {
 * Internal async implementation of getDocPage.
 */
 async function getDocPageAsyncImpl(parser, args, options) {
-	let initialState = parser.initialState;
-	if (options?.annotations) initialState = {
-		...typeof initialState === "object" && initialState !== null ? initialState : {},
-		[require_annotations.annotationKey]: options.annotations
-	};
+	const initialState = injectAnnotationsIntoState(parser.initialState, options);
 	let context = {
 		buffer: args,
 		optionsTerminated: false,