@iowarp/clio-coder 0.4.5 → 0.4.7

package/src/interactive/interactive-slash-runtime.ts

@@ -17,7 +17,7 @@ import {
 	type ThinkingLevel,
 	thinkingLevelChoiceLabel,
 } from "../domains/providers/index.js";
-import type { LibraryEntryKind, ResourcesContract } from "../domains/resources/index.js";
+import type { ResourcesContract } from "../domains/resources/index.js";
 import { installSkill } from "../domains/resources/skills/marketplace.js";
 import { foldDecisionBoard } from "../domains/session/decision-board.js";
 import type { SessionContract, SessionEntry } from "../domains/session/index.js";
@@ -33,7 +33,7 @@ import type { ChatLoop } from "./chat-loop.js";
 import { type ChatPanel, createChatPanel } from "./chat-panel.js";
 import { rehydrateChatPanelFromTurns } from "./chat-renderer.js";
 import { runCompactWithNotice } from "./command-fallbacks.js";
-import { appendNotice, appendOperatorCommand } from "./command-output.js";
+import { appendNotice, appendOperatorAside, appendOperatorCommand, appendReferenceCard } from "./command-output.js";
 import { runOperatorRecall } from "./context-recall-command.js";
 import { renderSessionHtml } from "./export-html/index.js";
 import { dateLocal } from "./format-time.js";
@@ -44,6 +44,7 @@ import {
 	type CouncilDispatchOutcome,
 	dispatchSlashCommand,
 	type InitCommandOptions,
+	type LibraryBrowseRequest,
 	parseSlashCommand,
 	type RunIo,
 	type SettingsAreaId,
@@ -61,10 +62,12 @@ export interface InteractiveSlashSubmitExpansion {
 	images: ImageContent[];
 	workingContextPaths: string[];
 	pendingSkillRequests: PendingSkillRequest[];
+	/** The typed line and a template note to paint instead of `text`; see `InteractiveSubmitExpansion`. */
+	display?: { text: string; note: string };
 }
 
 type SlashChat = Pick<ChatLoop, "clearSkillSurface" | "getSessionId" | "isStreaming" | "submit">;
-type SlashChatPanel = Pick<ChatPanel, "appendReplayBlock" | "appendUser" | "clearFoldOverrides">;
+type SlashChatPanel = Pick<ChatPanel, "appendReplayBlock" | "appendUser">;
 type UserTurnStatus = import("./chat-panel.js").UserTurnStatus;
 type SlashResources = Pick<ResourcesContract, "prompts" | "expandPromptTemplate" | "reload">;
 type SlashExtensions = Pick<ExtensionsContract, "list">;
@@ -72,6 +75,9 @@ type SlashAgents = Pick<AgentsContract, "getSpec" | "listSpecs">;
 type SlashShare = Pick<ShareContract, "writeArchive" | "planImport" | "importArchive">;
 
 export interface InteractiveSlashRuntimeDeps {
+	keyboardActions?: SlashCommandContext["keyboardActions"];
+	operatorExtensions?: SlashCommandContext["operatorExtensions"];
+	showExtensionOutput?: SlashCommandContext["showExtensionOutput"];
 	io: RunIo;
 	bus: SafeEventBus;
 	dispatch: DispatchContract;
@@ -82,6 +88,7 @@ export interface InteractiveSlashRuntimeDeps {
 	resources?: SlashResources;
 	extensions?: SlashExtensions;
 	reloadExtensions?: SlashCommandContext["reloadExtensions"];
+	reloadPlugins?: SlashCommandContext["reloadPlugins"];
 	interop?: SlashCommandContext["interop"];
 	agents?: SlashAgents;
 	share?: SlashShare;
@@ -119,7 +126,7 @@ export interface InteractiveSlashRuntimeDeps {
 	session?: Pick<SessionContract, "tree" | "current" | "appendEntry">;
 	expandSubmit: (text: string) => Promise<InteractiveSlashSubmitExpansion>;
 	openAskUser: AskUserHandler;
-	openSkillsHub: (tab?: LibraryEntryKind) => void;
+	openSkillsHub: (request?: LibraryBrowseRequest) => void;
 	openCost: () => void;
 	/** Run one `/btw` side question in its own overlay. */
 	openSideQuestion: (question: string) => void;
@@ -155,8 +162,6 @@ export interface InteractiveSlashRuntimeDeps {
 	openTree: () => void;
 	openMessagePicker: () => void;
 	openHelp: (query?: string) => void;
-	openAgents: () => void;
-	openPrompts: () => void;
 	openExtensions: () => void;
 	openInterop?: () => void;
 	openContextReset: () => void;
@@ -178,7 +183,6 @@ export interface InteractiveSlashRuntime {
 }
 
 /** Owns slash-command context construction and its asynchronous command state. */
-const OUTPUT_VERBOSITIES: ReadonlyArray<ClioSettings["interface"]["outputDetail"]> = ["minimal", "default", "verbose"];
 
 /** Thinking capability of the active orchestrator target and model, or null when unresolved. */
 export function resolveThinkingCapability(
@@ -261,13 +265,22 @@ export function createInteractiveSlashRuntime(deps: InteractiveSlashRuntimeDeps)
 			// is in the ledger yet, and a refused preflight must not leave a row
 			// that reads like a committed turn (issue #251).
 			let rowStatus: UserTurnStatus = "pending";
-			if (!willQueue) deps.chatPanel.appendUser(sub.text, () => rowStatus);
+			if (!willQueue) {
+				deps.chatPanel.appendUser(sub.display?.text ?? sub.text, () => rowStatus);
+				if (sub.display) {
+					appendOperatorAside(sub.display.note, {
+						appendReplayBlock: (renderBlock) => deps.chatPanel.appendReplayBlock(renderBlock),
+						requestRender: deps.requestRender,
+					});
+				}
+			}
 			deps.requestRender();
 			let acknowledgeAdmission = (): void => {};
 			const admitted = new Promise<void>((resolve) => {
 				acknowledgeAdmission = resolve;
 			});
 			const turn = deps.chat.submit(sub.text, {
+				...(sub.display ? { display: sub.display } : {}),
 				...(sub.images.length > 0 ? { images: sub.images } : {}),
 				...(sub.workingContextPaths.length > 0 ? { workingContextPaths: sub.workingContextPaths } : {}),
 				...(sub.pendingSkillRequests.length > 0 ? { pendingSkillRequests: sub.pendingSkillRequests } : {}),
@@ -311,6 +324,13 @@ export function createInteractiveSlashRuntime(deps: InteractiveSlashRuntimeDeps)
 	const admitChat = async (text: string, signal?: AbortSignal): Promise<void> => {
 		try {
 			signal?.throwIfAborted();
+			// submitChat can be called directly, bypassing command dispatch. Keep
+			// the reserved clear command ahead of skill lookup and installation.
+			const command = parseSlashCommand(text);
+			if (command.kind === "skill-surface-clear") {
+				dispatchSlashCommand(command, context);
+				return;
+			}
 			const submitted = await deps.expandSubmit(text);
 			signal?.throwIfAborted();
 			const uninstalled = submitted.pendingSkillRequests.find((request) => !request.installed);
@@ -380,6 +400,12 @@ export function createInteractiveSlashRuntime(deps: InteractiveSlashRuntimeDeps)
 				requestRender: deps.requestRender,
 			});
 		},
+		showReference: (card) => {
+			appendReferenceCard(card, {
+				appendReplayBlock: (renderBlock) => deps.chatPanel.appendReplayBlock(renderBlock),
+				requestRender: deps.requestRender,
+			});
+		},
 		dispatch: deps.dispatch,
 		...(deps.getDecisionBoard ? { getDecisionBoard: deps.getDecisionBoard } : {}),
 		bus: deps.bus,
@@ -394,6 +420,9 @@ export function createInteractiveSlashRuntime(deps: InteractiveSlashRuntimeDeps)
 		openSkillsHub: deps.openSkillsHub,
 		clearSkillSurface: () => deps.chat.clearSkillSurface(),
 		listExtensions: () => deps.extensions?.list(cwd(), { all: true }) ?? [],
+		...(deps.keyboardActions ? { keyboardActions: deps.keyboardActions } : {}),
+		...(deps.operatorExtensions ? { operatorExtensions: deps.operatorExtensions } : {}),
+		...(deps.showExtensionOutput ? { showExtensionOutput: deps.showExtensionOutput } : {}),
 		listAgents: () => deps.agents?.listSpecs().filter((spec) => spec.audience !== "internal") ?? [],
 		listDelegationAgents: () => deps.getSettings?.().integrations.externalAgents.entries ?? [],
 		exportShareArchive: (outPath) => {
@@ -466,7 +495,7 @@ export function createInteractiveSlashRuntime(deps: InteractiveSlashRuntimeDeps)
 			if (!match) {
 				return { status: "unsupported", level, supported: supported.map(labelFor) };
 			}
-			// Session scope, like /output: onSetThinkingLevel writes the level
+			// Session scope, like Alt+O: onSetThinkingLevel writes the level
 			// through to settings.yaml as the new default, which a slash command
 			// has no mandate to do.
 			if (deps.commitSetting) {
@@ -508,42 +537,6 @@ export function createInteractiveSlashRuntime(deps: InteractiveSlashRuntimeDeps)
 					if (selected) dispatchSlashCommand({ kind: "thinking-set", level: selected.value }, context);
 				});
 		},
-		setOutputVerbosity: (verbosity) => {
-			if (!deps.getSettings || !(deps.commitSetting || deps.writeSettings)) return { status: "unavailable" };
-			const requested = verbosity.trim().toLowerCase();
-			const match = OUTPUT_VERBOSITIES.find((candidate) => candidate === requested);
-			if (!match) return { status: "unsupported", verbosity, supported: OUTPUT_VERBOSITIES };
-			const next = structuredClone(deps.getSettings()) as ClioSettings;
-			next.interface.outputDetail = match;
-			// Session scope: /output changes this session and leaves settings.yaml
-			// alone. Saving it as the default is what Settings → Terminal is for.
-			if (deps.commitSetting) deps.commitSetting("interface.outputDetail", next, "session");
-			else deps.writeSettings?.(next);
-			// `/output` is also the explicit reset action for transcript folds. Do
-			// this even when the requested level already matches the current one;
-			// the render-time change detector cannot observe a same-value command.
-			deps.chatPanel.clearFoldOverrides();
-			deps.refreshFooter();
-			return { status: "applied", verbosity: match };
-		},
-		openOutputPicker: () => {
-			void deps
-				.openAskUser([
-					{
-						question: "Choose transcript detail for this session.",
-						header: "Output",
-						options: OUTPUT_VERBOSITIES.map((value) => ({
-							label: `${value[0]?.toUpperCase()}${value.slice(1)}`,
-						})),
-					},
-				])
-				.then((result) => {
-					if (result.cancelled) return;
-					const answer = result.answers[0]?.answer.toLowerCase();
-					const selected = OUTPUT_VERBOSITIES.find((value) => value === answer);
-					if (selected) dispatchSlashCommand({ kind: "output-set", verbosity: selected }, context);
-				});
-		},
 		openModel: deps.openModel,
 		providers: deps.providers,
 		applyModelRef: (ref) => {
@@ -568,10 +561,9 @@ export function createInteractiveSlashRuntime(deps: InteractiveSlashRuntimeDeps)
 		openTree: deps.openTree,
 		openMessagePicker: deps.openMessagePicker,
 		openHelp: deps.openHelp,
-		openAgents: deps.openAgents,
-		openPrompts: deps.openPrompts,
 		openExtensions: deps.openExtensions,
 		...(deps.reloadExtensions ? { reloadExtensions: deps.reloadExtensions } : {}),
+		...(deps.reloadPlugins ? { reloadPlugins: deps.reloadPlugins } : {}),
 		...(deps.openInterop ? { openInterop: deps.openInterop } : {}),
 		...(deps.interop ? { interop: deps.interop } : {}),
 		setEditorText: (text) => {
@@ -595,7 +587,7 @@ export function createInteractiveSlashRuntime(deps: InteractiveSlashRuntimeDeps)
 				// operator overrides, and rendered at a stable width. HTML converts
 				// the resulting ANSI presentation to inline styles; Markdown keeps the
 				// prior plain-text fenced transcript.
-				const exportPanel = createChatPanel({ unboundedToolBodies: true, getOutputVerbosity: () => "verbose" });
+				const exportPanel = createChatPanel({ unboundedToolBodies: true, getOutputStyle: () => "detailed" });
 				// Scoped to the leaf the session is on, the same way /resume replays
 				// (issue #107): with a /tree pin persisted and not yet extended, the
 				// file still holds the abandoned branch after the pin, and an unscoped

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/layout.ts

@@ -13,6 +13,7 @@ export interface LayoutParts {
 export interface LayoutOptions {
 	mode?: TuiMode;
 	fullscreenScrollbar?: ScrollViewScrollbar;
+	onTranscript?: (view: ScrollView) => void;
 }
 
 export interface FullscreenLayout {
@@ -20,10 +21,7 @@ export interface FullscreenLayout {
 	transcript: ScrollView;
 }
 
-function buildFullscreenLayout(
-	parts: LayoutParts,
-	options: Pick<LayoutOptions, "fullscreenScrollbar"> = {},
-): FullscreenLayout {
+function buildFullscreenLayout(parts: LayoutParts, options: LayoutOptions = {}): FullscreenLayout {
 	const document = new Container();
 	document.addChild(parts.banner);
 	document.addChild(parts.chat);
@@ -36,6 +34,7 @@ function buildFullscreenLayout(
 		scrollbarTrackStyle: (text) => theme.fg("frame", text),
 		scrollbarThumbStyle: () => theme.fg("frameStrong", GLYPH.barFull),
 	});
+	options.onTranscript?.(transcript);
 	const dock = new VStack();
 	if (parts.pending) dock.addChild(parts.pending, { shrink: 1, minSize: 0 });
 	dock.addChild(parts.editor, { shrink: 1, minSize: 3 });
@@ -56,3 +55,29 @@ export function buildLayout(parts: LayoutParts, options: LayoutOptions = {}): Co
 	root.addChild(parts.footer);
 	return root;
 }
+
+/** Keep the nearest surviving text at the viewport when a preset changes row counts. */
+export function preserveTranscriptScroll(view: ScrollView | undefined, width: number, mutation: () => void): void {
+	if (!view || view.isFollowingEnd) {
+		mutation();
+		return;
+	}
+	const top = view.scrollTop;
+	const before = view.render(width);
+	mutation();
+	const after = view.render(width);
+	for (let row = top; row < Math.min(before.length, top + view.viewportHeight); row++) {
+		const anchor = before[row];
+		if (!anchor?.trim()) continue;
+		let match = -1;
+		for (let index = 0; index < after.length; index++) {
+			if (after[index] === anchor && (match < 0 || Math.abs(index - row) < Math.abs(match - row))) match = index;
+		}
+		if (match >= 0) {
+			view.updateLayout(after.length, view.viewportHeight, () => {});
+			view.scrollTo(Math.max(0, match - (row - top)), { disableFollow: true });
+			return;
+		}
+	}
+	view.scrollTo(top, { disableFollow: true });
+}