@iowarp/clio-coder 0.4.6 → 0.4.7

package/src/interactive/keybinding-manager.ts

@@ -64,20 +64,27 @@ export interface PlatformKeybindingWarning {
 
 export interface LeaderTarget {
 	key: string;
-	id: ClioKeybinding;
+	id: Keybinding;
+	label?: string;
+	disabledReason?: string;
 }
 
 export interface ClioKeybindingManager {
 	matches(data: string, id: Keybinding): boolean;
 	getKeys(id: Keybinding): ReadonlyArray<KeyId>;
-	getDescription(id: ClioKeybinding): string;
+	getDescription(id: Keybinding): string;
+	readonly generation: number;
+	reload(overrides: Readonly<Record<string, string | string[]>>): void;
+	onReload(listener: () => void): () => void;
+	isDisabled(id: Keybinding): boolean;
+	actionLabel(id: Keybinding): string;
 	getConflicts(): ReadonlyArray<KeybindingConflict>;
 	overrideCount(): number;
 	invalidCount(): number;
 	invalidBindings(): ReadonlyArray<InvalidKeybinding>;
 	platformWarnings(): ReadonlyArray<PlatformKeybindingWarning>;
 	leaderTargets(): ReadonlyArray<LeaderTarget>;
-	hotkeyEntries(): ReadonlyArray<{ id: ClioKeybinding; keys: string; description: string; source: "default" | "user" }>;
+	hotkeyEntries(): ReadonlyArray<{ id: Keybinding; keys: string; description: string; source: "default" | "user" }>;
 }
 
 const BASE_SPECIAL_KEYS = new Set([
@@ -156,6 +163,15 @@ const MODIFIERS = new Set(["ctrl", "shift", "alt", "super"]);
  * attempt to exercise pi-tui's matcher; we just reject identifiers that
  * would silently fail at match time.
  */
+function canonicalKey(key: string): string {
+	const parts = key.toLowerCase().split("+");
+	let base = parts.pop() ?? "";
+	if (base === "esc") base = "escape";
+	if (base === "return") base = "enter";
+	const modifiers = ["ctrl", "alt", "shift", "super"].filter((mod) => parts.includes(mod));
+	return [...modifiers, base].join("+");
+}
+
 function isValidKeyId(keyId: unknown): boolean {
 	if (typeof keyId !== "string" || keyId.length === 0) return false;
 	const parts = keyId.toLowerCase().split("+");
@@ -192,10 +208,13 @@ export function validateKeybindings(raw: Readonly<Record<string, string | string
 	const valid: KeybindingsConfig = {};
 	const invalid: InvalidKeybinding[] = [];
 	for (const [id, value] of Object.entries(raw)) {
+		if (!Object.hasOwn(CLIO_KEYBINDINGS, id)) {
+			invalid.push({ id, keys: ["unknown action ID; use /help"] });
+			continue;
+		}
 		if (typeof value === "string") {
-			if (value.length === 0) continue;
 			if (isValidKeyId(value)) {
-				valid[id] = value as KeyId;
+				valid[id] = canonicalKey(value) as KeyId;
 			} else {
 				invalid.push({ id, keys: [value] });
 			}
@@ -205,14 +224,17 @@ export function validateKeybindings(raw: Readonly<Record<string, string | string
 			const accepted: KeyId[] = [];
 			const rejected: string[] = [];
 			for (const entry of value) {
-				if (typeof entry !== "string" || entry.length === 0) continue;
+				if (typeof entry !== "string") {
+					rejected.push(String(entry));
+					continue;
+				}
 				if (isValidKeyId(entry)) {
-					accepted.push(entry as KeyId);
+					accepted.push(canonicalKey(entry) as KeyId);
 				} else {
 					rejected.push(entry);
 				}
 			}
-			if (accepted.length > 0) valid[id] = accepted;
+			if (accepted.length > 0 || value.length === 0) valid[id] = accepted;
 			if (rejected.length > 0) invalid.push({ id, keys: rejected });
 		}
 	}
@@ -329,8 +351,10 @@ function keyUsesAltLetter(keyId: string): boolean {
 
 function terminalReservedReason(keyId: string): string | null {
 	const key = normalizeKeyForRisk(keyId);
-	if (key === "ctrl+s" || key === "ctrl+q") return "terminal flow control may intercept this chord";
-	if (key === "ctrl+z") return "shell job control may suspend the process";
+	if (key === "ctrl+s")
+		return "an intermediary may intercept this chord; Node raw mode normally disables terminal flow control";
+	if (key === "ctrl+z")
+		return "an intermediary may intercept this chord; Node raw mode normally disables signal generation";
 	return null;
 }
 
@@ -342,7 +366,7 @@ function keyRiskReason(keyId: string, support: TerminalKeySupport): string | nul
 	return terminalReservedReason(key);
 }
 
-const MACOS_OPTION_DEFAULT_WARNING_ID = "clio.macos.option-letter.defaults";
+const MACOS_OPTION_DEFAULT_WARNING_ID = "clio-coder.macos.option-letter.defaults";
 
 export function detectPlatformKeybindingWarnings(
 	userBindings: Readonly<KeybindingsConfig>,
@@ -403,94 +427,147 @@ function joinKeys(keys: ReadonlyArray<KeyId>): string {
 	return keys.join(" / ");
 }
 
-function deriveLeaderTargets(inner: KeybindingsManager): LeaderTarget[] {
-	const targets: LeaderTarget[] = [];
-	for (const id of CLIO_APP_KEYBINDING_IDS) {
-		for (const key of inner.getKeys(id as Keybinding)) {
-			const base = altLetterBase(String(key));
-			if (base) targets.push({ key: base, id });
+const VIEWPORT_LEADER_TARGETS: LeaderTarget[] = [
+	{ key: "z", id: "tui.editor.undo" },
+	{ key: "r", id: "tui.altScreen.search" },
+	{ key: "p", id: "tui.altScreen.pageUp" },
+	{ key: "n", id: "tui.altScreen.pageDown" },
+	{ key: "home", id: "tui.altScreen.top" },
+	{ key: "end", id: "tui.altScreen.bottom" },
+	{ key: "", id: "tui.altScreen.previousPrompt" },
+	{ key: "", id: "tui.altScreen.nextPrompt" },
+];
+
+function keybindingScope(id: string): string {
+	if (id.startsWith("clio-coder.")) return "composer";
+	if (id.startsWith("tui.select.")) return "selection";
+	if (/tui.altScreen.search(Next|Previous|Close)/u.test(id)) return "search";
+	if (id.startsWith("tui.altScreen.")) return "fullscreen composer";
+	return "editable field";
+}
+
+function legacyKey(key: string): string {
+	const canonical = canonicalKey(key);
+	return (
+		({ "ctrl+i": "tab", "ctrl+m": "enter", "ctrl+[": "escape", "ctrl+_": "ctrl+-" } as Record<string, string>)[
+			canonical
+		] ?? canonical
+	);
+}
+
+/** Selection, search and editable input deliberately share delivered keys. */
+function scopesOverlap(a: string, b: string): boolean {
+	const left = keybindingScope(a),
+		right = keybindingScope(b);
+	if (left === "selection" || right === "selection") return left === right;
+	if (left === "search" || right === "search") return left === right;
+	if (
+		(a === "clio-coder.exit" && b === "tui.editor.deleteCharForward") ||
+		(b === "clio-coder.exit" && a === "tui.editor.deleteCharForward")
+	)
+		return false;
+	return true;
+}
+
+function effectiveConflicts(inner: KeybindingsManager): KeybindingConflict[] {
+	const keys = new Map<string, string[]>();
+	for (const id of Object.keys(CLIO_KEYBINDINGS) as Keybinding[]) {
+		for (const key of inner.getKeys(id)) {
+			const canonical = legacyKey(key);
+			const ids = keys.get(canonical) ?? [];
+			if (!ids.includes(id)) ids.push(id);
+			keys.set(canonical, ids);
 		}
 	}
-	return targets;
+	return [...keys]
+		.filter(
+			([, ids]) =>
+				ids.length > 1 && ids.some((id, index) => ids.slice(index + 1).some((other) => scopesOverlap(id, other))),
+		)
+		.map(([key, keybindings]) => ({
+			key: key as KeyId,
+			keybindings: keybindings.filter((id) => keybindings.some((other) => other !== id && scopesOverlap(id, other))),
+		}));
 }
 
 function buildManager(
-	inner: KeybindingsManager,
-	invalid: ReadonlyArray<InvalidKeybinding>,
-	platformWarnings: ReadonlyArray<PlatformKeybindingWarning>,
+	overrides: Readonly<Record<string, string | string[]>>,
+	env: Readonly<Record<string, string | undefined>>,
+	install: boolean,
 ): ClioKeybindingManager {
-	const frozen = invalid.map((entry) => ({ id: entry.id, keys: [...entry.keys] as ReadonlyArray<string> }));
-	const frozenPlatformWarnings = platformWarnings.map((entry) => ({
-		id: entry.id,
-		keys: [...entry.keys] as ReadonlyArray<string>,
-		terminal: entry.terminal,
-		reason: entry.reason,
-		source: entry.source,
-	}));
-	const frozenLeaderTargets = deriveLeaderTargets(inner).map((entry) => ({ ...entry }));
+	let validated = validateKeybindings(overrides);
+	const inner = new KeybindingsManager(CLIO_KEYBINDINGS, validated.valid);
+	if (install) setKeybindings(inner);
+	let generation = 0;
+	const listeners = new Set<() => void>();
+	const isDisabled = (id: Keybinding): boolean => {
+		const value = inner.getUserBindings()[id];
+		return Array.isArray(value) && value.length === 0;
+	};
+	const leaderTargets = (): LeaderTarget[] => {
+		if (inner.getKeys("clio-coder.leader").length === 0) return [];
+		const app = CLIO_APP_KEYBINDING_IDS.flatMap((id) => {
+			const descriptor = CLIO_APP_KEYBINDINGS[id];
+			return "leader" in descriptor ? [{ key: descriptor.leader, id }] : [];
+		});
+		return [...app, ...VIEWPORT_LEADER_TARGETS].filter(({ id }) => !isDisabled(id));
+	};
+	const actionLabel = (id: Keybinding): string => {
+		const keys = inner.getKeys(id);
+		const suffix = leaderTargets().find((entry) => entry.id === id)?.key;
+		return (
+			[keys.join(" / "), suffix ? `${inner.getKeys("clio-coder.leader")[0]} ${suffix}` : ""].filter(Boolean).join(" · ") ||
+			"unbound; see /help"
+		);
+	};
 	return {
-		matches(data, id) {
-			return inner.matches(data, id as Keybinding);
-		},
-		getKeys(id) {
-			return inner.getKeys(id as Keybinding);
-		},
-		getDescription(id) {
-			return inner.getDefinition(id as Keybinding).description ?? "";
-		},
-		getConflicts() {
-			return inner.getConflicts();
-		},
-		overrideCount() {
-			return Object.keys(inner.getUserBindings()).length;
+		matches: (data, id) => inner.matches(data, id),
+		getKeys: (id) => inner.getKeys(id),
+		getDescription: (id) => inner.getDefinition(id).description ?? "",
+		getConflicts: () => effectiveConflicts(inner),
+		get generation() {
+			return generation;
 		},
-		invalidCount() {
-			return frozen.reduce((sum, entry) => sum + entry.keys.length, 0);
+		reload(next) {
+			validated = validateKeybindings(next);
+			inner.setUserBindings(validated.valid);
+			if (install) setKeybindings(inner);
+			generation += 1;
+			for (const listener of listeners) listener();
 		},
-		invalidBindings() {
-			return frozen;
+		onReload(listener) {
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
 		},
-		platformWarnings() {
-			return frozenPlatformWarnings;
-		},
-		leaderTargets() {
-			return frozenLeaderTargets;
-		},
-		hotkeyEntries() {
-			const userBindings = inner.getUserBindings();
-			return CLIO_APP_KEYBINDING_IDS.map((id) => ({
+		isDisabled,
+		actionLabel,
+		overrideCount: () => Object.keys(validated.valid).length,
+		invalidCount: () => validated.invalid.reduce((sum, entry) => sum + entry.keys.length, 0),
+		invalidBindings: () => validated.invalid,
+		platformWarnings: () => detectPlatformKeybindingWarnings(validated.valid, detectTerminalKeySupport(env)),
+		leaderTargets,
+		hotkeyEntries: () =>
+			(Object.keys(CLIO_KEYBINDINGS) as Keybinding[]).map((id) => ({
 				id,
-				keys: joinKeys(inner.getKeys(id as Keybinding)),
-				description: inner.getDefinition(id as Keybinding).description ?? "",
-				source: userBindings[id] === undefined ? ("default" as const) : ("user" as const),
-			}));
-		},
+				keys: joinKeys(inner.getKeys(id)),
+				description: `${inner.getDefinition(id).description ?? ""} (${keybindingScope(id)}${isDisabled(id) ? "; disabled by user" : ""})${id === "tui.input.copy" ? "; composer Ctrl+C cancels; use native terminal clipboard" : ""}`,
+				source: validated.valid[id] === undefined ? "default" : "user",
+			})),
 	};
 }
 
-/**
- * Build a `ClioKeybindingManager` from the provided settings snapshot. The
- * resulting manager is also installed as pi-tui's global so editor and
- * select components pick up the same overrides. Callers are expected to
- * recreate the manager if `settings.interface.keybindings` is replaced wholesale;
- * partial live updates should instead go through `manager` state.
- */
 export function createKeybindingManager(
 	settings: Readonly<ClioSettings>,
-	env: NodeJS.ProcessEnv | Readonly<Record<string, string | undefined>> = process.env,
+	env: Readonly<Record<string, string | undefined>> = process.env,
 ): ClioKeybindingManager {
-	const { valid, invalid } = validateKeybindings(settings.interface.keybindings ?? {});
-	const inner = new KeybindingsManager(CLIO_KEYBINDINGS, valid);
-	setKeybindings(inner);
-	return buildManager(inner, invalid, detectPlatformKeybindingWarnings(valid, detectTerminalKeySupport(env)));
+	return buildManager(settings.interface.keybindings ?? {}, env, true);
 }
 
-/** Pure test hook: build a manager from a raw settings snapshot without touching the pi-tui global. */
 export function createKeybindingManagerForTesting(
 	overrides: Readonly<Record<string, string | string[]>> = {},
-	env: NodeJS.ProcessEnv | Readonly<Record<string, string | undefined>> = {},
+	env: Readonly<Record<string, string | undefined>> = {},
 ): ClioKeybindingManager {
-	const { valid, invalid } = validateKeybindings(overrides);
-	const inner = new KeybindingsManager(CLIO_KEYBINDINGS, valid);
-	return buildManager(inner, invalid, detectPlatformKeybindingWarnings(valid, detectTerminalKeySupport(env)));
+	return buildManager(overrides, env, false);
 }

package/src/interactive/keyboard-owner.ts

@@ -0,0 +1,37 @@
+import {
+	type Component,
+	decodePrintableKey,
+	Editor,
+	Input,
+	type TUI,
+	TuiAltScreen,
+	TuiMainScreen,
+} from "../engine/tui.js";
+
+/** Internal focus contract for Clio's existing components and frame wrappers. */
+export interface KeyboardOwner {
+	readonly keyboardScope?: "browse" | "edit" | "review";
+	undoInput?(): boolean;
+}
+
+export function keyboardOwner(component: object | null): KeyboardOwner {
+	if (component instanceof Editor || component instanceof Input) {
+		return {
+			keyboardScope: "edit",
+			undoInput: () => {
+				component.applyEdit("undo");
+				return true;
+			},
+		};
+	}
+	return (component as KeyboardOwner | null) ?? {};
+}
+
+export function focusedComponent(tui: TUI): Component | null {
+	return tui instanceof TuiAltScreen || tui instanceof TuiMainScreen ? tui.getFocusedComponent() : null;
+}
+
+/** Preserve controls and paste packets; normalize only encoded printable keys. */
+export function localKey(data: string): string {
+	return data.includes("\x1b[200~") ? data : (decodePrintableKey(data) ?? data);
+}

package/src/interactive/leader-key.ts

@@ -1,139 +1,86 @@
-import type { ClioKeybinding } from "../domains/config/keybindings.js";
-import { isKeyRelease, type KeyId, matchesKey } from "../engine/tui.js";
+import { decodePrintableKey, isKeyRelease, isKeyRepeat, type Keybinding, matchesKey } from "../engine/tui.js";
 
 export interface LeaderTarget {
 	key: string;
-	id: ClioKeybinding;
+	id: Keybinding;
+	label?: string;
+	disabledReason?: string;
 }
-
-export type LeaderKeyState = { status: "idle" } | { status: "pending"; expiresAt: number };
-
+export type LeaderKeyState = { status: "idle" } | { status: "pending"; selected: number; notice?: string };
+export const IDLE_LEADER_STATE: LeaderKeyState = { status: "idle" };
 export interface LeaderKeyRouteDeps {
-	matchesLeader: (data: string) => boolean;
+	matchesLeader(data: string): boolean;
 	leaderTargets: ReadonlyArray<LeaderTarget>;
-	dispatchAction: (id: ClioKeybinding) => boolean;
-	now: number;
-	timeoutMs?: number;
+	dispatchAction(id: Keybinding): boolean;
 	isRelease?: (data: string) => boolean;
 }
-
 export interface LeaderKeyRouteResult {
 	state: LeaderKeyState;
 	consumed: boolean;
 }
 
-export const LEADER_TIMEOUT_MS = 1500;
-export const IDLE_LEADER_STATE: LeaderKeyState = { status: "idle" };
-
-function baseLetterFromInput(data: string): string | null {
-	if (data.length === 1) {
-		const lower = data.toLowerCase();
-		return lower >= "a" && lower <= "z" ? lower : null;
-	}
-	for (let code = 97; code <= 122; code += 1) {
-		const key = String.fromCharCode(code) as KeyId;
-		if (matchesKey(data, key) || matchesKey(data, `shift+${key}` as KeyId)) return key;
-	}
-	return null;
-}
-
-function isEscapeKey(data: string): boolean {
-	return matchesKey(data, "escape") && !isKeyRelease(data);
-}
-
-/** Pure leader-key router: returns the next leader state and whether input was swallowed. */
 export function routeLeaderKey(data: string, state: LeaderKeyState, deps: LeaderKeyRouteDeps): LeaderKeyRouteResult {
-	const timeoutMs = deps.timeoutMs ?? LEADER_TIMEOUT_MS;
-	if (state.status === "pending") {
-		if (deps.now > state.expiresAt) return { state: IDLE_LEADER_STATE, consumed: true };
-		if (deps.isRelease?.(data) ?? false) return { state, consumed: true };
-		if (isEscapeKey(data)) return { state: IDLE_LEADER_STATE, consumed: true };
-		const base = baseLetterFromInput(data);
-		const target = base ? deps.leaderTargets.find((entry) => entry.key === base) : undefined;
-		if (target) {
-			deps.dispatchAction(target.id);
-			return { state: IDLE_LEADER_STATE, consumed: true };
-		}
-		return { state: IDLE_LEADER_STATE, consumed: true };
+	if (isKeyRelease(data)) return { state, consumed: state.status === "pending" };
+	if (matchesKey(data, "ctrl+c")) return { state: IDLE_LEADER_STATE, consumed: false };
+	if (state.status === "idle") {
+		return deps.matchesLeader(data) && !isKeyRepeat(data)
+			? { state: { status: "pending", selected: 0 }, consumed: true }
+			: { state, consumed: false };
 	}
-	if (deps.isRelease?.(data) ?? false) return { state, consumed: false };
-	if (!deps.matchesLeader(data)) return { state, consumed: false };
-	return { state: { status: "pending", expiresAt: deps.now + timeoutMs }, consumed: true };
-}
-
-export interface LeaderKeyTimeout {
-	unref?(): void;
+	if (isKeyRepeat(data) && !matchesKey(data, "up") && !matchesKey(data, "down")) return { state, consumed: true };
+	if (matchesKey(data, "escape") || deps.matchesLeader(data)) return { state: IDLE_LEADER_STATE, consumed: true };
+	const count = deps.leaderTargets.length;
+	if (matchesKey(data, "up") || matchesKey(data, "down")) {
+		const delta = matchesKey(data, "up") ? -1 : 1;
+		return {
+			state: { status: "pending", selected: count ? (state.selected + delta + count) % count : 0 },
+			consumed: true,
+		};
+	}
+	const key = data.includes("\x1b[200~")
+		? null
+		: (decodePrintableKey(data) ?? (data.length === 1 ? data : undefined))?.toLowerCase();
+	const target = matchesKey(data, "enter")
+		? deps.leaderTargets[state.selected]
+		: deps.leaderTargets.find(
+				(entry) =>
+					entry.key &&
+					(entry.key === key ||
+						(entry.key === "home" && matchesKey(data, "home")) ||
+						(entry.key === "end" && matchesKey(data, "end"))),
+			);
+	if (!target) return { state: { ...state, notice: "No action for this key" }, consumed: true };
+	if (target.disabledReason) return { state: { ...state, notice: target.disabledReason }, consumed: true };
+	deps.dispatchAction(target.id);
+	return { state: IDLE_LEADER_STATE, consumed: true };
 }
 
 export interface LeaderKeyControllerDeps {
-	matchesLeader: (data: string) => boolean;
-	leaderTargets: () => ReadonlyArray<LeaderTarget>;
-	dispatchAction: (id: ClioKeybinding) => boolean;
+	matchesLeader(data: string): boolean;
+	leaderTargets(): ReadonlyArray<LeaderTarget>;
+	dispatchAction(id: Keybinding): boolean;
 	isRelease: (data: string) => boolean;
-	now?: () => number;
-	timeoutMs?: number;
-	scheduleTimeout?: (callback: () => void, delayMs: number) => LeaderKeyTimeout;
-	clearScheduledTimeout?: (timeout: LeaderKeyTimeout) => void;
-	/**
-	 * Fired when the leader arms or disarms, including on timeout.
-	 *
-	 * Ctrl+G is the fallback for terminals where Alt is broken, and the frame
-	 * between it and the next key was identical to the idle frame: nothing said
-	 * the leader had taken, on the one surface whose users cannot test it with a
-	 * working Alt shortcut.
-	 */
 	onStateChange?: (pending: boolean) => void;
+	onMenuChange?: (state: LeaderKeyState, targets: ReadonlyArray<LeaderTarget>) => void;
 }
-
 export interface LeaderKeyController {
 	isPending(): boolean;
 	route(data: string): boolean;
 	reset(): void;
 	dispose(): void;
 }
-
 export function createLeaderKeyController(deps: LeaderKeyControllerDeps): LeaderKeyController {
-	const now = deps.now ?? Date.now;
-	const scheduleTimeout = deps.scheduleTimeout ?? ((callback, delayMs) => setTimeout(callback, delayMs));
-	const clearScheduledTimeout =
-		deps.clearScheduledTimeout ?? ((timeout: LeaderKeyTimeout) => clearTimeout(timeout as ReturnType<typeof setTimeout>));
 	let state: LeaderKeyState = IDLE_LEADER_STATE;
-	let timer: LeaderKeyTimeout | null = null;
-
 	const setState = (next: LeaderKeyState): void => {
-		const wasPending = state.status === "pending";
+		const changed = state.status !== next.status;
 		state = next;
-		if (timer) {
-			clearScheduledTimeout(timer);
-			timer = null;
-		}
-		if (next.status !== "pending") {
-			if (wasPending) deps.onStateChange?.(false);
-			return;
-		}
-		if (!wasPending) deps.onStateChange?.(true);
-		timer = scheduleTimeout(
-			() => {
-				state = IDLE_LEADER_STATE;
-				timer = null;
-				deps.onStateChange?.(false);
-			},
-			Math.max(0, next.expiresAt - now()),
-		);
-		timer.unref?.();
+		deps.onMenuChange?.(state, deps.leaderTargets());
+		if (changed) deps.onStateChange?.(state.status === "pending");
 	};
-
 	return {
 		isPending: () => state.status === "pending",
-		route: (data) => {
-			const result = routeLeaderKey(data, state, {
-				matchesLeader: deps.matchesLeader,
-				leaderTargets: deps.leaderTargets(),
-				dispatchAction: deps.dispatchAction,
-				now: now(),
-				...(deps.timeoutMs === undefined ? {} : { timeoutMs: deps.timeoutMs }),
-				isRelease: deps.isRelease,
-			});
+		route(data) {
+			const result = routeLeaderKey(data, state, { ...deps, leaderTargets: deps.leaderTargets() });
 			if (result.state !== state) setState(result.state);
 			return result.consumed;
 		},

package/src/interactive/leader-menu.ts

@@ -0,0 +1,45 @@
+import { type Component, type OverlayHandle, type TUI, truncateToWidth } from "../engine/tui.js";
+import type { LeaderKeyState, LeaderTarget } from "./leader-key.js";
+import { showClioOverlayFrame } from "./overlay-frame.js";
+import { clioTheme } from "./theme/index.js";
+
+/** Noncapturing presentation: controller retains the underlying cancellation owner. */
+export function createLeaderMenu(tui: TUI, scope: () => string, keyLabel: (id: LeaderTarget["id"]) => string) {
+	let handle: OverlayHandle | null = null;
+	let state: LeaderKeyState = { status: "idle" };
+	let targets: ReadonlyArray<LeaderTarget> = [];
+	const component: Component = {
+		render(width) {
+			if (state.status === "idle") return [];
+			const selected = state.selected;
+			const count = Math.max(1, Math.min(10, tui.terminal.rows - 8));
+			const start = Math.max(0, Math.min(selected - Math.floor(count / 2), targets.length - count));
+			return [
+				`${scope()} · letters select actions · close, then /help for commands`,
+				...targets.slice(start, start + count).map((entry, index) => {
+					const text = `${start + index === selected ? "›" : " "} ${entry.key || "·"}  ${entry.label ?? entry.id}  ${keyLabel(entry.id)}${entry.disabledReason ? ` (${entry.disabledReason})` : ""}`;
+					return truncateToWidth(start + index === selected ? clioTheme().fg("accent", text) : text, width);
+				}),
+				`${targets.length ? `${selected + 1}/${targets.length}` : "No actions in this scope"} · ${state.notice ?? "Up/Down select · Enter run · Esc close · Ctrl+C cancel"}`,
+			].map((line) => truncateToWidth(line, width));
+		},
+		invalidate() {},
+	};
+	return (next: LeaderKeyState, entries: ReadonlyArray<LeaderTarget>): void => {
+		state = next;
+		targets = entries;
+		if (state.status === "idle") {
+			handle?.hide();
+			handle = null;
+		} else if (!handle)
+			handle = showClioOverlayFrame(tui, component, {
+				title: "Actions",
+				markerId: "keyboard-actions",
+				anchor: "top-center",
+				width: 88,
+				nonCapturing: true,
+				footerHint: () => `${keyLabel("clio-coder.leader")} or Esc closes this menu`,
+			});
+		tui.requestRender();
+	};
+}

package/src/interactive/overlay-ask-user-lifecycle.ts

@@ -1,5 +1,10 @@
 import type { TUI } from "../engine/tui.js";
-import { type AskUserHandler, cancelledAskUserResult } from "../tools/ask-user.js";
+import {
+	type AskUserAnswer,
+	type AskUserHandler,
+	type AskUserQuestion,
+	cancelledAskUserResult,
+} from "../tools/ask-user.js";
 import type { OverlayState } from "./overlay-key-routing.js";
 import { type AskUserOverlaySession, openAskUserOverlay } from "./overlays/ask-user.js";
 
@@ -19,6 +24,8 @@ export interface OverlayAskUserLifecycleDeps {
 	 * overlay session opens, not per question, so one interview notifies once.
 	 */
 	onOperatorParked?(): void;
+	/** A round the operator answered, for the transcript record. Not fired on cancel. */
+	onRoundAnswered?(questions: ReadonlyArray<AskUserQuestion>, answers: ReadonlyArray<AskUserAnswer>): void;
 }
 
 export interface OverlayAskUserLifecycle {
@@ -84,6 +91,7 @@ export function createOverlayAskUserLifecycle(deps: OverlayAskUserLifecycleDeps)
 		if (!activeSession) return cancelledAskUserResult();
 		pendingCancel = cancel;
 		const result = await activeSession.ask(questions, invokeOptions?.decisionPresentation);
+		if (result.cancelled !== true && result.answers.length > 0) deps.onRoundAnswered?.(questions, result.answers);
 		if (result.cancelled === true || !toolBacked) {
 			if (result.cancelled === true) cancelledForTurn = true;
 			close();

package/src/interactive/overlay-frame.ts

@@ -11,6 +11,7 @@ import {
 	truncateToWidth,
 	visibleWidth,
 } from "../engine/tui.js";
+import { keyboardOwner } from "./keyboard-owner.js";
 import { enterModal, type ModalMarkerSink } from "./modal-marker.js";
 import { type ClioToken, clioTheme, padAnsi, screenTitle, selectListTheme, settingsListTheme } from "./theme/index.js";
 
@@ -43,6 +44,13 @@ export class FocusBox extends Box {
 		this.onInput = options?.onInput;
 	}
 
+	get keyboardScope() {
+		return keyboardOwner(this.inputTarget).keyboardScope;
+	}
+	undoInput(): boolean {
+		return keyboardOwner(this.inputTarget).undoInput?.() ?? false;
+	}
+
 	handleInput(data: string): void {
 		if (this.onInput) {
 			this.onInput(data);
@@ -427,6 +435,13 @@ export class ClioOverlayFrame implements Component {
 		return lines;
 	}
 
+	get keyboardScope() {
+		return keyboardOwner(this.child).keyboardScope;
+	}
+	undoInput(): boolean {
+		return keyboardOwner(this.child).undoInput?.() ?? false;
+	}
+
 	handleInput(data: string): void {
 		this.child.handleInput?.(data);
 	}