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

package/dist/modifiers.cjs

@@ -1,47 +1,13 @@
-const require_annotations = require('./annotations.cjs');
+const require_annotations = require('./internal/annotations.cjs');
 const require_message = require('./message.cjs');
-const require_mode_dispatch = require('./mode-dispatch.cjs');
-const require_dependency_metadata = require('./dependency-metadata.cjs');
-const require_phase2_seed = require('./phase2-seed.cjs');
-const require_parser = require('./parser.cjs');
+const require_mode_dispatch = require('./internal/mode-dispatch.cjs');
+const require_parser = require('./internal/parser.cjs');
 const require_annotation_state = require('./annotation-state.cjs');
+const require_execution_context = require('./execution-context.cjs');
+const require_phase2_seed = require('./phase2-seed.cjs');
+const require_dependency_metadata = require('./dependency-metadata.cjs');
 
 //#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: require_annotation_state.normalizeNestedDelegatedAnnotationState(result.value)
 	} : result;
 }
+function shouldRetryOptionalLikeCompatibilityError(error, state) {
+	return error instanceof TypeError && state != null && typeof state === "object" && require_annotations.isInjectedAnnotationWrapper(state);
+}
 function completeOptionalLikeSync(parser, state, exec) {
 	const hasCarrier = require_annotation_state.hasDelegatedAnnotationCarrier(state);
-	const shouldRetryFalseResult = require_annotation_state.isAnnotationWrappedInitialState(state);
-	const run = (candidate) => normalizeOptionalLikeCompleteResult(parser.complete(candidate, exec));
+	const shouldRetryFalseResult = hasCarrier && require_annotation_state.isAnnotationWrappedInitialState(state);
+	const run = (candidate, shouldNormalize) => normalizeOptionalLikeCompleteResult(parser.complete(candidate, exec), shouldNormalize);
 	try {
-		const result = run(state);
-		if (!result.success && shouldRetryFalseResult) return run(require_annotation_state.normalizeDelegatedAnnotationState(state));
+		const result = run(state, hasCarrier);
+		if (!result.success && shouldRetryFalseResult) return run(require_annotation_state.normalizeDelegatedAnnotationState(state), false);
 		return result;
 	} catch (error) {
-		if (!hasCarrier) throw error;
-		return run(require_annotation_state.normalizeDelegatedAnnotationState(state));
+		if (!shouldRetryOptionalLikeCompatibilityError(error, state)) throw error;
+		return run(require_annotation_state.normalizeDelegatedAnnotationState(state), false);
 	}
 }
 async function completeOptionalLikeAsync(parser, state, exec) {
 	const hasCarrier = require_annotation_state.hasDelegatedAnnotationCarrier(state);
-	const shouldRetryFalseResult = require_annotation_state.isAnnotationWrappedInitialState(state);
-	const run = async (candidate) => normalizeOptionalLikeCompleteResult(await parser.complete(candidate, exec));
+	const shouldRetryFalseResult = hasCarrier && require_annotation_state.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(require_annotation_state.normalizeDelegatedAnnotationState(state));
+		const result = await run(state, hasCarrier);
+		if (!result.success && shouldRetryFalseResult) return await run(require_annotation_state.normalizeDelegatedAnnotationState(state), false);
 		return result;
 	} catch (error) {
-		if (!hasCarrier) throw error;
-		return await run(require_annotation_state.normalizeDelegatedAnnotationState(state));
+		if (!shouldRetryOptionalLikeCompatibilityError(error, state)) throw error;
+		return await run(require_annotation_state.normalizeDelegatedAnnotationState(state), false);
 	}
 }
-function normalizeOptionalLikePhase2Seed(seed) {
-	return seed == null ? null : {
+function normalizeOptionalLikePhase2Seed(seed, shouldNormalize) {
+	return seed == null ? null : shouldNormalize ? {
 		...seed,
 		value: require_annotation_state.normalizeNestedDelegatedAnnotationState(seed.value)
-	};
+	} : seed;
 }
 function extractOptionalLikePhase2Seed(parser, state, exec) {
-	if (!Array.isArray(state) && !(state != null && typeof state === "object")) return require_mode_dispatch.wrapForMode(parser.$mode, null);
+	if (!Array.isArray(state) && !(state != null && typeof state === "object")) return require_mode_dispatch.wrapForMode(parser.mode, null);
 	const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
 	const hasCarrier = require_annotation_state.hasDelegatedAnnotationCarrier(innerState);
-	return require_mode_dispatch.dispatchByMode(parser.$mode, () => {
+	const shouldRetryFalseResult = hasCarrier && require_annotation_state.isAnnotationWrappedInitialState(innerState);
+	return require_mode_dispatch.dispatchByMode(parser.mode, () => {
 		try {
 			const result = parser.complete(innerState, exec);
-			if (result.success) return normalizeOptionalLikePhase2Seed(require_phase2_seed.phase2SeedFromValueResult(result));
+			if (result.success) return normalizeOptionalLikePhase2Seed(require_phase2_seed.phase2SeedFromValueResult(result), hasCarrier);
+			if (shouldRetryFalseResult) {
+				const fallbackState = require_annotation_state.normalizeDelegatedAnnotationState(innerState);
+				const fallbackResult = parser.complete(fallbackState, exec);
+				if (fallbackResult.success) return normalizeOptionalLikePhase2Seed(require_phase2_seed.phase2SeedFromValueResult(fallbackResult), false);
+			}
 			const seed = require_phase2_seed.extractPhase2Seed(parser, innerState, exec);
 			if (seed == null && hasCarrier) {
 				const fallbackState = require_annotation_state.normalizeDelegatedAnnotationState(innerState);
-				return normalizeOptionalLikePhase2Seed(require_phase2_seed.extractPhase2Seed(parser, fallbackState, exec));
+				return normalizeOptionalLikePhase2Seed(require_phase2_seed.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 = require_annotation_state.normalizeDelegatedAnnotationState(innerState);
 			const result = parser.complete(fallbackState, exec);
-			if (result.success) return normalizeOptionalLikePhase2Seed(require_phase2_seed.phase2SeedFromValueResult(result));
-			return normalizeOptionalLikePhase2Seed(require_phase2_seed.extractPhase2Seed(parser, fallbackState, exec));
+			if (result.success) return normalizeOptionalLikePhase2Seed(require_phase2_seed.phase2SeedFromValueResult(result), false);
+			return normalizeOptionalLikePhase2Seed(require_phase2_seed.extractPhase2Seed(parser, fallbackState, exec), false);
 		}
 	}, async () => {
 		try {
 			const result = await parser.complete(innerState, exec);
-			if (result.success) return normalizeOptionalLikePhase2Seed(require_phase2_seed.phase2SeedFromValueResult(result));
+			if (result.success) return normalizeOptionalLikePhase2Seed(require_phase2_seed.phase2SeedFromValueResult(result), hasCarrier);
+			if (shouldRetryFalseResult) {
+				const fallbackState = require_annotation_state.normalizeDelegatedAnnotationState(innerState);
+				const fallbackResult = await parser.complete(fallbackState, exec);
+				if (fallbackResult.success) return normalizeOptionalLikePhase2Seed(require_phase2_seed.phase2SeedFromValueResult(fallbackResult), false);
+			}
 			const seed = await require_phase2_seed.extractPhase2Seed(parser, innerState, exec);
 			if (seed == null && hasCarrier) {
 				const fallbackState = require_annotation_state.normalizeDelegatedAnnotationState(innerState);
-				return normalizeOptionalLikePhase2Seed(await require_phase2_seed.extractPhase2Seed(parser, fallbackState, exec));
+				return normalizeOptionalLikePhase2Seed(await require_phase2_seed.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 = require_annotation_state.normalizeDelegatedAnnotationState(innerState);
 			const result = await parser.complete(fallbackState, exec);
-			if (result.success) return normalizeOptionalLikePhase2Seed(require_phase2_seed.phase2SeedFromValueResult(result));
-			return normalizeOptionalLikePhase2Seed(await require_phase2_seed.extractPhase2Seed(parser, fallbackState, exec));
+			if (result.success) return normalizeOptionalLikePhase2Seed(require_phase2_seed.phase2SeedFromValueResult(result), false);
+			return normalizeOptionalLikePhase2Seed(await require_phase2_seed.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 (require_annotations.getAnnotations(outerState) != null && innerState != null && typeof innerState === "object") return require_annotations.inheritAnnotations(outerState, innerState);
+		if (require_annotations.getAnnotations(outerState) != null && innerState != null && typeof innerState === "object") return require_annotation_state.getDelegatedAnnotationState(outerState, innerState);
 		return innerState;
 	}
 	const initial = parser.initialState;
 	if (initial != null && typeof initial !== "object") return initial;
-	return require_annotations.inheritAnnotations(outerState, initial);
+	return initial != null && typeof initial === "object" ? require_annotation_state.getDelegatedAnnotationState(outerState, initial) : require_annotations.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 && require_annotation_state.normalizeDelegatedAnnotationState(previousState) !== require_annotation_state.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(require_annotation_state.normalizeDelegatedAnnotationState(innerState), exec);
 				return result;
 			} catch (error) {
-				if (!hasCarrier) throw error;
+				if (!shouldRetryOptionalLikeCompatibilityError(error, innerState)) throw error;
 				return innerCheck(require_annotation_state.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[require_parser.unmatchedNonCliDependencySourceStateMarker] === true ? { [require_parser.unmatchedNonCliDependencySourceStateMarker]: true } : {},
@@ -355,13 +338,13 @@ function optional(parser) {
 			return extractOptionalLikePhase2Seed(parser, state, exec);
 		},
 		parse(context) {
-			return require_mode_dispatch.dispatchByMode(parser.$mode, () => parseOptionalStyleSync(context, syncParser), () => parseOptionalStyleAsync(context, parser));
+			return require_mode_dispatch.dispatchByMode(parser.mode, () => parseOptionalStyleSync(context, syncParser), () => parseOptionalStyleAsync(context, parser));
 		},
 		complete(state, exec) {
 			if (!Array.isArray(state)) {
 				const delegateToInner = (resolvedInnerState) => {
-					const innerResult = require_mode_dispatch.dispatchByMode(parser.$mode, () => completeOptionalLikeSync(syncParser, resolvedInnerState, exec), async () => await completeOptionalLikeAsync(parser, resolvedInnerState, exec));
-					return require_mode_dispatch.mapModeValue(parser.$mode, innerResult, (result) => result.success ? result : {
+					const innerResult = require_mode_dispatch.dispatchByMode(parser.mode, () => completeOptionalLikeSync(syncParser, resolvedInnerState, exec), async () => await completeOptionalLikeAsync(parser, resolvedInnerState, exec));
+					return require_mode_dispatch.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 require_mode_dispatch.dispatchByMode(parser.$mode, () => completeOptionalLikeSync(syncParser, delegatedState, exec), async () => await completeOptionalLikeAsync(parser, delegatedState, exec));
+					return require_mode_dispatch.dispatchByMode(parser.mode, () => completeOptionalLikeSync(syncParser, delegatedState, exec), async () => await completeOptionalLikeAsync(parser, delegatedState, exec));
 				}
 				if (parser[require_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 require_mode_dispatch.dispatchByMode(parser.$mode, () => completeOptionalLikeSync(syncParser, innerElement, exec), async () => await completeOptionalLikeAsync(parser, innerElement, exec));
+			return require_mode_dispatch.dispatchByMode(parser.mode, () => completeOptionalLikeSync(syncParser, innerElement, exec), async () => await completeOptionalLikeAsync(parser, innerElement, exec));
 		},
 		suggest(context, prefix) {
-			return require_mode_dispatch.dispatchIterableByMode(parser.$mode, () => suggestSync(context, prefix), () => suggestAsync(context, prefix));
+			return require_mode_dispatch.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 require_mode_dispatch.wrapForMode(parser.$mode, {
+				if (v === void 0) return require_mode_dispatch.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[require_parser.unmatchedNonCliDependencySourceStateMarker] === true ? { [require_parser.unmatchedNonCliDependencySourceStateMarker]: true } : {},
@@ -523,7 +506,7 @@ function withDefault(parser, defaultValue, options) {
 			return extractOptionalLikePhase2Seed(parser, state, exec);
 		},
 		parse(context) {
-			return require_mode_dispatch.dispatchByMode(parser.$mode, () => parseOptionalStyleSync(context, syncParser), () => parseOptionalStyleAsync(context, parser));
+			return require_mode_dispatch.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 = require_mode_dispatch.dispatchByMode(parser.$mode, () => completeOptionalLikeSync(syncParser, innerState, exec), async () => await completeOptionalLikeAsync(parser, innerState, exec));
+					const innerResult = require_mode_dispatch.dispatchByMode(parser.mode, () => completeOptionalLikeSync(syncParser, innerState, exec), async () => await completeOptionalLikeAsync(parser, innerState, exec));
 					return innerResult;
 				}
 				if (parser[require_parser.unmatchedNonCliDependencySourceStateMarker] === true && state != null && typeof state === "object") {
 					const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
-					const innerResult = require_mode_dispatch.dispatchByMode(parser.$mode, () => completeOptionalLikeSync(syncParser, innerState, exec), async () => await completeOptionalLikeAsync(parser, innerState, exec));
+					const innerResult = require_mode_dispatch.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 require_mode_dispatch.mapModeValue(parser.$mode, innerResult, handleInnerResult);
+					return require_mode_dispatch.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 require_mode_dispatch.dispatchByMode(parser.$mode, () => completeOptionalLikeSync(syncParser, innerElement, exec), async () => await completeOptionalLikeAsync(parser, innerElement, exec));
+			return require_mode_dispatch.dispatchByMode(parser.mode, () => completeOptionalLikeSync(syncParser, innerElement, exec), async () => await completeOptionalLikeAsync(parser, innerElement, exec));
 		},
 		suggest(context, prefix) {
-			return require_mode_dispatch.dispatchIterableByMode(parser.$mode, () => suggestSync(context, prefix), () => suggestAsync(context, prefix));
+			return require_mode_dispatch.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 require_mode_dispatch.mapModeValue(parser.$mode, parser.complete(state, exec), (result) => {
+		return require_mode_dispatch.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,
 		[require_phase2_seed.extractPhase2SeedKey](state, exec) {
-			return require_mode_dispatch.mapModeValue(parser.$mode, require_phase2_seed.completeOrExtractPhase2Seed(parser, state, exec), (seed) => {
+			return require_mode_dispatch.mapModeValue(parser.mode, require_phase2_seed.completeOrExtractPhase2Seed(parser, state, exec), (seed) => {
 				if (seed == null) return null;
 				if (seed.deferred) try {
 					return {
@@ -955,13 +938,13 @@ function multiple(parser, options = {}) {
 		let added = !canExtendCurrent;
 		let itemIndex = canExtendCurrent ? context.state.length - 1 : context.state.length;
 		const currentItemStateWithAnnotations = canExtendCurrent ? currentItemState : require_annotations.inheritAnnotations(context.state, syncParser.initialState);
-		let result = parseSyncWithUnwrappedFallback(withChildContext(context, itemIndex, currentItemStateWithAnnotations));
+		let result = parseSyncWithUnwrappedFallback(require_execution_context.withChildContext(context, itemIndex, currentItemStateWithAnnotations));
 		if (!result.success) {
 			if (result.consumed !== 0) return result;
 			if (!added && canOpenFreshItem) {
 				const nextInitialState = require_annotations.inheritAnnotations(context.state, syncParser.initialState);
 				itemIndex = context.state.length;
-				result = parseSyncWithUnwrappedFallback(withChildContext(context, itemIndex, nextInitialState));
+				result = parseSyncWithUnwrappedFallback(require_execution_context.withChildContext(context, itemIndex, nextInitialState));
 				if (!result.success) {
 					if (min === 0 && context.buffer.length === 0 && result.consumed === 0) return {
 						success: true,
@@ -978,7 +961,7 @@ function multiple(parser, options = {}) {
 			};
 			else return result;
 		}
-		const mergedExec = mergeChildExec(context.exec, result.next.exec);
+		const mergedExec = require_execution_context.mergeChildExec(context.exec, result.next.exec);
 		if (added && result.consumed.length === 0 && result.next.optionsTerminated === context.optionsTerminated && isUnstartedMultipleItemState(result.next.state, currentItemStateWithAnnotations)) return {
 			success: true,
 			next: {
@@ -1035,13 +1018,13 @@ function multiple(parser, options = {}) {
 		let added = !canExtendCurrent;
 		let itemIndex = canExtendCurrent ? context.state.length - 1 : context.state.length;
 		const currentItemStateWithAnnotations = canExtendCurrent ? currentItemState : require_annotations.inheritAnnotations(context.state, parser.initialState);
-		let result = await parseAsyncWithUnwrappedFallback(withChildContext(context, itemIndex, currentItemStateWithAnnotations));
+		let result = await parseAsyncWithUnwrappedFallback(require_execution_context.withChildContext(context, itemIndex, currentItemStateWithAnnotations));
 		if (!result.success) {
 			if (result.consumed !== 0) return result;
 			if (!added && canOpenFreshItem) {
 				const nextInitialState = require_annotations.inheritAnnotations(context.state, parser.initialState);
 				itemIndex = context.state.length;
-				result = await parseAsyncWithUnwrappedFallback(withChildContext(context, itemIndex, nextInitialState));
+				result = await parseAsyncWithUnwrappedFallback(require_execution_context.withChildContext(context, itemIndex, nextInitialState));
 				if (!result.success) {
 					if (min === 0 && context.buffer.length === 0 && result.consumed === 0) return {
 						success: true,
@@ -1058,7 +1041,7 @@ function multiple(parser, options = {}) {
 			};
 			else return result;
 		}
-		const mergedExec = mergeChildExec(context.exec, result.next.exec);
+		const mergedExec = require_execution_context.mergeChildExec(context.exec, result.next.exec);
 		if (added && result.consumed.length === 0 && result.next.optionsTerminated === context.optionsTerminated && isUnstartedMultipleItemState(result.next.state, currentItemStateWithAnnotations)) return {
 			success: true,
 			next: {
@@ -1104,7 +1087,7 @@ function multiple(parser, options = {}) {
 		};
 	};
 	const resultParser = {
-		$mode: parser.$mode,
+		mode: parser.mode,
 		$valueType: [],
 		$stateType: [],
 		priority: parser.priority,
@@ -1125,15 +1108,15 @@ function multiple(parser, options = {}) {
 			}, ...innerNodes] : innerNodes;
 		},
 		parse(context) {
-			return require_mode_dispatch.dispatchByMode(parser.$mode, () => parseSync(context), () => parseAsync(context));
+			return require_mode_dispatch.dispatchByMode(parser.mode, () => parseSync(context), () => parseAsync(context));
 		},
 		complete(state, exec) {
-			return require_mode_dispatch.dispatchByMode(parser.$mode, () => {
+			return require_mode_dispatch.dispatchByMode(parser.mode, () => {
 				const result = [];
 				const deferredIndices = /* @__PURE__ */ new Map();
 				let hasDeferred = false;
 				for (let i = 0; i < state.length; i++) {
-					const valueResult = completeSyncWithUnwrappedFallback(state[i], withChildExecPath(exec, i));
+					const valueResult = completeSyncWithUnwrappedFallback(state[i], require_execution_context.withChildExecPath(exec, i));
 					if (valueResult.success) {
 						const unwrappedValue = unwrapInjectedWrapper(valueResult.value);
 						result.push(unwrappedValue);
@@ -1151,7 +1134,7 @@ function multiple(parser, options = {}) {
 				const deferredIndices = /* @__PURE__ */ new Map();
 				let hasDeferred = false;
 				for (let i = 0; i < state.length; i++) {
-					const valueResult = await completeAsyncWithUnwrappedFallback(state[i], withChildExecPath(exec, i));
+					const valueResult = await completeAsyncWithUnwrappedFallback(state[i], require_execution_context.withChildExecPath(exec, i));
 					if (valueResult.success) {
 						const unwrappedValue = unwrapInjectedWrapper(valueResult.value);
 						values.push(unwrappedValue);
@@ -1167,13 +1150,13 @@ function multiple(parser, options = {}) {
 			});
 		},
 		[require_phase2_seed.extractPhase2SeedKey](state, exec) {
-			return require_mode_dispatch.dispatchByMode(parser.$mode, () => {
+			return require_mode_dispatch.dispatchByMode(parser.mode, () => {
 				const values = [];
 				const deferredIndices = /* @__PURE__ */ new Map();
 				let hasDeferred = false;
 				let hasAnySeed = false;
 				for (let i = 0; i < state.length; i++) {
-					const seed = extractPhase2SeedSyncWithUnwrappedFallback(state[i], withChildExecPath(exec, i));
+					const seed = extractPhase2SeedSyncWithUnwrappedFallback(state[i], require_execution_context.withChildExecPath(exec, i));
 					if (seed == null) continue;
 					hasAnySeed = true;
 					values[i] = seed.value;
@@ -1195,7 +1178,7 @@ function multiple(parser, options = {}) {
 				let hasDeferred = false;
 				let hasAnySeed = false;
 				for (let i = 0; i < state.length; i++) {
-					const seed = await extractPhase2SeedAsyncWithUnwrappedFallback(state[i], withChildExecPath(exec, i));
+					const seed = await extractPhase2SeedAsyncWithUnwrappedFallback(state[i], require_execution_context.withChildExecPath(exec, i));
 					if (seed == null) continue;
 					hasAnySeed = true;
 					values[i] = seed.value;
@@ -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 require_mode_dispatch.dispatchIterableByMode(parser.$mode, function* () {}, async function* () {});
+			if (!canExtendCurrent && !canOpenNew) return require_mode_dispatch.dispatchIterableByMode(parser.mode, function* () {}, async function* () {});
 			const itemIndex = canExtendCurrent ? context.state.length - 1 : context.state.length;
 			const suggestInitialState = canExtendCurrent ? currentItemState : require_annotations.inheritAnnotations(context.state, parser.initialState);
 			const suggestFallbackState = unwrapInjectedWrapper(suggestInitialState);
@@ -1225,7 +1208,7 @@ function multiple(parser, options = {}) {
 			const collectSelectedValuesSync = () => {
 				const selectedValues = /* @__PURE__ */ new Set();
 				for (let i = 0; i < context.state.length; i++) {
-					const childContext = withChildContext(context, i, context.state[i]);
+					const childContext = require_execution_context.withChildContext(context, i, context.state[i]);
 					const completed = completeSyncWithUnwrappedFallback(childContext.state, childContext.exec);
 					if (completed.success) selectedValues.add(String(unwrapInjectedWrapper(completed.value)));
 				}
@@ -1234,7 +1217,7 @@ function multiple(parser, options = {}) {
 			const collectSelectedValuesAsync = async () => {
 				const selectedValues = /* @__PURE__ */ new Set();
 				for (let i = 0; i < context.state.length; i++) {
-					const childContext = withChildContext(context, i, context.state[i]);
+					const childContext = require_execution_context.withChildContext(context, i, context.state[i]);
 					const completed = await completeAsyncWithUnwrappedFallback(childContext.state, childContext.exec);
 					if (completed.success) selectedValues.add(String(unwrapInjectedWrapper(completed.value)));
 				}
@@ -1260,7 +1243,7 @@ function multiple(parser, options = {}) {
 					description
 				]);
 			};
-			return require_mode_dispatch.dispatchIterableByMode(parser.$mode, function* () {
+			return require_mode_dispatch.dispatchIterableByMode(parser.mode, function* () {
 				const selectedValues = collectSelectedValuesSync();
 				const emitted = /* @__PURE__ */ new Set();
 				const yieldUnique = function* (suggestions) {
@@ -1274,12 +1257,12 @@ function multiple(parser, options = {}) {
 				};
 				let shouldTryFallback = false;
 				try {
-					yield* yieldUnique(syncParser.suggest(withChildContext(context, itemIndex, suggestInitialState), prefix));
+					yield* yieldUnique(syncParser.suggest(require_execution_context.withChildContext(context, itemIndex, suggestInitialState), prefix));
 				} catch (error) {
 					if (!hasSuggestFallbackState) throw error;
 					shouldTryFallback = true;
 				}
-				if (shouldTryFallback) yield* yieldUnique(syncParser.suggest(withChildContext(context, itemIndex, suggestFallbackState), prefix));
+				if (shouldTryFallback) yield* yieldUnique(syncParser.suggest(require_execution_context.withChildContext(context, itemIndex, suggestFallbackState), prefix));
 			}, async function* () {
 				const selectedValues = await collectSelectedValuesAsync();
 				const emitted = /* @__PURE__ */ new Set();
@@ -1294,12 +1277,12 @@ function multiple(parser, options = {}) {
 				};
 				let shouldTryFallback = false;
 				try {
-					yield* yieldUnique(parser.suggest(withChildContext(context, itemIndex, suggestInitialState), prefix));
+					yield* yieldUnique(parser.suggest(require_execution_context.withChildContext(context, itemIndex, suggestInitialState), prefix));
 				} catch (error) {
 					if (!hasSuggestFallbackState) throw error;
 					shouldTryFallback = true;
 				}
-				if (shouldTryFallback) yield* yieldUnique(parser.suggest(withChildContext(context, itemIndex, suggestFallbackState), prefix));
+				if (shouldTryFallback) yield* yieldUnique(parser.suggest(require_execution_context.withChildContext(context, itemIndex, suggestFallbackState), prefix));
 			});
 		},
 		getDocFragments(state, defaultValue) {
@@ -1393,15 +1376,15 @@ function multiple(parser, options = {}) {
 			value(values) {
 				if (!Array.isArray(values)) {
 					const actualType = values === null ? "null" : typeof values;
-					return require_mode_dispatch.wrapForMode(parser.$mode, {
+					return require_mode_dispatch.wrapForMode(parser.mode, {
 						success: false,
 						error: require_message.message`Expected an array of values, but received ${actualType}.`
 					});
 				}
 				const arity = validateArity(values);
-				if (!arity.success) return require_mode_dispatch.wrapForMode(parser.$mode, arity);
-				if (innerValidate == null) return require_mode_dispatch.wrapForMode(parser.$mode, arity);
-				return require_mode_dispatch.dispatchByMode(parser.$mode, () => {
+				if (!arity.success) return require_mode_dispatch.wrapForMode(parser.mode, arity);
+				if (innerValidate == null) return require_mode_dispatch.wrapForMode(parser.mode, arity);
+				return require_mode_dispatch.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 require_mode_dispatch.dispatchByMode(parser.$mode, () => parseSync(context), () => parseAsync(context));
+			return require_mode_dispatch.dispatchByMode(parser.mode, () => parseSync(context), () => parseAsync(context));
 		},
 		complete(state, exec) {
 			return parser.complete(state, exec);

package/dist/modifiers.d.cts

@@ -1,5 +1,5 @@
 import { Message } from "./message.cjs";
-import { Mode, Parser } from "./parser.cjs";
+import { Mode, Parser } from "./internal/parser.cjs";
 
 //#region src/modifiers.d.ts
 

package/dist/modifiers.d.ts

@@ -1,5 +1,5 @@
 import { Message } from "./message.js";
-import { Mode, Parser } from "./parser.js";
+import { Mode, Parser } from "./internal/parser.js";
 
 //#region src/modifiers.d.ts