@optique/core 1.4.0-dev.2715 → 1.4.0-dev.2716

package/dist/extension.cjs

@@ -2,6 +2,7 @@ const require_internal_annotations = require('./internal/annotations.cjs');
 const require_mode_dispatch = require('./internal/mode-dispatch.cjs');
 const require_internal_parser = require('./internal/parser.cjs');
 const require_annotation_state = require('./annotation-state.cjs');
+const require_empty_input = require('./internal/empty-input.cjs');
 const require_short_option = require('./short-option.cjs');
 const require_passthrough = require('./internal/passthrough.cjs');
 const require_phase2_seed = require('./phase2-seed.cjs');
@@ -104,15 +105,92 @@ function delegateOptionParsing(wrapper, inner, getInnerState) {
 		state: getInnerState(state)
 	}]);
 }
+/**
+* Declares a parser's static empty-input behavior for usage-group formatting.
+* Facts must hold across runtime annotations and source contexts; omit outcomes
+* that depend on them. These facts do not change parsing or branch eligibility
+* (leadingNames and acceptingAnyToken still determine eligibility).
+*
+* The declaration replaces any prior facts, and an empty object clears them.
+* It is copied and frozen, bound to parse(), complete(), mode and initialState,
+* and not copied by object spread. State getters are bound by identity without
+* invoking them. Declare after finalizing methods and before composing parsers:
+* combinators capture facts and usage at construction. Later closure or in-place
+* state mutations cannot be detected. Initial-state getters must remain cheap,
+* side-effect free and semantically stable.
+*
+* State-shape information remains internal, so a declared successful empty step
+* alone cannot determine whether multiple() retains a repetition item.
+*
+* @param parser The parser to annotate.
+* @param behavior The known outcomes; omitted fields stay unknown.
+* @throws {TypeError} If a value is invalid, afterStep is supplied for a failing
+*                    step, or the metadata cannot be defined or cleared.
+* @since 1.4.0
+*/
+function defineEmptyInputBehavior(parser, behavior) {
+	if (behavior.step !== void 0 && behavior.step !== "success" && behavior.step !== "provisional" && behavior.step !== "failure") throw new TypeError("Invalid empty-input step.");
+	if (behavior.afterStep !== void 0 && typeof behavior.afterStep !== "boolean" || behavior.fromInitial !== void 0 && typeof behavior.fromInitial !== "boolean") throw new TypeError("Empty-input completion outcomes must be booleans.");
+	if (behavior.step === "failure" && behavior.afterStep !== void 0) throw new TypeError("A failing empty-input step has no completion state.");
+	const facts = projectEmptyInputBehavior(behavior);
+	require_empty_input.defineEmptyInputFacts(parser, Object.keys(facts).length < 1 ? {} : {
+		...facts,
+		probe: facts.step === void 0 ? {} : { step: facts.step }
+	});
+}
+/**
+* Reads known empty-input outcomes without executing the parser or its state
+* getter. Returns a frozen object; absent or invalidated facts read as unknown.
+* Internal state-shape information is never exposed.
+* @param parser The parser to inspect.
+* @returns The known public facts, with unknown fields omitted.
+* @since 1.4.0
+*/
+function getEmptyInputBehavior(parser) {
+	return projectEmptyInputBehavior(require_empty_input.getEmptyInputFacts(parser));
+}
+/**
+* Preserves empty-input facts when constructing a transparent parser wrapper.
+* Calling this asserts that the wrapper preserves the three public outcomes.
+* A wrapper that changes completion or empty-step semantics must instead use
+* getEmptyInputBehavior() and defineEmptyInputBehavior() for the valid subset.
+*
+* Internal probe-completion and repetition-state facts are preserved only
+* when parse(),
+* complete(), and the initial-state binding are identical. Spreading a parser
+* with a state getter snapshots its value and loses those facts; preserve
+* its property descriptors or delegate through its prototype to keep the getter.
+* Unknown source facts clear the destination. Finalize both parsers before
+* inheritance and keep them immutable after composing them.
+*
+* @param wrapper The parser receiving the facts.
+* @param inner The parser whose behavior is preserved.
+* @throws {TypeError} If modes differ or metadata cannot be defined or cleared.
+* @since 1.4.0
+*/
+function inheritEmptyInputBehavior(wrapper, inner) {
+	if (wrapper.mode !== inner.mode) throw new TypeError("Cannot inherit empty-input behavior across parser modes.");
+	require_empty_input.inheritEmptyInputFacts(wrapper, inner);
+}
+function projectEmptyInputBehavior(behavior) {
+	return Object.freeze({
+		...behavior.step === void 0 ? {} : { step: behavior.step },
+		...behavior.afterStep === void 0 ? {} : { afterStep: behavior.afterStep },
+		...behavior.fromInitial === void 0 ? {} : { fromInitial: behavior.fromInitial }
+	});
+}
 
 //#endregion
+exports.defineEmptyInputBehavior = defineEmptyInputBehavior;
 exports.defineTraits = defineTraits;
 exports.delegateOptionParsing = delegateOptionParsing;
 exports.delegateSuggestNodes = delegateSuggestNodes;
 exports.dispatchByMode = require_mode_dispatch.dispatchByMode;
 exports.extractPhase2SeedKey = require_phase2_seed.extractPhase2SeedKey;
+exports.getEmptyInputBehavior = getEmptyInputBehavior;
 exports.getTraits = getTraits;
 exports.inheritAnnotations = require_internal_annotations.inheritAnnotations;
+exports.inheritEmptyInputBehavior = inheritEmptyInputBehavior;
 exports.inheritOptionScope = inheritOptionScope$1;
 exports.injectAnnotations = require_internal_annotations.injectAnnotations;
 exports.isInjectedAnnotationState = require_internal_annotations.isInjectedAnnotationState;

package/dist/extension.d.cts

@@ -117,5 +117,80 @@ declare function mapSourceMetadata<M extends Mode, TValue, TState>(parser: Pick<
  * @since 1.0.11
  */
 declare function delegateOptionParsing<TOuterState, TInnerState>(wrapper: Parser<Mode, unknown, TOuterState>, inner: Parser<Mode, unknown, TInnerState>, getInnerState: (state: TOuterState) => TInnerState): void;
+/**
+ * Static, context-independent facts about a parser's empty-input behavior.
+ * An omitted field means unknown. Declarations are trusted without executing
+ * the parser, its sources, or its completion callbacks.
+ *
+ * @since 1.4.0
+ */
+interface EmptyInputBehavior {
+  /**
+   * The outcome of parse() from the initial state with an empty buffer and
+   * options not terminated. "provisional" means success with provisional: true.
+   * No tokens can be consumed from the empty buffer, including on failure.
+   */
+  readonly step?: "success" | "provisional" | "failure";
+  /**
+   * Whether complete() succeeds in the completion phase on the state left by
+   * a successful or provisional empty step. Omit when step is "failure".
+   */
+  readonly afterStep?: boolean;
+  /** Whether complete() succeeds in the completion phase from initialState. */
+  readonly fromInitial?: boolean;
+}
+/**
+ * Declares a parser's static empty-input behavior for usage-group formatting.
+ * Facts must hold across runtime annotations and source contexts; omit outcomes
+ * that depend on them. These facts do not change parsing or branch eligibility
+ * (leadingNames and acceptingAnyToken still determine eligibility).
+ *
+ * The declaration replaces any prior facts, and an empty object clears them.
+ * It is copied and frozen, bound to parse(), complete(), mode and initialState,
+ * and not copied by object spread. State getters are bound by identity without
+ * invoking them. Declare after finalizing methods and before composing parsers:
+ * combinators capture facts and usage at construction. Later closure or in-place
+ * state mutations cannot be detected. Initial-state getters must remain cheap,
+ * side-effect free and semantically stable.
+ *
+ * State-shape information remains internal, so a declared successful empty step
+ * alone cannot determine whether multiple() retains a repetition item.
+ *
+ * @param parser The parser to annotate.
+ * @param behavior The known outcomes; omitted fields stay unknown.
+ * @throws {TypeError} If a value is invalid, afterStep is supplied for a failing
+ *                    step, or the metadata cannot be defined or cleared.
+ * @since 1.4.0
+ */
+declare function defineEmptyInputBehavior(parser: Parser<Mode, unknown, unknown>, behavior: EmptyInputBehavior): void;
+/**
+ * Reads known empty-input outcomes without executing the parser or its state
+ * getter. Returns a frozen object; absent or invalidated facts read as unknown.
+ * Internal state-shape information is never exposed.
+ * @param parser The parser to inspect.
+ * @returns The known public facts, with unknown fields omitted.
+ * @since 1.4.0
+ */
+declare function getEmptyInputBehavior(parser: Parser<Mode, unknown, unknown>): EmptyInputBehavior;
+/**
+ * Preserves empty-input facts when constructing a transparent parser wrapper.
+ * Calling this asserts that the wrapper preserves the three public outcomes.
+ * A wrapper that changes completion or empty-step semantics must instead use
+ * getEmptyInputBehavior() and defineEmptyInputBehavior() for the valid subset.
+ *
+ * Internal probe-completion and repetition-state facts are preserved only
+ * when parse(),
+ * complete(), and the initial-state binding are identical. Spreading a parser
+ * with a state getter snapshots its value and loses those facts; preserve
+ * its property descriptors or delegate through its prototype to keep the getter.
+ * Unknown source facts clear the destination. Finalize both parsers before
+ * inheritance and keep them immutable after composing them.
+ *
+ * @param wrapper The parser receiving the facts.
+ * @param inner The parser whose behavior is preserved.
+ * @throws {TypeError} If modes differ or metadata cannot be defined or cleared.
+ * @since 1.4.0
+ */
+declare function inheritEmptyInputBehavior(wrapper: Parser<Mode, unknown, unknown>, inner: Parser<Mode, unknown, unknown>): void;
 //#endregion
-export { ParserSourceMetadata, ParserTraits, SuggestNode, defineTraits, delegateOptionParsing, delegateSuggestNodes, dispatchByMode, extractPhase2SeedKey, getTraits, inheritAnnotations, inheritOptionScope, injectAnnotations, isInjectedAnnotationState, mapModeValue, mapSourceMetadata, unwrapInjectedAnnotationState, withAnnotationView, wrapForMode };
+export { EmptyInputBehavior, ParserSourceMetadata, ParserTraits, SuggestNode, defineEmptyInputBehavior, defineTraits, delegateOptionParsing, delegateSuggestNodes, dispatchByMode, extractPhase2SeedKey, getEmptyInputBehavior, getTraits, inheritAnnotations, inheritEmptyInputBehavior, inheritOptionScope, injectAnnotations, isInjectedAnnotationState, mapModeValue, mapSourceMetadata, unwrapInjectedAnnotationState, withAnnotationView, wrapForMode };

package/dist/extension.d.ts

@@ -117,5 +117,80 @@ declare function mapSourceMetadata<M extends Mode, TValue, TState>(parser: Pick<
  * @since 1.0.11
  */
 declare function delegateOptionParsing<TOuterState, TInnerState>(wrapper: Parser<Mode, unknown, TOuterState>, inner: Parser<Mode, unknown, TInnerState>, getInnerState: (state: TOuterState) => TInnerState): void;
+/**
+ * Static, context-independent facts about a parser's empty-input behavior.
+ * An omitted field means unknown. Declarations are trusted without executing
+ * the parser, its sources, or its completion callbacks.
+ *
+ * @since 1.4.0
+ */
+interface EmptyInputBehavior {
+  /**
+   * The outcome of parse() from the initial state with an empty buffer and
+   * options not terminated. "provisional" means success with provisional: true.
+   * No tokens can be consumed from the empty buffer, including on failure.
+   */
+  readonly step?: "success" | "provisional" | "failure";
+  /**
+   * Whether complete() succeeds in the completion phase on the state left by
+   * a successful or provisional empty step. Omit when step is "failure".
+   */
+  readonly afterStep?: boolean;
+  /** Whether complete() succeeds in the completion phase from initialState. */
+  readonly fromInitial?: boolean;
+}
+/**
+ * Declares a parser's static empty-input behavior for usage-group formatting.
+ * Facts must hold across runtime annotations and source contexts; omit outcomes
+ * that depend on them. These facts do not change parsing or branch eligibility
+ * (leadingNames and acceptingAnyToken still determine eligibility).
+ *
+ * The declaration replaces any prior facts, and an empty object clears them.
+ * It is copied and frozen, bound to parse(), complete(), mode and initialState,
+ * and not copied by object spread. State getters are bound by identity without
+ * invoking them. Declare after finalizing methods and before composing parsers:
+ * combinators capture facts and usage at construction. Later closure or in-place
+ * state mutations cannot be detected. Initial-state getters must remain cheap,
+ * side-effect free and semantically stable.
+ *
+ * State-shape information remains internal, so a declared successful empty step
+ * alone cannot determine whether multiple() retains a repetition item.
+ *
+ * @param parser The parser to annotate.
+ * @param behavior The known outcomes; omitted fields stay unknown.
+ * @throws {TypeError} If a value is invalid, afterStep is supplied for a failing
+ *                    step, or the metadata cannot be defined or cleared.
+ * @since 1.4.0
+ */
+declare function defineEmptyInputBehavior(parser: Parser<Mode, unknown, unknown>, behavior: EmptyInputBehavior): void;
+/**
+ * Reads known empty-input outcomes without executing the parser or its state
+ * getter. Returns a frozen object; absent or invalidated facts read as unknown.
+ * Internal state-shape information is never exposed.
+ * @param parser The parser to inspect.
+ * @returns The known public facts, with unknown fields omitted.
+ * @since 1.4.0
+ */
+declare function getEmptyInputBehavior(parser: Parser<Mode, unknown, unknown>): EmptyInputBehavior;
+/**
+ * Preserves empty-input facts when constructing a transparent parser wrapper.
+ * Calling this asserts that the wrapper preserves the three public outcomes.
+ * A wrapper that changes completion or empty-step semantics must instead use
+ * getEmptyInputBehavior() and defineEmptyInputBehavior() for the valid subset.
+ *
+ * Internal probe-completion and repetition-state facts are preserved only
+ * when parse(),
+ * complete(), and the initial-state binding are identical. Spreading a parser
+ * with a state getter snapshots its value and loses those facts; preserve
+ * its property descriptors or delegate through its prototype to keep the getter.
+ * Unknown source facts clear the destination. Finalize both parsers before
+ * inheritance and keep them immutable after composing them.
+ *
+ * @param wrapper The parser receiving the facts.
+ * @param inner The parser whose behavior is preserved.
+ * @throws {TypeError} If modes differ or metadata cannot be defined or cleared.
+ * @since 1.4.0
+ */
+declare function inheritEmptyInputBehavior(wrapper: Parser<Mode, unknown, unknown>, inner: Parser<Mode, unknown, unknown>): void;
 //#endregion
-export { ParserSourceMetadata, ParserTraits, SuggestNode, defineTraits, delegateOptionParsing, delegateSuggestNodes, dispatchByMode, extractPhase2SeedKey, getTraits, inheritAnnotations, inheritOptionScope, injectAnnotations, isInjectedAnnotationState, mapModeValue, mapSourceMetadata, unwrapInjectedAnnotationState, withAnnotationView, wrapForMode };
+export { EmptyInputBehavior, ParserSourceMetadata, ParserTraits, SuggestNode, defineEmptyInputBehavior, defineTraits, delegateOptionParsing, delegateSuggestNodes, dispatchByMode, extractPhase2SeedKey, getEmptyInputBehavior, getTraits, inheritAnnotations, inheritEmptyInputBehavior, inheritOptionScope, injectAnnotations, isInjectedAnnotationState, mapModeValue, mapSourceMetadata, unwrapInjectedAnnotationState, withAnnotationView, wrapForMode };

package/dist/extension.js

@@ -2,6 +2,7 @@ import { inheritAnnotations, injectAnnotations, isInjectedAnnotationState, unwra
 import { dispatchByMode, mapModeValue, wrapForMode } from "./internal/mode-dispatch.js";
 import { annotationWrapperRequiresSourceBindingKey, composeWrappedSourceMetadata, defineInheritedAnnotationParser, getDelegatingSuggestRuntimeNodes, inheritParentAnnotationsKey, unmatchedNonCliDependencySourceStateMarker } from "./internal/parser.js";
 import { withAnnotationView } from "./annotation-state.js";
+import { defineEmptyInputFacts, getEmptyInputFacts, inheritEmptyInputFacts } from "./internal/empty-input.js";
 import { inheritOptionScope } from "./short-option.js";
 import { defineReachableChildren } from "./internal/passthrough.js";
 import { extractPhase2SeedKey } from "./phase2-seed.js";
@@ -104,6 +105,80 @@ function delegateOptionParsing(wrapper, inner, getInnerState) {
 		state: getInnerState(state)
 	}]);
 }
+/**
+* Declares a parser's static empty-input behavior for usage-group formatting.
+* Facts must hold across runtime annotations and source contexts; omit outcomes
+* that depend on them. These facts do not change parsing or branch eligibility
+* (leadingNames and acceptingAnyToken still determine eligibility).
+*
+* The declaration replaces any prior facts, and an empty object clears them.
+* It is copied and frozen, bound to parse(), complete(), mode and initialState,
+* and not copied by object spread. State getters are bound by identity without
+* invoking them. Declare after finalizing methods and before composing parsers:
+* combinators capture facts and usage at construction. Later closure or in-place
+* state mutations cannot be detected. Initial-state getters must remain cheap,
+* side-effect free and semantically stable.
+*
+* State-shape information remains internal, so a declared successful empty step
+* alone cannot determine whether multiple() retains a repetition item.
+*
+* @param parser The parser to annotate.
+* @param behavior The known outcomes; omitted fields stay unknown.
+* @throws {TypeError} If a value is invalid, afterStep is supplied for a failing
+*                    step, or the metadata cannot be defined or cleared.
+* @since 1.4.0
+*/
+function defineEmptyInputBehavior(parser, behavior) {
+	if (behavior.step !== void 0 && behavior.step !== "success" && behavior.step !== "provisional" && behavior.step !== "failure") throw new TypeError("Invalid empty-input step.");
+	if (behavior.afterStep !== void 0 && typeof behavior.afterStep !== "boolean" || behavior.fromInitial !== void 0 && typeof behavior.fromInitial !== "boolean") throw new TypeError("Empty-input completion outcomes must be booleans.");
+	if (behavior.step === "failure" && behavior.afterStep !== void 0) throw new TypeError("A failing empty-input step has no completion state.");
+	const facts = projectEmptyInputBehavior(behavior);
+	defineEmptyInputFacts(parser, Object.keys(facts).length < 1 ? {} : {
+		...facts,
+		probe: facts.step === void 0 ? {} : { step: facts.step }
+	});
+}
+/**
+* Reads known empty-input outcomes without executing the parser or its state
+* getter. Returns a frozen object; absent or invalidated facts read as unknown.
+* Internal state-shape information is never exposed.
+* @param parser The parser to inspect.
+* @returns The known public facts, with unknown fields omitted.
+* @since 1.4.0
+*/
+function getEmptyInputBehavior(parser) {
+	return projectEmptyInputBehavior(getEmptyInputFacts(parser));
+}
+/**
+* Preserves empty-input facts when constructing a transparent parser wrapper.
+* Calling this asserts that the wrapper preserves the three public outcomes.
+* A wrapper that changes completion or empty-step semantics must instead use
+* getEmptyInputBehavior() and defineEmptyInputBehavior() for the valid subset.
+*
+* Internal probe-completion and repetition-state facts are preserved only
+* when parse(),
+* complete(), and the initial-state binding are identical. Spreading a parser
+* with a state getter snapshots its value and loses those facts; preserve
+* its property descriptors or delegate through its prototype to keep the getter.
+* Unknown source facts clear the destination. Finalize both parsers before
+* inheritance and keep them immutable after composing them.
+*
+* @param wrapper The parser receiving the facts.
+* @param inner The parser whose behavior is preserved.
+* @throws {TypeError} If modes differ or metadata cannot be defined or cleared.
+* @since 1.4.0
+*/
+function inheritEmptyInputBehavior(wrapper, inner) {
+	if (wrapper.mode !== inner.mode) throw new TypeError("Cannot inherit empty-input behavior across parser modes.");
+	inheritEmptyInputFacts(wrapper, inner);
+}
+function projectEmptyInputBehavior(behavior) {
+	return Object.freeze({
+		...behavior.step === void 0 ? {} : { step: behavior.step },
+		...behavior.afterStep === void 0 ? {} : { afterStep: behavior.afterStep },
+		...behavior.fromInitial === void 0 ? {} : { fromInitial: behavior.fromInitial }
+	});
+}
 
 //#endregion
-export { defineTraits, delegateOptionParsing, delegateSuggestNodes, dispatchByMode, extractPhase2SeedKey, getTraits, inheritAnnotations, inheritOptionScope$1 as inheritOptionScope, injectAnnotations, isInjectedAnnotationState, mapModeValue, mapSourceMetadata, unwrapInjectedAnnotationState, withAnnotationView, wrapForMode };
+export { defineEmptyInputBehavior, defineTraits, delegateOptionParsing, delegateSuggestNodes, dispatchByMode, extractPhase2SeedKey, getEmptyInputBehavior, getTraits, inheritAnnotations, inheritEmptyInputBehavior, inheritOptionScope$1 as inheritOptionScope, injectAnnotations, isInjectedAnnotationState, mapModeValue, mapSourceMetadata, unwrapInjectedAnnotationState, withAnnotationView, wrapForMode };

package/dist/internal/empty-input.cjs

@@ -17,24 +17,50 @@ function resolveEmptyStepState(next, initialState) {
 	return "unchanged" in next ? initialState : next.state(initialState);
 }
 const emptyInputFactsKey = Symbol("emptyInputFacts");
+function initialStateBinding(parser) {
+	let target = parser;
+	while (target != null) {
+		const descriptor = Object.getOwnPropertyDescriptor(target, "initialState");
+		if (descriptor != null) return "value" in descriptor ? {
+			kind: "data",
+			value: descriptor.value
+		} : {
+			kind: "accessor",
+			get: descriptor.get
+		};
+		target = Object.getPrototypeOf(target);
+	}
+	return {
+		kind: "data",
+		value: void 0
+	};
+}
+function sameInitialState(a, b) {
+	return a.kind === "data" && b.kind === "data" ? Object.is(a.value, b.value) : a.kind === "accessor" && b.kind === "accessor" && a.get === b.get;
+}
 const UNKNOWN = Object.freeze({});
 /**
 * Attaches empty-input facts to a parser.  The facts are stored as a
 * non-enumerable property, so object spread does not copy them, and they
 * are bound to the parser's current `parse`, `complete`, and
-* `initialState`, so replacing any of those invalidates them.
+* `initialState`, and mode, so replacing any of those invalidates them.
+* State accessors are bound by getter identity without invoking them.
 * @param parser The parser to annotate.
 * @param facts The facts to attach.
 * @internal
 */
 function defineEmptyInputFacts(parser, facts) {
-	if (Object.keys(facts).length < 1) return;
+	if (Object.keys(facts).length < 1) {
+		if (!Reflect.deleteProperty(parser, emptyInputFactsKey)) throw new TypeError("Cannot clear empty-input facts on this parser.");
+		return;
+	}
 	Object.defineProperty(parser, emptyInputFactsKey, {
 		value: {
-			facts,
+			facts: Object.freeze({ ...facts }),
 			parse: parser.parse,
 			complete: parser.complete,
-			...Object.getOwnPropertyDescriptor(parser, "initialState")?.get == null ? { initialState: { value: parser.initialState } } : {}
+			mode: parser.mode,
+			initialState: initialStateBinding(parser)
 		},
 		configurable: true,
 		enumerable: false,
@@ -49,11 +75,29 @@ function defineEmptyInputFacts(parser, facts) {
 * @internal
 */
 function getEmptyInputFacts(parser) {
+	if (!Object.hasOwn(parser, emptyInputFactsKey)) return UNKNOWN;
 	const stored = parser[emptyInputFactsKey];
-	if (stored == null || stored.parse !== parser.parse || stored.complete !== parser.complete || stored.initialState != null && stored.initialState.value !== parser.initialState) return UNKNOWN;
+	if (stored == null || stored.parse !== parser.parse || stored.complete !== parser.complete || stored.mode !== parser.mode || !sameInitialState(stored.initialState, initialStateBinding(parser))) return UNKNOWN;
 	return stored.facts;
 }
 /**
+* Copies facts for an explicitly transparent wrapper, preserving internal
+* state information only when its execution members match the source.
+* @param wrapper The receiving parser.
+* @param inner The wrapped parser.
+* @internal
+*/
+function inheritEmptyInputFacts(wrapper, inner) {
+	const facts = getEmptyInputFacts(inner);
+	const identical = wrapper.parse === inner.parse && wrapper.complete === inner.complete && sameInitialState(initialStateBinding(wrapper), initialStateBinding(inner));
+	defineEmptyInputFacts(wrapper, identical ? facts : {
+		...Object.keys(facts).length < 1 ? {} : { probe: facts.step === void 0 ? {} : { step: facts.step } },
+		...facts.step === void 0 ? {} : { step: facts.step },
+		...facts.afterStep === void 0 ? {} : { afterStep: facts.afterStep },
+		...facts.fromInitial === void 0 ? {} : { fromInitial: facts.fromInitial }
+	});
+}
+/**
 * Returns whether `parse(parser, [])` succeeds, when that is known from the
 * facts.
 * @param facts The parser's facts.
@@ -109,6 +153,13 @@ function wrapInFreshArray(child, childInitialState) {
 * @internal
 */
 function optionalLikeFacts(child, childInitialState, fromInitial) {
+	const facts = computeOptionalLikeFacts(child, childInitialState, fromInitial);
+	return child.probe !== void 0 ? {
+		...facts,
+		probe: computeOptionalLikeFacts(probeFacts(child), childInitialState, fromInitial)
+	} : facts;
+}
+function computeOptionalLikeFacts(child, childInitialState, fromInitial) {
 	if (child.step === "failure") return {
 		step: "success",
 		next: UNCHANGED,
@@ -134,6 +185,13 @@ function optionalLikeFacts(child, childInitialState, fromInitial) {
 * @internal
 */
 function multipleFacts(child, retainsItem, childInitialState, min) {
+	const facts = computeMultipleFacts(child, retainsItem, childInitialState, min);
+	return child.probe !== void 0 ? {
+		...facts,
+		probe: computeMultipleFacts(probeFacts(child), retainsItem, childInitialState, min)
+	} : facts;
+}
+function computeMultipleFacts(child, retainsItem, childInitialState, min) {
 	const fromInitial = min < 1;
 	if (child.step === "failure") return min < 1 ? {
 		step: "success",
@@ -200,6 +258,16 @@ function exclusiveNextState(index) {
 * @internal
 */
 function orFacts(branches) {
+	const facts = computeOrFacts(branches);
+	return branches.some((c) => c.facts.probe !== void 0) ? {
+		...facts,
+		probe: computeOrFacts(branches.map((b) => ({
+			...b,
+			facts: probeFacts(b.facts)
+		})))
+	} : facts;
+}
+function computeOrFacts(branches) {
 	const candidate = selectZeroInputCandidate(branches);
 	if (candidate === void 0) return {};
 	const fromInitial = exclusiveFromInitial(branches);
@@ -223,6 +291,16 @@ function orFacts(branches) {
 * @internal
 */
 function longestMatchFacts(branches) {
+	const facts = computeLongestMatchFacts(branches);
+	return branches.some((c) => c.facts.probe !== void 0) ? {
+		...facts,
+		probe: computeLongestMatchFacts(branches.map((b) => ({
+			...b,
+			facts: probeFacts(b.facts)
+		})))
+	} : facts;
+}
+function computeLongestMatchFacts(branches) {
 	const fromInitial = exclusiveFromInitial(branches);
 	let best = null;
 	for (let i = 0; i < branches.length; i++) {
@@ -240,7 +318,7 @@ function longestMatchFacts(branches) {
 		fromInitial
 	};
 	return {
-		step: best.facts.step,
+		step: "success",
 		next: exclusiveNextState(best.index),
 		afterStep: best.facts.afterStep,
 		fromInitial
@@ -263,6 +341,16 @@ function all(values) {
 * @internal
 */
 function tupleFacts(children) {
+	const facts = computeTupleFacts(children);
+	return children.some((c) => c.facts.probe !== void 0) ? {
+		...facts,
+		probe: computeTupleFacts(children.map((c) => ({
+			...c,
+			facts: probeFacts(c.facts)
+		})))
+	} : facts;
+}
+function computeTupleFacts(children) {
 	const fromInitial = all(children.map((c) => c.facts.fromInitial));
 	if (children.some((c) => c.facts.step == null)) return {
 		step: "success",
@@ -308,6 +396,20 @@ function objectNextState(changed) {
 * @internal
 */
 function objectFacts(children, keys) {
+	const completion = computeObjectFacts(children, keys);
+	if (!children.some((c) => c.facts.probe !== void 0)) return completion;
+	const probe = computeObjectFacts(children.map((c) => ({
+		...c,
+		facts: probeFacts(c.facts)
+	})), keys);
+	return {
+		...probe,
+		fromInitial: completion.fromInitial,
+		afterStep: probe.step === "success" ? completion.afterStep : void 0,
+		probe
+	};
+}
+function computeObjectFacts(children, keys) {
 	const fromInitial = all(children.map((c) => c.facts.fromInitial));
 	const outcomes = [];
 	const changed = [];
@@ -351,6 +453,9 @@ function withEmptyInputFacts(parser, facts) {
 	defineEmptyInputFacts(parser, facts);
 	return parser;
 }
+function probeFacts(facts) {
+	return facts.probe ?? facts;
+}
 
 //#endregion
 exports.UNCHANGED = UNCHANGED;
@@ -358,6 +463,7 @@ exports.acceptsEmptyInput = acceptsEmptyInput;
 exports.defineEmptyInputFacts = defineEmptyInputFacts;
 exports.failingStepFacts = failingStepFacts;
 exports.getEmptyInputFacts = getEmptyInputFacts;
+exports.inheritEmptyInputFacts = inheritEmptyInputFacts;
 exports.longestMatchFacts = longestMatchFacts;
 exports.multipleFacts = multipleFacts;
 exports.objectFacts = objectFacts;

package/dist/internal/empty-input.js

@@ -16,24 +16,50 @@ function resolveEmptyStepState(next, initialState) {
 	return "unchanged" in next ? initialState : next.state(initialState);
 }
 const emptyInputFactsKey = Symbol("emptyInputFacts");
+function initialStateBinding(parser) {
+	let target = parser;
+	while (target != null) {
+		const descriptor = Object.getOwnPropertyDescriptor(target, "initialState");
+		if (descriptor != null) return "value" in descriptor ? {
+			kind: "data",
+			value: descriptor.value
+		} : {
+			kind: "accessor",
+			get: descriptor.get
+		};
+		target = Object.getPrototypeOf(target);
+	}
+	return {
+		kind: "data",
+		value: void 0
+	};
+}
+function sameInitialState(a, b) {
+	return a.kind === "data" && b.kind === "data" ? Object.is(a.value, b.value) : a.kind === "accessor" && b.kind === "accessor" && a.get === b.get;
+}
 const UNKNOWN = Object.freeze({});
 /**
 * Attaches empty-input facts to a parser.  The facts are stored as a
 * non-enumerable property, so object spread does not copy them, and they
 * are bound to the parser's current `parse`, `complete`, and
-* `initialState`, so replacing any of those invalidates them.
+* `initialState`, and mode, so replacing any of those invalidates them.
+* State accessors are bound by getter identity without invoking them.
 * @param parser The parser to annotate.
 * @param facts The facts to attach.
 * @internal
 */
 function defineEmptyInputFacts(parser, facts) {
-	if (Object.keys(facts).length < 1) return;
+	if (Object.keys(facts).length < 1) {
+		if (!Reflect.deleteProperty(parser, emptyInputFactsKey)) throw new TypeError("Cannot clear empty-input facts on this parser.");
+		return;
+	}
 	Object.defineProperty(parser, emptyInputFactsKey, {
 		value: {
-			facts,
+			facts: Object.freeze({ ...facts }),
 			parse: parser.parse,
 			complete: parser.complete,
-			...Object.getOwnPropertyDescriptor(parser, "initialState")?.get == null ? { initialState: { value: parser.initialState } } : {}
+			mode: parser.mode,
+			initialState: initialStateBinding(parser)
 		},
 		configurable: true,
 		enumerable: false,
@@ -48,11 +74,29 @@ function defineEmptyInputFacts(parser, facts) {
 * @internal
 */
 function getEmptyInputFacts(parser) {
+	if (!Object.hasOwn(parser, emptyInputFactsKey)) return UNKNOWN;
 	const stored = parser[emptyInputFactsKey];
-	if (stored == null || stored.parse !== parser.parse || stored.complete !== parser.complete || stored.initialState != null && stored.initialState.value !== parser.initialState) return UNKNOWN;
+	if (stored == null || stored.parse !== parser.parse || stored.complete !== parser.complete || stored.mode !== parser.mode || !sameInitialState(stored.initialState, initialStateBinding(parser))) return UNKNOWN;
 	return stored.facts;
 }
 /**
+* Copies facts for an explicitly transparent wrapper, preserving internal
+* state information only when its execution members match the source.
+* @param wrapper The receiving parser.
+* @param inner The wrapped parser.
+* @internal
+*/
+function inheritEmptyInputFacts(wrapper, inner) {
+	const facts = getEmptyInputFacts(inner);
+	const identical = wrapper.parse === inner.parse && wrapper.complete === inner.complete && sameInitialState(initialStateBinding(wrapper), initialStateBinding(inner));
+	defineEmptyInputFacts(wrapper, identical ? facts : {
+		...Object.keys(facts).length < 1 ? {} : { probe: facts.step === void 0 ? {} : { step: facts.step } },
+		...facts.step === void 0 ? {} : { step: facts.step },
+		...facts.afterStep === void 0 ? {} : { afterStep: facts.afterStep },
+		...facts.fromInitial === void 0 ? {} : { fromInitial: facts.fromInitial }
+	});
+}
+/**
 * Returns whether `parse(parser, [])` succeeds, when that is known from the
 * facts.
 * @param facts The parser's facts.
@@ -108,6 +152,13 @@ function wrapInFreshArray(child, childInitialState) {
 * @internal
 */
 function optionalLikeFacts(child, childInitialState, fromInitial) {
+	const facts = computeOptionalLikeFacts(child, childInitialState, fromInitial);
+	return child.probe !== void 0 ? {
+		...facts,
+		probe: computeOptionalLikeFacts(probeFacts(child), childInitialState, fromInitial)
+	} : facts;
+}
+function computeOptionalLikeFacts(child, childInitialState, fromInitial) {
 	if (child.step === "failure") return {
 		step: "success",
 		next: UNCHANGED,
@@ -133,6 +184,13 @@ function optionalLikeFacts(child, childInitialState, fromInitial) {
 * @internal
 */
 function multipleFacts(child, retainsItem, childInitialState, min) {
+	const facts = computeMultipleFacts(child, retainsItem, childInitialState, min);
+	return child.probe !== void 0 ? {
+		...facts,
+		probe: computeMultipleFacts(probeFacts(child), retainsItem, childInitialState, min)
+	} : facts;
+}
+function computeMultipleFacts(child, retainsItem, childInitialState, min) {
 	const fromInitial = min < 1;
 	if (child.step === "failure") return min < 1 ? {
 		step: "success",
@@ -199,6 +257,16 @@ function exclusiveNextState(index) {
 * @internal
 */
 function orFacts(branches) {
+	const facts = computeOrFacts(branches);
+	return branches.some((c) => c.facts.probe !== void 0) ? {
+		...facts,
+		probe: computeOrFacts(branches.map((b) => ({
+			...b,
+			facts: probeFacts(b.facts)
+		})))
+	} : facts;
+}
+function computeOrFacts(branches) {
 	const candidate = selectZeroInputCandidate(branches);
 	if (candidate === void 0) return {};
 	const fromInitial = exclusiveFromInitial(branches);
@@ -222,6 +290,16 @@ function orFacts(branches) {
 * @internal
 */
 function longestMatchFacts(branches) {
+	const facts = computeLongestMatchFacts(branches);
+	return branches.some((c) => c.facts.probe !== void 0) ? {
+		...facts,
+		probe: computeLongestMatchFacts(branches.map((b) => ({
+			...b,
+			facts: probeFacts(b.facts)
+		})))
+	} : facts;
+}
+function computeLongestMatchFacts(branches) {
 	const fromInitial = exclusiveFromInitial(branches);
 	let best = null;
 	for (let i = 0; i < branches.length; i++) {
@@ -239,7 +317,7 @@ function longestMatchFacts(branches) {
 		fromInitial
 	};
 	return {
-		step: best.facts.step,
+		step: "success",
 		next: exclusiveNextState(best.index),
 		afterStep: best.facts.afterStep,
 		fromInitial
@@ -262,6 +340,16 @@ function all(values) {
 * @internal
 */
 function tupleFacts(children) {
+	const facts = computeTupleFacts(children);
+	return children.some((c) => c.facts.probe !== void 0) ? {
+		...facts,
+		probe: computeTupleFacts(children.map((c) => ({
+			...c,
+			facts: probeFacts(c.facts)
+		})))
+	} : facts;
+}
+function computeTupleFacts(children) {
 	const fromInitial = all(children.map((c) => c.facts.fromInitial));
 	if (children.some((c) => c.facts.step == null)) return {
 		step: "success",
@@ -307,6 +395,20 @@ function objectNextState(changed) {
 * @internal
 */
 function objectFacts(children, keys) {
+	const completion = computeObjectFacts(children, keys);
+	if (!children.some((c) => c.facts.probe !== void 0)) return completion;
+	const probe = computeObjectFacts(children.map((c) => ({
+		...c,
+		facts: probeFacts(c.facts)
+	})), keys);
+	return {
+		...probe,
+		fromInitial: completion.fromInitial,
+		afterStep: probe.step === "success" ? completion.afterStep : void 0,
+		probe
+	};
+}
+function computeObjectFacts(children, keys) {
 	const fromInitial = all(children.map((c) => c.facts.fromInitial));
 	const outcomes = [];
 	const changed = [];
@@ -350,6 +452,9 @@ function withEmptyInputFacts(parser, facts) {
 	defineEmptyInputFacts(parser, facts);
 	return parser;
 }
+function probeFacts(facts) {
+	return facts.probe ?? facts;
+}
 
 //#endregion
-export { UNCHANGED, acceptsEmptyInput, defineEmptyInputFacts, failingStepFacts, getEmptyInputFacts, longestMatchFacts, multipleFacts, objectFacts, optionalLikeFacts, orFacts, resolveEmptyStepState, tupleFacts, withEmptyInputFacts };
+export { UNCHANGED, acceptsEmptyInput, defineEmptyInputFacts, failingStepFacts, getEmptyInputFacts, inheritEmptyInputFacts, longestMatchFacts, multipleFacts, objectFacts, optionalLikeFacts, orFacts, resolveEmptyStepState, tupleFacts, withEmptyInputFacts };

package/dist/modifiers.cjs

@@ -945,6 +945,12 @@ function map(parser, transform) {
 	require_dependency_runtime.defineForwardedEffectfulSchedulingNodes(mappedParser, parser);
 	const innerFacts = require_empty_input.getEmptyInputFacts(parser);
 	require_empty_input.defineEmptyInputFacts(mappedParser, {
+		...innerFacts.probe == null ? {} : { probe: {
+			step: innerFacts.probe.step,
+			next: innerFacts.probe.next,
+			...innerFacts.probe.afterStep === false ? { afterStep: false } : {},
+			...innerFacts.probe.fromInitial === false ? { fromInitial: false } : {}
+		} },
 		...innerFacts.step == null ? {} : { step: innerFacts.step },
 		...innerFacts.next == null ? {} : { next: innerFacts.next },
 		...innerFacts.afterStep === false ? { afterStep: false } : {},
@@ -1928,6 +1934,10 @@ function nonEmpty(parser) {
 	const scopedNonEmptyParser = require_short_option.scopeParser(nonEmptyParser, require_short_option.combinedOptionScope([parser]));
 	const innerFacts = require_empty_input.getEmptyInputFacts(parser);
 	require_empty_input.defineEmptyInputFacts(scopedNonEmptyParser, {
+		...innerFacts.probe == null ? {} : { probe: {
+			step: "failure",
+			fromInitial: innerFacts.probe.fromInitial
+		} },
 		step: "failure",
 		...innerFacts.fromInitial == null ? {} : { fromInitial: innerFacts.fromInitial }
 	});

package/dist/modifiers.js

@@ -945,6 +945,12 @@ function map(parser, transform) {
 	defineForwardedEffectfulSchedulingNodes(mappedParser, parser);
 	const innerFacts = getEmptyInputFacts(parser);
 	defineEmptyInputFacts(mappedParser, {
+		...innerFacts.probe == null ? {} : { probe: {
+			step: innerFacts.probe.step,
+			next: innerFacts.probe.next,
+			...innerFacts.probe.afterStep === false ? { afterStep: false } : {},
+			...innerFacts.probe.fromInitial === false ? { fromInitial: false } : {}
+		} },
 		...innerFacts.step == null ? {} : { step: innerFacts.step },
 		...innerFacts.next == null ? {} : { next: innerFacts.next },
 		...innerFacts.afterStep === false ? { afterStep: false } : {},
@@ -1928,6 +1934,10 @@ function nonEmpty(parser) {
 	const scopedNonEmptyParser = scopeParser(nonEmptyParser, combinedOptionScope([parser]));
 	const innerFacts = getEmptyInputFacts(parser);
 	defineEmptyInputFacts(scopedNonEmptyParser, {
+		...innerFacts.probe == null ? {} : { probe: {
+			step: "failure",
+			fromInitial: innerFacts.probe.fromInitial
+		} },
 		step: "failure",
 		...innerFacts.fromInitial == null ? {} : { fromInitial: innerFacts.fromInitial }
 	});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.4.0-dev.2715",
+  "version": "1.4.0-dev.2716",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -245,7 +245,7 @@
   },
   "sideEffects": false,
   "devDependencies": {
-    "@optique/env": "1.4.0-dev.2715+f162fe0e",
+    "@optique/env": "1.4.0-dev.2716+57cbdb77",
     "@types/node": "^24.0.0",
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",

package/skills/optique/SKILL.md

@@ -234,9 +234,11 @@ Common mistakes checklist
 
  -  Pass parsers to `run()` for apps; use explicit argument arrays with
     `parse()` in tests and embedded use. Do not pre-parse `process.argv`.
- -  Do not treat `or(a, b)` as “zero or more alternatives.” It requires one
-    matching branch unless the whole `or()` is wrapped in `optional()` or
-    `withDefault()`.
+ -  Declare only static facts with `defineEmptyInputBehavior()` in
+    `@optique/core/extension`; use `inheritEmptyInputBehavior()` for
+    transparent wrappers. See <https://optique.dev/concepts/extend.md>.
+ -  Do not treat `or(a, b)` as “zero or more alternatives.” Wrap it in
+    `optional()` or `withDefault()` to allow no matching branch.
  -  Do not use `object()` for mutually exclusive subcommands. Use
     `or(command(...), command(...))`.
  -  Do not forget that `flag("--x")` is required. Wrap it in `optional()` or
@@ -252,10 +254,8 @@ Common mistakes checklist
  -  Enable `showEnvironment` for env-only help; set `documentation.description`.
  -  Keep multi-level dependency graphs with `dependency()` rather than
     duplicating one-level factories.
- -  Do not probe runtime capabilities eagerly before constructing a prompt
-    parser. Put synchronous or asynchronous checks in the prompt config's
-    `when` field and provide a typed `otherwise` value. The check then runs
-    only if parsing reaches the prompt fallback.
+ -  Put runtime prompt checks in `when`, with typed `otherwise`; evaluate them
+    only at fallback, never eagerly during construction.
 
 For the detailed maintained guide, use <https://optique.dev/pitfalls.md>.