@optique/core 1.0.0-dev.1828 → 1.0.0-dev.1841

package/dist/context.d.cts

@@ -12,6 +12,46 @@ import { Annotations } from "./annotations.cjs";
  * @since 1.0.0
  */
 type SourceContextPhase = "single-pass" | "two-pass";
+/**
+ * Phase-1 annotation collection request for a {@link SourceContext}.
+ *
+ * @since 1.0.0
+ */
+interface SourceContextPhase1Request {
+  /**
+   * Indicates that the runner is collecting initial annotations before the
+   * first parse pass.
+   */
+  readonly phase: "phase1";
+}
+/**
+ * Phase-2 annotation collection request for a {@link SourceContext}.
+ *
+ * @since 1.0.0
+ */
+interface SourceContextPhase2Request {
+  /**
+   * Indicates that the runner is recollecting annotations after a usable
+   * first parse pass.
+   */
+  readonly phase: "phase2";
+  /**
+   * Parsed result from the first pass, or a best-effort partial value
+   * extracted from parser state when the first pass reached a usable
+   * intermediate state but did not complete successfully.
+   */
+  readonly parsed: unknown;
+}
+/**
+ * Request object passed to {@link SourceContext.getAnnotations} and
+ * {@link SourceContext.getInternalAnnotations}.
+ *
+ * This makes phase 1 and phase 2 explicit so successful parser results of
+ * `undefined` are no longer ambiguous.
+ *
+ * @since 1.0.0
+ */
+type SourceContextRequest = SourceContextPhase1Request | SourceContextPhase2Request;
 /**
  * Brand symbol for ParserValuePlaceholder type.
  * @internal
@@ -128,10 +168,11 @@ interface SourceContext<TRequiredOptions = void> {
    * This method is called during phase 1 for every context and during phase 2
    * only for `two-pass` contexts:
    *
-   * 1. *Phase 1*: `parsed` is `undefined`.
-   * 2. *Phase 2*: `parsed` contains the first pass result, or a best-effort
-   *    partial value extracted from parser state when the first pass reached a
-   *    usable intermediate state but still did not complete successfully.
+   * 1. *Phase 1*: `request.phase` is `"phase1"`.
+   * 2. *Phase 2*: `request.phase` is `"phase2"` and `request.parsed`
+   *    contains the first pass result, or a best-effort partial value
+   *    extracted from parser state when the first pass reached a usable
+   *    intermediate state but still did not complete successfully.
    *    Deferred or otherwise unresolved fields may be `undefined`. This
    *    second return value is treated as the context's final annotation
    *    snapshot for the second parse pass, replacing that context's phase-one
@@ -139,9 +180,15 @@ interface SourceContext<TRequiredOptions = void> {
    *    second call is skipped and the original parse failure is reported
    *    instead.
    *
-   * @param parsed Optional parsed result from a previous parse pass.
-   *               `single-pass` contexts can ignore this parameter.
-   *               `two-pass` contexts use this to extract or refine data.
+   * Omitting the request is treated as a manual phase-1 call for
+   * convenience, so `context.getAnnotations()` continues to work for
+   * simple one-shot annotation reads.
+   *
+   * @param request Optional request describing which collection phase the
+   *                runner is performing. `single-pass` contexts can ignore
+   *                this parameter. `two-pass` contexts should branch on
+   *                `request.phase` rather than inferring phases from
+   *                `request.parsed`.
    * @param options Optional context-required options provided by the caller
    *               of `runWith()`. These are the options declared via the
    *               `TRequiredOptions` type parameter.
@@ -150,36 +197,22 @@ interface SourceContext<TRequiredOptions = void> {
    *          during phase 1. Can be a Promise for async operations (e.g.,
    *          loading config files).
    */
-  getAnnotations(parsed?: unknown, options?: unknown): Promise<Annotations> | Annotations;
+  getAnnotations(request?: SourceContextRequest, options?: unknown): Promise<Annotations> | Annotations;
   /**
    * Optional hook to provide additional internal annotations during
    * annotation collection.  Called after {@link getAnnotations} with the
-   * same parsed value and the annotations returned by `getAnnotations()`.
+   * same request object and the annotations returned by `getAnnotations()`.
    *
    * Returns additional annotations to merge, or `undefined` to add nothing.
    * This enables contexts to inject phase-specific markers without
    * exposing them through the primary `getAnnotations()` API.
    *
-   * @param parsed The parsed result from a previous parse pass, or
-   *               `undefined` during the first pass.
+   * @param request The request describing the current collection phase.
    * @param annotations The annotations returned by `getAnnotations()`.
    * @returns Additional annotations to merge, or `undefined`.
    * @since 1.0.0
    */
-  getInternalAnnotations?(parsed: unknown, annotations: Annotations): Annotations | undefined;
-  /**
-   * Optional hook to transform the parsed value before it is passed to
-   * {@link getAnnotations} during phase-2 annotation collection.
-   *
-   * This allows contexts to distinguish between "parsed value was
-   * `undefined`" and "no parse happened yet" by wrapping `undefined`
-   * values with a context-private marker.
-   *
-   * @param parsed The parsed value to finalize.
-   * @returns The finalized parsed value.
-   * @since 1.0.0
-   */
-  finalizeParsed?(parsed: unknown): unknown;
+  getInternalAnnotations?(request: SourceContextRequest, annotations: Annotations): Annotations | undefined;
   /**
    * Optional synchronous cleanup method.  Called by `runWith()` and
    * `runWithSync()` after parsing completes.  In `runWith()`, this happens
@@ -199,4 +232,4 @@ interface SourceContext<TRequiredOptions = void> {
   [Symbol.asyncDispose]?(): void | PromiseLike<void>;
 }
 //#endregion
-export { type Annotations, ParserValuePlaceholder, SourceContext, SourceContextPhase };
+export { type Annotations, ParserValuePlaceholder, SourceContext, SourceContextPhase, SourceContextPhase1Request, SourceContextPhase2Request, SourceContextRequest };

package/dist/context.d.ts

@@ -12,6 +12,46 @@ import { Annotations } from "./annotations.js";
  * @since 1.0.0
  */
 type SourceContextPhase = "single-pass" | "two-pass";
+/**
+ * Phase-1 annotation collection request for a {@link SourceContext}.
+ *
+ * @since 1.0.0
+ */
+interface SourceContextPhase1Request {
+  /**
+   * Indicates that the runner is collecting initial annotations before the
+   * first parse pass.
+   */
+  readonly phase: "phase1";
+}
+/**
+ * Phase-2 annotation collection request for a {@link SourceContext}.
+ *
+ * @since 1.0.0
+ */
+interface SourceContextPhase2Request {
+  /**
+   * Indicates that the runner is recollecting annotations after a usable
+   * first parse pass.
+   */
+  readonly phase: "phase2";
+  /**
+   * Parsed result from the first pass, or a best-effort partial value
+   * extracted from parser state when the first pass reached a usable
+   * intermediate state but did not complete successfully.
+   */
+  readonly parsed: unknown;
+}
+/**
+ * Request object passed to {@link SourceContext.getAnnotations} and
+ * {@link SourceContext.getInternalAnnotations}.
+ *
+ * This makes phase 1 and phase 2 explicit so successful parser results of
+ * `undefined` are no longer ambiguous.
+ *
+ * @since 1.0.0
+ */
+type SourceContextRequest = SourceContextPhase1Request | SourceContextPhase2Request;
 /**
  * Brand symbol for ParserValuePlaceholder type.
  * @internal
@@ -128,10 +168,11 @@ interface SourceContext<TRequiredOptions = void> {
    * This method is called during phase 1 for every context and during phase 2
    * only for `two-pass` contexts:
    *
-   * 1. *Phase 1*: `parsed` is `undefined`.
-   * 2. *Phase 2*: `parsed` contains the first pass result, or a best-effort
-   *    partial value extracted from parser state when the first pass reached a
-   *    usable intermediate state but still did not complete successfully.
+   * 1. *Phase 1*: `request.phase` is `"phase1"`.
+   * 2. *Phase 2*: `request.phase` is `"phase2"` and `request.parsed`
+   *    contains the first pass result, or a best-effort partial value
+   *    extracted from parser state when the first pass reached a usable
+   *    intermediate state but still did not complete successfully.
    *    Deferred or otherwise unresolved fields may be `undefined`. This
    *    second return value is treated as the context's final annotation
    *    snapshot for the second parse pass, replacing that context's phase-one
@@ -139,9 +180,15 @@ interface SourceContext<TRequiredOptions = void> {
    *    second call is skipped and the original parse failure is reported
    *    instead.
    *
-   * @param parsed Optional parsed result from a previous parse pass.
-   *               `single-pass` contexts can ignore this parameter.
-   *               `two-pass` contexts use this to extract or refine data.
+   * Omitting the request is treated as a manual phase-1 call for
+   * convenience, so `context.getAnnotations()` continues to work for
+   * simple one-shot annotation reads.
+   *
+   * @param request Optional request describing which collection phase the
+   *                runner is performing. `single-pass` contexts can ignore
+   *                this parameter. `two-pass` contexts should branch on
+   *                `request.phase` rather than inferring phases from
+   *                `request.parsed`.
    * @param options Optional context-required options provided by the caller
    *               of `runWith()`. These are the options declared via the
    *               `TRequiredOptions` type parameter.
@@ -150,36 +197,22 @@ interface SourceContext<TRequiredOptions = void> {
    *          during phase 1. Can be a Promise for async operations (e.g.,
    *          loading config files).
    */
-  getAnnotations(parsed?: unknown, options?: unknown): Promise<Annotations> | Annotations;
+  getAnnotations(request?: SourceContextRequest, options?: unknown): Promise<Annotations> | Annotations;
   /**
    * Optional hook to provide additional internal annotations during
    * annotation collection.  Called after {@link getAnnotations} with the
-   * same parsed value and the annotations returned by `getAnnotations()`.
+   * same request object and the annotations returned by `getAnnotations()`.
    *
    * Returns additional annotations to merge, or `undefined` to add nothing.
    * This enables contexts to inject phase-specific markers without
    * exposing them through the primary `getAnnotations()` API.
    *
-   * @param parsed The parsed result from a previous parse pass, or
-   *               `undefined` during the first pass.
+   * @param request The request describing the current collection phase.
    * @param annotations The annotations returned by `getAnnotations()`.
    * @returns Additional annotations to merge, or `undefined`.
    * @since 1.0.0
    */
-  getInternalAnnotations?(parsed: unknown, annotations: Annotations): Annotations | undefined;
-  /**
-   * Optional hook to transform the parsed value before it is passed to
-   * {@link getAnnotations} during phase-2 annotation collection.
-   *
-   * This allows contexts to distinguish between "parsed value was
-   * `undefined`" and "no parse happened yet" by wrapping `undefined`
-   * values with a context-private marker.
-   *
-   * @param parsed The parsed value to finalize.
-   * @returns The finalized parsed value.
-   * @since 1.0.0
-   */
-  finalizeParsed?(parsed: unknown): unknown;
+  getInternalAnnotations?(request: SourceContextRequest, annotations: Annotations): Annotations | undefined;
   /**
    * Optional synchronous cleanup method.  Called by `runWith()` and
    * `runWithSync()` after parsing completes.  In `runWith()`, this happens
@@ -199,4 +232,4 @@ interface SourceContext<TRequiredOptions = void> {
   [Symbol.asyncDispose]?(): void | PromiseLike<void>;
 }
 //#endregion
-export { type Annotations, ParserValuePlaceholder, SourceContext, SourceContextPhase };
+export { type Annotations, ParserValuePlaceholder, SourceContext, SourceContextPhase, SourceContextPhase1Request, SourceContextPhase2Request, SourceContextRequest };

package/dist/facade.cjs

@@ -28,9 +28,6 @@ const SuppressedErrorCtor = typeof SuppressedError === "function" ? SuppressedEr
 	}
 	return SuppressedErrorPolyfill;
 })();
-function finalizeParsedForContext(context, parsed) {
-	return context.finalizeParsed != null ? context.finalizeParsed(parsed) : parsed;
-}
 function isPlainObject(value$1) {
 	const proto = Object.getPrototypeOf(value$1);
 	return proto === Object.prototype || proto === null;
@@ -89,9 +86,6 @@ function prepareParsedForContexts(parsed, deferred, deferredKeys) {
 	if (parsed == null || typeof parsed !== "object") return void 0;
 	return parsed;
 }
-function withPreparedParsedForContext(context, preparedParsed, run) {
-	return run(finalizeParsedForContext(context, preparedParsed));
-}
 function isBufferUnchanged(previous, current) {
 	return current.length > 0 && current.length === previous.length && current.every((item, i) => item === previous[i]);
 }
@@ -1247,9 +1241,10 @@ async function collectPhase1Annotations(contexts, options) {
 	const annotationsList = [];
 	let snapshots;
 	for (const context of contexts) {
-		const result = context.getAnnotations(void 0, options);
+		const request = { phase: "phase1" };
+		const result = context.getAnnotations(request, options);
 		const annotations = result instanceof Promise ? await result : result;
-		const internalAnnotations = context.getInternalAnnotations?.(void 0, annotations);
+		const internalAnnotations = context.getInternalAnnotations?.(request, annotations);
 		const snapshot = internalAnnotations == null ? annotations : mergeAnnotations([annotations, internalAnnotations]);
 		annotationsList.push(snapshot);
 		if (snapshots != null) snapshots.push(snapshot);
@@ -1283,12 +1278,14 @@ async function collectFinalAnnotations(contexts, phase1Snapshots, parsed, option
 			annotationsList.push(phase1Snapshots[index]);
 			continue;
 		}
-		const mergedAnnotations = await withPreparedParsedForContext(context, preparedParsed, async (contextParsed) => {
-			const result = context.getAnnotations(contextParsed, options);
-			const annotations = result instanceof Promise ? await result : result;
-			const internalAnnotations = context.getInternalAnnotations?.(contextParsed, annotations);
-			return internalAnnotations == null ? annotations : mergeAnnotations([annotations, internalAnnotations]);
-		});
+		const request = {
+			phase: "phase2",
+			parsed: preparedParsed
+		};
+		const result = context.getAnnotations(request, options);
+		const annotations = result instanceof Promise ? await result : result;
+		const internalAnnotations = context.getInternalAnnotations?.(request, annotations);
+		const mergedAnnotations = internalAnnotations == null ? annotations : mergeAnnotations([annotations, internalAnnotations]);
 		annotationsList.push(mergedAnnotations);
 	}
 	return { annotations: mergeAnnotations(annotationsList) };
@@ -1300,15 +1297,16 @@ async function collectFinalAnnotations(contexts, phase1Snapshots, parsed, option
 * @param contexts Source contexts to collect annotations from.
 * @param options Optional context-required options to pass to each context.
 * @returns Merged annotations, per-context snapshots, and a two-phase hint.
-* @throws Error if any context returns a Promise.
+* @throws {TypeError} If any context returns a Promise.
 */
 function collectPhase1AnnotationsSync(contexts, options) {
 	const annotationsList = [];
 	let snapshots;
 	for (const context of contexts) {
-		const result = context.getAnnotations(void 0, options);
-		if (result instanceof Promise) throw new Error(`Context ${String(context.id)} returned a Promise in sync mode. Use runWith() or runWithAsync() for async contexts.`);
-		const internalAnnotations = context.getInternalAnnotations?.(void 0, result);
+		const request = { phase: "phase1" };
+		const result = context.getAnnotations(request, options);
+		if (result instanceof Promise) throw new TypeError(`Context ${String(context.id)} returned a Promise in sync mode. Use runWith() or runWithAsync() for async contexts.`);
+		const internalAnnotations = context.getInternalAnnotations?.(request, result);
 		const snapshot = internalAnnotations == null ? result : mergeAnnotations([result, internalAnnotations]);
 		annotationsList.push(snapshot);
 		if (snapshots != null) snapshots.push(snapshot);
@@ -1332,7 +1330,7 @@ function collectPhase1AnnotationsSync(contexts, options) {
 * @param parsed Optional parsed result from a previous parse pass.
 * @param options Optional context-required options to pass to each context.
 * @returns Merged annotations.
-* @throws Error if any context returns a Promise.
+* @throws {TypeError} If any context returns a Promise.
 */
 function collectFinalAnnotationsSync(contexts, phase1Snapshots, parsed, options, deferred, deferredKeys) {
 	const annotationsList = [];
@@ -1343,12 +1341,14 @@ function collectFinalAnnotationsSync(contexts, phase1Snapshots, parsed, options,
 			annotationsList.push(phase1Snapshots[index]);
 			continue;
 		}
-		const mergedAnnotations = withPreparedParsedForContext(context, preparedParsed, (contextParsed) => {
-			const result = context.getAnnotations(contextParsed, options);
-			if (result instanceof Promise) throw new Error(`Context ${String(context.id)} returned a Promise in sync mode. Use runWith() or runWithAsync() for async contexts.`);
-			const internalAnnotations = context.getInternalAnnotations?.(contextParsed, result);
-			return internalAnnotations == null ? result : mergeAnnotations([result, internalAnnotations]);
-		});
+		const request = {
+			phase: "phase2",
+			parsed: preparedParsed
+		};
+		const result = context.getAnnotations(request, options);
+		if (result instanceof Promise) throw new TypeError(`Context ${String(context.id)} returned a Promise in sync mode. Use runWith() or runWithAsync() for async contexts.`);
+		const internalAnnotations = context.getInternalAnnotations?.(request, result);
+		const mergedAnnotations = internalAnnotations == null ? result : mergeAnnotations([result, internalAnnotations]);
 		annotationsList.push(mergedAnnotations);
 	}
 	return { annotations: mergeAnnotations(annotationsList) };
@@ -1436,9 +1436,10 @@ async function runWithBody(parser, programName, contexts, args, options) {
 *    reaches a usable intermediate state but still does not complete
 *    successfully, the runner extracts a best-effort seed from that state
 *    instead.
-* 3. *Phase 2*: Call `getAnnotations(parsed)` on all two-pass contexts with
-*    the first pass value. Deferred or otherwise unresolved fields in
-*    `parsed` may be `undefined`. Each two-pass context's phase-two return
+* 3. *Phase 2*: Call `getAnnotations({ phase: "phase2", parsed })` on all
+*    two-pass contexts with the first pass value. Deferred or otherwise
+*    unresolved fields in `parsed` may be `undefined`. Each two-pass
+*    context's phase-two return
 *    value replaces its own phase-one contribution for the final parse, so
 *    returning `{}` clears any annotations that context provided during
 *    phase 1. Single-pass contexts reuse their phase-one snapshot.
@@ -1558,7 +1559,7 @@ function runWithSyncBody(parser, programName, contexts, args, options) {
 * {@link SourceContext.id}.
 * @throws {TypeError} If any context omits `phase` or declares an invalid
 * phase value.
-* @throws {Error} If any context returns a Promise or if a context's
+* @throws {TypeError} If any context returns a Promise or if a context's
 * `[Symbol.asyncDispose]` returns a Promise.
 * @throws {SuppressedError} If the runner throws and a context's disposal
 * also throws.  The original error is available via `.suppressed` and the

package/dist/facade.d.cts

@@ -3,7 +3,7 @@ import { HiddenVisibility, OptionName } from "./usage.cjs";
 import { DocSection, ShowChoicesOptions, ShowDefaultOptions } from "./doc.cjs";
 import { InferMode, InferValue, Mode, ModeValue, Parser } from "./parser.cjs";
 import { ShellCompletion } from "./completion.cjs";
-import { ParserValuePlaceholder, SourceContext } from "./context.cjs";
+import { ParserValuePlaceholder, SourceContext, SourceContextRequest } from "./context.cjs";
 import { Program } from "./program.cjs";
 
 //#region src/facade.d.ts
@@ -416,9 +416,10 @@ type ContextOptionsParam<TContexts extends readonly SourceContext<unknown>[], TV
  *    reaches a usable intermediate state but still does not complete
  *    successfully, the runner extracts a best-effort seed from that state
  *    instead.
- * 3. *Phase 2*: Call `getAnnotations(parsed)` on all two-pass contexts with
- *    the first pass value. Deferred or otherwise unresolved fields in
- *    `parsed` may be `undefined`. Each two-pass context's phase-two return
+ * 3. *Phase 2*: Call `getAnnotations({ phase: "phase2", parsed })` on all
+ *    two-pass contexts with the first pass value. Deferred or otherwise
+ *    unresolved fields in `parsed` may be `undefined`. Each two-pass
+ *    context's phase-two return
  *    value replaces its own phase-one contribution for the final parse, so
  *    returning `{}` clears any annotations that context provided during
  *    phase 1. Single-pass contexts reuse their phase-one snapshot.
@@ -491,7 +492,7 @@ declare function runWith<TParser extends Parser<Mode, unknown, unknown>, TContex
  * {@link SourceContext.id}.
  * @throws {TypeError} If any context omits `phase` or declares an invalid
  * phase value.
- * @throws {Error} If any context returns a Promise or if a context's
+ * @throws {TypeError} If any context returns a Promise or if a context's
  * `[Symbol.asyncDispose]` returns a Promise.
  * @throws {SuppressedError} If the runner throws and a context's disposal
  * also throws.  The original error is available via `.suppressed` and the
@@ -522,4 +523,4 @@ declare function runWithSync<TParser extends Parser<"sync", unknown, unknown>, T
  */
 declare function runWithAsync<TParser extends Parser<Mode, unknown, unknown>, TContexts extends readonly SourceContext<unknown>[], THelp = void, TError = never>(parser: TParser, programName: string, contexts: TContexts, options: RunWithOptions<THelp, TError> & ContextOptionsParam<TContexts, InferValue<TParser>>): Promise<InferValue<TParser>>;
 //#endregion
-export { CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, type ParserValuePlaceholder, RunOptions, RunParserError, RunWithOptions, type SourceContext, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync };
+export { CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, type ParserValuePlaceholder, RunOptions, RunParserError, RunWithOptions, type SourceContext, type SourceContextRequest, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync };

package/dist/facade.d.ts

@@ -3,7 +3,7 @@ import { HiddenVisibility, OptionName } from "./usage.js";
 import { DocSection, ShowChoicesOptions, ShowDefaultOptions } from "./doc.js";
 import { InferMode, InferValue, Mode, ModeValue, Parser } from "./parser.js";
 import { ShellCompletion } from "./completion.js";
-import { ParserValuePlaceholder, SourceContext } from "./context.js";
+import { ParserValuePlaceholder, SourceContext, SourceContextRequest } from "./context.js";
 import { Program } from "./program.js";
 
 //#region src/facade.d.ts
@@ -416,9 +416,10 @@ type ContextOptionsParam<TContexts extends readonly SourceContext<unknown>[], TV
  *    reaches a usable intermediate state but still does not complete
  *    successfully, the runner extracts a best-effort seed from that state
  *    instead.
- * 3. *Phase 2*: Call `getAnnotations(parsed)` on all two-pass contexts with
- *    the first pass value. Deferred or otherwise unresolved fields in
- *    `parsed` may be `undefined`. Each two-pass context's phase-two return
+ * 3. *Phase 2*: Call `getAnnotations({ phase: "phase2", parsed })` on all
+ *    two-pass contexts with the first pass value. Deferred or otherwise
+ *    unresolved fields in `parsed` may be `undefined`. Each two-pass
+ *    context's phase-two return
  *    value replaces its own phase-one contribution for the final parse, so
  *    returning `{}` clears any annotations that context provided during
  *    phase 1. Single-pass contexts reuse their phase-one snapshot.
@@ -491,7 +492,7 @@ declare function runWith<TParser extends Parser<Mode, unknown, unknown>, TContex
  * {@link SourceContext.id}.
  * @throws {TypeError} If any context omits `phase` or declares an invalid
  * phase value.
- * @throws {Error} If any context returns a Promise or if a context's
+ * @throws {TypeError} If any context returns a Promise or if a context's
  * `[Symbol.asyncDispose]` returns a Promise.
  * @throws {SuppressedError} If the runner throws and a context's disposal
  * also throws.  The original error is available via `.suppressed` and the
@@ -522,4 +523,4 @@ declare function runWithSync<TParser extends Parser<"sync", unknown, unknown>, T
  */
 declare function runWithAsync<TParser extends Parser<Mode, unknown, unknown>, TContexts extends readonly SourceContext<unknown>[], THelp = void, TError = never>(parser: TParser, programName: string, contexts: TContexts, options: RunWithOptions<THelp, TError> & ContextOptionsParam<TContexts, InferValue<TParser>>): Promise<InferValue<TParser>>;
 //#endregion
-export { CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, type ParserValuePlaceholder, RunOptions, RunParserError, RunWithOptions, type SourceContext, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync };
+export { CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, type ParserValuePlaceholder, RunOptions, RunParserError, RunWithOptions, type SourceContext, type SourceContextRequest, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync };

package/dist/facade.js

@@ -28,9 +28,6 @@ const SuppressedErrorCtor = typeof SuppressedError === "function" ? SuppressedEr
 	}
 	return SuppressedErrorPolyfill;
 })();
-function finalizeParsedForContext(context, parsed) {
-	return context.finalizeParsed != null ? context.finalizeParsed(parsed) : parsed;
-}
 function isPlainObject(value$1) {
 	const proto = Object.getPrototypeOf(value$1);
 	return proto === Object.prototype || proto === null;
@@ -89,9 +86,6 @@ function prepareParsedForContexts(parsed, deferred, deferredKeys) {
 	if (parsed == null || typeof parsed !== "object") return void 0;
 	return parsed;
 }
-function withPreparedParsedForContext(context, preparedParsed, run) {
-	return run(finalizeParsedForContext(context, preparedParsed));
-}
 function isBufferUnchanged(previous, current) {
 	return current.length > 0 && current.length === previous.length && current.every((item, i) => item === previous[i]);
 }
@@ -1247,9 +1241,10 @@ async function collectPhase1Annotations(contexts, options) {
 	const annotationsList = [];
 	let snapshots;
 	for (const context of contexts) {
-		const result = context.getAnnotations(void 0, options);
+		const request = { phase: "phase1" };
+		const result = context.getAnnotations(request, options);
 		const annotations = result instanceof Promise ? await result : result;
-		const internalAnnotations = context.getInternalAnnotations?.(void 0, annotations);
+		const internalAnnotations = context.getInternalAnnotations?.(request, annotations);
 		const snapshot = internalAnnotations == null ? annotations : mergeAnnotations([annotations, internalAnnotations]);
 		annotationsList.push(snapshot);
 		if (snapshots != null) snapshots.push(snapshot);
@@ -1283,12 +1278,14 @@ async function collectFinalAnnotations(contexts, phase1Snapshots, parsed, option
 			annotationsList.push(phase1Snapshots[index]);
 			continue;
 		}
-		const mergedAnnotations = await withPreparedParsedForContext(context, preparedParsed, async (contextParsed) => {
-			const result = context.getAnnotations(contextParsed, options);
-			const annotations = result instanceof Promise ? await result : result;
-			const internalAnnotations = context.getInternalAnnotations?.(contextParsed, annotations);
-			return internalAnnotations == null ? annotations : mergeAnnotations([annotations, internalAnnotations]);
-		});
+		const request = {
+			phase: "phase2",
+			parsed: preparedParsed
+		};
+		const result = context.getAnnotations(request, options);
+		const annotations = result instanceof Promise ? await result : result;
+		const internalAnnotations = context.getInternalAnnotations?.(request, annotations);
+		const mergedAnnotations = internalAnnotations == null ? annotations : mergeAnnotations([annotations, internalAnnotations]);
 		annotationsList.push(mergedAnnotations);
 	}
 	return { annotations: mergeAnnotations(annotationsList) };
@@ -1300,15 +1297,16 @@ async function collectFinalAnnotations(contexts, phase1Snapshots, parsed, option
 * @param contexts Source contexts to collect annotations from.
 * @param options Optional context-required options to pass to each context.
 * @returns Merged annotations, per-context snapshots, and a two-phase hint.
-* @throws Error if any context returns a Promise.
+* @throws {TypeError} If any context returns a Promise.
 */
 function collectPhase1AnnotationsSync(contexts, options) {
 	const annotationsList = [];
 	let snapshots;
 	for (const context of contexts) {
-		const result = context.getAnnotations(void 0, options);
-		if (result instanceof Promise) throw new Error(`Context ${String(context.id)} returned a Promise in sync mode. Use runWith() or runWithAsync() for async contexts.`);
-		const internalAnnotations = context.getInternalAnnotations?.(void 0, result);
+		const request = { phase: "phase1" };
+		const result = context.getAnnotations(request, options);
+		if (result instanceof Promise) throw new TypeError(`Context ${String(context.id)} returned a Promise in sync mode. Use runWith() or runWithAsync() for async contexts.`);
+		const internalAnnotations = context.getInternalAnnotations?.(request, result);
 		const snapshot = internalAnnotations == null ? result : mergeAnnotations([result, internalAnnotations]);
 		annotationsList.push(snapshot);
 		if (snapshots != null) snapshots.push(snapshot);
@@ -1332,7 +1330,7 @@ function collectPhase1AnnotationsSync(contexts, options) {
 * @param parsed Optional parsed result from a previous parse pass.
 * @param options Optional context-required options to pass to each context.
 * @returns Merged annotations.
-* @throws Error if any context returns a Promise.
+* @throws {TypeError} If any context returns a Promise.
 */
 function collectFinalAnnotationsSync(contexts, phase1Snapshots, parsed, options, deferred, deferredKeys) {
 	const annotationsList = [];
@@ -1343,12 +1341,14 @@ function collectFinalAnnotationsSync(contexts, phase1Snapshots, parsed, options,
 			annotationsList.push(phase1Snapshots[index]);
 			continue;
 		}
-		const mergedAnnotations = withPreparedParsedForContext(context, preparedParsed, (contextParsed) => {
-			const result = context.getAnnotations(contextParsed, options);
-			if (result instanceof Promise) throw new Error(`Context ${String(context.id)} returned a Promise in sync mode. Use runWith() or runWithAsync() for async contexts.`);
-			const internalAnnotations = context.getInternalAnnotations?.(contextParsed, result);
-			return internalAnnotations == null ? result : mergeAnnotations([result, internalAnnotations]);
-		});
+		const request = {
+			phase: "phase2",
+			parsed: preparedParsed
+		};
+		const result = context.getAnnotations(request, options);
+		if (result instanceof Promise) throw new TypeError(`Context ${String(context.id)} returned a Promise in sync mode. Use runWith() or runWithAsync() for async contexts.`);
+		const internalAnnotations = context.getInternalAnnotations?.(request, result);
+		const mergedAnnotations = internalAnnotations == null ? result : mergeAnnotations([result, internalAnnotations]);
 		annotationsList.push(mergedAnnotations);
 	}
 	return { annotations: mergeAnnotations(annotationsList) };
@@ -1436,9 +1436,10 @@ async function runWithBody(parser, programName, contexts, args, options) {
 *    reaches a usable intermediate state but still does not complete
 *    successfully, the runner extracts a best-effort seed from that state
 *    instead.
-* 3. *Phase 2*: Call `getAnnotations(parsed)` on all two-pass contexts with
-*    the first pass value. Deferred or otherwise unresolved fields in
-*    `parsed` may be `undefined`. Each two-pass context's phase-two return
+* 3. *Phase 2*: Call `getAnnotations({ phase: "phase2", parsed })` on all
+*    two-pass contexts with the first pass value. Deferred or otherwise
+*    unresolved fields in `parsed` may be `undefined`. Each two-pass
+*    context's phase-two return
 *    value replaces its own phase-one contribution for the final parse, so
 *    returning `{}` clears any annotations that context provided during
 *    phase 1. Single-pass contexts reuse their phase-one snapshot.
@@ -1558,7 +1559,7 @@ function runWithSyncBody(parser, programName, contexts, args, options) {
 * {@link SourceContext.id}.
 * @throws {TypeError} If any context omits `phase` or declares an invalid
 * phase value.
-* @throws {Error} If any context returns a Promise or if a context's
+* @throws {TypeError} If any context returns a Promise or if a context's
 * `[Symbol.asyncDispose]` returns a Promise.
 * @throws {SuppressedError} If the runner throws and a context's disposal
 * also throws.  The original error is available via `.suppressed` and the

package/dist/index.d.cts

@@ -9,7 +9,7 @@ import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOpt
 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 { ParserValuePlaceholder, SourceContext, SourceContextRequest } 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, 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, SourceContextRequest, 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

@@ -9,7 +9,7 @@ import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOpt
 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 { ParserValuePlaceholder, SourceContext, SourceContextRequest } 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, 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, SourceContextRequest, 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.1828+b245a686",
+  "version": "1.0.0-dev.1841+7b330b10",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",