@optique/core 1.0.0-dev.1901 → 1.0.0-dev.1970

package/dist/modifiers.js

@@ -1,47 +1,13 @@
-import { annotateFreshArray, annotationKey, getAnnotations, inheritAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper } from "./annotations.js";
+import { annotateFreshArray, annotationKey, getAnnotations, inheritAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper } from "./internal/annotations.js";
 import { formatMessage, message, text } from "./message.js";
-import { dispatchByMode, dispatchIterableByMode, mapModeValue, wrapForMode } from "./mode-dispatch.js";
-import { composeDependencyMetadata } from "./dependency-metadata.js";
-import { completeOrExtractPhase2Seed, extractPhase2Seed, extractPhase2SeedKey, phase2SeedFromValueResult } from "./phase2-seed.js";
-import { defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, unmatchedNonCliDependencySourceStateMarker } from "./parser.js";
+import { dispatchByMode, dispatchIterableByMode, mapModeValue, wrapForMode } from "./internal/mode-dispatch.js";
+import { defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, unmatchedNonCliDependencySourceStateMarker } from "./internal/parser.js";
 import { getDelegatedAnnotationState, hasDelegatedAnnotationCarrier, isAnnotationWrappedInitialState, normalizeDelegatedAnnotationState, normalizeNestedDelegatedAnnotationState } from "./annotation-state.js";
+import { mergeChildExec, withChildContext, withChildExecPath } from "./execution-context.js";
+import { completeOrExtractPhase2Seed, extractPhase2Seed, extractPhase2SeedKey, phase2SeedFromValueResult } from "./phase2-seed.js";
+import { composeDependencyMetadata } from "./dependency-metadata.js";
 
 //#region src/modifiers.ts
-function withChildExecPath(exec, segment) {
-	if (exec == null) return void 0;
-	return {
-		...exec,
-		path: [...exec.path ?? [], segment]
-	};
-}
-function mergeChildExec(parent, child) {
-	if (parent == null) return child;
-	if (child == null) return parent;
-	return {
-		...parent,
-		trace: child.trace ?? parent.trace,
-		dependencyRuntime: child.dependencyRuntime ?? parent.dependencyRuntime,
-		dependencyRegistry: child.dependencyRegistry ?? parent.dependencyRegistry,
-		commandPath: child.commandPath ?? parent.commandPath,
-		preCompletedByParser: child.preCompletedByParser ?? parent.preCompletedByParser,
-		excludedSourceFields: child.excludedSourceFields ?? parent.excludedSourceFields
-	};
-}
-function withChildContext(context, segment, state) {
-	const exec = withChildExecPath(context.exec, segment);
-	const dependencyRegistry = context.dependencyRegistry ?? exec?.dependencyRegistry;
-	return {
-		...context,
-		state,
-		...exec != null ? {
-			exec: dependencyRegistry === exec.dependencyRegistry ? exec : {
-				...exec,
-				dependencyRegistry
-			},
-			dependencyRegistry
-		} : {}
-	};
-}
 function isTerminalMultipleItemState(state) {
 	const unwrapped = unwrapMultipleItemState(state).value;
 	return unwrapped != null && typeof unwrapped === "object" && Object.hasOwn(unwrapped, "success") && typeof unwrapped.success === "boolean";
@@ -82,91 +48,105 @@ function unwrapMultipleItemState(state) {
 function isPromiseLike(value) {
 	return value != null && (typeof value === "object" || typeof value === "function") && "then" in value && typeof value.then === "function";
 }
-function normalizeOptionalLikeCompleteResult(result) {
-	return result.success ? {
+function normalizeOptionalLikeCompleteResult(result, shouldNormalize) {
+	return result.success && shouldNormalize ? {
 		...result,
 		value: normalizeNestedDelegatedAnnotationState(result.value)
 	} : result;
 }
+function shouldRetryOptionalLikeCompatibilityError(error, state) {
+	return error instanceof TypeError && state != null && typeof state === "object" && isInjectedAnnotationWrapper(state);
+}
 function completeOptionalLikeSync(parser, state, exec) {
 	const hasCarrier = hasDelegatedAnnotationCarrier(state);
-	const shouldRetryFalseResult = isAnnotationWrappedInitialState(state);
-	const run = (candidate) => normalizeOptionalLikeCompleteResult(parser.complete(candidate, exec));
+	const shouldRetryFalseResult = hasCarrier && isAnnotationWrappedInitialState(state);
+	const run = (candidate, shouldNormalize) => normalizeOptionalLikeCompleteResult(parser.complete(candidate, exec), shouldNormalize);
 	try {
-		const result = run(state);
-		if (!result.success && shouldRetryFalseResult) return run(normalizeDelegatedAnnotationState(state));
+		const result = run(state, hasCarrier);
+		if (!result.success && shouldRetryFalseResult) return run(normalizeDelegatedAnnotationState(state), false);
 		return result;
 	} catch (error) {
-		if (!hasCarrier) throw error;
-		return run(normalizeDelegatedAnnotationState(state));
+		if (!shouldRetryOptionalLikeCompatibilityError(error, state)) throw error;
+		return run(normalizeDelegatedAnnotationState(state), false);
 	}
 }
 async function completeOptionalLikeAsync(parser, state, exec) {
 	const hasCarrier = hasDelegatedAnnotationCarrier(state);
-	const shouldRetryFalseResult = isAnnotationWrappedInitialState(state);
-	const run = async (candidate) => normalizeOptionalLikeCompleteResult(await parser.complete(candidate, exec));
+	const shouldRetryFalseResult = hasCarrier && isAnnotationWrappedInitialState(state);
+	const run = async (candidate, shouldNormalize) => normalizeOptionalLikeCompleteResult(await parser.complete(candidate, exec), shouldNormalize);
 	try {
-		const result = await run(state);
-		if (!result.success && shouldRetryFalseResult) return await run(normalizeDelegatedAnnotationState(state));
+		const result = await run(state, hasCarrier);
+		if (!result.success && shouldRetryFalseResult) return await run(normalizeDelegatedAnnotationState(state), false);
 		return result;
 	} catch (error) {
-		if (!hasCarrier) throw error;
-		return await run(normalizeDelegatedAnnotationState(state));
+		if (!shouldRetryOptionalLikeCompatibilityError(error, state)) throw error;
+		return await run(normalizeDelegatedAnnotationState(state), false);
 	}
 }
-function normalizeOptionalLikePhase2Seed(seed) {
-	return seed == null ? null : {
+function normalizeOptionalLikePhase2Seed(seed, shouldNormalize) {
+	return seed == null ? null : shouldNormalize ? {
 		...seed,
 		value: normalizeNestedDelegatedAnnotationState(seed.value)
-	};
+	} : seed;
 }
 function extractOptionalLikePhase2Seed(parser, state, exec) {
-	if (!Array.isArray(state) && !(state != null && typeof state === "object")) return wrapForMode(parser.$mode, null);
+	if (!Array.isArray(state) && !(state != null && typeof state === "object")) return wrapForMode(parser.mode, null);
 	const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
 	const hasCarrier = hasDelegatedAnnotationCarrier(innerState);
-	return dispatchByMode(parser.$mode, () => {
+	const shouldRetryFalseResult = hasCarrier && isAnnotationWrappedInitialState(innerState);
+	return dispatchByMode(parser.mode, () => {
 		try {
 			const result = parser.complete(innerState, exec);
-			if (result.success) return normalizeOptionalLikePhase2Seed(phase2SeedFromValueResult(result));
+			if (result.success) return normalizeOptionalLikePhase2Seed(phase2SeedFromValueResult(result), hasCarrier);
+			if (shouldRetryFalseResult) {
+				const fallbackState = normalizeDelegatedAnnotationState(innerState);
+				const fallbackResult = parser.complete(fallbackState, exec);
+				if (fallbackResult.success) return normalizeOptionalLikePhase2Seed(phase2SeedFromValueResult(fallbackResult), false);
+			}
 			const seed = extractPhase2Seed(parser, innerState, exec);
 			if (seed == null && hasCarrier) {
 				const fallbackState = normalizeDelegatedAnnotationState(innerState);
-				return normalizeOptionalLikePhase2Seed(extractPhase2Seed(parser, fallbackState, exec));
+				return normalizeOptionalLikePhase2Seed(extractPhase2Seed(parser, fallbackState, exec), false);
 			}
-			return normalizeOptionalLikePhase2Seed(seed);
+			return normalizeOptionalLikePhase2Seed(seed, hasCarrier);
 		} catch (error) {
-			if (!hasCarrier) throw error;
+			if (!shouldRetryOptionalLikeCompatibilityError(error, innerState)) throw error;
 			const fallbackState = normalizeDelegatedAnnotationState(innerState);
 			const result = parser.complete(fallbackState, exec);
-			if (result.success) return normalizeOptionalLikePhase2Seed(phase2SeedFromValueResult(result));
-			return normalizeOptionalLikePhase2Seed(extractPhase2Seed(parser, fallbackState, exec));
+			if (result.success) return normalizeOptionalLikePhase2Seed(phase2SeedFromValueResult(result), false);
+			return normalizeOptionalLikePhase2Seed(extractPhase2Seed(parser, fallbackState, exec), false);
 		}
 	}, async () => {
 		try {
 			const result = await parser.complete(innerState, exec);
-			if (result.success) return normalizeOptionalLikePhase2Seed(phase2SeedFromValueResult(result));
+			if (result.success) return normalizeOptionalLikePhase2Seed(phase2SeedFromValueResult(result), hasCarrier);
+			if (shouldRetryFalseResult) {
+				const fallbackState = normalizeDelegatedAnnotationState(innerState);
+				const fallbackResult = await parser.complete(fallbackState, exec);
+				if (fallbackResult.success) return normalizeOptionalLikePhase2Seed(phase2SeedFromValueResult(fallbackResult), false);
+			}
 			const seed = await extractPhase2Seed(parser, innerState, exec);
 			if (seed == null && hasCarrier) {
 				const fallbackState = normalizeDelegatedAnnotationState(innerState);
-				return normalizeOptionalLikePhase2Seed(await extractPhase2Seed(parser, fallbackState, exec));
+				return normalizeOptionalLikePhase2Seed(await extractPhase2Seed(parser, fallbackState, exec), false);
 			}
-			return normalizeOptionalLikePhase2Seed(seed);
+			return normalizeOptionalLikePhase2Seed(seed, hasCarrier);
 		} catch (error) {
-			if (!hasCarrier) throw error;
+			if (!shouldRetryOptionalLikeCompatibilityError(error, innerState)) throw error;
 			const fallbackState = normalizeDelegatedAnnotationState(innerState);
 			const result = await parser.complete(fallbackState, exec);
-			if (result.success) return normalizeOptionalLikePhase2Seed(phase2SeedFromValueResult(result));
-			return normalizeOptionalLikePhase2Seed(await extractPhase2Seed(parser, fallbackState, exec));
+			if (result.success) return normalizeOptionalLikePhase2Seed(phase2SeedFromValueResult(result), false);
+			return normalizeOptionalLikePhase2Seed(await extractPhase2Seed(parser, fallbackState, exec), false);
 		}
 	});
 }
 /**
 * Computes the inner state to pass through to the wrapped parser inside
 * {@link optional} / {@link withDefault}.  When the outer state is an
-* array, the inner state is `state[0]`.  Otherwise — including the
+* array, the inner state is `state[0]`.  Otherwise, including the
 * common case where `optional()` sits at top level and the outer state
 * is either `undefined` or an annotation wrapper from `parseOptionalLike`
-* / `parse({ annotations })` — we use the wrapped parser's
+* / `parse({ annotations })`, we use the wrapped parser's
 * `initialState`, propagating annotations from the outer state so that
 * source-binding wrappers under `optional()` / `withDefault()` (e.g.,
 * `bindEnv()` / `bindConfig()`) can resolve their fallbacks.
@@ -176,19 +156,19 @@ function extractOptionalLikePhase2Seed(parser, state, exec) {
 function deriveOptionalInnerParseState(outerState, parser) {
 	if (Array.isArray(outerState)) {
 		const innerState = outerState[0];
-		if (getAnnotations(outerState) != null && innerState != null && typeof innerState === "object") return inheritAnnotations(outerState, innerState);
+		if (getAnnotations(outerState) != null && innerState != null && typeof innerState === "object") return getDelegatedAnnotationState(outerState, innerState);
 		return innerState;
 	}
 	const initial = parser.initialState;
 	if (initial != null && typeof initial !== "object") return initial;
-	return inheritAnnotations(outerState, initial);
+	return initial != null && typeof initial === "object" ? getDelegatedAnnotationState(outerState, initial) : inheritAnnotations(outerState, initial);
 }
 /**
 * Internal helper for optional-style parsing logic shared by optional()
 * and withDefault(). Handles the common pattern of:
 * - Unwrapping optional state to inner parser state
-* - Detecting if inner parser actually matched (state changed or no consumption)
-* - Returning success with undefined state when inner parser fails without consuming
+* - Detecting if the inner parser actually matched (state changed or no consumption)
+* - Returning success with undefined state when the inner parser fails without consuming
 * @internal
 */
 function parseOptionalStyleSync(context, parser) {
@@ -215,9 +195,12 @@ async function parseOptionalStyleAsync(context, parser) {
 * Internal helper to process optional-style parse results.
 * @internal
 */
+function hasOptionalLikeParseStateChanged(previousState, nextState) {
+	return previousState !== nextState && normalizeDelegatedAnnotationState(previousState) !== normalizeDelegatedAnnotationState(nextState);
+}
 function processOptionalStyleResult(result, innerState, context) {
 	if (result.success) {
-		if (result.next.state !== innerState || result.consumed.length === 0) return {
+		if (hasOptionalLikeParseStateChanged(innerState, result.next.state) || result.consumed.length === 0) return {
 			success: true,
 			...result.provisional ? { provisional: true } : {},
 			next: {
@@ -249,7 +232,7 @@ function processOptionalStyleResult(result, innerState, context) {
 * {@link withDefault} before delegating to the inner parser's hook.
 *
 * When state is an array, the adapter unwraps `state[0]` and propagates
-* annotations from the outer array.  Non-array objects (e.g., PromptBindState
+* annotations from the outer array.  Non-array objects (e.g. PromptBindState
 * from `prompt()`) are passed through directly.  `undefined` returns `false`
 * without calling the inner hook.
 *
@@ -266,7 +249,7 @@ function adaptShouldDeferCompletion(innerCheck, parser) {
 				if (!result && shouldRetryFalseResult) return innerCheck(normalizeDelegatedAnnotationState(innerState), exec);
 				return result;
 			} catch (error) {
-				if (!hasCarrier) throw error;
+				if (!shouldRetryOptionalLikeCompatibilityError(error, innerState)) throw error;
 				return innerCheck(normalizeDelegatedAnnotationState(innerState), exec);
 			}
 		}
@@ -324,7 +307,7 @@ function optional(parser) {
 		for await (const s of suggestions) yield s;
 	}
 	const optionalParser = {
-		$mode: parser.$mode,
+		mode: parser.mode,
 		$valueType: [],
 		$stateType: [],
 		...parser[unmatchedNonCliDependencySourceStateMarker] === true ? { [unmatchedNonCliDependencySourceStateMarker]: true } : {},
@@ -355,13 +338,13 @@ function optional(parser) {
 			return extractOptionalLikePhase2Seed(parser, state, exec);
 		},
 		parse(context) {
-			return dispatchByMode(parser.$mode, () => parseOptionalStyleSync(context, syncParser), () => parseOptionalStyleAsync(context, parser));
+			return dispatchByMode(parser.mode, () => parseOptionalStyleSync(context, syncParser), () => parseOptionalStyleAsync(context, parser));
 		},
 		complete(state, exec) {
 			if (!Array.isArray(state)) {
 				const delegateToInner = (resolvedInnerState) => {
-					const innerResult = dispatchByMode(parser.$mode, () => completeOptionalLikeSync(syncParser, resolvedInnerState, exec), async () => await completeOptionalLikeAsync(parser, resolvedInnerState, exec));
-					return mapModeValue(parser.$mode, innerResult, (result) => result.success ? result : {
+					const innerResult = dispatchByMode(parser.mode, () => completeOptionalLikeSync(syncParser, resolvedInnerState, exec), async () => await completeOptionalLikeAsync(parser, resolvedInnerState, exec));
+					return mapModeValue(parser.mode, innerResult, (result) => result.success ? result : {
 						success: true,
 						value: void 0
 					});
@@ -373,7 +356,7 @@ function optional(parser) {
 				const sourceMetadata = parser.dependencyMetadata?.source;
 				if (sourceMetadata?.preservesSourceValue !== false && sourceMetadata?.getMissingSourceValue != null) {
 					const delegatedState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
-					return dispatchByMode(parser.$mode, () => completeOptionalLikeSync(syncParser, delegatedState, exec), async () => await completeOptionalLikeAsync(parser, delegatedState, exec));
+					return dispatchByMode(parser.mode, () => completeOptionalLikeSync(syncParser, delegatedState, exec), async () => await completeOptionalLikeAsync(parser, delegatedState, exec));
 				}
 				if (parser[unmatchedNonCliDependencySourceStateMarker] === true && state != null && typeof state === "object") {
 					const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
@@ -385,10 +368,10 @@ function optional(parser) {
 				};
 			}
 			const innerElement = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
-			return dispatchByMode(parser.$mode, () => completeOptionalLikeSync(syncParser, innerElement, exec), async () => await completeOptionalLikeAsync(parser, innerElement, exec));
+			return dispatchByMode(parser.mode, () => completeOptionalLikeSync(syncParser, innerElement, exec), async () => await completeOptionalLikeAsync(parser, innerElement, exec));
 		},
 		suggest(context, prefix) {
-			return dispatchIterableByMode(parser.$mode, () => suggestSync(context, prefix), () => suggestAsync(context, prefix));
+			return dispatchIterableByMode(parser.mode, () => suggestSync(context, prefix), () => suggestAsync(context, prefix));
 		},
 		getDocFragments(state, defaultValue) {
 			const innerState = state.kind === "unavailable" ? { kind: "unavailable" } : state.state === void 0 ? { kind: "unavailable" } : {
@@ -413,7 +396,7 @@ function optional(parser) {
 		const innerValidate = parser.validateValue.bind(parser);
 		Object.defineProperty(optionalParser, "validateValue", {
 			value(v) {
-				if (v === void 0) return wrapForMode(parser.$mode, {
+				if (v === void 0) return wrapForMode(parser.mode, {
 					success: true,
 					value: v
 				});
@@ -493,7 +476,7 @@ function withDefault(parser, defaultValue, options) {
 		for await (const s of suggestions) yield s;
 	}
 	const withDefaultParser = {
-		$mode: parser.$mode,
+		mode: parser.mode,
 		$valueType: [],
 		$stateType: [],
 		...parser[unmatchedNonCliDependencySourceStateMarker] === true ? { [unmatchedNonCliDependencySourceStateMarker]: true } : {},
@@ -523,7 +506,7 @@ function withDefault(parser, defaultValue, options) {
 			return extractOptionalLikePhase2Seed(parser, state, exec);
 		},
 		parse(context) {
-			return dispatchByMode(parser.$mode, () => parseOptionalStyleSync(context, syncParser), () => parseOptionalStyleAsync(context, parser));
+			return dispatchByMode(parser.mode, () => parseOptionalStyleSync(context, syncParser), () => parseOptionalStyleAsync(context, parser));
 		},
 		complete(state, exec) {
 			function evaluateDefault() {
@@ -536,12 +519,12 @@ function withDefault(parser, defaultValue, options) {
 			if (!Array.isArray(state)) {
 				if (typeof parser.shouldDeferCompletion === "function" && state != null && typeof state === "object") {
 					const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
-					const innerResult = dispatchByMode(parser.$mode, () => completeOptionalLikeSync(syncParser, innerState, exec), async () => await completeOptionalLikeAsync(parser, innerState, exec));
+					const innerResult = dispatchByMode(parser.mode, () => completeOptionalLikeSync(syncParser, innerState, exec), async () => await completeOptionalLikeAsync(parser, innerState, exec));
 					return innerResult;
 				}
 				if (parser[unmatchedNonCliDependencySourceStateMarker] === true && state != null && typeof state === "object") {
 					const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
-					const innerResult = dispatchByMode(parser.$mode, () => completeOptionalLikeSync(syncParser, innerState, exec), async () => await completeOptionalLikeAsync(parser, innerState, exec));
+					const innerResult = dispatchByMode(parser.mode, () => completeOptionalLikeSync(syncParser, innerState, exec), async () => await completeOptionalLikeAsync(parser, innerState, exec));
 					const handleInnerResult = (result) => {
 						if (result.success && result.value !== void 0) return result;
 						try {
@@ -556,7 +539,7 @@ function withDefault(parser, defaultValue, options) {
 							};
 						}
 					};
-					return mapModeValue(parser.$mode, innerResult, handleInnerResult);
+					return mapModeValue(parser.mode, innerResult, handleInnerResult);
 				}
 				try {
 					const value = evaluateDefault();
@@ -572,10 +555,10 @@ function withDefault(parser, defaultValue, options) {
 				}
 			}
 			const innerElement = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
-			return dispatchByMode(parser.$mode, () => completeOptionalLikeSync(syncParser, innerElement, exec), async () => await completeOptionalLikeAsync(parser, innerElement, exec));
+			return dispatchByMode(parser.mode, () => completeOptionalLikeSync(syncParser, innerElement, exec), async () => await completeOptionalLikeAsync(parser, innerElement, exec));
 		},
 		suggest(context, prefix) {
-			return dispatchIterableByMode(parser.$mode, () => suggestSync(context, prefix), () => suggestAsync(context, prefix));
+			return dispatchIterableByMode(parser.mode, () => suggestSync(context, prefix), () => suggestAsync(context, prefix));
 		},
 		getDocFragments(state, upperDefaultValue) {
 			const innerState = state.kind === "unavailable" ? { kind: "unavailable" } : state.state === void 0 ? { kind: "unavailable" } : {
@@ -737,7 +720,7 @@ function withDefault(parser, defaultValue, options) {
 */
 function map(parser, transform) {
 	const complete = (state, exec) => {
-		return mapModeValue(parser.$mode, parser.complete(state, exec), (result) => {
+		return mapModeValue(parser.mode, parser.complete(state, exec), (result) => {
 			if (!result.success) return result;
 			if (result.deferred) try {
 				return {
@@ -763,7 +746,7 @@ function map(parser, transform) {
 		$valueType: [],
 		complete,
 		[extractPhase2SeedKey](state, exec) {
-			return mapModeValue(parser.$mode, completeOrExtractPhase2Seed(parser, state, exec), (seed) => {
+			return mapModeValue(parser.mode, completeOrExtractPhase2Seed(parser, state, exec), (seed) => {
 				if (seed == null) return null;
 				if (seed.deferred) try {
 					return {
@@ -1104,7 +1087,7 @@ function multiple(parser, options = {}) {
 		};
 	};
 	const resultParser = {
-		$mode: parser.$mode,
+		mode: parser.mode,
 		$valueType: [],
 		$stateType: [],
 		priority: parser.priority,
@@ -1125,10 +1108,10 @@ function multiple(parser, options = {}) {
 			}, ...innerNodes] : innerNodes;
 		},
 		parse(context) {
-			return dispatchByMode(parser.$mode, () => parseSync(context), () => parseAsync(context));
+			return dispatchByMode(parser.mode, () => parseSync(context), () => parseAsync(context));
 		},
 		complete(state, exec) {
-			return dispatchByMode(parser.$mode, () => {
+			return dispatchByMode(parser.mode, () => {
 				const result = [];
 				const deferredIndices = /* @__PURE__ */ new Map();
 				let hasDeferred = false;
@@ -1167,7 +1150,7 @@ function multiple(parser, options = {}) {
 			});
 		},
 		[extractPhase2SeedKey](state, exec) {
-			return dispatchByMode(parser.$mode, () => {
+			return dispatchByMode(parser.mode, () => {
 				const values = [];
 				const deferredIndices = /* @__PURE__ */ new Map();
 				let hasDeferred = false;
@@ -1217,7 +1200,7 @@ function multiple(parser, options = {}) {
 			const currentItemState = context.state.at(-1);
 			const canExtendCurrent = currentItemState != null && !isTerminalMultipleItemState(currentItemState);
 			const canOpenNew = context.state.length < max;
-			if (!canExtendCurrent && !canOpenNew) return dispatchIterableByMode(parser.$mode, function* () {}, async function* () {});
+			if (!canExtendCurrent && !canOpenNew) return dispatchIterableByMode(parser.mode, function* () {}, async function* () {});
 			const itemIndex = canExtendCurrent ? context.state.length - 1 : context.state.length;
 			const suggestInitialState = canExtendCurrent ? currentItemState : inheritAnnotations(context.state, parser.initialState);
 			const suggestFallbackState = unwrapInjectedWrapper(suggestInitialState);
@@ -1260,7 +1243,7 @@ function multiple(parser, options = {}) {
 					description
 				]);
 			};
-			return dispatchIterableByMode(parser.$mode, function* () {
+			return dispatchIterableByMode(parser.mode, function* () {
 				const selectedValues = collectSelectedValuesSync();
 				const emitted = /* @__PURE__ */ new Set();
 				const yieldUnique = function* (suggestions) {
@@ -1393,15 +1376,15 @@ function multiple(parser, options = {}) {
 			value(values) {
 				if (!Array.isArray(values)) {
 					const actualType = values === null ? "null" : typeof values;
-					return wrapForMode(parser.$mode, {
+					return wrapForMode(parser.mode, {
 						success: false,
 						error: message`Expected an array of values, but received ${actualType}.`
 					});
 				}
 				const arity = validateArity(values);
-				if (!arity.success) return wrapForMode(parser.$mode, arity);
-				if (innerValidate == null) return wrapForMode(parser.$mode, arity);
-				return dispatchByMode(parser.$mode, () => {
+				if (!arity.success) return wrapForMode(parser.mode, arity);
+				if (innerValidate == null) return wrapForMode(parser.mode, arity);
+				return dispatchByMode(parser.mode, () => {
 					let changed = false;
 					const normalized = [];
 					for (const v of values) {
@@ -1519,7 +1502,7 @@ function nonEmpty(parser) {
 		return processNonEmptyResult(result);
 	};
 	const nonEmptyParser = {
-		$mode: parser.$mode,
+		mode: parser.mode,
 		$valueType: parser.$valueType,
 		$stateType: parser.$stateType,
 		priority: parser.priority,
@@ -1536,7 +1519,7 @@ function nonEmpty(parser) {
 			}] : []);
 		},
 		parse(context) {
-			return dispatchByMode(parser.$mode, () => parseSync(context), () => parseAsync(context));
+			return dispatchByMode(parser.mode, () => parseSync(context), () => parseAsync(context));
 		},
 		complete(state, exec) {
 			return parser.complete(state, exec);