@optique/core 1.0.0-dev.1658 → 1.0.0-dev.1661

package/dist/dependency-runtime.cjs

@@ -553,10 +553,16 @@ function resolveDeferredInState(state, runtime, visited = /* @__PURE__ */ new We
 	}
 	if (require_dependency.isDeferredParseState(state)) return resolveSingleDeferred(state, runtime);
 	if (require_dependency.isDependencySourceState(state)) return state;
-	if (Array.isArray(state)) return state.map((item) => resolveDeferredInState(item, runtime, visited));
+	if (Array.isArray(state)) {
+		const resolved = state.map((item) => resolveDeferredInState(item, runtime, visited));
+		return resolved.every((item, index) => item === state[index]) ? state : resolved;
+	}
 	if (isPlainObject(state)) {
+		const keys = Reflect.ownKeys(state);
+		const resolvedEntries = keys.map((key) => [key, resolveDeferredInState(state[key], runtime, visited)]);
+		if (resolvedEntries.every(([key, value]) => value === state[key])) return state;
 		const resolved = Object.create(Object.getPrototypeOf(state));
-		for (const key of Reflect.ownKeys(state)) resolved[key] = resolveDeferredInState(state[key], runtime, visited);
+		for (const [key, value] of resolvedEntries) resolved[key] = value;
 		return resolved;
 	}
 	return state;
@@ -595,13 +601,18 @@ async function resolveDeferredInStateAsync(state, runtime, visited = /* @__PURE_
 		return Promise.resolve(deferred.parser[require_dependency.parseWithDependency](deferred.rawInput, depValue));
 	}
 	if (require_dependency.isDependencySourceState(state)) return state;
-	if (Array.isArray(state)) return Promise.all(state.map((item) => resolveDeferredInStateAsync(item, runtime, visited)));
+	if (Array.isArray(state)) {
+		const resolved = await Promise.all(state.map((item) => resolveDeferredInStateAsync(item, runtime, visited)));
+		return resolved.every((item, index) => item === state[index]) ? state : resolved;
+	}
 	if (isPlainObject(state)) {
-		const resolved = Object.create(Object.getPrototypeOf(state));
 		const keys = Reflect.ownKeys(state);
-		await Promise.all(keys.map(async (key) => {
-			resolved[key] = await resolveDeferredInStateAsync(state[key], runtime, visited);
+		const resolvedEntries = await Promise.all(keys.map(async (key) => {
+			return [key, await resolveDeferredInStateAsync(state[key], runtime, visited)];
 		}));
+		if (resolvedEntries.every(([key, value]) => value === state[key])) return state;
+		const resolved = Object.create(Object.getPrototypeOf(state));
+		for (const [key, value] of resolvedEntries) resolved[key] = value;
 		return resolved;
 	}
 	return state;

package/dist/dependency-runtime.js

@@ -553,10 +553,16 @@ function resolveDeferredInState(state, runtime, visited = /* @__PURE__ */ new We
 	}
 	if (isDeferredParseState(state)) return resolveSingleDeferred(state, runtime);
 	if (isDependencySourceState(state)) return state;
-	if (Array.isArray(state)) return state.map((item) => resolveDeferredInState(item, runtime, visited));
+	if (Array.isArray(state)) {
+		const resolved = state.map((item) => resolveDeferredInState(item, runtime, visited));
+		return resolved.every((item, index) => item === state[index]) ? state : resolved;
+	}
 	if (isPlainObject(state)) {
+		const keys = Reflect.ownKeys(state);
+		const resolvedEntries = keys.map((key) => [key, resolveDeferredInState(state[key], runtime, visited)]);
+		if (resolvedEntries.every(([key, value]) => value === state[key])) return state;
 		const resolved = Object.create(Object.getPrototypeOf(state));
-		for (const key of Reflect.ownKeys(state)) resolved[key] = resolveDeferredInState(state[key], runtime, visited);
+		for (const [key, value] of resolvedEntries) resolved[key] = value;
 		return resolved;
 	}
 	return state;
@@ -595,13 +601,18 @@ async function resolveDeferredInStateAsync(state, runtime, visited = /* @__PURE_
 		return Promise.resolve(deferred.parser[parseWithDependency](deferred.rawInput, depValue));
 	}
 	if (isDependencySourceState(state)) return state;
-	if (Array.isArray(state)) return Promise.all(state.map((item) => resolveDeferredInStateAsync(item, runtime, visited)));
+	if (Array.isArray(state)) {
+		const resolved = await Promise.all(state.map((item) => resolveDeferredInStateAsync(item, runtime, visited)));
+		return resolved.every((item, index) => item === state[index]) ? state : resolved;
+	}
 	if (isPlainObject(state)) {
-		const resolved = Object.create(Object.getPrototypeOf(state));
 		const keys = Reflect.ownKeys(state);
-		await Promise.all(keys.map(async (key) => {
-			resolved[key] = await resolveDeferredInStateAsync(state[key], runtime, visited);
+		const resolvedEntries = await Promise.all(keys.map(async (key) => {
+			return [key, await resolveDeferredInStateAsync(state[key], runtime, visited)];
 		}));
+		if (resolvedEntries.every(([key, value]) => value === state[key])) return state;
+		const resolved = Object.create(Object.getPrototypeOf(state));
+		for (const [key, value] of resolvedEntries) resolved[key] = value;
 		return resolved;
 	}
 	return state;

package/dist/index.cjs

@@ -17,6 +17,7 @@ exports.DuplicateOptionError = require_constructs.DuplicateOptionError;
 exports.RunParserError = require_facade.RunParserError;
 exports.WithDefaultError = require_modifiers.WithDefaultError;
 exports.annotationKey = require_annotations.annotationKey;
+exports.annotationWrapperRequiresSourceBindingKey = require_parser.annotationWrapperRequiresSourceBindingKey;
 exports.argument = require_primitives.argument;
 exports.bash = require_completion.bash;
 exports.checkBooleanOption = require_valueparser.checkBooleanOption;
@@ -28,6 +29,7 @@ exports.cloneUsage = require_usage.cloneUsage;
 exports.cloneUsageTerm = require_usage.cloneUsageTerm;
 exports.command = require_primitives.command;
 exports.commandLine = require_message.commandLine;
+exports.composeWrappedSourceMetadata = require_parser.composeWrappedSourceMetadata;
 exports.concat = require_constructs.concat;
 exports.conditional = require_constructs.conditional;
 exports.constant = require_primitives.constant;
@@ -40,6 +42,8 @@ exports.deduplicateDocFragments = require_doc.deduplicateDocFragments;
 exports.defaultDependencyValueSnapshot = require_dependency.defaultDependencyValueSnapshot;
 exports.defaultValues = require_dependency.defaultValues;
 exports.deferredParseMarker = require_dependency.deferredParseMarker;
+exports.defineInheritedAnnotationParser = require_parser.defineInheritedAnnotationParser;
+exports.defineSourceBindingOnlyAnnotationCompletionParser = require_parser.defineSourceBindingOnlyAnnotationCompletionParser;
 exports.dependency = require_dependency.dependency;
 exports.dependencyId = require_dependency.dependencyId;
 exports.dependencyIds = require_dependency.dependencyIds;
@@ -68,6 +72,7 @@ exports.formatUsage = require_usage.formatUsage;
 exports.formatUsageTerm = require_usage.formatUsageTerm;
 exports.getAnnotations = require_annotations.getAnnotations;
 exports.getDefaultValuesFunction = require_dependency.getDefaultValuesFunction;
+exports.getDelegatingSuggestRuntimeNodes = require_parser.getDelegatingSuggestRuntimeNodes;
 exports.getDependencyIds = require_dependency.getDependencyIds;
 exports.getDocPage = require_parser.getDocPage;
 exports.getDocPageAsync = require_parser.getDocPageAsync;
@@ -76,6 +81,7 @@ exports.getParserSuggestRuntimeNodes = require_parser.getParserSuggestRuntimeNod
 exports.getSnapshottedDefaultDependencyValues = require_dependency.getSnapshottedDefaultDependencyValues;
 exports.group = require_constructs.group;
 exports.hostname = require_valueparser.hostname;
+exports.inheritParentAnnotationsKey = require_parser.inheritParentAnnotationsKey;
 exports.integer = require_valueparser.integer;
 exports.ip = require_valueparser.ip;
 exports.ipv4 = require_valueparser.ipv4;

package/dist/index.d.cts

@@ -7,9 +7,9 @@ import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsStr
 import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, GroupOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.cjs";
 import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.cjs";
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, option, passThrough } from "./primitives.cjs";
-import { CombineModes, DocState, ExecutionContext, ExecutionPhase, InferMode, InferValue, Mode, ModeIterable, ModeValue, ParseFrame, Parser, ParserContext, ParserResult, Result, Suggestion, createParserContext, getDocPage, getDocPageAsync, getDocPageSync, getParserSuggestRuntimeNodes, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync, unmatchedNonCliDependencySourceStateMarker } from "./parser.cjs";
+import { CombineModes, DocState, ExecutionContext, ExecutionPhase, InferMode, InferValue, Mode, ModeIterable, ModeValue, ParseFrame, Parser, ParserContext, ParserResult, Result, Suggestion, annotationWrapperRequiresSourceBindingKey, composeWrappedSourceMetadata, createParserContext, defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, getDelegatingSuggestRuntimeNodes, getDocPage, getDocPageAsync, getDocPageSync, getParserSuggestRuntimeNodes, inheritParentAnnotationsKey, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync, unmatchedNonCliDependencySourceStateMarker } from "./parser.cjs";
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.cjs";
 import { ParserValuePlaceholder, SourceContext } from "./context.cjs";
 import { AnyDependencySource, CombineMode, CombinedDependencyMode, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, PendingDependencySourceState, ResolvedDependency, 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.cjs";
 import { CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.cjs";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, DeferredMap, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FlagErrorOptions, FlagOptions, FloatOptions, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ResolvedDependency, Result, RunOptions, RunParserError, RunWithOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createParserContext, createPendingDependencySourceState, deduplicateDocEntries, deduplicateDocFragments, defaultDependencyValueSnapshot, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, getParserSuggestRuntimeNodes, getSnapshottedDefaultDependencyValues, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, singleDefaultValue, snapshotDefaultDependencyValues, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, unmatchedNonCliDependencySourceStateMarker, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, DeferredMap, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FlagErrorOptions, FlagOptions, FloatOptions, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ResolvedDependency, Result, RunOptions, RunParserError, RunWithOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, annotationWrapperRequiresSourceBindingKey, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, command, commandLine, composeWrappedSourceMetadata, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createParserContext, createPendingDependencySourceState, deduplicateDocEntries, deduplicateDocFragments, defaultDependencyValueSnapshot, defaultValues, deferredParseMarker, defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDelegatingSuggestRuntimeNodes, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, getParserSuggestRuntimeNodes, getSnapshottedDefaultDependencyValues, group, hostname, inheritParentAnnotationsKey, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, singleDefaultValue, snapshotDefaultDependencyValues, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, unmatchedNonCliDependencySourceStateMarker, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };

package/dist/index.d.ts

@@ -7,9 +7,9 @@ import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsStr
 import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, GroupOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
 import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, option, passThrough } from "./primitives.js";
-import { CombineModes, DocState, ExecutionContext, ExecutionPhase, InferMode, InferValue, Mode, ModeIterable, ModeValue, ParseFrame, Parser, ParserContext, ParserResult, Result, Suggestion, createParserContext, getDocPage, getDocPageAsync, getDocPageSync, getParserSuggestRuntimeNodes, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync, unmatchedNonCliDependencySourceStateMarker } from "./parser.js";
+import { CombineModes, DocState, ExecutionContext, ExecutionPhase, InferMode, InferValue, Mode, ModeIterable, ModeValue, ParseFrame, Parser, ParserContext, ParserResult, Result, Suggestion, annotationWrapperRequiresSourceBindingKey, composeWrappedSourceMetadata, createParserContext, defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, getDelegatingSuggestRuntimeNodes, getDocPage, getDocPageAsync, getDocPageSync, getParserSuggestRuntimeNodes, inheritParentAnnotationsKey, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync, unmatchedNonCliDependencySourceStateMarker } from "./parser.js";
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { ParserValuePlaceholder, SourceContext } from "./context.js";
 import { AnyDependencySource, CombineMode, CombinedDependencyMode, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, PendingDependencySourceState, ResolvedDependency, 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 { CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, DeferredMap, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FlagErrorOptions, FlagOptions, FloatOptions, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ResolvedDependency, Result, RunOptions, RunParserError, RunWithOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createParserContext, createPendingDependencySourceState, deduplicateDocEntries, deduplicateDocFragments, defaultDependencyValueSnapshot, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, getParserSuggestRuntimeNodes, getSnapshottedDefaultDependencyValues, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, singleDefaultValue, snapshotDefaultDependencyValues, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, unmatchedNonCliDependencySourceStateMarker, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, DeferredMap, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FlagErrorOptions, FlagOptions, FloatOptions, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ResolvedDependency, Result, RunOptions, RunParserError, RunWithOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, annotationWrapperRequiresSourceBindingKey, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, command, commandLine, composeWrappedSourceMetadata, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createParserContext, createPendingDependencySourceState, deduplicateDocEntries, deduplicateDocFragments, defaultDependencyValueSnapshot, defaultValues, deferredParseMarker, defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDelegatingSuggestRuntimeNodes, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, getParserSuggestRuntimeNodes, getSnapshottedDefaultDependencyValues, group, hostname, inheritParentAnnotationsKey, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, singleDefaultValue, snapshotDefaultDependencyValues, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, unmatchedNonCliDependencySourceStateMarker, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };

package/dist/index.js

@@ -8,8 +8,8 @@ import { WithDefaultError, map, multiple, nonEmpty, optional, withDefault } from
 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";
 import { argument, command, constant, fail, flag, option, passThrough } from "./primitives.js";
-import { createParserContext, getDocPage, getDocPageAsync, getDocPageSync, getParserSuggestRuntimeNodes, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync, unmatchedNonCliDependencySourceStateMarker } from "./parser.js";
+import { annotationWrapperRequiresSourceBindingKey, composeWrappedSourceMetadata, createParserContext, defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, getDelegatingSuggestRuntimeNodes, getDocPage, getDocPageAsync, getDocPageSync, getParserSuggestRuntimeNodes, inheritParentAnnotationsKey, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync, unmatchedNonCliDependencySourceStateMarker } from "./parser.js";
 import { DuplicateOptionError, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
 import { RunParserError, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
 
-export { DependencyRegistry, DuplicateOptionError, RunParserError, WithDefaultError, annotationKey, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createParserContext, createPendingDependencySourceState, deduplicateDocEntries, deduplicateDocFragments, defaultDependencyValueSnapshot, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, getParserSuggestRuntimeNodes, getSnapshottedDefaultDependencyValues, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, singleDefaultValue, snapshotDefaultDependencyValues, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, unmatchedNonCliDependencySourceStateMarker, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };
+export { DependencyRegistry, DuplicateOptionError, RunParserError, WithDefaultError, annotationKey, annotationWrapperRequiresSourceBindingKey, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, command, commandLine, composeWrappedSourceMetadata, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createParserContext, createPendingDependencySourceState, deduplicateDocEntries, deduplicateDocFragments, defaultDependencyValueSnapshot, defaultValues, deferredParseMarker, defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDelegatingSuggestRuntimeNodes, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, getParserSuggestRuntimeNodes, getSnapshottedDefaultDependencyValues, group, hostname, inheritParentAnnotationsKey, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, singleDefaultValue, snapshotDefaultDependencyValues, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, unmatchedNonCliDependencySourceStateMarker, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };

package/dist/modifiers.cjs

@@ -2,6 +2,7 @@ const require_annotations = require('./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_parser = require('./parser.cjs');
 
 //#region src/modifiers.ts
 function withChildExecPath(exec, segment) {
@@ -148,15 +149,23 @@ function processOptionalStyleResult(result, innerState, context) {
 *
 * @internal
 */
-function adaptShouldDeferCompletion(innerCheck) {
+function adaptShouldDeferCompletion(innerCheck, parser) {
 	return (state, exec) => {
-		if (Array.isArray(state)) return innerCheck(normalizeOptionalLikeInnerState(state, state[0]), exec);
-		if (state != null && typeof state === "object") return innerCheck(state, exec);
+		if (Array.isArray(state) || state != null && typeof state === "object") return innerCheck(normalizeOptionalLikeInnerState(state, parser.initialState, parser), exec);
 		return false;
 	};
 }
-function normalizeOptionalLikeInnerState(state, initialState) {
+function isAnnotationOnlyObjectState(state) {
+	if (state == null || typeof state !== "object" || Array.isArray(state) || require_annotations.isInjectedAnnotationWrapper(state)) return false;
+	const keys = Reflect.ownKeys(state);
+	return require_annotations.getAnnotations(state) != null && keys.length === 1 && keys[0] === require_annotations.annotationKey;
+}
+function normalizeOptionalLikeInnerState(state, initialState, parser) {
 	if (Array.isArray(state)) return require_annotations.getAnnotations(state) != null && state[0] != null && typeof state[0] === "object" ? require_annotations.inheritAnnotations(state, state[0]) : state[0];
+	if (isAnnotationOnlyObjectState(state)) {
+		if (parser != null && (parser.dependencyMetadata?.source != null || typeof parser.shouldDeferCompletion === "function")) return require_annotations.inheritAnnotations(state, initialState);
+		return initialState;
+	}
 	if (state != null && typeof state === "object") return state;
 	return initialState;
 }
@@ -175,14 +184,14 @@ function normalizeOptionalLikeInnerState(state, initialState) {
 function optional(parser) {
 	const syncParser = parser;
 	function* suggestSync(context, prefix) {
-		const innerState = normalizeOptionalLikeInnerState(context.state, syncParser.initialState);
+		const innerState = normalizeOptionalLikeInnerState(context.state, syncParser.initialState, parser);
 		yield* syncParser.suggest({
 			...context,
 			state: innerState
 		}, prefix);
 	}
 	async function* suggestAsync(context, prefix) {
-		const innerState = normalizeOptionalLikeInnerState(context.state, syncParser.initialState);
+		const innerState = normalizeOptionalLikeInnerState(context.state, syncParser.initialState, parser);
 		const suggestions = parser.suggest({
 			...context,
 			state: innerState
@@ -202,14 +211,14 @@ function optional(parser) {
 		leadingNames: parser.leadingNames,
 		acceptingAnyToken: false,
 		initialState: void 0,
-		...typeof parser.shouldDeferCompletion === "function" ? { shouldDeferCompletion: adaptShouldDeferCompletion(parser.shouldDeferCompletion.bind(parser)) } : {},
+		...typeof parser.shouldDeferCompletion === "function" ? { shouldDeferCompletion: adaptShouldDeferCompletion(parser.shouldDeferCompletion.bind(parser), parser) } : {},
 		getSuggestRuntimeNodes(state, path) {
 			if (optionalParser.dependencyMetadata?.source != null) return [{
 				path,
 				parser: optionalParser,
 				state
 			}];
-			const innerState = normalizeOptionalLikeInnerState(state, parser.initialState);
+			const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
 			return parser.getSuggestRuntimeNodes?.(innerState, path) ?? (parser.dependencyMetadata?.source != null ? [{
 				path,
 				parser,
@@ -223,7 +232,7 @@ function optional(parser) {
 			if (!Array.isArray(state)) {
 				if (typeof parser.shouldDeferCompletion === "function" && state != null && typeof state === "object") {
 					const innerComplete = () => {
-						const innerState = normalizeOptionalLikeInnerState(state, parser.initialState);
+						const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
 						const innerResult = require_mode_dispatch.dispatchByMode(parser.$mode, () => syncParser.complete(innerState, exec), async () => await parser.complete(innerState, exec));
 						return require_mode_dispatch.mapModeValue(parser.$mode, innerResult, (result) => result.success ? result : {
 							success: true,
@@ -234,7 +243,7 @@ function optional(parser) {
 				}
 				const sourceMetadata = parser.dependencyMetadata?.source;
 				if (sourceMetadata?.preservesSourceValue !== false && sourceMetadata?.getMissingSourceValue != null) {
-					const delegatedState = normalizeOptionalLikeInnerState(state, parser.initialState);
+					const delegatedState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
 					return require_mode_dispatch.dispatchByMode(parser.$mode, () => syncParser.complete(delegatedState, exec), async () => await parser.complete(delegatedState, exec));
 				}
 				return {
@@ -242,7 +251,7 @@ function optional(parser) {
 					value: void 0
 				};
 			}
-			const innerElement = normalizeOptionalLikeInnerState(state, parser.initialState);
+			const innerElement = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
 			return require_mode_dispatch.dispatchByMode(parser.$mode, () => syncParser.complete(innerElement, exec), async () => await parser.complete(innerElement, exec));
 		},
 		suggest(context, prefix) {
@@ -271,6 +280,8 @@ function optional(parser) {
 		const composed = require_dependency_metadata.composeDependencyMetadata(parser.dependencyMetadata, "optional");
 		if (composed != null) optionalParser.dependencyMetadata = composed;
 	}
+	require_parser.defineInheritedAnnotationParser(optionalParser);
+	require_parser.defineSourceBindingOnlyAnnotationCompletionParser(optionalParser);
 	return optionalParser;
 }
 /**
@@ -320,14 +331,14 @@ function withDefault(parser, defaultValue, options) {
 		}
 	};
 	function* suggestSync(context, prefix) {
-		const innerState = normalizeOptionalLikeInnerState(context.state, syncParser.initialState);
+		const innerState = normalizeOptionalLikeInnerState(context.state, syncParser.initialState, parser);
 		yield* syncParser.suggest({
 			...context,
 			state: innerState
 		}, prefix);
 	}
 	async function* suggestAsync(context, prefix) {
-		const innerState = normalizeOptionalLikeInnerState(context.state, syncParser.initialState);
+		const innerState = normalizeOptionalLikeInnerState(context.state, syncParser.initialState, parser);
 		const suggestions = parser.suggest({
 			...context,
 			state: innerState
@@ -346,14 +357,14 @@ function withDefault(parser, defaultValue, options) {
 		leadingNames: parser.leadingNames,
 		acceptingAnyToken: false,
 		initialState: void 0,
-		...typeof parser.shouldDeferCompletion === "function" ? { shouldDeferCompletion: adaptShouldDeferCompletion(parser.shouldDeferCompletion.bind(parser)) } : {},
+		...typeof parser.shouldDeferCompletion === "function" ? { shouldDeferCompletion: adaptShouldDeferCompletion(parser.shouldDeferCompletion.bind(parser), parser) } : {},
 		getSuggestRuntimeNodes(state, path) {
 			if (withDefaultParser.dependencyMetadata?.source != null) return [{
 				path,
 				parser: withDefaultParser,
 				state
 			}];
-			const innerState = normalizeOptionalLikeInnerState(state, parser.initialState);
+			const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
 			return parser.getSuggestRuntimeNodes?.(innerState, path) ?? (parser.dependencyMetadata?.source != null ? [{
 				path,
 				parser,
@@ -373,7 +384,7 @@ 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);
+					const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
 					const innerResult = require_mode_dispatch.dispatchByMode(parser.$mode, () => syncParser.complete(innerState, exec), async () => await parser.complete(innerState, exec));
 					return innerResult;
 				}
@@ -390,7 +401,7 @@ function withDefault(parser, defaultValue, options) {
 					};
 				}
 			}
-			const innerElement = normalizeOptionalLikeInnerState(state, parser.initialState);
+			const innerElement = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
 			return require_mode_dispatch.dispatchByMode(parser.$mode, () => syncParser.complete(innerElement, exec), async () => await parser.complete(innerElement, exec));
 		},
 		suggest(context, prefix) {
@@ -465,6 +476,8 @@ function withDefault(parser, defaultValue, options) {
 		} });
 		if (composed != null) withDefaultParser.dependencyMetadata = composed;
 	}
+	require_parser.defineInheritedAnnotationParser(withDefaultParser);
+	require_parser.defineSourceBindingOnlyAnnotationCompletionParser(withDefaultParser);
 	return withDefaultParser;
 }
 /**

package/dist/modifiers.js

@@ -1,7 +1,8 @@
-import { annotateFreshArray, getAnnotations, inheritAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper } from "./annotations.js";
+import { annotateFreshArray, annotationKey, getAnnotations, inheritAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper } from "./annotations.js";
 import { formatMessage, message, text } from "./message.js";
 import { dispatchByMode, dispatchIterableByMode, mapModeValue } from "./mode-dispatch.js";
 import { composeDependencyMetadata } from "./dependency-metadata.js";
+import { defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser } from "./parser.js";
 
 //#region src/modifiers.ts
 function withChildExecPath(exec, segment) {
@@ -148,15 +149,23 @@ function processOptionalStyleResult(result, innerState, context) {
 *
 * @internal
 */
-function adaptShouldDeferCompletion(innerCheck) {
+function adaptShouldDeferCompletion(innerCheck, parser) {
 	return (state, exec) => {
-		if (Array.isArray(state)) return innerCheck(normalizeOptionalLikeInnerState(state, state[0]), exec);
-		if (state != null && typeof state === "object") return innerCheck(state, exec);
+		if (Array.isArray(state) || state != null && typeof state === "object") return innerCheck(normalizeOptionalLikeInnerState(state, parser.initialState, parser), exec);
 		return false;
 	};
 }
-function normalizeOptionalLikeInnerState(state, initialState) {
+function isAnnotationOnlyObjectState(state) {
+	if (state == null || typeof state !== "object" || Array.isArray(state) || isInjectedAnnotationWrapper(state)) return false;
+	const keys = Reflect.ownKeys(state);
+	return getAnnotations(state) != null && keys.length === 1 && keys[0] === annotationKey;
+}
+function normalizeOptionalLikeInnerState(state, initialState, parser) {
 	if (Array.isArray(state)) return getAnnotations(state) != null && state[0] != null && typeof state[0] === "object" ? inheritAnnotations(state, state[0]) : state[0];
+	if (isAnnotationOnlyObjectState(state)) {
+		if (parser != null && (parser.dependencyMetadata?.source != null || typeof parser.shouldDeferCompletion === "function")) return inheritAnnotations(state, initialState);
+		return initialState;
+	}
 	if (state != null && typeof state === "object") return state;
 	return initialState;
 }
@@ -175,14 +184,14 @@ function normalizeOptionalLikeInnerState(state, initialState) {
 function optional(parser) {
 	const syncParser = parser;
 	function* suggestSync(context, prefix) {
-		const innerState = normalizeOptionalLikeInnerState(context.state, syncParser.initialState);
+		const innerState = normalizeOptionalLikeInnerState(context.state, syncParser.initialState, parser);
 		yield* syncParser.suggest({
 			...context,
 			state: innerState
 		}, prefix);
 	}
 	async function* suggestAsync(context, prefix) {
-		const innerState = normalizeOptionalLikeInnerState(context.state, syncParser.initialState);
+		const innerState = normalizeOptionalLikeInnerState(context.state, syncParser.initialState, parser);
 		const suggestions = parser.suggest({
 			...context,
 			state: innerState
@@ -202,14 +211,14 @@ function optional(parser) {
 		leadingNames: parser.leadingNames,
 		acceptingAnyToken: false,
 		initialState: void 0,
-		...typeof parser.shouldDeferCompletion === "function" ? { shouldDeferCompletion: adaptShouldDeferCompletion(parser.shouldDeferCompletion.bind(parser)) } : {},
+		...typeof parser.shouldDeferCompletion === "function" ? { shouldDeferCompletion: adaptShouldDeferCompletion(parser.shouldDeferCompletion.bind(parser), parser) } : {},
 		getSuggestRuntimeNodes(state, path) {
 			if (optionalParser.dependencyMetadata?.source != null) return [{
 				path,
 				parser: optionalParser,
 				state
 			}];
-			const innerState = normalizeOptionalLikeInnerState(state, parser.initialState);
+			const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
 			return parser.getSuggestRuntimeNodes?.(innerState, path) ?? (parser.dependencyMetadata?.source != null ? [{
 				path,
 				parser,
@@ -223,7 +232,7 @@ function optional(parser) {
 			if (!Array.isArray(state)) {
 				if (typeof parser.shouldDeferCompletion === "function" && state != null && typeof state === "object") {
 					const innerComplete = () => {
-						const innerState = normalizeOptionalLikeInnerState(state, parser.initialState);
+						const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
 						const innerResult = dispatchByMode(parser.$mode, () => syncParser.complete(innerState, exec), async () => await parser.complete(innerState, exec));
 						return mapModeValue(parser.$mode, innerResult, (result) => result.success ? result : {
 							success: true,
@@ -234,7 +243,7 @@ function optional(parser) {
 				}
 				const sourceMetadata = parser.dependencyMetadata?.source;
 				if (sourceMetadata?.preservesSourceValue !== false && sourceMetadata?.getMissingSourceValue != null) {
-					const delegatedState = normalizeOptionalLikeInnerState(state, parser.initialState);
+					const delegatedState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
 					return dispatchByMode(parser.$mode, () => syncParser.complete(delegatedState, exec), async () => await parser.complete(delegatedState, exec));
 				}
 				return {
@@ -242,7 +251,7 @@ function optional(parser) {
 					value: void 0
 				};
 			}
-			const innerElement = normalizeOptionalLikeInnerState(state, parser.initialState);
+			const innerElement = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
 			return dispatchByMode(parser.$mode, () => syncParser.complete(innerElement, exec), async () => await parser.complete(innerElement, exec));
 		},
 		suggest(context, prefix) {
@@ -271,6 +280,8 @@ function optional(parser) {
 		const composed = composeDependencyMetadata(parser.dependencyMetadata, "optional");
 		if (composed != null) optionalParser.dependencyMetadata = composed;
 	}
+	defineInheritedAnnotationParser(optionalParser);
+	defineSourceBindingOnlyAnnotationCompletionParser(optionalParser);
 	return optionalParser;
 }
 /**
@@ -320,14 +331,14 @@ function withDefault(parser, defaultValue, options) {
 		}
 	};
 	function* suggestSync(context, prefix) {
-		const innerState = normalizeOptionalLikeInnerState(context.state, syncParser.initialState);
+		const innerState = normalizeOptionalLikeInnerState(context.state, syncParser.initialState, parser);
 		yield* syncParser.suggest({
 			...context,
 			state: innerState
 		}, prefix);
 	}
 	async function* suggestAsync(context, prefix) {
-		const innerState = normalizeOptionalLikeInnerState(context.state, syncParser.initialState);
+		const innerState = normalizeOptionalLikeInnerState(context.state, syncParser.initialState, parser);
 		const suggestions = parser.suggest({
 			...context,
 			state: innerState
@@ -346,14 +357,14 @@ function withDefault(parser, defaultValue, options) {
 		leadingNames: parser.leadingNames,
 		acceptingAnyToken: false,
 		initialState: void 0,
-		...typeof parser.shouldDeferCompletion === "function" ? { shouldDeferCompletion: adaptShouldDeferCompletion(parser.shouldDeferCompletion.bind(parser)) } : {},
+		...typeof parser.shouldDeferCompletion === "function" ? { shouldDeferCompletion: adaptShouldDeferCompletion(parser.shouldDeferCompletion.bind(parser), parser) } : {},
 		getSuggestRuntimeNodes(state, path) {
 			if (withDefaultParser.dependencyMetadata?.source != null) return [{
 				path,
 				parser: withDefaultParser,
 				state
 			}];
-			const innerState = normalizeOptionalLikeInnerState(state, parser.initialState);
+			const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
 			return parser.getSuggestRuntimeNodes?.(innerState, path) ?? (parser.dependencyMetadata?.source != null ? [{
 				path,
 				parser,
@@ -373,7 +384,7 @@ 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);
+					const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
 					const innerResult = dispatchByMode(parser.$mode, () => syncParser.complete(innerState, exec), async () => await parser.complete(innerState, exec));
 					return innerResult;
 				}
@@ -390,7 +401,7 @@ function withDefault(parser, defaultValue, options) {
 					};
 				}
 			}
-			const innerElement = normalizeOptionalLikeInnerState(state, parser.initialState);
+			const innerElement = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
 			return dispatchByMode(parser.$mode, () => syncParser.complete(innerElement, exec), async () => await parser.complete(innerElement, exec));
 		},
 		suggest(context, prefix) {
@@ -465,6 +476,8 @@ function withDefault(parser, defaultValue, options) {
 		} });
 		if (composed != null) withDefaultParser.dependencyMetadata = composed;
 	}
+	defineInheritedAnnotationParser(withDefaultParser);
+	defineSourceBindingOnlyAnnotationCompletionParser(withDefaultParser);
 	return withDefaultParser;
 }
 /**