@optique/core 1.0.0-dev.1778 → 1.0.0-dev.1786

package/dist/context.d.cts

@@ -126,9 +126,14 @@ interface SourceContext<TRequiredOptions = void> {
    *
    * 1. *First call*: `parsed` is `undefined`. Static contexts should return
    *    their annotations, while dynamic contexts should return an empty object.
-   * 2. *Second call*: `parsed` contains the result from the first parse pass.
-   *    Dynamic contexts can use this to load external data (e.g., reading
-   *    a config file whose path was determined in the first pass).
+   * 2. *Second call*: `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. Dynamic contexts can use this to load external data
+   *    (e.g., reading a config file whose path was determined in the first
+   *    pass). Deferred or otherwise unresolved fields may be `undefined`.
+   *    If the runner cannot extract a usable value at all, this second call
+   *    is skipped and the original parse failure is reported instead.
    *
    * @param parsed Optional parsed result from a previous parse pass.
    *               Static contexts can ignore this parameter.

package/dist/context.d.ts

@@ -126,9 +126,14 @@ interface SourceContext<TRequiredOptions = void> {
    *
    * 1. *First call*: `parsed` is `undefined`. Static contexts should return
    *    their annotations, while dynamic contexts should return an empty object.
-   * 2. *Second call*: `parsed` contains the result from the first parse pass.
-   *    Dynamic contexts can use this to load external data (e.g., reading
-   *    a config file whose path was determined in the first pass).
+   * 2. *Second call*: `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. Dynamic contexts can use this to load external data
+   *    (e.g., reading a config file whose path was determined in the first
+   *    pass). Deferred or otherwise unresolved fields may be `undefined`.
+   *    If the runner cannot extract a usable value at all, this second call
+   *    is skipped and the original parse failure is reported instead.
    *
    * @param parsed Optional parsed result from a previous parse pass.
    *               Static contexts can ignore this parameter.

package/dist/facade.cjs

@@ -5,10 +5,13 @@ const require_validate = require('./validate.cjs');
 const require_usage = require('./usage.cjs');
 const require_doc = require('./doc.cjs');
 const require_mode_dispatch = require('./mode-dispatch.cjs');
+const require_input_trace = require('./input-trace.cjs');
+const require_phase2_seed = require('./phase2-seed.cjs');
 const require_modifiers = require('./modifiers.cjs');
 const require_valueparser = require('./valueparser.cjs');
 const require_primitives = require('./primitives.cjs');
 const require_parser = require('./parser.cjs');
+const require_dependency_runtime = require('./dependency-runtime.cjs');
 const require_constructs = require('./constructs.cjs');
 
 //#region src/facade.ts
@@ -89,6 +92,60 @@ function prepareParsedForContexts(parsed, deferred, deferredKeys) {
 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]);
+}
+function createPhase2SeedExec(parser, context) {
+	const exec = {
+		usage: parser.usage,
+		phase: "parse",
+		path: [],
+		trace: require_input_trace.createInputTrace()
+	};
+	const runtime = require_dependency_runtime.createDependencyRuntimeContext();
+	return {
+		...exec,
+		phase: "complete",
+		dependencyRuntime: runtime,
+		dependencyRegistry: runtime.registry,
+		trace: context.exec?.trace ?? context.trace ?? exec.trace
+	};
+}
+function createPhase2SeedContext(parser, args) {
+	const exec = {
+		usage: parser.usage,
+		phase: "parse",
+		path: [],
+		trace: require_input_trace.createInputTrace()
+	};
+	return require_parser.createParserContext({
+		buffer: args,
+		state: parser.initialState,
+		optionsTerminated: false
+	}, exec);
+}
+function extractPhase2SeedSync(parser, args) {
+	let context = createPhase2SeedContext(parser, args);
+	do {
+		const result = parser.parse(context);
+		if (!result.success) return require_phase2_seed.completeOrExtractPhase2Seed(parser, context.state, createPhase2SeedExec(parser, context));
+		const previousBuffer = context.buffer;
+		context = result.next;
+		if (isBufferUnchanged(previousBuffer, context.buffer)) return require_phase2_seed.completeOrExtractPhase2Seed(parser, context.state, createPhase2SeedExec(parser, context));
+	} while (context.buffer.length > 0);
+	return require_phase2_seed.completeOrExtractPhase2Seed(parser, context.state, createPhase2SeedExec(parser, context));
+}
+async function extractPhase2SeedAsync(parser, args) {
+	let context = createPhase2SeedContext(parser, args);
+	do {
+		const result = await parser.parse(context);
+		if (!result.success) return await require_phase2_seed.completeOrExtractPhase2Seed(parser, context.state, createPhase2SeedExec(parser, context));
+		const previousBuffer = context.buffer;
+		context = result.next;
+		if (isBufferUnchanged(previousBuffer, context.buffer)) return await require_phase2_seed.completeOrExtractPhase2Seed(parser, context.state, createPhase2SeedExec(parser, context));
+	} while (context.buffer.length > 0);
+	return await require_phase2_seed.completeOrExtractPhase2Seed(parser, context.state, createPhase2SeedExec(parser, context));
+}
 /**
 * Creates help parsers based on the sub-config.
 */
@@ -1197,30 +1254,13 @@ async function runWithBody(parser, programName, contexts, args, options) {
 		return Promise.resolve(runParser(augmentedParser, programName, args, options));
 	}
 	const augmentedParser1 = injectAnnotationsIntoParser(parser, phase1Annotations);
-	let firstPassResult;
-	let firstPassDeferred;
-	let firstPassDeferredKeys;
-	let firstPassFailed = false;
-	try {
-		if (parser.$mode === "async") firstPassResult = await require_parser.parseAsync(augmentedParser1, args);
-		else firstPassResult = require_parser.parseSync(augmentedParser1, args);
-		if (typeof firstPassResult === "object" && firstPassResult !== null && "success" in firstPassResult) {
-			const result = firstPassResult;
-			if (result.success) {
-				firstPassResult = result.value;
-				firstPassDeferred = result.deferred;
-				firstPassDeferredKeys = result.deferredKeys;
-			} else firstPassFailed = true;
-		}
-	} catch {
-		firstPassFailed = true;
-	}
-	if (firstPassFailed) {
+	const firstPassSeed = await require_mode_dispatch.dispatchByMode(parser.$mode, () => extractPhase2SeedSync(augmentedParser1, args), () => extractPhase2SeedAsync(augmentedParser1, args));
+	if (firstPassSeed == null) {
 		const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
 		if (parser.$mode === "async") return runParser(augmentedParser, programName, args, options);
 		return Promise.resolve(runParser(augmentedParser, programName, args, options));
 	}
-	const { annotationsList: phase2AnnotationsList } = await collectAnnotations(contexts, firstPassResult, ctxOptions, firstPassDeferred, firstPassDeferredKeys);
+	const { annotationsList: phase2AnnotationsList } = await collectAnnotations(contexts, firstPassSeed.value, ctxOptions, firstPassSeed.deferred, firstPassSeed.deferredKeys);
 	const finalAnnotations = mergeTwoPhaseAnnotations(phase1AnnotationsList, phase2AnnotationsList);
 	const augmentedParser2 = injectAnnotationsIntoParser(parser, finalAnnotations);
 	if (parser.$mode === "async") return runParser(augmentedParser2, programName, args, options);
@@ -1236,13 +1276,19 @@ async function runWithBody(parser, programName, contexts, args, options) {
 *
 * 1. *Phase 1*: Collect annotations from all contexts (static contexts return
 *    their data, dynamic contexts may return empty).
-* 2. *First parse*: Parse with Phase 1 annotations.
+* 2. *First parse*: Parse with Phase 1 annotations. If that pass finishes
+*    successfully, its value becomes the phase-two input. If the parser
+*    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 contexts with the first
-*    parse result.
+*    pass value. Deferred or otherwise unresolved fields in `parsed` may be
+*    `undefined`.
 * 4. *Second parse*: Parse again with merged annotations from both phases.
 *
-* If all contexts are static (no dynamic contexts), the second parse is skipped
-* for optimization.
+* If all contexts are static (no dynamic contexts), the second parse is
+* skipped for optimization. Phase 2 is also skipped when the first pass does
+* not yield any usable seed at all.
 *
 * @template TParser The parser type.
 * @template THelp Return type when help is shown.
@@ -1317,20 +1363,12 @@ function runWithSyncBody(parser, programName, contexts, args, options) {
 		return runParser(augmentedParser, programName, args, options);
 	}
 	const augmentedParser1 = injectAnnotationsIntoParser(parser, phase1Annotations);
-	let firstPassResult;
-	let firstPassDeferred;
-	let firstPassDeferredKeys;
-	try {
-		const result = require_parser.parseSync(augmentedParser1, args);
-		if (result.success) {
-			firstPassResult = result.value;
-			firstPassDeferred = result.deferred;
-			firstPassDeferredKeys = result.deferredKeys;
-		} else return runParser(augmentedParser1, programName, args, options);
-	} catch {
-		return runParser(augmentedParser1, programName, args, options);
+	const firstPassSeed = extractPhase2SeedSync(augmentedParser1, args);
+	if (firstPassSeed == null) {
+		const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
+		return runParser(augmentedParser, programName, args, options);
 	}
-	const { annotationsList: phase2AnnotationsList } = collectAnnotationsSync(contexts, firstPassResult, ctxOptions, firstPassDeferred, firstPassDeferredKeys);
+	const { annotationsList: phase2AnnotationsList } = collectAnnotationsSync(contexts, firstPassSeed.value, ctxOptions, firstPassSeed.deferred, firstPassSeed.deferredKeys);
 	const finalAnnotations = mergeTwoPhaseAnnotations(phase1AnnotationsList, phase2AnnotationsList);
 	const augmentedParser2 = injectAnnotationsIntoParser(parser, finalAnnotations);
 	return runParser(augmentedParser2, programName, args, options);
@@ -1339,7 +1377,9 @@ function runWithSyncBody(parser, programName, contexts, args, options) {
 * Runs a synchronous parser with multiple source contexts.
 *
 * This is the sync-only variant of {@link runWith}. All contexts must return
-* annotations synchronously (not Promises).
+* annotations synchronously (not Promises). It uses the same two-phase
+* best-effort seed extraction as {@link runWith} when dynamic contexts are
+* present.
 *
 * @template TParser The sync parser type.
 * @template THelp Return type when help is shown.
@@ -1415,10 +1455,25 @@ function runWithAsync(parser, programName, contexts, options) {
 */
 function injectAnnotationsIntoParser(parser, annotations) {
 	const newInitialState = require_annotations.injectAnnotations(parser.initialState, annotations);
-	return {
-		...parser,
-		initialState: newInitialState
+	const descriptors = { ...Object.getOwnPropertyDescriptors(parser) };
+	const initialState = descriptors.initialState;
+	descriptors.initialState = initialState == null ? {
+		value: newInitialState,
+		writable: true,
+		enumerable: true,
+		configurable: true
+	} : "get" in initialState || "set" in initialState ? {
+		value: newInitialState,
+		writable: true,
+		enumerable: initialState.enumerable ?? true,
+		configurable: initialState.configurable ?? true
+	} : {
+		value: newInitialState,
+		writable: initialState.writable ?? true,
+		enumerable: initialState.enumerable ?? true,
+		configurable: initialState.configurable ?? true
 	};
+	return Object.create(Object.getPrototypeOf(parser), descriptors);
 }
 
 //#endregion

package/dist/facade.d.cts

@@ -412,13 +412,19 @@ type ContextOptionsParam<TContexts extends readonly SourceContext<unknown>[], TV
  *
  * 1. *Phase 1*: Collect annotations from all contexts (static contexts return
  *    their data, dynamic contexts may return empty).
- * 2. *First parse*: Parse with Phase 1 annotations.
+ * 2. *First parse*: Parse with Phase 1 annotations. If that pass finishes
+ *    successfully, its value becomes the phase-two input. If the parser
+ *    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 contexts with the first
- *    parse result.
+ *    pass value. Deferred or otherwise unresolved fields in `parsed` may be
+ *    `undefined`.
  * 4. *Second parse*: Parse again with merged annotations from both phases.
  *
- * If all contexts are static (no dynamic contexts), the second parse is skipped
- * for optimization.
+ * If all contexts are static (no dynamic contexts), the second parse is
+ * skipped for optimization. Phase 2 is also skipped when the first pass does
+ * not yield any usable seed at all.
  *
  * @template TParser The parser type.
  * @template THelp Return type when help is shown.
@@ -460,7 +466,9 @@ declare function runWith<TParser extends Parser<Mode, unknown, unknown>, TContex
  * Runs a synchronous parser with multiple source contexts.
  *
  * This is the sync-only variant of {@link runWith}. All contexts must return
- * annotations synchronously (not Promises).
+ * annotations synchronously (not Promises). It uses the same two-phase
+ * best-effort seed extraction as {@link runWith} when dynamic contexts are
+ * present.
  *
  * @template TParser The sync parser type.
  * @template THelp Return type when help is shown.

package/dist/facade.d.ts

@@ -412,13 +412,19 @@ type ContextOptionsParam<TContexts extends readonly SourceContext<unknown>[], TV
  *
  * 1. *Phase 1*: Collect annotations from all contexts (static contexts return
  *    their data, dynamic contexts may return empty).
- * 2. *First parse*: Parse with Phase 1 annotations.
+ * 2. *First parse*: Parse with Phase 1 annotations. If that pass finishes
+ *    successfully, its value becomes the phase-two input. If the parser
+ *    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 contexts with the first
- *    parse result.
+ *    pass value. Deferred or otherwise unresolved fields in `parsed` may be
+ *    `undefined`.
  * 4. *Second parse*: Parse again with merged annotations from both phases.
  *
- * If all contexts are static (no dynamic contexts), the second parse is skipped
- * for optimization.
+ * If all contexts are static (no dynamic contexts), the second parse is
+ * skipped for optimization. Phase 2 is also skipped when the first pass does
+ * not yield any usable seed at all.
  *
  * @template TParser The parser type.
  * @template THelp Return type when help is shown.
@@ -460,7 +466,9 @@ declare function runWith<TParser extends Parser<Mode, unknown, unknown>, TContex
  * Runs a synchronous parser with multiple source contexts.
  *
  * This is the sync-only variant of {@link runWith}. All contexts must return
- * annotations synchronously (not Promises).
+ * annotations synchronously (not Promises). It uses the same two-phase
+ * best-effort seed extraction as {@link runWith} when dynamic contexts are
+ * present.
  *
  * @template TParser The sync parser type.
  * @template THelp Return type when help is shown.

package/dist/facade.js

@@ -5,10 +5,13 @@ import { validateCommandNames, validateContextIds, validateMetaNameCollisions, v
 import { extractCommandNames, extractLiteralValues, extractOptionNames, formatUsage } from "./usage.js";
 import { formatDocPage } from "./doc.js";
 import { dispatchByMode } from "./mode-dispatch.js";
+import { createInputTrace } from "./input-trace.js";
+import { completeOrExtractPhase2Seed } from "./phase2-seed.js";
 import { multiple, optional, withDefault } from "./modifiers.js";
 import { string } from "./valueparser.js";
 import { argument, command, constant, flag, option } from "./primitives.js";
-import { getDocPage, parseAsync, parseSync, suggest, suggestAsync } from "./parser.js";
+import { createParserContext, getDocPage, parseAsync, parseSync, suggest, suggestAsync } from "./parser.js";
+import { createDependencyRuntimeContext } from "./dependency-runtime.js";
 import { group, longestMatch, object } from "./constructs.js";
 
 //#region src/facade.ts
@@ -89,6 +92,60 @@ function prepareParsedForContexts(parsed, deferred, deferredKeys) {
 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]);
+}
+function createPhase2SeedExec(parser, context) {
+	const exec = {
+		usage: parser.usage,
+		phase: "parse",
+		path: [],
+		trace: createInputTrace()
+	};
+	const runtime = createDependencyRuntimeContext();
+	return {
+		...exec,
+		phase: "complete",
+		dependencyRuntime: runtime,
+		dependencyRegistry: runtime.registry,
+		trace: context.exec?.trace ?? context.trace ?? exec.trace
+	};
+}
+function createPhase2SeedContext(parser, args) {
+	const exec = {
+		usage: parser.usage,
+		phase: "parse",
+		path: [],
+		trace: createInputTrace()
+	};
+	return createParserContext({
+		buffer: args,
+		state: parser.initialState,
+		optionsTerminated: false
+	}, exec);
+}
+function extractPhase2SeedSync(parser, args) {
+	let context = createPhase2SeedContext(parser, args);
+	do {
+		const result = parser.parse(context);
+		if (!result.success) return completeOrExtractPhase2Seed(parser, context.state, createPhase2SeedExec(parser, context));
+		const previousBuffer = context.buffer;
+		context = result.next;
+		if (isBufferUnchanged(previousBuffer, context.buffer)) return completeOrExtractPhase2Seed(parser, context.state, createPhase2SeedExec(parser, context));
+	} while (context.buffer.length > 0);
+	return completeOrExtractPhase2Seed(parser, context.state, createPhase2SeedExec(parser, context));
+}
+async function extractPhase2SeedAsync(parser, args) {
+	let context = createPhase2SeedContext(parser, args);
+	do {
+		const result = await parser.parse(context);
+		if (!result.success) return await completeOrExtractPhase2Seed(parser, context.state, createPhase2SeedExec(parser, context));
+		const previousBuffer = context.buffer;
+		context = result.next;
+		if (isBufferUnchanged(previousBuffer, context.buffer)) return await completeOrExtractPhase2Seed(parser, context.state, createPhase2SeedExec(parser, context));
+	} while (context.buffer.length > 0);
+	return await completeOrExtractPhase2Seed(parser, context.state, createPhase2SeedExec(parser, context));
+}
 /**
 * Creates help parsers based on the sub-config.
 */
@@ -1197,30 +1254,13 @@ async function runWithBody(parser, programName, contexts, args, options) {
 		return Promise.resolve(runParser(augmentedParser, programName, args, options));
 	}
 	const augmentedParser1 = injectAnnotationsIntoParser(parser, phase1Annotations);
-	let firstPassResult;
-	let firstPassDeferred;
-	let firstPassDeferredKeys;
-	let firstPassFailed = false;
-	try {
-		if (parser.$mode === "async") firstPassResult = await parseAsync(augmentedParser1, args);
-		else firstPassResult = parseSync(augmentedParser1, args);
-		if (typeof firstPassResult === "object" && firstPassResult !== null && "success" in firstPassResult) {
-			const result = firstPassResult;
-			if (result.success) {
-				firstPassResult = result.value;
-				firstPassDeferred = result.deferred;
-				firstPassDeferredKeys = result.deferredKeys;
-			} else firstPassFailed = true;
-		}
-	} catch {
-		firstPassFailed = true;
-	}
-	if (firstPassFailed) {
+	const firstPassSeed = await dispatchByMode(parser.$mode, () => extractPhase2SeedSync(augmentedParser1, args), () => extractPhase2SeedAsync(augmentedParser1, args));
+	if (firstPassSeed == null) {
 		const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
 		if (parser.$mode === "async") return runParser(augmentedParser, programName, args, options);
 		return Promise.resolve(runParser(augmentedParser, programName, args, options));
 	}
-	const { annotationsList: phase2AnnotationsList } = await collectAnnotations(contexts, firstPassResult, ctxOptions, firstPassDeferred, firstPassDeferredKeys);
+	const { annotationsList: phase2AnnotationsList } = await collectAnnotations(contexts, firstPassSeed.value, ctxOptions, firstPassSeed.deferred, firstPassSeed.deferredKeys);
 	const finalAnnotations = mergeTwoPhaseAnnotations(phase1AnnotationsList, phase2AnnotationsList);
 	const augmentedParser2 = injectAnnotationsIntoParser(parser, finalAnnotations);
 	if (parser.$mode === "async") return runParser(augmentedParser2, programName, args, options);
@@ -1236,13 +1276,19 @@ async function runWithBody(parser, programName, contexts, args, options) {
 *
 * 1. *Phase 1*: Collect annotations from all contexts (static contexts return
 *    their data, dynamic contexts may return empty).
-* 2. *First parse*: Parse with Phase 1 annotations.
+* 2. *First parse*: Parse with Phase 1 annotations. If that pass finishes
+*    successfully, its value becomes the phase-two input. If the parser
+*    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 contexts with the first
-*    parse result.
+*    pass value. Deferred or otherwise unresolved fields in `parsed` may be
+*    `undefined`.
 * 4. *Second parse*: Parse again with merged annotations from both phases.
 *
-* If all contexts are static (no dynamic contexts), the second parse is skipped
-* for optimization.
+* If all contexts are static (no dynamic contexts), the second parse is
+* skipped for optimization. Phase 2 is also skipped when the first pass does
+* not yield any usable seed at all.
 *
 * @template TParser The parser type.
 * @template THelp Return type when help is shown.
@@ -1317,20 +1363,12 @@ function runWithSyncBody(parser, programName, contexts, args, options) {
 		return runParser(augmentedParser, programName, args, options);
 	}
 	const augmentedParser1 = injectAnnotationsIntoParser(parser, phase1Annotations);
-	let firstPassResult;
-	let firstPassDeferred;
-	let firstPassDeferredKeys;
-	try {
-		const result = parseSync(augmentedParser1, args);
-		if (result.success) {
-			firstPassResult = result.value;
-			firstPassDeferred = result.deferred;
-			firstPassDeferredKeys = result.deferredKeys;
-		} else return runParser(augmentedParser1, programName, args, options);
-	} catch {
-		return runParser(augmentedParser1, programName, args, options);
+	const firstPassSeed = extractPhase2SeedSync(augmentedParser1, args);
+	if (firstPassSeed == null) {
+		const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
+		return runParser(augmentedParser, programName, args, options);
 	}
-	const { annotationsList: phase2AnnotationsList } = collectAnnotationsSync(contexts, firstPassResult, ctxOptions, firstPassDeferred, firstPassDeferredKeys);
+	const { annotationsList: phase2AnnotationsList } = collectAnnotationsSync(contexts, firstPassSeed.value, ctxOptions, firstPassSeed.deferred, firstPassSeed.deferredKeys);
 	const finalAnnotations = mergeTwoPhaseAnnotations(phase1AnnotationsList, phase2AnnotationsList);
 	const augmentedParser2 = injectAnnotationsIntoParser(parser, finalAnnotations);
 	return runParser(augmentedParser2, programName, args, options);
@@ -1339,7 +1377,9 @@ function runWithSyncBody(parser, programName, contexts, args, options) {
 * Runs a synchronous parser with multiple source contexts.
 *
 * This is the sync-only variant of {@link runWith}. All contexts must return
-* annotations synchronously (not Promises).
+* annotations synchronously (not Promises). It uses the same two-phase
+* best-effort seed extraction as {@link runWith} when dynamic contexts are
+* present.
 *
 * @template TParser The sync parser type.
 * @template THelp Return type when help is shown.
@@ -1415,10 +1455,25 @@ function runWithAsync(parser, programName, contexts, options) {
 */
 function injectAnnotationsIntoParser(parser, annotations) {
 	const newInitialState = injectAnnotations(parser.initialState, annotations);
-	return {
-		...parser,
-		initialState: newInitialState
+	const descriptors = { ...Object.getOwnPropertyDescriptors(parser) };
+	const initialState = descriptors.initialState;
+	descriptors.initialState = initialState == null ? {
+		value: newInitialState,
+		writable: true,
+		enumerable: true,
+		configurable: true
+	} : "get" in initialState || "set" in initialState ? {
+		value: newInitialState,
+		writable: true,
+		enumerable: initialState.enumerable ?? true,
+		configurable: initialState.configurable ?? true
+	} : {
+		value: newInitialState,
+		writable: initialState.writable ?? true,
+		enumerable: initialState.enumerable ?? true,
+		configurable: initialState.configurable ?? true
 	};
+	return Object.create(Object.getPrototypeOf(parser), descriptors);
 }
 
 //#endregion

package/dist/modifiers.cjs

@@ -2,6 +2,7 @@ const require_annotations = require('./annotations.cjs');
 const require_message = require('./message.cjs');
 const require_mode_dispatch = require('./mode-dispatch.cjs');
 const require_dependency_metadata = require('./dependency-metadata.cjs');
+const require_phase2_seed = require('./phase2-seed.cjs');
 const require_parser = require('./parser.cjs');
 
 //#region src/modifiers.ts
@@ -79,6 +80,10 @@ function unwrapMultipleItemState(state) {
 function isPromiseLike(value) {
 	return value != null && (typeof value === "object" || typeof value === "function") && "then" in value && typeof value.then === "function";
 }
+function extractOptionalLikePhase2Seed(parser, state, exec) {
+	if (!Array.isArray(state) && !(state != null && typeof state === "object")) return require_mode_dispatch.wrapForMode(parser.$mode, null);
+	return require_phase2_seed.completeOrExtractPhase2Seed(parser, normalizeOptionalLikeInnerState(state, parser.initialState, parser), exec);
+}
 /**
 * Computes the inner state to pass through to the wrapped parser inside
 * {@link optional} / {@link withDefault}.  When the outer state is an
@@ -251,6 +256,9 @@ function optional(parser) {
 				state: innerState
 			}] : []);
 		},
+		[require_phase2_seed.extractPhase2SeedKey](state, exec) {
+			return extractOptionalLikePhase2Seed(parser, state, exec);
+		},
 		parse(context) {
 			return require_mode_dispatch.dispatchByMode(parser.$mode, () => parseOptionalStyleSync(context, syncParser), () => parseOptionalStyleAsync(context, parser));
 		},
@@ -416,6 +424,9 @@ function withDefault(parser, defaultValue, options) {
 				state: innerState
 			}] : []);
 		},
+		[require_phase2_seed.extractPhase2SeedKey](state, exec) {
+			return extractOptionalLikePhase2Seed(parser, state, exec);
+		},
 		parse(context) {
 			return require_mode_dispatch.dispatchByMode(parser.$mode, () => parseOptionalStyleSync(context, syncParser), () => parseOptionalStyleAsync(context, parser));
 		},
@@ -656,6 +667,23 @@ function map(parser, transform) {
 		...parser,
 		$valueType: [],
 		complete,
+		[require_phase2_seed.extractPhase2SeedKey](state, exec) {
+			return require_mode_dispatch.mapModeValue(parser.$mode, require_phase2_seed.completeOrExtractPhase2Seed(parser, state, exec), (seed) => {
+				if (seed == null) return null;
+				if (seed.deferred) try {
+					return {
+						value: transform(seed.value),
+						deferred: true
+					};
+				} catch {
+					return {
+						value: void 0,
+						deferred: true
+					};
+				}
+				return { value: transform(seed.value) };
+			});
+		},
 		getSuggestRuntimeNodes(state, path) {
 			if (mappedParser.dependencyMetadata?.source != null) return [{
 				path,
@@ -795,6 +823,26 @@ function multiple(parser, options = {}) {
 			});
 		}
 	};
+	const extractPhase2SeedSyncWithUnwrappedFallback = (state, exec) => {
+		try {
+			const seed = require_phase2_seed.completeOrExtractPhase2Seed(syncParser, state, exec);
+			if (seed == null && require_annotations.isInjectedAnnotationWrapper(state)) return require_phase2_seed.completeOrExtractPhase2Seed(syncParser, unwrapInjectedWrapper(state), exec);
+			return seed;
+		} catch (error) {
+			if (!require_annotations.isInjectedAnnotationWrapper(state)) throw error;
+			return require_phase2_seed.completeOrExtractPhase2Seed(syncParser, unwrapInjectedWrapper(state), exec);
+		}
+	};
+	const extractPhase2SeedAsyncWithUnwrappedFallback = async (state, exec) => {
+		try {
+			const seed = await require_phase2_seed.completeOrExtractPhase2Seed(parser, state, exec);
+			if (seed == null && require_annotations.isInjectedAnnotationWrapper(state)) return await require_phase2_seed.completeOrExtractPhase2Seed(parser, unwrapInjectedWrapper(state), exec);
+			return seed;
+		} catch (error) {
+			if (!require_annotations.isInjectedAnnotationWrapper(state)) throw error;
+			return await require_phase2_seed.completeOrExtractPhase2Seed(parser, unwrapInjectedWrapper(state), exec);
+		}
+	};
 	const getInnerSuggestRuntimeNodes = (state, path) => parser.getSuggestRuntimeNodes?.(state, path) ?? (parser.dependencyMetadata?.source != null ? [{
 		path,
 		parser,
@@ -1023,6 +1071,53 @@ function multiple(parser, options = {}) {
 				return validateMultipleResult(values, deferredIndices, hasDeferred);
 			});
 		},
+		[require_phase2_seed.extractPhase2SeedKey](state, exec) {
+			return require_mode_dispatch.dispatchByMode(parser.$mode, () => {
+				const values = [];
+				const deferredIndices = /* @__PURE__ */ new Map();
+				let hasDeferred = false;
+				let hasAnySeed = false;
+				for (let i = 0; i < state.length; i++) {
+					const seed = extractPhase2SeedSyncWithUnwrappedFallback(state[i], withChildExecPath(exec, i));
+					if (seed == null) continue;
+					hasAnySeed = true;
+					values[i] = seed.value;
+					if (seed.deferred) if (seed.deferredKeys) deferredIndices.set(i, seed.deferredKeys);
+					else if (seed.value == null || typeof seed.value !== "object") deferredIndices.set(i, null);
+					else hasDeferred = true;
+				}
+				if (!hasAnySeed) return null;
+				return {
+					value: values,
+					...deferredIndices.size > 0 || hasDeferred ? {
+						deferred: true,
+						...deferredIndices.size > 0 ? { deferredKeys: deferredIndices } : {}
+					} : {}
+				};
+			}, async () => {
+				const values = [];
+				const deferredIndices = /* @__PURE__ */ new Map();
+				let hasDeferred = false;
+				let hasAnySeed = false;
+				for (let i = 0; i < state.length; i++) {
+					const seed = await extractPhase2SeedAsyncWithUnwrappedFallback(state[i], withChildExecPath(exec, i));
+					if (seed == null) continue;
+					hasAnySeed = true;
+					values[i] = seed.value;
+					if (seed.deferred) if (seed.deferredKeys) deferredIndices.set(i, seed.deferredKeys);
+					else if (seed.value == null || typeof seed.value !== "object") deferredIndices.set(i, null);
+					else hasDeferred = true;
+				}
+				if (!hasAnySeed) return null;
+				return {
+					value: values,
+					...deferredIndices.size > 0 || hasDeferred ? {
+						deferred: true,
+						...deferredIndices.size > 0 ? { deferredKeys: deferredIndices } : {}
+					} : {}
+				};
+			});
+		},
 		suggest(context, prefix) {
 			const currentItemState = context.state.at(-1);
 			const canExtendCurrent = currentItemState != null && !isTerminalMultipleItemState(currentItemState);
@@ -1365,6 +1460,13 @@ function nonEmpty(parser) {
 		configurable: true,
 		enumerable: false
 	});
+	Object.defineProperty(nonEmptyParser, require_phase2_seed.extractPhase2SeedKey, {
+		value(state, exec) {
+			return require_phase2_seed.extractPhase2Seed(parser, state, exec);
+		},
+		configurable: true,
+		enumerable: false
+	});
 	if (typeof parser.normalizeValue === "function") Object.defineProperty(nonEmptyParser, "normalizeValue", {
 		value: parser.normalizeValue.bind(parser),
 		configurable: true,