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

package/src/prompt/word-completion.ts

@@ -0,0 +1,205 @@
+import { logger } from "@oh-my-pi/pi-utils";
+import type { EditorTextAssistProvider } from "../components/editor";
+import { maskNonProse } from "./markdown-prose";
+import { isProseWord, lineContext, ProseSource } from "./prose-gate";
+
+/** Values of the `spelling.autocomplete` setting. */
+export const WORD_COMPLETION_METHODS = ["off", "auto", "ngram", "smollm", "apple"] as const;
+
+/** Configured word-completion engine; `off` disables ghost text. */
+export type WordCompletionMethod = (typeof WORD_COMPLETION_METHODS)[number];
+
+/** Whether `value` is a {@link WordCompletionMethod}. */
+export function isWordCompletionMethod(value: unknown): value is WordCompletionMethod {
+	return WORD_COMPLETION_METHODS.some(method => method === value);
+}
+
+/** An enabled word-completion engine. */
+export type WordCompletionEngine = Exclude<WordCompletionMethod, "off">;
+
+/** Asynchronous engine behind ghost-text word completion (coding-agent: the text-prediction daemon). */
+export interface WordPredictionBackend {
+	/** Characters to paint after `prefix` typed after `before`, or `null` to show nothing. */
+	complete(before: string, prefix: string): Promise<string | null>;
+	/** Report a shown suggestion the user accepted (Tab/→) or typed past. Fire-and-forget. */
+	feedback(before: string, prefix: string, suggestion: string, accepted: boolean): void;
+}
+
+/** Resolves the backend for an engine; `undefined` means none is available (no ghost text). */
+export type WordPredictionBackendResolver = (method: WordCompletionEngine) => WordPredictionBackend | undefined;
+
+let hostResolver: WordPredictionBackendResolver | undefined;
+
+/**
+ * Install the host's backend resolver for every editor, including ones built
+ * before the host finished starting. Pass `undefined` to detach.
+ */
+export function setWordPredictionHost(resolver: WordPredictionBackendResolver | undefined): void {
+	hostResolver = resolver;
+}
+
+const WORD_SUFFIX = /[\p{L}\p{M}']+$/u;
+const WORD_CONTINUES = /^[\p{L}\p{M}']/u;
+const CACHE_LIMIT = 256;
+/** Context sent with each query: the editor text before the word, capped to a recent tail. */
+const BEFORE_LIMIT = 2_000;
+
+interface WordQuery {
+	key: string;
+	before: string;
+	prefix: string;
+}
+
+/** Editor text before the word starting at `start`, truncated to its last {@link BEFORE_LIMIT} code units. */
+function textBefore(lines: readonly string[], cursorLine: number, start: number): string {
+	let text = (lines[cursorLine] ?? "").slice(0, start);
+	for (let line = cursorLine - 1; line >= 0 && text.length < BEFORE_LIMIT; line--) {
+		text = `${lines[line] ?? ""}\n${text}`;
+	}
+	if (text.length <= BEFORE_LIMIT) return text;
+	let cut = text.length - BEFORE_LIMIT;
+	// Never start on the low half of a surrogate pair.
+	const unit = text.charCodeAt(cut);
+	if (unit >= 0xdc00 && unit <= 0xdfff) cut++;
+	return text.slice(cut);
+}
+
+/**
+ * Ghost-text word completion for the prose word ending at the cursor, served
+ * by an injected asynchronous {@link WordPredictionBackend}.
+ *
+ * Rendering is synchronous, so a cache miss schedules a single-flight backend
+ * request (one active, the newest queued) and repaints through `onUpdate` when
+ * the answer changes what is shown. The previous suggestion is projected: if
+ * its full word still extends what was typed, the remainder shows immediately
+ * and stays until the engine offers a different word.
+ */
+export class WordCompletionProvider implements EditorTextAssistProvider {
+	#method: WordCompletionMethod = "off";
+	#generation = 0;
+	#prose = new ProseSource();
+	#cache = new Map<string, string | null>();
+	#activeKey: string | undefined;
+	#queued: WordQuery | undefined;
+	/** Last non-empty suggestion shown, for projection while typing through it. */
+	#lastShown: { before: string; word: string } | undefined;
+	/** What the last `getWordCompletion` returned, so a fetch repaints only when it changes that. */
+	#displayed: { key: string; suffix: string | null } | undefined;
+
+	/** Invoked when an asynchronous answer changes the rendered ghost text. */
+	onUpdate: (() => void) | undefined;
+
+	readonly #resolveBackend: WordPredictionBackendResolver;
+
+	/** `resolveBackend` defaults to the host installed with {@link setWordPredictionHost}. */
+	constructor(resolveBackend: WordPredictionBackendResolver = method => hostResolver?.(method)) {
+		this.#resolveBackend = resolveBackend;
+	}
+
+	/** Select the engine (`off` disables completion) and drop answers from the previous one. */
+	setMethod(method: WordCompletionMethod): void {
+		if (this.#method === method) return;
+		this.#method = method;
+		this.#generation++;
+		this.#cache.clear();
+		this.#queued = undefined;
+		this.#lastShown = undefined;
+		this.#displayed = undefined;
+	}
+
+	/** Return the ghost-text suffix for the prose word ending at the cursor, or `null`. */
+	getWordCompletion(lines: string[], cursorLine: number, cursorCol: number): string | null {
+		const query = this.#query(lines, cursorLine, cursorCol);
+		const backend = query && this.#backend();
+		if (!query || !backend) {
+			this.#displayed = undefined;
+			return null;
+		}
+		if (!this.#cache.has(query.key)) this.#schedule(backend, query);
+		// Typing through a shown ghost without Tab can answer null (the word fell
+		// under the show threshold, or SmolLM excludes words typed past); keep that
+		// ghost until the engine offers something else.
+		const suffix = this.#cache.get(query.key) ?? this.#project(query);
+		this.#displayed = { key: query.key, suffix };
+		if (suffix) this.#lastShown = { before: query.before, word: query.prefix + suffix };
+		return suffix;
+	}
+
+	/** Forward accept (Tab/→) or typed-past feedback for the suggestion shown at the cursor. */
+	wordCompletionFeedback(
+		lines: string[],
+		cursorLine: number,
+		cursorCol: number,
+		suggestion: string,
+		accepted: boolean,
+	): void {
+		const query = this.#query(lines, cursorLine, cursorCol);
+		if (!query) return;
+		this.#backend()?.feedback(query.before, query.prefix, suggestion, accepted);
+		if (!accepted) this.#lastShown = undefined;
+	}
+
+	#backend(): WordPredictionBackend | undefined {
+		return this.#method === "off" ? undefined : this.#resolveBackend(this.#method);
+	}
+
+	#query(lines: readonly string[], cursorLine: number, cursorCol: number): WordQuery | undefined {
+		if (this.#method === "off") return undefined;
+		const line = lines[cursorLine] ?? "";
+		if (WORD_CONTINUES.test(line.slice(cursorCol))) return undefined;
+		// Single letters are asked too (`figure o|ut`); engines own their minimum prefix.
+		const match = WORD_SUFFIX.exec(line.slice(0, cursorCol));
+		if (!match) return undefined;
+		const start = cursorCol - match[0].length;
+		if (!isProseWord(line, maskNonProse(line), start, cursorCol)) return undefined;
+		if (!this.#prose.isProse(lineContext(lines, cursorLine), start, cursorCol)) return undefined;
+		const prefix = match[0];
+		const before = textBefore(lines, cursorLine, start);
+		// The method keeps a request still in flight for the previous engine from
+		// shadowing the same word state on the new one.
+		return { key: `${this.#method}\u0000${prefix}\u0000${before}`, before, prefix };
+	}
+
+	#project(query: WordQuery): string | null {
+		const shown = this.#lastShown;
+		if (!shown || shown.before !== query.before || shown.word.length <= query.prefix.length) return null;
+		if (!shown.word.toLocaleLowerCase().startsWith(query.prefix.toLocaleLowerCase())) return null;
+		return shown.word.slice(query.prefix.length);
+	}
+
+	#schedule(backend: WordPredictionBackend, query: WordQuery): void {
+		if (this.#activeKey === query.key || this.#queued?.key === query.key) return;
+		if (this.#activeKey !== undefined) {
+			this.#queued = query;
+			return;
+		}
+		void this.#run(backend, query);
+	}
+
+	/** Answer `query`, start the queued request, then repaint if the answer changes what is shown. */
+	async #run(backend: WordPredictionBackend, query: WordQuery): Promise<void> {
+		this.#activeKey = query.key;
+		const generation = this.#generation;
+		let suffix: string | null;
+		try {
+			suffix = (await backend.complete(query.before, query.prefix)) || null;
+		} catch (error) {
+			logger.debug("word completion request failed", { error: String(error) });
+			suffix = null;
+		}
+		if (this.#activeKey === query.key) this.#activeKey = undefined;
+		const current = generation === this.#generation;
+		if (current) {
+			if (this.#cache.size >= CACHE_LIMIT) this.#cache.clear();
+			this.#cache.set(query.key, suffix);
+		}
+		const queued = this.#queued;
+		this.#queued = undefined;
+		const next = queued && !this.#cache.has(queued.key) ? this.#backend() : undefined;
+		if (queued && next) void this.#run(next, queued);
+		const displayed = this.#displayed;
+		if (current && displayed?.key === query.key && displayed.suffix !== (suffix ?? this.#project(query))) {
+			this.onUpdate?.();
+		}
+	}
+}

package/src/render/render-utils.ts

@@ -10,7 +10,7 @@ import * as path from "node:path";
 import { ThinkingLevel } from "@oh-my-pi/pi-agent-core";
 import type { Ellipsis } from "@oh-my-pi/pi-natives";
 import { pluralize, sanitizeText } from "@oh-my-pi/pi-utils";
-import { formatKeyHints, type KeyId } from "../app-keybindings";
+import { formatKeyHint, type KeyId } from "../app-keybindings";
 import { getKeybindings } from "../keybindings";
 import type { Theme } from "../theme/theme";
 import type { Component } from "../tui";
@@ -201,10 +201,10 @@ const EXPAND_ACTION = "app.tools.expand";
 /** Fallback key when no binding is resolvable (e.g. outside an interactive session). */
 const DEFAULT_EXPAND_KEY: KeyId = "ctrl+o";
 
-/** Human-readable key currently bound to tool-output expansion, e.g. `Ctrl+O`. */
+/** Human-readable primary key bound to tool-output expansion, e.g. `Ctrl+O`. */
 export function expandKeyHint(): string {
-	const keys = getKeybindings().getKeys(EXPAND_ACTION);
-	return formatKeyHints(keys.length > 0 ? keys : [DEFAULT_EXPAND_KEY]);
+	const [key = DEFAULT_EXPAND_KEY] = getKeybindings().getKeys(EXPAND_ACTION);
+	return formatKeyHint(key);
 }
 
 // =============================================================================

package/src/setup/scenes/composer.ts

@@ -6,6 +6,7 @@ import { WizardStep } from "../../components/wizard-step";
 import type { ComposerShape } from "../../overlays/composer-shape-registry";
 import { renderComposerShapePreview } from "../../overlays/composer-shape-preview";
 import { getComposerShapeOptions } from "../../overlays/composer-shape-registry";
+import { editorKey } from "../../chrome/keybinding-hints";
 import { getSelectListTheme, theme } from "../../theme/theme";
 import type { SetupScene, SetupSceneController, SetupSceneHost } from "./types";
 
@@ -73,7 +74,10 @@ class ComposerSceneController implements SetupSceneController {
 
 	render(width: number, maxLines?: number): readonly string[] {
 		const intro = new Text(
-			theme.fg("muted", "Select a layout; live preview updates below. Press Enter to confirm."),
+			theme.fg(
+				"muted",
+				`Select a layout; live preview updates below. Press ${editorKey("tui.select.confirm")} to confirm.`,
+			),
 			0,
 			0,
 		);

package/src/setup/scenes/model.ts

@@ -4,6 +4,7 @@ import { Text } from "../../components/text";
 import { WizardStep } from "../../components/wizard-step";
 import { buildBrowserItems, ModelBrowser, resolveRoleAssignments, sortModelItems } from "../../overlays/model-browser";
 import { BROWSER_FRAME_ROWS } from "../../overlays/model-picker";
+import { formatKeyHint } from "../../app-keybindings";
 import { theme } from "../../theme/theme";
 import type { SetupScene, SetupSceneController, SetupSceneHost } from "./types";
 
@@ -58,7 +59,8 @@ class ModelSceneController implements SetupSceneController {
 
 	render(width: number, maxLines?: number): readonly string[] {
 		const intro = new Text(
-			this.#status ?? theme.fg("muted", "Type to search. Enter saves the highlighted model as your default."),
+			this.#status ??
+				theme.fg("muted", `Type to search. ${formatKeyHint("enter")} saves the highlighted model as your default.`),
 			0,
 			0,
 		);

package/src/setup/scenes/providers.ts

@@ -1,5 +1,6 @@
 import { type SgrMouseEvent } from "../../mouse";
 import { TabBar } from "../../components/tab-bar";
+import { editorKey } from "../../chrome/keybinding-hints";
 import { getTabBarTheme } from "../../chrome/shared";
 import { SignInTab } from "./sign-in";
 import type { SetupScene, SetupSceneController, SetupSceneHost, SetupTab } from "./types";
@@ -13,7 +14,9 @@ import { WebSearchTab } from "./web-search";
  */
 class ProvidersSceneController implements SetupSceneController {
 	title = "Set up your providers";
-	subtitle = "Sign in and pick a web search provider. Press Esc when you're done.";
+	get subtitle(): string {
+		return `Sign in and pick a web search provider. Press ${editorKey("tui.select.cancel")} when you're done.`;
+	}
 
 	#tabs: SetupTab[];
 	#tabBar: TabBar;

package/src/setup/scenes/sign-in.ts

@@ -6,6 +6,8 @@ import { Spacer } from "../../components/spacer";
 import { Text } from "../../components/text";
 import { WizardStep } from "../../components/wizard-step";
 import { Input } from "../../components/input";
+import { formatKeyHint } from "../../app-keybindings";
+import { editorKey } from "../../chrome/keybinding-hints";
 import { matchesKey } from "../../keys";
 import { type SgrMouseEvent } from "../../mouse";
 import { wrapTextWithAnsi } from "../../utils";
@@ -19,7 +21,7 @@ function loginUrlLink(url: string): string {
 }
 
 function loginCopyHint(): string {
-	return theme.fg("dim", "(clipboard copy attempted; Alt+C retries)");
+	return theme.fg("dim", `(clipboard copy attempted; ${formatKeyHint("alt+c")} retries)`);
 }
 
 class CopyablePromptInput implements Component, Focusable {
@@ -290,7 +292,7 @@ export class SignInTab implements SetupTab {
 				const message = error instanceof Error ? error.message : String(error);
 				this.#statusLines = [
 					theme.fg("error", `Login failed: ${message}`),
-					theme.fg("dim", "Choose another provider or press Esc to continue."),
+					theme.fg("dim", `Choose another provider or press ${editorKey("tui.select.cancel")} to continue.`),
 				];
 				this.#authUrl = undefined;
 				this.#authLaunchUrl = undefined;

package/src/setup/scenes/splash.ts

@@ -2,6 +2,7 @@ import { centerLine, visibleWidth } from "../../utils";
 import { padToWidth } from "../../render/utils";
 import { gradientEscape, gradientLogo, PI_LOGO, type ShineConfig } from "../../prompt/welcome";
 import { theme } from "../../theme/theme";
+import { formatKeyHint } from "../../app-keybindings";
 
 export const SETUP_SPLASH_MS = 2600;
 export const SETUP_TICK_MS = 33;
@@ -22,7 +23,10 @@ const RESET = "\x1b[0m";
 const MIN_SCENE_WIDTH = 56;
 const MIN_SCENE_HEIGHT = 22;
 
-const SKIP_HINT = "press enter to skip";
+/** Skip affordance; built at render time so it follows the live symbol preset. */
+function skipHint(): string {
+	return `press ${formatKeyHint("enter")} to skip`;
+}
 
 /** Density ramp for the rippling water, lightest → heaviest. */
 const WATER_RAMP = [
@@ -166,12 +170,13 @@ export function renderSetupSplash(width: number, height: number, elapsedMs: numb
 		}
 	});
 	// 4. skip hint on a cleared strip at the bottom so it stays legible over the water
-	const hintWidth = visibleWidth(SKIP_HINT);
+	const hint = skipHint();
+	const hintWidth = visibleWidth(hint);
 	const hintStart = Math.floor((w - hintWidth) / 2);
 	const hintRow = h - 1;
 	for (let x = hintStart - 1; x <= hintStart + hintWidth; x++) put(x, hintRow, " ");
 	let col = hintStart;
-	for (const ch of SKIP_HINT) put(col++, hintRow, ch === " " ? " " : theme.fg("dim", ch));
+	for (const ch of hint) put(col++, hintRow, ch === " " ? " " : theme.fg("dim", ch));
 
 	return cells.map(row => row.join(""));
 }
@@ -187,6 +192,6 @@ function renderCompactSplash(width: number, height: number, phase: number, shine
 		lines.push(width > 0 ? padToWidth(item !== undefined ? centerLine(item, width) : "", width) : "");
 	}
 	if (height > 2)
-		lines[height - 2] = width > 0 ? padToWidth(centerLine(theme.fg("dim", SKIP_HINT), width), width) : "";
+		lines[height - 2] = width > 0 ? padToWidth(centerLine(theme.fg("dim", skipHint()), width), width) : "";
 	return lines;
 }

package/src/setup/scenes/theme.ts

@@ -5,6 +5,7 @@ import { type SelectItem, SelectList } from "../../components/select-list";
 import { Text } from "../../components/text";
 import { WizardStep } from "../../components/wizard-step";
 import { Container } from "../../tui";
+import { editorKey } from "../../chrome/keybinding-hints";
 import {
 	enableAutoTheme,
 	getAvailableThemes,
@@ -59,7 +60,10 @@ function renderMockEditor(width: number): string[] {
 	const top = theme.fg("borderAccent", `${box.topLeft}${horizontal}${box.topRight}`);
 	const bottom = theme.fg("borderMuted", `${box.bottomLeft}${horizontal}${box.bottomRight}`);
 	const prompt = `${theme.fg("accent", ">")} ${theme.fg("text", "Ask anything, edit files, run tools")}${theme.inverse(" ")}`;
-	const hint = theme.fg("dim", "enter send · shift+enter newline · / commands");
+	const hint = theme.fg(
+		"dim",
+		`${editorKey("tui.input.submit")} send · ${editorKey("tui.input.newLine")} newline · / commands`,
+	);
 	return [
 		top,
 		`${theme.fg("borderAccent", box.vertical)}${innerWidth > 0 ? padToWidth(prompt, innerWidth) : ""}${theme.fg("borderAccent", box.vertical)}`,
@@ -83,7 +87,9 @@ function renderThemePreview(width: number): string[] {
 
 class ThemeSceneController implements SetupSceneController {
 	title = "Pick a theme";
-	subtitle = "Move through the list to preview; Enter saves the highlighted choice.";
+	get subtitle(): string {
+		return `Move through the list to preview; ${editorKey("tui.select.confirm")} saves the highlighted choice.`;
+	}
 	#mode: ThemeMode = "curated";
 	#selectList: SelectList;
 	#loadingAllThemes = false;
@@ -135,13 +141,20 @@ class ThemeSceneController implements SetupSceneController {
 	render(width: number, maxLines?: number): readonly string[] {
 		const intro = new Container();
 		intro.addChild(
-			new Text(theme.fg("muted", "Theme changes preview live. Nothing is saved until you press Enter."), 0, 0),
+			new Text(
+				theme.fg(
+					"muted",
+					`Theme changes preview live. Nothing is saved until you press ${editorKey("tui.select.confirm")}.`,
+				),
+				0,
+				0,
+			),
 		);
 		intro.addChild(
 			new Text(
 				this.#mode === "all"
-					? theme.fg("dim", "Browsing all themes · Esc returns to curated choices")
-					: theme.fg("dim", "Esc skips this step"),
+					? theme.fg("dim", `Browsing all themes · ${editorKey("tui.select.cancel")} returns to curated choices`)
+					: theme.fg("dim", `${editorKey("tui.select.cancel")} skips this step`),
 				0,
 				0,
 			),

package/src/setup/wizard-overlay.ts

@@ -1,4 +1,6 @@
 import { type Component, type OverlayFocusOwner } from "../tui";
+import { formatKeyHint } from "../app-keybindings";
+import { editorKey, editorKeys } from "../chrome/keybinding-hints";
 import { matchesKey } from "../keys";
 import { centerLine, padding } from "../utils";
 import { padToWidth } from "../render/utils";
@@ -200,10 +202,9 @@ export class SetupWizardComponent implements Component, OverlayFocusOwner {
 		header.push("");
 		this.#bodyRowStart = header.length;
 
-		const footer = [
-			"",
-			centerLine(theme.fg("dim", "↑/↓ select · enter confirm · esc skip · ctrl+c exit setup"), width),
-		];
+		const navKeys = editorKeys("tui.select.up", "tui.select.down");
+		const footerHint = `${navKeys} select · ${editorKey("tui.select.confirm")} confirm · ${editorKey("tui.select.cancel")} skip · ${formatKeyHint("ctrl+c")} exit setup`;
+		const footer = ["", centerLine(theme.fg("dim", footerHint), width)];
 		const maxBodyLines = Math.max(0, height - header.length - footer.length);
 		const body = this.#activeScene?.render(contentWidth, maxBodyLines).slice(0, maxBodyLines) ?? [];
 		const lines = [...header, ...body.map(line => indentLine(line, width, SCENE_MARGIN_X))];

package/src/theme/active-symbols.ts

@@ -0,0 +1,20 @@
+/**
+ * Active theme's symbol lookup without importing `./theme` (which pulls the
+ * native addon through `@oh-my-pi/pi-natives`). Key-hint formatting runs on
+ * CLI paths that must stay addon-free (`omp --version`, help), so it reads the
+ * active theme through this mirror; `./theme` publishes every assignment here.
+ */
+import { SYMBOL_PRESETS, type SymbolKey } from "./symbols";
+import type { Theme } from "./theme-class";
+
+let active: Theme | undefined;
+
+/** @internal Called by `./theme` whenever the active theme changes. */
+export function setActiveSymbolTheme(value: Theme | undefined): void {
+	active = value;
+}
+
+/** Symbol from the active theme, or the ascii preset before any theme loads. */
+export function activeThemeSymbol(key: SymbolKey): string {
+	return active ? active.symbol(key) : SYMBOL_PRESETS.ascii[key];
+}

package/src/theme/glyph-bundle.json

@@ -1,5 +1,5 @@
 {
-	"$comment": "Glyph Protocol `glyf` payloads for every private-use icon the TUI emits, extracted from JetBrainsMono NFM Regular (Version 2.304; Nerd Fonts 3.5.1): simple glyphs only, hinting stripped, outlines lifted by +300 so y=0 is the descender line of the aw×lh layout box. Powerline glyphs carry stretch=true. Generated offline; regenerate from the same font when icons are added.",
+	"$comment": "Generated by packages/tui/scripts/gen-glyphs.ts from JetBrainsMono NFM Regular (Version 2.304; ttfautohint (v1.8.4.7-5d5b);Nerd Fonts 3.5.1). Do not edit; run `bun run gen:glyphs`.",
 	"upm": 1000,
 	"aw": 600,
 	"lh": 1320,
@@ -595,6 +595,9 @@
 		"f0068": {
 			"glyf": "AAUAAAFoAlgDwQAJABIAHAAgADAAABMHNyciFzc0BxcFNzQHFycHNycTNAcXJwc3JzAXAzcnBzcXFhQHAQYiLwEmNDcBNjK6RigoAkhIKCgBDkgoKEhGKCiOKChIRigoRq5GPkZcQAoK/rYKGAhCCgoBTAoYA1spSEYoKAFHSPEpAUhHKChHRwFWAUdIKSlIRij+9UU9RV9BCBkJ/rQKCkEIGAoBTAo="
 		},
+		"f006e": {
+			"glyf": "AAIAAAGzAlgDdQAOABoAAAEhIg8BFxYzITI2NRE0JgMHJwcnNyc3FzcXBwIm/ogYDoiIDhgBeBQeHmAiWloiWloiWloiWAN1FsvLFh0VAV4VHf7FI1paI1paI1paI1o="
+		},
 		"f00e3": {
 			"glyf": "AAIAAAF4AlgDsAAJABkAAAEnJiIHARcBNjQBIgYVFAcGIx4BMzI2NTQmAk4qCBwI/uRYARoK/kYoOBQUFhRGJDRKNgN8LAgI/uRWARoKGv7gNigcEhAeIko0KDY="
 		},
@@ -661,6 +664,12 @@
 		"f030c": {
 			"glyf": "AAwAAAHCAlgDZgADAAcACwAPABMAFwAbAB8AIwAnACsAOwAAASM1MxUjNTMnIzUzFSM1MxUjNTMlIzUzFSM1OwIVIzUzFSMXMxUjNTMVIyUhIgYVERQWMyEyNjURNCYB/jw8PDxaPDw8PPDw/vI8PDw8Hjw8PDxaPDw8PAEO/iAYJCQYAeAYJCQC0DyWPB48ljy0PJY8ljw8ljwePJY8liQY/tQYJCQYASwYJA=="
 		},
+		"f0311": {
+			"glyf": "AAEAAAHWAlgDUgAKAAABFSE3JwcXNychNQIY/mByLL6+LHIB4AMyfnAuvr4ucL4="
+		},
+		"f0312": {
+			"glyf": "AAIAAAHoAlgDQAADAAwAAAEzESMHFyEVIQcXNycCIDg48mj+agGWaCqqqgHoAVgqZjhoKKys"
+		},
 		"f0331": {
 			"glyf": "AAIAAAE+AlgD6gAIABYAAAEyNjQmIgYUFhcuASMRMhYXPgEzESIGASwqOjpUOjoqPJpWVpo8PphWVpgDIjtTOjpTO3U4Pf6SPjg4PgFuPQ=="
 		},
@@ -700,6 +709,18 @@
 		"f0616": {
 			"glyf": "AAIAAAFoAlgDwAAIABEAABM1IzcnBzUjFQE3FTM1IxUzB+h2ljCURAGAlETodpYBaEOWL5Z36QFQlnfpQ5Y="
 		},
+		"f0633": {
+			"glyf": "AAYAAAFoAlgDwAAoADEANQA+AEcAUAAAEzIWHQEzNTQ2MhYUBisBFTMyFhQGIiY9ASMVFAYiJjQ2OwE1IyImNDYBFBYyNjQmKwEnIxUzByIGFBYyNj0BETQmIgYUFjsBITI2NCYiBh0BeDBIeEZiSEgwPDwwSEhiRnhIYkZGMjw8MkZGAV4iNCIiGjw8eHjwGiIiMiQkMiIiGjwBLBgkIjQiA8BGMT09MUZGYkd5R2JHRzE9PTFHR2JHeUdiRv4gGSMjMiS0eTskMiMjGT0BLBkjIzMjIzMjIxk9"
+		},
+		"f0634": {
+			"glyf": "AAEAAAHjAlgDRQAHAAABByInByciAQJYNQH29jUBASwCGTb09DYBLA=="
+		},
+		"f0635": {
+			"glyf": "AAIAAAGJAlgDnwAHAAsAABEzEzMVIwMjJTMVI8zsoMzqogFw6OgDn/4tQwHTQ0M="
+		},
+		"f0636": {
+			"glyf": "AAIAAAGkAlgDhAAGAA0AAAE1MycHMxUTASMVITUjAYZAmpxCWgEslv7UlgHgtJqatAGk/tS0tA=="
+		},
 		"f0638": {
 			"glyf": "AAP/+wGDAlwDpQAFABsAIQAAAScRNzYmBRMeARcyPwE+ATc0JwMuASMiDwEOASU0JisBFwI0KEYKE/28jgccEAwL1A4UAQSQBR4PCwzTFRQB2SIYKWMDaBH+/qgVLGL+qRATAQVYBxwQCwsBWBAUBFgKLFgYIu8="
 		},
@@ -748,9 +769,15 @@
 		"f0d57": {
 			"glyf": "AAQAAAFoAlgDwAAQACAAJAAoAAABBxc1PgI0LgEnFR4BFAYHJTQ2NzUOAhUUFhcnNy4BASMRNxE1JxUBaHh4RG4+Pm5EUGRmTv7UZFBEbj5uVhQkRFQBDjw8PAKUd3ldByo/Rz8qBzwHMj4xB1cfMQg8Byo/JDBNDxUjCi4BSP63O/62Hj1b"
 		},
+		"f0e7e": {
+			"glyf": "AAIAAAGzAlgDdQAOABoAABMhMj8BJyYjISIGFREUFhM3FzcXBxcHJwcnNzIBeBQUhoYUFP6IFB4eYCRYWiRaWiRaWCRYAbMWy8sWHRX+ohUdATsjWlojWlojWlojWg=="
+		},
 		"f0eab": {
 			"glyf": "AAUAAAFoAlgDwAALACAAJAAqAC4AAAEzFTMVIxUjNSM1MwEhMhYdASYnNSERMxYXIyImNRE0NhchFSEVIRUGByMVMxUjAbo+YGA+Xl7+hgG4HCQeIv5I4AQS9hwkJFoBPP7EATwoIvKengJkXz5fXz4BuyUb9hEF4P5HIh4lGwG5GyV+QD8jBhY/QA=="
 		},
+		"f1050": {
+			"glyf": "AAEAAAIwAlgC+AANAAARMxUhNTMVFAYjISImNUQB0EQoHP4wHCgC+IWFhRwnJxw="
+		},
 		"f12b7": {
 			"glyf": "AAMAAAILAlgDHQALACMAOwAAETMVIxUzFSMVMxUjATMVIxUzMhYdARQGKwE1MzUjIiY9ATQ2OwEyFh0BIzUjFTM1MxUUBisBIiY9ATQ2pGxsbGykARJsbDQYICAYbGw0GCAg8DYYIDg2NjggGDYWICADHTc3Njc3ARI3NyAWNxcgNzcgFjcXICAXGxukGxsXICEWpBcg"
 		},

package/src/theme/symbols.ts

@@ -99,7 +99,6 @@ export type SymbolKey =
 	| "icon.advisorClosed"
 	| "icon.time"
 	| "icon.omp"
-	| "icon.esc"
 	| "icon.ghost"
 	| "icon.agents"
 	| "icon.job"
@@ -285,7 +284,28 @@ export type SymbolKey =
 	| "tool.goal"
 	| "tool.irc"
 	| "tool.delete"
-	| "tool.move";
+	| "tool.move"
+	// Keyboard keys (rendered by formatKeyHint). `*Mac` variants replace the
+	// generic modifier on macOS, whose keycaps are labelled with ⌃ ⌥ ⌘.
+	| "key.ctrl"
+	| "key.ctrlMac"
+	| "key.shift"
+	| "key.alt"
+	| "key.altMac"
+	| "key.super"
+	| "key.superMac"
+	// Gap after a glyph modifier (`⌃⇧C`); nerd icons render too small to abut
+	| "key.joiner"
+	| "key.enter"
+	| "key.esc"
+	| "key.tab"
+	| "key.backspace"
+	| "key.delete"
+	| "key.space"
+	| "key.up"
+	| "key.down"
+	| "key.left"
+	| "key.right";
 
 export type SymbolMap = Record<SymbolKey, string>;
 /**
@@ -459,7 +479,6 @@ const UNICODE_SYMBOLS: SymbolMap = {
 	"icon.advisorClosed": "🙈",
 	"icon.time": "⏱",
 	"icon.omp": "π",
-	"icon.esc": "⎋",
 	"icon.ghost": "👻",
 	"icon.agents": "👥",
 	"icon.job": "⚙",
@@ -646,6 +665,25 @@ const UNICODE_SYMBOLS: SymbolMap = {
 	"tool.irc": "✉",
 	"tool.delete": "🗑",
 	"tool.move": "➜",
+	// Keys: word modifiers off macOS (⌃/⌥/⌘ name no key on a PC keyboard)
+	"key.ctrl": "Ctrl",
+	"key.ctrlMac": "⌃",
+	"key.shift": "⇧",
+	"key.alt": "Alt",
+	"key.altMac": "⌥",
+	"key.super": "Super",
+	"key.superMac": "⌘",
+	"key.joiner": "",
+	"key.enter": "⏎",
+	"key.esc": "⎋",
+	"key.tab": "⇥",
+	"key.backspace": "⌫",
+	"key.delete": "⌦",
+	"key.space": "␣",
+	"key.up": "↑",
+	"key.down": "↓",
+	"key.left": "←",
+	"key.right": "→",
 };
 
 const NERD_SYMBOLS: SymbolMap = {
@@ -822,8 +860,6 @@ const NERD_SYMBOLS: SymbolMap = {
 	// U+F03FF before (2ec52b8bdd) and reverted because it renders the wrong glyph;
 	// do not swap it again.
 	"icon.omp": "\u{f0d57}",
-	// pick: 󱊷 (nf-md-keyboard_esc) | alt: ⎋
-	"icon.esc": "\u{f12b7}",
 	// pick: 󰊠 (nf-md-ghost) | alt: 👻
 	"icon.ghost": "\u{f02a0}",
 	// pick:  | alt: 
@@ -1098,6 +1134,35 @@ const NERD_SYMBOLS: SymbolMap = {
 	"tool.irc": "\uF086",
 	"tool.delete": "\uf12d",
 	"tool.move": "\uf061",
+	// Keys: word modifiers off macOS; arrows stay Unicode (nerd arrows add nothing)
+	"key.ctrl": "Ctrl",
+	// pick: 󰘴 (nf-md-apple_keyboard_control) | alt: ⌃
+	"key.ctrlMac": "\u{f0634}",
+	// pick: 󰘶 (nf-md-apple_keyboard_shift) | alt: ⇧
+	"key.shift": "\u{f0636}",
+	"key.alt": "Alt",
+	// pick: 󰘵 (nf-md-apple_keyboard_option) | alt: ⌥
+	"key.altMac": "\u{f0635}",
+	"key.super": "Super",
+	// pick: 󰘳 (nf-md-apple_keyboard_command) | alt: ⌘
+	"key.superMac": "\u{f0633}",
+	"key.joiner": " ",
+	// pick: 󰌑 (nf-md-keyboard_return) | alt: ⏎
+	"key.enter": "\u{f0311}",
+	// pick: 󱊷 (nf-md-keyboard_esc) | alt: ⎋
+	"key.esc": "\u{f12b7}",
+	// pick: 󰌒 (nf-md-keyboard_tab) | alt: ⇥
+	"key.tab": "\u{f0312}",
+	// pick: 󰁮 (nf-md-backspace) | alt: ⌫
+	"key.backspace": "\u{f006e}",
+	// pick: 󰹾 (nf-md-backspace_reverse) | alt: ⌦
+	"key.delete": "\u{f0e7e}",
+	// pick: 󱁐 (nf-md-keyboard_space) | alt: ␣
+	"key.space": "\u{f1050}",
+	"key.up": "↑",
+	"key.down": "↓",
+	"key.left": "←",
+	"key.right": "→",
 };
 
 const ASCII_SYMBOLS: SymbolMap = {
@@ -1192,7 +1257,6 @@ const ASCII_SYMBOLS: SymbolMap = {
 	"icon.advisorClosed": "(adv)",
 	"icon.time": "t:",
 	"icon.omp": "pi",
-	"icon.esc": "esc",
 	"icon.ghost": "@",
 	"icon.agents": "AG",
 	"icon.job": "bg",
@@ -1374,6 +1438,24 @@ const ASCII_SYMBOLS: SymbolMap = {
 	"tool.irc": "#",
 	"tool.delete": "rm",
 	"tool.move": "mv",
+	"key.ctrl": "Ctrl",
+	"key.ctrlMac": "Ctrl",
+	"key.shift": "Shift",
+	"key.alt": "Alt",
+	"key.altMac": "Option",
+	"key.super": "Super",
+	"key.superMac": "Cmd",
+	"key.joiner": "+",
+	"key.enter": "Enter",
+	"key.esc": "Esc",
+	"key.tab": "Tab",
+	"key.backspace": "Backspace",
+	"key.delete": "Delete",
+	"key.space": "Space",
+	"key.up": "Up",
+	"key.down": "Down",
+	"key.left": "Left",
+	"key.right": "Right",
 };
 
 export const SYMBOL_PRESETS: Record<SymbolPreset, SymbolMap> = {