@optique/core 1.4.0-dev.2683 → 1.4.0-dev.2709

package/dist/primitives.cjs

@@ -6,6 +6,7 @@ const require_mode_dispatch = require('./internal/mode-dispatch.cjs');
 const require_internal_dependency = require('./internal/dependency.cjs');
 const require_dependency_runtime = require('./dependency-runtime.cjs');
 const require_annotation_state = require('./annotation-state.cjs');
+const require_empty_input = require('./internal/empty-input.cjs');
 const require_execution_context = require('./execution-context.cjs');
 const require_usage_internals = require('./usage-internals.cjs');
 const require_short_option = require('./short-option.cjs');
@@ -174,6 +175,12 @@ function constant(value) {
 		}
 	};
 	require_passthrough.defineKnownCompletion(result, (state) => require_annotation_state.normalizeInjectedAnnotationState(state));
+	require_empty_input.defineEmptyInputFacts(result, {
+		step: "success",
+		next: require_empty_input.UNCHANGED,
+		afterStep: true,
+		fromInitial: true
+	});
 	Object.defineProperty(result, "placeholder", {
 		value,
 		configurable: true,
@@ -202,7 +209,7 @@ function constant(value) {
 * @since 1.0.0
 */
 function fail() {
-	return require_modifiers.fluent({
+	const result = {
 		$valueType: [],
 		$stateType: [],
 		mode: "sync",
@@ -236,7 +243,9 @@ function fail() {
 				sourceOnly: true
 			};
 		}
-	});
+	};
+	require_empty_input.defineEmptyInputFacts(result, require_empty_input.failingStepFacts(false));
+	return require_modifiers.fluent(result);
 }
 /**
 * Internal helper to get suggestions from a value parser, using dependency values
@@ -794,6 +803,7 @@ function option(...args) {
 		configurable: true,
 		enumerable: false
 	});
+	else require_empty_input.defineEmptyInputFacts(result, require_empty_input.failingStepFacts(valueParser == null));
 	return require_modifiers.fluent(result);
 }
 /**
@@ -983,6 +993,7 @@ function flag(...args) {
 		enumerable: false,
 		writable: false
 	});
+	require_empty_input.defineEmptyInputFacts(result, require_empty_input.failingStepFacts(false));
 	return require_modifiers.fluent(result);
 }
 function normalizeNegatableFlagNameList(names) {
@@ -1395,6 +1406,7 @@ function argument(valueParser, options = {}) {
 		configurable: true,
 		enumerable: false
 	});
+	else require_empty_input.defineEmptyInputFacts(result, require_empty_input.failingStepFacts(false));
 	return require_modifiers.fluent(result);
 }
 function normalizeCommandState(state) {
@@ -1770,9 +1782,11 @@ function command(name, parser, options = {}) {
 		const child = selectChild(state);
 		return child == null ? [] : [child];
 	});
-	return require_modifiers.fluent(require_short_option.scopeParser(result, commandScope.source, (context) => {
+	const scoped = require_short_option.scopeParser(result, commandScope.source, (context) => {
 		if (normalizeCommandState(context.state) != null) commandScope.select(context, enteredScope);
-	}));
+	});
+	require_empty_input.defineEmptyInputFacts(scoped, require_empty_input.failingStepFacts(false));
+	return require_modifiers.fluent(scoped);
 }
 /**
 * Creates a parser that collects unrecognized options and passes them through.
@@ -1963,6 +1977,7 @@ function passThrough(options = {}) {
 		const accepts = format === "equalsOnly" ? equalsOptionPattern.test(token) : format === "nextToken" && optionPattern.test(token);
 		return accepts ? result.priority : void 0;
 	});
+	require_empty_input.defineEmptyInputFacts(result, require_empty_input.failingStepFacts(true));
 	return require_modifiers.fluent(result);
 }
 

package/dist/primitives.js

@@ -6,6 +6,7 @@ import { dispatchByMode, dispatchIterableByMode, wrapForMode } from "./internal/
 import { getDefaultValuesFunction, getDependencyIds, getSnapshottedDefaultDependencyValues, isDerivedValueParser, suggestWithDependency } from "./internal/dependency.js";
 import { effectfulSchedulingNodesKey, exclusiveSourceScopeKey, includeSourceFailureChain, recordDerivedRawInput, replayDerivedParser, replayDerivedParserAsync, sourceCollectionExpansionKey } from "./dependency-runtime.js";
 import { getWrappedChildParseState, getWrappedChildState, isAnnotationWrappedInitialState, normalizeInjectedAnnotationState } from "./annotation-state.js";
+import { UNCHANGED, defineEmptyInputFacts, failingStepFacts } from "./internal/empty-input.js";
 import { mergeChildExec, withChildContext, withChildExecPath } from "./execution-context.js";
 import { extractLeadingCommandNames } from "./usage-internals.js";
 import { attachedValuePrefix, combinedOptionScope, fullNameOwnsToken, prefixSuggestion, scopeParser, selectableOptionScope } from "./short-option.js";
@@ -174,6 +175,12 @@ function constant(value) {
 		}
 	};
 	defineKnownCompletion(result, (state) => normalizeInjectedAnnotationState(state));
+	defineEmptyInputFacts(result, {
+		step: "success",
+		next: UNCHANGED,
+		afterStep: true,
+		fromInitial: true
+	});
 	Object.defineProperty(result, "placeholder", {
 		value,
 		configurable: true,
@@ -202,7 +209,7 @@ function constant(value) {
 * @since 1.0.0
 */
 function fail() {
-	return fluent({
+	const result = {
 		$valueType: [],
 		$stateType: [],
 		mode: "sync",
@@ -236,7 +243,9 @@ function fail() {
 				sourceOnly: true
 			};
 		}
-	});
+	};
+	defineEmptyInputFacts(result, failingStepFacts(false));
+	return fluent(result);
 }
 /**
 * Internal helper to get suggestions from a value parser, using dependency values
@@ -794,6 +803,7 @@ function option(...args) {
 		configurable: true,
 		enumerable: false
 	});
+	else defineEmptyInputFacts(result, failingStepFacts(valueParser == null));
 	return fluent(result);
 }
 /**
@@ -983,6 +993,7 @@ function flag(...args) {
 		enumerable: false,
 		writable: false
 	});
+	defineEmptyInputFacts(result, failingStepFacts(false));
 	return fluent(result);
 }
 function normalizeNegatableFlagNameList(names) {
@@ -1395,6 +1406,7 @@ function argument(valueParser, options = {}) {
 		configurable: true,
 		enumerable: false
 	});
+	else defineEmptyInputFacts(result, failingStepFacts(false));
 	return fluent(result);
 }
 function normalizeCommandState(state) {
@@ -1770,9 +1782,11 @@ function command(name, parser, options = {}) {
 		const child = selectChild(state);
 		return child == null ? [] : [child];
 	});
-	return fluent(scopeParser(result, commandScope.source, (context) => {
+	const scoped = scopeParser(result, commandScope.source, (context) => {
 		if (normalizeCommandState(context.state) != null) commandScope.select(context, enteredScope);
-	}));
+	});
+	defineEmptyInputFacts(scoped, failingStepFacts(false));
+	return fluent(scoped);
 }
 /**
 * Creates a parser that collects unrecognized options and passes them through.
@@ -1963,6 +1977,7 @@ function passThrough(options = {}) {
 		const accepts = format === "equalsOnly" ? equalsOptionPattern.test(token) : format === "nextToken" && optionPattern.test(token);
 		return accepts ? result.priority : void 0;
 	});
+	defineEmptyInputFacts(result, failingStepFacts(true));
 	return fluent(result);
 }
 

package/dist/terminal-internal.cjs

@@ -1,4 +1,5 @@
 const require_displaywidth = require('./displaywidth.cjs');
+const require_terminal_separators = require('./terminal-separators.cjs');
 const require_terminal = require('./terminal.cjs');
 
 //#region src/terminal-internal.ts
@@ -151,6 +152,7 @@ function sameStyle(a, b) {
 }
 function* fragmentTokens(fragment, scopes = [], inherited = {}) {
 	if (fragment.type === "text") {
+		const marks = require_terminal_separators.wrapTrimmableFragments.has(fragment) ? { trimOnWrap: true } : {};
 		const lines = fragment.text.split("\n");
 		for (let i = 0; i < lines.length; i++) {
 			if (i > 0) yield {
@@ -161,7 +163,8 @@ function* fragmentTokens(fragment, scopes = [], inherited = {}) {
 			if (lines[i].length > 0 || lines.length === 1) yield {
 				text: lines[i],
 				width: require_displaywidth.getDisplayWidth(lines[i]),
-				scopes
+				scopes,
+				...marks
 			};
 		}
 		return;

package/dist/terminal-internal.d.cts

@@ -16,6 +16,11 @@ interface TerminalToken {
   readonly programBoundary?: boolean;
   /** Enables only the legacy default formatter whitespace behavior. */
   readonly legacyWhitespace?: boolean;
+  /**
+   * Leading whitespace only separates the token from preceding content, so
+   * message wrapping may drop it when the token starts a wrapped line.
+   */
+  readonly trimOnWrap?: boolean;
 }
 declare function terminalText(text: string): TerminalFragment;
 declare function formatTerminalTerm(term: TerminalTerm, theme?: TerminalTheme, quotes?: boolean, usage?: TerminalFormatContext["usage"]): TerminalFragment;

package/dist/terminal-internal.d.ts

@@ -16,6 +16,11 @@ interface TerminalToken {
   readonly programBoundary?: boolean;
   /** Enables only the legacy default formatter whitespace behavior. */
   readonly legacyWhitespace?: boolean;
+  /**
+   * Leading whitespace only separates the token from preceding content, so
+   * message wrapping may drop it when the token starts a wrapped line.
+   */
+  readonly trimOnWrap?: boolean;
 }
 declare function terminalText(text: string): TerminalFragment;
 declare function formatTerminalTerm(term: TerminalTerm, theme?: TerminalTheme, quotes?: boolean, usage?: TerminalFormatContext["usage"]): TerminalFragment;

package/dist/terminal-internal.js

@@ -1,4 +1,5 @@
 import { getDisplayWidth } from "./displaywidth.js";
+import { wrapTrimmableFragments } from "./terminal-separators.js";
 import { defaultTerminalTheme } from "./terminal.js";
 
 //#region src/terminal-internal.ts
@@ -151,6 +152,7 @@ function sameStyle(a, b) {
 }
 function* fragmentTokens(fragment, scopes = [], inherited = {}) {
 	if (fragment.type === "text") {
+		const marks = wrapTrimmableFragments.has(fragment) ? { trimOnWrap: true } : {};
 		const lines = fragment.text.split("\n");
 		for (let i = 0; i < lines.length; i++) {
 			if (i > 0) yield {
@@ -161,7 +163,8 @@ function* fragmentTokens(fragment, scopes = [], inherited = {}) {
 			if (lines[i].length > 0 || lines.length === 1) yield {
 				text: lines[i],
 				width: getDisplayWidth(lines[i]),
-				scopes
+				scopes,
+				...marks
 			};
 		}
 		return;

package/dist/terminal-separators.cjs

@@ -0,0 +1,13 @@
+
+//#region src/terminal-separators.ts
+/**
+* Text fragments that only separate the items around them, such as the
+* spaces the default `values` formatter puts between values.  When message
+* wrapping moves such a fragment to the start of a new line, its leading
+* whitespace may be dropped.
+* @internal
+*/
+const wrapTrimmableFragments = /* @__PURE__ */ new WeakSet();
+
+//#endregion
+exports.wrapTrimmableFragments = wrapTrimmableFragments;

package/dist/terminal-separators.js

@@ -0,0 +1,12 @@
+//#region src/terminal-separators.ts
+/**
+* Text fragments that only separate the items around them, such as the
+* spaces the default `values` formatter puts between values.  When message
+* wrapping moves such a fragment to the start of a new line, its leading
+* whitespace may be dropped.
+* @internal
+*/
+const wrapTrimmableFragments = /* @__PURE__ */ new WeakSet();
+
+//#endregion
+export { wrapTrimmableFragments };

package/dist/terminal.cjs

@@ -1,3 +1,4 @@
+const require_terminal_separators = require('./terminal-separators.cjs');
 
 //#region src/terminal.ts
 const plain = (text) => ({
@@ -9,6 +10,8 @@ const styled = (text, style) => ({
 	style,
 	children: [plain(text)]
 });
+const valuesSeparator = plain(" ");
+require_terminal_separators.wrapTrimmableFragments.add(valuesSeparator);
 /**
 * Optique's built-in terminal theme, with every formatter available for delegation.
 * @since 1.3.0
@@ -34,7 +37,7 @@ const defaultTerminalTheme = {
 	value: (_term, ctx) => ctx.usage === "literal" ? plain(ctx.text) : styled(ctx.text, { foreground: "green" }),
 	values: (term, ctx) => ({
 		type: "concat",
-		children: term.values.flatMap((value, i) => [...i === 0 ? [] : [plain(" ")], ctx.format({
+		children: term.values.flatMap((value, i) => [...i === 0 ? [] : [valuesSeparator], ctx.format({
 			type: "value",
 			value
 		})])

package/dist/terminal.js

@@ -1,3 +1,5 @@
+import { wrapTrimmableFragments } from "./terminal-separators.js";
+
 //#region src/terminal.ts
 const plain = (text) => ({
 	type: "text",
@@ -8,6 +10,8 @@ const styled = (text, style) => ({
 	style,
 	children: [plain(text)]
 });
+const valuesSeparator = plain(" ");
+wrapTrimmableFragments.add(valuesSeparator);
 /**
 * Optique's built-in terminal theme, with every formatter available for delegation.
 * @since 1.3.0
@@ -33,7 +37,7 @@ const defaultTerminalTheme = {
 	value: (_term, ctx) => ctx.usage === "literal" ? plain(ctx.text) : styled(ctx.text, { foreground: "green" }),
 	values: (term, ctx) => ({
 		type: "concat",
-		children: term.values.flatMap((value, i) => [...i === 0 ? [] : [plain(" ")], ctx.format({
+		children: term.values.flatMap((value, i) => [...i === 0 ? [] : [valuesSeparator], ctx.format({
 			type: "value",
 			value
 		})])

package/dist/text-layout.cjs

@@ -51,6 +51,18 @@ function placeText(text, cursor, maxWidth, trailingRoom = 0) {
 		}
 	};
 }
+const leadingSpacePattern = /^((?:\x1B(?:\[[0-9;:]*[@-~]|\][^\x1B\x07]*(?:\x1B\\|\x07)))*)[^\S\n]+/;
+/**
+* Removes the whitespace that begins a text's first line, keeping any
+* escape sequences before it.  Used when layout moves text that starts with
+* a separating space to a fresh line.
+* @param text Rendered text, possibly containing ANSI styles or OSC links.
+* @returns The text without its leading whitespace.
+* @internal
+*/
+function trimLeadingSpace(text) {
+	return text.replace(leadingSpacePattern, "$1");
+}
 /**
 * Measures an annotation's fixed text without invoking theme callbacks.
 * @param prefix The already joined prefix and optional label.
@@ -84,4 +96,5 @@ function spaceAfterLabel(label) {
 exports.measureAnnotation = measureAnnotation;
 exports.measureText = measureText;
 exports.placeText = placeText;
-exports.spaceAfterLabel = spaceAfterLabel;
+exports.spaceAfterLabel = spaceAfterLabel;
+exports.trimLeadingSpace = trimLeadingSpace;

package/dist/text-layout.d.cts

@@ -41,7 +41,14 @@ declare function placeText(text: string, cursor: TextCursor, maxWidth?: number,
   readonly text: string;
   readonly cursor: TextCursor;
 };
-/** Fixed annotation geometry shared by preflight and placement. @internal */
+/**
+ * Removes the whitespace that begins a text's first line, keeping any
+ * escape sequences before it.  Used when layout moves text that starts with
+ * a separating space to a fresh line.
+ * @param text Rendered text, possibly containing ANSI styles or OSC links.
+ * @returns The text without its leading whitespace.
+ * @internal
+ */
 
 /**
  * Adds a separating space only when a label occupies its final physical line.

package/dist/text-layout.d.ts

@@ -41,7 +41,14 @@ declare function placeText(text: string, cursor: TextCursor, maxWidth?: number,
   readonly text: string;
   readonly cursor: TextCursor;
 };
-/** Fixed annotation geometry shared by preflight and placement. @internal */
+/**
+ * Removes the whitespace that begins a text's first line, keeping any
+ * escape sequences before it.  Used when layout moves text that starts with
+ * a separating space to a fresh line.
+ * @param text Rendered text, possibly containing ANSI styles or OSC links.
+ * @returns The text without its leading whitespace.
+ * @internal
+ */
 
 /**
  * Adds a separating space only when a label occupies its final physical line.

package/dist/text-layout.js

@@ -51,6 +51,18 @@ function placeText(text, cursor, maxWidth, trailingRoom = 0) {
 		}
 	};
 }
+const leadingSpacePattern = /^((?:\x1B(?:\[[0-9;:]*[@-~]|\][^\x1B\x07]*(?:\x1B\\|\x07)))*)[^\S\n]+/;
+/**
+* Removes the whitespace that begins a text's first line, keeping any
+* escape sequences before it.  Used when layout moves text that starts with
+* a separating space to a fresh line.
+* @param text Rendered text, possibly containing ANSI styles or OSC links.
+* @returns The text without its leading whitespace.
+* @internal
+*/
+function trimLeadingSpace(text) {
+	return text.replace(leadingSpacePattern, "$1");
+}
 /**
 * Measures an annotation's fixed text without invoking theme callbacks.
 * @param prefix The already joined prefix and optional label.
@@ -81,4 +93,4 @@ function spaceAfterLabel(label) {
 }
 
 //#endregion
-export { measureAnnotation, measureText, placeText, spaceAfterLabel };
+export { measureAnnotation, measureText, placeText, spaceAfterLabel, trimLeadingSpace };

package/dist/usage.cjs

@@ -1,5 +1,6 @@
 const require_displaywidth = require('./displaywidth.cjs');
 const require_terminal_internal = require('./terminal-internal.cjs');
+const require_internal_usage = require('./internal/usage.cjs');
 const require_validate = require('./validate.cjs');
 
 //#region src/usage.ts
@@ -190,16 +191,33 @@ function formatUsage(programName, usage, options = {}) {
 		theme: require_terminal_internal.cacheTerminalTheme(options.theme)
 	};
 	require_validate.validateProgramName(programName);
-	usage = normalizeUsage(filterUsageForDisplay(usage));
+	return formatUsageLines(programName, normalizeUsage(filterUsageForDisplay(require_internal_usage.resolveUsageForDisplay(usage, isUsageHidden))), normalizeUsage(filterUsageForDisplay(require_internal_usage.forgetEmptyInput(usage))), options);
+}
+/**
+* Formats a display-ready usage, expanding a trailing command group into one
+* line per command when requested.
+* @param programName The program name.
+* @param usage The usage to draw, already resolved, filtered and normalized.
+* @param declared The same usage as declared, without empty-input records,
+*                 filtered and normalized.  It tells a group that was drawn
+*                 as optional because it accepts empty input apart from a
+*                 group declared optional.
+* @param options The formatting options.
+* @returns The formatted usage.
+*/
+function formatUsageLines(programName, usage, declared, options) {
 	if (options.expandCommands) {
-		const lastTerm = usage.at(-1);
+		let lastTerm = usage.at(-1);
+		const declaredLast = declared.at(-1);
+		if (lastTerm?.type === "optional" && lastTerm.terms.length === 1 && lastTerm.terms[0].type === "exclusive" && declaredLast?.type === "exclusive") lastTerm = lastTerm.terms[0];
 		if (usage.length > 0 && usage.slice(0, -1).every((t) => t.type === "command") && lastTerm.type === "exclusive" && lastTerm.terms.every((t) => t.length > 0 && (t[0].type === "command" || t[0].type === "option" || t[0].type === "argument" || t[0].type === "optional" && t[0].terms.length === 1 && (t[0].terms[0].type === "command" || t[0].terms[0].type === "option" || t[0].terms[0].type === "argument")))) {
+			const declaredBranches = declaredLast?.type === "exclusive" && declaredLast.terms.length === lastTerm.terms.length ? declaredLast.terms : void 0;
 			const lines = [];
-			for (let command of lastTerm.terms) {
+			for (const [index, command] of lastTerm.terms.entries()) {
 				const firstTerm = command[0];
 				if (firstTerm?.type === "command" && isUsageHidden(firstTerm.hidden)) continue;
-				if (usage.length > 1) command = [...usage.slice(0, -1), ...command];
-				lines.push(formatUsage(programName, command, options));
+				const line = normalizeUsage(filterUsageForDisplay([...usage.slice(0, -1), ...command]));
+				lines.push(formatUsageLines(programName, line, declaredBranches == null ? line : normalizeUsage(filterUsageForDisplay([...declared.slice(0, -1), ...declaredBranches[index]])), options));
 			}
 			if (lines.length > 0) return lines.join("\n");
 		}
@@ -277,7 +295,8 @@ function normalizeUsageTerm(term) {
 	} else if (term.type === "multiple") return {
 		type: "multiple",
 		terms: normalizeUsage(term.terms),
-		min: term.min
+		min: term.min,
+		...acceptsEmptyOf(term)
 	};
 	else if (term.type === "sequence") return {
 		type: "sequence",
@@ -287,14 +306,15 @@ function normalizeUsageTerm(term) {
 		const terms = [];
 		for (const usage of term.terms) {
 			const normalized = normalizeUsage(usage);
-			if (normalized.length >= 1 && normalized[0].type === "exclusive") {
+			if (normalized.length >= 1 && normalized[0].type === "exclusive" && normalized[0].acceptsEmpty == null) {
 				const rest = normalized.slice(1);
 				for (const subUsage of normalized[0].terms) terms.push([...subUsage, ...rest]);
 			} else if (normalized.length > 0 || !containsMalformedLeaf(usage)) terms.push(normalized);
 		}
 		return {
 			type: "exclusive",
-			terms
+			terms,
+			...acceptsEmptyOf(term)
 		};
 	} else {
 		if (term.type === "option") return {
@@ -311,10 +331,14 @@ function normalizeUsageTerm(term) {
 		return { ...term };
 	}
 }
+function acceptsEmptyOf(term) {
+	return term.acceptsEmpty == null ? {} : { acceptsEmpty: term.acceptsEmpty };
+}
 function isNonDegenerateTerm(term) {
 	if (term.type === "option") return term.names.length > 0;
 	if (term.type === "command") return term.name !== "";
 	if (term.type === "argument") return term.metavar.length > 0;
+	if ((term.type === "multiple" || term.type === "exclusive") && term.acceptsEmpty != null) return true;
 	if (term.type === "optional" || term.type === "multiple" || term.type === "exclusive" || term.type === "sequence") return term.terms.length > 0;
 	return true;
 }
@@ -370,11 +394,13 @@ function cloneUsageTerm(term) {
 		case "multiple": return {
 			type: "multiple",
 			terms: term.terms.map(cloneUsageTerm),
-			min: term.min
+			min: term.min,
+			...acceptsEmptyOf(term)
 		};
 		case "exclusive": return {
 			type: "exclusive",
-			terms: term.terms.map((u) => u.map(cloneUsageTerm))
+			terms: term.terms.map((u) => u.map(cloneUsageTerm)),
+			...acceptsEmptyOf(term)
 		};
 		case "sequence": return {
 			type: "sequence",
@@ -416,7 +442,8 @@ function filterUsageForDisplay(usage, isHidden = isUsageHidden) {
 			if (filtered.length > 0) terms.push({
 				type: "multiple",
 				terms: filtered,
-				min: term.min
+				min: term.min,
+				...acceptsEmptyOf(term)
 			});
 			continue;
 		}
@@ -428,7 +455,8 @@ function filterUsageForDisplay(usage, isHidden = isUsageHidden) {
 			}).filter((branch) => branch.length > 0);
 			if (filteredBranches.length > 0) terms.push({
 				type: "exclusive",
-				terms: filteredBranches
+				terms: filteredBranches,
+				...acceptsEmptyOf(term)
 			});
 			continue;
 		}
@@ -482,7 +510,7 @@ function formatUsageTerm(term, options = {}) {
 		theme: require_terminal_internal.cacheTerminalTheme(options.theme)
 	};
 	const hiddenCheck = options.context === "doc" ? isDocHidden : isUsageHidden;
-	const visibleTerms = filterUsageForDisplay([term], hiddenCheck);
+	const visibleTerms = filterUsageForDisplay(require_internal_usage.resolveUsageForDisplay([term], hiddenCheck), hiddenCheck);
 	if (visibleTerms.length < 1) return "";
 	return wrapUsageTokens(formatUsageTermInternal(visibleTerms[0], options), options);
 }

package/dist/usage.d.cts

@@ -164,6 +164,16 @@ type UsageTerm =
    * The minimum number of times the term must occur.
    */
   readonly min: number;
+  /**
+   * Whether the parser that produced this group succeeds when it parses an
+   * empty argument list on its own.  Built-in combinators set this when
+   * the outcome is statically known and omit it otherwise.  Usage
+   * formatters use it to decide whether to draw the group as omissible;
+   * it is a declaration for display, not evidence about how any other
+   * parser behaves.
+   * @since 1.4.0
+   */
+  readonly acceptsEmpty?: boolean;
 } |
 /**
 * An exclusive term, which represents a group of terms that are mutually
@@ -180,6 +190,16 @@ type UsageTerm =
    * arguments, options, commands, or other usage terms.
    */
   readonly terms: readonly Usage[];
+  /**
+   * Whether the parser that produced this group succeeds when it parses an
+   * empty argument list on its own.  Built-in combinators set this when
+   * the outcome is statically known and omit it otherwise.  Usage
+   * formatters use it to decide whether to draw the group as omissible;
+   * it is a declaration for display, not evidence about how any other
+   * parser behaves.
+   * @since 1.4.0
+   */
+  readonly acceptsEmpty?: boolean;
 }
 /**
  * A sequence term, which preserves the declaration order of its child

package/dist/usage.d.ts

@@ -164,6 +164,16 @@ type UsageTerm =
    * The minimum number of times the term must occur.
    */
   readonly min: number;
+  /**
+   * Whether the parser that produced this group succeeds when it parses an
+   * empty argument list on its own.  Built-in combinators set this when
+   * the outcome is statically known and omit it otherwise.  Usage
+   * formatters use it to decide whether to draw the group as omissible;
+   * it is a declaration for display, not evidence about how any other
+   * parser behaves.
+   * @since 1.4.0
+   */
+  readonly acceptsEmpty?: boolean;
 } |
 /**
 * An exclusive term, which represents a group of terms that are mutually
@@ -180,6 +190,16 @@ type UsageTerm =
    * arguments, options, commands, or other usage terms.
    */
   readonly terms: readonly Usage[];
+  /**
+   * Whether the parser that produced this group succeeds when it parses an
+   * empty argument list on its own.  Built-in combinators set this when
+   * the outcome is statically known and omit it otherwise.  Usage
+   * formatters use it to decide whether to draw the group as omissible;
+   * it is a declaration for display, not evidence about how any other
+   * parser behaves.
+   * @since 1.4.0
+   */
+  readonly acceptsEmpty?: boolean;
 }
 /**
  * A sequence term, which preserves the declaration order of its child