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

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-tui",
-	"version": "18.3.2",
+	"version": "18.3.4",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://omp.sh",
 	"author": {
@@ -37,17 +37,18 @@
 		"lint": "oxlint .",
 		"test": "bun test --parallel test/*.test.ts",
 		"fix": "oxlint --fix --fix-suggestions . && bun run fmt",
-		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
+		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'",
+		"gen:glyphs": "bun scripts/gen-glyphs.ts"
 	},
 	"dependencies": {
-		"@oh-my-pi/omptype": "18.3.2",
-		"@oh-my-pi/pi-agent-core": "18.3.2",
-		"@oh-my-pi/pi-ai": "18.3.2",
-		"@oh-my-pi/pi-catalog": "18.3.2",
-		"@oh-my-pi/pi-natives": "18.3.2",
-		"@oh-my-pi/pi-utils": "18.3.2",
-		"@oh-my-pi/pi-wire": "18.3.2",
-		"@oh-my-pi/snapcompact": "18.3.2"
+		"@oh-my-pi/omptype": "18.3.4",
+		"@oh-my-pi/pi-agent-core": "18.3.4",
+		"@oh-my-pi/pi-ai": "18.3.4",
+		"@oh-my-pi/pi-catalog": "18.3.4",
+		"@oh-my-pi/pi-natives": "18.3.4",
+		"@oh-my-pi/pi-utils": "18.3.4",
+		"@oh-my-pi/pi-wire": "18.3.4",
+		"@oh-my-pi/snapcompact": "18.3.4"
 	},
 	"devDependencies": {
 		"kitty-vt-wasm": "^0.2.0"

package/src/app-keybindings.ts

@@ -1,14 +1,14 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import {
-	getActiveProfile,
-	getAgentDir,
-	getProfileRootDir,
-	isEnoent,
-	logger,
-	stringifyYamlConfig,
-} from "@oh-my-pi/pi-utils";
+// Subpaths, not the `@oh-my-pi/pi-utils` barrel: the barrel loads the native
+// addon (file-lock), and key-hint formatting runs on addon-free CLI paths
+// (`omp --version`, help) through cli/command-help.ts.
+import { getActiveProfile, getAgentDir, getProfileRootDir } from "@oh-my-pi/pi-utils/dirs";
+import { isEnoent } from "@oh-my-pi/pi-utils/fs-error";
+import * as logger from "@oh-my-pi/pi-utils/logger";
+import { stringifyYamlConfig } from "@oh-my-pi/pi-utils/yaml-config";
 import { JSONC, YAML } from "bun";
+import { formatKeyHints } from "./key-hint-format";
 import {
 	type Keybinding,
 	type KeybindingDefinitions,
@@ -645,12 +645,9 @@ export class KeybindingsManager extends TuiKeybindingsManager {
 		return this.getResolvedBindings();
 	}
 
-	/**
-	 * Get display string for a keybinding (e.g., "ctrl+c/escape").
-	 */
+	/** Display string for a keybinding's keys (see {@link formatKeyHints}); empty when unbound. */
 	getDisplayString(keybinding: Keybinding): string {
-		const keys = this.getKeys(keybinding);
-		return formatKeyHints(keys.length === 0 ? [] : keys);
+		return formatKeyHints(this.getKeys(keybinding));
 	}
 
 	/**
@@ -664,97 +661,7 @@ export class KeybindingsManager extends TuiKeybindingsManager {
 	}
 }
 
-/**
- * Key hint formatting utilities for UI labels.
- *
- * Modifier labels are platform-aware: macOS names the physical keys `Option`
- * (`alt`) and `Cmd` (`super`), so rendering `Alt`/`Super` there would name keys
- * absent from a Mac keyboard. Every other platform keeps `Alt`/`Super`.
- */
-
-/**
- * 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;
-}
-
-type Modifier = "ctrl" | "shift" | "alt" | "super";
-
-function isModifier(part: string): part is Modifier {
-	return part === "ctrl" || part === "shift" || part === "alt" || part === "super";
-}
-
-/**
- * Human label for a modifier, using each platform's own key names. `ctrl` and
- * `shift` are the same everywhere; `alt`/`super` become `Option`/`Cmd` on macOS.
- */
-export function modifierLabel(mod: Modifier, platform: NodeJS.Platform = keyHintPlatform()): string {
-	switch (mod) {
-		case "ctrl":
-			return "Ctrl";
-		case "shift":
-			return "Shift";
-		case "alt":
-			return platform === "darwin" ? "Option" : "Alt";
-		case "super":
-			return platform === "darwin" ? "Cmd" : "Super";
-	}
-}
-
-const KEY_LABELS: Record<string, string> = {
-	esc: "Esc",
-	escape: "Esc",
-	enter: "Enter",
-	return: "Enter",
-	space: "Space",
-	tab: "Tab",
-	backspace: "Backspace",
-	delete: "Delete",
-	home: "Home",
-	end: "End",
-	pageup: "PgUp",
-	pagedown: "PgDn",
-	up: "Up",
-	down: "Down",
-	left: "Left",
-	right: "Right",
-};
-
-function formatKeyPart(part: string, platform: NodeJS.Platform): string {
-	const lower = part.toLowerCase();
-	if (isModifier(lower)) return modifierLabel(lower, platform);
-	const label = KEY_LABELS[lower];
-	if (label) return label;
-	if (part.length === 1) return part.toUpperCase();
-	return `${part.charAt(0).toUpperCase()}${part.slice(1)}`;
-}
-
-/** Format a key chord with human-readable, platform-aware modifier labels. */
-export function formatKeyHint(key: KeyId): string {
-	const platform = keyHintPlatform();
-	return key
-		.split("+")
-		.map(part => formatKeyPart(part, platform))
-		.join("+");
-}
-
-/** Format alternative key chords as slash-separated human-readable hints. */
-export function formatKeyHints(keys: KeyId | KeyId[]): string {
-	const list = Array.isArray(keys) ? keys : [keys];
-	return list.map(formatKeyHint).join("/");
-}
+export * from "./key-hint-format";
 
 export type { Keybinding, KeybindingsConfig, KeyId };
 export { migrateKeybindingsConfigFile };

package/src/apps/autoresearch-dashboard.ts

@@ -1,3 +1,4 @@
+import { formatKeyHint, formatKeyHints } from "../app-keybindings";
 import { matchesKey } from "../keys";
 import { replaceTabs, truncateToWidth, visibleWidth } from "../utils";
 import { ScrollView } from "../components/scroll-view";
@@ -186,7 +187,10 @@ function renderExpandedHeader(runtime: AutoresearchDashboardRuntime, width: numb
 	const state = runtime.state;
 	const status = renderModeStatus(runtime, state);
 	const label = state.name ? ` autoresearch: ${replaceTabs(state.name)} ` : " autoresearch ";
-	const hint = theme.fg("dim", ` ctrl+x collapse  ctrl+shift+x overlay${status ? `  ${status}` : ""} `);
+	const hint = theme.fg(
+		"dim",
+		` ${formatKeyHint("ctrl+x")} collapse  ${formatKeyHint("ctrl+shift+x")} overlay${status ? `  ${status}` : ""} `,
+	);
 	const fillWidth = Math.max(0, width - visibleWidth(label) - visibleWidth(hint));
 	return truncateToWidth(theme.fg("accent", label) + theme.fg("borderMuted", "-".repeat(fillWidth)) + hint, width);
 }
@@ -256,7 +260,7 @@ function renderCollapsedLine(runtime: AutoresearchDashboardRuntime, state: Exper
 	} else if (!runtime.autoresearchMode) {
 		parts.push(theme.fg("dim", ` | ${renderModeStatus(runtime, state)}`));
 	}
-	parts.push(theme.fg("dim", " | ctrl+x expand"));
+	parts.push(theme.fg("dim", ` | ${formatKeyHint("ctrl+x")} expand`));
 	return parts.join("");
 }
 
@@ -471,7 +475,10 @@ function renderOverlayRunningLine(
 }
 
 function renderOverlayFooter(width: number, theme: Theme): string {
-	const hint = theme.fg("dim", " up/down j/k pageup pagedown g G esc ");
+	const hint = theme.fg(
+		"dim",
+		` ${formatKeyHints(["up", "down"])} ${formatKeyHints(["j", "k"])} ${formatKeyHint("pageUp")} ${formatKeyHint("pageDown")} ${formatKeyHint("g")} ${formatKeyHint("shift+g")} ${formatKeyHint("escape")} `,
+	);
 	const fill = Math.max(0, width - visibleWidth(hint));
 	return theme.fg("borderMuted", "-".repeat(fill)) + hint;
 }

package/src/apps/debug/log-viewer.ts

@@ -1,3 +1,4 @@
+import { formatKeyHint, formatKeyHints } from "../../app-keybindings";
 import type { Component } from "../../tui";
 import { extractPrintableText, matchesKey } from "../../keys";
 import { routeSgrMouseInput, type SgrMouseEvent } from "../../mouse";
@@ -715,7 +716,7 @@ export class DebugLogViewerComponent implements Component {
 	}
 
 	#controlsText(): string {
-		return "Esc close · Ctrl+C copy · ↑/↓/wheel move · click toggle · Shift+↑/↓ select · ←/→ collapse/expand · Ctrl+A all · Ctrl+O older · Ctrl+P pid";
+		return `${formatKeyHint("escape")} close · ${formatKeyHint("ctrl+c")} copy · ${formatKeyHints(["up", "down"])}/wheel move · click toggle · ${formatKeyHints(["shift+up", "shift+down"])} select · ${formatKeyHints(["left", "right"])} collapse/expand · ${formatKeyHint("ctrl+a")} all · ${formatKeyHint("ctrl+o")} older · ${formatKeyHint("ctrl+p")} pid`;
 	}
 
 	#filterText(): string {
@@ -731,7 +732,7 @@ export class DebugLogViewerComponent implements Component {
 	#statusText(): string {
 		return this.#statusMessage
 			? theme.fg("success", this.#statusMessage)
-			: theme.fg("dim", "Enter loads older when highlighted; printable keys update filter");
+			: theme.fg("dim", `${formatKeyHint("enter")} loads older when highlighted; printable keys update filter`);
 	}
 
 	async #handleLoadOlder(additionalCount: number = LOAD_OLDER_CHUNK): Promise<void> {

package/src/apps/debug/raw-sse.ts

@@ -1,3 +1,4 @@
+import { formatKeyHint } from "../../app-keybindings";
 import type { Component } from "../../tui";
 import { matchesKey } from "../../keys";
 import { routeSgrMouseInput, type SgrMouseEvent } from "../../mouse";
@@ -252,7 +253,7 @@ export class RawSseViewerComponent implements Component {
 	}
 
 	#statusText(): string {
-		const help = "Esc close · Ctrl+C copy raw · End follow tail · wheel scroll · click summary toggles follow";
+		const help = `${formatKeyHint("escape")} close · ${formatKeyHint("ctrl+c")} copy raw · ${formatKeyHint("end")} follow tail · wheel scroll · click summary toggles follow`;
 		return this.#statusMessage
 			? `${theme.fg("success", this.#statusMessage)}  ${theme.fg("dim", help)}`
 			: theme.fg("dim", help);

package/src/apps/git/git-tui.ts

@@ -24,6 +24,7 @@
  * every file underneath it.
  */
 
+import { formatKeyHint, formatKeyHints } from "../../app-keybindings";
 import { SplitPane } from "../../components/layout/split-pane";
 import { Stack } from "../../components/layout/stack";
 import { matchesKey } from "../../keys";
@@ -340,7 +341,10 @@ class GitTuiComponent implements Component {
 			if (this.#pendingDiscard !== key) {
 				this.#pendingDiscard = key;
 				this.#setStatus(
-					theme.fg("warning", `Discard changes to ${action.selection.label}? Press delete again to confirm`),
+					theme.fg(
+						"warning",
+						`Discard changes to ${action.selection.label}? Press ${formatKeyHint("delete")} again to confirm`,
+					),
 				);
 				return;
 			}
@@ -451,7 +455,7 @@ class GitTuiComponent implements Component {
 		if (!hunk.patch) return;
 		if (action === "discard" && this.#pendingDiscard !== hunk.patch) {
 			this.#pendingDiscard = hunk.patch;
-			this.#setStatus(theme.fg("warning", "Discard hunk? Press x (or click) again to confirm"));
+			this.#setStatus(theme.fg("warning", `Discard hunk? Press ${formatKeyHint("x")} (or click) again to confirm`));
 			return;
 		}
 		this.#pendingDiscard = null;
@@ -487,7 +491,7 @@ class GitTuiComponent implements Component {
 		}
 		if (action === "discard" && this.#pendingDiscard !== patch) {
 			this.#pendingDiscard = patch;
-			this.#setStatus(theme.fg("warning", "Discard selected lines? Press x again to confirm"));
+			this.#setStatus(theme.fg("warning", `Discard selected lines? Press ${formatKeyHint("x")} again to confirm`));
 			return;
 		}
 		this.#pendingDiscard = null;
@@ -768,8 +772,8 @@ class GitTuiComponent implements Component {
 			theme.fg(
 				"dim",
 				this.#focus === "diff"
-					? "alt+↓/↑ hunk · ]/[ file · shift+↑/↓ select · s/u stage · x/del discard · v view · c commit · q quit"
-					: "↑/↓ move · ←/→ fold · space stage · del discard · enter open · alt+↓/↑ hunk · c commit · t tree · q quit",
+					? `${formatKeyHints(["alt+down", "alt+up"])} hunk · ${formatKeyHints(["]", "["])} file · ${formatKeyHints(["shift+up", "shift+down"])} select · ${formatKeyHints(["s", "u"])} stage · ${formatKeyHints(["x", "delete"])} discard · ${formatKeyHint("v")} view · ${formatKeyHint("c")} commit · ${formatKeyHint("q")} quit`
+					: `${formatKeyHints(["up", "down"])} move · ${formatKeyHints(["left", "right"])} fold · ${formatKeyHint("space")} stage · ${formatKeyHint("delete")} discard · ${formatKeyHint("enter")} open · ${formatKeyHints(["alt+down", "alt+up"])} hunk · ${formatKeyHint("c")} commit · ${formatKeyHint("t")} tree · ${formatKeyHint("q")} quit`,
 			);
 		const free = width - row.width - right.width - 1;
 		const middleText = free > visibleWidth(middle) + 4 ? middle : truncateToWidth(middle, Math.max(0, free - 4));

package/src/apps/live-visualizer.ts

@@ -1,3 +1,4 @@
+import { formatKeyHint } from "../app-keybindings";
 import type { Component } from "../tui";
 import { OverlayPanel, PanelRows } from "../chrome/overlay-box";
 import { type KeyId, matchesKey } from "../keys";
@@ -197,7 +198,7 @@ export class LiveVisualizer implements Component {
 		const frames = theme.spinnerFrames;
 		const icon = this.#phase === "working" ? frames[this.#frame % frames.length] : PHASE_ICONS[this.#phase];
 		const status = `${icon} ${this.#phase}`;
-		const fullLabel = ` ${status} · space mute · esc end `;
+		const fullLabel = ` ${status} · ${formatKeyHint("space")} mute · ${formatKeyHint("escape")} end `;
 		const shortLabel = ` ${status} `;
 		const label =
 			innerWidth >= visibleWidth(fullLabel) + 1

package/src/apps/ps-top.ts

@@ -6,6 +6,7 @@
  * `x` kill, `r` restart, `a` toggle all scopes, `q`/`esc`/`ctrl+c` quit.
  * Sub-views (info, logs): `esc`/`q` back.
  */
+import { formatKeyHint, formatKeyHints } from "../app-keybindings";
 import { KeyValueList, type KeyValueRow } from "../components/key-value-list";
 import { ScrollView } from "../components/scroll-view";
 import { renderTableRow, type TableColumn } from "../components/table";
@@ -281,11 +282,16 @@ export class PsTopComponent implements Component {
 	}
 
 	#renderTable(width: number, height: number): string[] {
-		const scopesLabel = `${this.#flat.length} process${this.#flat.length === 1 ? "" : "es"} in ${this.#reports.length} scope${this.#reports.length === 1 ? "" : "s"} ${chalk.dim(this.#all ? "(all)" : "(current)")}`;
+		const scopeKind = this.#all
+			? "(all)"
+			: this.#target.dir !== undefined || this.#target.global !== undefined
+				? "(target)"
+				: "(current + global)";
+		const scopesLabel = `${this.#flat.length} process${this.#flat.length === 1 ? "" : "es"} in ${this.#reports.length} scope${this.#reports.length === 1 ? "" : "s"} ${chalk.dim(scopeKind)}`;
 		const header = this.#header(width, scopesLabel);
 		const footer = this.#footer(
 			width,
-			"↑/↓ select · enter info · l logs · s stop · x kill · r restart · a all scopes · q quit",
+			`${formatKeyHints(["up", "down"])} select · ${formatKeyHint("enter")} info · ${formatKeyHint("l")} logs · ${formatKeyHint("s")} stop · ${formatKeyHint("x")} kill · ${formatKeyHint("r")} restart · ${formatKeyHint("a")} all scopes · ${formatKeyHint("q")} quit`,
 		);
 		const bodyHeight = height - 1 - footer.length;
 
@@ -350,7 +356,7 @@ export class PsTopComponent implements Component {
 	#renderInfo(width: number, height: number): string[] {
 		const info = this.#info;
 		const header = this.#header(width, "process info");
-		const footer = this.#footer(width, "esc back · q back");
+		const footer = this.#footer(width, `${formatKeyHint("escape")} back · ${formatKeyHint("q")} back`);
 		const body = [""];
 		if (info) {
 			const daemon = info.daemon;
@@ -383,7 +389,10 @@ export class PsTopComponent implements Component {
 			width,
 			`logs ${chalk.bold(name)}${this.#logsState ? chalk.dim(` · ${this.#logsState}`) : ""}`,
 		);
-		const footer = this.#footer(width, "esc back · q back · view refreshes live");
+		const footer = this.#footer(
+			width,
+			`${formatKeyHint("escape")} back · ${formatKeyHint("q")} back · view refreshes live`,
+		);
 		const bodyHeight = height - 1 - footer.length;
 		this.#logsView.setLines(this.#logsLines.map(line => ` ${line}`));
 		this.#logsView.setHeight(bodyHeight);

package/src/autocomplete.ts

@@ -6,6 +6,14 @@ import { getProjectDir } from "@oh-my-pi/pi-utils";
 
 const PATH_DELIMITERS = new Set([" ", "\t", '"', "'", "="]);
 
+/**
+ * How long an `@` fuzzy search may run before the immediate-directory prefix
+ * listing is reported through `onPartial`. Fuzzy walks of normal repos finish
+ * well under this, so they never flash an interim list; huge roots (a volume
+ * of sibling projects) take seconds and would otherwise show nothing new.
+ */
+const AT_PARTIAL_DELAY_MS = 150;
+
 function buildAutocompleteFuzzyDiscoveryProfile(
 	query: string,
 	basePath: string,
@@ -149,6 +157,17 @@ export function subsequenceMatch(query: string, target: string): boolean {
 	return qi === query.length;
 }
 
+/**
+ * Whether an `@` file completion `value` still fits the live `@` token.
+ * The editor narrows a stale `@` list with this while a fresh search runs;
+ * mirrors the subsequence filter `getSuggestions` applies to fuzzy results.
+ */
+export function atCompletionMatches(token: string, value: string): boolean {
+	const query = parsePathPrefix(token).rawPrefix.replaceAll("\\", "/").toLowerCase();
+	const target = parsePathPrefix(value).rawPrefix.replace(/"$/, "").toLowerCase();
+	return subsequenceMatch(query, target);
+}
+
 /** Ranked-tier subsequence score (100/80/60/40−gaps·5); higher is better, 0 is no match. */
 export function subsequenceScore(query: string, target: string): number {
 	if (query.length === 0) return 1;
@@ -205,12 +224,16 @@ export interface SlashCommand {
 }
 
 export interface AutocompleteProvider {
-	/** Get autocomplete suggestions for current text/cursor position. Expensive providers SHOULD stop when `signal` aborts. */
+	/**
+	 * Get autocomplete suggestions for current text/cursor position. Expensive providers SHOULD stop when `signal` aborts.
+	 * Slow providers MAY report interim suggestions through `onPartial` before resolving; the resolved value supersedes them.
+	 */
 	getSuggestions(
 		lines: string[],
 		cursorLine: number,
 		cursorCol: number,
 		signal?: AbortSignal,
+		onPartial?: (suggestions: { items: AutocompleteItem[]; prefix: string }) => void,
 	): Promise<{
 		items: AutocompleteItem[];
 		prefix: string; // What we're matching against (e.g., "/" or "src/")
@@ -558,6 +581,7 @@ export class CombinedAutocompleteProvider implements AutocompleteProvider {
 		cursorLine: number,
 		cursorCol: number,
 		signal?: AbortSignal,
+		onPartial?: (suggestions: { items: AutocompleteItem[]; prefix: string }) => void,
 	): Promise<{ items: AutocompleteItem[]; prefix: string } | null> {
 		if (signal?.aborted) return null;
 		const currentLine = lines[cursorLine] || "";
@@ -653,16 +677,27 @@ export class CombinedAutocompleteProvider implements AutocompleteProvider {
 				if (items.length === 0) return null;
 				return { items, prefix: atPrefix };
 			}
-			const suggestions =
-				rawPrefix.length > 0
-					? await this.#getFuzzyFileSuggestions(rawPrefix, { isQuotedPrefix, signal })
-					: await this.#getFileSuggestions("@");
-			if (suggestions.length === 0 && rawPrefix.length > 0) {
+			if (rawPrefix.length === 0) {
+				const items = await this.#getFileSuggestions("@");
+				return items.length > 0 ? { items, prefix: atPrefix } : null;
+			}
+			const fuzzy = this.#getFuzzyFileSuggestions(rawPrefix, { isQuotedPrefix, signal });
+			if (onPartial) {
+				const settled = await Promise.race([
+					fuzzy.then(() => true),
+					Bun.sleep(AT_PARTIAL_DELAY_MS).then(() => false),
+				]);
+				if (!settled) {
+					const listing = await this.#getFileSuggestions(atPrefix);
+					if (listing.length > 0 && !signal?.aborted) onPartial({ items: listing, prefix: atPrefix });
+				}
+			}
+			const suggestions = await fuzzy;
+			if (suggestions.length === 0) {
 				const fallback = await this.#getFileSuggestions(atPrefix);
 				if (fallback.length === 0) return null;
 				return { items: fallback, prefix: atPrefix };
 			}
-			if (suggestions.length === 0) return null;
 
 			return {
 				items: suggestions,

package/src/chat/compaction-summary-message.ts

@@ -4,6 +4,7 @@ import { type Component } from "../tui";
 import { Markdown } from "../components/markdown";
 import { formatNumber } from "@oh-my-pi/pi-utils";
 import { getMarkdownTheme, theme } from "../theme";
+import { expandKeyHint } from "../render/render-utils";
 import type { BranchSummaryMessage, CompactionSummaryMessage, CustomMessage } from "./messages";
 
 /** Divider labels per compaction method; unknown/legacy methods fall back to "compacted". */
@@ -54,7 +55,7 @@ class DividerSummary implements Component {
 		const rule = theme.tree.horizontal;
 		const label = this.#label();
 		// sep.dot ships pre-padded (" · "); trim so the hint joins with single spaces.
-		const hint = `${theme.sep.dot.trim()} ctrl+o`;
+		const hint = `${theme.sep.dot.trim()} ${expandKeyHint()}`;
 		const plainWidth = Bun.stringWidth(`${label} ${hint}`, { countAnsiEscapeCodes: false });
 		// ` label hint ` framed by rules on both sides.
 		const remaining = width - plainWidth - 2;

package/src/chat/execution-shared.ts

@@ -15,6 +15,8 @@ import type { OutputArtifactError } from "../tools/streaming-output";
 import { formatArtifactErrorNotice, formatTruncationMetaNotice, type TruncationMeta } from "../tools/output-meta";
 import { DynamicBorder } from "../chrome/dynamic-border";
 import { Ellipsis, truncateToWidth, visibleWidth } from "../utils";
+import { interruptKey } from "../chrome/keybinding-hints";
+import { expandKeyHint } from "../render/render-utils";
 
 /** Output rows shown while an execution is collapsed. */
 export const PREVIEW_LINES = 20;
@@ -59,7 +61,7 @@ export function buildExecutionFrame(
 		ui,
 		spinner => theme.fg(colorKey, spinner),
 		text => theme.fg("muted", text),
-		`Running… (esc to cancel)`,
+		`Running… (${interruptKey()} to cancel)`,
 		getSymbolTheme().spinnerFrames,
 	);
 
@@ -84,7 +86,7 @@ export function buildStatusFooter(opts: {
 	const parts: string[] = [];
 
 	if (opts.hiddenLineCount > 0 && !opts.suppressHiddenCount) {
-		parts.push(theme.fg("dim", `… ${opts.hiddenLineCount} more lines (ctrl+o to expand)`));
+		parts.push(theme.fg("dim", `… ${opts.hiddenLineCount} more lines (${expandKeyHint()} to expand)`));
 	}
 	if (opts.status === "cancelled") {
 		parts.push(theme.fg("warning", "(cancelled)"));

package/src/chat/tool-execution.ts

@@ -937,7 +937,9 @@ export class ToolExecutionComponent extends Container {
 		const benignSkip = this.#isBenignSkip();
 		const stateBgKey =
 			this.#isPartial || benignSkip ? "toolPendingBg" : this.#result?.isError ? "toolErrorBg" : "toolSuccessBg";
-		const stateBgFn = (t: string) => theme.bg(stateBgKey, t);
+		// bgFill, not bg: rows carry nested full resets (e.g. truncateToWidth's
+		// `\x1b[0m` before its ellipsis) that would otherwise punch holes in the tint.
+		const stateBgFn = (t: string) => theme.bgFill(stateBgKey, t);
 
 		// A benign skip is a synthetic placeholder for a call that never executed,
 		// so bypass any bespoke error frame and draw the neutral generic card —

package/src/chat/ttsr-notification.ts

@@ -2,6 +2,7 @@ import { Text } from "../components/text";
 import { type Component, Container } from "../tui";
 import { MessageNoticeComponent, type MessageNoticePresentation } from "../chrome/message-notice";
 import { theme } from "../theme";
+import { expandKeyHint } from "../render/render-utils";
 
 /** Rule fields shown in rewind notifications. */
 export interface NotificationRule {
@@ -83,7 +84,7 @@ export class TtsrNotificationComponent extends Container {
 
 		const body: Component[] = [new Text(theme.italic(displayText), 0, 0)];
 		if (truncated) {
-			body.push(new Text(theme.italic(" (ctrl+o to expand)"), 0, 0));
+			body.push(new Text(theme.italic(` (${expandKeyHint()} to expand)`), 0, 0));
 		}
 		return { icon: theme.icon.warning, header, body };
 	}
@@ -114,9 +115,9 @@ export class TtsrNotificationComponent extends Container {
 
 		const hidden = this.#rules.length - visible.length;
 		if (hidden > 0) {
-			body.push(new Text(theme.italic(`… +${hidden} more (ctrl+o to expand)`), 0, 0));
+			body.push(new Text(theme.italic(`… +${hidden} more (${expandKeyHint()} to expand)`), 0, 0));
 		} else if (elidedDetail) {
-			body.push(new Text(theme.italic(" (ctrl+o to expand)"), 0, 0));
+			body.push(new Text(theme.italic(` (${expandKeyHint()} to expand)`), 0, 0));
 		}
 		return { icon: theme.icon.warning, header, body };
 	}

package/src/chat/user-message.ts

@@ -15,7 +15,7 @@ import {
 	skillChipStyle,
 } from "../prompt/composer-attachments";
 import { MODEL_MENTION_TAG_RE } from "../prompt/model-mention-syntax";
-import { fileHyperlink } from "../render";
+import { expandKeyHint, fileHyperlink } from "../render";
 import { imageReferenceHyperlink } from "../prompt/image-references";
 import { highlightMagicKeywords } from "../prompt/magic-keywords";
 import type { ReactionTarget } from "./reaction";
@@ -198,7 +198,7 @@ class SyntheticSummary implements Component {
 	render(width: number): readonly string[] {
 		width = Math.max(1, width);
 		if (this.#cache?.width === width) return this.#cache.lines;
-		const hint = `${theme.sep.dot.trim()} ctrl+o`;
+		const hint = `${theme.sep.dot.trim()} ${expandKeyHint()}`;
 		const lines = [` ${theme.fg("dim", truncateSummary(`${this.#summary} ${hint}`, Math.max(10, width - 1)))}`];
 		this.#cache = { width, lines };
 		return lines;

package/src/chrome/keybinding-hints.ts

@@ -1,21 +1,49 @@
 /**
  * Utilities for formatting keybinding hints in the UI.
  */
-import { getKeybindings, type Keybinding } from "../keybindings";
-import { type AppKeybinding, formatKeyHints, type KeybindingsManager } from "../app-keybindings";
+import { getKeybindings, type KeyId, type Keybinding } from "../keybindings";
+import {
+	type AppKeybinding,
+	formatKeyHint,
+	formatKeyHints,
+	type KeyName,
+	type KeybindingsManager,
+} from "../app-keybindings";
 import { theme } from "../theme/index";
+
 /**
- * Get display string for an editor action.
+ * Primary (first) key bound to an editor action, formatted for footer hints;
+ * empty when unbound. Full alternatives: `formatKeyHints(getKeybindings().getKeys(action))`.
  */
 export function editorKey(action: Keybinding): string {
-	return formatKeyHints(getKeybindings().getKeys(action));
+	const [key] = getKeybindings().getKeys(action);
+	return key ? formatKeyHint(key) : "";
+}
+
+/** Primary keys of several actions, slash-joined: `editorKeys("tui.select.up", "tui.select.down")` → `↑/↓`. */
+export function editorKeys(...actions: Keybinding[]): string {
+	return actions.map(editorKey).join("/");
 }
 
 /**
- * Get display string for an app action.
+ * Keys bound to `action`, or `fallback` when the active registry has none — a
+ * TUI-only registry carries no `app.*` bindings. Mirrors the fallbacks in
+ * `keybinding-matchers.ts`, so hints name the keys the matcher accepts.
  */
+export function boundKeys(action: Keybinding, fallback: readonly KeyId[]): readonly KeyId[] {
+	const keys = getKeybindings().getKeys(action);
+	return keys.length > 0 ? keys : fallback;
+}
+
+/** Primary interrupt key (`app.interrupt`, raw Escape when unbound, as `matchesAppInterrupt`). */
+export function interruptKey(): string {
+	return formatKeyHint(boundKeys("app.interrupt", ["escape"])[0] ?? "escape");
+}
+
+/** Primary key bound to an app action (see {@link editorKey}); all keys: `getDisplayString`. */
 export function appKey(keybindings: KeybindingsManager, action: AppKeybinding): string {
-	return formatKeyHints(keybindings.getKeys(action));
+	const [key] = keybindings.getKeys(action);
+	return key ? formatKeyHint(key) : "";
 }
 
 /**
@@ -44,12 +72,9 @@ export function appKeyHint(keybindings: KeybindingsManager, action: AppKeybindin
 }
 
 /**
- * Format a raw key string with description (for non-configurable keys like ↑↓).
- *
- * @param key - Raw key string
- * @param description - Description text
- * @returns Formatted string with dim key and muted description
+ * Format a hint for fixed (non-configurable) keys, e.g. `rawKeyHint(["up", "down"], "navigate")`.
+ * Alternatives render slash-separated (see {@link formatKeyHints}).
  */
-export function rawKeyHint(key: string, description: string): string {
-	return theme.fg("dim", key) + theme.fg("muted", ` ${description}`);
+export function rawKeyHint(keys: KeyName | readonly KeyName[], description: string): string {
+	return theme.fg("dim", formatKeyHints(keys)) + theme.fg("muted", ` ${description}`);
 }