@wierdbytes/pi-facelift 0.1.1 → 0.3.1

package/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+## 0.3.1
+
+- **Fix**: `read` bodies rendered as plain uncolored text whenever
+  pi's `settings.theme` was a name Shiki doesn't ship (e.g.
+  `tokyo-night-storm`). pi-facelift forwarded the raw value to
+  Shiki's `codeToANSI`, which threw, and `hlBlock`'s `catch` block
+  silently fell back to plain `code.split("\n")` — leaving frame
+  chrome and line numbers but no syntax highlighting.
+  Three changes land together:
+  1. The resolved theme is now validated against Shiki's
+     `bundledThemes` set; unknown names fall back to
+     `DEFAULT_THEME` (`github-dark`) instead of being passed through.
+  2. Common pi/host theme aliases are mapped to their nearest Shiki
+     bundled equivalent (`tokyo-night-storm` → `tokyo-night`,
+     `catppuccin` → `catppuccin-mocha`, `material-darker` →
+     `material-theme-darker`, `gruvbox-dark` → `gruvbox-dark-medium`,
+     `solarized` → `solarized-dark`, `one-dark` → `one-dark-pro`,
+     and Tokyo Night/Material/Catppuccin variants). Lookup is
+     case-insensitive.
+  3. The `hlBlock` catch now logs once per `(theme, language)` to
+     stderr (instead of swallowing every error forever) so future
+     regressions in the highlighter pipeline surface during dev.
+  A one-shot `console.error` is also emitted the first time an
+  unknown theme name is rejected, advertising `FACELIFT_THEME` as the
+  override knob.
+
+## 0.3.0
+
+- Frame primitives (open-right rounded box for `read` / `bash` / `ls` /
+  `find` / `grep`) extracted to `@wierdbytes/pi-common/tool-frame`.
+  pi-facelift now consumes them as a library so the same chrome can be
+  reused by other extensions (e.g. `@wierdbytes/pi-web`).
+- Status border colours now follow host theme tokens (`success` →
+  `theme.fg("success", …)`, pending → `warning`, error → `error`)
+  instead of pi-facelift's previous fixed RGB palette. Visual contract
+  is unchanged on the default pi theme; on custom themes the frame
+  inherits the user's palette.
+- `formatDuration` (the bash bottom-label timer formatter) moved to
+  `@wierdbytes/pi-common/tool-frame` so other extensions can reuse it.
+  Behaviour unchanged.
+- **Fix**: the `read` tool's frame body silently went empty after the
+  Phase-2 refactor because `renderFileContent` still referenced the
+  deleted `bodyW()` helper, and the highlighter promise's
+  `.catch(() => {})` swallowed the resulting `ReferenceError`. The
+  width is now computed inline as `termW() - 1` and the catch logs to
+  stderr so future regressions in the highlighter pipeline are
+  visible. Same `console.error` treatment applied to the matching
+  `renderGrepResults` catch.

package/README.md

@@ -14,10 +14,19 @@ tool output.
 - **`bash`** — open-right frame with the duration + status pinned to the
   bottom border
 
-  Status color follows pi: **green** on success, **yellow** while still
-  running, **red** on non-zero / timeout / abort. The exit summary is
-  consistent across statuses (`✓ exit 0`, `✗ exit N`, `⚡ timed out`,
-  `⚡ aborted`). Duration is shown as `3.3s` / `1m3s` / `2h5m`.
+  Status colour follows the host theme tokens (`success` while finished,
+  `warning` while running, `error` on non-zero / timeout / abort) so the
+  chrome blends with whatever palette the user is running. The exit
+  summary is consistent across statuses (`✓ exit 0`, `✗ exit N`,
+  `⚡ timed out`, `⚡ aborted`). Duration is shown as `3.3s` / `1m3s` /
+  `2h5m`.
+
+  > Frame primitives (top/bottom borders, rail, multi-line title
+  > sub-tree) live in [`@wierdbytes/pi-common/tool-frame`][cf] and are
+  > shared with `@wierdbytes/pi-web` so every tool that opts into
+  > `renderShell: "self"` looks the same.
+
+  [cf]: ../common/README.md#tool-frame
 - **`ls`** — Nerd Font file icons + tree-oriented rendering.
 - **`find` / `grep`** — grouped / highlighted rendering on top of pi's
   built-in tool implementations (no extra search backend, no extra

package/image-rendering.test.ts

@@ -30,6 +30,15 @@ class MockText {
 	}
 }
 
+// Minimal duck-typed theme: the new shared frame helpers in
+// `@wierdbytes/pi-common/tool-frame` invoke `theme.fg(token, str)` to colour
+// the chrome, so the empty-object placeholder this test used previously no
+// longer suffices. Pass-through `fg` keeps assertions focused on structure.
+const mockTheme = {
+	fg: (_key: string, text: string) => text,
+	bold: (text: string) => text,
+};
+
 function mockToolFactory(exec: any) {
 	return (_cwd: string) => ({
 		name: "mock",
@@ -136,7 +145,7 @@ describe("image rendering terminal detection", () => {
 		}));
 
 		const result = await readTool.execute("t1", { path: "media/inline-image.png" }, null, null, {});
-		const rendered = readTool.renderResult(result, {}, {}, {
+		const rendered = readTool.renderResult(result, {}, mockTheme, {
 			lastComponent: new MockText(),
 			isError: false,
 			state: {},

package/index.ts

@@ -40,8 +40,22 @@ import type {
 	ReadToolInput,
 	ToolRenderResultOptions,
 } from "@earendil-works/pi-coding-agent";
+import type { Theme } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import { codeToANSI } from "@shikijs/cli";
+import { bundledThemes } from "shiki";
+import {
+	formatDuration,
+	frameBodyLines,
+	frameBottom,
+	frameBottomWithLabel,
+	frameResult,
+	frameResultWithBottomLabel,
+	frameTop,
+	getFrameStatus,
+	renderToolError,
+	type FrameStatus,
+} from "@wierdbytes/pi-common/tool-frame";
 import type { BundledLanguage, BundledTheme } from "shiki";
 
 // ---------------------------------------------------------------------------
@@ -50,12 +64,83 @@ import type { BundledLanguage, BundledTheme } from "shiki";
 
 const DEFAULT_THEME: BundledTheme = "github-dark";
 
+/**
+ * Aliases that map common pi/host theme names (or popular external
+ * themes that aren't bundled with Shiki) to their closest Shiki
+ * `BundledTheme` equivalent.
+ *
+ * Keys are lowercased; values must be valid `BundledTheme` keys.
+ * The full Shiki theme list lives at https://shiki.style/themes.
+ *
+ * Why this exists: pi's `settings.theme` is consumed by the host UI
+ * and may use names Shiki doesn't ship (e.g. `tokyo-night-storm`).
+ * Without aliasing, `codeToANSI` throws and `hlBlock` silently falls
+ * back to plain text — leaving every `read` body uncolored.
+ */
+const THEME_ALIASES: Record<string, BundledTheme> = {
+	// Tokyo Night family (storm/night/day are Tokyo Night palette variants;
+	// Shiki only ships the storm-equivalent under the bare `tokyo-night` name).
+	"tokyo-night-storm": "tokyo-night",
+	"tokyo-night-night": "tokyo-night",
+	"tokyo-night-day": "tokyo-night",
+	tokyonight: "tokyo-night",
+	"tokyonight-storm": "tokyo-night",
+	"tokyonight-night": "tokyo-night",
+	"tokyonight-day": "tokyo-night",
+	// Catppuccin (default → mocha, the most common dark variant)
+	catppuccin: "catppuccin-mocha",
+	// Dracula
+	"dracula-pro": "dracula",
+	// Material
+	material: "material-theme",
+	"material-darker": "material-theme-darker",
+	"material-lighter": "material-theme-lighter",
+	"material-ocean": "material-theme-ocean",
+	"material-palenight": "material-theme-palenight",
+	// Gruvbox (medium contrast is the canonical default)
+	"gruvbox-dark": "gruvbox-dark-medium",
+	"gruvbox-light": "gruvbox-light-medium",
+	// Solarized (default → dark)
+	solarized: "solarized-dark",
+	// One Dark
+	"one-dark": "one-dark-pro",
+	onedark: "one-dark-pro",
+};
+
+const _themeWarningShown = new Set<string>();
+
+function isBundledTheme(name: string): name is BundledTheme {
+	return Object.prototype.hasOwnProperty.call(bundledThemes, name);
+}
+
+function warnInvalidTheme(rawName: string, fallback: BundledTheme): void {
+	if (_themeWarningShown.has(rawName)) return;
+	_themeWarningShown.add(rawName);
+	console.error(
+		`pi-facelift: theme "${rawName}" is not a Shiki bundled theme; ` +
+			`falling back to "${fallback}". ` +
+			`Set FACELIFT_THEME to one of: ${Object.keys(bundledThemes).sort().join(", ")}.`,
+	);
+}
+
+/** Resolve a raw theme name to a valid `BundledTheme`, applying aliases. */
+function resolveBundledTheme(rawName: string | undefined): BundledTheme {
+	if (!rawName) return DEFAULT_THEME;
+	const trimmed = rawName.trim();
+	if (!trimmed) return DEFAULT_THEME;
+	if (isBundledTheme(trimmed)) return trimmed;
+	const aliased = THEME_ALIASES[trimmed.toLowerCase()];
+	if (aliased) return aliased;
+	warnInvalidTheme(trimmed, DEFAULT_THEME);
+	return DEFAULT_THEME;
+}
+
 function getDefaultAgentDir(): string | undefined {
 	const home = process.env.HOME ?? "";
 	return home ? join(home, ".pi/agent") : undefined;
 }
 
-function readThemeFromSettings(agentDir?: string): BundledTheme | undefined {
+function readThemeFromSettings(agentDir?: string): string | undefined {
 	const resolvedAgentDir = agentDir ?? getDefaultAgentDir();
 	if (!resolvedAgentDir) return undefined;
 
@@ -63,27 +148,34 @@ function readThemeFromSettings(agentDir?: string): BundledTheme | undefined {
 		const settings = JSON.parse(readFileSync(join(resolvedAgentDir, "settings.json"), "utf8")) as {
 			theme?: unknown;
 		};
-		return typeof settings.theme === "string" ? (settings.theme as BundledTheme) : undefined;
+		return typeof settings.theme === "string" ? settings.theme : undefined;
 	} catch {
 		return undefined;
 	}
 }
 
 function resolvePrettyTheme(agentDir?: string): BundledTheme {
-	return (
-		(process.env.FACELIFT_THEME as BundledTheme | undefined) ??
-		readThemeFromSettings(agentDir) ??
-		DEFAULT_THEME
-	);
+	const raw = process.env.FACELIFT_THEME ?? readThemeFromSettings(agentDir);
+	return resolveBundledTheme(raw);
 }
 
 let THEME: BundledTheme = resolvePrettyTheme();
 
+/** Test-only hooks for theme resolution (alias map, bundled validation, fallback warning). */
+export const __themeInternals = {
+	DEFAULT_THEME,
+	THEME_ALIASES,
+	isBundledTheme,
+	resolveBundledTheme,
+	resetWarningsForTests: () => _themeWarningShown.clear(),
+};
+
 function setPrettyTheme(agentDir?: string): void {
 	const resolvedTheme = resolvePrettyTheme(agentDir);
 	if (resolvedTheme === THEME) return;
 	THEME = resolvedTheme;
 	_cache.clear();
+	_hlErrorLogged.clear();
 	codeToANSI("", "typescript", THEME).catch(() => {});
 }
 
@@ -149,10 +241,6 @@ function resolveBaseBackground(theme: BgTheme | null | undefined): void {
 	RST = `\x1b[0m${BG_BASE}`;
 }
 
-function renderToolError(error: string, theme: FgTheme): string {
-	return frameResult(theme.fg("error", error), "error");
-}
-
 const ESC_RE = "\u001b";
 const ANSI_CAPTURE_RE = new RegExp(`${ESC_RE}\\[([0-9;]*)m`, "g");
 
@@ -207,229 +295,11 @@ function lnum(n: number, w: number): string {
 }
 
 // ---------------------------------------------------------------------------
-// Frame — open-right rounded box for tool output.
-//
-// Replaces pi core's `toolSuccessBg` fill (the green left rail in the
-// default tool shell) with a status-aware single-line frame that reads
-// the same way as the settings modal in pi-wierd-stuff
-// (`packages/common/settings/frame.ts`), but with the right side left
-// open so long lines fade out naturally:
-//
-//     ╭── read /some/file.ext ─────
-//     │   12 lines
-//     │ 535 │ const x = 1;
-//     │ 536 │ const y = 2;
-//     ╰─────────────────────────
-//
-// Tools opt in by setting `renderShell: "self"` on their definition,
-// which tells pi core to skip the colored Box wrapper and let the tool
-// draw its own framing.
+// Frame helpers now live in `@wierdbytes/pi-common/tool-frame`. Status
+// border colours follow host theme tokens (`success` / `warning` /
+// `error`) instead of the previous fixed RGB palette.
 // ---------------------------------------------------------------------------
 
-type FrameStatus = "pending" | "success" | "error";
-
-function getFrameStatus(ctx: { isError?: boolean; isPartial?: boolean }): FrameStatus {
-	if (ctx.isError) return "error";
-	if (ctx.isPartial) return "pending";
-	return "success";
-}
-
-function getFrameColor(status: FrameStatus): string {
-	switch (status) {
-		case "error":
-			return FG_RED;
-		case "pending":
-			return FG_YELLOW;
-		default:
-			return FG_GREEN;
-	}
-}
-
-/** Inner content width — terminal width minus the `│` left rail (1 col). */
-function bodyW(): number {
-	return Math.max(1, termW() - 1);
-}
-
-/**
- * Find the visible column of the first space character in an ANSI-formatted
- * string, ignoring ANSI escape sequences. Returns -1 if no space is found
- * before a newline (or end of string).
- *
- * Used by `frameTop` to align continuation rows under the first argument of
- * the tool title (e.g., the column where `cd` starts in `bash cd …`).
- */
-function firstVisibleSpace(s: string): number {
-	let visiblePos = 0;
-	let i = 0;
-	while (i < s.length) {
-		const ch = s[i];
-		if (ch === "\x1b") {
-			const next = s[i + 1];
-			if (next === "[") {
-				const end = s.indexOf("m", i + 2);
-				if (end < 0) return -1;
-				i = end + 1;
-				continue;
-			}
-			// Unknown escape — bail out
-			return -1;
-		}
-		if (ch === "\n") return -1;
-		if (ch === " ") return visiblePos;
-		visiblePos += 1;
-		i += 1;
-	}
-	return -1;
-}
-
-/**
- * Render the top border of the frame: `╭── <title> ─────`.
- * The title may contain ANSI codes; visible width is measured with pi-tui.
- * Truncated with `…` if it would overflow the terminal width.
- *
- * Multi-line titles (e.g., a multi-line bash command) are rendered with the
- * first line as the top border and remaining lines as rail-prefixed
- * continuation rows in a sub-tree:
- *
- *     ╭── bash cd /…/pi-wierd-stuff && \ ──────────────
- *     │      │ echo "line 1" \
- *     │      ╚ echo "line 2"
- *
- * Each continuation row is composed of:
- *   • the outer frame rail `│` (frame status color)
- *   • padding sized so the sub-tree connector lines up with the first arg
- *     character of the first row
- *   • a sub-tree connector (`│` for non-last rows, `╰` for the last)
- *   • a single separator space
- *   • the row's content (callers are expected to wrap each line in the
- *     same color as the first-row args so the sub-tree text matches)
- *
- * Trailing dashes are only emitted on the first row so continuation rows
- * stay clean.
- */
-function frameTop(titleAnsi: string, status: FrameStatus): string {
-	const color = getFrameColor(status);
-	const w = termW();
-	const titleLines = titleAnsi.split("\n");
-	const firstTitle = titleLines[0];
-	const continuations = titleLines.slice(1);
-
-	// Layout: `╭` (1) + `──` (2) + ` ` (1) + title + ` ` (1) + trailing dashes (≥1)
-	const minTrailing = 1;
-	const fixed = 1 + 2 + 1 + 1 + minTrailing;
-	const maxTitleW = Math.max(0, w - fixed);
-
-	let title = firstTitle;
-	let tw = visibleWidth(firstTitle);
-	if (tw > maxTitleW) {
-		title = truncateToWidth(firstTitle, maxTitleW, "…");
-		tw = visibleWidth(title);
-	}
-	const trailing = Math.max(minTrailing, w - 1 - 2 - 1 - tw - 1);
-	const firstLine = `${color}╭──${RST} ${title} ${color}${"─".repeat(trailing)}${RST}`;
-
-	if (continuations.length === 0) return firstLine;
-
-	// Continuation rows: rail + padding + sub-tree connector + space + content.
-	// First line layout:
-	//   col 1: `╭`
-	//   cols 2-3: `──`
-	//   col 4: literal space
-	//   cols 5..: title (toolName + space + args…)
-	// If the toolName ends at visible-offset N (i.e., the space is at offset N),
-	// the first arg char sits at column N + 6 (1-indexed). We align the sub-tree
-	// connector two columns before it (at contentCol - 2) and put the content
-	// itself at the same column as the first row's first arg char, so the rows
-	// read as a tree hanging off the title.
-	const toolNameEnd = firstVisibleSpace(firstTitle);
-	const contentCol = toolNameEnd >= 0 ? toolNameEnd + 6 : 6;
-	const padBetween = " ".repeat(Math.max(0, contentCol - 4));
-	const rail = `${color}│${RST}`;
-	const innerW = Math.max(1, w - contentCol + 1);
-	const lastIdx = continuations.length - 1;
-
-	const contLines = continuations.map((line, idx) => {
-		const connectorChar = idx === lastIdx ? "╰" : "│";
-		const connector = `${color}${connectorChar}${RST}`;
-		const fitted = visibleWidth(line) > innerW ? truncateToWidth(line, innerW, "…") : line;
-		return `${rail}${padBetween}${connector} ${fitted}`;
-	});
-
-	return [firstLine, ...contLines].join("\n");
-}
-
-/** Render the bottom border of the frame: `╰─────────────`. */
-function frameBottom(status: FrameStatus): string {
-	const color = getFrameColor(status);
-	const w = termW();
-	return `${color}╰${"─".repeat(Math.max(1, w - 1))}${RST}`;
-}
-
-/**
- * Render the bottom border with an inline label, mirroring `frameTop`:
- * `╰── <label> ──────`. Used by the bash renderer to keep the exit
- * summary attached to the frame instead of as the first body line.
- */
-function frameBottomWithLabel(labelAnsi: string, status: FrameStatus): string {
-	const color = getFrameColor(status);
-	const w = termW();
-	const minTrailing = 1;
-	const fixed = 1 + 2 + 1 + 1 + minTrailing;
-	const maxLabelW = Math.max(0, w - fixed);
-
-	let label = labelAnsi;
-	let lw = visibleWidth(labelAnsi);
-	if (lw > maxLabelW) {
-		label = truncateToWidth(labelAnsi, maxLabelW, "…");
-		lw = visibleWidth(label);
-	}
-	const trailing = Math.max(minTrailing, w - 1 - 2 - 1 - lw - 1);
-	return `${color}╰──${RST} ${label} ${color}${"─".repeat(trailing)}${RST}`;
-}
-
-/**
- * Prefix every line in `text` with the frame's left rail (`│`).
- * Each logical line is right-truncated to `bodyW()` so the visible width
- * including the rail never exceeds `termW()`.
- *
- * Embedded carriage returns (`\r`) are collapsed using terminal-style
- * overwrite semantics: only the content after the last `\r` on a line is
- * kept. Without this, sequences like `git rebase`'s
- * `Rebasing (1/1)\rSuccessfully rebased…` would clobber the rail when the
- * terminal honors `\r` as cursor-reset, leaving the line visibly
- * unprefixed.
- */
-function frameBodyLines(text: string, status: FrameStatus): string {
-	const color = getFrameColor(status);
-	const rail = `${color}│${RST}`;
-	const w = bodyW();
-	return text
-		.split("\n")
-		.map((line) => {
-			// Terminal-style \r handling: keep only what survives after the last
-			// carriage return so the rail isn't overwritten by progress messages.
-			const lastCR = line.lastIndexOf("\r");
-			const safeLine = lastCR >= 0 ? line.slice(lastCR + 1) : line;
-			const fitted = safeLine && visibleWidth(safeLine) > w ? truncateToWidth(safeLine, w, "") : safeLine;
-			return `${rail}${fitted}`;
-		})
-		.join("\n");
-}
-
-/** Wrap `body` as the result-side of the frame: rail-prefixed lines + bottom border.
- *  An empty `body` collapses to just the bottom border, mirroring
- *  `frameResultWithBottomLabel` so the frame doesn't show an empty rail row. */
-function frameResult(body: string, status: FrameStatus): string {
-	const body_ = body ? `${frameBodyLines(body, status)}\n` : "";
-	return `${body_}${frameBottom(status)}`;
-}
-
-/** Same as `frameResult` but embeds `label` inline in the bottom border. */
-function frameResultWithBottomLabel(body: string, labelAnsi: string, status: FrameStatus): string {
-	const body_ = body ? `${frameBodyLines(body, status)}\n` : "";
-	return `${body_}${frameBottomWithLabel(labelAnsi, status)}`;
-}
-
 // ---------------------------------------------------------------------------
 // Language detection
 // ---------------------------------------------------------------------------
@@ -644,21 +514,6 @@ export const __imageInternals = {
 	},
 };
 
-/**
- * Compact human-readable duration: `3.3s`, `1m3s`, `2h5m`.
- * Mirrors the style requested by the user for the bash bottom-border label.
- */
-function formatDuration(ms: number): string {
-	const totalSec = Math.max(0, ms) / 1000;
-	if (totalSec < 60) return `${totalSec.toFixed(1)}s`;
-	const totalMin = Math.floor(totalSec / 60);
-	const sec = Math.floor(totalSec % 60);
-	if (totalMin < 60) return sec > 0 ? `${totalMin}m${sec}s` : `${totalMin}m`;
-	const hours = Math.floor(totalMin / 60);
-	const min = totalMin % 60;
-	return min > 0 ? `${hours}h${min}m` : `${hours}h`;
-}
-
 /**
  * Get human-readable file size
  */
@@ -790,6 +645,7 @@ function dirIcon(): string {
 codeToANSI("", "typescript", THEME).catch(() => {});
 
 const _cache = new Map<string, string[]>();
+const _hlErrorLogged = new Set<string>();
 
 function _touch(k: string, v: string[]): string[] {
 	_cache.delete(k);
@@ -814,11 +670,30 @@ async function hlBlock(code: string, language: BundledLanguage | undefined): Pro
 		const ansi = normalizeShikiContrast(await codeToANSI(code, language, THEME));
 		const out = (ansi.endsWith("\n") ? ansi.slice(0, -1) : ansi).split("\n");
 		return _touch(k, out);
-	} catch {
+	} catch (err) {
+		// Log once per (theme, language) so silent regressions are visible
+		// during dev (e.g. an unsupported theme name slipping through, or a
+		// grammar load failure for a niche language) without spamming on
+		// every render. The plain-text fallback below keeps the body usable.
+		const tag = `${THEME}\0${language}`;
+		if (!_hlErrorLogged.has(tag)) {
+			_hlErrorLogged.add(tag);
+			const msg = err instanceof Error ? err.message : String(err);
+			console.error(
+				`pi-facelift: shiki highlighting failed for theme="${THEME}" language="${language}": ${msg}`,
+			);
+		}
 		return code.split("\n");
 	}
 }
 
+/** Test-only hooks for the Shiki highlighter pipeline. */
+export const __hlInternals = {
+	hlBlock,
+	resetErrorLogForTests: () => _hlErrorLogged.clear(),
+	resetCacheForTests: () => _cache.clear(),
+};
+
 // ---------------------------------------------------------------------------
 // Renderers
 // ---------------------------------------------------------------------------
@@ -837,8 +712,9 @@ async function renderFileContent(
 	const lg = lang(filePath);
 	const hl = await hlBlock(show.join("\n"), lg);
 
-	// Reserve 2 cols for the outer frame's `│ ` rail — rendered by frameBodyLines.
-	const tw = bodyW();
+	// Reserve 1 col for the outer frame's `│` rail (drawn later by
+	// `frameBodyLines`) so the highlighted lines fit inside the frame.
+	const tw = Math.max(1, termW() - 1);
 	const startLine = offset;
 	const endLine = startLine + show.length - 1;
 	const nw = Math.max(3, String(endLine).length);
@@ -995,6 +871,15 @@ type ToolResultLike<TDetails = unknown> = AgentToolResult<TDetails | undefined>;
 type TextComponentLike = { setText(value: string): void; getText?: () => string };
 type TextComponentCtor = new (text?: string, x?: number, y?: number) => TextComponentLike;
 type ThemeLike = BgTheme & FgTheme & { bold: (text: string) => string };
+
+/**
+ * Cast the loose `ThemeLike` (used by the duck-typed render hooks) to the
+ * real `Theme` class expected by the shared
+ * `@wierdbytes/pi-common/tool-frame` helpers. The helpers only call
+ * `theme.fg(token, str)`, which `ThemeLike` already provides, so the cast
+ * is structurally safe at runtime.
+ */
+const asTheme = (theme: ThemeLike): Theme => theme as unknown as Theme;
 type RenderContextLike<TState extends Record<string, unknown> = Record<string, unknown>> = {
 	lastComponent?: TextComponentLike;
 	state: TState;
@@ -1208,7 +1093,7 @@ export default function piFaceliftExtension(pi: PiFaceliftApi, deps?: PiFacelift
 			const offset = args.offset ? ` ${theme.fg("muted", `from line ${args.offset}`)}` : "";
 			const limit = args.limit ? ` ${theme.fg("muted", `(${args.limit} lines)`)}` : "";
 			const title = `${theme.fg("toolTitle", theme.bold("read"))} ${theme.fg("accent", sp(fp))}${offset}${limit}`;
-			text.setText(frameTop(title, getFrameStatus(ctx)));
+			text.setText(frameTop(title, getFrameStatus(ctx), asTheme(theme), termW()));
 			return text;
 		},
 
@@ -1221,9 +1106,11 @@ export default function piFaceliftExtension(pi: PiFaceliftApi, deps?: PiFacelift
 			resolveBaseBackground(theme);
 			const text = ctx.lastComponent ?? new TextComponent("", 0, 0);
 			const status = getFrameStatus(ctx);
+			const t = asTheme(theme);
+			const w = termW();
 
 			if (ctx.isError) {
-				text.setText(renderToolError(getTextContent(result) || "Error", theme));
+				text.setText(renderToolError(getTextContent(result) || "Error", t, w));
 				return text;
 			}
 
@@ -1237,35 +1124,41 @@ export default function piFaceliftExtension(pi: PiFaceliftApi, deps?: PiFacelift
 				const sizeStr = humanSize(byteSize);
 				const mimeStr = d.mimeType ?? "image";
 
-				text.setText(frameResult(`${fileIcon(d.filePath)}${FG_DIM}${mimeStr} · ${sizeStr}${RST}`, status));
+				text.setText(frameResult(`${fileIcon(d.filePath)}${FG_DIM}${mimeStr} · ${sizeStr}${RST}`, status, t, w));
 				return text;
 			}
 
 			if (d?._type === "readFile" && d.content) {
-				const key = `read:${d.filePath}:${d.offset}:${d.lineCount}:${termW()}:${status}`;
+				const key = `read:${d.filePath}:${d.offset}:${d.lineCount}:${w}:${status}`;
 				if (ctx.state._rk !== key) {
 					ctx.state._rk = key;
 					// Initial render: just the frame chrome until shiki resolves.
 					// Once `renderFileContent` returns we re-cache with the highlighted body.
-					ctx.state._rt = frameResult("", status);
+					ctx.state._rt = frameResult("", status, t, w);
 
 					const maxShow = ctx.expanded ? d.lineCount : MAX_PREVIEW_LINES;
 					renderFileContent(d.content, d.filePath, d.offset, maxShow)
 						.then((rendered: string) => {
 							if (ctx.state._rk !== key) return;
-							ctx.state._rt = frameResult(rendered, status);
+							ctx.state._rt = frameResult(rendered, status, t, w);
 							ctx.invalidate();
 						})
-						.catch(() => {});
+						.catch((err: unknown) => {
+							// Surface to stderr so silent regressions in the highlighter
+							// (e.g. a stale helper reference) are visible during dev
+							// instead of producing an empty-body frame.
+							const msg = err instanceof Error ? err.message : String(err);
+							console.error(`pi-facelift: read render failed: ${msg}`);
+						});
 				}
-				text.setText(ctx.state._rt ?? frameResult("", status));
+				text.setText(ctx.state._rt ?? frameResult("", status, t, w));
 				return text;
 			}
 
 			// Fallback
 			const fallback = result.content?.[0];
 			const fallbackText = fallback && isTextContent(fallback) ? fallback.text : "read";
-			text.setText(frameResult(theme.fg("dim", String(fallbackText).slice(0, 120)), status));
+			text.setText(frameResult(theme.fg("dim", String(fallbackText).slice(0, 120)), status, t, w));
 			return text;
 		},
 	});
@@ -1334,7 +1227,7 @@ export default function piFaceliftExtension(pi: PiFaceliftApi, deps?: PiFacelift
 				const restCmd = cmdLines.slice(1).map((line) => line.replace(/^\s+/, ""));
 				const firstTitle = `${theme.fg("toolTitle", theme.bold("bash"))} ${theme.fg("accent", firstCmd)}${timeout}`;
 				const title = [firstTitle, ...restCmd.map((line) => theme.fg("accent", line))].join("\n");
-				t.setText(frameTop(title, getFrameStatus(ctx)));
+				t.setText(frameTop(title, getFrameStatus(ctx), asTheme(theme), termW()));
 				return t;
 			},
 
@@ -1347,6 +1240,8 @@ export default function piFaceliftExtension(pi: PiFaceliftApi, deps?: PiFacelift
 				resolveBaseBackground(theme);
 				const t = ctx.lastComponent ?? new TextComponent("", 0, 0);
 				const status = getFrameStatus(ctx);
+				const frameTheme = asTheme(theme);
+				const frameWidth = termW();
 				const state = ctx.state;
 
 				// Live timer: tick every second while still streaming, freeze on final/error.
@@ -1413,9 +1308,9 @@ export default function piFaceliftExtension(pi: PiFaceliftApi, deps?: PiFacelift
 				const body = out.join("\n");
 
 				if (label) {
-					t.setText(frameResultWithBottomLabel(body, label, status));
+					t.setText(frameResultWithBottomLabel(body, label, status, frameTheme, frameWidth));
 				} else {
-					t.setText(frameResult(body, status));
+					t.setText(frameResult(body, status, frameTheme, frameWidth));
 				}
 				return t;
 			},
@@ -1461,7 +1356,7 @@ export default function piFaceliftExtension(pi: PiFaceliftApi, deps?: PiFacelift
 				const fp = args.path ?? ".";
 				const text = ctx.lastComponent ?? new TextComponent("", 0, 0);
 				const title = `${theme.fg("toolTitle", theme.bold("ls"))} ${theme.fg("accent", sp(fp))}`;
-				text.setText(frameTop(title, getFrameStatus(ctx)));
+				text.setText(frameTop(title, getFrameStatus(ctx), asTheme(theme), termW()));
 				return text;
 			},
 
@@ -1469,9 +1364,11 @@ export default function piFaceliftExtension(pi: PiFaceliftApi, deps?: PiFacelift
 				resolveBaseBackground(theme);
 				const text = ctx.lastComponent ?? new TextComponent("", 0, 0);
 				const status = getFrameStatus(ctx);
+				const t = asTheme(theme);
+				const w = termW();
 
 				if (ctx.isError) {
-					text.setText(renderToolError(getTextContent(result) || "Error", theme));
+					text.setText(renderToolError(getTextContent(result) || "Error", t, w));
 					return text;
 				}
 
@@ -1479,13 +1376,13 @@ export default function piFaceliftExtension(pi: PiFaceliftApi, deps?: PiFacelift
 				if (d?._type === "lsResult" && d.text) {
 					const tree = renderTree(d.text, d.path);
 					const info = `${FG_DIM}${d.entryCount} entries${RST}`;
-					text.setText(frameResultWithBottomLabel(tree, info, status));
+					text.setText(frameResultWithBottomLabel(tree, info, status, t, w));
 					return text;
 				}
 
 				const fallback = result.content?.[0];
 				const fallbackText = fallback && isTextContent(fallback) ? fallback.text : "listed";
-				text.setText(frameResult(theme.fg("dim", String(fallbackText).slice(0, 120)), status));
+				text.setText(frameResult(theme.fg("dim", String(fallbackText).slice(0, 120)), status, t, w));
 				return text;
 			},
 		});
@@ -1530,7 +1427,7 @@ export default function piFaceliftExtension(pi: PiFaceliftApi, deps?: PiFacelift
 				const path = args.path ? ` ${theme.fg("muted", `in ${sp(args.path)}`)}` : "";
 				const text = ctx.lastComponent ?? new TextComponent("", 0, 0);
 				const title = `${theme.fg("toolTitle", theme.bold("find"))} ${theme.fg("accent", pattern)}${path}`;
-				text.setText(frameTop(title, getFrameStatus(ctx)));
+				text.setText(frameTop(title, getFrameStatus(ctx), asTheme(theme), termW()));
 				return text;
 			},
 
@@ -1543,9 +1440,11 @@ export default function piFaceliftExtension(pi: PiFaceliftApi, deps?: PiFacelift
 				resolveBaseBackground(theme);
 				const text = ctx.lastComponent ?? new TextComponent("", 0, 0);
 				const status = getFrameStatus(ctx);
+				const t = asTheme(theme);
+				const w = termW();
 
 				if (ctx.isError) {
-					text.setText(renderToolError(getTextContent(result) || "Error", theme));
+					text.setText(renderToolError(getTextContent(result) || "Error", t, w));
 					return text;
 				}
 
@@ -1553,13 +1452,13 @@ export default function piFaceliftExtension(pi: PiFaceliftApi, deps?: PiFacelift
 				if (d?._type === "findResult" && d.text) {
 					const rendered = renderFindResults(d.text);
 					const info = `${FG_DIM}${d.matchCount} files${RST}`;
-					text.setText(frameResultWithBottomLabel(rendered, info, status));
+					text.setText(frameResultWithBottomLabel(rendered, info, status, t, w));
 					return text;
 				}
 
 				const fallback = result.content?.[0];
 				const fallbackText = fallback && isTextContent(fallback) ? fallback.text : "found";
-				text.setText(frameResult(theme.fg("dim", String(fallbackText).slice(0, 120)), status));
+				text.setText(frameResult(theme.fg("dim", String(fallbackText).slice(0, 120)), status, t, w));
 				return text;
 			},
 		});
@@ -1615,7 +1514,7 @@ export default function piFaceliftExtension(pi: PiFaceliftApi, deps?: PiFacelift
 				const glob = args.glob ? ` ${theme.fg("muted", `(${args.glob})`)}` : "";
 				const text = ctx.lastComponent ?? new TextComponent("", 0, 0);
 				const title = `${theme.fg("toolTitle", theme.bold("grep"))} ${theme.fg("accent", pattern)}${path}${glob}`;
-				text.setText(frameTop(title, getFrameStatus(ctx)));
+				text.setText(frameTop(title, getFrameStatus(ctx), asTheme(theme), termW()));
 				return text;
 			},
 
@@ -1628,37 +1527,42 @@ export default function piFaceliftExtension(pi: PiFaceliftApi, deps?: PiFacelift
 				resolveBaseBackground(theme);
 				const text = ctx.lastComponent ?? new TextComponent("", 0, 0);
 				const status = getFrameStatus(ctx);
+				const t = asTheme(theme);
+				const w = termW();
 
 				if (ctx.isError) {
-					text.setText(renderToolError(getTextContent(result) || "Error", theme));
+					text.setText(renderToolError(getTextContent(result) || "Error", t, w));
 					return text;
 				}
 
 				const d = result.details;
 				if (d?._type === "grepResult" && d.text) {
-					const key = `grep:${d.pattern}:${d.matchCount}:${termW()}:${status}`;
+					const key = `grep:${d.pattern}:${d.matchCount}:${w}:${status}`;
 					if (ctx.state._gk !== key) {
 						ctx.state._gk = key;
 						const info = `${FG_DIM}${d.matchCount} matches${RST}`;
-						ctx.state._gt = frameResultWithBottomLabel("", info, status);
+						ctx.state._gt = frameResultWithBottomLabel("", info, status, t, w);
 
 						renderGrepResults(d.text, d.pattern)
 							.then((rendered: string) => {
 								if (ctx.state._gk !== key) return;
-								ctx.state._gt = frameResultWithBottomLabel(rendered, info, status);
+								ctx.state._gt = frameResultWithBottomLabel(rendered, info, status, t, w);
 								ctx.invalidate();
 							})
-							.catch(() => {});
+							.catch((err: unknown) => {
+								const msg = err instanceof Error ? err.message : String(err);
+								console.error(`pi-facelift: grep render failed: ${msg}`);
+							});
 					}
 					text.setText(
-						ctx.state._gt ?? frameResultWithBottomLabel("", `${FG_DIM}${d.matchCount} matches${RST}`, status),
+						ctx.state._gt ?? frameResultWithBottomLabel("", `${FG_DIM}${d.matchCount} matches${RST}`, status, t, w),
 					);
 					return text;
 				}
 
 				const fallback = result.content?.[0];
 				const fallbackText = fallback && isTextContent(fallback) ? fallback.text : "searched";
-				text.setText(frameResult(theme.fg("dim", String(fallbackText).slice(0, 120)), status));
+				text.setText(frameResult(theme.fg("dim", String(fallbackText).slice(0, 120)), status, t, w));
 				return text;
 			},
 		});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wierdbytes/pi-facelift",
-  "version": "0.1.1",
+  "version": "0.3.1",
   "description": "Cosmetic facelift for built-in pi tool output — open-right rounded frames, syntax-highlighted reads, status-aware bash summaries, find/grep.",
   "type": "module",
   "files": [
@@ -52,7 +52,8 @@
     "demo": "bun scripts/demo.ts"
   },
   "dependencies": {
-    "@shikijs/cli": "^4.0.2"
+    "@shikijs/cli": "^4.0.2",
+    "@wierdbytes/pi-common": "^0.3.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": ">=0.74.0",

package/read-rendering.test.ts

@@ -0,0 +1,209 @@
+/**
+ * Regression tests for the `read` tool's body rendering.
+ *
+ * History: a previous refactor stranded a `bodyW()` reference inside
+ * `renderFileContent` after the helper itself was deleted. The
+ * resulting `ReferenceError` was swallowed by `.catch(() => {})` on
+ * the shiki promise, leaving every `read` result with a top + bottom
+ * border but no body lines at all. These tests force the async
+ * highlighter to run and assert that the body actually populates.
+ */
+
+import { describe, expect, it } from "vitest";
+
+import piFaceliftExtension from "./index.ts";
+
+class MockText {
+	private text = "";
+	constructor(_text = "", _x = 0, _y = 0) {}
+	setText(value: string) {
+		this.text = value;
+	}
+	getText() {
+		return this.text;
+	}
+}
+
+const mockTheme = {
+	fg: (_key: string, text: string) => text,
+	bold: (text: string) => text,
+};
+
+function mockToolFactory(exec: any) {
+	return (_cwd: string) => ({
+		name: "mock",
+		description: "mock",
+		parameters: { type: "object", properties: {} },
+		execute: exec,
+	});
+}
+
+/**
+ * Pin `process.stdout.columns` for the lifetime of `fn`, including
+ * across `await` boundaries. The naive sync `try/finally` version
+ * restores the descriptor immediately when `fn` returns its promise,
+ * so any code that runs after the first `await` sees the *original*
+ * width — enough to flip a width-keyed cache (`_rk`) and force a
+ * shiki re-run, which clobbers the populated `_rt` we waited for.
+ */
+async function withStdoutColumns<T>(
+	columns: number,
+	fn: () => T | Promise<T>,
+): Promise<T> {
+	const descriptor = Object.getOwnPropertyDescriptor(process.stdout, "columns");
+	Object.defineProperty(process.stdout, "columns", {
+		configurable: true,
+		value: columns,
+	});
+	try {
+		return await fn();
+	} finally {
+		if (descriptor)
+			Object.defineProperty(process.stdout, "columns", descriptor);
+		else
+			delete (process.stdout as NodeJS.WriteStream & { columns?: number })
+				.columns;
+	}
+}
+
+function loadReadTool(readExec: any) {
+	const noopExec = async () => ({ content: [{ type: "text", text: "" }] });
+	const tools = new Map<string, any>();
+	const pi = {
+		registerTool: (tool: any) => tools.set(tool.name, tool),
+		registerCommand: () => {},
+		on: () => {},
+	};
+
+	piFaceliftExtension(pi, {
+		sdk: {
+			createReadToolDefinition: mockToolFactory(readExec),
+			createBashToolDefinition: mockToolFactory(noopExec),
+			createLsToolDefinition: mockToolFactory(noopExec),
+			createFindToolDefinition: mockToolFactory(noopExec),
+			createGrepToolDefinition: mockToolFactory(noopExec),
+			getAgentDir: () => "/tmp/pi-facelift-test",
+		},
+		TextComponent: MockText,
+	});
+
+	return tools.get("read");
+}
+
+const stripAnsi = (s: string): string => s.replace(/\x1b\[[0-9;]*m/g, "");
+
+/**
+ * Wait until `state._rt` is populated by shiki's async render. Shiki's
+ * first call cold-starts the highlighter (registers the language
+ * grammar, etc.) which can take a few hundred ms in CI; we poll up to
+ * a few seconds before giving up so the test still fails fast on a
+ * real regression.
+ */
+/**
+ * Wait until `state._rt` is populated by shiki's async render. Shiki's
+ * first call cold-starts the highlighter (registers the language
+ * grammar, etc.) which can take a few hundred ms in CI; we poll up to
+ * a few seconds before giving up so the test still fails fast on a
+ * real regression.
+ */
+async function waitForCachedBody(state: { _rt?: string }): Promise<void> {
+	const deadline = Date.now() + 3000;
+	while (Date.now() < deadline) {
+		await new Promise((r) => setTimeout(r, 25));
+		if (state._rt && state._rt.split("\n").length > 1) return;
+	}
+}
+
+describe("read renderResult body", () => {
+	it("populates the frame body with file contents (regression: bodyW reference)", async () => {
+		const fileContent = [
+			"line one",
+			"line two",
+			"line three",
+			"line four",
+			"line five",
+		].join("\n");
+
+		const readTool = loadReadTool(async () => ({
+			content: [{ type: "text", text: fileContent }],
+		}));
+
+		// First, run execute() so the result has the expected `details`
+		// payload that renderResult dispatches on.
+		const result = await readTool.execute(
+			"t1",
+			{ path: "fixtures/sample.txt" },
+			null,
+			null,
+			{},
+		);
+
+		await withStdoutColumns(80, async () => {
+			let invalidated = 0;
+			const ctx: any = {
+				lastComponent: new MockText(),
+				isError: false,
+				isPartial: false,
+				state: {},
+				expanded: false,
+				invalidate: () => {
+					invalidated += 1;
+				},
+			};
+
+			// First render: kicks off shiki, sets the cached `_rt` to an
+			// empty-body frame. The async pipeline then populates `_rt`.
+			const rendered = readTool.renderResult(result, {}, mockTheme, ctx);
+			expect(rendered.getText()).toMatch(/^╰─+$/m); // bottom border present
+
+			await waitForCachedBody(ctx.state);
+
+			// After the highlighter resolves, `ctx.invalidate` should have
+			// fired so pi-tui re-invokes the renderer. Simulate that.
+			expect(invalidated).toBeGreaterThanOrEqual(1);
+			const rendered2 = readTool.renderResult(result, {}, mockTheme, ctx);
+			const lines = rendered2.getText().split("\n");
+
+			// Top border is drawn by renderCall, not renderResult — so the
+			// renderResult output starts with at least one body line and
+			// ends with the bottom border. Body rows carry the `│` rail.
+			const bodyRows = lines.filter((l: string) =>
+				stripAnsi(l).startsWith("│"),
+			);
+			expect(bodyRows.length).toBeGreaterThan(0);
+
+			// Body must contain each source line by content.
+			const body = lines.map(stripAnsi).join("\n");
+			expect(body).toContain("line one");
+			expect(body).toContain("line five");
+		});
+	});
+
+	it("renders an unknown-language file without dying (uses fallback path)", async () => {
+		const readTool = loadReadTool(async () => ({
+			content: [{ type: "text", text: "hello world" }],
+		}));
+		const result = await readTool.execute(
+			"t2",
+			{ path: "fixtures/no-extension" },
+			null,
+			null,
+			{},
+		);
+
+		await withStdoutColumns(80, async () => {
+			const ctx: any = {
+				lastComponent: new MockText(),
+				isError: false,
+				isPartial: false,
+				state: {},
+				expanded: false,
+				invalidate: () => {},
+			};
+			readTool.renderResult(result, {}, mockTheme, ctx);
+			await waitForCachedBody(ctx.state);
+			const rendered = readTool.renderResult(result, {}, mockTheme, ctx);
+			expect(stripAnsi(rendered.getText())).toContain("hello world");
+		});
+	});
+});

package/theme-resolution.test.ts

@@ -0,0 +1,238 @@
+/**
+ * Regression tests for Shiki theme resolution.
+ *
+ * Background: pi's `~/.pi/agent/settings.json` `theme` field is consumed
+ * by the host UI and may carry names that aren't valid Shiki bundled
+ * themes (e.g. `tokyo-night-storm`). Before this regression net,
+ * `pi-facelift` passed the raw value straight to Shiki's `codeToANSI`,
+ * which threw, and `hlBlock`'s `catch` block silently fell back to
+ * uncolored text — leaving every `read` body in plain whitish output
+ * with no obvious error.
+ *
+ * These tests pin three guarantees:
+ *   1. Bundled themes pass through untouched.
+ *   2. Common pi/host theme names are aliased to their nearest Shiki
+ *      bundled equivalent (case-insensitive).
+ *   3. Unknown / empty / whitespace-only theme names fall back to
+ *      `DEFAULT_THEME` and emit a one-shot console.error so silent
+ *      regressions are visible during dev.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { bundledThemes } from "shiki";
+
+import { __hlInternals, __themeInternals } from "./index.ts";
+
+const { DEFAULT_THEME, THEME_ALIASES, isBundledTheme, resolveBundledTheme, resetWarningsForTests } =
+	__themeInternals;
+
+const { hlBlock, resetCacheForTests, resetErrorLogForTests } = __hlInternals;
+
+beforeEach(() => {
+	resetWarningsForTests();
+});
+
+describe("theme resolution: alias map sanity", () => {
+	it("DEFAULT_THEME is a valid Shiki bundled theme", () => {
+		expect(isBundledTheme(DEFAULT_THEME)).toBe(true);
+	});
+
+	it("every alias value points at a valid Shiki bundled theme", () => {
+		for (const [from, to] of Object.entries(THEME_ALIASES)) {
+			expect(isBundledTheme(to), `alias ${from} -> ${to} must be bundled`).toBe(true);
+		}
+	});
+
+	it("alias keys are lowercase (matching the lookup convention)", () => {
+		for (const key of Object.keys(THEME_ALIASES)) {
+			expect(key).toBe(key.toLowerCase());
+		}
+	});
+
+	it("does not alias names that are already bundled (would be dead code)", () => {
+		for (const key of Object.keys(THEME_ALIASES)) {
+			expect(
+				Object.prototype.hasOwnProperty.call(bundledThemes, key),
+				`alias key "${key}" is already a bundled theme; alias entry is unreachable`,
+			).toBe(false);
+		}
+	});
+});
+
+describe("resolveBundledTheme: passthrough + fallbacks", () => {
+	let errorSpy: ReturnType<typeof vi.spyOn>;
+
+	beforeEach(() => {
+		errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+	});
+	afterEach(() => {
+		errorSpy.mockRestore();
+	});
+
+	it("returns a bundled theme name unchanged", () => {
+		expect(resolveBundledTheme("github-dark")).toBe("github-dark");
+		expect(resolveBundledTheme("dracula")).toBe("dracula");
+		expect(resolveBundledTheme("nord")).toBe("nord");
+		expect(errorSpy).not.toHaveBeenCalled();
+	});
+
+	it("falls back to DEFAULT_THEME for undefined/empty/whitespace input", () => {
+		expect(resolveBundledTheme(undefined)).toBe(DEFAULT_THEME);
+		expect(resolveBundledTheme("")).toBe(DEFAULT_THEME);
+		expect(resolveBundledTheme("   ")).toBe(DEFAULT_THEME);
+		// Empty/whitespace input is the "no theme configured" path — no warning.
+		expect(errorSpy).not.toHaveBeenCalled();
+	});
+
+	it("trims surrounding whitespace before validating", () => {
+		expect(resolveBundledTheme("  github-dark  ")).toBe("github-dark");
+		expect(errorSpy).not.toHaveBeenCalled();
+	});
+});
+
+describe("resolveBundledTheme: alias resolution", () => {
+	let errorSpy: ReturnType<typeof vi.spyOn>;
+
+	beforeEach(() => {
+		errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+	});
+	afterEach(() => {
+		errorSpy.mockRestore();
+	});
+
+	// The original bug report: pi user has `"theme": "tokyo-night-storm"`,
+	// Shiki only ships `tokyo-night`.
+	it("aliases tokyo-night-storm to tokyo-night (the original bug report)", () => {
+		expect(resolveBundledTheme("tokyo-night-storm")).toBe("tokyo-night");
+		expect(errorSpy).not.toHaveBeenCalled();
+	});
+
+	it("aliases other tokyo-night variants", () => {
+		expect(resolveBundledTheme("tokyo-night-night")).toBe("tokyo-night");
+		expect(resolveBundledTheme("tokyo-night-day")).toBe("tokyo-night");
+		expect(resolveBundledTheme("tokyonight")).toBe("tokyo-night");
+		expect(resolveBundledTheme("tokyonight-storm")).toBe("tokyo-night");
+	});
+
+	it("aliases case-insensitively", () => {
+		expect(resolveBundledTheme("Tokyo-Night-Storm")).toBe("tokyo-night");
+		expect(resolveBundledTheme("CATPPUCCIN")).toBe("catppuccin-mocha");
+		expect(resolveBundledTheme("Material")).toBe("material-theme");
+	});
+
+	it("aliases catppuccin family defaults", () => {
+		expect(resolveBundledTheme("catppuccin")).toBe("catppuccin-mocha");
+	});
+
+	it("aliases gruvbox/material/solarized/one-dark families to canonical variants", () => {
+		expect(resolveBundledTheme("gruvbox-dark")).toBe("gruvbox-dark-medium");
+		expect(resolveBundledTheme("gruvbox-light")).toBe("gruvbox-light-medium");
+		expect(resolveBundledTheme("material")).toBe("material-theme");
+		expect(resolveBundledTheme("material-darker")).toBe("material-theme-darker");
+		expect(resolveBundledTheme("solarized")).toBe("solarized-dark");
+		expect(resolveBundledTheme("one-dark")).toBe("one-dark-pro");
+	});
+});
+
+describe("resolveBundledTheme: invalid theme warning", () => {
+	let errorSpy: ReturnType<typeof vi.spyOn>;
+
+	beforeEach(() => {
+		errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+	});
+	afterEach(() => {
+		errorSpy.mockRestore();
+	});
+
+	it("falls back to DEFAULT_THEME for an unknown name and warns once", () => {
+		expect(resolveBundledTheme("not-a-real-theme-9000")).toBe(DEFAULT_THEME);
+		expect(errorSpy).toHaveBeenCalledTimes(1);
+
+		const msg = errorSpy.mock.calls[0]?.[0];
+		expect(msg).toContain("pi-facelift");
+		expect(msg).toContain("not-a-real-theme-9000");
+		expect(msg).toContain(DEFAULT_THEME);
+		// The warning should advertise FACELIFT_THEME as the fix knob.
+		expect(msg).toContain("FACELIFT_THEME");
+	});
+
+	it("warns at most once per distinct invalid theme (no per-render spam)", () => {
+		expect(resolveBundledTheme("bogus-theme")).toBe(DEFAULT_THEME);
+		expect(resolveBundledTheme("bogus-theme")).toBe(DEFAULT_THEME);
+		expect(resolveBundledTheme("bogus-theme")).toBe(DEFAULT_THEME);
+		expect(errorSpy).toHaveBeenCalledTimes(1);
+	});
+
+	it("warns separately for distinct invalid names", () => {
+		expect(resolveBundledTheme("first-bad")).toBe(DEFAULT_THEME);
+		expect(resolveBundledTheme("second-bad")).toBe(DEFAULT_THEME);
+		expect(errorSpy).toHaveBeenCalledTimes(2);
+	});
+
+	it("does NOT warn for names resolved via the alias map", () => {
+		// `tokyo-night-storm` is invalid for Shiki but covered by an alias —
+		// this is the *fixed* path, not a regression, so it must stay quiet.
+		expect(resolveBundledTheme("tokyo-night-storm")).toBe("tokyo-night");
+		expect(errorSpy).not.toHaveBeenCalled();
+	});
+});
+
+describe("hlBlock: Shiki failure logging + plain-text fallback", () => {
+	let errorSpy: ReturnType<typeof vi.spyOn>;
+
+	beforeEach(() => {
+		errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+		resetCacheForTests();
+		resetErrorLogForTests();
+	});
+	afterEach(() => {
+		errorSpy.mockRestore();
+	});
+
+	it("returns plain split lines when language is missing (no shiki call, no log)", async () => {
+		const out = await hlBlock("a\nb\nc", undefined);
+		expect(out).toEqual(["a", "b", "c"]);
+		expect(errorSpy).not.toHaveBeenCalled();
+	});
+
+	it("returns [''] for empty input", async () => {
+		expect(await hlBlock("", "typescript")).toEqual([""]);
+		expect(errorSpy).not.toHaveBeenCalled();
+	});
+
+	it("returns ANSI-colored lines for a valid theme + language (sanity)", async () => {
+		const out = await hlBlock("const x = 1;", "typescript");
+		expect(out.length).toBeGreaterThan(0);
+		// Joined output must contain at least one ANSI escape — proof shiki ran.
+		expect(out.join("\n")).toMatch(/\x1b\[/);
+		expect(errorSpy).not.toHaveBeenCalled();
+	});
+
+	it("falls back to plain split lines when shiki rejects a bogus language, and logs once", async () => {
+		// `"definitely-not-a-language"` is not a `BundledLanguage`, but the
+		// runtime check in shiki throws synchronously inside the promise.
+		// We cast through `unknown` to bypass the compile-time guard — this
+		// is the same shape a stale settings.theme value would take if it
+		// somehow reached the highlighter.
+		const bogusLang = "definitely-not-a-language" as unknown as Parameters<
+			typeof hlBlock
+		>[1];
+		const src = "const x = 1;";
+
+		const out1 = await hlBlock(src, bogusLang);
+		expect(out1).toEqual([src]);
+		expect(errorSpy).toHaveBeenCalledTimes(1);
+
+		const msg = errorSpy.mock.calls[0]?.[0];
+		expect(msg).toContain("pi-facelift");
+		expect(msg).toContain("shiki");
+		expect(msg).toContain("definitely-not-a-language");
+
+		// Second call with the same (theme, language) tag must NOT re-log.
+		// We change the source so the cache key differs and the catch path
+		// runs again — still only one log.
+		const out2 = await hlBlock("let y = 2;", bogusLang);
+		expect(out2).toEqual(["let y = 2;"]);
+		expect(errorSpy).toHaveBeenCalledTimes(1);
+	});
+});