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

package/src/prompt/macos-spelling.ts

@@ -4,6 +4,7 @@ import type { EditorInlineReplacement, EditorTextAssistProvider, EditorWordRepla
 import { logger } from "@oh-my-pi/pi-utils";
 import { isMagicKeyword } from "./magic-keywords";
 import { maskNonProse } from "./markdown-prose";
+import { isProseWord, lineContext, ProseSource, type SpellingDecorationContext } from "./prose-gate";
 
 /** Styled underline: red curly undercurl via colon-subparameter SGR (4:3 + SGR 58 color). */
 const STYLED_TYPO_MARKS = { start: "\x1b[4:3m\x1b[58:2::255:95:95m", end: "\x1b[4:0m\x1b[59m" } as const;
@@ -14,35 +15,20 @@ const STYLED_TYPO_MARKS = { start: "\x1b[4:3m\x1b[58:2::255:95:95m", end: "\x1b[
  */
 const FLAT_TYPO_MARKS = { start: "\x1b[4m", end: "\x1b[24m" } as const;
 
-const WORD_SUFFIX = /[\p{L}\p{M}']+$/u;
 const COMPLETED_WORD = /([\p{L}\p{M}']+)([\s.,;:!?"\])}])$/u;
-const CODEISH_CHARACTERS = "\\/@_=:{}[]<>";
-const CAMEL_CASE = /\p{Ll}\p{Lu}/u;
 const CACHE_LIMIT = 256;
-const MAX_SPELLING_BUFFER_LENGTH = 20_000;
-const MAX_SPELLING_LINE_LENGTH = 1_000;
 const WORD_BOUNDARY = /[\s.,;:!?"\])}]/u;
 
 /** Independently switchable macOS prose-assistance features. */
-export interface SpellingFeatures {
+export interface MacOSSpellingFeatures {
 	typoDetection: boolean;
-	autocomplete: boolean;
 	autocorrect: boolean;
 }
 
-/** Logical source location for one rendered editor segment. */
-export interface SpellingDecorationContext {
-	editorText: string;
-	lines: readonly string[];
-	line: number;
-	startCol: number;
-}
-
 /** Native spelling operations used by {@link MacOSSpellingProvider}. */
 export interface SpellingBackend {
 	isAvailable(): boolean;
 	checkSpelling(text: string): Promise<readonly native.SpellingRange[]>;
-	completeWord(text: string, start: number, length: number): Promise<readonly string[]>;
 	autocorrectWord(text: string, start: number, length: number): Promise<string | null>;
 	spellingGuesses(text: string, start: number, length: number): Promise<readonly string[]>;
 }
@@ -51,41 +37,21 @@ const NATIVE_BACKEND: SpellingBackend = {
 	isAvailable: () =>
 		typeof native.macOSSpellCheckerAvailable === "function" &&
 		typeof native.macOSCheckSpelling === "function" &&
-		typeof native.macOSCompleteWord === "function" &&
 		typeof native.macOSAutocorrectWord === "function" &&
 		typeof native.macOSSpellingGuesses === "function" &&
 		native.macOSSpellCheckerAvailable(),
 	checkSpelling: text => native.macOSCheckSpelling(text),
-	completeWord: (text, start, length) => native.macOSCompleteWord(text, start, length),
 	autocorrectWord: (text, start, length) => native.macOSAutocorrectWord(text, start, length),
 	spellingGuesses: (text, start, length) => native.macOSSpellingGuesses(text, start, length),
 };
 
-function tokenAt(text: string, start: number, end: number): string {
-	let tokenStart = start;
-	while (tokenStart > 0 && !/\s/.test(text[tokenStart - 1] ?? "")) tokenStart--;
-	let tokenEnd = end;
-	while (tokenEnd < text.length && !/\s/.test(text[tokenEnd] ?? "")) tokenEnd++;
-	return text.slice(tokenStart, tokenEnd);
-}
-
-function isProseWord(text: string, masked: string, start: number, end: number): boolean {
-	if (start < 0 || end <= start || end > text.length) return false;
-	if (masked.slice(start, end).trim().length === 0) return false;
-	const token = tokenAt(text, start, end);
-	for (const char of token) {
-		if (CODEISH_CHARACTERS.includes(char)) return false;
-	}
-	if (CAMEL_CASE.test(token) || /\d/.test(token)) return false;
-	return !text.trimStart().startsWith("/") && !text.startsWith("->") && !text.startsWith("=>");
-}
-
 /**
- * Bridges Apple's spelling service into the editor's separate typo,
- * word-completion, and autocorrection paths.
+ * Bridges Apple's spelling service into the editor's typo and autocorrection
+ * paths. Word completion is the cross-platform `WordCompletionProvider`
+ * (`word-completion.ts`).
  */
 export class MacOSSpellingProvider implements EditorTextAssistProvider {
-	#features: SpellingFeatures = { typoDetection: false, autocomplete: false, autocorrect: false };
+	#features: MacOSSpellingFeatures = { typoDetection: false, autocorrect: false };
 	#available: boolean;
 	#availabilityChecked = false;
 	#cacheGeneration = 0;
@@ -93,12 +59,7 @@ export class MacOSSpellingProvider implements EditorTextAssistProvider {
 	#typoInFlight = new Map<string, Promise<readonly native.SpellingRange[]>>();
 	#automaticTypoActive = false;
 	#automaticTypoQueue = new Map<string, string>();
-	#completionCache = new Map<string, string | null>();
-	#completionActiveKey: string | undefined;
-	#completionQueued: { key: string; line: string; start: number; prefix: string } | undefined;
-	#sourceText = "";
-	#sourceMask = "";
-	#sourceLineOffsets: number[] = [];
+	#prose = new ProseSource();
 	/** Underline open/close pair, chosen once from the terminal's styled-underline capability. */
 	readonly #marks: { start: string; end: string };
 
@@ -113,17 +74,16 @@ export class MacOSSpellingProvider implements EditorTextAssistProvider {
 		this.#marks = styledUnderlines ? STYLED_TYPO_MARKS : FLAT_TYPO_MARKS;
 	}
 
-	/** Apply all three independent feature gates and invalidate rendered typo ranges. */
-	setFeatures(features: SpellingFeatures): void {
+	/** Apply both independent feature gates and invalidate rendered typo ranges. */
+	setFeatures(features: MacOSSpellingFeatures): void {
 		if (
 			this.#features.typoDetection === features.typoDetection &&
-			this.#features.autocomplete === features.autocomplete &&
 			this.#features.autocorrect === features.autocorrect
 		) {
 			return;
 		}
 		this.#features = { ...features };
-		if (!this.#availabilityChecked && (features.typoDetection || features.autocomplete || features.autocorrect)) {
+		if (!this.#availabilityChecked && (features.typoDetection || features.autocorrect)) {
 			this.#availabilityChecked = true;
 			this.#available = typeof this.backend.isAvailable === "function" && this.backend.isAvailable();
 		}
@@ -137,7 +97,7 @@ export class MacOSSpellingProvider implements EditorTextAssistProvider {
 		decorate: (span: string) => string = value => value,
 	): string {
 		if (!this.#available || !this.#features.typoDetection || text.length === 0) return decorate(text);
-		if (!this.#sourceRangeIsProse(context, context.startCol, context.startCol + text.length)) {
+		if (!this.#prose.isProse(context, context.startCol, context.startCol + text.length)) {
 			return decorate(text);
 		}
 		const lane = `${context.line}:${context.startCol}`;
@@ -160,7 +120,7 @@ export class MacOSSpellingProvider implements EditorTextAssistProvider {
 			// must never re-emit already-rendered text: that doubles it on screen and
 			// desyncs the rendered width from the measured width (cursor drift).
 			if (range.start < cursor || end > text.length) continue;
-			if (!this.#sourceRangeIsProse(context, context.startCol + range.start, context.startCol + end)) {
+			if (!this.#prose.isProse(context, context.startCol + range.start, context.startCol + end)) {
 				continue;
 			}
 			rendered += decorate(text.slice(cursor, range.start));
@@ -170,26 +130,6 @@ export class MacOSSpellingProvider implements EditorTextAssistProvider {
 		return rendered + decorate(text.slice(cursor));
 	}
 
-	/** Return the cached macOS completion suffix for the word ending at the cursor. */
-	getWordCompletion(lines: string[], cursorLine: number, cursorCol: number): string | null {
-		if (!this.#available || !this.#features.autocomplete) return null;
-		const line = lines[cursorLine] ?? "";
-		if (/^[\p{L}\p{M}']/u.test(line.slice(cursorCol))) return null;
-		const match = WORD_SUFFIX.exec(line.slice(0, cursorCol));
-		if (!match || match[0].length < 2) return null;
-		const start = cursorCol - match[0].length;
-		const masked = maskNonProse(line);
-		if (!isProseWord(line, masked, start, cursorCol)) return null;
-		const context = this.#context(lines, cursorLine);
-		if (!this.#sourceRangeIsProse(context, start, cursorCol)) return null;
-
-		const prefix = match[0];
-		const key = `${start}:${prefix.length}:${line}`;
-		if (this.#completionCache.has(key)) return this.#completionCache.get(key) ?? null;
-		this.#scheduleWordCompletion(key, line, start, prefix);
-		return null;
-	}
-
 	/** Return the confident macOS correction after a completed prose word. */
 	async tryAutocorrect(
 		lines: string[],
@@ -207,8 +147,8 @@ export class MacOSSpellingProvider implements EditorTextAssistProvider {
 		const start = match.index;
 		const masked = maskNonProse(textBeforeCursor);
 		if (!isProseWord(textBeforeCursor, masked, start, start + word.length)) return null;
-		const context = this.#context(lines, cursorLine);
-		if (!this.#sourceRangeIsProse(context, start, start + word.length)) return null;
+		const context = lineContext(lines, cursorLine);
+		if (!this.#prose.isProse(context, start, start + word.length)) return null;
 		try {
 			const correction = await this.backend.autocorrectWord(textBeforeCursor, start, word.length);
 			if (!correction || correction === word) return null;
@@ -228,15 +168,15 @@ export class MacOSSpellingProvider implements EditorTextAssistProvider {
 		if (!this.#available || !this.#features.typoDetection) return null;
 
 		const line = lines[cursorLine] ?? "";
-		const context = this.#context(lines, cursorLine);
-		if (!this.#sourceRangeIsProse(context, 0, line.length)) return null;
+		const context = lineContext(lines, cursorLine);
+		if (!this.#prose.isProse(context, 0, line.length)) return null;
 		const ranges = this.#typoCache.get(line) ?? (await this.#loadTypoRanges(line));
 		const range = ranges.find(candidate => {
 			const end = candidate.start + candidate.length;
 			return (
 				cursorCol >= candidate.start &&
 				(cursorCol <= end || (cursorCol === end + 1 && WORD_BOUNDARY.test(line[end] ?? ""))) &&
-				this.#sourceRangeIsProse(context, candidate.start, end)
+				this.#prose.isProse(context, candidate.start, end)
 			);
 		});
 		if (!range || !this.#available || !this.#features.typoDetection) return null;
@@ -365,92 +305,11 @@ export class MacOSSpellingProvider implements EditorTextAssistProvider {
 		return ranges;
 	}
 
-	#scheduleWordCompletion(key: string, line: string, start: number, prefix: string): void {
-		if (this.#completionActiveKey === key || this.#completionQueued?.key === key) return;
-		if (this.#completionActiveKey !== undefined) {
-			this.#completionQueued = { key, line, start, prefix };
-			return;
-		}
-		this.#startWordCompletion(key, line, start, prefix);
-	}
-	#startWordCompletion(key: string, line: string, start: number, prefix: string): void {
-		this.#completionActiveKey = key;
-		const generation = this.#cacheGeneration;
-		const request = this.#fetchWordCompletion(key, line, start, prefix, generation);
-		const finished = (): void => {
-			if (this.#completionActiveKey === key) this.#completionActiveKey = undefined;
-			const queued = this.#completionQueued;
-			this.#completionQueued = undefined;
-			if (queued && this.#available && this.#features.autocomplete && !this.#completionCache.has(queued.key)) {
-				this.#startWordCompletion(queued.key, queued.line, queued.start, queued.prefix);
-			}
-		};
-		void request.then(finished, finished);
-	}
-
-	async #fetchWordCompletion(
-		key: string,
-		line: string,
-		start: number,
-		prefix: string,
-		generation: number,
-	): Promise<void> {
-		try {
-			const completions = await this.backend.completeWord(line, start, prefix.length);
-			if (generation !== this.#cacheGeneration || !this.#available) return;
-			const lowerPrefix = prefix.toLocaleLowerCase();
-			let suffix: string | null = null;
-			for (const completion of completions) {
-				if (completion.length > prefix.length && completion.toLocaleLowerCase().startsWith(lowerPrefix)) {
-					suffix = completion.slice(prefix.length);
-					break;
-				}
-			}
-			if (this.#completionCache.size >= CACHE_LIMIT) this.#completionCache.clear();
-			this.#completionCache.set(key, suffix);
-			// A null suffix means no ghost text; the current paint is already right.
-			if (suffix !== null && this.#completionQueued === undefined) this.onUpdate?.();
-		} catch (error) {
-			this.#disable(error);
-		}
-	}
-
-	#context(lines: readonly string[], line: number): SpellingDecorationContext {
-		return { editorText: lines.join("\n"), lines, line, startCol: 0 };
-	}
-
-	#sourceRangeIsProse(context: SpellingDecorationContext, startCol: number, endCol: number): boolean {
-		if (context.editorText.length > MAX_SPELLING_BUFFER_LENGTH || startCol < 0 || endCol <= startCol) {
-			return false;
-		}
-		const line = context.lines[context.line];
-		if (line === undefined || line.length > MAX_SPELLING_LINE_LENGTH || endCol > line.length) return false;
-		this.#prepareSource(context);
-		const lineOffset = this.#sourceLineOffsets[context.line];
-		if (lineOffset === undefined) return false;
-		return this.#sourceMask.slice(lineOffset + startCol, lineOffset + endCol).trim().length > 0;
-	}
-
-	#prepareSource(context: SpellingDecorationContext): void {
-		if (this.#sourceText === context.editorText) return;
-		this.#sourceText = context.editorText;
-		this.#sourceMask = maskNonProse(context.editorText);
-		// oxlint-disable-next-line unicorn/no-new-array -- length preallocation
-		this.#sourceLineOffsets = new Array<number>(context.lines.length);
-		let offset = 0;
-		for (let line = 0; line < context.lines.length; line++) {
-			this.#sourceLineOffsets[line] = offset;
-			offset += (context.lines[line]?.length ?? 0) + 1;
-		}
-	}
-
 	#clearCaches(): void {
 		this.#cacheGeneration++;
 		this.#typoCache.clear();
 		this.#typoInFlight.clear();
 		this.#automaticTypoQueue.clear();
-		this.#completionCache.clear();
-		this.#completionQueued = undefined;
 	}
 
 	#disable(error: unknown): void {

package/src/prompt/prompt-action-autocomplete.ts

@@ -135,6 +135,7 @@ export class PromptActionAutocompleteProvider 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] || "";
@@ -150,7 +151,13 @@ export class PromptActionAutocompleteProvider implements AutocompleteProvider {
 			const commandName = commandText.slice(1, spaceIndex);
 			const command = this.#commands.find(cmd => cmd.name === commandName || cmd.aliases?.includes(commandName));
 			if (command && (!("allowArgs" in command) || command.allowArgs !== false)) {
-				const argumentSuggestions = await this.#baseProvider.getSuggestions(lines, cursorLine, cursorCol, signal);
+				const argumentSuggestions = await this.#baseProvider.getSuggestions(
+					lines,
+					cursorLine,
+					cursorCol,
+					signal,
+					onPartial,
+				);
 				if (argumentSuggestions) return argumentSuggestions;
 				const modelMentionSuggestions = getModelMentionSuggestions(textBeforeCursor, this.#modelMentions);
 				if (modelMentionSuggestions) return modelMentionSuggestions;
@@ -205,7 +212,7 @@ export class PromptActionAutocompleteProvider implements AutocompleteProvider {
 			if (emojiSuggestions) return emojiSuggestions;
 		}
 
-		return this.#baseProvider.getSuggestions(lines, cursorLine, cursorCol, signal);
+		return this.#baseProvider.getSuggestions(lines, cursorLine, cursorCol, signal, onPartial);
 	}
 
 	applyCompletion(

package/src/prompt/prose-gate.ts

@@ -0,0 +1,87 @@
+import { maskNonProse } from "./markdown-prose";
+
+/**
+ * Client-side gates shared by the prose assistants (macOS typo/autocorrect and
+ * word completion): only plain prose words in modest buffers are ever sent to
+ * a spelling or prediction backend.
+ */
+
+const CODEISH_CHARACTERS = "\\/@_=:{}[]<>";
+const CAMEL_CASE = /\p{Ll}\p{Lu}/u;
+/** Buffers above this many UTF-16 units get no prose assistance at all. */
+const MAX_PROSE_BUFFER_LENGTH = 20_000;
+/** Lines above this many UTF-16 units get no prose assistance at all. */
+const MAX_PROSE_LINE_LENGTH = 1_000;
+
+/** Logical source location for one rendered editor segment. */
+export interface SpellingDecorationContext {
+	editorText: string;
+	lines: readonly string[];
+	line: number;
+	startCol: number;
+}
+
+function tokenAt(text: string, start: number, end: number): string {
+	let tokenStart = start;
+	while (tokenStart > 0 && !/\s/.test(text[tokenStart - 1] ?? "")) tokenStart--;
+	let tokenEnd = end;
+	while (tokenEnd < text.length && !/\s/.test(text[tokenEnd] ?? "")) tokenEnd++;
+	return text.slice(tokenStart, tokenEnd);
+}
+
+/**
+ * Whether `text[start, end)` is a prose word: unmasked by {@link maskNonProse},
+ * not inside a path/identifier-like token, and not on a slash-command or
+ * queue-shorthand line.
+ */
+export function isProseWord(text: string, masked: string, start: number, end: number): boolean {
+	if (start < 0 || end <= start || end > text.length) return false;
+	if (masked.slice(start, end).trim().length === 0) return false;
+	const token = tokenAt(text, start, end);
+	for (const char of token) {
+		if (CODEISH_CHARACTERS.includes(char)) return false;
+	}
+	if (CAMEL_CASE.test(token) || /\d/.test(token)) return false;
+	return !text.trimStart().startsWith("/") && !text.startsWith("->") && !text.startsWith("=>");
+}
+
+/** Whole-buffer context for `line`, starting at column 0. */
+export function lineContext(lines: readonly string[], line: number): SpellingDecorationContext {
+	return { editorText: lines.join("\n"), lines, line, startCol: 0 };
+}
+
+/**
+ * Memoized whole-buffer prose mask: answers whether a line range is prose in
+ * the context of the full editor text (fenced code spans lines).
+ */
+export class ProseSource {
+	#text = "";
+	#mask = "";
+	#lineOffsets: number[] = [];
+
+	/** True when `[startCol, endCol)` of `context.line` is prose and the buffer is within the caps. */
+	isProse(context: SpellingDecorationContext, startCol: number, endCol: number): boolean {
+		if (context.editorText.length > MAX_PROSE_BUFFER_LENGTH || startCol < 0 || endCol <= startCol) {
+			return false;
+		}
+		const line = context.lines[context.line];
+		if (line === undefined || line.length > MAX_PROSE_LINE_LENGTH || endCol > line.length) return false;
+		this.#prepare(context);
+		const lineOffset = this.#lineOffsets[context.line];
+		if (lineOffset === undefined) return false;
+		return this.#mask.slice(lineOffset + startCol, lineOffset + endCol).trim().length > 0;
+	}
+
+	#prepare(context: SpellingDecorationContext): void {
+		if (this.#text === context.editorText) return;
+		this.#text = context.editorText;
+		this.#mask = maskNonProse(context.editorText);
+		// oxlint-disable-next-line unicorn/no-new-array -- length preallocation
+		this.#lineOffsets = new Array<number>(context.lines.length);
+		let offset = 0;
+		for (let line = 0; line < context.lines.length; line++) {
+			this.#lineOffsets[line] = offset;
+			offset += (context.lines[line]?.length ?? 0) + 1;
+		}
+	}
+}

package/src/prompt/tips.txt

@@ -1,7 +1,7 @@
 Tired of typing "keep going"? Just send a '.'
 You can /btw to ask a side question
 Use /tan to fork the current conversation into a background agent
-With default keybindings, Ctrl+D deletes the character under the cursor instead of quitting your draft — see /hotkeys for your exit key
+With default keybindings, {key:ctrl+d} deletes the character under the cursor instead of quitting your draft — see /hotkeys for your exit key
 Find out which model you emotionally abuse the most with `omp stats`
 Try task isolation to create CoW worktrees
 Need a cheap nested model call? Use `completion(x...)`. Have a big batch of tasks? Ask clanker to use it!
@@ -13,17 +13,17 @@ Say `workflowz` in your message to drive the task with parallel subagents in eva
 Bulk data to classify or triage? Say `jevify` in your message — the eval kernel's `judge()` processes the batch and you read only what it flags — watch it glow as you type
 Log in to several accounts of the same provider — `/login` again — and omp load-balances across them automatically
 Run `omp auth-broker serve` once and every machine pulls live tokens over the wire — refresh keys never leave the host; `omp auth-gateway` fronts it as a drop-in proxy any OpenAI-compatible client can hit
-Press alt+p (or /switch) to switch provider, and ctrl+p to cycle role models smol -> slow -> etc
-Press ctrl+r to search your prompt history and reuse a past message
+Press {key:alt+p} (or /switch) to switch provider, and {key:ctrl+p} to cycle role models smol -> slow -> etc
+Press {key:ctrl+r} to search your prompt history and reuse a past message
 `/force read` pins the next turn to one specific tool when the model keeps reaching for the wrong one
 `/copy code` grabs the last code block to your clipboard — `/copy cmd` grabs the last shell/python command
 `/shake` rips heavy tool results out of context to reclaim tokens without a full /compact — `/shake images` drops just images
 Pair up live: `/collab` shares your session through an end-to-end encrypted relay link — a teammate runs `/join <link>` to watch tool calls stream and prompt the agent from their own omp
-Press ← ← to drill into a running or finished agent and inspect its tool calls and transcript
+Press {tap:left} to drill into a running or finished agent and inspect its tool calls and transcript
 Hit a Codex rate limit? `/usage reset` spends a saved reset credit to immediately restore your quota
 No native tool_calling? Inference provider botches parsing them? `PI_DIALECT=glm|kimi|anthropic…` rolls it locally for them!
 Turn on `/advisor` to attach a second model that reviews every turn and quietly injects advice
 Try starting your prompt with a ->, and writing a list (1. Do X, 2. Do Y)
-Press shift+tab to cycle through reasoning effort levels
+Press {key:shift+tab} to cycle through reasoning effort levels
 omp can reconfigure and extend itself — ask any questions you have!
-Lint/type errors piling up? `omp cleanse` (or /cleanse right here) hunts project diagnostics and fixes them with parallel subagents — esc cancels
+Lint/type errors piling up? `omp cleanse` (or /cleanse right here) hunts project diagnostics and fixes them with parallel subagents — {key:escape} cancels

package/src/prompt/welcome.ts

@@ -3,9 +3,13 @@ import type { Component } from "../tui";
 import { padding, replaceTabs, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "../utils";
 import { APP_NAME } from "@oh-my-pi/pi-utils/dirs";
 import { theme } from "../theme/theme";
+import { formatDoubleTap, formatKeyHint, formatKeyHints, type KeyName } from "../app-keybindings";
+import { editorKey } from "../chrome/keybinding-hints";
+import { getKeybindings, type Keybinding } from "../keybindings";
 import tipsText from "./tips.txt" with { type: "text" };
 
-/** Tips embedded at build time, one per line; blanks dropped. */
+/** Tips embedded at build time, one per line; blanks dropped. Key placeholders
+ *  (see {@link expandTipKeys}) stay raw until render time. */
 const TIPS: readonly string[] = tipsText
 	.split("\n")
 	.map(line => line.trim())
@@ -76,6 +80,35 @@ function renderNewTag(phase: number, encoding: ColorEncoding): string {
 	}
 	return out + reset;
 }
+
+/** Key placeholders in tips.txt: `{key:shift+tab}`, `{keys:up,down}`, `{tap:left}`, `{action:tui.editor.undo}`. */
+const TIP_KEY_PLACEHOLDER = /\{(key|keys|tap|action):([^}]+)\}/g;
+
+const MODIFIER_NAMES: Record<string, true | undefined> = { ctrl: true, shift: true, alt: true, super: true };
+
+/** A `+`-joined chord whose leading parts are modifiers (`ctrl+o`, `shift`, `left`). */
+function isKeyName(key: string): key is KeyName {
+	const parts = key.split("+");
+	return parts.every((part, i) => part.length > 0 && (i === parts.length - 1 || MODIFIER_NAMES[part] === true));
+}
+
+function isKeybinding(action: string): action is Keybinding {
+	return action in getKeybindings().getResolvedBindings();
+}
+
+/** Expand tip key placeholders through the key formatter; malformed ones stay verbatim. */
+function expandTipKeys(tip: string): string {
+	return tip.replace(TIP_KEY_PLACEHOLDER, (placeholder, kind: string, value: string) => {
+		if (kind === "action") return isKeybinding(value) ? editorKey(value) : placeholder;
+		const keys = value.split(",");
+		if (!keys.every(isKeyName)) return placeholder;
+		if (kind === "keys") return formatKeyHints(keys);
+		const [key] = keys;
+		if (key === undefined) return placeholder;
+		return kind === "tap" ? formatDoubleTap(key) : formatKeyHint(key);
+	});
+}
+
 export function renderWelcomeTip(tip: string, boxWidth: number, phase = 0): string[] {
 	const label = "Tip: ";
 	const labelWidth = visibleWidth(label);
@@ -83,7 +116,7 @@ export function renderWelcomeTip(tip: string, boxWidth: number, phase = 0): stri
 	if (bodyBudget < 8) return [];
 
 	const isNew = NEW_TIP_MARKER.test(tip);
-	const body = isNew ? tip.replace(NEW_TIP_MARKER, "") : tip;
+	const body = expandTipKeys(isNew ? tip.replace(NEW_TIP_MARKER, "") : tip);
 
 	const wrappedBody = wrapTextWithAnsi(replaceTabs(body), bodyBudget);
 	if (wrappedBody.length === 0) return [];