@optique/core 0.10.7 → 1.0.0-dev.1116

package/dist/constructs.js

@@ -1,11 +1,13 @@
+import { getAnnotations, inheritAnnotations, injectAnnotations } from "./annotations.js";
 import { message, optionName, text, values } from "./message.js";
 import { DependencyRegistry, dependencyId, isDeferredParseState, isDependencySourceState, isPendingDependencySourceState, isWrappedDependencySource, parseWithDependency, wrappedDependencySourceMarker } from "./dependency.js";
 import { dispatchByMode, dispatchIterableByMode } from "./mode-dispatch.js";
-import { extractArgumentMetavars, extractCommandNames, extractOptionNames } from "./usage.js";
+import { extractArgumentMetavars, extractCommandNames, extractOptionNames, isDocHidden, mergeHidden } from "./usage.js";
 import { DEFAULT_FIND_SIMILAR_OPTIONS, createErrorWithSuggestions, createSuggestionMessage, deduplicateSuggestions, findSimilar } from "./suggestion.js";
 import { collectLeadingCandidates } from "./usage-internals.js";
 
 //#region src/constructs.ts
+const inheritParentAnnotationsKey = Symbol.for("@optique/core/inheritParentAnnotations");
 function createUnexpectedInputErrorWithScopedSuggestions(baseError, invalidInput, parsers, customFormatter) {
 	const options = /* @__PURE__ */ new Set();
 	const commands = /* @__PURE__ */ new Set();
@@ -19,6 +21,60 @@ function createUnexpectedInputErrorWithScopedSuggestions(baseError, invalidInput
 		...suggestionMsg
 	] : baseError;
 }
+function applyHiddenToUsageTerm(term, hidden) {
+	if (hidden == null) return term;
+	if (term.type === "optional") return {
+		type: "optional",
+		terms: applyHiddenToUsage(term.terms, hidden)
+	};
+	if (term.type === "multiple") return {
+		type: "multiple",
+		terms: applyHiddenToUsage(term.terms, hidden),
+		min: term.min
+	};
+	if (term.type === "exclusive") return {
+		type: "exclusive",
+		terms: term.terms.map((u) => applyHiddenToUsage(u, hidden))
+	};
+	if (term.type === "argument" || term.type === "option" || term.type === "command" || term.type === "passthrough") return {
+		...term,
+		hidden: mergeHidden(term.hidden, hidden)
+	};
+	return term;
+}
+function applyHiddenToUsage(usage, hidden) {
+	if (hidden == null) return usage;
+	return usage.map((term) => applyHiddenToUsageTerm(term, hidden));
+}
+function applyHiddenToDocEntry(entry, hidden) {
+	const mergedTerm = applyHiddenToUsageTerm(entry.term, hidden);
+	if ((mergedTerm.type === "argument" || mergedTerm.type === "option" || mergedTerm.type === "command" || mergedTerm.type === "passthrough") && isDocHidden(mergedTerm.hidden)) return void 0;
+	return {
+		...entry,
+		term: mergedTerm
+	};
+}
+function applyHiddenToDocFragments(fragments, hidden) {
+	if (hidden == null) return fragments;
+	const result = [];
+	for (const fragment of fragments) {
+		if (fragment.type === "entry") {
+			const entry = applyHiddenToDocEntry(fragment, hidden);
+			if (entry != null) result.push({
+				...entry,
+				type: "entry"
+			});
+			continue;
+		}
+		const entries = fragment.entries.map((entry) => applyHiddenToDocEntry(entry, hidden)).filter((entry) => entry != null);
+		result.push({
+			type: "section",
+			title: fragment.title,
+			entries
+		});
+	}
+	return result;
+}
 /**
 * Checks if the given token is an option name that requires a value
 * (i.e., has a metavar) within the given usage terms.
@@ -554,8 +610,9 @@ function longestMatch(...args) {
 * @internal
 */
 function* suggestObjectSync(context, prefix, parserPairs) {
-	const registry = context.dependencyRegistry instanceof DependencyRegistry ? context.dependencyRegistry : new DependencyRegistry();
+	const registry = context.dependencyRegistry ? context.dependencyRegistry.clone() : new DependencyRegistry();
 	if (context.state && typeof context.state === "object") collectDependencies(context.state, registry);
+	completeDependencySourceDefaults(context, parserPairs, registry);
 	const contextWithRegistry = {
 		...context,
 		dependencyRegistry: registry
@@ -587,8 +644,9 @@ function* suggestObjectSync(context, prefix, parserPairs) {
 * @internal
 */
 async function* suggestObjectAsync(context, prefix, parserPairs) {
-	const registry = context.dependencyRegistry instanceof DependencyRegistry ? context.dependencyRegistry : new DependencyRegistry();
+	const registry = context.dependencyRegistry ? context.dependencyRegistry.clone() : new DependencyRegistry();
 	if (context.state && typeof context.state === "object") collectDependencies(context.state, registry);
+	await completeDependencySourceDefaultsAsync(context, parserPairs, registry);
 	const contextWithRegistry = {
 		...context,
 		dependencyRegistry: registry
@@ -617,17 +675,62 @@ async function* suggestObjectAsync(context, prefix, parserPairs) {
 	yield* deduplicateSuggestions(suggestions);
 }
 /**
-* Resolves deferred parse states in an object's field states.
-* This function builds a dependency registry from DependencySourceState fields
-* and re-parses DeferredParseState fields using the actual dependency values.
+* Registers an already-resolved dependency source value in the registry
+* if it is a successful {@link DependencySourceState}.
 *
-* @param fieldStates A record of field names to their state values
-* @returns The field states with deferred states resolved to their actual values
 * @internal
 */
+function registerCompletedDependency(completed, registry) {
+	if (isDependencySourceState(completed) && completed.result.success && !registry.has(completed[dependencyId])) registry.set(completed[dependencyId], completed.result.value);
+}
+/**
+* Yields `(parser, state)` pairs for dependency source parsers whose field
+* state is unpopulated, so callers can invoke `complete()` on them.
+*
+* @see https://github.com/dahlia/optique/issues/186
+* @internal
+*/
+function* pendingDependencyDefaults(context, parserPairs) {
+	for (const [field, fieldParser] of parserPairs) {
+		const fieldState = context.state != null && typeof context.state === "object" && field in context.state ? context.state[field] : void 0;
+		if (fieldState != null) continue;
+		if (isPendingDependencySourceState(fieldParser.initialState)) yield {
+			parser: fieldParser,
+			state: fieldParser.initialState
+		};
+		else if (isWrappedDependencySource(fieldParser)) yield {
+			parser: fieldParser,
+			state: [fieldParser[wrappedDependencySourceMarker]]
+		};
+	}
+}
+/**
+* Pre-completes dependency source parsers wrapped in `withDefault()` whose
+* field state is unpopulated, so that their default values are registered
+* in the dependency registry.  This mirrors Phase 1 of parse-time dependency
+* resolution and ensures `suggest()` sees the same defaults as `parse()`.
+*
+* @see https://github.com/dahlia/optique/issues/186
+* @internal
+*/
+function completeDependencySourceDefaults(context, parserPairs, registry) {
+	for (const { parser, state } of pendingDependencyDefaults(context, parserPairs)) registerCompletedDependency(parser.complete(state), registry);
+}
+/**
+* Async version of {@link completeDependencySourceDefaults} that awaits
+* `complete()` results.  Async parsers with `transformsDependencyValue`
+* return a `Promise` from `complete()`, which the sync version cannot handle.
+*
+* @see https://github.com/dahlia/optique/issues/186
+* @internal
+*/
+async function completeDependencySourceDefaultsAsync(context, parserPairs, registry) {
+	for (const { parser, state } of pendingDependencyDefaults(context, parserPairs)) registerCompletedDependency(await parser.complete(state), registry);
+}
 /**
 * Recursively collects dependency values from DependencySourceState objects
 * found anywhere in the state tree.
+* @internal
 */
 function collectDependencies(state, registry, visited = /* @__PURE__ */ new WeakSet()) {
 	if (state === null || state === void 0) return;
@@ -783,8 +886,36 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 	const parserKeys = Reflect.ownKeys(parsers);
 	const parserPairs = parserKeys.map((k) => [k, parsers[k]]);
 	parserPairs.sort(([_, parserA], [__, parserB]) => parserB.priority - parserA.priority);
-	const initialState = {};
-	for (const key of parserKeys) initialState[key] = parsers[key].initialState;
+	const createInitialState = () => {
+		const state = {};
+		for (const key of parserKeys) state[key] = parsers[key].initialState;
+		return state;
+	};
+	const inheritedFieldStateCache = /* @__PURE__ */ new WeakMap();
+	const createFieldStateGetter = (parentState) => {
+		return (field, parser) => {
+			const fieldKey = field;
+			const cache = parentState != null && typeof parentState === "object" ? inheritedFieldStateCache.get(parentState) ?? (() => {
+				const stateCache = /* @__PURE__ */ new Map();
+				inheritedFieldStateCache.set(parentState, stateCache);
+				return stateCache;
+			})() : void 0;
+			if (cache?.has(fieldKey)) return cache.get(fieldKey);
+			const sourceState = parentState != null && typeof parentState === "object" && fieldKey in parentState ? parentState[fieldKey] : parser.initialState;
+			if (sourceState == null || typeof sourceState !== "object") {
+				cache?.set(fieldKey, sourceState);
+				return sourceState;
+			}
+			const annotations = getAnnotations(parentState);
+			if (annotations === void 0 || getAnnotations(sourceState) === annotations) {
+				cache?.set(fieldKey, sourceState);
+				return sourceState;
+			}
+			const inheritedState = Reflect.get(parser, inheritParentAnnotationsKey) === true ? injectAnnotations(sourceState, annotations) : inheritAnnotations(parentState, sourceState);
+			cache?.set(fieldKey, inheritedState);
+			return inheritedState;
+		};
+	};
 	if (!options.allowDuplicates) checkDuplicateOptionNames(parserPairs.map(([field, parser]) => [field, parser.usage]));
 	const noMatchContext = analyzeNoMatchContext(parserKeys.map((k) => parsers[k]));
 	const combinedMode = parserKeys.some((k) => parsers[k].$mode === "async") ? "async" : "sync";
@@ -809,10 +940,11 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		let madeProgress = true;
 		while (madeProgress && currentContext.buffer.length > 0) {
 			madeProgress = false;
+			const getFieldState = createFieldStateGetter(currentContext.state);
 			for (const [field, parser] of parserPairs) {
 				const result = parser.parse({
 					...currentContext,
-					state: currentContext.state && typeof currentContext.state === "object" && field in currentContext.state ? currentContext.state[field] : parser.initialState
+					state: getFieldState(field, parser)
 				});
 				if (result.success && result.consumed.length > 0) {
 					currentContext = {
@@ -838,8 +970,9 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		};
 		if (context.buffer.length === 0) {
 			let allCanComplete = true;
+			const getFieldState = createFieldStateGetter(context.state);
 			for (const [field, parser] of parserPairs) {
-				const fieldState = context.state && typeof context.state === "object" && field in context.state ? context.state[field] : parser.initialState;
+				const fieldState = getFieldState(field, parser);
 				const completeResult = parser.complete(fieldState);
 				if (!completeResult.success) {
 					allCanComplete = false;
@@ -865,10 +998,11 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		let madeProgress = true;
 		while (madeProgress && currentContext.buffer.length > 0) {
 			madeProgress = false;
+			const getFieldState = createFieldStateGetter(currentContext.state);
 			for (const [field, parser] of parserPairs) {
 				const resultOrPromise = parser.parse({
 					...currentContext,
-					state: currentContext.state && typeof currentContext.state === "object" && field in currentContext.state ? currentContext.state[field] : parser.initialState
+					state: getFieldState(field, parser)
 				});
 				const result = await resultOrPromise;
 				if (result.success && result.consumed.length > 0) {
@@ -895,8 +1029,9 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		};
 		if (context.buffer.length === 0) {
 			let allCanComplete = true;
+			const getFieldState = createFieldStateGetter(context.state);
 			for (const [field, parser] of parserPairs) {
-				const fieldState = context.state && typeof context.state === "object" && field in context.state ? context.state[field] : parser.initialState;
+				const fieldState = getFieldState(field, parser);
 				const completeResult = await parser.complete(fieldState);
 				if (!completeResult.success) {
 					allCanComplete = false;
@@ -919,8 +1054,10 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		$valueType: [],
 		$stateType: [],
 		priority: Math.max(...parserKeys.map((k) => parsers[k].priority)),
-		usage: parserPairs.flatMap(([_, p]) => p.usage),
-		initialState,
+		usage: applyHiddenToUsage(parserPairs.flatMap(([_, p]) => p.usage), options.hidden),
+		get initialState() {
+			return createInitialState();
+		},
 		parse(context) {
 			return dispatchByMode(combinedMode, () => parseSync(context), () => parseAsync(context));
 		},
@@ -928,6 +1065,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			return dispatchByMode(combinedMode, () => {
 				const preCompletedState = {};
 				const preCompletedKeys = /* @__PURE__ */ new Set();
+				const getFieldState = createFieldStateGetter(state);
 				for (const field of parserKeys) {
 					const fieldKey = field;
 					const fieldState = state[fieldKey];
@@ -947,10 +1085,11 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 							preCompletedState[fieldKey] = completed;
 							preCompletedKeys.add(fieldKey);
 						} else preCompletedState[fieldKey] = fieldState;
-					} else preCompletedState[fieldKey] = fieldState;
+					} else preCompletedState[fieldKey] = getFieldState(field, fieldParser);
 				}
 				const resolvedState = resolveDeferredParseStates(preCompletedState);
 				const result = {};
+				const getCompletionFieldState = createFieldStateGetter(state);
 				for (const field of parserKeys) {
 					const fieldKey = field;
 					const fieldResolvedState = resolvedState[fieldKey];
@@ -964,7 +1103,8 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 						};
 						continue;
 					}
-					const valueResult = fieldParser.complete(fieldResolvedState);
+					const completionState = fieldResolvedState === void 0 ? getCompletionFieldState(field, fieldParser) : fieldResolvedState;
+					const valueResult = fieldParser.complete(completionState);
 					if (valueResult.success) result[fieldKey] = valueResult.value;
 					else return {
 						success: false,
@@ -978,6 +1118,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			}, async () => {
 				const preCompletedState = {};
 				const preCompletedKeys = /* @__PURE__ */ new Set();
+				const getFieldState = createFieldStateGetter(state);
 				for (const field of parserKeys) {
 					const fieldKey = field;
 					const fieldState = state[fieldKey];
@@ -997,10 +1138,11 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 							preCompletedState[fieldKey] = completed;
 							preCompletedKeys.add(fieldKey);
 						} else preCompletedState[fieldKey] = fieldState;
-					} else preCompletedState[fieldKey] = fieldState;
+					} else preCompletedState[fieldKey] = getFieldState(field, fieldParser);
 				}
 				const resolvedState = await resolveDeferredParseStatesAsync(preCompletedState);
 				const result = {};
+				const getCompletionFieldState = createFieldStateGetter(state);
 				for (const field of parserKeys) {
 					const fieldKey = field;
 					const fieldResolvedState = resolvedState[fieldKey];
@@ -1014,7 +1156,8 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 						};
 						continue;
 					}
-					const valueResult = await fieldParser.complete(fieldResolvedState);
+					const completionState = fieldResolvedState === void 0 ? getCompletionFieldState(field, fieldParser) : fieldResolvedState;
+					const valueResult = await fieldParser.complete(completionState);
 					if (valueResult.success) result[fieldKey] = valueResult.value;
 					else return {
 						success: false,
@@ -1028,6 +1171,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			});
 		},
 		suggest(context, prefix) {
+			if (options.hidden === true) return dispatchIterableByMode(combinedMode, function* () {}, async function* () {});
 			return dispatchIterableByMode(combinedMode, () => {
 				const syncParserPairs = parserPairs;
 				return suggestObjectSync(context, prefix, syncParserPairs);
@@ -1041,9 +1185,10 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 				};
 				return p.getDocFragments(fieldState, defaultValue?.[field]).fragments;
 			});
-			const entries = fragments.filter((d) => d.type === "entry");
+			const hiddenAwareFragments = applyHiddenToDocFragments(fragments, options.hidden);
+			const entries = hiddenAwareFragments.filter((d) => d.type === "entry");
 			const sections = [];
-			for (const fragment of fragments) {
+			for (const fragment of hiddenAwareFragments) {
 				if (fragment.type !== "section") continue;
 				if (fragment.title == null) entries.push(...fragment.entries);
 				else sections.push(fragment);
@@ -1375,9 +1520,10 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 function merge(...args) {
 	const label = typeof args[0] === "string" ? args[0] : void 0;
 	const lastArg = args[args.length - 1];
-	const options = lastArg && typeof lastArg === "object" && !("parse" in lastArg) && !("complete" in lastArg) ? lastArg : {};
+	const hasOptions = lastArg != null && typeof lastArg === "object" && !("$valueType" in lastArg);
+	const options = hasOptions ? lastArg : {};
 	const startIndex = typeof args[0] === "string" ? 1 : 0;
-	const endIndex = lastArg && typeof lastArg === "object" && !("parse" in lastArg) && !("complete" in lastArg) ? args.length - 1 : args.length;
+	const endIndex = hasOptions ? args.length - 1 : args.length;
 	const rawParsers = args.slice(startIndex, endIndex);
 	const combinedMode = rawParsers.some((p) => p.$mode === "async") ? "async" : "sync";
 	const isAsync = combinedMode === "async";
@@ -1518,7 +1664,7 @@ function merge(...args) {
 		$valueType: [],
 		$stateType: [],
 		priority: Math.max(...parsers.map((p) => p.priority)),
-		usage: parsers.flatMap((p) => p.usage),
+		usage: applyHiddenToUsage(parsers.flatMap((p) => p.usage), options.hidden),
 		initialState,
 		parse(context) {
 			if (isAsync) return parseAsync(context);
@@ -1572,6 +1718,7 @@ function merge(...args) {
 			})();
 		},
 		suggest(context, prefix) {
+			if (options.hidden === true) return dispatchIterableByMode(combinedMode, function* () {}, async function* () {});
 			const extractState = (p, i) => {
 				if (p.initialState === void 0) {
 					const key = `__parser_${i}`;
@@ -1587,13 +1734,19 @@ function merge(...args) {
 				}
 				return p.initialState;
 			};
+			const registry = context.dependencyRegistry ? context.dependencyRegistry.clone() : new DependencyRegistry();
+			if (context.state && typeof context.state === "object") collectDependencies(context.state, registry);
+			const contextWithRegistry = {
+				...context,
+				dependencyRegistry: registry
+			};
 			if (isAsync) return async function* () {
 				const suggestions = [];
 				for (let i = 0; i < parsers.length; i++) {
 					const parser = parsers[i];
 					const parserState = extractState(parser, i);
 					const parserSuggestions = parser.suggest({
-						...context,
+						...contextWithRegistry,
 						state: parserState
 					}, prefix);
 					if (parser.$mode === "async") for await (const s of parserSuggestions) suggestions.push(s);
@@ -1607,7 +1760,7 @@ function merge(...args) {
 					const parser = syncParsers[i];
 					const parserState = extractState(parser, i);
 					const parserSuggestions = parser.suggest({
-						...context,
+						...contextWithRegistry,
 						state: parserState
 					}, prefix);
 					suggestions.push(...parserSuggestions);
@@ -1638,9 +1791,10 @@ function merge(...args) {
 				footer ??= docFragments.footer;
 				return docFragments.fragments;
 			});
-			const entries = fragments.filter((f) => f.type === "entry");
+			const hiddenAwareFragments = applyHiddenToDocFragments(fragments, options.hidden);
+			const entries = hiddenAwareFragments.filter((f) => f.type === "entry");
 			const sections = [];
-			for (const fragment of fragments) {
+			for (const fragment of hiddenAwareFragments) {
 				if (fragment.type !== "section") continue;
 				if (fragment.title == null) entries.push(...fragment.entries);
 				else sections.push(fragment);
@@ -1676,6 +1830,118 @@ function merge(...args) {
 		}
 	};
 }
+/**
+* Builds a dependency registry from the pre-parsed context state and returns
+* the enriched context alongside the state array.  Used by both the sync and
+* async branches of `concat().suggest()`.
+* @internal
+*/
+function buildSuggestRegistry(preParsedContext) {
+	const stateArray = preParsedContext.state;
+	const registry = preParsedContext.dependencyRegistry ? preParsedContext.dependencyRegistry.clone() : new DependencyRegistry();
+	if (stateArray && Array.isArray(stateArray)) collectDependencies(stateArray, registry);
+	return {
+		context: {
+			...preParsedContext,
+			dependencyRegistry: registry
+		},
+		stateArray
+	};
+}
+/**
+* This helper replays child parsers in priority order (mirroring
+* `concat.parse()`) to accumulate dependency source values for suggestions.
+* @internal
+*/
+function preParseSuggestContext(context, parsers) {
+	if (context.buffer.length < 1 || !Array.isArray(context.state)) return context;
+	return preParseSuggestLoop(context, context.state.slice(), parsers);
+}
+/**
+* Async variant of {@link preParseSuggestContext} that awaits async child
+* parsers so that dependency sources from async sub-parsers are resolved.
+* @internal
+*/
+async function preParseSuggestContextAsync(context, parsers) {
+	if (context.buffer.length < 1 || !Array.isArray(context.state)) return context;
+	return await preParseSuggestLoop(context, context.state.slice(), parsers);
+}
+/**
+* Shared loop for sync and async concat suggest pre-parse.  When a child
+* parser returns a Promise its result is awaited; sync results are used
+* directly.  Parsers are tried in priority order, matching `concat.parse()`.
+* @internal
+*/
+function preParseSuggestLoop(context, stateArray, parsers, matchedParsers = /* @__PURE__ */ new Set()) {
+	const indexedParsers = parsers.map((parser, index) => [parser, index]);
+	let currentContext = context;
+	let changed = true;
+	while (changed && currentContext.buffer.length > 0) {
+		changed = false;
+		const remaining = indexedParsers.filter(([_, index]) => !matchedParsers.has(index)).sort(([a], [b]) => b.priority - a.priority);
+		const tried = tryParseSuggestList(currentContext, stateArray, parsers, matchedParsers, remaining);
+		if (tried === null) continue;
+		if (typeof tried === "object" && "then" in tried && typeof tried.then === "function") return tried;
+		currentContext = tried;
+		changed = true;
+	}
+	return {
+		...currentContext,
+		state: stateArray
+	};
+}
+/**
+* Tries each parser in `remaining` once.  Returns the updated context if a
+* parser consumed input (sync), a Promise that resolves to a context if an
+* async parser was encountered, or `null` if no parser consumed.
+* @internal
+*/
+function tryParseSuggestList(context, stateArray, parsers, matchedParsers, remaining) {
+	for (let ri = 0; ri < remaining.length; ri++) {
+		const [parser, index] = remaining[ri];
+		const parserState = index < stateArray.length ? stateArray[index] : parser.initialState;
+		const resultOrPromise = parser.parse({
+			...context,
+			state: parserState
+		});
+		if (resultOrPromise != null && typeof resultOrPromise === "object" && "then" in resultOrPromise && typeof resultOrPromise.then === "function") {
+			const tail = remaining.slice(ri + 1);
+			return resultOrPromise.then((result$1) => {
+				if (result$1.success && result$1.consumed.length > 0) {
+					stateArray[index] = result$1.next.state;
+					matchedParsers.add(index);
+					return preParseSuggestLoop({
+						...context,
+						buffer: result$1.next.buffer,
+						optionsTerminated: result$1.next.optionsTerminated,
+						state: stateArray
+					}, stateArray, parsers, matchedParsers);
+				}
+				const next = tryParseSuggestList(context, stateArray, parsers, matchedParsers, tail);
+				if (next === null) return {
+					...context,
+					state: stateArray
+				};
+				if (typeof next === "object" && "then" in next && typeof next.then === "function") return next.then((ctx) => ctx.buffer.length < context.buffer.length ? preParseSuggestLoop(ctx, stateArray, parsers, matchedParsers) : ctx);
+				const nextCtx = next;
+				if (nextCtx.buffer.length < context.buffer.length) return preParseSuggestLoop(nextCtx, stateArray, parsers, matchedParsers);
+				return nextCtx;
+			});
+		}
+		const result = resultOrPromise;
+		if (result.success && result.consumed.length > 0) {
+			stateArray[index] = result.next.state;
+			matchedParsers.add(index);
+			return {
+				...context,
+				buffer: result.next.buffer,
+				optionsTerminated: result.next.optionsTerminated,
+				state: stateArray
+			};
+		}
+	}
+	return null;
+}
 function concat(...parsers) {
 	const combinedMode = parsers.some((p) => p.$mode === "async") ? "async" : "sync";
 	const isAsync = combinedMode === "async";
@@ -1859,14 +2125,15 @@ function concat(...parsers) {
 			return completeSync(state);
 		},
 		suggest(context, prefix) {
-			const stateArray = context.state;
 			if (isAsync) return async function* () {
+				const preParsedContext$1 = await preParseSuggestContextAsync(context, parsers);
+				const { context: contextWithRegistry$1, stateArray: stateArray$1 } = buildSuggestRegistry(preParsedContext$1);
 				const suggestions = [];
 				for (let i = 0; i < parsers.length; i++) {
 					const parser = parsers[i];
-					const parserState = stateArray && Array.isArray(stateArray) ? stateArray[i] : parser.initialState;
+					const parserState = stateArray$1 && Array.isArray(stateArray$1) ? stateArray$1[i] : parser.initialState;
 					const parserSuggestions = parser.suggest({
-						...context,
+						...contextWithRegistry$1,
 						state: parserState
 					}, prefix);
 					if (parser.$mode === "async") for await (const s of parserSuggestions) suggestions.push(s);
@@ -1874,13 +2141,15 @@ function concat(...parsers) {
 				}
 				yield* deduplicateSuggestions(suggestions);
 			}();
+			const preParsedContext = preParseSuggestContext(context, syncParsers);
+			const { context: contextWithRegistry, stateArray } = buildSuggestRegistry(preParsedContext);
 			return function* () {
 				const suggestions = [];
 				for (let i = 0; i < syncParsers.length; i++) {
 					const parser = syncParsers[i];
 					const parserState = stateArray && Array.isArray(stateArray) ? stateArray[i] : parser.initialState;
 					const parserSuggestions = parser.suggest({
-						...context,
+						...contextWithRegistry,
 						state: parserState
 					}, prefix);
 					suggestions.push(...parserSuggestions);
@@ -1915,64 +2184,27 @@ function concat(...parsers) {
 		}
 	};
 }
-/**
-* Wraps a parser with a group label for documentation purposes.
-*
-* The `group()` function is a documentation-only wrapper that applies a label
-* to any parser for help text organization. This allows you to use clean code
-* structure with combinators like {@link merge} while maintaining well-organized
-* help text through group labeling.
-*
-* The wrapped parser has identical parsing behavior but generates documentation
-* fragments wrapped in a labeled section. This is particularly useful when
-* combining parsers using {@link merge}—you can wrap the merged result with
-* `group()` to add a section header in help output.
-*
-* @example
-* ```typescript
-* const apiOptions = merge(
-*   object({ endpoint: option("--endpoint", string()) }),
-*   object({ timeout: option("--timeout", integer()) })
-* );
-*
-* const groupedApiOptions = group("API Options", apiOptions);
-* // Now produces a labeled "API Options" section in help text
-* ```
-*
-* @example
-* ```typescript
-* // Can be used with any parser, not just merge()
-* const verboseGroup = group("Verbosity", object({
-*   verbose: option("-v", "--verbose"),
-*   quiet: option("-q", "--quiet")
-* }));
-* ```
-*
-* @template TValue The value type of the wrapped parser.
-* @template TState The state type of the wrapped parser.
-* @param label A descriptive label for this parser group, used for
-*              documentation and help text organization.
-* @param parser The parser to wrap with a group label.
-* @returns A new parser that behaves identically to the input parser
-*          but generates documentation within a labeled section.
-* @since 0.4.0
-*/
-function group(label, parser) {
+function group(label, parser, options = {}) {
 	return {
 		$mode: parser.$mode,
 		$valueType: parser.$valueType,
 		$stateType: parser.$stateType,
 		priority: parser.priority,
-		usage: parser.usage,
+		usage: applyHiddenToUsage(parser.usage, options.hidden),
 		initialState: parser.initialState,
+		...typeof parser.shouldDeferCompletion === "function" ? { shouldDeferCompletion: parser.shouldDeferCompletion.bind(parser) } : {},
 		parse: (context) => parser.parse(context),
 		complete: (state) => parser.complete(state),
-		suggest: (context, prefix) => parser.suggest(context, prefix),
+		suggest: (context, prefix) => {
+			if (options.hidden === true) return dispatchIterableByMode(parser.$mode, function* () {}, async function* () {});
+			return parser.suggest(context, prefix);
+		},
 		getDocFragments: (state, defaultValue) => {
 			const { brief, description, footer, fragments } = parser.getDocFragments(state, defaultValue);
+			const hiddenAwareFragments = applyHiddenToDocFragments(fragments, options.hidden);
 			const allEntries = [];
 			const titledSections = [];
-			for (const fragment of fragments) if (fragment.type === "entry") allEntries.push(fragment);
+			for (const fragment of hiddenAwareFragments) if (fragment.type === "entry") allEntries.push(fragment);
 			else if (fragment.type === "section") if (fragment.title) titledSections.push(fragment);
 			else allEntries.push(...fragment.entries);
 			const initialFragments = parser.getDocFragments({