@optique/core 1.0.0-dev.1785 → 1.0.0-dev.1787

package/dist/facade.cjs

@@ -5,13 +5,13 @@ const require_validate = require('./validate.cjs');
 const require_usage = require('./usage.cjs');
 const require_doc = require('./doc.cjs');
 const require_mode_dispatch = require('./mode-dispatch.cjs');
+const require_dependency_runtime = require('./dependency-runtime.cjs');
 const require_input_trace = require('./input-trace.cjs');
 const require_phase2_seed = require('./phase2-seed.cjs');
 const require_modifiers = require('./modifiers.cjs');
 const require_valueparser = require('./valueparser.cjs');
 const require_primitives = require('./primitives.cjs');
 const require_parser = require('./parser.cjs');
-const require_dependency_runtime = require('./dependency-runtime.cjs');
 const require_constructs = require('./constructs.cjs');
 
 //#region src/facade.ts

package/dist/facade.js

@@ -5,13 +5,13 @@ import { validateCommandNames, validateContextIds, validateMetaNameCollisions, v
 import { extractCommandNames, extractLiteralValues, extractOptionNames, formatUsage } from "./usage.js";
 import { formatDocPage } from "./doc.js";
 import { dispatchByMode } from "./mode-dispatch.js";
+import { createDependencyRuntimeContext } from "./dependency-runtime.js";
 import { createInputTrace } from "./input-trace.js";
 import { completeOrExtractPhase2Seed } from "./phase2-seed.js";
 import { multiple, optional, withDefault } from "./modifiers.js";
 import { string } from "./valueparser.js";
 import { argument, command, constant, flag, option } from "./primitives.js";
 import { createParserContext, getDocPage, parseAsync, parseSync, suggest, suggestAsync } from "./parser.js";
-import { createDependencyRuntimeContext } from "./dependency-runtime.js";
 import { group, longestMatch, object } from "./constructs.js";
 
 //#region src/facade.ts

package/dist/index.cjs

@@ -1,9 +1,9 @@
 const require_annotations = require('./annotations.cjs');
 const require_message = require('./message.cjs');
 const require_completion = require('./completion.cjs');
-const require_dependency = require('./dependency.cjs');
 const require_usage = require('./usage.cjs');
 const require_doc = require('./doc.cjs');
+const require_dependency = require('./dependency.cjs');
 const require_modifiers = require('./modifiers.cjs');
 const require_nonempty = require('./nonempty.cjs');
 const require_valueparser = require('./valueparser.cjs');

package/dist/index.js

@@ -1,9 +1,9 @@
 import { annotationKey, getAnnotations } from "./annotations.js";
 import { commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.js";
 import { bash, fish, nu, pwsh, zsh } from "./completion.js";
-import { DependencyRegistry, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultDependencyValueSnapshot, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, formatDependencyError, getDefaultValuesFunction, getDependencyIds, getSnapshottedDefaultDependencyValues, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isPendingDependencySourceState, isWrappedDependencySource, parseWithDependency, pendingDependencySourceStateMarker, singleDefaultValue, snapshotDefaultDependencyValues, suggestWithDependency, transformsDependencyValue, transformsDependencyValueMarker, wrappedDependencySourceMarker } from "./dependency.js";
 import { cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.js";
 import { cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage, isDocEntryHidden } from "./doc.js";
+import { DependencyRegistry, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultDependencyValueSnapshot, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, formatDependencyError, getDefaultValuesFunction, getDependencyIds, getSnapshottedDefaultDependencyValues, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isPendingDependencySourceState, isWrappedDependencySource, parseWithDependency, pendingDependencySourceStateMarker, singleDefaultValue, snapshotDefaultDependencyValues, suggestWithDependency, transformsDependencyValue, transformsDependencyValueMarker, wrappedDependencySourceMarker } from "./dependency.js";
 import { WithDefaultError, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
 import { ensureNonEmptyString, isNonEmptyString } from "./nonempty.js";
 import { checkBooleanOption, checkEnumOption, choice, cidr, domain, email, float, hostname, integer, ip, ipv4, ipv6, isValueParser, locale, macAddress, port, portRange, socketAddress, string, url, uuid } from "./valueparser.js";

package/dist/parser.cjs

@@ -3,10 +3,10 @@ const require_message = require('./message.cjs');
 const require_usage = require('./usage.cjs');
 const require_doc = require('./doc.cjs');
 const require_mode_dispatch = require('./mode-dispatch.cjs');
+const require_dependency_runtime = require('./dependency-runtime.cjs');
 const require_input_trace = require('./input-trace.cjs');
 const require_modifiers = require('./modifiers.cjs');
 const require_primitives = require('./primitives.cjs');
-const require_dependency_runtime = require('./dependency-runtime.cjs');
 const require_constructs = require('./constructs.cjs');
 
 //#region src/parser.ts

package/dist/parser.js

@@ -3,10 +3,10 @@ import { cloneMessage, message } from "./message.js";
 import { cloneUsage, normalizeUsage } from "./usage.js";
 import { cloneDocEntry, isDocEntryHidden } from "./doc.js";
 import { dispatchByMode } from "./mode-dispatch.js";
+import { collectExplicitSourceValues, collectExplicitSourceValuesAsync, createDependencyRuntimeContext } from "./dependency-runtime.js";
 import { createInputTrace } from "./input-trace.js";
 import { WithDefaultError, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
 import { argument, command, constant, fail, flag, option, passThrough } from "./primitives.js";
-import { collectExplicitSourceValues, collectExplicitSourceValuesAsync, createDependencyRuntimeContext } from "./dependency-runtime.js";
 import { DuplicateOptionError, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
 
 //#region src/parser.ts

package/dist/primitives.cjs

@@ -1,15 +1,16 @@
 const require_annotations = require('./annotations.cjs');
 const require_message = require('./message.cjs');
-const require_dependency = require('./dependency.cjs');
 const require_validate = require('./validate.cjs');
 const require_usage = require('./usage.cjs');
 const require_mode_dispatch = require('./mode-dispatch.cjs');
+const require_dependency = require('./dependency.cjs');
+const require_dependency_runtime = require('./dependency-runtime.cjs');
 const require_dependency_metadata = require('./dependency-metadata.cjs');
 const require_phase2_seed = require('./phase2-seed.cjs');
 const require_suggestion = require('./suggestion.cjs');
 const require_usage_internals = require('./usage-internals.cjs');
 const require_valueparser = require('./valueparser.cjs');
-const require_dependency_runtime = require('./dependency-runtime.cjs');
+const require_annotation_state = require('./annotation-state.cjs');
 
 //#region src/primitives.ts
 /**
@@ -307,7 +308,7 @@ function* suggestOptionSync(optionNames$1, valueParser, hidden, context, prefix)
 			if (context.buffer.length > 0) {
 				const lastToken = context.buffer[context.buffer.length - 1];
 				if (optionNames$1.includes(lastToken)) shouldSuggestValues = true;
-			} else if (context.state === void 0 && context.buffer.length === 0 && (context.exec?.path?.length ?? 0) === 0 && !(prefix.startsWith("--") || prefix.startsWith("-") || prefix.startsWith("/"))) shouldSuggestValues = true;
+			} else if (require_annotation_state.isAnnotationWrappedInitialState(context.state) && context.buffer.length === 0 && (context.exec?.path?.length ?? 0) === 0 && !(prefix.startsWith("--") || prefix.startsWith("-") || prefix.startsWith("/"))) shouldSuggestValues = true;
 			if (shouldSuggestValues) yield* getSuggestionsWithDependency(valueParser, prefix, context.dependencyRegistry, context.exec);
 		}
 	}
@@ -391,7 +392,7 @@ async function* suggestOptionAsync(optionNames$1, valueParser, hidden, context,
 			if (context.buffer.length > 0) {
 				const lastToken = context.buffer[context.buffer.length - 1];
 				if (optionNames$1.includes(lastToken)) shouldSuggestValues = true;
-			} else if (context.state === void 0 && context.buffer.length === 0 && (context.exec?.path?.length ?? 0) === 0 && !(prefix.startsWith("--") || prefix.startsWith("-") || prefix.startsWith("/"))) shouldSuggestValues = true;
+			} else if (require_annotation_state.isAnnotationWrappedInitialState(context.state) && context.buffer.length === 0 && (context.exec?.path?.length ?? 0) === 0 && !(prefix.startsWith("--") || prefix.startsWith("-") || prefix.startsWith("/"))) shouldSuggestValues = true;
 			if (shouldSuggestValues) for await (const suggestion of getSuggestionsWithDependencyAsync(valueParser, prefix, context.dependencyRegistry, context.exec)) yield suggestion;
 		}
 	}
@@ -996,6 +997,7 @@ function argument(valueParser, options = {}) {
 		acceptingAnyToken: true,
 		initialState: void 0,
 		parse(context) {
+			const localState = require_annotation_state.normalizeInjectedAnnotationState(context.state);
 			if (context.buffer.length < 1) return {
 				success: false,
 				consumed: 0,
@@ -1018,7 +1020,7 @@ function argument(valueParser, options = {}) {
 				consumed: i,
 				error: require_message.message`Expected an argument, but got end of input.`
 			};
-			if (context.state != null) return {
+			if (localState != null) return {
 				success: false,
 				consumed: i,
 				error: options.errors?.multiple ? typeof options.errors.multiple === "function" ? options.errors.multiple(valueParser.metavar) : options.errors.multiple : require_message.message`The argument ${require_message.metavar(valueParser.metavar)} cannot be used multiple times.`
@@ -1077,7 +1079,7 @@ function argument(valueParser, options = {}) {
 			return require_mode_dispatch.dispatchByMode(valueParser.$mode, completeSync, completeAsync);
 		},
 		suggest(context, prefix) {
-			if (context.state != null) return require_mode_dispatch.dispatchIterableByMode(valueParser.$mode, function* () {}, async function* () {});
+			if (require_annotation_state.normalizeInjectedAnnotationState(context.state) != null) return require_mode_dispatch.dispatchIterableByMode(valueParser.$mode, function* () {}, async function* () {});
 			if (isAsync) return suggestArgumentAsync(valueParser, require_usage.isSuggestionHidden(options.hidden), prefix, context.dependencyRegistry, context.exec);
 			return suggestArgumentSync(valueParser, require_usage.isSuggestionHidden(options.hidden), prefix, context.dependencyRegistry, context.exec);
 		},
@@ -1166,30 +1168,44 @@ function argument(valueParser, options = {}) {
 	});
 	return result;
 }
+function normalizeCommandState(state) {
+	return require_annotation_state.normalizeInjectedAnnotationState(state);
+}
+function getCommandParseChildState(commandState, childState, parser) {
+	return require_annotation_state.getWrappedChildParseState(commandState, childState, parser);
+}
+function getCommandChildState(commandState, childState, parser) {
+	return require_annotation_state.getWrappedChildState(commandState, childState, parser);
+}
+function createCommandState(sourceState, state) {
+	return require_annotations.annotateFreshArray(sourceState, state);
+}
 function* suggestCommandSync(context, prefix, name, parser, options) {
 	if (require_usage.isSuggestionHidden(options.hidden)) return;
-	if (context.state === void 0) {
+	const state = normalizeCommandState(context.state);
+	if (state === void 0) {
 		if (name.startsWith(prefix)) yield {
 			kind: "literal",
 			text: name,
 			...options.description && { description: options.description }
 		};
-	} else if (context.state[0] === "matched") yield* parser.suggest(withChildContext(context, name, parser.initialState, parser.usage), prefix);
-	else if (context.state[0] === "parsing") yield* parser.suggest(withChildContext(context, name, context.state[1], parser.usage), prefix);
+	} else if (state[0] === "matched") yield* parser.suggest(withChildContext(context, name, getCommandChildState(context.state, parser.initialState, parser), parser.usage), prefix);
+	else if (state[0] === "parsing") yield* parser.suggest(withChildContext(context, name, getCommandChildState(context.state, state[1], parser), parser.usage), prefix);
 }
 async function* suggestCommandAsync(context, prefix, name, parser, options) {
 	if (require_usage.isSuggestionHidden(options.hidden)) return;
-	if (context.state === void 0) {
+	const state = normalizeCommandState(context.state);
+	if (state === void 0) {
 		if (name.startsWith(prefix)) yield {
 			kind: "literal",
 			text: name,
 			...options.description && { description: options.description }
 		};
-	} else if (context.state[0] === "matched") {
-		const suggestions = parser.suggest(withChildContext(context, name, parser.initialState, parser.usage), prefix);
+	} else if (state[0] === "matched") {
+		const suggestions = parser.suggest(withChildContext(context, name, getCommandChildState(context.state, parser.initialState, parser), parser.usage), prefix);
 		for await (const s of suggestions) yield s;
-	} else if (context.state[0] === "parsing") {
-		const suggestions = parser.suggest(withChildContext(context, name, context.state[1], parser.usage), prefix);
+	} else if (state[0] === "parsing") {
+		const suggestions = parser.suggest(withChildContext(context, name, getCommandChildState(context.state, state[1], parser), parser.usage), prefix);
 		for await (const s of suggestions) yield s;
 	}
 }
@@ -1230,8 +1246,9 @@ function command(name, parser, options = {}) {
 		acceptingAnyToken: false,
 		initialState: void 0,
 		getSuggestRuntimeNodes(state, path) {
-			if (state === void 0) return [];
-			const childState = state[0] === "matched" ? parser.initialState : state[1];
+			const normalizedState = normalizeCommandState(state);
+			if (normalizedState === void 0) return [];
+			const childState = normalizedState[0] === "matched" ? getCommandChildState(state, parser.initialState, parser) : getCommandChildState(state, normalizedState[1], parser);
 			const childPath = [...path, name];
 			return parser.getSuggestRuntimeNodes?.(childState, childPath) ?? (parser.dependencyMetadata?.source != null ? [{
 				path: childPath,
@@ -1240,7 +1257,8 @@ function command(name, parser, options = {}) {
 			}] : []);
 		},
 		parse(context) {
-			if (context.state === void 0) {
+			const state = normalizeCommandState(context.state);
+			if (state === void 0) {
 				if (context.buffer.length < 1 || context.buffer[0] !== name) {
 					const actual = context.buffer.length > 0 ? context.buffer[0] : null;
 					const leadingCmds = require_usage_internals.extractLeadingCommandNames(context.usage);
@@ -1275,12 +1293,12 @@ function command(name, parser, options = {}) {
 					next: {
 						...context,
 						buffer: context.buffer.slice(1),
-						state: ["matched", name]
+						state: createCommandState(context.state, ["matched", name])
 					},
 					consumed: context.buffer.slice(0, 1)
 				};
-			} else if (context.state[0] === "matched" || context.state[0] === "parsing") {
-				const innerState = context.state[0] === "matched" ? parser.initialState : context.state[1];
+			} else if (state[0] === "matched" || state[0] === "parsing") {
+				const innerState = state[0] === "matched" ? getCommandParseChildState(context.state, parser.initialState, parser) : getCommandParseChildState(context.state, state[1], parser);
 				const wrapState = (parseResult) => {
 					if (parseResult.success) {
 						const mergedExec = mergeChildExec(context.exec, parseResult.next.exec);
@@ -1288,7 +1306,7 @@ function command(name, parser, options = {}) {
 							success: true,
 							next: {
 								...parseResult.next,
-								state: ["parsing", parseResult.next.state],
+								state: createCommandState(context.state, ["parsing", parseResult.next.state]),
 								...mergedExec != null ? {
 									exec: mergedExec,
 									dependencyRegistry: mergedExec.dependencyRegistry
@@ -1308,17 +1326,18 @@ function command(name, parser, options = {}) {
 			};
 		},
 		complete(state, exec) {
-			if (typeof state === "undefined") return {
+			const normalizedState = normalizeCommandState(state);
+			if (typeof normalizedState === "undefined") return {
 				success: false,
 				error: options.errors?.notFound ?? require_message.message`Command ${require_message.optionName(name)} was not matched.`
 			};
-			else if (state[0] === "matched") {
+			else if (normalizedState[0] === "matched") {
 				const childExec = withChildExecPath(exec, name);
 				const childContext = {
 					buffer: [],
 					optionsTerminated: false,
 					usage: parser.usage,
-					state: parser.initialState,
+					state: getCommandParseChildState(state, parser.initialState, parser),
 					...childExec != null ? {
 						exec: childExec,
 						trace: childExec.trace,
@@ -1328,15 +1347,15 @@ function command(name, parser, options = {}) {
 				return require_mode_dispatch.dispatchByMode(parser.$mode, () => {
 					const parseResult = syncInnerParser.parse(childContext);
 					const nextExec = parseResult.success ? mergeChildExec(childExec, parseResult.next.exec) : childExec;
-					return syncInnerParser.complete(parseResult.success ? parseResult.next.state : syncInnerParser.initialState, nextExec);
+					return syncInnerParser.complete(parseResult.success ? getCommandChildState(state, parseResult.next.state, parser) : getCommandChildState(state, syncInnerParser.initialState, parser), nextExec);
 				}, async () => {
 					const parseResult = await asyncInnerParser.parse(childContext);
 					const nextExec = parseResult.success ? mergeChildExec(childExec, parseResult.next.exec) : childExec;
-					return asyncInnerParser.complete(parseResult.success ? parseResult.next.state : parser.initialState, nextExec);
+					return asyncInnerParser.complete(parseResult.success ? getCommandChildState(state, parseResult.next.state, parser) : getCommandChildState(state, parser.initialState, parser), nextExec);
 				});
-			} else if (state[0] === "parsing") {
+			} else if (normalizedState[0] === "parsing") {
 				const childExec = withChildExecPath(exec, name);
-				return require_mode_dispatch.dispatchByMode(parser.$mode, () => syncInnerParser.complete(state[1], childExec), async () => await asyncInnerParser.complete(state[1], childExec));
+				return require_mode_dispatch.dispatchByMode(parser.$mode, () => syncInnerParser.complete(getCommandChildState(state, normalizedState[1], parser), childExec), async () => await asyncInnerParser.complete(getCommandChildState(state, normalizedState[1], parser), childExec));
 			}
 			return {
 				success: false,
@@ -1344,14 +1363,15 @@ function command(name, parser, options = {}) {
 			};
 		},
 		[require_phase2_seed.extractPhase2SeedKey](state, exec) {
-			if (typeof state === "undefined") return require_mode_dispatch.wrapForMode(parser.$mode, null);
-			if (state[0] === "matched") {
+			const normalizedState = normalizeCommandState(state);
+			if (typeof normalizedState === "undefined") return require_mode_dispatch.wrapForMode(parser.$mode, null);
+			if (normalizedState[0] === "matched") {
 				const childExec = withChildExecPath(exec, name);
 				const childContext = {
 					buffer: [],
 					optionsTerminated: false,
 					usage: parser.usage,
-					state: parser.initialState,
+					state: getCommandParseChildState(state, parser.initialState, parser),
 					...childExec != null ? {
 						exec: childExec,
 						trace: childExec.trace,
@@ -1361,14 +1381,14 @@ function command(name, parser, options = {}) {
 				return require_mode_dispatch.dispatchByMode(parser.$mode, () => {
 					const parseResult = syncInnerParser.parse(childContext);
 					const nextExec = parseResult.success ? mergeChildExec(childExec, parseResult.next.exec) : childExec;
-					return require_phase2_seed.completeOrExtractPhase2Seed(syncInnerParser, parseResult.success ? parseResult.next.state : syncInnerParser.initialState, nextExec);
+					return require_phase2_seed.completeOrExtractPhase2Seed(syncInnerParser, parseResult.success ? getCommandChildState(state, parseResult.next.state, parser) : getCommandChildState(state, syncInnerParser.initialState, parser), nextExec);
 				}, async () => {
 					const parseResult = await asyncInnerParser.parse(childContext);
 					const nextExec = parseResult.success ? mergeChildExec(childExec, parseResult.next.exec) : childExec;
-					return await require_phase2_seed.completeOrExtractPhase2Seed(asyncInnerParser, parseResult.success ? parseResult.next.state : parser.initialState, nextExec);
+					return await require_phase2_seed.completeOrExtractPhase2Seed(asyncInnerParser, parseResult.success ? getCommandChildState(state, parseResult.next.state, parser) : getCommandChildState(state, parser.initialState, parser), nextExec);
 				});
 			}
-			if (state[0] === "parsing") return require_phase2_seed.completeOrExtractPhase2Seed(parser, state[1], withChildExecPath(exec, name));
+			if (normalizedState[0] === "parsing") return require_phase2_seed.completeOrExtractPhase2Seed(parser, getCommandChildState(state, normalizedState[1], parser), withChildExecPath(exec, name));
 			return require_mode_dispatch.wrapForMode(parser.$mode, null);
 		},
 		suggest(context, prefix) {
@@ -1376,7 +1396,8 @@ function command(name, parser, options = {}) {
 			return suggestCommandSync(context, prefix, name, parser, options);
 		},
 		getDocFragments(state, defaultValue) {
-			if (state.kind === "unavailable" || typeof state.state === "undefined") {
+			const commandState = state.kind === "available" ? normalizeCommandState(state.state) : void 0;
+			if (state.kind === "unavailable" || typeof commandState === "undefined") {
 				if (require_usage.isDocHidden(options.hidden)) return {
 					fragments: [],
 					description: options.description
@@ -1393,12 +1414,12 @@ function command(name, parser, options = {}) {
 					}]
 				};
 			}
-			const innerState = state.state[0] === "parsing" ? {
+			const innerState = commandState[0] === "parsing" ? {
 				kind: "available",
-				state: state.state[1]
+				state: getCommandChildState(state.state, commandState[1], parser)
 			} : {
 				kind: "available",
-				state: parser.initialState
+				state: getCommandChildState(state.state, parser.initialState, parser)
 			};
 			const innerFragments = parser.getDocFragments(innerState, defaultValue);
 			return {

package/dist/primitives.js

@@ -1,15 +1,16 @@
 import { annotateFreshArray, getAnnotations } from "./annotations.js";
 import { message, metavar, optionName, optionNames, text, valueSet } from "./message.js";
-import { getDefaultValuesFunction, getDependencyIds, getSnapshottedDefaultDependencyValues, isDerivedValueParser, suggestWithDependency } from "./dependency.js";
 import { validateCommandNames, validateOptionNames } from "./validate.js";
 import { extractOptionNames, isDocHidden, isSuggestionHidden } from "./usage.js";
 import { dispatchByMode, dispatchIterableByMode, wrapForMode } from "./mode-dispatch.js";
+import { getDefaultValuesFunction, getDependencyIds, getSnapshottedDefaultDependencyValues, isDerivedValueParser, suggestWithDependency } from "./dependency.js";
+import { replayDerivedParser, replayDerivedParserAsync } from "./dependency-runtime.js";
 import { extractDependencyMetadata } from "./dependency-metadata.js";
 import { completeOrExtractPhase2Seed, extractPhase2SeedKey } from "./phase2-seed.js";
 import { DEFAULT_FIND_SIMILAR_OPTIONS, createErrorWithSuggestions, createSuggestionMessage, findSimilar } from "./suggestion.js";
 import { extractLeadingCommandNames } from "./usage-internals.js";
 import { isValueParser } from "./valueparser.js";
-import { replayDerivedParser, replayDerivedParserAsync } from "./dependency-runtime.js";
+import { getWrappedChildParseState, getWrappedChildState, isAnnotationWrappedInitialState, normalizeInjectedAnnotationState } from "./annotation-state.js";
 
 //#region src/primitives.ts
 /**
@@ -307,7 +308,7 @@ function* suggestOptionSync(optionNames$1, valueParser, hidden, context, prefix)
 			if (context.buffer.length > 0) {
 				const lastToken = context.buffer[context.buffer.length - 1];
 				if (optionNames$1.includes(lastToken)) shouldSuggestValues = true;
-			} else if (context.state === void 0 && context.buffer.length === 0 && (context.exec?.path?.length ?? 0) === 0 && !(prefix.startsWith("--") || prefix.startsWith("-") || prefix.startsWith("/"))) shouldSuggestValues = true;
+			} else if (isAnnotationWrappedInitialState(context.state) && context.buffer.length === 0 && (context.exec?.path?.length ?? 0) === 0 && !(prefix.startsWith("--") || prefix.startsWith("-") || prefix.startsWith("/"))) shouldSuggestValues = true;
 			if (shouldSuggestValues) yield* getSuggestionsWithDependency(valueParser, prefix, context.dependencyRegistry, context.exec);
 		}
 	}
@@ -391,7 +392,7 @@ async function* suggestOptionAsync(optionNames$1, valueParser, hidden, context,
 			if (context.buffer.length > 0) {
 				const lastToken = context.buffer[context.buffer.length - 1];
 				if (optionNames$1.includes(lastToken)) shouldSuggestValues = true;
-			} else if (context.state === void 0 && context.buffer.length === 0 && (context.exec?.path?.length ?? 0) === 0 && !(prefix.startsWith("--") || prefix.startsWith("-") || prefix.startsWith("/"))) shouldSuggestValues = true;
+			} else if (isAnnotationWrappedInitialState(context.state) && context.buffer.length === 0 && (context.exec?.path?.length ?? 0) === 0 && !(prefix.startsWith("--") || prefix.startsWith("-") || prefix.startsWith("/"))) shouldSuggestValues = true;
 			if (shouldSuggestValues) for await (const suggestion of getSuggestionsWithDependencyAsync(valueParser, prefix, context.dependencyRegistry, context.exec)) yield suggestion;
 		}
 	}
@@ -996,6 +997,7 @@ function argument(valueParser, options = {}) {
 		acceptingAnyToken: true,
 		initialState: void 0,
 		parse(context) {
+			const localState = normalizeInjectedAnnotationState(context.state);
 			if (context.buffer.length < 1) return {
 				success: false,
 				consumed: 0,
@@ -1018,7 +1020,7 @@ function argument(valueParser, options = {}) {
 				consumed: i,
 				error: message`Expected an argument, but got end of input.`
 			};
-			if (context.state != null) return {
+			if (localState != null) return {
 				success: false,
 				consumed: i,
 				error: options.errors?.multiple ? typeof options.errors.multiple === "function" ? options.errors.multiple(valueParser.metavar) : options.errors.multiple : message`The argument ${metavar(valueParser.metavar)} cannot be used multiple times.`
@@ -1077,7 +1079,7 @@ function argument(valueParser, options = {}) {
 			return dispatchByMode(valueParser.$mode, completeSync, completeAsync);
 		},
 		suggest(context, prefix) {
-			if (context.state != null) return dispatchIterableByMode(valueParser.$mode, function* () {}, async function* () {});
+			if (normalizeInjectedAnnotationState(context.state) != null) return dispatchIterableByMode(valueParser.$mode, function* () {}, async function* () {});
 			if (isAsync) return suggestArgumentAsync(valueParser, isSuggestionHidden(options.hidden), prefix, context.dependencyRegistry, context.exec);
 			return suggestArgumentSync(valueParser, isSuggestionHidden(options.hidden), prefix, context.dependencyRegistry, context.exec);
 		},
@@ -1166,30 +1168,44 @@ function argument(valueParser, options = {}) {
 	});
 	return result;
 }
+function normalizeCommandState(state) {
+	return normalizeInjectedAnnotationState(state);
+}
+function getCommandParseChildState(commandState, childState, parser) {
+	return getWrappedChildParseState(commandState, childState, parser);
+}
+function getCommandChildState(commandState, childState, parser) {
+	return getWrappedChildState(commandState, childState, parser);
+}
+function createCommandState(sourceState, state) {
+	return annotateFreshArray(sourceState, state);
+}
 function* suggestCommandSync(context, prefix, name, parser, options) {
 	if (isSuggestionHidden(options.hidden)) return;
-	if (context.state === void 0) {
+	const state = normalizeCommandState(context.state);
+	if (state === void 0) {
 		if (name.startsWith(prefix)) yield {
 			kind: "literal",
 			text: name,
 			...options.description && { description: options.description }
 		};
-	} else if (context.state[0] === "matched") yield* parser.suggest(withChildContext(context, name, parser.initialState, parser.usage), prefix);
-	else if (context.state[0] === "parsing") yield* parser.suggest(withChildContext(context, name, context.state[1], parser.usage), prefix);
+	} else if (state[0] === "matched") yield* parser.suggest(withChildContext(context, name, getCommandChildState(context.state, parser.initialState, parser), parser.usage), prefix);
+	else if (state[0] === "parsing") yield* parser.suggest(withChildContext(context, name, getCommandChildState(context.state, state[1], parser), parser.usage), prefix);
 }
 async function* suggestCommandAsync(context, prefix, name, parser, options) {
 	if (isSuggestionHidden(options.hidden)) return;
-	if (context.state === void 0) {
+	const state = normalizeCommandState(context.state);
+	if (state === void 0) {
 		if (name.startsWith(prefix)) yield {
 			kind: "literal",
 			text: name,
 			...options.description && { description: options.description }
 		};
-	} else if (context.state[0] === "matched") {
-		const suggestions = parser.suggest(withChildContext(context, name, parser.initialState, parser.usage), prefix);
+	} else if (state[0] === "matched") {
+		const suggestions = parser.suggest(withChildContext(context, name, getCommandChildState(context.state, parser.initialState, parser), parser.usage), prefix);
 		for await (const s of suggestions) yield s;
-	} else if (context.state[0] === "parsing") {
-		const suggestions = parser.suggest(withChildContext(context, name, context.state[1], parser.usage), prefix);
+	} else if (state[0] === "parsing") {
+		const suggestions = parser.suggest(withChildContext(context, name, getCommandChildState(context.state, state[1], parser), parser.usage), prefix);
 		for await (const s of suggestions) yield s;
 	}
 }
@@ -1230,8 +1246,9 @@ function command(name, parser, options = {}) {
 		acceptingAnyToken: false,
 		initialState: void 0,
 		getSuggestRuntimeNodes(state, path) {
-			if (state === void 0) return [];
-			const childState = state[0] === "matched" ? parser.initialState : state[1];
+			const normalizedState = normalizeCommandState(state);
+			if (normalizedState === void 0) return [];
+			const childState = normalizedState[0] === "matched" ? getCommandChildState(state, parser.initialState, parser) : getCommandChildState(state, normalizedState[1], parser);
 			const childPath = [...path, name];
 			return parser.getSuggestRuntimeNodes?.(childState, childPath) ?? (parser.dependencyMetadata?.source != null ? [{
 				path: childPath,
@@ -1240,7 +1257,8 @@ function command(name, parser, options = {}) {
 			}] : []);
 		},
 		parse(context) {
-			if (context.state === void 0) {
+			const state = normalizeCommandState(context.state);
+			if (state === void 0) {
 				if (context.buffer.length < 1 || context.buffer[0] !== name) {
 					const actual = context.buffer.length > 0 ? context.buffer[0] : null;
 					const leadingCmds = extractLeadingCommandNames(context.usage);
@@ -1275,12 +1293,12 @@ function command(name, parser, options = {}) {
 					next: {
 						...context,
 						buffer: context.buffer.slice(1),
-						state: ["matched", name]
+						state: createCommandState(context.state, ["matched", name])
 					},
 					consumed: context.buffer.slice(0, 1)
 				};
-			} else if (context.state[0] === "matched" || context.state[0] === "parsing") {
-				const innerState = context.state[0] === "matched" ? parser.initialState : context.state[1];
+			} else if (state[0] === "matched" || state[0] === "parsing") {
+				const innerState = state[0] === "matched" ? getCommandParseChildState(context.state, parser.initialState, parser) : getCommandParseChildState(context.state, state[1], parser);
 				const wrapState = (parseResult) => {
 					if (parseResult.success) {
 						const mergedExec = mergeChildExec(context.exec, parseResult.next.exec);
@@ -1288,7 +1306,7 @@ function command(name, parser, options = {}) {
 							success: true,
 							next: {
 								...parseResult.next,
-								state: ["parsing", parseResult.next.state],
+								state: createCommandState(context.state, ["parsing", parseResult.next.state]),
 								...mergedExec != null ? {
 									exec: mergedExec,
 									dependencyRegistry: mergedExec.dependencyRegistry
@@ -1308,17 +1326,18 @@ function command(name, parser, options = {}) {
 			};
 		},
 		complete(state, exec) {
-			if (typeof state === "undefined") return {
+			const normalizedState = normalizeCommandState(state);
+			if (typeof normalizedState === "undefined") return {
 				success: false,
 				error: options.errors?.notFound ?? message`Command ${optionName(name)} was not matched.`
 			};
-			else if (state[0] === "matched") {
+			else if (normalizedState[0] === "matched") {
 				const childExec = withChildExecPath(exec, name);
 				const childContext = {
 					buffer: [],
 					optionsTerminated: false,
 					usage: parser.usage,
-					state: parser.initialState,
+					state: getCommandParseChildState(state, parser.initialState, parser),
 					...childExec != null ? {
 						exec: childExec,
 						trace: childExec.trace,
@@ -1328,15 +1347,15 @@ function command(name, parser, options = {}) {
 				return dispatchByMode(parser.$mode, () => {
 					const parseResult = syncInnerParser.parse(childContext);
 					const nextExec = parseResult.success ? mergeChildExec(childExec, parseResult.next.exec) : childExec;
-					return syncInnerParser.complete(parseResult.success ? parseResult.next.state : syncInnerParser.initialState, nextExec);
+					return syncInnerParser.complete(parseResult.success ? getCommandChildState(state, parseResult.next.state, parser) : getCommandChildState(state, syncInnerParser.initialState, parser), nextExec);
 				}, async () => {
 					const parseResult = await asyncInnerParser.parse(childContext);
 					const nextExec = parseResult.success ? mergeChildExec(childExec, parseResult.next.exec) : childExec;
-					return asyncInnerParser.complete(parseResult.success ? parseResult.next.state : parser.initialState, nextExec);
+					return asyncInnerParser.complete(parseResult.success ? getCommandChildState(state, parseResult.next.state, parser) : getCommandChildState(state, parser.initialState, parser), nextExec);
 				});
-			} else if (state[0] === "parsing") {
+			} else if (normalizedState[0] === "parsing") {
 				const childExec = withChildExecPath(exec, name);
-				return dispatchByMode(parser.$mode, () => syncInnerParser.complete(state[1], childExec), async () => await asyncInnerParser.complete(state[1], childExec));
+				return dispatchByMode(parser.$mode, () => syncInnerParser.complete(getCommandChildState(state, normalizedState[1], parser), childExec), async () => await asyncInnerParser.complete(getCommandChildState(state, normalizedState[1], parser), childExec));
 			}
 			return {
 				success: false,
@@ -1344,14 +1363,15 @@ function command(name, parser, options = {}) {
 			};
 		},
 		[extractPhase2SeedKey](state, exec) {
-			if (typeof state === "undefined") return wrapForMode(parser.$mode, null);
-			if (state[0] === "matched") {
+			const normalizedState = normalizeCommandState(state);
+			if (typeof normalizedState === "undefined") return wrapForMode(parser.$mode, null);
+			if (normalizedState[0] === "matched") {
 				const childExec = withChildExecPath(exec, name);
 				const childContext = {
 					buffer: [],
 					optionsTerminated: false,
 					usage: parser.usage,
-					state: parser.initialState,
+					state: getCommandParseChildState(state, parser.initialState, parser),
 					...childExec != null ? {
 						exec: childExec,
 						trace: childExec.trace,
@@ -1361,14 +1381,14 @@ function command(name, parser, options = {}) {
 				return dispatchByMode(parser.$mode, () => {
 					const parseResult = syncInnerParser.parse(childContext);
 					const nextExec = parseResult.success ? mergeChildExec(childExec, parseResult.next.exec) : childExec;
-					return completeOrExtractPhase2Seed(syncInnerParser, parseResult.success ? parseResult.next.state : syncInnerParser.initialState, nextExec);
+					return completeOrExtractPhase2Seed(syncInnerParser, parseResult.success ? getCommandChildState(state, parseResult.next.state, parser) : getCommandChildState(state, syncInnerParser.initialState, parser), nextExec);
 				}, async () => {
 					const parseResult = await asyncInnerParser.parse(childContext);
 					const nextExec = parseResult.success ? mergeChildExec(childExec, parseResult.next.exec) : childExec;
-					return await completeOrExtractPhase2Seed(asyncInnerParser, parseResult.success ? parseResult.next.state : parser.initialState, nextExec);
+					return await completeOrExtractPhase2Seed(asyncInnerParser, parseResult.success ? getCommandChildState(state, parseResult.next.state, parser) : getCommandChildState(state, parser.initialState, parser), nextExec);
 				});
 			}
-			if (state[0] === "parsing") return completeOrExtractPhase2Seed(parser, state[1], withChildExecPath(exec, name));
+			if (normalizedState[0] === "parsing") return completeOrExtractPhase2Seed(parser, getCommandChildState(state, normalizedState[1], parser), withChildExecPath(exec, name));
 			return wrapForMode(parser.$mode, null);
 		},
 		suggest(context, prefix) {
@@ -1376,7 +1396,8 @@ function command(name, parser, options = {}) {
 			return suggestCommandSync(context, prefix, name, parser, options);
 		},
 		getDocFragments(state, defaultValue) {
-			if (state.kind === "unavailable" || typeof state.state === "undefined") {
+			const commandState = state.kind === "available" ? normalizeCommandState(state.state) : void 0;
+			if (state.kind === "unavailable" || typeof commandState === "undefined") {
 				if (isDocHidden(options.hidden)) return {
 					fragments: [],
 					description: options.description
@@ -1393,12 +1414,12 @@ function command(name, parser, options = {}) {
 					}]
 				};
 			}
-			const innerState = state.state[0] === "parsing" ? {
+			const innerState = commandState[0] === "parsing" ? {
 				kind: "available",
-				state: state.state[1]
+				state: getCommandChildState(state.state, commandState[1], parser)
 			} : {
 				kind: "available",
-				state: parser.initialState
+				state: getCommandChildState(state.state, parser.initialState, parser)
 			};
 			const innerFragments = parser.getDocFragments(innerState, defaultValue);
 			return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.1785+6a8af6b8",
+  "version": "1.0.0-dev.1787+4a55dc3b",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",