@oh-my-pi/pi-tui 18.3.2 → 18.3.3

package/src/key-hint-format.ts

@@ -0,0 +1,122 @@
+/**
+ * Key-hint formatting, kept free of the native addon: it imports only types
+ * plus the theme symbol mirror, so addon-free CLI paths (`omp --version`,
+ * help text in cli/command-help.ts) can format keys without loading
+ * `@oh-my-pi/pi-natives` through the keybindings registry.
+ */
+import type { KeyId } from "./keybindings";
+import type { ModifierName } from "./keys";
+import { activeThemeSymbol } from "./theme/active-symbols";
+import type { SymbolKey } from "./theme/symbols";
+
+/**
+ * Key hint formatting: every key shown to the user renders through
+ * {@link formatKeyHint}, so a key reads the same everywhere in the UI.
+ *
+ * Keys resolve through the active theme's `key.*` symbols — words in the
+ * ascii preset, keycap glyphs in unicode, icons in nerd — falling back to the
+ * ascii words before a theme loads. Modifiers are platform-aware: macOS
+ * keycaps are labelled ⌃ ⌥ ⌘ (`key.*Mac`), while other platforms keep
+ * `Ctrl`/`Alt`/`Super`, since those glyphs name no key on a PC keyboard.
+ */
+
+/**
+ * Platform override for key-hint rendering; `undefined` resolves to the host
+ * `process.platform`. Mirrors `setKittyProtocolActive` in the TUI keys module:
+ * a single seam that keeps hint output deterministic in tests without mutating
+ * the global `process.platform`.
+ */
+let keyHintPlatformOverride: NodeJS.Platform | undefined;
+
+/** Pin the platform used to render modifier labels (test seam). */
+export function setKeyHintPlatform(platform: NodeJS.Platform | undefined): void {
+	keyHintPlatformOverride = platform;
+}
+
+/** Platform currently used for key-hint rendering. */
+export function keyHintPlatform(): NodeJS.Platform {
+	return keyHintPlatformOverride ?? process.platform;
+}
+
+/** Modifier → [generic symbol, macOS symbol], in display order (⌃⌥⇧⌘, as macOS menus list them). */
+const MODIFIER_SYMBOLS: Record<string, readonly [SymbolKey, SymbolKey] | undefined> = {
+	ctrl: ["key.ctrl", "key.ctrlMac"],
+	alt: ["key.alt", "key.altMac"],
+	shift: ["key.shift", "key.shift"],
+	super: ["key.super", "key.superMac"],
+};
+const KEY_SYMBOLS: Record<string, SymbolKey | undefined> = {
+	esc: "key.esc",
+	escape: "key.esc",
+	enter: "key.enter",
+	return: "key.enter",
+	space: "key.space",
+	tab: "key.tab",
+	backspace: "key.backspace",
+	delete: "key.delete",
+	up: "key.up",
+	down: "key.down",
+	left: "key.left",
+	right: "key.right",
+};
+
+/** Keys without a keycap glyph; spelled out in every preset. */
+const KEY_WORDS: Record<string, string | undefined> = {
+	home: "Home",
+	end: "End",
+	pageup: "PgUp",
+	pagedown: "PgDn",
+	insert: "Ins",
+};
+
+function keySymbol(key: SymbolKey): string {
+	return activeThemeSymbol(key);
+}
+
+const HAS_LETTER = /[A-Za-z0-9]/;
+
+/** A displayable key: a chord, or a bare modifier for "hold ⇧" style hints. */
+export type KeyName = KeyId | ModifierName;
+
+/**
+ * Format one key for display: `"ctrl+shift+c"` → `⌃⇧C` (macOS) / `Ctrl+⇧C`,
+ * `"escape"` → `⎋`, `"alt+up"` → `⌥↑` / `Alt+↑`, `"shift"` → `⇧`.
+ * A glyph modifier is followed by the preset's `key.joiner` (nothing in
+ * unicode, a space in nerd, whose icons blur together when adjacent); a word
+ * modifier takes a `+`. Modifiers
+ * render in canonical order whatever the binding says (`shift+ctrl+p` → `⌃⇧P`).
+ * A bare letter stays lowercase (`q`) since `Q` would read as ⇧Q; in a chord it
+ * is capitalized. Other keys are capitalized (`f5` → `F5`).
+ */
+export function formatKeyHint(key: KeyName): string {
+	const mac = keyHintPlatform() === "darwin";
+	// A trailing `+` is the plus key itself (`+`, `ctrl++`), not a separator.
+	const parts = key.endsWith("+") ? [...key.slice(0, -1).split("+").slice(0, -1), "+"] : key.split("+");
+	const base = parts.pop()!;
+	let out = "";
+	for (const modifier in MODIFIER_SYMBOLS) {
+		if (!parts.includes(modifier)) continue;
+		const label = keySymbol(MODIFIER_SYMBOLS[modifier]![mac ? 1 : 0]);
+		out += HAS_LETTER.test(label) ? `${label}+` : label + keySymbol("key.joiner");
+	}
+	const lower = base.toLowerCase();
+	const modifier = MODIFIER_SYMBOLS[lower];
+	const symbol = KEY_SYMBOLS[lower];
+	if (modifier) out += keySymbol(modifier[mac ? 1 : 0]);
+	else if (symbol !== undefined) out += keySymbol(symbol);
+	else if (KEY_WORDS[lower] !== undefined) out += KEY_WORDS[lower];
+	else if (base.length === 1) out += parts.length === 0 ? base : base.toUpperCase();
+	else out += base[0]!.toUpperCase() + base.slice(1);
+	return out;
+}
+
+/** Format alternative keys as a slash-separated hint (`["f5", "alt+r"]` → `F5/⌥R`). */
+export function formatKeyHints(keys: KeyName | readonly KeyName[]): string {
+	return typeof keys === "string" ? formatKeyHint(keys) : keys.map(formatKeyHint).join("/");
+}
+
+/** Format a double-tap gesture: `←←` with glyphs, `Left Left` with words. */
+export function formatDoubleTap(key: KeyName): string {
+	const label = formatKeyHint(key);
+	return `${label}${HAS_LETTER.test(label) ? " " : keySymbol("key.joiner")}${label}`;
+}

package/src/keys.ts

@@ -177,7 +177,8 @@ type SpecialKey =
 	| "f12";
 
 type BaseKey = Letter | Digit | KeySymbol | SpecialKey;
-type ModifierName = "ctrl" | "shift" | "alt" | "super";
+/** Modifier key names as they appear in {@link KeyId} chords. */
+export type ModifierName = "ctrl" | "shift" | "alt" | "super";
 
 type ModifiedKeyId<Key extends string, RemainingModifiers extends ModifierName = ModifierName> = {
 	[M in RemainingModifiers]: `${M}+${Key}` | `${M}+${ModifiedKeyId<Key, Exclude<RemainingModifiers, M>>}`;

package/src/overlays/advisor-config.ts

@@ -31,6 +31,8 @@ import {
 } from "../index";
 import { getSelectListTheme, theme } from "../theme";
 import { sanitizeDisplayWarnings } from "../render/render-utils";
+import { formatKeyHint } from "../app-keybindings";
+import { editorKey, editorKeys } from "../chrome/keybinding-hints";
 import { HookEditorComponent } from "./hook-editor";
 import { buildBrowserItems, ModelBrowser, type ModelBrowserSource, sortModelItems } from "./model-browser";
 import { bottomBorder, divider, dividerSplit, PanelRows, row, topBorder, topBorderSplit } from "../chrome/overlay-box";
@@ -514,7 +516,11 @@ export class AdvisorConfigOverlayComponent implements Component {
 				this.#cb.notify(`Advisor config: ${err instanceof Error ? err.message : String(err)}`);
 			});
 		list.onCancel = () => this.#cb.close();
-		this.#setScreen("list", list, "↑↓ move · Enter / click select · scroll preview on the right · Esc close");
+		this.#setScreen(
+			"list",
+			list,
+			`${editorKeys("tui.select.up", "tui.select.down")} move · ${editorKey("tui.select.confirm")} / click select · scroll preview on the right · ${editorKey("tui.select.cancel")} close`,
+		);
 	}
 
 	async #onListSelect(value: string): Promise<void> {
@@ -596,7 +602,11 @@ export class AdvisorConfigOverlayComponent implements Component {
 		const list = new SelectList(items, Math.max(1, items.length), getSelectListTheme());
 		list.onSelect = item => this.#onDetailSelect(index, item.value);
 		list.onCancel = () => this.#showList();
-		this.#setScreen("detail", list, `Editing "${advisor.name}" · Enter / click edit field · Esc back`);
+		this.#setScreen(
+			"detail",
+			list,
+			`Editing "${advisor.name}" · ${editorKey("tui.select.confirm")} / click edit field · ${editorKey("tui.select.cancel")} back`,
+		);
 	}
 
 	#onDetailSelect(index: number, field: string): void {
@@ -647,7 +657,11 @@ export class AdvisorConfigOverlayComponent implements Component {
 			this.#showDetail(index);
 		};
 		input.onEscape = () => this.#showDetail(index);
-		this.#setScreen("name", input, "Type a name · Enter save · Esc cancel");
+		this.#setScreen(
+			"name",
+			input,
+			`Type a name · ${editorKey("tui.input.submit")} save · ${editorKey("tui.select.cancel")} cancel`,
+		);
 	}
 
 	#showModelPicker(index: number): void {
@@ -680,7 +694,11 @@ export class AdvisorConfigOverlayComponent implements Component {
 			}
 		};
 		picker.onCancel = () => this.#showDetail(index);
-		this.#setScreen("model", picker, "Type to search · Enter / click twice picks · Esc back");
+		this.#setScreen(
+			"model",
+			picker,
+			`Type to search · ${formatKeyHint("enter")} / click twice picks · ${editorKey("tui.select.cancel")} back`,
+		);
 	}
 
 	#showThinkingPicker(index: number, selector: string, efforts: readonly string[]): void {
@@ -694,7 +712,11 @@ export class AdvisorConfigOverlayComponent implements Component {
 			this.#showDetail(index);
 		};
 		list.onCancel = () => this.#showModelPicker(index);
-		this.#setScreen("thinking", list, `Thinking effort for ${selector} · Enter / click pick · Esc back`);
+		this.#setScreen(
+			"thinking",
+			list,
+			`Thinking effort for ${selector} · ${editorKey("tui.select.confirm")} / click pick · ${editorKey("tui.select.cancel")} back`,
+		);
 	}
 
 	#showToolsEditor(index: number, selected: Set<string>, cursor: number): void {
@@ -729,7 +751,7 @@ export class AdvisorConfigOverlayComponent implements Component {
 		this.#setScreen(
 			"tools",
 			list,
-			"Enter / click toggle · select Done or Esc to apply (empty = no tools; read/grep/glob = default)",
+			`${editorKey("tui.select.confirm")} / click toggle · select Done or ${editorKey("tui.select.cancel")} to apply (empty = no tools; read/grep/glob = default)`,
 		);
 	}
 

package/src/overlays/agent-hub.ts

@@ -25,7 +25,7 @@ import {
 	type AgentActivityRow,
 	activityRowsFromProgress,
 } from "./agent-activity";
-import type { KeyId } from "../app-keybindings";
+import { formatKeyHint, formatKeyHints, type KeyId } from "../app-keybindings";
 import type { MessageRenderer } from "../chat/extension-types";
 import type { AgentLifecycleLike, IrcBusLike } from "./agent-hub-types";
 import { type AgentRecordLike, type AgentHubRegistry, type AgentStatus, MAIN_AGENT_ID } from "./agent-hub-types";
@@ -767,7 +767,7 @@ export class AgentHubOverlayComponent<TRecord extends AgentRecordLike = AgentRec
 			row(
 				theme.fg(
 					"dim",
-					"1:agents  j/k:select  Enter:transcript  Space:follow  f:filter  s:scope  /:search  Esc:close",
+					`1:agents  ${formatKeyHints(["j", "k"])}:select  ${formatKeyHint("enter")}:transcript  ${formatKeyHint("space")}:follow  ${formatKeyHint("f")}:filter  ${formatKeyHint("s")}:scope  /:search  ${formatKeyHint("escape")}:close`,
 				),
 				width,
 			),
@@ -834,15 +834,18 @@ export class AgentHubOverlayComponent<TRecord extends AgentRecordLike = AgentRec
 		if (showingNarrowDetails) {
 			return theme.fg(
 				"dim",
-				`${filter}1:agents  2:activity  Tab:roster  PgUp/PgDn:scroll  Enter:open  t:${nextView}  Esc:roster`,
+				`${filter}1:agents  2:activity  ${formatKeyHint("tab")}:roster  ${formatKeyHints(["pageUp", "pageDown"])}:scroll  ${formatKeyHint("enter")}:open  ${formatKeyHint("t")}:${nextView}  ${formatKeyHint("escape")}:roster`,
 			);
 		}
 		if (availableWidth < 96) {
-			return theme.fg("dim", `${filter}j/k:select  Enter:open  t:${nextView}  Tab:details  r/x:manage  Esc:close`);
+			return theme.fg(
+				"dim",
+				`${filter}${formatKeyHints(["j", "k"])}:select  ${formatKeyHint("enter")}:open  ${formatKeyHint("t")}:${nextView}  ${formatKeyHint("tab")}:details  ${formatKeyHints(["r", "x"])}:manage  ${formatKeyHint("escape")}:close`,
+			);
 		}
 		return theme.fg(
 			"dim",
-			`${filter}1:agents  2:activity  j/k/wheel:select  PgUp/PgDn:details  Enter/click:open  t:${nextView}  r:revive  x:kill  Esc:close`,
+			`${filter}1:agents  2:activity  ${formatKeyHints(["j", "k"])}/wheel:select  ${formatKeyHints(["pageUp", "pageDown"])}:details  ${formatKeyHint("enter")}/click:open  ${formatKeyHint("t")}:${nextView}  ${formatKeyHint("r")}:revive  ${formatKeyHint("x")}:kill  ${formatKeyHint("escape")}:close`,
 		);
 	}
 

package/src/overlays/agent-transcript-viewer.ts

@@ -20,7 +20,8 @@ import { Editor } from "../components/editor";
 import { matchesKey } from "../keys";
 import { routeSgrMouseInput } from "../mouse";
 import { formatDuration, formatNumber, logger } from "@oh-my-pi/pi-utils";
-import type { KeyId } from "../app-keybindings";
+import { formatKeyHint, formatKeyHints, type KeyId } from "../app-keybindings";
+import { editorKey } from "../chrome/keybinding-hints";
 import type { MessageRenderer } from "../chat/extension-types";
 import type { AgentLifecycleLike } from "./agent-hub-types";
 import type { AgentHubRegistry, AgentStatus } from "./agent-hub-types";
@@ -627,9 +628,10 @@ export class AgentTranscriptViewer implements Component {
 		const lines: string[] = [];
 		const statsLine = this.#statsLine();
 		if (statsLine) lines.push(statsLine);
-		const hint = this.#editor
-			? `Enter:send  Esc:close  ${this.#deps.expandKeys[0] ?? "ctrl+o"}:expand  empty input → j/k:scroll  g/G:top/bottom`
-			: `Esc:close  ${this.#deps.expandKeys[0] ?? "ctrl+o"}:expand  j/k:scroll  g/G:top/bottom`;
+		const keys =
+			`${formatKeyHint("escape")}:close  ${formatKeyHint(this.#deps.expandKeys[0] ?? "ctrl+o")}:expand  ` +
+			`${this.#editor ? "empty input → " : ""}${formatKeyHints(["j", "k"])}:scroll  ${formatKeyHints(["g", "shift+g"])}:top/bottom`;
+		const hint = this.#editor ? `${editorKey("tui.input.submit")}:send  ${keys}` : keys;
 		lines.push(theme.fg("dim", hint));
 		return lines;
 	}

package/src/overlays/agents-hub.ts

@@ -29,6 +29,8 @@ import type { AgentSource } from "../tools/task";
 import { shortenPath } from "../render/render-utils";
 import { getEditorTheme, theme } from "../theme";
 import { matchesAppFollowUp, matchesSelectCancel, matchesSelectDown, matchesSelectUp } from "../keybinding-matchers";
+import { formatKeyHint, formatKeyHints } from "../app-keybindings";
+import { boundKeys, editorKey, editorKeys } from "../chrome/keybinding-hints";
 import {
 	buildBrowserItems,
 	ModelBrowser,
@@ -980,7 +982,10 @@ export class AgentsHubComponent implements Component {
 			const { agent, property } = this.#assigning;
 			const what = property === "model" ? "model override" : `${property} model`;
 			return truncateToWidth(
-				theme.fg("accent", ` Picking ${what} for ${theme.bold(agent.name)} — Enter assigns, Esc cancels`),
+				theme.fg(
+					"accent",
+					` Picking ${what} for ${theme.bold(agent.name)} — ${formatKeyHint("enter")} assigns, ${editorKey("tui.select.cancel")} cancels`,
+				),
 				width,
 			);
 		}
@@ -1152,26 +1157,35 @@ export class AgentsHubComponent implements Component {
 	}
 
 	#footerHint(): string {
+		const enter = formatKeyHint("enter");
+		const cancel = editorKey("tui.select.cancel");
+		const upDown = editorKeys("tui.select.up", "tui.select.down");
 		if (this.#strip) {
 			if (this.#strip.kind === "pattern") {
 				const property = this.#strip.property;
 				const values = property === "model" ? "a model pattern" : '"on", "off", or a model pattern';
-				return `Enter ${values} (role aliases like @smol and :level suffixes work; empty clears) · Esc back`;
+				return `Enter ${values} (role aliases like @smol and :level suffixes work; empty clears) · ${cancel} back`;
 			}
-			return this.#strip.property ? "←/→ choose · Enter apply · Esc back" : "←/→ choose · Enter open · Esc cancel";
+			const choose = formatKeyHints(["left", "right"]);
+			return this.#strip.property
+				? `${choose} choose · ${enter} apply · ${cancel} back`
+				: `${choose} choose · ${enter} open · ${cancel} cancel`;
 		}
 		if (this.#assigning) {
-			return "Enter pick · ↑/↓ models · type to search · Esc cancel";
+			return `${enter} pick · ${upDown} models · type to search · ${cancel} cancel`;
 		}
 		if (this.#createActive) {
-			if (this.#createSpec) return "Enter save · Tab scope · r regenerate · Esc cancel";
+			const tab = formatKeyHint("tab");
+			if (this.#createSpec)
+				return `${enter} save · ${tab} scope · ${formatKeyHint("r")} regenerate · ${cancel} cancel`;
 			if (this.#createGenerating) return "Generating…";
-			return "Ctrl+Q/Ctrl+Enter generate · Enter newline · Tab scope · Esc cancel";
+			const generate = formatKeyHints(boundKeys("app.message.followUp", ["ctrl+q", "ctrl+enter"]));
+			return `${generate} generate · ${enter} newline · ${tab} scope · ${cancel} cancel`;
 		}
 		if (this.#focus === "scope") {
-			return "↑/↓ scopes · →/Enter agents · Esc close";
+			return `${upDown} scopes · ${formatKeyHints(["right", "enter"])} agents · ${cancel} close`;
 		}
-		return "Enter configure · Space enable/disable · ↑/↓ rows · type to search · Ctrl+R reload · Esc close";
+		return `${enter} configure · ${formatKeyHint("space")} enable/disable · ${upDown} rows · type to search · ${formatKeyHint("ctrl+r")} reload · ${cancel} close`;
 	}
 
 	#renderFooter(width: number): string {

package/src/overlays/annotation-overlay.ts

@@ -11,7 +11,9 @@ import {
 	visibleWidth,
 	wrapTextWithAnsi,
 } from "../index";
-import { type KeybindingsManager } from "../app-keybindings";
+import { appKey, editorKey } from "../chrome/keybinding-hints";
+import { formatKeyHint, formatKeyHints, type KeybindingsManager } from "../app-keybindings";
+import type { Keybinding } from "../keybindings";
 import { sanitizeText } from "@oh-my-pi/pi-utils";
 import { type Theme } from "../theme/theme";
 import type {
@@ -157,7 +159,6 @@ export class AnnotationOverlay implements Component {
 	#textViewportDriven = false;
 	#textRenderedRowBySource: readonly number[] = [];
 	#staticRenderedDiffBodies = new WeakMap<ReviewDiffFile, RenderedDiffBody>();
-	#externalEditorLabel: string;
 
 	readonly #tui: TUI;
 	readonly #theme: Theme;
@@ -253,7 +254,6 @@ export class AnnotationOverlay implements Component {
 		this.#editor.cursorOverride = " ";
 		this.#editor.setScrollbarVisible(true);
 		this.#editor.onSubmit = value => this.#commitAnnotation(value);
-		this.#externalEditorLabel = keybindings.getDisplayString("app.editor.external");
 		this.#resetSourceCursor();
 	}
 
@@ -328,6 +328,12 @@ export class AnnotationOverlay implements Component {
 		else this.#handleActions(data);
 	}
 
+	/** Primary key bound to `action` in this overlay's keybindings, formatted for footer hints. */
+	#key(action: Keybinding): string {
+		const [key] = this.#keybindings.getKeys(action);
+		return key ? formatKeyHint(key) : "";
+	}
+
 	#finish(result: CodeReviewOverlayResult | TextReviewOverlayResult | undefined): void {
 		if (this.#finished) return;
 		this.#finished = true;
@@ -962,14 +968,11 @@ export class AnnotationOverlay implements Component {
 		const options = chooser.entries
 			.slice(start, start + optionLimit)
 			.map((index, windowIndex) => this.#renderAnnotationChooserEntry(chooser, index, start + windowIndex, width));
+		const keysHint = `${this.#key("tui.select.up")}/${this.#key("tui.select.down")} choose · ${this.#key("tui.select.confirm")} edit · ${this.#key("tui.select.cancel")} cancel`;
 		const lines =
 			availableRows === 2
-				? [this.#theme.fg("dim", "Edit annotation · ↑↓ choose · enter edit · esc cancel"), ...options.slice(0, 1)]
-				: [
-						this.#theme.fg("dim", "Edit annotation · ↑↓ choose · enter edit · esc cancel"),
-						...options,
-						this.#theme.fg("dim", "↑↓ choose · enter edit · esc cancel"),
-					];
+				? [this.#theme.fg("dim", `Edit annotation · ${keysHint}`), ...options.slice(0, 1)]
+				: [this.#theme.fg("dim", `Edit annotation · ${keysHint}`), ...options, this.#theme.fg("dim", keysHint)];
 		return Number.isFinite(availableRows) ? lines.slice(0, availableRows) : lines;
 	}
 
@@ -1034,20 +1037,31 @@ export class AnnotationOverlay implements Component {
 				width,
 				Ellipsis.Unicode,
 			);
-			const hints = ["enter save", "shift+enter newline", "esc cancel"];
-			if (this.#externalEditorLabel) hints.push(`${this.#externalEditorLabel} editor`);
+			const hints = [
+				`${editorKey("tui.input.submit")} save`,
+				`${editorKey("tui.input.newLine")} newline`,
+				`${this.#key("tui.select.cancel")} cancel`,
+			];
+			const externalEditorKey = appKey(this.#keybindings, "app.editor.external");
+			if (externalEditorKey) hints.push(`${externalEditorKey} editor`);
 			this.#editor.focused = true;
 			return [caption, ...this.#editor.render(width), this.#theme.fg("dim", hints.join(" · "))];
 		}
+		const upDown = `${this.#key("tui.select.up")}/${this.#key("tui.select.down")}`;
+		const confirm = this.#key("tui.select.confirm");
+		const editNote = `${formatKeyHint("e")} edit note`;
 		const focusHelp =
 			this.#focus === "files"
-				? "↑↓ file · ⏎ diff · a/A file note · e edit note"
+				? `${upDown} file · ${confirm} diff · ${formatKeyHints(["a", "shift+a"])} file note · ${editNote}`
 				: this.#focus === "diff"
-					? this.#textSource
-						? "↑↓ line · ⇧ faster · pgup/pgdn · g/G ends · a line note · A text note · e edit note"
-						: "↑↓ line · ⇧ faster · pgup/pgdn · g/G ends · a line note · A file note · e edit note"
-					: "↑↓ select · ⏎ confirm";
-		return [this.#theme.fg("dim", `${focusHelp} · u undo · tab regions · esc cancel`)];
+					? `${upDown} line · ${formatKeyHint("shift")} faster · ${this.#key("tui.select.pageUp")}/${this.#key("tui.select.pageDown")} · ${formatKeyHints(["g", "shift+g"])} ends · ${formatKeyHint("a")} line note · ${formatKeyHint("shift+a")} ${this.#textSource ? "text" : "file"} note · ${editNote}`
+					: `${upDown} select · ${confirm} confirm`;
+		return [
+			this.#theme.fg(
+				"dim",
+				`${focusHelp} · ${formatKeyHint("u")} undo · ${formatKeyHint("tab")} regions · ${this.#key("tui.select.cancel")} cancel`,
+			),
+		];
 	}
 
 	#ensureCursorVisible(renderedRowBySource: readonly number[]): void {

package/src/overlays/ask-dialog.ts

@@ -71,7 +71,8 @@ import {
 } from "../keybinding-matchers";
 import { optionMarker } from "../tools/ask";
 import { CountdownTimer } from "../chrome/countdown-timer";
-import { editorKey } from "../chrome/keybinding-hints";
+import { editorKey, editorKeys } from "../chrome/keybinding-hints";
+import { formatKeyHint, formatKeyHints } from "../app-keybindings";
 import { OverlayPanel, PanelDivider, PanelRows } from "../chrome/overlay-box";
 import { handleTabSwitchKey } from "../chrome/selector-helpers";
 
@@ -309,17 +310,6 @@ function renderCachedPreview(cache: PreviewRenderCache, preview: string, width:
 	return rendered;
 }
 
-function pageKeysLabel(): string {
-	const pageUp = editorKey("tui.select.pageUp");
-	const pageDown = editorKey("tui.select.pageDown");
-	return `${pageUp === "pageup" ? "PgUp" : pageUp}/${pageDown === "pagedown" ? "PgDn" : pageDown}`;
-}
-
-function cancelKeyLabel(): string {
-	const [key = ""] = editorKey("tui.select.cancel").split("/");
-	return key === "escape" ? "Esc" : key;
-}
-
 function normalizedInlineInput(input: string): string {
 	return replaceTabs(input).replace(/\s+/g, " ").trim();
 }
@@ -767,24 +757,29 @@ export class AskDialogComponent implements Component {
 	}
 
 	#footerHintText(indicator: string): string {
-		const cancel = `${cancelKeyLabel()} cancel`;
+		const cancel = `${editorKey("tui.select.cancel")} cancel`;
+		const enter = formatKeyHint("enter");
+		const upDown = editorKeys("tui.select.up", "tui.select.down");
 		const inputGuard = this.options.inputGuard;
 		if (inputGuard?.isBlocked()) return `${inputGuard.hint}${this.#expandHint()} · ${cancel}`;
 		if (this.#isSubmitTab()) {
 			const scroll = indicator ? ` ${indicator} scroll ·` : "";
-			return `Enter submit · ↑/↓ scroll ·${scroll} ${cancel}`;
+			return `${enter} submit · ${upDown} scroll ·${scroll} ${cancel}`;
 		}
 		const question = this.#questions[this.#currentQuestionIndex()];
 		// Enter advances in multi-question dialogs and submits single-question ones.
 		const enterAction = this.#questions.length > 1 ? "next" : "submit";
-		const action = question?.multi ? `Space toggle · Enter ${enterAction}` : "Enter select · n note";
-		const tabs = this.#hasSubmitTab() ? " · Tab/←/→" : "";
+		const action = question?.multi
+			? `${formatKeyHint("space")} toggle · ${enter} ${enterAction}`
+			: `${enter} select · ${formatKeyHint("n")} note`;
+		const tabs = this.#hasSubmitTab() ? ` · ${formatKeyHints(["tab", "left", "right"])}` : "";
 		const expand = this.#expandHint();
 		if (this.#questionCanPage && indicator) {
-			return `${action} · ↑/↓${tabs} · ${cancel}${expand} · ${pageKeysLabel()} ${indicator}`;
+			const pageKeys = editorKeys("tui.select.pageUp", "tui.select.pageDown");
+			return `${action} · ${upDown}${tabs} · ${cancel}${expand} · ${pageKeys} ${indicator}`;
 		}
 		const scroll = indicator ? ` ${indicator} scroll ·` : "";
-		return `${action} · ↑/↓ move${tabs} ·${scroll} ${cancel}${expand}`;
+		return `${action} · ${upDown} move${tabs} ·${scroll} ${cancel}${expand}`;
 	}
 
 	#questionRows(question: ExtensionAskDialogQuestion): QuestionRow[] {
@@ -1051,7 +1046,7 @@ export class AskDialogComponent implements Component {
 			allLines.push(
 				theme.fg(
 					"warning",
-					`${unanswered} unanswered question${unanswered === 1 ? "" : "s"}; Enter still submits.`,
+					`${unanswered} unanswered question${unanswered === 1 ? "" : "s"}; ${formatKeyHint("enter")} still submits.`,
 				),
 			);
 			allLines.push("");

package/src/overlays/bordered-loader.ts

@@ -1,6 +1,7 @@
 import { CancellableLoader, Container, Spacer, Text, type TUI } from "../index";
 import type { Theme } from "../theme/theme";
 import { DynamicBorder } from "../chrome/dynamic-border";
+import { editorKey } from "../chrome/keybinding-hints";
 
 /** Loader wrapped with borders for hook UI */
 export class BorderedLoader extends Container {
@@ -18,7 +19,7 @@ export class BorderedLoader extends Container {
 		);
 		this.addChild(this.#loader);
 		this.addChild(new Spacer(1));
-		this.addChild(new Text(theme.fg("muted", "esc cancel"), 1, 0));
+		this.addChild(new Text(theme.fg("muted", `${editorKey("tui.select.cancel")} cancel`), 1, 0));
 		this.addChild(new Spacer(1));
 		this.addChild(new DynamicBorder(borderColor));
 	}

package/src/overlays/btw-history-panel.ts

@@ -28,7 +28,8 @@ import {
 import type { SpaceHoldHandler } from "../space-hold";
 import { sanitizeErrorLine } from "../chrome/error-block";
 import { sanitizeDisplayLine, sanitizeDisplayText } from "./extensions/display-text";
-import { editorKey, rawKeyHint } from "../chrome/keybinding-hints";
+import { editorKey, editorKeys, keyHint, rawKeyHint } from "../chrome/keybinding-hints";
+import { formatKeyHint } from "../app-keybindings";
 import { bottomBorder, row, topBorder } from "../chrome/overlay-box";
 import { padToWidth } from "../render/utils";
 import { SplitPane } from "../components/layout/split-pane";
@@ -267,11 +268,11 @@ export class BtwHistoryPanel implements Component, Focusable {
 				this.#focus = "answer";
 				this.#followLatest = true;
 			} else {
-				composer.notice = "Follow-up was not started. Your draft is kept; Enter to retry.";
+				composer.notice = `Follow-up was not started. Your draft is kept; ${editorKey("tui.input.submit")} to retry.`;
 			}
 		} catch {
 			if (this.#composer === composer) {
-				composer.notice = "Could not start the follow-up. Your draft is kept; Enter to retry.";
+				composer.notice = `Could not start the follow-up. Your draft is kept; ${editorKey("tui.input.submit")} to retry.`;
 			}
 		} finally {
 			this.#followUpPending = false;
@@ -507,15 +508,19 @@ export class BtwHistoryPanel implements Component, Focusable {
 		const composer = this.#composer;
 		const latest = record ? getBtwLatestTurn(record) : undefined;
 		const actions = composer
-			? [rawKeyHint("Enter", this.#followUpPending ? "starting…" : "send"), rawKeyHint("Esc", "cancel")]
+			? [
+					keyHint("tui.input.submit", this.#followUpPending ? "starting…" : "send"),
+					keyHint("tui.select.cancel", "cancel"),
+				]
 			: [
-					rawKeyHint("Esc", latest?.status === "running" ? "cancel" : "close"),
-					rawKeyHint("Tab/Ctrl+/", "switch pane"),
+					keyHint("tui.select.cancel", latest?.status === "running" ? "cancel" : "close"),
+					rawKeyHint(["tab", "ctrl+/"], "switch pane"),
 				];
 		if (!composer) {
-			if (record && this.#canFollowUp(record)) actions.push(rawKeyHint("f/Enter", "follow up"));
+			if (record && this.#canFollowUp(record)) actions.push(rawKeyHint(["f", "enter"], "follow up"));
 			if (record && getBtwCopyText(record) !== undefined) {
-				if (this.#isCopied(record)) actions.push(theme.fg("success", "✓ copied · c to copy again"));
+				if (this.#isCopied(record))
+					actions.push(theme.fg("success", `✓ copied · ${formatKeyHint("c")} to copy again`));
 				else actions.push(rawKeyHint("c", inner < 40 ? "copy" : "copy answer"));
 			}
 		}
@@ -577,10 +582,8 @@ export class BtwHistoryPanel implements Component, Focusable {
 			if (showNavigation) {
 				lines.push(
 					row(
-						rawKeyHint(
-							`${editorKey("tui.select.up")}/${editorKey("tui.select.down")}`,
-							this.#focus === "list" ? "select" : "scroll",
-						),
+						theme.fg("dim", editorKeys("tui.select.up", "tui.select.down")) +
+							theme.fg("muted", ` ${this.#focus === "list" ? "select" : "scroll"}`),
 						width,
 					),
 				);

package/src/overlays/btw-panel.ts

@@ -4,6 +4,8 @@ import { getMarkdownTheme, theme } from "../theme/theme";
 import { sanitizeErrorLine } from "../chrome/error-block";
 import { OverlayPanel } from "../chrome/overlay-box";
 import { StreamingPanelContent } from "../chrome/streaming-panel";
+import { interruptKey } from "../chrome/keybinding-hints";
+import { formatKeyHint } from "../app-keybindings";
 
 type BtwPanelState = "running" | "complete" | "branching" | "aborted" | "error";
 
@@ -129,15 +131,18 @@ export class BtwPanelComponent extends OverlayPanel {
 	}
 
 	#footerLine(): string {
+		// The main editor routes `app.interrupt` (Escape by default) to the panel.
+		const esc = interruptKey();
 		switch (this.#state) {
 			case "running":
-				return theme.fg("muted", "Esc to cancel");
+				return theme.fg("muted", `${esc} to cancel`);
 			case "complete": {
 				const actions: string[] = [];
-				if (this.isCopyable()) actions.push(this.#copied ? "c to copy again" : "c to copy");
-				if (this.#canFollowUp?.()) actions.push("f to follow up");
-				if (this.#canBranch?.() ?? this.isBranchable()) actions.push("b to branch");
-				actions.push("Esc to close");
+				const copyKey = formatKeyHint("c");
+				if (this.isCopyable()) actions.push(this.#copied ? `${copyKey} to copy again` : `${copyKey} to copy`);
+				if (this.#canFollowUp?.()) actions.push(`${formatKeyHint("f")} to follow up`);
+				if (this.#canBranch?.() ?? this.isBranchable()) actions.push(`${formatKeyHint("b")} to branch`);
+				actions.push(`${esc} to close`);
 				if (this.#copied) {
 					return `${theme.fg("success", "✓ Copied to clipboard")}${theme.fg("muted", actions.length > 0 ? ` · ${actions.join(" · ")}` : "")}`;
 				}
@@ -146,9 +151,9 @@ export class BtwPanelComponent extends OverlayPanel {
 			case "branching":
 				return theme.fg("muted", `${theme.status.pending} Branching to chat…`);
 			case "aborted":
-				return theme.fg("warning", `${theme.status.warning} Cancelled · Esc to close`);
+				return theme.fg("warning", `${theme.status.warning} Cancelled · ${esc} to close`);
 			case "error":
-				return theme.fg("error", `${theme.status.error} Error · Esc to close`);
+				return theme.fg("error", `${theme.status.error} Error · ${esc} to close`);
 		}
 	}