@optique/core 1.0.16-dev.2947 → 1.0.16-dev.2983

package/dist/constructs.cjs

@@ -1,5 +1,6 @@
 const require_annotations = require('./internal/annotations.cjs');
 const require_message = require('./message.cjs');
+const require_command_usage = require('./internal/command-usage.cjs');
 const require_command_doc_metadata = require('./internal/command-doc-metadata.cjs');
 const require_passthrough = require('./internal/passthrough.cjs');
 const require_validate = require('./validate.cjs');
@@ -382,10 +383,10 @@ function applyHiddenToUsageTerm(term, hidden) {
 		type: "exclusive",
 		terms: term.terms.map((u) => applyHiddenToUsage(u, hidden))
 	};
-	if (term.type === "argument" || term.type === "option" || term.type === "command" || term.type === "passthrough") return {
+	if (term.type === "argument" || term.type === "option" || term.type === "command" || term.type === "passthrough") return require_command_usage.copyCommandUsageId(term, {
 		...term,
 		hidden: require_usage.mergeHidden(term.hidden, hidden)
-	};
+	});
 	return term;
 }
 function applyHiddenToUsage(usage, hidden) {
@@ -1252,6 +1253,7 @@ function or(...args) {
 			success: false
 		};
 	};
+	const commandUsageScopes = parsers.map(() => /* @__PURE__ */ new WeakMap());
 	const singleResult = {
 		mode: combinedMode,
 		$valueType: [],
@@ -1259,7 +1261,7 @@ function or(...args) {
 		priority: Math.max(...parsers.map((p) => p.priority)),
 		usage: [{
 			type: "exclusive",
-			terms: parsers.map((p) => p.usage)
+			terms: parsers.map((p, i) => require_command_usage.scopeCommandUsage(p.usage, commandUsageScopes[i]))
 		}],
 		leadingNames: unionLeadingNames(parsers),
 		acceptingAnyToken: parsers.some((p) => p.acceptingAnyToken),
@@ -1289,7 +1291,7 @@ function or(...args) {
 					state: parserResult.next.state
 				} : { kind: "unavailable" };
 				const docFragments = parsers[index].getDocFragments(innerState, void 0);
-				commandMetadata = require_command_doc_metadata.getCommandDocMetadata(docFragments);
+				commandMetadata = require_command_doc_metadata.scopeCommandDocMetadata(require_command_doc_metadata.getCommandDocMetadata(docFragments), commandUsageScopes[index]);
 				brief = docFragments.brief;
 				description = docFragments.description;
 				footer = docFragments.footer;
@@ -1480,6 +1482,7 @@ function longestMatch(...args) {
 			success: false
 		};
 	};
+	const commandUsageScopes = parsers.map(() => /* @__PURE__ */ new WeakMap());
 	const multiResult = {
 		mode: combinedMode,
 		$valueType: [],
@@ -1487,7 +1490,7 @@ function longestMatch(...args) {
 		priority: Math.max(...parsers.map((p) => p.priority)),
 		usage: [{
 			type: "exclusive",
-			terms: parsers.map((p) => p.usage)
+			terms: parsers.map((p, i) => require_command_usage.scopeCommandUsage(p.usage, commandUsageScopes[i]))
 		}],
 		leadingNames: unionLeadingNames(parsers),
 		acceptingAnyToken: parsers.some((p) => p.acceptingAnyToken),
@@ -1520,7 +1523,7 @@ function longestMatch(...args) {
 						kind: "available",
 						state: result.next.state
 					});
-					commandMetadata = require_command_doc_metadata.getCommandDocMetadata(docResult);
+					commandMetadata = require_command_doc_metadata.scopeCommandDocMetadata(require_command_doc_metadata.getCommandDocMetadata(docResult), commandUsageScopes[i]);
 					brief = docResult.brief;
 					description = docResult.description;
 					footer = docResult.footer;
@@ -2231,13 +2234,14 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			success: false
 		};
 	};
+	const commandUsageScopes = new Map(parserPairs.map(([field]) => [field, /* @__PURE__ */ new WeakMap()]));
 	const objectParser = {
 		mode: combinedMode,
 		$valueType: [],
 		$stateType: [],
 		[fieldParsersKey]: parserPairs,
 		priority: Math.max(...parserKeys.map((k) => parsers[k].priority)),
-		usage: applyHiddenToUsage(parserPairs.flatMap(([_, p]) => p.usage), options.hidden),
+		usage: applyHiddenToUsage(parserPairs.flatMap(([field, p]) => require_command_usage.scopeCommandUsage(p.usage, commandUsageScopes.get(field))), options.hidden),
 		leadingNames: sharedBufferLeadingNames(parserPairs.map(([_, p]) => p)),
 		acceptingAnyToken: parserPairs.some(([_, p]) => p.acceptingAnyToken),
 		get initialState() {
@@ -2489,7 +2493,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 					state: state.state[field]
 				};
 				const docs = p.getDocFragments(fieldState, defaultValue?.[field]);
-				commandMetadata = require_command_doc_metadata.collectCommandDocMetadata(commandMetadata, docs);
+				commandMetadata = require_command_doc_metadata.collectCommandDocMetadata(commandMetadata, docs, false, commandUsageScopes.get(field));
 				return docs.fragments;
 			});
 			const hiddenAwareFragments = applyHiddenToDocFragments(fragments, options.hidden);
@@ -2946,12 +2950,16 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			consumed: allConsumed
 		};
 	};
+	const commandUsageScopes = parsers.map(() => /* @__PURE__ */ new WeakMap());
 	const tupleParser = {
 		mode: combinedMode,
 		$valueType: [],
 		$stateType: [],
 		[fieldParsersKey]: parsers.map((parser, index) => [String(index), parser]),
-		usage: parsers.toSorted((a, b) => b.priority - a.priority).flatMap((p) => p.usage),
+		usage: parsers.map((p, i) => ({
+			p,
+			i
+		})).toSorted((a, b) => b.p.priority - a.p.priority).flatMap(({ p, i }) => require_command_usage.scopeCommandUsage(p.usage, commandUsageScopes[i])),
 		leadingNames: sharedBufferLeadingNames(parsers),
 		acceptingAnyToken: parsers.some((p) => p.acceptingAnyToken),
 		priority: parsers.length > 0 ? Math.max(...parsers.map((p) => p.priority)) : 0,
@@ -3144,7 +3152,7 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 					state: state.state[i]
 				};
 				const docs = p.getDocFragments(indexState, defaultValue?.[i]);
-				commandMetadata = require_command_doc_metadata.collectCommandDocMetadata(commandMetadata, docs);
+				commandMetadata = require_command_doc_metadata.collectCommandDocMetadata(commandMetadata, docs, false, commandUsageScopes[i]);
 				return docs.fragments;
 			});
 			const entries = fragments.filter((d) => d.type === "entry");
@@ -3638,13 +3646,14 @@ function merge(...args) {
 			consumed: allConsumed
 		};
 	};
+	const commandUsageScopes = parsers.map(() => /* @__PURE__ */ new WeakMap());
 	const mergeParser = {
 		mode: combinedMode,
 		$valueType: [],
 		$stateType: [],
 		[fieldParsersKey]: mergedFieldParsers,
 		priority: Math.max(...mergeParseLanes.map((lane) => lane.priority)),
-		usage: applyHiddenToUsage(parsers.flatMap((p) => p.usage), options.hidden),
+		usage: applyHiddenToUsage(parsers.flatMap((p, i) => require_command_usage.scopeCommandUsage(p.usage, commandUsageScopes[i])), options.hidden),
 		leadingNames: sharedBufferLeadingNames(mergeParseLanes),
 		acceptingAnyToken: mergeParseLanes.some((lane) => lane.acceptingAnyToken),
 		initialState,
@@ -4073,7 +4082,7 @@ function merge(...args) {
 					state: state.state
 				};
 				const docFragments = p.getDocFragments(parserState, void 0);
-				commandMetadata = require_command_doc_metadata.collectCommandDocMetadata(commandMetadata, docFragments, true);
+				commandMetadata = require_command_doc_metadata.collectCommandDocMetadata(commandMetadata, docFragments, true, commandUsageScopes[i]);
 				brief ??= docFragments.brief;
 				description ??= docFragments.description;
 				footer ??= docFragments.footer;
@@ -4610,12 +4619,13 @@ function concat(...parsers) {
 			} : {}
 		};
 	};
+	const commandUsageScopes = parsers.map(() => /* @__PURE__ */ new WeakMap());
 	const concatParser = {
 		mode: combinedMode,
 		$valueType: [],
 		$stateType: [],
 		priority: parsers.length > 0 ? Math.max(...parsers.map((p) => p.priority)) : 0,
-		usage: parsers.flatMap((p) => p.usage),
+		usage: parsers.flatMap((p, i) => require_command_usage.scopeCommandUsage(p.usage, commandUsageScopes[i])),
 		leadingNames: sharedBufferLeadingNames(parsers),
 		acceptingAnyToken: parsers.some((p) => p.acceptingAnyToken),
 		initialState,
@@ -4733,7 +4743,7 @@ function concat(...parsers) {
 					state: state.state[index]
 				};
 				const docs = p.getDocFragments(indexState, void 0);
-				commandMetadata = require_command_doc_metadata.collectCommandDocMetadata(commandMetadata, docs);
+				commandMetadata = require_command_doc_metadata.collectCommandDocMetadata(commandMetadata, docs, false, commandUsageScopes[index]);
 				return docs.fragments;
 			});
 			const entries = fragments.filter((f) => f.type === "entry");
@@ -4944,8 +4954,12 @@ function conditional(discriminator, branches, defaultBranch, options) {
 		else result.push(term);
 		return result;
 	}
-	const branchUsages = branchParsers.map(([key, p]) => [...appendLiteralToUsage(discriminator.usage, key), ...p.usage]);
-	if (defaultBranch) branchUsages.push(defaultBranch.usage);
+	const discriminatorUsageScope = /* @__PURE__ */ new WeakMap();
+	const branchUsageScope = /* @__PURE__ */ new WeakMap();
+	const commandUsageScopes = new Map(branchParsers.map(([key]) => [key, /* @__PURE__ */ new WeakMap()]));
+	const defaultUsageScope = /* @__PURE__ */ new WeakMap();
+	const branchUsages = branchParsers.map(([key, p]) => require_command_usage.scopeCommandUsage([...appendLiteralToUsage(require_command_usage.scopeCommandUsage(discriminator.usage, discriminatorUsageScope), key), ...require_command_usage.scopeCommandUsage(p.usage, branchUsageScope)], commandUsageScopes.get(key)));
+	if (defaultBranch) branchUsages.push(require_command_usage.scopeCommandUsage(defaultBranch.usage, defaultUsageScope));
 	const usage = branchUsages.length > 1 ? [{
 		type: "exclusive",
 		terms: branchUsages
@@ -5795,7 +5809,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 			if (isAsync) return suggestAsync(context, prefix);
 			return suggestSync(context, prefix);
 		},
-		getDocFragments(_state, _defaultValue) {
+		getDocFragments(state, _defaultValue) {
 			const fragments = [];
 			const discriminatorFragments = discriminator.getDocFragments({ kind: "unavailable" }, void 0);
 			fragments.push(...discriminatorFragments.fragments);
@@ -5819,7 +5833,27 @@ function conditional(discriminator, branches, defaultBranch, options) {
 					entries
 				});
 			}
-			return { fragments };
+			let selected = require_command_doc_metadata.getSelectedCommandUsage(void 0);
+			if (state.kind === "available" && state.state.selectedBranch != null) {
+				const selection = state.state.selectedBranch;
+				const branch = selection.kind === "default" ? defaultBranch : branches[selection.key];
+				if (branch != null) {
+					const docs = branch.getDocFragments({
+						kind: "available",
+						state: require_annotation_state.getWrappedChildState(state.state, state.state.branchState, branch)
+					}, void 0);
+					if (selection.kind === "default") selected = require_command_doc_metadata.getSelectedCommandUsage(require_command_doc_metadata.scopeCommandDocMetadata(require_command_doc_metadata.getCommandDocMetadata(docs), defaultUsageScope));
+					else {
+						const discriminatorDocs = discriminator.getDocFragments({
+							kind: "available",
+							state: require_annotation_state.getWrappedChildState(state.state, state.state.discriminatorState, discriminator)
+						}, void 0);
+						const metadata = require_command_doc_metadata.collectCommandDocMetadata(require_command_doc_metadata.scopeCommandDocMetadata(require_command_doc_metadata.getCommandDocMetadata(discriminatorDocs), discriminatorUsageScope), docs, false, branchUsageScope);
+						selected = require_command_doc_metadata.getSelectedCommandUsage(require_command_doc_metadata.scopeCommandDocMetadata(metadata, commandUsageScopes.get(selection.key)));
+					}
+				}
+			}
+			return require_command_doc_metadata.withCommandDocMetadata({ fragments }, require_command_doc_metadata.withSelectedCommandUsage({}, selected));
 		}
 	};
 	require_parser.defineInheritedAnnotationParser(conditionalParser);

package/dist/constructs.js

@@ -1,6 +1,7 @@
 import { annotateFreshArray, getAnnotations, inheritAnnotations } from "./internal/annotations.js";
 import { message, optionName, text, values } from "./message.js";
-import { collectCommandDocMetadata, getCommandDocMetadata, withCommandDocMetadata } from "./internal/command-doc-metadata.js";
+import { copyCommandUsageId, scopeCommandUsage } from "./internal/command-usage.js";
+import { collectCommandDocMetadata, getCommandDocMetadata, getSelectedCommandUsage, scopeCommandDocMetadata, withCommandDocMetadata, withSelectedCommandUsage } from "./internal/command-doc-metadata.js";
 import { combineOptionMatches, combinePassThroughPriorities, defineOptionMatch, definePassThroughPriority, delegateKnownCompletion, getKnownCompletion, getOptionMatch, getPassThroughFailureHint, getPassThroughPriority, hasPassThroughUsage, matchesOptionToken, retainConsumingFailure, retainConsumingFailureHint, withPassThroughFailure } from "./internal/passthrough.js";
 import { validateLabel } from "./validate.js";
 import { extractArgumentMetavars, extractCommandNames, extractOptionNames, isDocHidden, mergeHidden } from "./usage.js";
@@ -382,10 +383,10 @@ function applyHiddenToUsageTerm(term, hidden) {
 		type: "exclusive",
 		terms: term.terms.map((u) => applyHiddenToUsage(u, hidden))
 	};
-	if (term.type === "argument" || term.type === "option" || term.type === "command" || term.type === "passthrough") return {
+	if (term.type === "argument" || term.type === "option" || term.type === "command" || term.type === "passthrough") return copyCommandUsageId(term, {
 		...term,
 		hidden: mergeHidden(term.hidden, hidden)
-	};
+	});
 	return term;
 }
 function applyHiddenToUsage(usage, hidden) {
@@ -1252,6 +1253,7 @@ function or(...args) {
 			success: false
 		};
 	};
+	const commandUsageScopes = parsers.map(() => /* @__PURE__ */ new WeakMap());
 	const singleResult = {
 		mode: combinedMode,
 		$valueType: [],
@@ -1259,7 +1261,7 @@ function or(...args) {
 		priority: Math.max(...parsers.map((p) => p.priority)),
 		usage: [{
 			type: "exclusive",
-			terms: parsers.map((p) => p.usage)
+			terms: parsers.map((p, i) => scopeCommandUsage(p.usage, commandUsageScopes[i]))
 		}],
 		leadingNames: unionLeadingNames(parsers),
 		acceptingAnyToken: parsers.some((p) => p.acceptingAnyToken),
@@ -1289,7 +1291,7 @@ function or(...args) {
 					state: parserResult.next.state
 				} : { kind: "unavailable" };
 				const docFragments = parsers[index].getDocFragments(innerState, void 0);
-				commandMetadata = getCommandDocMetadata(docFragments);
+				commandMetadata = scopeCommandDocMetadata(getCommandDocMetadata(docFragments), commandUsageScopes[index]);
 				brief = docFragments.brief;
 				description = docFragments.description;
 				footer = docFragments.footer;
@@ -1480,6 +1482,7 @@ function longestMatch(...args) {
 			success: false
 		};
 	};
+	const commandUsageScopes = parsers.map(() => /* @__PURE__ */ new WeakMap());
 	const multiResult = {
 		mode: combinedMode,
 		$valueType: [],
@@ -1487,7 +1490,7 @@ function longestMatch(...args) {
 		priority: Math.max(...parsers.map((p) => p.priority)),
 		usage: [{
 			type: "exclusive",
-			terms: parsers.map((p) => p.usage)
+			terms: parsers.map((p, i) => scopeCommandUsage(p.usage, commandUsageScopes[i]))
 		}],
 		leadingNames: unionLeadingNames(parsers),
 		acceptingAnyToken: parsers.some((p) => p.acceptingAnyToken),
@@ -1520,7 +1523,7 @@ function longestMatch(...args) {
 						kind: "available",
 						state: result.next.state
 					});
-					commandMetadata = getCommandDocMetadata(docResult);
+					commandMetadata = scopeCommandDocMetadata(getCommandDocMetadata(docResult), commandUsageScopes[i]);
 					brief = docResult.brief;
 					description = docResult.description;
 					footer = docResult.footer;
@@ -2231,13 +2234,14 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			success: false
 		};
 	};
+	const commandUsageScopes = new Map(parserPairs.map(([field]) => [field, /* @__PURE__ */ new WeakMap()]));
 	const objectParser = {
 		mode: combinedMode,
 		$valueType: [],
 		$stateType: [],
 		[fieldParsersKey]: parserPairs,
 		priority: Math.max(...parserKeys.map((k) => parsers[k].priority)),
-		usage: applyHiddenToUsage(parserPairs.flatMap(([_, p]) => p.usage), options.hidden),
+		usage: applyHiddenToUsage(parserPairs.flatMap(([field, p]) => scopeCommandUsage(p.usage, commandUsageScopes.get(field))), options.hidden),
 		leadingNames: sharedBufferLeadingNames(parserPairs.map(([_, p]) => p)),
 		acceptingAnyToken: parserPairs.some(([_, p]) => p.acceptingAnyToken),
 		get initialState() {
@@ -2489,7 +2493,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 					state: state.state[field]
 				};
 				const docs = p.getDocFragments(fieldState, defaultValue?.[field]);
-				commandMetadata = collectCommandDocMetadata(commandMetadata, docs);
+				commandMetadata = collectCommandDocMetadata(commandMetadata, docs, false, commandUsageScopes.get(field));
 				return docs.fragments;
 			});
 			const hiddenAwareFragments = applyHiddenToDocFragments(fragments, options.hidden);
@@ -2946,12 +2950,16 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			consumed: allConsumed
 		};
 	};
+	const commandUsageScopes = parsers.map(() => /* @__PURE__ */ new WeakMap());
 	const tupleParser = {
 		mode: combinedMode,
 		$valueType: [],
 		$stateType: [],
 		[fieldParsersKey]: parsers.map((parser, index) => [String(index), parser]),
-		usage: parsers.toSorted((a, b) => b.priority - a.priority).flatMap((p) => p.usage),
+		usage: parsers.map((p, i) => ({
+			p,
+			i
+		})).toSorted((a, b) => b.p.priority - a.p.priority).flatMap(({ p, i }) => scopeCommandUsage(p.usage, commandUsageScopes[i])),
 		leadingNames: sharedBufferLeadingNames(parsers),
 		acceptingAnyToken: parsers.some((p) => p.acceptingAnyToken),
 		priority: parsers.length > 0 ? Math.max(...parsers.map((p) => p.priority)) : 0,
@@ -3144,7 +3152,7 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 					state: state.state[i]
 				};
 				const docs = p.getDocFragments(indexState, defaultValue?.[i]);
-				commandMetadata = collectCommandDocMetadata(commandMetadata, docs);
+				commandMetadata = collectCommandDocMetadata(commandMetadata, docs, false, commandUsageScopes[i]);
 				return docs.fragments;
 			});
 			const entries = fragments.filter((d) => d.type === "entry");
@@ -3638,13 +3646,14 @@ function merge(...args) {
 			consumed: allConsumed
 		};
 	};
+	const commandUsageScopes = parsers.map(() => /* @__PURE__ */ new WeakMap());
 	const mergeParser = {
 		mode: combinedMode,
 		$valueType: [],
 		$stateType: [],
 		[fieldParsersKey]: mergedFieldParsers,
 		priority: Math.max(...mergeParseLanes.map((lane) => lane.priority)),
-		usage: applyHiddenToUsage(parsers.flatMap((p) => p.usage), options.hidden),
+		usage: applyHiddenToUsage(parsers.flatMap((p, i) => scopeCommandUsage(p.usage, commandUsageScopes[i])), options.hidden),
 		leadingNames: sharedBufferLeadingNames(mergeParseLanes),
 		acceptingAnyToken: mergeParseLanes.some((lane) => lane.acceptingAnyToken),
 		initialState,
@@ -4073,7 +4082,7 @@ function merge(...args) {
 					state: state.state
 				};
 				const docFragments = p.getDocFragments(parserState, void 0);
-				commandMetadata = collectCommandDocMetadata(commandMetadata, docFragments, true);
+				commandMetadata = collectCommandDocMetadata(commandMetadata, docFragments, true, commandUsageScopes[i]);
 				brief ??= docFragments.brief;
 				description ??= docFragments.description;
 				footer ??= docFragments.footer;
@@ -4610,12 +4619,13 @@ function concat(...parsers) {
 			} : {}
 		};
 	};
+	const commandUsageScopes = parsers.map(() => /* @__PURE__ */ new WeakMap());
 	const concatParser = {
 		mode: combinedMode,
 		$valueType: [],
 		$stateType: [],
 		priority: parsers.length > 0 ? Math.max(...parsers.map((p) => p.priority)) : 0,
-		usage: parsers.flatMap((p) => p.usage),
+		usage: parsers.flatMap((p, i) => scopeCommandUsage(p.usage, commandUsageScopes[i])),
 		leadingNames: sharedBufferLeadingNames(parsers),
 		acceptingAnyToken: parsers.some((p) => p.acceptingAnyToken),
 		initialState,
@@ -4733,7 +4743,7 @@ function concat(...parsers) {
 					state: state.state[index]
 				};
 				const docs = p.getDocFragments(indexState, void 0);
-				commandMetadata = collectCommandDocMetadata(commandMetadata, docs);
+				commandMetadata = collectCommandDocMetadata(commandMetadata, docs, false, commandUsageScopes[index]);
 				return docs.fragments;
 			});
 			const entries = fragments.filter((f) => f.type === "entry");
@@ -4944,8 +4954,12 @@ function conditional(discriminator, branches, defaultBranch, options) {
 		else result.push(term);
 		return result;
 	}
-	const branchUsages = branchParsers.map(([key, p]) => [...appendLiteralToUsage(discriminator.usage, key), ...p.usage]);
-	if (defaultBranch) branchUsages.push(defaultBranch.usage);
+	const discriminatorUsageScope = /* @__PURE__ */ new WeakMap();
+	const branchUsageScope = /* @__PURE__ */ new WeakMap();
+	const commandUsageScopes = new Map(branchParsers.map(([key]) => [key, /* @__PURE__ */ new WeakMap()]));
+	const defaultUsageScope = /* @__PURE__ */ new WeakMap();
+	const branchUsages = branchParsers.map(([key, p]) => scopeCommandUsage([...appendLiteralToUsage(scopeCommandUsage(discriminator.usage, discriminatorUsageScope), key), ...scopeCommandUsage(p.usage, branchUsageScope)], commandUsageScopes.get(key)));
+	if (defaultBranch) branchUsages.push(scopeCommandUsage(defaultBranch.usage, defaultUsageScope));
 	const usage = branchUsages.length > 1 ? [{
 		type: "exclusive",
 		terms: branchUsages
@@ -5795,7 +5809,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 			if (isAsync) return suggestAsync(context, prefix);
 			return suggestSync(context, prefix);
 		},
-		getDocFragments(_state, _defaultValue) {
+		getDocFragments(state, _defaultValue) {
 			const fragments = [];
 			const discriminatorFragments = discriminator.getDocFragments({ kind: "unavailable" }, void 0);
 			fragments.push(...discriminatorFragments.fragments);
@@ -5819,7 +5833,27 @@ function conditional(discriminator, branches, defaultBranch, options) {
 					entries
 				});
 			}
-			return { fragments };
+			let selected = getSelectedCommandUsage(void 0);
+			if (state.kind === "available" && state.state.selectedBranch != null) {
+				const selection = state.state.selectedBranch;
+				const branch = selection.kind === "default" ? defaultBranch : branches[selection.key];
+				if (branch != null) {
+					const docs = branch.getDocFragments({
+						kind: "available",
+						state: getWrappedChildState(state.state, state.state.branchState, branch)
+					}, void 0);
+					if (selection.kind === "default") selected = getSelectedCommandUsage(scopeCommandDocMetadata(getCommandDocMetadata(docs), defaultUsageScope));
+					else {
+						const discriminatorDocs = discriminator.getDocFragments({
+							kind: "available",
+							state: getWrappedChildState(state.state, state.state.discriminatorState, discriminator)
+						}, void 0);
+						const metadata = collectCommandDocMetadata(scopeCommandDocMetadata(getCommandDocMetadata(discriminatorDocs), discriminatorUsageScope), docs, false, branchUsageScope);
+						selected = getSelectedCommandUsage(scopeCommandDocMetadata(metadata, commandUsageScopes.get(selection.key)));
+					}
+				}
+			}
+			return withCommandDocMetadata({ fragments }, withSelectedCommandUsage({}, selected));
 		}
 	};
 	defineInheritedAnnotationParser(conditionalParser);

package/dist/input-trace.cjs

@@ -22,23 +22,102 @@ function serializePath(path) {
 	if (path.length === 0) return "";
 	return path.map(serializeKey).join("");
 }
+function height(node$1) {
+	return node$1?.height ?? 0;
+}
+function node(key, entry, left, right) {
+	return {
+		key,
+		entry,
+		left,
+		right,
+		height: 1 + Math.max(height(left), height(right))
+	};
+}
+function balance(key, entry, left, right) {
+	if (height(left) - height(right) > 1 && left != null) {
+		const pivot = left.right;
+		if (height(pivot) > height(left.left) && pivot != null) return node(pivot.key, pivot.entry, node(left.key, left.entry, left.left, pivot.left), node(key, entry, pivot.right, right));
+		return node(left.key, left.entry, left.left, node(key, entry, left.right, right));
+	}
+	if (height(right) - height(left) > 1 && right != null) {
+		const pivot = right.left;
+		if (height(pivot) > height(right.right) && pivot != null) return node(pivot.key, pivot.entry, node(key, entry, left, pivot.left), node(right.key, right.entry, pivot.right, right.right));
+		return node(right.key, right.entry, node(key, entry, left, right.left), right.right);
+	}
+	return node(key, entry, left, right);
+}
+function setEntry(root, key, entry) {
+	if (root == null) return node(key, entry, void 0, void 0);
+	if (key === root.key) return entry === root.entry ? root : {
+		...root,
+		entry
+	};
+	if (key < root.key) {
+		const left = setEntry(root.left, key, entry);
+		return left === root.left ? root : balance(root.key, root.entry, left, root.right);
+	}
+	const right = setEntry(root.right, key, entry);
+	return right === root.right ? root : balance(root.key, root.entry, root.left, right);
+}
+function popMin(root) {
+	if (root.left == null) return [root, root.right];
+	const [minimum, left] = popMin(root.left);
+	return [minimum, balance(root.key, root.entry, left, root.right)];
+}
+function deleteEntry(root, key) {
+	if (root == null) return void 0;
+	if (key === root.key) {
+		if (root.left == null) return root.right;
+		if (root.right == null) return root.left;
+		const [successor, right$1] = popMin(root.right);
+		return balance(successor.key, successor.entry, root.left, right$1);
+	}
+	if (key < root.key) {
+		const left = deleteEntry(root.left, key);
+		return left === root.left ? root : balance(root.key, root.entry, left, root.right);
+	}
+	const right = deleteEntry(root.right, key);
+	return right === root.right ? root : balance(root.key, root.entry, root.left, right);
+}
+function inspectNode(root, lower, upper) {
+	if (root == null) return {
+		size: 0,
+		height: 0
+	};
+	if (lower !== void 0 && root.key <= lower || upper !== void 0 && root.key >= upper) throw new TypeError("Input trace keys are not strictly ordered.");
+	const left = inspectNode(root.left, lower, root.key);
+	const right = inspectNode(root.right, root.key, upper);
+	const actualHeight = 1 + Math.max(left.height, right.height);
+	if (root.height !== actualHeight || Math.abs(left.height - right.height) > 1) throw new TypeError("Input trace heights or balance are invalid.");
+	return {
+		size: 1 + left.size + right.size,
+		height: actualHeight
+	};
+}
 var InputTraceImpl = class InputTraceImpl {
-	#entries;
-	constructor(entries) {
-		this.#entries = entries ?? /* @__PURE__ */ new Map();
+	#root;
+	constructor(root) {
+		this.#root = root;
 	}
 	get(path) {
-		return this.#entries.get(serializePath(path));
+		const key = serializePath(path);
+		let current = this.#root;
+		while (current != null) {
+			if (key === current.key) return current.entry;
+			current = key < current.key ? current.left : current.right;
+		}
+		return void 0;
 	}
 	set(path, entry) {
-		const copy = new Map(this.#entries);
-		copy.set(serializePath(path), entry);
-		return new InputTraceImpl(copy);
+		return new InputTraceImpl(setEntry(this.#root, serializePath(path), entry));
 	}
 	delete(path) {
-		const copy = new Map(this.#entries);
-		copy.delete(serializePath(path));
-		return new InputTraceImpl(copy);
+		return new InputTraceImpl(deleteEntry(this.#root, serializePath(path)));
+	}
+	static inspect(trace) {
+		if (!(trace instanceof InputTraceImpl)) throw new TypeError("Expected an Optique input trace.");
+		return inspectNode(trace.#root);
 	}
 };
 /**

package/dist/input-trace.d.cts

@@ -67,11 +67,14 @@ interface InputTrace {
   delete(path: readonly PropertyKey[]): InputTrace;
 }
 /**
- * Creates a new empty {@link InputTrace}.
+ * Checks private tree invariants without exposing mutable nodes.
+ * This module is not a package export; the checker is used by internal tests.
  *
- * @returns An empty immutable input trace.
+ * @param trace The trace to inspect.
+ * @returns Its size and verified height.
+ * @throws {TypeError} If the trace is foreign or its tree invariants are invalid.
  * @internal
- * @since 1.0.0
+ * @since 1.0.16
  */
 //#endregion
 export { InputTrace };

package/dist/input-trace.d.ts

@@ -67,11 +67,14 @@ interface InputTrace {
   delete(path: readonly PropertyKey[]): InputTrace;
 }
 /**
- * Creates a new empty {@link InputTrace}.
+ * Checks private tree invariants without exposing mutable nodes.
+ * This module is not a package export; the checker is used by internal tests.
  *
- * @returns An empty immutable input trace.
+ * @param trace The trace to inspect.
+ * @returns Its size and verified height.
+ * @throws {TypeError} If the trace is foreign or its tree invariants are invalid.
  * @internal
- * @since 1.0.0
+ * @since 1.0.16
  */
 //#endregion
 export { InputTrace };