@optique/core 1.0.0-dev.1736 → 1.0.0-dev.1739

package/dist/constructs.cjs

@@ -5,7 +5,6 @@ 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_modifiers = require('./modifiers.cjs');
 const require_suggestion = require('./suggestion.cjs');
 const require_usage_internals = require('./usage-internals.cjs');
 const require_parser = require('./parser.cjs');
@@ -1765,7 +1764,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			for (const [field, parser] of parserPairs) {
 				if (consumedFields.has(field)) continue;
 				const typedParser = parser;
-				if (parser.leadingNames.size > 0 || typedParser.acceptingAnyToken || Reflect.get(parser, require_modifiers.optionalStyleWrapperKey) === true) continue;
+				if (parser.leadingNames.size > 0 || typedParser.acceptingAnyToken) continue;
 				const fieldState = getFieldState(field, parser);
 				const result = typedParser.parse(withChildContext(currentContext, field, fieldState, parser));
 				if (result.success && result.consumed.length === 0 && result.next.state !== fieldState) {
@@ -1862,7 +1861,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			const getFieldState = createFieldStateGetter(currentContext.state, getObjectParseChildState);
 			for (const [field, parser] of parserPairs) {
 				if (consumedFields.has(field)) continue;
-				if (parser.leadingNames.size > 0 || parser.acceptingAnyToken || Reflect.get(parser, require_modifiers.optionalStyleWrapperKey) === true) continue;
+				if (parser.leadingNames.size > 0 || parser.acceptingAnyToken) continue;
 				const fieldState = getFieldState(field, parser);
 				const resultOrPromise = parser.parse(withChildContext(currentContext, field, fieldState, parser));
 				const result = await resultOrPromise;

package/dist/constructs.js

@@ -5,7 +5,6 @@ import { validateLabel } from "./validate.js";
 import { extractArgumentMetavars, extractCommandNames, extractOptionNames, isDocHidden, mergeHidden } from "./usage.js";
 import { deduplicateDocFragments } from "./doc.js";
 import { dispatchByMode, dispatchIterableByMode } from "./mode-dispatch.js";
-import { optionalStyleWrapperKey } from "./modifiers.js";
 import { DEFAULT_FIND_SIMILAR_OPTIONS, createErrorWithSuggestions, createSuggestionMessage, deduplicateSuggestions, findSimilar } from "./suggestion.js";
 import { collectLeadingCandidates } from "./usage-internals.js";
 import { defineInheritedAnnotationParser, getParserSuggestRuntimeNodes, inheritParentAnnotationsKey, unmatchedNonCliDependencySourceStateMarker } from "./parser.js";
@@ -1765,7 +1764,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			for (const [field, parser] of parserPairs) {
 				if (consumedFields.has(field)) continue;
 				const typedParser = parser;
-				if (parser.leadingNames.size > 0 || typedParser.acceptingAnyToken || Reflect.get(parser, optionalStyleWrapperKey) === true) continue;
+				if (parser.leadingNames.size > 0 || typedParser.acceptingAnyToken) continue;
 				const fieldState = getFieldState(field, parser);
 				const result = typedParser.parse(withChildContext(currentContext, field, fieldState, parser));
 				if (result.success && result.consumed.length === 0 && result.next.state !== fieldState) {
@@ -1862,7 +1861,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			const getFieldState = createFieldStateGetter(currentContext.state, getObjectParseChildState);
 			for (const [field, parser] of parserPairs) {
 				if (consumedFields.has(field)) continue;
-				if (parser.leadingNames.size > 0 || parser.acceptingAnyToken || Reflect.get(parser, optionalStyleWrapperKey) === true) continue;
+				if (parser.leadingNames.size > 0 || parser.acceptingAnyToken) continue;
 				const fieldState = getFieldState(field, parser);
 				const resultOrPromise = parser.parse(withChildContext(currentContext, field, fieldState, parser));
 				const result = await resultOrPromise;

package/dist/index.cjs

@@ -117,7 +117,6 @@ exports.option = require_primitives.option;
 exports.optionName = require_message.optionName;
 exports.optionNames = require_message.optionNames;
 exports.optional = require_modifiers.optional;
-exports.optionalStyleWrapperKey = require_modifiers.optionalStyleWrapperKey;
 exports.or = require_constructs.or;
 exports.parse = require_parser.parse;
 exports.parseAsync = require_parser.parseAsync;

package/dist/index.d.cts

@@ -5,11 +5,11 @@ import { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, Usa
 import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage, isDocEntryHidden } from "./doc.cjs";
 import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, DeferredMap, DomainOptions, EmailOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, MacAddressOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, domain, email, float, hostname, integer, ip, ipv4, ipv6, isValueParser, locale, macAddress, port, portRange, socketAddress, string, url, uuid } from "./valueparser.cjs";
 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, optionalStyleWrapperKey, withDefault } from "./modifiers.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, 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, 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, optionalStyleWrapperKey, 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

@@ -5,11 +5,11 @@ import { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, Usa
 import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage, isDocEntryHidden } from "./doc.js";
 import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, DeferredMap, DomainOptions, EmailOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, MacAddressOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, 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 { 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, optionalStyleWrapperKey, withDefault } from "./modifiers.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, 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, 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, optionalStyleWrapperKey, 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

@@ -4,7 +4,7 @@ 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 { WithDefaultError, map, multiple, nonEmpty, optional, optionalStyleWrapperKey, withDefault } from "./modifiers.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";
 import { argument, command, constant, fail, flag, option, passThrough } from "./primitives.js";
@@ -12,4 +12,4 @@ import { annotationWrapperRequiresSourceBindingKey, composeWrappedSourceMetadata
 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, 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, optionalStyleWrapperKey, 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

@@ -5,15 +5,6 @@ const require_dependency_metadata = require('./dependency-metadata.cjs');
 const require_parser = require('./parser.cjs');
 
 //#region src/modifiers.ts
-/**
-* Internal marker for wrappers that should be skipped by `object()`'s
-* zero-consumption pass.  Set on `optional()`, `withDefault()`, and
-* `prompt()`, since these wrappers have their own completion semantics
-* that should not be short-circuited during parse.
-*
-* @internal
-*/
-const optionalStyleWrapperKey = Symbol.for("@optique/core/optionalStyleWrapper");
 function withChildExecPath(exec, segment) {
 	if (exec == null) return void 0;
 	return {
@@ -89,6 +80,28 @@ function isPromiseLike(value) {
 	return value != null && (typeof value === "object" || typeof value === "function") && "then" in value && typeof value.then === "function";
 }
 /**
+* Computes the inner state to pass through to the wrapped parser inside
+* {@link optional} / {@link withDefault}.  When the outer state is an
+* array, the inner state is `state[0]`.  Otherwise — including the
+* common case where `optional()` sits at top level and the outer state
+* is either `undefined` or an annotation wrapper from `parseOptionalLike`
+* / `parse({ annotations })` — we use the wrapped parser's
+* `initialState`, propagating annotations from the outer state so that
+* source-binding wrappers under `optional()` / `withDefault()` (e.g.,
+* `bindEnv()` / `bindConfig()`) can resolve their fallbacks.
+*
+* @internal
+*/
+function deriveOptionalInnerParseState(outerState, parser) {
+	if (Array.isArray(outerState)) return outerState[0];
+	const initial = parser.initialState;
+	if (outerState != null && typeof outerState === "object") {
+		const annotations = require_annotations.getAnnotations(outerState);
+		if (annotations != null) return require_annotations.injectAnnotations(initial, annotations);
+	}
+	return initial;
+}
+/**
 * Internal helper for optional-style parsing logic shared by optional()
 * and withDefault(). Handles the common pattern of:
 * - Unwrapping optional state to inner parser state
@@ -97,7 +110,7 @@ function isPromiseLike(value) {
 * @internal
 */
 function parseOptionalStyleSync(context, parser) {
-	const innerState = Array.isArray(context.state) ? context.state[0] : parser.initialState;
+	const innerState = deriveOptionalInnerParseState(context.state, parser);
 	const result = parser.parse({
 		...context,
 		state: innerState
@@ -109,7 +122,7 @@ function parseOptionalStyleSync(context, parser) {
 * @internal
 */
 async function parseOptionalStyleAsync(context, parser) {
-	const innerState = Array.isArray(context.state) ? context.state[0] : parser.initialState;
+	const innerState = deriveOptionalInnerParseState(context.state, parser);
 	const result = await parser.parse({
 		...context,
 		state: innerState
@@ -213,7 +226,7 @@ function optional(parser) {
 		$mode: parser.$mode,
 		$valueType: [],
 		$stateType: [],
-		[optionalStyleWrapperKey]: true,
+		...parser[require_parser.unmatchedNonCliDependencySourceStateMarker] === true ? { [require_parser.unmatchedNonCliDependencySourceStateMarker]: true } : {},
 		placeholder: void 0,
 		priority: parser.priority,
 		usage: [{
@@ -242,22 +255,26 @@ function optional(parser) {
 		},
 		complete(state, exec) {
 			if (!Array.isArray(state)) {
+				const delegateToInner = (resolvedInnerState) => {
+					const innerResult = require_mode_dispatch.dispatchByMode(parser.$mode, () => syncParser.complete(resolvedInnerState, exec), async () => await parser.complete(resolvedInnerState, exec));
+					return require_mode_dispatch.mapModeValue(parser.$mode, innerResult, (result) => result.success ? result : {
+						success: true,
+						value: void 0
+					});
+				};
 				if (typeof parser.shouldDeferCompletion === "function" && state != null && typeof state === "object") {
-					const innerComplete = () => {
-						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,
-							value: void 0
-						});
-					};
-					return innerComplete();
+					const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
+					return delegateToInner(innerState);
 				}
 				const sourceMetadata = parser.dependencyMetadata?.source;
 				if (sourceMetadata?.preservesSourceValue !== false && sourceMetadata?.getMissingSourceValue != null) {
 					const delegatedState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
 					return require_mode_dispatch.dispatchByMode(parser.$mode, () => syncParser.complete(delegatedState, exec), async () => await parser.complete(delegatedState, exec));
 				}
+				if (parser[require_parser.unmatchedNonCliDependencySourceStateMarker] === true && state != null && typeof state === "object") {
+					const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
+					return delegateToInner(innerState);
+				}
 				return {
 					success: true,
 					value: void 0
@@ -361,7 +378,7 @@ function withDefault(parser, defaultValue, options) {
 		$mode: parser.$mode,
 		$valueType: [],
 		$stateType: [],
-		[optionalStyleWrapperKey]: true,
+		...parser[require_parser.unmatchedNonCliDependencySourceStateMarker] === true ? { [require_parser.unmatchedNonCliDependencySourceStateMarker]: true } : {},
 		priority: parser.priority,
 		usage: [{
 			type: "optional",
@@ -401,6 +418,25 @@ function withDefault(parser, defaultValue, options) {
 					const innerResult = require_mode_dispatch.dispatchByMode(parser.$mode, () => syncParser.complete(innerState, exec), async () => await parser.complete(innerState, exec));
 					return innerResult;
 				}
+				if (parser[require_parser.unmatchedNonCliDependencySourceStateMarker] === true && state != null && typeof state === "object") {
+					const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
+					const innerResult = require_mode_dispatch.dispatchByMode(parser.$mode, () => syncParser.complete(innerState, exec), async () => await parser.complete(innerState, exec));
+					const handleInnerResult = (result) => {
+						if (result.success && result.value !== void 0) return result;
+						try {
+							return {
+								success: true,
+								value: evaluateDefault()
+							};
+						} catch (error) {
+							return {
+								success: false,
+								error: error instanceof WithDefaultError ? error.errorMessage : require_message.message`${require_message.text(String(error))}`
+							};
+						}
+					};
+					return require_mode_dispatch.mapModeValue(parser.$mode, innerResult, handleInnerResult);
+				}
 				try {
 					const value = evaluateDefault();
 					return {
@@ -1221,5 +1257,4 @@ exports.map = map;
 exports.multiple = multiple;
 exports.nonEmpty = nonEmpty;
 exports.optional = optional;
-exports.optionalStyleWrapperKey = optionalStyleWrapperKey;
 exports.withDefault = withDefault;

package/dist/modifiers.d.cts

@@ -3,15 +3,6 @@ import { Mode, Parser } from "./parser.cjs";
 
 //#region src/modifiers.d.ts
 
-/**
- * Internal marker for wrappers that should be skipped by `object()`'s
- * zero-consumption pass.  Set on `optional()`, `withDefault()`, and
- * `prompt()`, since these wrappers have their own completion semantics
- * that should not be short-circuited during parse.
- *
- * @internal
- */
-declare const optionalStyleWrapperKey: unique symbol;
 /**
  * Creates a parser that makes another parser optional, allowing it to succeed
  * without consuming input if the wrapped parser fails to match.
@@ -282,4 +273,4 @@ declare function multiple<M extends Mode, TValue, TState>(parser: Parser<M, TVal
  */
 declare function nonEmpty<M extends Mode, T, TState>(parser: Parser<M, T, TState>): Parser<M, T, TState>;
 //#endregion
-export { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, nonEmpty, optional, optionalStyleWrapperKey, withDefault };
+export { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, nonEmpty, optional, withDefault };

package/dist/modifiers.d.ts

@@ -3,15 +3,6 @@ import { Mode, Parser } from "./parser.js";
 
 //#region src/modifiers.d.ts
 
-/**
- * Internal marker for wrappers that should be skipped by `object()`'s
- * zero-consumption pass.  Set on `optional()`, `withDefault()`, and
- * `prompt()`, since these wrappers have their own completion semantics
- * that should not be short-circuited during parse.
- *
- * @internal
- */
-declare const optionalStyleWrapperKey: unique symbol;
 /**
  * Creates a parser that makes another parser optional, allowing it to succeed
  * without consuming input if the wrapped parser fails to match.
@@ -282,4 +273,4 @@ declare function multiple<M extends Mode, TValue, TState>(parser: Parser<M, TVal
  */
 declare function nonEmpty<M extends Mode, T, TState>(parser: Parser<M, T, TState>): Parser<M, T, TState>;
 //#endregion
-export { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, nonEmpty, optional, optionalStyleWrapperKey, withDefault };
+export { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, nonEmpty, optional, withDefault };

package/dist/modifiers.js

@@ -1,19 +1,10 @@
-import { annotateFreshArray, annotationKey, getAnnotations, inheritAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper } from "./annotations.js";
+import { annotateFreshArray, annotationKey, getAnnotations, inheritAnnotations, injectAnnotations, 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";
+import { defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, unmatchedNonCliDependencySourceStateMarker } from "./parser.js";
 
 //#region src/modifiers.ts
-/**
-* Internal marker for wrappers that should be skipped by `object()`'s
-* zero-consumption pass.  Set on `optional()`, `withDefault()`, and
-* `prompt()`, since these wrappers have their own completion semantics
-* that should not be short-circuited during parse.
-*
-* @internal
-*/
-const optionalStyleWrapperKey = Symbol.for("@optique/core/optionalStyleWrapper");
 function withChildExecPath(exec, segment) {
 	if (exec == null) return void 0;
 	return {
@@ -89,6 +80,28 @@ function isPromiseLike(value) {
 	return value != null && (typeof value === "object" || typeof value === "function") && "then" in value && typeof value.then === "function";
 }
 /**
+* Computes the inner state to pass through to the wrapped parser inside
+* {@link optional} / {@link withDefault}.  When the outer state is an
+* array, the inner state is `state[0]`.  Otherwise — including the
+* common case where `optional()` sits at top level and the outer state
+* is either `undefined` or an annotation wrapper from `parseOptionalLike`
+* / `parse({ annotations })` — we use the wrapped parser's
+* `initialState`, propagating annotations from the outer state so that
+* source-binding wrappers under `optional()` / `withDefault()` (e.g.,
+* `bindEnv()` / `bindConfig()`) can resolve their fallbacks.
+*
+* @internal
+*/
+function deriveOptionalInnerParseState(outerState, parser) {
+	if (Array.isArray(outerState)) return outerState[0];
+	const initial = parser.initialState;
+	if (outerState != null && typeof outerState === "object") {
+		const annotations = getAnnotations(outerState);
+		if (annotations != null) return injectAnnotations(initial, annotations);
+	}
+	return initial;
+}
+/**
 * Internal helper for optional-style parsing logic shared by optional()
 * and withDefault(). Handles the common pattern of:
 * - Unwrapping optional state to inner parser state
@@ -97,7 +110,7 @@ function isPromiseLike(value) {
 * @internal
 */
 function parseOptionalStyleSync(context, parser) {
-	const innerState = Array.isArray(context.state) ? context.state[0] : parser.initialState;
+	const innerState = deriveOptionalInnerParseState(context.state, parser);
 	const result = parser.parse({
 		...context,
 		state: innerState
@@ -109,7 +122,7 @@ function parseOptionalStyleSync(context, parser) {
 * @internal
 */
 async function parseOptionalStyleAsync(context, parser) {
-	const innerState = Array.isArray(context.state) ? context.state[0] : parser.initialState;
+	const innerState = deriveOptionalInnerParseState(context.state, parser);
 	const result = await parser.parse({
 		...context,
 		state: innerState
@@ -213,7 +226,7 @@ function optional(parser) {
 		$mode: parser.$mode,
 		$valueType: [],
 		$stateType: [],
-		[optionalStyleWrapperKey]: true,
+		...parser[unmatchedNonCliDependencySourceStateMarker] === true ? { [unmatchedNonCliDependencySourceStateMarker]: true } : {},
 		placeholder: void 0,
 		priority: parser.priority,
 		usage: [{
@@ -242,22 +255,26 @@ function optional(parser) {
 		},
 		complete(state, exec) {
 			if (!Array.isArray(state)) {
+				const delegateToInner = (resolvedInnerState) => {
+					const innerResult = dispatchByMode(parser.$mode, () => syncParser.complete(resolvedInnerState, exec), async () => await parser.complete(resolvedInnerState, exec));
+					return mapModeValue(parser.$mode, innerResult, (result) => result.success ? result : {
+						success: true,
+						value: void 0
+					});
+				};
 				if (typeof parser.shouldDeferCompletion === "function" && state != null && typeof state === "object") {
-					const innerComplete = () => {
-						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,
-							value: void 0
-						});
-					};
-					return innerComplete();
+					const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
+					return delegateToInner(innerState);
 				}
 				const sourceMetadata = parser.dependencyMetadata?.source;
 				if (sourceMetadata?.preservesSourceValue !== false && sourceMetadata?.getMissingSourceValue != null) {
 					const delegatedState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
 					return dispatchByMode(parser.$mode, () => syncParser.complete(delegatedState, exec), async () => await parser.complete(delegatedState, exec));
 				}
+				if (parser[unmatchedNonCliDependencySourceStateMarker] === true && state != null && typeof state === "object") {
+					const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
+					return delegateToInner(innerState);
+				}
 				return {
 					success: true,
 					value: void 0
@@ -361,7 +378,7 @@ function withDefault(parser, defaultValue, options) {
 		$mode: parser.$mode,
 		$valueType: [],
 		$stateType: [],
-		[optionalStyleWrapperKey]: true,
+		...parser[unmatchedNonCliDependencySourceStateMarker] === true ? { [unmatchedNonCliDependencySourceStateMarker]: true } : {},
 		priority: parser.priority,
 		usage: [{
 			type: "optional",
@@ -401,6 +418,25 @@ function withDefault(parser, defaultValue, options) {
 					const innerResult = dispatchByMode(parser.$mode, () => syncParser.complete(innerState, exec), async () => await parser.complete(innerState, exec));
 					return innerResult;
 				}
+				if (parser[unmatchedNonCliDependencySourceStateMarker] === true && state != null && typeof state === "object") {
+					const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
+					const innerResult = dispatchByMode(parser.$mode, () => syncParser.complete(innerState, exec), async () => await parser.complete(innerState, exec));
+					const handleInnerResult = (result) => {
+						if (result.success && result.value !== void 0) return result;
+						try {
+							return {
+								success: true,
+								value: evaluateDefault()
+							};
+						} catch (error) {
+							return {
+								success: false,
+								error: error instanceof WithDefaultError ? error.errorMessage : message`${text(String(error))}`
+							};
+						}
+					};
+					return mapModeValue(parser.$mode, innerResult, handleInnerResult);
+				}
 				try {
 					const value = evaluateDefault();
 					return {
@@ -1216,4 +1252,4 @@ function nonEmpty(parser) {
 }
 
 //#endregion
-export { WithDefaultError, map, multiple, nonEmpty, optional, optionalStyleWrapperKey, withDefault };
+export { WithDefaultError, map, multiple, nonEmpty, optional, withDefault };

package/dist/parser.cjs

@@ -731,7 +731,6 @@ exports.nonEmpty = require_modifiers.nonEmpty;
 exports.object = require_constructs.object;
 exports.option = require_primitives.option;
 exports.optional = require_modifiers.optional;
-exports.optionalStyleWrapperKey = require_modifiers.optionalStyleWrapperKey;
 exports.or = require_constructs.or;
 exports.parse = parse;
 exports.parseAsync = parseAsync;

package/dist/parser.d.cts

@@ -8,7 +8,7 @@ import { ParserDependencyMetadata } from "./dependency-metadata.cjs";
 import { DependencyRuntimeContext, RuntimeNode } from "./dependency-runtime.cjs";
 import { InputTrace } from "./input-trace.cjs";
 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, optionalStyleWrapperKey, withDefault } from "./modifiers.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";
 
 //#region src/parser.d.ts
@@ -934,4 +934,4 @@ declare function getDocPage(parser: Parser<"sync", unknown, unknown>, argsOrOpti
 declare function getDocPage(parser: Parser<"async", unknown, unknown>, argsOrOptions?: readonly string[] | ParseOptions, options?: ParseOptions): Promise<DocPage | undefined>;
 declare function getDocPage<M extends Mode>(parser: Parser<M, unknown, unknown>, argsOrOptions?: readonly string[] | ParseOptions, options?: ParseOptions): ModeValue<M, DocPage | undefined>;
 //#endregion
-export { ArgumentErrorOptions, ArgumentOptions, CombineModes, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocState, DuplicateOptionError, ExecutionContext, ExecutionPhase, FlagErrorOptions, FlagOptions, GroupOptions, InferMode, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OptionState, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, annotationWrapperRequiresSourceBindingKey, argument, command, composeWrappedSourceMetadata, concat, conditional, constant, createParserContext, defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, fail, flag, getDelegatingSuggestRuntimeNodes, getDocPage, getDocPageAsync, getDocPageSync, getParserSuggestRuntimeNodes, group, inheritParentAnnotationsKey, longestMatch, map, merge, multiple, nonEmpty, object, option, optional, optionalStyleWrapperKey, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, unmatchedNonCliDependencySourceStateMarker, withDefault };
+export { ArgumentErrorOptions, ArgumentOptions, CombineModes, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocState, DuplicateOptionError, ExecutionContext, ExecutionPhase, FlagErrorOptions, FlagOptions, GroupOptions, InferMode, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OptionState, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, annotationWrapperRequiresSourceBindingKey, argument, command, composeWrappedSourceMetadata, concat, conditional, constant, createParserContext, defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, fail, flag, getDelegatingSuggestRuntimeNodes, getDocPage, getDocPageAsync, getDocPageSync, getParserSuggestRuntimeNodes, group, inheritParentAnnotationsKey, longestMatch, map, merge, multiple, nonEmpty, object, option, optional, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, unmatchedNonCliDependencySourceStateMarker, withDefault };

package/dist/parser.d.ts

@@ -8,7 +8,7 @@ import { ParserDependencyMetadata } from "./dependency-metadata.js";
 import { DependencyRuntimeContext, RuntimeNode } from "./dependency-runtime.js";
 import { InputTrace } from "./input-trace.js";
 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, optionalStyleWrapperKey, withDefault } from "./modifiers.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";
 
 //#region src/parser.d.ts
@@ -934,4 +934,4 @@ declare function getDocPage(parser: Parser<"sync", unknown, unknown>, argsOrOpti
 declare function getDocPage(parser: Parser<"async", unknown, unknown>, argsOrOptions?: readonly string[] | ParseOptions, options?: ParseOptions): Promise<DocPage | undefined>;
 declare function getDocPage<M extends Mode>(parser: Parser<M, unknown, unknown>, argsOrOptions?: readonly string[] | ParseOptions, options?: ParseOptions): ModeValue<M, DocPage | undefined>;
 //#endregion
-export { ArgumentErrorOptions, ArgumentOptions, CombineModes, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocState, DuplicateOptionError, ExecutionContext, ExecutionPhase, FlagErrorOptions, FlagOptions, GroupOptions, InferMode, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OptionState, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, annotationWrapperRequiresSourceBindingKey, argument, command, composeWrappedSourceMetadata, concat, conditional, constant, createParserContext, defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, fail, flag, getDelegatingSuggestRuntimeNodes, getDocPage, getDocPageAsync, getDocPageSync, getParserSuggestRuntimeNodes, group, inheritParentAnnotationsKey, longestMatch, map, merge, multiple, nonEmpty, object, option, optional, optionalStyleWrapperKey, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, unmatchedNonCliDependencySourceStateMarker, withDefault };
+export { ArgumentErrorOptions, ArgumentOptions, CombineModes, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocState, DuplicateOptionError, ExecutionContext, ExecutionPhase, FlagErrorOptions, FlagOptions, GroupOptions, InferMode, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OptionState, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, annotationWrapperRequiresSourceBindingKey, argument, command, composeWrappedSourceMetadata, concat, conditional, constant, createParserContext, defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, fail, flag, getDelegatingSuggestRuntimeNodes, getDocPage, getDocPageAsync, getDocPageSync, getParserSuggestRuntimeNodes, group, inheritParentAnnotationsKey, longestMatch, map, merge, multiple, nonEmpty, object, option, optional, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, unmatchedNonCliDependencySourceStateMarker, withDefault };

package/dist/parser.js

@@ -4,7 +4,7 @@ import { cloneUsage, normalizeUsage } from "./usage.js";
 import { cloneDocEntry, isDocEntryHidden } from "./doc.js";
 import { dispatchByMode } from "./mode-dispatch.js";
 import { createInputTrace } from "./input-trace.js";
-import { WithDefaultError, map, multiple, nonEmpty, optional, optionalStyleWrapperKey, withDefault } from "./modifiers.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";
@@ -702,4 +702,4 @@ function buildDocPage(parser, context, args) {
 }
 
 //#endregion
-export { DuplicateOptionError, WithDefaultError, annotationWrapperRequiresSourceBindingKey, argument, command, composeWrappedSourceMetadata, concat, conditional, constant, createParserContext, defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, fail, flag, getDelegatingSuggestRuntimeNodes, getDocPage, getDocPageAsync, getDocPageSync, getParserSuggestRuntimeNodes, group, inheritParentAnnotationsKey, longestMatch, map, merge, multiple, nonEmpty, object, option, optional, optionalStyleWrapperKey, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, unmatchedNonCliDependencySourceStateMarker, withDefault };
+export { DuplicateOptionError, WithDefaultError, annotationWrapperRequiresSourceBindingKey, argument, command, composeWrappedSourceMetadata, concat, conditional, constant, createParserContext, defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, fail, flag, getDelegatingSuggestRuntimeNodes, getDocPage, getDocPageAsync, getDocPageSync, getParserSuggestRuntimeNodes, group, inheritParentAnnotationsKey, longestMatch, map, merge, multiple, nonEmpty, object, option, optional, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, unmatchedNonCliDependencySourceStateMarker, withDefault };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.1736+79c0851e",
+  "version": "1.0.0-dev.1739+5fe92e35",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",