@optique/core 1.0.0-dev.1574 → 1.0.0-dev.1583

package/dist/modifiers.cjs

@@ -75,12 +75,12 @@ function processOptionalStyleResult(result, innerState, context) {
 * @internal
 */
 function adaptShouldDeferCompletion(innerCheck) {
-	return (state) => {
+	return (state, exec) => {
 		if (Array.isArray(state)) {
 			const inner = require_annotations.getAnnotations(state) != null && state[0] != null && typeof state[0] === "object" ? require_annotations.inheritAnnotations(state, state[0]) : state[0];
-			return innerCheck(inner);
+			return innerCheck(inner, exec);
 		}
-		if (state != null && typeof state === "object") return innerCheck(state);
+		if (state != null && typeof state === "object") return innerCheck(state, exec);
 		return false;
 	};
 }
@@ -136,12 +136,12 @@ function optional(parser) {
 		parse(context) {
 			return require_mode_dispatch.dispatchByMode(parser.$mode, () => parseOptionalStyleSync(context, syncParser), () => parseOptionalStyleAsync(context, parser));
 		},
-		complete(state) {
+		complete(state, exec) {
 			if (!Array.isArray(state)) {
-				if (innerHasWrappedDependency && wrappedPendingState) return require_mode_dispatch.dispatchByMode(parser.$mode, () => syncParser.complete([wrappedPendingState]), () => parser.complete([wrappedPendingState]));
+				if (innerHasWrappedDependency && wrappedPendingState) return require_mode_dispatch.dispatchByMode(parser.$mode, () => syncParser.complete([wrappedPendingState], exec), () => parser.complete([wrappedPendingState], exec));
 				if (typeof parser.shouldDeferCompletion === "function" && state != null && typeof state === "object") {
 					const innerComplete = () => {
-						const innerResult = require_mode_dispatch.dispatchByMode(parser.$mode, () => syncParser.complete(state), () => parser.complete(state));
+						const innerResult = require_mode_dispatch.dispatchByMode(parser.$mode, () => syncParser.complete(state, exec), () => parser.complete(state, exec));
 						return require_mode_dispatch.mapModeValue(parser.$mode, innerResult, (result) => result.success ? result : {
 							success: true,
 							value: void 0
@@ -155,14 +155,14 @@ function optional(parser) {
 				};
 			}
 			if (Array.isArray(state) && state.length === 1 && require_dependency.isPendingDependencySourceState(state[0])) {
-				if (innerHasWrappedDependency) return require_mode_dispatch.dispatchByMode(parser.$mode, () => syncParser.complete(state), () => parser.complete(state));
+				if (innerHasWrappedDependency) return require_mode_dispatch.dispatchByMode(parser.$mode, () => syncParser.complete(state, exec), () => parser.complete(state, exec));
 				return {
 					success: true,
 					value: void 0
 				};
 			}
 			const innerElement = require_annotations.getAnnotations(state) != null && state[0] != null && typeof state[0] === "object" ? require_annotations.inheritAnnotations(state, state[0]) : state[0];
-			return require_mode_dispatch.dispatchByMode(parser.$mode, () => syncParser.complete(innerElement), () => parser.complete(innerElement));
+			return require_mode_dispatch.dispatchByMode(parser.$mode, () => syncParser.complete(innerElement, exec), () => parser.complete(innerElement, exec));
 		},
 		suggest(context, prefix) {
 			return require_mode_dispatch.dispatchIterableByMode(parser.$mode, () => suggestSync(context, prefix), () => suggestAsync(context, prefix));
@@ -268,7 +268,7 @@ function withDefault(parser, defaultValue, options) {
 		parse(context) {
 			return require_mode_dispatch.dispatchByMode(parser.$mode, () => parseOptionalStyleSync(context, syncParser), () => parseOptionalStyleAsync(context, parser));
 		},
-		complete(state) {
+		complete(state, exec) {
 			function evaluateDefault() {
 				const raw = typeof defaultValue === "function" ? defaultValue() : defaultValue;
 				if (typeof parser.normalizeValue === "function") try {
@@ -278,7 +278,7 @@ function withDefault(parser, defaultValue, options) {
 			}
 			if (!Array.isArray(state)) {
 				if (require_dependency.transformsDependencyValue(parser)) {
-					const innerResult = require_mode_dispatch.dispatchByMode(parser.$mode, () => syncParser.complete(void 0), () => parser.complete(void 0));
+					const innerResult = require_mode_dispatch.dispatchByMode(parser.$mode, () => syncParser.complete(void 0, exec), () => parser.complete(void 0, exec));
 					const handleInnerResult = (res) => {
 						if (require_dependency.isDependencySourceState(res)) try {
 							const value = evaluateDefault();
@@ -321,7 +321,7 @@ function withDefault(parser, defaultValue, options) {
 					};
 				}
 				if (typeof parser.shouldDeferCompletion === "function" && state != null && typeof state === "object") {
-					const innerResult = require_mode_dispatch.dispatchByMode(parser.$mode, () => syncParser.complete(state), () => parser.complete(state));
+					const innerResult = require_mode_dispatch.dispatchByMode(parser.$mode, () => syncParser.complete(state, exec), () => parser.complete(state, exec));
 					return innerResult;
 				}
 				try {
@@ -339,7 +339,7 @@ function withDefault(parser, defaultValue, options) {
 			}
 			if (require_dependency.isPendingDependencySourceState(state[0])) {
 				if (require_dependency.transformsDependencyValue(parser)) {
-					const innerResult = require_mode_dispatch.dispatchByMode(parser.$mode, () => syncParser.complete(state), () => parser.complete(state));
+					const innerResult = require_mode_dispatch.dispatchByMode(parser.$mode, () => syncParser.complete(state, exec), () => parser.complete(state, exec));
 					const handleInnerResult = (res) => {
 						if (require_dependency.isDependencySourceState(res)) try {
 							const value = evaluateDefault();
@@ -382,7 +382,7 @@ function withDefault(parser, defaultValue, options) {
 				}
 			}
 			const innerElement = require_annotations.getAnnotations(state) != null && state[0] != null && typeof state[0] === "object" ? require_annotations.inheritAnnotations(state, state[0]) : state[0];
-			return require_mode_dispatch.dispatchByMode(parser.$mode, () => syncParser.complete(innerElement), () => parser.complete(innerElement));
+			return require_mode_dispatch.dispatchByMode(parser.$mode, () => syncParser.complete(innerElement, exec), () => parser.complete(innerElement, exec));
 		},
 		suggest(context, prefix) {
 			return require_mode_dispatch.dispatchIterableByMode(parser.$mode, () => suggestSync(context, prefix), () => suggestAsync(context, prefix));
@@ -512,8 +512,8 @@ function withDefault(parser, defaultValue, options) {
 * ```
 */
 function map(parser, transform) {
-	const complete = (state) => {
-		return require_mode_dispatch.mapModeValue(parser.$mode, parser.complete(state), (result) => {
+	const complete = (state, exec) => {
+		return require_mode_dispatch.mapModeValue(parser.$mode, parser.complete(state, exec), (result) => {
 			if (!result.success) return result;
 			if (result.deferred) try {
 				return {
@@ -580,12 +580,12 @@ function multiple(parser, options = {}) {
 	const syncParser = parser;
 	const { min = 0, max = Infinity } = options;
 	const unwrapInjectedWrapper = require_annotations.unwrapInjectedAnnotationWrapper;
-	const completeSyncWithUnwrappedFallback = (state) => {
+	const completeSyncWithUnwrappedFallback = (state, exec) => {
 		try {
-			return syncParser.complete(state);
+			return syncParser.complete(state, exec);
 		} catch (error) {
 			if (!require_annotations.isInjectedAnnotationWrapper(state)) throw error;
-			return syncParser.complete(unwrapInjectedWrapper(state));
+			return syncParser.complete(unwrapInjectedWrapper(state), exec);
 		}
 	};
 	const parseSyncWithUnwrappedFallback = (context) => {
@@ -604,12 +604,12 @@ function multiple(parser, options = {}) {
 			});
 		}
 	};
-	const completeAsyncWithUnwrappedFallback = async (state) => {
+	const completeAsyncWithUnwrappedFallback = async (state, exec) => {
 		try {
-			return await parser.complete(state);
+			return await parser.complete(state, exec);
 		} catch (error) {
 			if (!require_annotations.isInjectedAnnotationWrapper(state)) throw error;
-			return await parser.complete(unwrapInjectedWrapper(state));
+			return await parser.complete(unwrapInjectedWrapper(state), exec);
 		}
 	};
 	const parseAsyncWithUnwrappedFallback = async (context) => {
@@ -698,13 +698,13 @@ function multiple(parser, options = {}) {
 		parse(context) {
 			return require_mode_dispatch.dispatchByMode(parser.$mode, () => parseSync(context), () => parseAsync(context));
 		},
-		complete(state) {
+		complete(state, exec) {
 			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]);
+					const valueResult = completeSyncWithUnwrappedFallback(state[i], exec);
 					if (valueResult.success) {
 						const unwrappedValue = unwrapInjectedWrapper(valueResult.value);
 						result.push(unwrappedValue);
@@ -718,7 +718,7 @@ function multiple(parser, options = {}) {
 				}
 				return validateMultipleResult(result, deferredIndices, hasDeferred);
 			}, async () => {
-				const results = await Promise.all(state.map((s) => completeAsyncWithUnwrappedFallback(s)));
+				const results = await Promise.all(state.map((s) => completeAsyncWithUnwrappedFallback(s, exec)));
 				const values = [];
 				const deferredIndices = /* @__PURE__ */ new Map();
 				let hasDeferred = false;
@@ -958,8 +958,8 @@ function nonEmpty(parser) {
 		parse(context) {
 			return require_mode_dispatch.dispatchByMode(parser.$mode, () => parseSync(context), () => parseAsync(context));
 		},
-		complete(state) {
-			return parser.complete(state);
+		complete(state, exec) {
+			return parser.complete(state, exec);
 		},
 		suggest(context, prefix) {
 			return parser.suggest(context, prefix);

package/dist/modifiers.js

@@ -75,12 +75,12 @@ function processOptionalStyleResult(result, innerState, context) {
 * @internal
 */
 function adaptShouldDeferCompletion(innerCheck) {
-	return (state) => {
+	return (state, exec) => {
 		if (Array.isArray(state)) {
 			const inner = getAnnotations(state) != null && state[0] != null && typeof state[0] === "object" ? inheritAnnotations(state, state[0]) : state[0];
-			return innerCheck(inner);
+			return innerCheck(inner, exec);
 		}
-		if (state != null && typeof state === "object") return innerCheck(state);
+		if (state != null && typeof state === "object") return innerCheck(state, exec);
 		return false;
 	};
 }
@@ -136,12 +136,12 @@ function optional(parser) {
 		parse(context) {
 			return dispatchByMode(parser.$mode, () => parseOptionalStyleSync(context, syncParser), () => parseOptionalStyleAsync(context, parser));
 		},
-		complete(state) {
+		complete(state, exec) {
 			if (!Array.isArray(state)) {
-				if (innerHasWrappedDependency && wrappedPendingState) return dispatchByMode(parser.$mode, () => syncParser.complete([wrappedPendingState]), () => parser.complete([wrappedPendingState]));
+				if (innerHasWrappedDependency && wrappedPendingState) return dispatchByMode(parser.$mode, () => syncParser.complete([wrappedPendingState], exec), () => parser.complete([wrappedPendingState], exec));
 				if (typeof parser.shouldDeferCompletion === "function" && state != null && typeof state === "object") {
 					const innerComplete = () => {
-						const innerResult = dispatchByMode(parser.$mode, () => syncParser.complete(state), () => parser.complete(state));
+						const innerResult = dispatchByMode(parser.$mode, () => syncParser.complete(state, exec), () => parser.complete(state, exec));
 						return mapModeValue(parser.$mode, innerResult, (result) => result.success ? result : {
 							success: true,
 							value: void 0
@@ -155,14 +155,14 @@ function optional(parser) {
 				};
 			}
 			if (Array.isArray(state) && state.length === 1 && isPendingDependencySourceState(state[0])) {
-				if (innerHasWrappedDependency) return dispatchByMode(parser.$mode, () => syncParser.complete(state), () => parser.complete(state));
+				if (innerHasWrappedDependency) return dispatchByMode(parser.$mode, () => syncParser.complete(state, exec), () => parser.complete(state, exec));
 				return {
 					success: true,
 					value: void 0
 				};
 			}
 			const innerElement = getAnnotations(state) != null && state[0] != null && typeof state[0] === "object" ? inheritAnnotations(state, state[0]) : state[0];
-			return dispatchByMode(parser.$mode, () => syncParser.complete(innerElement), () => parser.complete(innerElement));
+			return dispatchByMode(parser.$mode, () => syncParser.complete(innerElement, exec), () => parser.complete(innerElement, exec));
 		},
 		suggest(context, prefix) {
 			return dispatchIterableByMode(parser.$mode, () => suggestSync(context, prefix), () => suggestAsync(context, prefix));
@@ -268,7 +268,7 @@ function withDefault(parser, defaultValue, options) {
 		parse(context) {
 			return dispatchByMode(parser.$mode, () => parseOptionalStyleSync(context, syncParser), () => parseOptionalStyleAsync(context, parser));
 		},
-		complete(state) {
+		complete(state, exec) {
 			function evaluateDefault() {
 				const raw = typeof defaultValue === "function" ? defaultValue() : defaultValue;
 				if (typeof parser.normalizeValue === "function") try {
@@ -278,7 +278,7 @@ function withDefault(parser, defaultValue, options) {
 			}
 			if (!Array.isArray(state)) {
 				if (transformsDependencyValue(parser)) {
-					const innerResult = dispatchByMode(parser.$mode, () => syncParser.complete(void 0), () => parser.complete(void 0));
+					const innerResult = dispatchByMode(parser.$mode, () => syncParser.complete(void 0, exec), () => parser.complete(void 0, exec));
 					const handleInnerResult = (res) => {
 						if (isDependencySourceState(res)) try {
 							const value = evaluateDefault();
@@ -321,7 +321,7 @@ function withDefault(parser, defaultValue, options) {
 					};
 				}
 				if (typeof parser.shouldDeferCompletion === "function" && state != null && typeof state === "object") {
-					const innerResult = dispatchByMode(parser.$mode, () => syncParser.complete(state), () => parser.complete(state));
+					const innerResult = dispatchByMode(parser.$mode, () => syncParser.complete(state, exec), () => parser.complete(state, exec));
 					return innerResult;
 				}
 				try {
@@ -339,7 +339,7 @@ function withDefault(parser, defaultValue, options) {
 			}
 			if (isPendingDependencySourceState(state[0])) {
 				if (transformsDependencyValue(parser)) {
-					const innerResult = dispatchByMode(parser.$mode, () => syncParser.complete(state), () => parser.complete(state));
+					const innerResult = dispatchByMode(parser.$mode, () => syncParser.complete(state, exec), () => parser.complete(state, exec));
 					const handleInnerResult = (res) => {
 						if (isDependencySourceState(res)) try {
 							const value = evaluateDefault();
@@ -382,7 +382,7 @@ function withDefault(parser, defaultValue, options) {
 				}
 			}
 			const innerElement = getAnnotations(state) != null && state[0] != null && typeof state[0] === "object" ? inheritAnnotations(state, state[0]) : state[0];
-			return dispatchByMode(parser.$mode, () => syncParser.complete(innerElement), () => parser.complete(innerElement));
+			return dispatchByMode(parser.$mode, () => syncParser.complete(innerElement, exec), () => parser.complete(innerElement, exec));
 		},
 		suggest(context, prefix) {
 			return dispatchIterableByMode(parser.$mode, () => suggestSync(context, prefix), () => suggestAsync(context, prefix));
@@ -512,8 +512,8 @@ function withDefault(parser, defaultValue, options) {
 * ```
 */
 function map(parser, transform) {
-	const complete = (state) => {
-		return mapModeValue(parser.$mode, parser.complete(state), (result) => {
+	const complete = (state, exec) => {
+		return mapModeValue(parser.$mode, parser.complete(state, exec), (result) => {
 			if (!result.success) return result;
 			if (result.deferred) try {
 				return {
@@ -580,12 +580,12 @@ function multiple(parser, options = {}) {
 	const syncParser = parser;
 	const { min = 0, max = Infinity } = options;
 	const unwrapInjectedWrapper = unwrapInjectedAnnotationWrapper;
-	const completeSyncWithUnwrappedFallback = (state) => {
+	const completeSyncWithUnwrappedFallback = (state, exec) => {
 		try {
-			return syncParser.complete(state);
+			return syncParser.complete(state, exec);
 		} catch (error) {
 			if (!isInjectedAnnotationWrapper(state)) throw error;
-			return syncParser.complete(unwrapInjectedWrapper(state));
+			return syncParser.complete(unwrapInjectedWrapper(state), exec);
 		}
 	};
 	const parseSyncWithUnwrappedFallback = (context) => {
@@ -604,12 +604,12 @@ function multiple(parser, options = {}) {
 			});
 		}
 	};
-	const completeAsyncWithUnwrappedFallback = async (state) => {
+	const completeAsyncWithUnwrappedFallback = async (state, exec) => {
 		try {
-			return await parser.complete(state);
+			return await parser.complete(state, exec);
 		} catch (error) {
 			if (!isInjectedAnnotationWrapper(state)) throw error;
-			return await parser.complete(unwrapInjectedWrapper(state));
+			return await parser.complete(unwrapInjectedWrapper(state), exec);
 		}
 	};
 	const parseAsyncWithUnwrappedFallback = async (context) => {
@@ -698,13 +698,13 @@ function multiple(parser, options = {}) {
 		parse(context) {
 			return dispatchByMode(parser.$mode, () => parseSync(context), () => parseAsync(context));
 		},
-		complete(state) {
+		complete(state, exec) {
 			return 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]);
+					const valueResult = completeSyncWithUnwrappedFallback(state[i], exec);
 					if (valueResult.success) {
 						const unwrappedValue = unwrapInjectedWrapper(valueResult.value);
 						result.push(unwrappedValue);
@@ -718,7 +718,7 @@ function multiple(parser, options = {}) {
 				}
 				return validateMultipleResult(result, deferredIndices, hasDeferred);
 			}, async () => {
-				const results = await Promise.all(state.map((s) => completeAsyncWithUnwrappedFallback(s)));
+				const results = await Promise.all(state.map((s) => completeAsyncWithUnwrappedFallback(s, exec)));
 				const values = [];
 				const deferredIndices = /* @__PURE__ */ new Map();
 				let hasDeferred = false;
@@ -958,8 +958,8 @@ function nonEmpty(parser) {
 		parse(context) {
 			return dispatchByMode(parser.$mode, () => parseSync(context), () => parseAsync(context));
 		},
-		complete(state) {
-			return parser.complete(state);
+		complete(state, exec) {
+			return parser.complete(state, exec);
 		},
 		suggest(context, prefix) {
 			return parser.suggest(context, prefix);

package/dist/parser.cjs

@@ -8,6 +8,28 @@ const require_modifiers = require('./modifiers.cjs');
 const require_primitives = require('./primitives.cjs');
 
 //#region src/parser.ts
+/**
+* Creates a {@link ParserContext} from a {@link ParseFrame} and an
+* {@link ExecutionContext}.  The returned object provides both structured
+* access (`frame`, `exec`) and flat access (`buffer`, `state`, etc.)
+* for backward compatibility.
+*
+* @template TState The type of the state used during parsing.
+* @param frame Parser-local frame data.
+* @param exec Shared execution context.
+* @returns A {@link ParserContext} instance.
+* @since 1.0.0
+*/
+function createParserContext(frame, exec) {
+	return {
+		exec,
+		buffer: frame.buffer,
+		state: frame.state,
+		optionsTerminated: frame.optionsTerminated,
+		usage: exec.usage,
+		dependencyRegistry: exec.dependencyRegistry
+	};
+}
 function injectAnnotationsIntoState(state, options) {
 	const annotations = options?.annotations;
 	if (annotations == null) return state;
@@ -38,12 +60,16 @@ function injectAnnotationsIntoState(state, options) {
 function parseSync(parser, args, options) {
 	const initialState = injectAnnotationsIntoState(parser.initialState, options);
 	const shouldUnwrapAnnotatedValue = options?.annotations != null || require_annotations.isInjectedAnnotationWrapper(parser.initialState);
-	let context = {
+	const exec = {
+		usage: parser.usage,
+		phase: "parse",
+		path: []
+	};
+	let context = createParserContext({
 		buffer: args,
-		optionsTerminated: false,
 		state: initialState,
-		usage: parser.usage
-	};
+		optionsTerminated: false
+	}, exec);
 	do {
 		const result = parser.parse(context);
 		if (!result.success) return {
@@ -57,7 +83,11 @@ function parseSync(parser, args, options) {
 			error: require_message.message`Unexpected option or argument: ${context.buffer[0]}.`
 		};
 	} while (context.buffer.length > 0);
-	const endResult = parser.complete(context.state);
+	const completeExec = {
+		...exec,
+		phase: "complete"
+	};
+	const endResult = parser.complete(context.state, completeExec);
 	return endResult.success ? {
 		success: true,
 		value: shouldUnwrapAnnotatedValue ? require_annotations.unwrapInjectedAnnotationWrapper(endResult.value) : endResult.value,
@@ -97,12 +127,16 @@ function isBufferUnchanged(previous, current) {
 async function parseAsync(parser, args, options) {
 	const initialState = injectAnnotationsIntoState(parser.initialState, options);
 	const shouldUnwrapAnnotatedValue = options?.annotations != null || require_annotations.isInjectedAnnotationWrapper(parser.initialState);
-	let context = {
+	const exec = {
+		usage: parser.usage,
+		phase: "parse",
+		path: []
+	};
+	let context = createParserContext({
 		buffer: args,
-		optionsTerminated: false,
 		state: initialState,
-		usage: parser.usage
-	};
+		optionsTerminated: false
+	}, exec);
 	do {
 		const result = await parser.parse(context);
 		if (!result.success) return {
@@ -116,7 +150,11 @@ async function parseAsync(parser, args, options) {
 			error: require_message.message`Unexpected option or argument: ${context.buffer[0]}.`
 		};
 	} while (context.buffer.length > 0);
-	const endResult = await parser.complete(context.state);
+	const completeExec = {
+		...exec,
+		phase: "complete"
+	};
+	const endResult = await parser.complete(context.state, completeExec);
 	return endResult.success ? {
 		success: true,
 		value: shouldUnwrapAnnotatedValue ? require_annotations.unwrapInjectedAnnotationWrapper(endResult.value) : endResult.value,
@@ -192,12 +230,15 @@ function suggestSync(parser, args, options) {
 	const allButLast = args.slice(0, -1);
 	const prefix = args[args.length - 1];
 	const initialState = injectAnnotationsIntoState(parser.initialState, options);
-	let context = {
+	let context = createParserContext({
 		buffer: allButLast,
-		optionsTerminated: false,
 		state: initialState,
-		usage: parser.usage
-	};
+		optionsTerminated: false
+	}, {
+		usage: parser.usage,
+		phase: "suggest",
+		path: []
+	});
 	while (context.buffer.length > 0) {
 		const result = parser.parse(context);
 		if (!result.success) return Array.from(parser.suggest(context, prefix));
@@ -231,12 +272,15 @@ async function suggestAsync(parser, args, options) {
 	const allButLast = args.slice(0, -1);
 	const prefix = args[args.length - 1];
 	const initialState = injectAnnotationsIntoState(parser.initialState, options);
-	let context = {
+	let context = createParserContext({
 		buffer: allButLast,
-		optionsTerminated: false,
 		state: initialState,
-		usage: parser.usage
-	};
+		optionsTerminated: false
+	}, {
+		usage: parser.usage,
+		phase: "suggest",
+		path: []
+	});
 	while (context.buffer.length > 0) {
 		const result = await parser.parse(context);
 		if (!result.success) {
@@ -493,6 +537,7 @@ exports.command = require_primitives.command;
 exports.concat = require_constructs.concat;
 exports.conditional = require_constructs.conditional;
 exports.constant = require_primitives.constant;
+exports.createParserContext = createParserContext;
 exports.fail = require_primitives.fail;
 exports.flag = require_primitives.flag;
 exports.getDocPage = getDocPage;

package/dist/parser.d.cts

@@ -164,13 +164,17 @@ interface Parser<M extends Mode = "sync", TValue = unknown, TState = unknown> {
    * message.
    * @param state The current state of the parser, which may contain accumulated
    *              data or context needed to produce the final value.
+   * @param exec Optional shared execution context.  When provided, gives the
+   *             parser access to cross-cutting runtime data such as the current
+   *             execution phase and dependency registry.
    * @returns A result object indicating success or failure of
    *          the transformation.  If successful, it should contain
    *          the parsed value of type {@link TValue}.  If not applicable,
    *          it should return an error message.
    *          In async mode, returns a Promise that resolves to the result.
+   * @since 1.0.0 Added optional `exec` parameter.
    */
-  complete(state: TState): ModeValue<M, ValueParserResult<TValue>>;
+  complete(state: TState, exec?: ExecutionContext): ModeValue<M, ValueParserResult<TValue>>;
   /**
    * Generates next-step suggestions based on the current context
    * and an optional prefix.  This can be used to provide shell completion
@@ -221,10 +225,12 @@ interface Parser<M extends Mode = "sync", TValue = unknown, TState = unknown> {
    * source) has resolved.
    *
    * @param state The current parser state.
+   * @param exec Optional shared execution context.
    * @returns `true` if completion should be deferred.
    * @since 1.0.0
+   * @since 1.0.0 Added optional `exec` parameter.
    */
-  shouldDeferCompletion?(state: TState): boolean;
+  shouldDeferCompletion?(state: TState, exec?: ExecutionContext): boolean;
   /**
    * Normalizes a parsed value according to the underlying value parser's
    * configuration.  When present, {@link withDefault} calls this method
@@ -246,11 +252,82 @@ interface Parser<M extends Mode = "sync", TValue = unknown, TState = unknown> {
    */
   normalizeValue?(value: TValue): TValue;
 }
+/**
+ * Parser-local frame data containing the input buffer and parser state.
+ * This represents the per-parser progress during parsing, separated from
+ * cross-cutting execution context.
+ * @template TState The type of the state used during parsing.
+ * @since 1.0.0
+ */
+interface ParseFrame<TState> {
+  /**
+   * The array of input strings that the parser is currently processing.
+   */
+  readonly buffer: readonly string[];
+  /**
+   * The current state of the parser, which is used to track
+   * the progress of parsing and any accumulated data.
+   */
+  readonly state: TState;
+  /**
+   * A flag indicating whether no more options should be parsed and instead
+   * the remaining input should be treated as positional arguments.
+   */
+  readonly optionsTerminated: boolean;
+}
+/**
+ * The phase of the execution pipeline.
+ * @since 1.0.0
+ */
+type ExecutionPhase = "parse" | "precomplete" | "resolve" | "complete" | "suggest";
+/**
+ * Shared execution context carrying cross-cutting runtime data.
+ * This includes information that is shared across all parsers in a parse
+ * tree, such as usage information, dependency registries, and the current
+ * execution phase.
+ * @since 1.0.0
+ */
+interface ExecutionContext {
+  /**
+   * Usage information for the entire parser tree.
+   */
+  readonly usage: Usage;
+  /**
+   * The current phase of the execution pipeline.
+   */
+  readonly phase: ExecutionPhase;
+  /**
+   * The path from the root to the current parser in the parse tree.
+   * Used by constructs to track the current position during dependency
+   * resolution and completion.
+   */
+  readonly path: readonly PropertyKey[];
+  /**
+   * A registry containing resolved dependency values from DependencySource
+   * parsers.
+   * @since 0.10.0
+   */
+  readonly dependencyRegistry?: DependencyRegistryLike;
+}
 /**
  * The context of the parser, which includes the input buffer and the state.
+ *
+ * `ParserContext` provides structured access to shared execution context
+ * via {@link exec}, and flat access to all fields for backward
+ * compatibility.
+ *
  * @template TState The type of the state used during parsing.
  */
 interface ParserContext<TState> {
+  /**
+   * Shared execution context (usage, phase, path, dependencyRegistry).
+   *
+   * Present when the context was created via {@link createParserContext}.
+   * Later runtime work will make this field required.
+   *
+   * @since 1.0.0
+   */
+  readonly exec?: ExecutionContext;
   /**
    * The array of input strings that the parser is currently processing.
    */
@@ -284,6 +361,19 @@ interface ParserContext<TState> {
    */
   readonly dependencyRegistry?: DependencyRegistryLike;
 }
+/**
+ * Creates a {@link ParserContext} from a {@link ParseFrame} and an
+ * {@link ExecutionContext}.  The returned object provides both structured
+ * access (`frame`, `exec`) and flat access (`buffer`, `state`, etc.)
+ * for backward compatibility.
+ *
+ * @template TState The type of the state used during parsing.
+ * @param frame Parser-local frame data.
+ * @param exec Shared execution context.
+ * @returns A {@link ParserContext} instance.
+ * @since 1.0.0
+ */
+declare function createParserContext<TState>(frame: ParseFrame<TState>, exec: ExecutionContext): ParserContext<TState>;
 /**
  * Represents a suggestion for command-line completion or guidance.
  * @since 0.6.0
@@ -648,4 +738,4 @@ declare function getDocPage(parser: Parser<"sync", unknown, unknown>, argsOrOpti
 declare function getDocPage(parser: Parser<"async", unknown, unknown>, argsOrOptions?: readonly string[] | ParseOptions, options?: ParseOptions): Promise<DocPage | undefined>;
 declare function getDocPage<M extends Mode>(parser: Parser<M, unknown, unknown>, argsOrOptions?: readonly string[] | ParseOptions, options?: ParseOptions): ModeValue<M, DocPage | undefined>;
 //#endregion
-export { ArgumentErrorOptions, ArgumentOptions, CombineModes, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocState, DuplicateOptionError, FlagErrorOptions, FlagOptions, GroupOptions, InferMode, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OptionState, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, argument, command, concat, conditional, constant, fail, flag, getDocPage, getDocPageAsync, getDocPageSync, group, longestMatch, map, merge, multiple, nonEmpty, object, option, optional, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, withDefault };
+export { ArgumentErrorOptions, ArgumentOptions, CombineModes, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocState, DuplicateOptionError, ExecutionContext, ExecutionPhase, FlagErrorOptions, FlagOptions, GroupOptions, InferMode, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OptionState, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, argument, command, concat, conditional, constant, createParserContext, fail, flag, getDocPage, getDocPageAsync, getDocPageSync, group, longestMatch, map, merge, multiple, nonEmpty, object, option, optional, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, withDefault };