@linxiraos/pi-tui 1.1.26 → 1.2.0

package/src/components/scroll-view.d.ts

@@ -92,6 +92,7 @@ export declare class ScrollView implements Component {
     /** Apply Arrow, Shift+Arrow, Page, Home, and End navigation keys. */
     handleScrollKey(data: string): boolean;
     invalidate(): void;
+    releaseRenderCaches(): void;
     /** Permanently release a wrapped child's timers, subscriptions, and other resources. */
     dispose(): void;
     /**

package/src/components/scroll-view.ts

@@ -408,6 +408,11 @@ export class ScrollView implements Component {
 		this.#child?.invalidate?.();
 	}
 
+	releaseRenderCaches(): void {
+		this.#cache = undefined;
+		this.#child?.releaseRenderCaches?.();
+	}
+
 	/** Permanently release a wrapped child's timers, subscriptions, and other resources. */
 	dispose(): void {
 		if (this.#disposed) return;

package/src/components/section.d.ts

@@ -15,6 +15,7 @@ export declare class Section implements Component {
     #private;
     constructor(options: SectionOptions);
     invalidate(): void;
+    releaseRenderCaches(): void;
     dispose(): void;
     /** A `section` headed by the styled title; the rule is the terminal's. */
     describe(_cx: DescribeContext): NativeNode;

package/src/components/section.ts

@@ -51,6 +51,11 @@ export class Section implements Component {
 		this.#cache = undefined;
 	}
 
+	releaseRenderCaches(): void {
+		this.#cache = undefined;
+		if (isComponent(this.#options.body)) this.#options.body.releaseRenderCaches?.();
+	}
+
 	dispose(): void {
 		if (this.#disposed) return;
 		this.#disposed = true;

package/src/components/settings-list.ts

@@ -346,6 +346,8 @@ export class SettingsList implements Component {
 			return { row: id, option: component.selectList.getSelectedItem()?.value };
 		}
 		if (component instanceof TextFormField) {
+			// Native inline text editing has no error slot; show the form until corrected.
+			if (component.hasError) return null;
 			const draft = component.getValue();
 			return {
 				row: id,

package/src/components/table.d.ts

@@ -29,6 +29,7 @@ export declare class Table implements Component {
     constructor(rows: readonly (readonly TableCell[])[], columns: readonly TableColumn[], options?: TableOptions);
     setRows(rows: readonly (readonly TableCell[])[]): boolean;
     invalidate(): void;
+    releaseRenderCaches(): void;
     /**
      * A native `table`. Column priorities carry over unchanged (lower gives
      * way first); truncating columns truncate at the end, the rest keep

package/src/components/table.ts

@@ -117,6 +117,10 @@ export class Table implements Component {
 		this.#native = undefined;
 	}
 
+	releaseRenderCaches(): void {
+		this.#cache = undefined;
+	}
+
 	/**
 	 * A native `table`. Column priorities carry over unchanged (lower gives
 	 * way first); truncating columns truncate at the end, the rest keep

package/src/components/text.d.ts

@@ -26,6 +26,7 @@ export declare class Text implements Component {
      */
     setStyleFn(styleFn?: (text: string) => string): this;
     invalidate(): void;
+    releaseRenderCaches(): void;
     /**
      * Wrapped text; styling re-derived from the styled source so a theme swap
      * re-resolves tokens. A background fill becomes the node's tone.

package/src/components/text.ts

@@ -109,6 +109,13 @@ export class Text implements Component {
 		this.#cachedLines = undefined;
 	}
 
+	releaseRenderCaches(): void {
+		this.#cachedText = undefined;
+		this.#cachedWidth = undefined;
+		this.#cachedWidthConfigEpoch = undefined;
+		this.#cachedLines = undefined;
+	}
+
 	/**
 	 * Wrapped text; styling re-derived from the styled source so a theme swap
 	 * re-resolves tokens. A background fill becomes the node's tone.

package/src/components/tree-view.d.ts

@@ -34,6 +34,13 @@ export interface FlattenTreeOptions<T, K extends TreeKey> {
     rootDepth?: number;
     /** Override the display depth inherited by direct children. */
     getChildDepth?: (item: T, row: TreeRow<T, K>, children: readonly T[]) => number;
+    /**
+     * Reuse the parent ancestor list when a child keeps the same display depth
+     * and the current item has no siblings (`siblingCount === 1`). Otherwise
+     * retain the current item as an ancestor so connector gutters remain
+     * accurate, including when the item has multiple children.
+     */
+    compactSameDepthAncestors?: boolean;
     /** Stop projection after this many structural items. Omit for no traversal cap. */
     maxItems?: number;
 }

package/src/components/tree-view.ts

@@ -43,17 +43,41 @@ export interface FlattenTreeOptions<T, K extends TreeKey> {
 	rootDepth?: number;
 	/** Override the display depth inherited by direct children. */
 	getChildDepth?: (item: T, row: TreeRow<T, K>, children: readonly T[]) => number;
+	/**
+	 * Reuse the parent ancestor list when a child keeps the same display depth
+	 * and the current item has no siblings (`siblingCount === 1`). Otherwise
+	 * retain the current item as an ancestor so connector gutters remain
+	 * accurate, including when the item has multiple children.
+	 */
+	compactSameDepthAncestors?: boolean;
 	/** Stop projection after this many structural items. Omit for no traversal cap. */
 	maxItems?: number;
 }
 
+/**
+ * Ancestors live in a shared parent chain instead of a per-row array: a linear
+ * conversation is an n-deep path, and copying the array at every level costs
+ * O(n²) memory — 80k-entry sessions exhausted RAM opening `/tree`. Rows build
+ * the array lazily, so only rendered rows pay O(depth).
+ */
+interface AncestorChain<K extends TreeKey> {
+	value: TreeAncestor<K>;
+	parent: AncestorChain<K> | undefined;
+}
+
+function ancestorArray<K extends TreeKey>(chain: AncestorChain<K> | undefined): readonly TreeAncestor<K>[] {
+	const out: TreeAncestor<K>[] = [];
+	for (let node = chain; node !== undefined; node = node.parent) out.push(node.value);
+	return out.reverse();
+}
+
 interface PendingTreeRow<T, K extends TreeKey> {
 	item: T;
 	parentKey: K | undefined;
 	depth: number;
 	siblingIndex: number;
 	siblingCount: number;
-	ancestors: readonly TreeAncestor<K>[];
+	chain: AncestorChain<K> | undefined;
 }
 
 interface FlattenTreeResult<T, K extends TreeKey> {
@@ -77,13 +101,14 @@ function projectTree<T, K extends TreeKey>(options: FlattenTreeOptions<T, K>): F
 			depth: rootDepth,
 			siblingIndex: index,
 			siblingCount: roots.length,
-			ancestors: [],
+			chain: undefined,
 		});
 	}
 
 	while (stack.length > 0 && rows.length < maxItems) {
 		const pending = stack.pop()!;
 		const key = options.getKey(pending.item);
+		const chain = pending.chain;
 		const row: TreeRow<T, K> = {
 			item: pending.item,
 			key,
@@ -93,7 +118,9 @@ function projectTree<T, K extends TreeKey>(options: FlattenTreeOptions<T, K>): F
 			siblingIndex: pending.siblingIndex,
 			siblingCount: pending.siblingCount,
 			isLast: pending.siblingIndex === pending.siblingCount - 1,
-			ancestors: pending.ancestors,
+			get ancestors() {
+				return ancestorArray(chain);
+			},
 		};
 		rows.push(row);
 
@@ -104,10 +131,13 @@ function projectTree<T, K extends TreeKey>(options: FlattenTreeOptions<T, K>): F
 			0,
 			Math.trunc(options.getChildDepth?.(pending.item, row, children) ?? pending.depth + 1),
 		);
-		const ancestors: readonly TreeAncestor<K>[] = [
-			...pending.ancestors,
-			{ key, depth: pending.depth, isLast: row.isLast, siblingCount: pending.siblingCount },
-		];
+		const childChain: AncestorChain<K> | undefined =
+			options.compactSameDepthAncestors && childDepth === pending.depth && pending.siblingCount === 1
+				? chain
+				: {
+						value: { key, depth: pending.depth, isLast: row.isLast, siblingCount: pending.siblingCount },
+						parent: chain,
+					};
 		for (let index = children.length - 1; index >= 0; index--) {
 			stack.push({
 				item: children[index],
@@ -115,7 +145,7 @@ function projectTree<T, K extends TreeKey>(options: FlattenTreeOptions<T, K>): F
 				depth: childDepth,
 				siblingIndex: index,
 				siblingCount: children.length,
-				ancestors,
+				chain: childChain,
 			});
 		}
 	}

package/src/components/truncated-text.d.ts

@@ -9,6 +9,7 @@ export declare class TruncatedText implements Component {
     /** Return bounded source text and the last-known truncation state. */
     debugState(): Record<string, unknown>;
     invalidate(): void;
+    releaseRenderCaches(): void;
     /** First line only, clamped to one visual line with an end ellipsis. */
     describe(_cx: DescribeContext): NativeNode;
     render(width: number): readonly string[];

package/src/components/truncated-text.ts

@@ -41,6 +41,11 @@ export class TruncatedText implements Component {
 		this.#cachedLines = undefined;
 	}
 
+	releaseRenderCaches(): void {
+		this.#cachedWidth = -1;
+		this.#cachedLines = undefined;
+	}
+
 	/** First line only, clamped to one visual line with an end ellipsis. */
 	describe(_cx: DescribeContext): NativeNode {
 		if (this.#native) return this.#native;

package/src/desktop-notify.ts

@@ -50,7 +50,8 @@ export function hasLinuxDesktopSession(
 	if (platform !== "linux") return false;
 	if (env.DBUS_SESSION_BUS_ADDRESS) return true;
 	const runtimeDir = env.XDG_RUNTIME_DIR;
-	return Boolean(runtimeDir && fileExists(path.join(runtimeDir, "bus")));
+	// Only reached for Linux, so join with POSIX separators regardless of the host.
+	return Boolean(runtimeDir && fileExists(path.posix.join(runtimeDir, "bus")));
 }
 
 /**
@@ -175,7 +176,7 @@ export function sendDesktopNotification(message: string | TerminalNotification):
 	try {
 		// `.unref()` lets the event loop exit while the notifier is still running.
 		// Without it, an unresponsive D-Bus activation (slow `notify-send`, hung
-		// `gdbus` waiting on a stalled session bus) would keep `omp` alive past
+		// `gdbus` waiting on a stalled session bus) would keep `zetacode` alive past
 		// the renderer's shutdown — a completion toast must never delay process
 		// exit. Ignored stdio alone does not detach the child from the parent's
 		// reference count.

package/src/fuzzy.d.ts

@@ -16,6 +16,20 @@ export interface FuzzyFilterResult<T> {
     score: number;
 }
 export declare function fuzzyMatch(query: string, text: string): FuzzyMatch;
+/**
+ * A query normalized and tokenized once for matching against many texts.
+ *
+ * `fuzzyMatch(query, text)` re-normalizes `query` (and rebuilds its
+ * alphanumeric-swap variants) on every call; filters that test one query
+ * against every row should build one `FuzzyQuery` per keystroke instead.
+ * `query.match(text)` returns exactly what `fuzzyMatch(query, text)` returns.
+ */
+export declare class FuzzyQuery {
+    #private;
+    constructor(query: string);
+    /** Same result as `fuzzyMatch(query, text)`; `text` may be a prepared {@link FuzzyText}. */
+    match(text: string | FuzzyText): FuzzyMatch;
+}
 /**
  * A text prepared once for repeated fuzzy matching.
  *
@@ -30,7 +44,21 @@ export declare class FuzzyText {
     #private;
     constructor(text: string);
     /** Match `query` (space-separated tokens; all must match) against the prepared text. */
-    match(query: string): FuzzyMatch;
+    match(query: string | FuzzyQuery): FuzzyMatch;
+}
+/**
+ * Items prepared once for repeated {@link fuzzyRank}-equivalent ranking.
+ *
+ * `fuzzyRank` resolves each candidate's search index through the bounded module
+ * cache, which holds at most {@link INDEX_CACHE_MAX} entries; larger candidate
+ * lists (the full model catalog) rebuild the overflow on every query. Hold one
+ * corpus per stable candidate list and call {@link rank} per keystroke instead.
+ */
+export declare class FuzzyCorpus<T> {
+    #private;
+    constructor(items: readonly T[], getText: (item: T) => string);
+    /** Same results as `fuzzyRank(items, query, getText)` for the prepared items. */
+    rank(query: string): FuzzyFilterResult<T>[];
 }
 /**
  * Filter and sort items by fuzzy match quality (best matches first).

package/src/fuzzy.ts

@@ -68,27 +68,41 @@ function normalizeForSearch(value: string): string {
 // index across keystrokes eliminates the redundant normalize + word-split + Set
 // build on every character. Consumers only read the result, so sharing is safe.
 //
-// Admission is conservative so the cache helps the repeated-filter hot path
-// without paying for one-off text: only short texts are cached (long inputs —
-// pasted prompts, transcripts searched via the message selector — would bloat
-// memory), and admission stops at the cap instead of evicting, so a stream of
-// unique texts (message/session search) can't churn the map.
+// Only short texts are cached (long inputs — pasted prompts, transcripts
+// searched via the message selector — would bloat memory). The map is a
+// bounded LRU: a hit re-inserts the entry (Map iteration order is insertion
+// order) and a miss at capacity evicts the oldest entry, so a burst of one-off
+// texts can't pin itself forever and starve later selectors of the cache.
+// A single ranking pass only admits/promotes its first INDEX_CACHE_MAX
+// candidates; the tail of a larger list is looked up without promotion and
+// built uncached otherwise, so re-ranking an oversized list keeps its head
+// cached instead of cyclically evicting every entry. Candidate lists larger
+// than the cap should hold a {@link FuzzyCorpus}.
 const INDEX_CACHE_MAX = 4096;
 const MAX_CACHED_TEXT_LEN = 4096;
 const indexCache = new Map<string, SearchIndex>();
 
-function buildSearchIndex(text: string): SearchIndex {
+function buildSearchIndex(text: string, admit = true): SearchIndex {
 	// Long inputs (pasted prompts, transcripts) are never cached; bypass the Map
 	// entirely so they don't pay a hash lookup on every search.
 	if (text.length > MAX_CACHED_TEXT_LEN) return buildUncachedSearchIndex(text);
 
 	const cached = indexCache.get(text);
-	if (cached !== undefined) return cached;
+	if (cached !== undefined) {
+		if (admit) {
+			indexCache.delete(text);
+			indexCache.set(text, cached);
+		}
+		return cached;
+	}
 
 	const result = buildUncachedSearchIndex(text);
-	if (indexCache.size < INDEX_CACHE_MAX) {
-		indexCache.set(text, result);
+	if (!admit) return result;
+	if (indexCache.size >= INDEX_CACHE_MAX) {
+		const oldest = indexCache.keys().next().value;
+		if (oldest !== undefined) indexCache.delete(oldest);
 	}
+	indexCache.set(text, result);
 	return result;
 }
 
@@ -307,11 +321,11 @@ function scoreTokenDirect(token: string, index: SearchIndex): FuzzyMatch {
 	return best ?? { matches: false, score: 0 };
 }
 
-function scoreToken(token: string, index: SearchIndex): FuzzyMatch {
+function scoreToken(token: string, swapVariants: readonly string[], index: SearchIndex): FuzzyMatch {
 	let best = scoreTokenDirect(token, index);
 	if (best.matches) return best;
 
-	for (const variant of buildAlphanumericSwapQueries(token)) {
+	for (const variant of swapVariants) {
 		const match = scoreTokenDirect(variant, index);
 		if (!match.matches) continue;
 		const score = match.score + ALPHANUMERIC_SWAP_PENALTY;
@@ -323,18 +337,26 @@ function scoreToken(token: string, index: SearchIndex): FuzzyMatch {
 	return best;
 }
 
-/** A query normalized and split once, so `fuzzyRank` doesn't re-normalize the
- * same query for every candidate in the list. */
+/** A query normalized and split once, so ranking doesn't re-normalize the
+ * same query (or rebuild its alphanumeric-swap variants) for every candidate. */
 interface PreparedQuery {
 	normalized: string;
 	tokens: string[];
+	/** `buildAlphanumericSwapQueries` of each token, index-aligned with `tokens`. */
+	tokenSwaps: string[][];
 	compact: string;
 }
 
 function prepareQuery(query: string): PreparedQuery | null {
 	const normalized = normalizeForSearch(query);
 	if (normalized.length === 0) return null;
-	return { normalized, tokens: normalized.split(" "), compact: normalized.replaceAll(" ", "") };
+	const tokens = normalized.split(" ");
+	return {
+		normalized,
+		tokens,
+		tokenSwaps: tokens.map(buildAlphanumericSwapQueries),
+		compact: normalized.replaceAll(" ", ""),
+	};
 }
 
 function fuzzyMatchCore(pq: PreparedQuery | null, index: SearchIndex): FuzzyMatch {
@@ -359,8 +381,8 @@ function fuzzyMatchCore(pq: PreparedQuery | null, index: SearchIndex): FuzzyMatc
 		totalScore += compactPhraseIndex * 0.01;
 	}
 
-	for (const token of pq.tokens) {
-		const match = scoreToken(token, index);
+	for (let i = 0; i < pq.tokens.length; i++) {
+		const match = scoreToken(pq.tokens[i]!, pq.tokenSwaps[i]!, index);
 		if (!match.matches) {
 			return { matches: false, score: 0 };
 		}
@@ -376,6 +398,33 @@ export function fuzzyMatch(query: string, text: string): FuzzyMatch {
 	return fuzzyMatchCore(pq, buildSearchIndex(text));
 }
 
+/**
+ * A query normalized and tokenized once for matching against many texts.
+ *
+ * `fuzzyMatch(query, text)` re-normalizes `query` (and rebuilds its
+ * alphanumeric-swap variants) on every call; filters that test one query
+ * against every row should build one `FuzzyQuery` per keystroke instead.
+ * `query.match(text)` returns exactly what `fuzzyMatch(query, text)` returns.
+ */
+export class FuzzyQuery {
+	readonly #prepared: PreparedQuery | null;
+
+	constructor(query: string) {
+		this.#prepared = prepareQuery(query);
+	}
+
+	/** Same result as `fuzzyMatch(query, text)`; `text` may be a prepared {@link FuzzyText}. */
+	match(text: string | FuzzyText): FuzzyMatch {
+		const pq = this.#prepared;
+		if (pq === null) return { matches: true, score: 0 };
+		return fuzzyMatchCore(pq, typeof text === "string" ? buildSearchIndex(text) : fuzzyTextIndex(text));
+	}
+}
+
+// Module-private read access to `FuzzyText#index` for `FuzzyQuery.match`;
+// assigned by FuzzyText's static initializer.
+let fuzzyTextIndex: (text: FuzzyText) => SearchIndex;
+
 /**
  * A text prepared once for repeated fuzzy matching.
  *
@@ -393,10 +442,57 @@ export class FuzzyText {
 		this.#index = buildUncachedSearchIndex(text);
 	}
 
+	static {
+		fuzzyTextIndex = text => text.#index;
+	}
+
 	/** Match `query` (space-separated tokens; all must match) against the prepared text. */
-	match(query: string): FuzzyMatch {
-		return fuzzyMatchCore(prepareQuery(query), this.#index);
+	match(query: string | FuzzyQuery): FuzzyMatch {
+		return typeof query === "string" ? fuzzyMatchCore(prepareQuery(query), this.#index) : query.match(this);
+	}
+}
+
+/**
+ * Items prepared once for repeated {@link fuzzyRank}-equivalent ranking.
+ *
+ * `fuzzyRank` resolves each candidate's search index through the bounded module
+ * cache, which holds at most {@link INDEX_CACHE_MAX} entries; larger candidate
+ * lists (the full model catalog) rebuild the overflow on every query. Hold one
+ * corpus per stable candidate list and call {@link rank} per keystroke instead.
+ */
+export class FuzzyCorpus<T> {
+	readonly #items: readonly T[];
+	readonly #indexes: SearchIndex[];
+
+	constructor(items: readonly T[], getText: (item: T) => string) {
+		this.#items = items;
+		this.#indexes = items.map(item => buildUncachedSearchIndex(getText(item)));
+	}
+
+	/** Same results as `fuzzyRank(items, query, getText)` for the prepared items. */
+	rank(query: string): FuzzyFilterResult<T>[] {
+		if (!query.trim()) return this.#items.map(item => ({ item, score: 0 }));
+		const indexes = this.#indexes;
+		return rankIndexed(this.#items, prepareQuery(query), i => indexes[i]!);
+	}
+}
+
+function rankIndexed<T>(
+	items: readonly T[],
+	pq: PreparedQuery | null,
+	indexAt: (i: number) => SearchIndex,
+): FuzzyFilterResult<T>[] {
+	const results: FuzzyFilterResult<T>[] = [];
+	for (let i = 0; i < items.length; i++) {
+		const index = indexAt(i);
+		const match = pq === null ? { matches: true, score: 0 } : fuzzyMatchCore(pq, index);
+		if (match.matches) {
+			results.push({ item: items[i]!, score: match.score });
+		}
 	}
+
+	results.sort((a, b) => a.score - b.score);
+	return results;
 }
 
 /**
@@ -411,18 +507,7 @@ export function fuzzyRank<T>(items: readonly T[], query: string, getText: (item:
 	// A non-blank query that normalizes to empty (pure punctuation) matches
 	// everything with score 0, but still calls getText per item — consumers rely
 	// on its side effects (see fuzzy-cache.test.ts).
-	const pq = prepareQuery(query);
-	const results: FuzzyFilterResult<T>[] = [];
-	for (const item of items) {
-		const text = getText(item);
-		const match = pq === null ? { matches: true, score: 0 } : fuzzyMatchCore(pq, buildSearchIndex(text));
-		if (match.matches) {
-			results.push({ item, score: match.score });
-		}
-	}
-
-	results.sort((a, b) => a.score - b.score);
-	return results;
+	return rankIndexed(items, prepareQuery(query), i => buildSearchIndex(getText(items[i]!), i < INDEX_CACHE_MAX));
 }
 
 export function fuzzyFilter<T>(items: T[], query: string, getText: (item: T) => string): T[] {

package/src/hotkeys-markdown.ts

@@ -62,6 +62,7 @@ function hotkeyGroups(bindings: HotkeysMarkdownBindings): HotkeyGroup[] {
 		if (keys.length > 0) return { keys: keys.map(formatKeyHint), ids: keys, action };
 		return { keys: [bindings.keybindings.getDisplayString(action) || "Disabled"], ids: [], action };
 	};
+	const pushToTalkKeys = bindings.keybindings.getKeys("app.stt.pushToTalk");
 	// CustomEditor tests the chord that was actually pressed, so exit keys split by role: a key
 	// that also carries tui.editor.deleteCharForward (the readline `^D` overlap) forward-deletes
 	// while the prompt holds a draft, any other exit key quits immediately. Mixed bindings such as
@@ -139,8 +140,14 @@ function hotkeyGroups(bindings: HotkeysMarkdownBindings): HotkeyGroup[] {
 				{ keys: [act("app.retry")], action: "Retry last failed assistant turn" },
 				{ keys: [act("app.clipboard.pasteImage")], action: "Paste image or text from clipboard" },
 				{
-					keys: [{ text: "Hold " }, hints(["space"])],
-					action: "Speech-to-text (push-to-talk): hold to record, release to transcribe",
+					keys:
+						pushToTalkKeys.length > 0
+							? [{ text: "Hold " }, act("app.stt.pushToTalk")]
+							: [act("app.stt.pushToTalk")],
+					action:
+						pushToTalkKeys.length > 0
+							? "Speech-to-text (push-to-talk): hold to record, release to transcribe"
+							: "Speech-to-text (push-to-talk) (disabled)",
 				},
 				{ keys: [act("app.live.toggle")], action: "Start/stop live voice mode (/live)" },
 				{

package/src/key-hint-format.d.ts

@@ -1,6 +1,6 @@
 /**
  * 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`,
+ * plus the theme symbol mirror, so addon-free CLI paths (`zetacode --version`,
  * help text in cli/command-help.ts) can format keys without loading
  * `@linxiraos/pi-natives` through the keybindings registry.
  */
@@ -23,6 +23,14 @@ export type KeyName = KeyId | ModifierName;
  * is capitalized. Other keys are capitalized (`f5` → `F5`).
  */
 export declare function formatKeyHint(key: KeyName): string;
+/**
+ * Format one key for a native tooltip (a TSP `title`): unicode keycap glyphs
+ * whatever the theme's symbol preset (`shift+tab` → `⇧⇥`), which Tern's
+ * tooltip splits into keycaps, and `esc` as Tern's own keycaps read. The nerd
+ * preset's icons are missing from Tern's UI font, and its spaced chords would
+ * not parse as keys.
+ */
+export declare function formatTooltipKey(key: KeyName): string;
 /** Format alternative keys as a slash-separated hint (`["f5", "alt+r"]` → `F5/⌥R`). */
 export declare function formatKeyHints(keys: KeyName | readonly KeyName[]): string;
 /** Format a double-tap gesture: `←←` with glyphs, `Left Left` with words. */

package/src/key-hint-format.ts

@@ -1,13 +1,13 @@
 /**
  * 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`,
+ * plus the theme symbol mirror, so addon-free CLI paths (`zetacode --version`,
  * help text in cli/command-help.ts) can format keys without loading
  * `@linxiraos/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";
+import { SYMBOL_PRESETS, type SymbolKey } from "./theme/symbols";
 
 /**
  * Key hint formatting: every key shown to the user renders through
@@ -69,9 +69,8 @@ const KEY_WORDS: Record<string, string | undefined> = {
 	insert: "Ins",
 };
 
-function keySymbol(key: SymbolKey): string {
-	return activeThemeSymbol(key);
-}
+/** Where a key's glyphs come from: the active theme, or a fixed preset. */
+type KeySymbols = (key: SymbolKey) => string;
 
 const HAS_LETTER = /[A-Za-z0-9]/;
 
@@ -89,6 +88,22 @@ export type KeyName = KeyId | ModifierName;
  * is capitalized. Other keys are capitalized (`f5` → `F5`).
  */
 export function formatKeyHint(key: KeyName): string {
+	return formatKey(key, activeThemeSymbol);
+}
+
+/**
+ * Format one key for a native tooltip (a TSP `title`): unicode keycap glyphs
+ * whatever the theme's symbol preset (`shift+tab` → `⇧⇥`), which Tern's
+ * tooltip splits into keycaps, and `esc` as Tern's own keycaps read. The nerd
+ * preset's icons are missing from Tern's UI font, and its spaced chords would
+ * not parse as keys.
+ */
+export function formatTooltipKey(key: KeyName): string {
+	return key === "escape" ? "esc" : formatKey(key, symbol => SYMBOL_PRESETS.unicode[symbol]);
+}
+
+/** {@link formatKeyHint} with glyphs from `symbol`. */
+function formatKey(key: KeyName, symbol: KeySymbols): 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("+");
@@ -96,14 +111,14 @@ export function formatKeyHint(key: KeyName): string {
 	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 label = symbol(MODIFIER_SYMBOLS[modifier]![mac ? 1 : 0]);
+		out += HAS_LETTER.test(label) ? `${label}+` : label + symbol("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);
+	const glyph = KEY_SYMBOLS[lower];
+	if (modifier) out += symbol(modifier[mac ? 1 : 0]);
+	else if (glyph !== undefined) out += symbol(glyph);
 	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);
@@ -118,5 +133,5 @@ export function formatKeyHints(keys: KeyName | readonly KeyName[]): string {
 /** 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}`;
+	return `${label}${HAS_LETTER.test(label) ? " " : activeThemeSymbol("key.joiner")}${label}`;
 }

package/src/keybinding-matchers.d.ts

@@ -1,3 +1,4 @@
+import type { KeyId } from "./app-keybindings";
 /**
  * Match the coding-agent interrupt key.
  *
@@ -18,6 +19,8 @@ export declare function matchesSelectDown(data: string): boolean;
 export declare function matchesSelectPageUp(data: string): boolean;
 /** Match the generic selector page-down keybinding. */
 export declare function matchesSelectPageDown(data: string): boolean;
+/** Effective external-editor key: the first bound key, or Ctrl+G when unbound. */
+export declare function appExternalEditorKey(): KeyId;
 /** Match the external-editor keybinding, falling back to Ctrl+G when unbound. */
 export declare function matchesAppExternalEditor(data: string): boolean;
 /**