@optique/core 1.3.0-dev.2379 → 1.3.0-dev.2380

package/dist/dependency-runtime.d.ts

@@ -1,6 +1,9 @@
+import { Message } from "./message.js";
 import { DependencyRegistryLike } from "./registry-types.js";
 import { ValueParserResult } from "./valueparser.js";
 import { ParserDependencyMetadata } from "./dependency-metadata.js";
+import { InputTrace } from "./input-trace.js";
+import { ExecutionContext } from "./internal/parser.js";
 
 //#region src/dependency-runtime.d.ts
 
@@ -255,6 +258,164 @@ declare function replayDerivedParserAsync(node: RuntimeNode, rawInput: string, r
  * @since 1.0.0
  */
 declare function extractRawInputFromState(state: unknown): string | undefined;
+/**
+ * Internal parser hook for constructs whose effectful scheduling nodes
+ * cannot be derived from flattened field pairs alone.
+ *
+ * `merge()` installs it so a parent's scheduling expansion uses the same
+ * child-indexed paths, declaration order, and duplicate-field exclusion
+ * as the merge's own scheduling pass; `or()`/`longestMatch()` install it
+ * to expose the committed branch; `command()` installs it to expose its
+ * inner parser once the command has matched.  The returned node paths
+ * must match the execution paths used when the same parsers complete, so
+ * the run-scoped completion cache lines up.
+ *
+ * @internal
+ * @since 1.3.0
+ */
+declare const effectfulSchedulingNodesKey: unique symbol;
+/**
+ * The shape of the {@link effectfulSchedulingNodesKey} hook.
+ *
+ * @internal
+ * @since 1.3.0
+ */
+type EffectfulSchedulingNodesFn = (state: unknown, parentPath: readonly PropertyKey[] | undefined) => readonly RuntimeNode[];
+/**
+ * Forwards effectful scheduling through a shape-preserving wrapper such
+ * as `map()`, `optional()`, `withDefault()`, or `nonEmpty()`, so the
+ * wrapped parser—a selected exclusive or command branch, or an ordinary
+ * construct with nested effectful sources—stays visible to a parent
+ * construct's scheduling expansion.
+ *
+ * The installed hook simply re-exposes the inner parser as a node with
+ * the wrapper's own state shape unwrapped (`adaptState`, e.g. the
+ * `[innerState]` array used by `optional()`/`withDefault()`); the
+ * expansion then applies its ordinary rules to the inner parser, whether
+ * it carries its own hook, flattened field pairs, or source metadata.
+ * Wrappers are path-transparent, so the node keeps the wrapper's path.
+ *
+ * @internal
+ * @since 1.3.0
+ */
+declare function defineForwardedEffectfulSchedulingNodes(wrapper: object, inner: {
+  readonly dependencyMetadata?: ParserDependencyMetadata;
+}, adaptState?: (state: unknown) => unknown): void;
+/**
+ * A completed effectful source result to be reused by the owning
+ * construct's final completion phase, keyed by the node's last path
+ * segment (its field key or tuple index).
+ *
+ * @internal
+ * @since 1.3.0
+ */
+interface EffectfulSourceCompletion {
+  /** The node's field key or index (its last path segment). */
+  readonly key: PropertyKey;
+  /** The effectful completion result. */
+  readonly result: ValueParserResult<unknown>;
+}
+/**
+ * The result of scheduling effectful source completions.
+ *
+ * @internal
+ * @since 1.3.0
+ */
+type EffectfulSourceCompletionResult = {
+  readonly success: true;
+  readonly completed: readonly EffectfulSourceCompletion[];
+} | {
+  readonly success: false;
+  readonly error: Message;
+};
+/**
+ * Collects the dependency source IDs demanded by consumers among the
+ * given nodes and state subtree.
+ *
+ * A consumer demands its sources when it has raw input evidence: either a
+ * trace entry recorded at its path during parsing, or a legacy
+ * `DeferredParseState` embedded in the state subtree.  Consumers without
+ * raw input never replay against real dependency values, so their sources
+ * are not demanded.
+ *
+ * @param nodes The direct-child runtime nodes of the owning construct.
+ * @param state The construct's state subtree (for legacy deferred states).
+ * @param trace The input trace recorded during parsing.
+ * @returns The set of demanded dependency source IDs.
+ * @internal
+ * @since 1.3.0
+ */
+declare function collectDemandedDependencyIds(nodes: readonly RuntimeNode[], state: unknown, trace: InputTrace | undefined): ReadonlySet<symbol>;
+/**
+ * Options for {@link completeEffectfulSourcesAsync}.
+ *
+ * @internal
+ * @since 1.3.0
+ */
+interface CompleteEffectfulSourcesOptions {
+  /**
+   * Nodes used for demand detection instead of the scheduled nodes.
+   * Constructs whose parse-time trace paths differ from their scheduling
+   * node paths (e.g., `merge()`, which records child-indexed paths but
+   * schedules flattened field nodes) pass path-corrected nodes here.
+   */
+  readonly demandNodes?: readonly RuntimeNode[];
+  /**
+   * Whether a node's completion result may be cached by the owning
+   * construct for reuse in its final completion phase.  Defaults to
+   * treating every node as reusable.  Non-reusable completions (nodes
+   * expanded from nested children, or sources whose field value differs
+   * from the source value) rely on the run-scoped session cache to avoid
+   * running twice, and are skipped when no session is available.
+   */
+  readonly isReusable?: (node: RuntimeNode) => boolean;
+}
+/**
+ * Runs effectful source completions (e.g., interactive prompts) serially
+ * in declaration order for source nodes whose value is not yet registered.
+ *
+ * This is the scheduling half of the `completeSource` capability contract:
+ *
+ * - Runs only during real completion (`exec.phase === "complete"`); probe
+ *   and suggest phases return immediately without effects.
+ * - Precedence is structural: a source whose value was registered before
+ *   the pass begins (from CLI state, environment, configuration, or a
+ *   default) or that has already failed is never completed effectfully.
+ *   When several scheduled occurrences share one source, each occurrence
+ *   still completes and re-registers, so the last occurrence wins—the
+ *   same rule as repeated command-line source occurrences.
+ * - Completion results that are `undefined` or marked `deferred` are
+ *   treated as declined and neither registered nor cached.
+ * - A successful result registers its value unless the value is
+ *   `undefined`.  When the node is reusable (a direct child whose field
+ *   value is the source value), the result is also returned for reuse by
+ *   the owning construct so the node is not completed twice; otherwise the
+ *   effectful parser's own run-scoped session cache prevents a second
+ *   execution, so nodes that are not reusable are only scheduled when a
+ *   session is present.  For a source behind a transform such as `map()`
+ *   (`preservesSourceValue: false`), the `completeSource` contract still
+ *   yields the pre-transform source value, so registration stays correct
+ *   while the field's final value is produced separately.
+ * - A failed result (e.g., a cancelled prompt) marks the source as failed
+ *   and aborts immediately—later effectful completions do not run.
+ *
+ * When the run-scoped session policy is `"demand-only"` (the phase-two
+ * seed pass), the demanded source IDs from
+ * {@link collectDemandedDependencyIds} are added to the session before any
+ * completion runs, letting effectful parsers defer when no phase-one
+ * consumer demands their value.
+ *
+ * @param nodes The runtime nodes to schedule, in declaration order.
+ * @param state The construct's state subtree (for demand detection).
+ * @param runtime The dependency runtime context.
+ * @param exec The execution context of the owning construct.
+ * @param options Scheduling options.
+ * @returns The scheduling result: completed nodes for reuse, or the first
+ *   failure.
+ * @internal
+ * @since 1.3.0
+ */
+declare function completeEffectfulSourcesAsync(nodes: readonly RuntimeNode[], state: unknown, runtime: DependencyRuntimeContext, exec: ExecutionContext | undefined, options?: CompleteEffectfulSourcesOptions): Promise<EffectfulSourceCompletionResult>;
 /**
  * Recursively collects dependency source values from {@link DependencySourceState}
  * objects found in the state tree and registers them in the runtime.
@@ -334,4 +495,4 @@ declare function buildRuntimeNodesFromArray(parsers: ReadonlyArray<{
   readonly initialState?: unknown;
 }>, stateArray: readonly unknown[], parentPath?: readonly PropertyKey[]): readonly RuntimeNode[];
 //#endregion
-export { DependencyRequest, DependencyResolution, DependencyRuntimeContext, ReplayKey, RuntimeNode, SourceDefaultFailure, buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, createDependencyFingerprint, createDependencyRuntimeContext, createReplayKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, replayDerivedParser, replayDerivedParserAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync };
+export { CompleteEffectfulSourcesOptions, DependencyRequest, DependencyResolution, DependencyRuntimeContext, EffectfulSchedulingNodesFn, EffectfulSourceCompletion, EffectfulSourceCompletionResult, ReplayKey, RuntimeNode, SourceDefaultFailure, buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectDemandedDependencyIds, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, completeEffectfulSourcesAsync, createDependencyFingerprint, createDependencyRuntimeContext, createReplayKey, defineForwardedEffectfulSchedulingNodes, effectfulSchedulingNodesKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, replayDerivedParser, replayDerivedParserAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync };

package/dist/dependency-runtime.js

@@ -478,6 +478,218 @@ function extractRawInputFromState(state) {
 	return void 0;
 }
 /**
+* Internal parser hook for constructs whose effectful scheduling nodes
+* cannot be derived from flattened field pairs alone.
+*
+* `merge()` installs it so a parent's scheduling expansion uses the same
+* child-indexed paths, declaration order, and duplicate-field exclusion
+* as the merge's own scheduling pass; `or()`/`longestMatch()` install it
+* to expose the committed branch; `command()` installs it to expose its
+* inner parser once the command has matched.  The returned node paths
+* must match the execution paths used when the same parsers complete, so
+* the run-scoped completion cache lines up.
+*
+* @internal
+* @since 1.3.0
+*/
+const effectfulSchedulingNodesKey = Symbol("@optique/core/dependency-runtime/effectfulSchedulingNodes");
+/**
+* Forwards effectful scheduling through a shape-preserving wrapper such
+* as `map()`, `optional()`, `withDefault()`, or `nonEmpty()`, so the
+* wrapped parser—a selected exclusive or command branch, or an ordinary
+* construct with nested effectful sources—stays visible to a parent
+* construct's scheduling expansion.
+*
+* The installed hook simply re-exposes the inner parser as a node with
+* the wrapper's own state shape unwrapped (`adaptState`, e.g. the
+* `[innerState]` array used by `optional()`/`withDefault()`); the
+* expansion then applies its ordinary rules to the inner parser, whether
+* it carries its own hook, flattened field pairs, or source metadata.
+* Wrappers are path-transparent, so the node keeps the wrapper's path.
+*
+* @internal
+* @since 1.3.0
+*/
+function defineForwardedEffectfulSchedulingNodes(wrapper, inner, adaptState) {
+	if (inner.dependencyMetadata?.source != null) return;
+	Object.defineProperty(wrapper, effectfulSchedulingNodesKey, {
+		value: ((state, parentPath) => [{
+			path: parentPath ?? [],
+			parser: inner,
+			state: adaptState == null ? state : adaptState(state)
+		}]),
+		configurable: true,
+		enumerable: false
+	});
+}
+/**
+* Collects the dependency source IDs demanded by consumers among the
+* given nodes and state subtree.
+*
+* A consumer demands its sources when it has raw input evidence: either a
+* trace entry recorded at its path during parsing, or a legacy
+* `DeferredParseState` embedded in the state subtree.  Consumers without
+* raw input never replay against real dependency values, so their sources
+* are not demanded.
+*
+* @param nodes The direct-child runtime nodes of the owning construct.
+* @param state The construct's state subtree (for legacy deferred states).
+* @param trace The input trace recorded during parsing.
+* @returns The set of demanded dependency source IDs.
+* @internal
+* @since 1.3.0
+*/
+function collectDemandedDependencyIds(nodes, state, trace) {
+	const demanded = /* @__PURE__ */ new Set();
+	for (const node of nodes) {
+		const derived = node.parser.dependencyMetadata?.derived;
+		if (derived == null) continue;
+		const hasRawInput = trace?.get(node.path)?.rawInput != null || extractRawInputFromState(node.state) != null;
+		if (!hasRawInput) continue;
+		for (const id of derived.dependencyIds) demanded.add(id);
+	}
+	collectDeferredDemand(state, demanded, /* @__PURE__ */ new WeakSet());
+	return demanded;
+}
+function collectDeferredDemand(state, demanded, visited) {
+	if (state == null || typeof state !== "object") return;
+	if (visited.has(state)) return;
+	visited.add(state);
+	if (isDeferredParseState(state)) {
+		const ids = state.dependencyIds != null && state.dependencyIds.length > 0 ? state.dependencyIds : [state.dependencyId];
+		for (const id of ids) demanded.add(id);
+		return;
+	}
+	for (const key of Reflect.ownKeys(state)) collectDeferredDemand(state[key], demanded, visited);
+}
+/**
+* Runs effectful source completions (e.g., interactive prompts) serially
+* in declaration order for source nodes whose value is not yet registered.
+*
+* This is the scheduling half of the `completeSource` capability contract:
+*
+* - Runs only during real completion (`exec.phase === "complete"`); probe
+*   and suggest phases return immediately without effects.
+* - Precedence is structural: a source whose value was registered before
+*   the pass begins (from CLI state, environment, configuration, or a
+*   default) or that has already failed is never completed effectfully.
+*   When several scheduled occurrences share one source, each occurrence
+*   still completes and re-registers, so the last occurrence wins—the
+*   same rule as repeated command-line source occurrences.
+* - Completion results that are `undefined` or marked `deferred` are
+*   treated as declined and neither registered nor cached.
+* - A successful result registers its value unless the value is
+*   `undefined`.  When the node is reusable (a direct child whose field
+*   value is the source value), the result is also returned for reuse by
+*   the owning construct so the node is not completed twice; otherwise the
+*   effectful parser's own run-scoped session cache prevents a second
+*   execution, so nodes that are not reusable are only scheduled when a
+*   session is present.  For a source behind a transform such as `map()`
+*   (`preservesSourceValue: false`), the `completeSource` contract still
+*   yields the pre-transform source value, so registration stays correct
+*   while the field's final value is produced separately.
+* - A failed result (e.g., a cancelled prompt) marks the source as failed
+*   and aborts immediately—later effectful completions do not run.
+*
+* When the run-scoped session policy is `"demand-only"` (the phase-two
+* seed pass), the demanded source IDs from
+* {@link collectDemandedDependencyIds} are added to the session before any
+* completion runs, letting effectful parsers defer when no phase-one
+* consumer demands their value.
+*
+* @param nodes The runtime nodes to schedule, in declaration order.
+* @param state The construct's state subtree (for demand detection).
+* @param runtime The dependency runtime context.
+* @param exec The execution context of the owning construct.
+* @param options Scheduling options.
+* @returns The scheduling result: completed nodes for reuse, or the first
+*   failure.
+* @internal
+* @since 1.3.0
+*/
+async function completeEffectfulSourcesAsync(nodes, state, runtime, exec, options) {
+	const empty = {
+		success: true,
+		completed: []
+	};
+	if (exec == null || exec.phase !== "complete") return empty;
+	const session = exec.effectfulCompletionSession;
+	if (session?.policy === "demand-only") {
+		const demandNodes = options?.demandNodes ?? nodes;
+		const demanded = collectDemandedDependencyIds(demandNodes, state, exec.trace);
+		for (const id of demanded) session.demanded.add(id);
+	}
+	if (session != null) {
+		for (const result of session.results.values()) if (!result.success) return {
+			success: false,
+			error: result.error
+		};
+	}
+	const schedulable = nodes.filter((node) => node.parser.dependencyMetadata?.source?.completeSource != null);
+	if (schedulable.length === 0) return empty;
+	const preexisting = /* @__PURE__ */ new Set();
+	for (const node of schedulable) {
+		const source = node.parser.dependencyMetadata?.source;
+		if (source != null && runtime.hasSource(source.sourceId) && session?.effectfulSources.has(source.sourceId) !== true) preexisting.add(source.sourceId);
+	}
+	const completed = [];
+	for (const node of schedulable) {
+		const source = node.parser.dependencyMetadata?.source;
+		if (source?.completeSource == null) continue;
+		const pathKey = serializeSchedulingPath(node.path);
+		const priorResult = session?.completedByPath.get(pathKey);
+		if (priorResult != null) {
+			if (source.preservesSourceValue && (options?.isReusable?.(node) ?? true)) completed.push({
+				key: node.path[node.path.length - 1],
+				result: priorResult
+			});
+			continue;
+		}
+		if (preexisting.has(source.sourceId)) continue;
+		const reusable = source.preservesSourceValue && (options?.isReusable?.(node) ?? true);
+		if (!reusable && session == null) continue;
+		const childExec = {
+			...exec,
+			path: node.path
+		};
+		const result = await source.completeSource(node.state, childExec);
+		if (result == null) continue;
+		if (!result.success) {
+			runtime.markSourceFailed(source.sourceId);
+			return {
+				success: false,
+				error: result.error
+			};
+		}
+		if (result.deferred === true) continue;
+		session?.completedByPath.set(pathKey, result);
+		if (reusable) completed.push({
+			key: node.path[node.path.length - 1],
+			result
+		});
+		if (result.value !== void 0) runtime.registerSource(source.sourceId, result.value);
+	}
+	return {
+		success: true,
+		completed
+	};
+}
+/**
+* Serializes a scheduling node path into a stable string key, using
+* length-prefixed segments so no separator escaping is needed.
+*/
+function serializeSchedulingPath(path) {
+	return path.map((segment) => {
+		if (typeof segment === "symbol") {
+			const key = stableSymbolKey(segment);
+			return `y${key.length}:${key}`;
+		}
+		const tag = typeof segment === "number" ? "n" : "s";
+		const text = String(segment);
+		return `${tag}${text.length}:${text}`;
+	}).join("");
+}
+/**
 * Checks if a value is a plain object (not a class instance) for the
 * purpose of recursive state traversal.
 */
@@ -717,4 +929,4 @@ function buildRuntimeNodesFromArray(parsers, stateArray, parentPath) {
 }
 
 //#endregion
-export { buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, createDependencyFingerprint, createDependencyRuntimeContext, createReplayKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, replayDerivedParser, replayDerivedParserAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync };
+export { buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectDemandedDependencyIds, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, completeEffectfulSourcesAsync, createDependencyFingerprint, createDependencyRuntimeContext, createReplayKey, defineForwardedEffectfulSchedulingNodes, effectfulSchedulingNodesKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, replayDerivedParser, replayDerivedParserAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync };

package/dist/doc.cjs

@@ -213,6 +213,7 @@ function defaultSectionOrder(a, b) {
 function formatDocPage(programName, page, options = {}) {
 	require_validate.validateProgramName(programName);
 	const termIndent = options.termIndent ?? 2;
+	const termWidth = options.termWidth ?? 26;
 	const showUsage = options.showUsage ?? true;
 	if (options.maxWidth != null && (!Number.isFinite(options.maxWidth) || !Number.isInteger(options.maxWidth))) throw new TypeError(`maxWidth must be a finite integer, got ${options.maxWidth}.`);
 	const filteredSections = page.sections.map((s) => ({
@@ -231,32 +232,9 @@ function formatDocPage(programName, page, options = {}) {
 		if (maxItems < 1) throw new RangeError(`showChoices.maxItems must be at least 1, but got ${maxItems}.`);
 	}
 	const hasContent = (msg) => Array.isArray(msg) && msg.length > 0;
-	const needsDescriptionColumn = (entry) => hasContent(entry.description) || (options.showDefault === true || typeof options.showDefault === "object") && hasContent(entry.default) || (options.showChoices === true || typeof options.showChoices === "object") && hasContent(entry.choices);
-	const automaticTermWidth = () => {
-		let widest;
-		for (const section of page.sections) for (const entry of section.entries) {
-			if (!needsDescriptionColumn(entry)) continue;
-			const rendered = require_usage.formatUsageTerm(entry.term, {
-				colors: options.colors,
-				optionsSeparator: ", ",
-				context: "doc"
-			});
-			const width = Math.max(...rendered.split("\n").map((line) => require_displaywidth.getDisplayWidth(line)));
-			widest = widest == null ? width : Math.max(widest, width);
-		}
-		return widest;
-	};
-	const termWidth = options.termWidth === "auto" ? automaticTermWidth() ?? 26 : options.termWidth ?? 26;
-	const hasEntries = page.sections.some((s) => s.entries.length > 0);
-	const needsDescColumn = hasEntries && page.sections.some((s) => s.entries.some(needsDescriptionColumn));
-	let effectiveTermWidth;
-	if (options.maxWidth == null) effectiveTermWidth = termWidth;
-	else {
-		const availableForColumns = options.maxWidth - termIndent - 2;
-		const evenlySplitTermWidth = Math.max(1, Math.floor(availableForColumns / 2));
-		effectiveTermWidth = options.termWidth === "auto" && needsDescColumn ? Math.min(termWidth, evenlySplitTermWidth) : availableForColumns >= termWidth + 1 ? termWidth : evenlySplitTermWidth;
-	}
 	if (options.maxWidth != null) {
+		const hasEntries = page.sections.some((s) => s.entries.length > 0);
+		const needsDescColumn = hasEntries && page.sections.some((s) => s.entries.some((e) => hasContent(e.description) || options.showDefault && hasContent(e.default) || options.showChoices && hasContent(e.choices)));
 		let minDescWidth = 1;
 		if (needsDescColumn) {
 			if (options.showDefault && page.sections.some((s) => s.entries.some((e) => hasContent(e.default)))) {
@@ -282,13 +260,20 @@ function formatDocPage(programName, page, options = {}) {
 		if (options.maxWidth < minWidth) throw new RangeError(`maxWidth must be at least ${minWidth}, got ${options.maxWidth}.`);
 		if (needsDescColumn && minDescWidth > 1) {
 			const avail = options.maxWidth - termIndent - 2;
-			const descW = avail - effectiveTermWidth;
+			const effTW = avail >= termWidth + 1 ? termWidth : Math.max(1, Math.floor(avail / 2));
+			const descW = avail - effTW;
 			if (descW < minDescWidth) {
-				const needed = termIndent + effectiveTermWidth + 2 + minDescWidth;
+				const needed = termIndent + termWidth + 2 + minDescWidth;
 				throw new RangeError(`maxWidth must be at least ${needed}, got ${options.maxWidth}.`);
 			}
 		}
 	}
+	let effectiveTermWidth;
+	if (options.maxWidth == null) effectiveTermWidth = termWidth;
+	else {
+		const availableForColumns = options.maxWidth - termIndent - 2;
+		effectiveTermWidth = availableForColumns >= termWidth + 1 ? termWidth : Math.max(1, Math.floor(availableForColumns / 2));
+	}
 	let output = "";
 	if (hasContent(page.brief)) {
 		output += require_message.formatMessage(page.brief, {

package/dist/doc.d.cts

@@ -217,14 +217,10 @@ interface DocPageFormatOptions {
    */
   termIndent?: number;
   /**
-   * Width allocated for terms before descriptions start.  Set to `"auto"`
-   * to align descriptions after the widest visible term that has content.
-   * Terminal display width is used for automatic measurement.
-   *
+   * Width allocated for terms before descriptions start.
    * @default `26`
-   * @since 1.3.0 Added automatic term width.
    */
-  termWidth?: number | "auto";
+  termWidth?: number;
   /**
    * Maximum width of the entire formatted output.
    */

package/dist/doc.d.ts

@@ -217,14 +217,10 @@ interface DocPageFormatOptions {
    */
   termIndent?: number;
   /**
-   * Width allocated for terms before descriptions start.  Set to `"auto"`
-   * to align descriptions after the widest visible term that has content.
-   * Terminal display width is used for automatic measurement.
-   *
+   * Width allocated for terms before descriptions start.
    * @default `26`
-   * @since 1.3.0 Added automatic term width.
    */
-  termWidth?: number | "auto";
+  termWidth?: number;
   /**
    * Maximum width of the entire formatted output.
    */

package/dist/doc.js

@@ -213,6 +213,7 @@ function defaultSectionOrder(a, b) {
 function formatDocPage(programName, page, options = {}) {
 	validateProgramName(programName);
 	const termIndent = options.termIndent ?? 2;
+	const termWidth = options.termWidth ?? 26;
 	const showUsage = options.showUsage ?? true;
 	if (options.maxWidth != null && (!Number.isFinite(options.maxWidth) || !Number.isInteger(options.maxWidth))) throw new TypeError(`maxWidth must be a finite integer, got ${options.maxWidth}.`);
 	const filteredSections = page.sections.map((s) => ({
@@ -231,32 +232,9 @@ function formatDocPage(programName, page, options = {}) {
 		if (maxItems < 1) throw new RangeError(`showChoices.maxItems must be at least 1, but got ${maxItems}.`);
 	}
 	const hasContent = (msg) => Array.isArray(msg) && msg.length > 0;
-	const needsDescriptionColumn = (entry) => hasContent(entry.description) || (options.showDefault === true || typeof options.showDefault === "object") && hasContent(entry.default) || (options.showChoices === true || typeof options.showChoices === "object") && hasContent(entry.choices);
-	const automaticTermWidth = () => {
-		let widest;
-		for (const section of page.sections) for (const entry of section.entries) {
-			if (!needsDescriptionColumn(entry)) continue;
-			const rendered = formatUsageTerm(entry.term, {
-				colors: options.colors,
-				optionsSeparator: ", ",
-				context: "doc"
-			});
-			const width = Math.max(...rendered.split("\n").map((line) => getDisplayWidth(line)));
-			widest = widest == null ? width : Math.max(widest, width);
-		}
-		return widest;
-	};
-	const termWidth = options.termWidth === "auto" ? automaticTermWidth() ?? 26 : options.termWidth ?? 26;
-	const hasEntries = page.sections.some((s) => s.entries.length > 0);
-	const needsDescColumn = hasEntries && page.sections.some((s) => s.entries.some(needsDescriptionColumn));
-	let effectiveTermWidth;
-	if (options.maxWidth == null) effectiveTermWidth = termWidth;
-	else {
-		const availableForColumns = options.maxWidth - termIndent - 2;
-		const evenlySplitTermWidth = Math.max(1, Math.floor(availableForColumns / 2));
-		effectiveTermWidth = options.termWidth === "auto" && needsDescColumn ? Math.min(termWidth, evenlySplitTermWidth) : availableForColumns >= termWidth + 1 ? termWidth : evenlySplitTermWidth;
-	}
 	if (options.maxWidth != null) {
+		const hasEntries = page.sections.some((s) => s.entries.length > 0);
+		const needsDescColumn = hasEntries && page.sections.some((s) => s.entries.some((e) => hasContent(e.description) || options.showDefault && hasContent(e.default) || options.showChoices && hasContent(e.choices)));
 		let minDescWidth = 1;
 		if (needsDescColumn) {
 			if (options.showDefault && page.sections.some((s) => s.entries.some((e) => hasContent(e.default)))) {
@@ -282,13 +260,20 @@ function formatDocPage(programName, page, options = {}) {
 		if (options.maxWidth < minWidth) throw new RangeError(`maxWidth must be at least ${minWidth}, got ${options.maxWidth}.`);
 		if (needsDescColumn && minDescWidth > 1) {
 			const avail = options.maxWidth - termIndent - 2;
-			const descW = avail - effectiveTermWidth;
+			const effTW = avail >= termWidth + 1 ? termWidth : Math.max(1, Math.floor(avail / 2));
+			const descW = avail - effTW;
 			if (descW < minDescWidth) {
-				const needed = termIndent + effectiveTermWidth + 2 + minDescWidth;
+				const needed = termIndent + termWidth + 2 + minDescWidth;
 				throw new RangeError(`maxWidth must be at least ${needed}, got ${options.maxWidth}.`);
 			}
 		}
 	}
+	let effectiveTermWidth;
+	if (options.maxWidth == null) effectiveTermWidth = termWidth;
+	else {
+		const availableForColumns = options.maxWidth - termIndent - 2;
+		effectiveTermWidth = availableForColumns >= termWidth + 1 ? termWidth : Math.max(1, Math.floor(availableForColumns / 2));
+	}
 	let output = "";
 	if (hasContent(page.brief)) {
 		output += formatMessage(page.brief, {