@heyhuynhgiabuu/pi-pretty 0.3.1 → 0.3.3

package/README.md

@@ -41,7 +41,25 @@ pi -e ./src/index.ts
 ## Terminal support for inline images
 
 Inline image previews are supported in **Ghostty**, **Kitty**, **iTerm2**, and **WezTerm**.  
-When running in **tmux**, pi-pretty uses passthrough escape sequences so inline image protocols still work.
+When running in **tmux**, pi-pretty uses passthrough escape sequences.
+
+> tmux must allow passthrough. Enable it with:
+>
+> ```tmux
+> set -g allow-passthrough on
+> ```
+>
+> (or run once in a session: `tmux set -g allow-passthrough on`)
+
+## FFF data directory
+
+When FFF is available, pi-pretty now stores its frecency/history data under a pi-pretty-specific path:
+
+```text
+~/.pi/agent/pi-pretty/fff/
+```
+
+This makes it clear that the cache belongs to this extension rather than Pi core.
 
 ## Configuration
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@heyhuynhgiabuu/pi-pretty",
-	"version": "0.3.1",
+	"version": "0.3.3",
 	"description": "Pretty terminal output for pi — syntax-highlighted file reads, colored bash output, tree-view directory listings, and more.",
 	"author": "huynhgiabuu",
 	"license": "MIT",

package/release-notes/v0.3.2.md

@@ -0,0 +1,34 @@
+# pi-pretty v0.3.2
+
+## Summary
+This patch release fixes inline image rendering reliability when running `pi-pretty` inside `tmux`.
+
+## What changed
+- Fixed terminal detection in tmux for:
+  - Kitty (`KITTY_WINDOW_ID`, `KITTY_PID`)
+  - WezTerm (`WEZTERM_EXECUTABLE`, `WEZTERM_CONFIG_DIR`, `WEZTERM_CONFIG_FILE`)
+- Added tmux fallback detection via:
+  - `tmux display-message -p "#{client_termname}"`
+- Replaced static tmux detection with runtime detection to avoid stale module-load state.
+- Added explicit warning when tmux passthrough is disabled:
+  - `tmux allow-passthrough is off. Run: tmux set -g allow-passthrough on`
+- Added non-PNG warning for Kitty/Ghostty image rendering path.
+- Added test coverage for image protocol detection and tmux passthrough warning behavior.
+- Updated README with tmux passthrough setup instructions.
+
+## Files
+- `src/index.ts`
+- `test/image-rendering.test.ts`
+- `README.md`
+
+## Verification
+- `npm run typecheck` ✅
+- `npm test` ✅ (46 tests)
+- `npm run lint` ⚠️ fails due to existing Biome diagnostics in legacy code paths (pre-existing, not introduced in this patch).
+
+## Upgrade notes
+When using `tmux`, enable passthrough:
+
+```tmux
+set -g allow-passthrough on
+```

package/release-notes/v0.3.3.md

@@ -0,0 +1,48 @@
+# pi-pretty v0.3.3
+
+## Summary
+This patch release combines the recent rendering and FFF-path fixes into a single `v0.3.3` release.
+
+## What changed
+- Fixed themed tool background rendering so `toolSuccessBg` and `toolErrorBg` fill the full rendered width for core tool output.
+- Preserved the active tool background across ANSI reset sequences to avoid broken background bands inside highlighted output.
+- Kept error rendering on `theme.fg("error", ...)` while switching error panels to `toolErrorBg`.
+- Moved pi-pretty FFF data from:
+  - `~/.pi/agent/fff`
+- To:
+  - `~/.pi/agent/pi-pretty/fff`
+- Added a helper to resolve the pi-pretty-specific FFF directory under `getAgentDir()`.
+- Updated README to document the pi-pretty-owned FFF data location.
+- Added a test that verifies the generated frecency/history DB paths use the new per-extension location.
+
+## Files
+- `src/index.ts`
+- `test/fff-integration.test.ts`
+- `README.md`
+- `package.json`
+- `package-lock.json`
+
+## Verification
+- `npm run typecheck` ✅
+- `npm test` ✅ (47 tests)
+- `npm run lint` ⚠️ still reports pre-existing Biome diagnostics in legacy code paths; no new release-blocking failure was introduced for this patch.
+
+## Upgrade notes
+If your Pi theme defines:
+
+```json
+{
+  "toolSuccessBg": "#1e2e1e",
+  "toolErrorBg": "#2e1e1e"
+}
+```
+
+core tool panels now render those backgrounds across the full line width instead of only behind printed characters.
+
+When FFF is available, pi-pretty now stores frecency/history data under:
+
+```text
+~/.pi/agent/pi-pretty/fff/
+```
+
+Existing data under `~/.pi/agent/fff` is not migrated automatically by this release.

package/src/index.ts

@@ -23,6 +23,7 @@
  *   • Large-file fallback (skip highlighting, still show line numbers)
  */
 
+import * as childProcess from "node:child_process";
 import { existsSync, mkdirSync, statSync } from "node:fs";
 import { basename, dirname, extname, join, relative } from "node:path";
 
@@ -70,28 +71,41 @@ const FG_PURPLE = "\x1b[38;2;170;120;200m";
 const BG_STDERR = "\x1b[48;2;40;25;25m";
 
 const BG_DEFAULT = "\x1b[49m";
-let BG_BASE = BG_DEFAULT; // tool box base bg — updated from theme's toolSuccessBg
+let BG_BASE = BG_DEFAULT; // tool box success/base bg — updated from theme's toolSuccessBg
+let BG_ERROR = BG_DEFAULT; // tool box error bg — updated from theme's toolErrorBg
+
+type BgTheme = { getBgAnsi?: (key: string) => string };
+type FgTheme = { fg: (key: string, text: string) => string };
 
 /** Parse an ANSI 24-bit color escape into { r, g, b }. Handles both fg (38;2) and bg (48;2). */
 function parseAnsiRgb(ansi: string): { r: number; g: number; b: number } | null {
-	const m = ansi.match(/\x1b\[(?:38|48);2;(\d+);(\d+);(\d+)m/);
+	const m = ansi.match(new RegExp(`${ESC_RE}\\[(?:38|48);2;(\\d+);(\\d+);(\\d+)m`));
 	return m ? { r: +m[1], g: +m[2], b: +m[3] } : null;
 }
 
-/** Read toolSuccessBg from the pi theme and update BG_BASE + RST.
+function getThemeBgAnsi(theme: BgTheme, key: string): string | null {
+	try {
+		const bgAnsi = theme.getBgAnsi?.(key);
+		return bgAnsi && parseAnsiRgb(bgAnsi) ? bgAnsi : null;
+	} catch {
+		return null;
+	}
+}
+
+/** Read themed tool backgrounds and update BG_BASE / BG_ERROR + RST.
  *  Call once when theme is first available. Idempotent. */
 let _bgBaseResolved = false;
-function resolveBaseBackground(theme: any): void {
+function resolveBaseBackground(theme: BgTheme | null | undefined): void {
 	if (_bgBaseResolved || !theme?.getBgAnsi) return;
 	_bgBaseResolved = true;
-	try {
-		const bgAnsi = theme.getBgAnsi("toolSuccessBg");
-		const parsed = parseAnsiRgb(bgAnsi);
-		if (parsed) {
-			BG_BASE = bgAnsi;
-			RST = `\x1b[0m${BG_BASE}`;
-		}
-	} catch { /* ignore — keep defaults */ }
+
+	BG_BASE = getThemeBgAnsi(theme, "toolSuccessBg") ?? BG_DEFAULT;
+	BG_ERROR = getThemeBgAnsi(theme, "toolErrorBg") ?? BG_BASE;
+	RST = `\x1b[0m${BG_BASE}`;
+}
+
+function renderToolError(error: string, theme: FgTheme): string {
+	return fillToolBackground(`\n${theme.fg("error", error)}`, BG_ERROR);
 }
 
 const ESC_RE = "\u001b";
@@ -125,6 +139,25 @@ function strip(s: string): string {
 	return s.replace(ANSI_RE, "");
 }
 
+function preserveToolBackground(ansi: string, bg: string): string {
+	return ansi.replace(ANSI_CAPTURE_RE, (seq, params: string) => {
+		const codes = params.split(";");
+		return params === "0" || codes.includes("49") ? `${seq}${bg}` : seq;
+	});
+}
+
+function fillToolBackground(text: string, bg = BG_BASE): string {
+	const width = termW();
+	return text
+		.split("\n")
+		.map((line) => {
+			const normalized = preserveToolBackground(line, bg);
+			const padding = Math.max(0, width - strip(normalized).length);
+			return `${bg}${normalized}${" ".repeat(padding)}${RST}`;
+		})
+		.join("\n");
+}
+
 function termW(): number {
 	const raw =
 		process.stdout.columns || (process.stderr as any).columns || Number.parseInt(process.env.COLUMNS ?? "", 10) || 200;
@@ -217,7 +250,45 @@ function lang(fp: string): BundledLanguage | undefined {
 
 type ImageProtocol = "iterm2" | "kitty" | "none";
 
-const IS_TMUX = !!process.env.TMUX;
+let _tmuxClientTermCache: string | null | undefined;
+let _tmuxAllowPassthroughCache: boolean | null | undefined;
+let _tmuxClientTermOverrideForTests: string | null | undefined;
+let _tmuxAllowPassthroughOverrideForTests: boolean | null | undefined;
+
+function isTmuxSession(): boolean {
+	return !!process.env.TMUX || /^(tmux|screen)/.test(process.env.TERM ?? "");
+}
+
+function normalizeTerminalName(term: string): string {
+	const t = term.toLowerCase();
+	if (t.includes("kitty")) return "kitty";
+	if (t.includes("ghostty")) return "ghostty";
+	if (t.includes("wezterm")) return "WezTerm";
+	if (t.includes("iterm")) return "iTerm.app";
+	if (t.includes("mintty")) return "mintty";
+	return term;
+}
+
+function readTmuxClientTerm(): string | null {
+	if (_tmuxClientTermOverrideForTests !== undefined) {
+		return _tmuxClientTermOverrideForTests ? normalizeTerminalName(_tmuxClientTermOverrideForTests) : null;
+	}
+	if (!isTmuxSession()) return null;
+	if (_tmuxClientTermCache !== undefined) return _tmuxClientTermCache;
+	try {
+		const term = childProcess
+			.execFileSync("tmux", ["display-message", "-p", "#{client_termname}"], {
+				encoding: "utf8",
+				stdio: ["ignore", "pipe", "ignore"],
+				timeout: 200,
+			})
+			.trim();
+		_tmuxClientTermCache = term ? normalizeTerminalName(term) : null;
+	} catch {
+		_tmuxClientTermCache = null;
+	}
+	return _tmuxClientTermCache;
+}
 
 /**
  * Detect the outer terminal when running inside tmux.
@@ -225,27 +296,34 @@ const IS_TMUX = !!process.env.TMUX;
  * the environment of the tmux server or can be inferred.
  */
 function getOuterTerminal(): string {
-	// Direct terminal (not in tmux)
-	const term = process.env.TERM_PROGRAM ?? "";
-	if (term !== "tmux" && term !== "screen") return term;
-
-	// Inside tmux: check common env vars that leak through
-	// Ghostty sets this; iTerm2 sets LC_TERMINAL
+	// Environment hints that often survive inside tmux
 	if (process.env.LC_TERMINAL === "iTerm2") return "iTerm.app";
-
-	// TERM_PROGRAM_VERSION sometimes survives into tmux
-	// Try to detect via COLORTERM or other hints
 	if (process.env.GHOSTTY_RESOURCES_DIR) return "ghostty";
+	if (process.env.KITTY_WINDOW_ID || process.env.KITTY_PID) return "kitty";
+	if (process.env.WEZTERM_EXECUTABLE || process.env.WEZTERM_CONFIG_DIR || process.env.WEZTERM_CONFIG_FILE) {
+		return "WezTerm";
+	}
 
-	// Default: assume modern terminal if truecolor is supported
-	if (process.env.COLORTERM === "truecolor" || process.env.COLORTERM === "24bit") {
-		// Can't determine exact terminal, but likely modern
-		return "unknown-modern";
+	const termProgram = process.env.TERM_PROGRAM ?? "";
+	if (termProgram && termProgram !== "tmux" && termProgram !== "screen") {
+		return normalizeTerminalName(termProgram);
 	}
-	return term;
+
+	const tmuxClientTerm = readTmuxClientTerm();
+	if (tmuxClientTerm) return tmuxClientTerm;
+
+	const term = process.env.TERM ?? "";
+	if (term) return normalizeTerminalName(term);
+	if (process.env.COLORTERM === "truecolor" || process.env.COLORTERM === "24bit") return "unknown-modern";
+	return termProgram;
 }
 
 function detectImageProtocol(): ImageProtocol {
+	const forced = (process.env.PRETTY_IMAGE_PROTOCOL ?? "").toLowerCase();
+	if (forced === "kitty" || forced === "iterm2" || forced === "none") {
+		return forced;
+	}
+
 	const term = getOuterTerminal();
 	// Ghostty and Kitty use the Kitty graphics protocol
 	if (term === "ghostty" || term === "kitty") return "kitty";
@@ -255,18 +333,67 @@ function detectImageProtocol(): ImageProtocol {
 	return "none";
 }
 
+function tmuxAllowsPassthrough(): boolean | null {
+	if (_tmuxAllowPassthroughOverrideForTests !== undefined) return _tmuxAllowPassthroughOverrideForTests;
+	if (!isTmuxSession()) return null;
+	if (_tmuxAllowPassthroughCache !== undefined) return _tmuxAllowPassthroughCache;
+	try {
+		const value = childProcess
+			.execFileSync("tmux", ["show-options", "-gv", "allow-passthrough"], {
+				encoding: "utf8",
+				stdio: ["ignore", "pipe", "ignore"],
+				timeout: 200,
+			})
+			.trim()
+			.toLowerCase();
+		_tmuxAllowPassthroughCache = value === "on" || value === "all";
+	} catch {
+		_tmuxAllowPassthroughCache = null;
+	}
+	return _tmuxAllowPassthroughCache;
+}
+
+function getTmuxPassthroughWarning(protocol: ImageProtocol): string | null {
+	if (!isTmuxSession() || protocol === "none") return null;
+	if (tmuxAllowsPassthrough() === false) {
+		return "tmux allow-passthrough is off. Run: tmux set -g allow-passthrough on";
+	}
+	return null;
+}
+
 /**
  * Wrap escape sequence for tmux passthrough.
  * tmux requires: ESC Ptmux; <escaped-sequence> ESC \
  * Inner ESC chars must be doubled.
  */
 function tmuxWrap(seq: string): string {
-	if (!IS_TMUX) return seq;
+	if (!isTmuxSession()) return seq;
 	// Double all ESC chars inside the sequence
 	const escaped = seq.split("\x1b").join("\x1b\x1b");
 	return `\x1bPtmux;${escaped}\x1b\\`;
 }
 
+export const __imageInternals = {
+	isTmuxSession,
+	getOuterTerminal,
+	detectImageProtocol,
+	tmuxWrap,
+	tmuxAllowsPassthrough,
+	getTmuxPassthroughWarning,
+	setTmuxClientTermOverrideForTests: (value: string | null | undefined) => {
+		_tmuxClientTermOverrideForTests = value;
+	},
+	setTmuxAllowPassthroughOverrideForTests: (value: boolean | null | undefined) => {
+		_tmuxAllowPassthroughOverrideForTests = value;
+	},
+	resetCachesForTests: () => {
+		_tmuxClientTermCache = undefined;
+		_tmuxAllowPassthroughCache = undefined;
+		_tmuxClientTermOverrideForTests = undefined;
+		_tmuxAllowPassthroughOverrideForTests = undefined;
+	},
+};
+
 /**
  * Render base64 image inline using iTerm2 inline image protocol.
  * Protocol: ESC ] 1337 ; File=[args] : base64data BEL
@@ -685,6 +812,10 @@ let _fffPartialIndex = false;
 let _fffDbDir: string | null = null;
 const FFF_SCAN_TIMEOUT = 15_000;
 
+function getPiPrettyFffDir(agentDir: string): string {
+	return join(agentDir, "pi-pretty", "fff");
+}
+
 async function fffEnsureFinder(cwd: string): Promise<any> {
 	if (_fffFinder && !_fffFinder.isDestroyed) return _fffFinder;
 	if (!_fffModule || !_fffDbDir) return null;
@@ -779,7 +910,7 @@ export default function piPrettyExtension(pi: any, deps?: PiPrettyDeps): void {
 		try {
 			_fffModule = require("@ff-labs/fff-node");
 			if (getAgentDir) {
-				_fffDbDir = join(getAgentDir(), "fff");
+				_fffDbDir = getPiPrettyFffDir(getAgentDir());
 				try {
 					mkdirSync(_fffDbDir, { recursive: true });
 				} catch {}
@@ -788,7 +919,7 @@ export default function piPrettyExtension(pi: any, deps?: PiPrettyDeps): void {
 			/* FFF not installed — SDK tools will be used */
 		}
 	} else if (_fffModule && getAgentDir) {
-		_fffDbDir = join(getAgentDir(), "fff");
+		_fffDbDir = getPiPrettyFffDir(getAgentDir());
 		try {
 			mkdirSync(_fffDbDir, { recursive: true });
 		} catch {}
@@ -806,7 +937,7 @@ export default function piPrettyExtension(pi: any, deps?: PiPrettyDeps): void {
 
 		if (!_fffDbDir) {
 			const agentDir = getAgentDir?.() ?? join(home, ".pi/agent");
-			_fffDbDir = join(agentDir, "fff");
+			_fffDbDir = getPiPrettyFffDir(agentDir);
 			try {
 				mkdirSync(_fffDbDir, { recursive: true });
 			} catch {}
@@ -883,7 +1014,7 @@ export default function piPrettyExtension(pi: any, deps?: PiPrettyDeps): void {
 			const text = ctx.lastComponent ?? new TextComponent("", 0, 0);
 			const offset = args?.offset ? ` ${theme.fg("muted", `from line ${args.offset}`)}` : "";
 			const limit = args?.limit ? ` ${theme.fg("muted", `(${args.limit} lines)`)}` : "";
-			text.setText(`${theme.fg("toolTitle", theme.bold("read"))} ${theme.fg("accent", sp(fp))}${offset}${limit}`);
+			text.setText(fillToolBackground(`${theme.fg("toolTitle", theme.bold("read"))} ${theme.fg("accent", sp(fp))}${offset}${limit}`));
 			return text;
 		},
 
@@ -897,7 +1028,7 @@ export default function piPrettyExtension(pi: any, deps?: PiPrettyDeps): void {
 						?.filter((c: any) => c.type === "text")
 						.map((c: any) => c.text || "")
 						.join("\n") ?? "Error";
-				text.setText(`\n${theme.fg("error", e)}`);
+				text.setText(renderToolError(e, theme));
 				return text;
 			}
 
@@ -916,9 +1047,16 @@ export default function piPrettyExtension(pi: any, deps?: PiPrettyDeps): void {
 				out.push(rule(tw));
 
 				const protocol = detectImageProtocol();
-				if (protocol === "kitty") {
-					const imgCols = Math.min(tw - 4, 80);
-					out.push(renderKittyImage(d.data, { cols: imgCols }));
+				const passthroughWarning = getTmuxPassthroughWarning(protocol);
+				if (passthroughWarning) {
+					out.push(`  ${FG_YELLOW}${passthroughWarning}${RST}`);
+				} else if (protocol === "kitty") {
+					if (d.mimeType && d.mimeType !== "image/png") {
+						out.push(`  ${FG_YELLOW}Kitty/Ghostty inline preview currently supports PNG payloads (got ${d.mimeType})${RST}`);
+					} else {
+						const imgCols = Math.min(tw - 4, 80);
+						out.push(renderKittyImage(d.data, { cols: imgCols }));
+					}
 				} else if (protocol === "iterm2") {
 					const imgWidth = Math.min(tw - 4, 80);
 					out.push(
@@ -932,7 +1070,7 @@ export default function piPrettyExtension(pi: any, deps?: PiPrettyDeps): void {
 				}
 
 				out.push(rule(tw));
-				text.setText(out.join("\n"));
+				text.setText(fillToolBackground(out.join("\n")));
 				return text;
 			}
 
@@ -941,24 +1079,24 @@ export default function piPrettyExtension(pi: any, deps?: PiPrettyDeps): void {
 				if (ctx.state._rk !== key) {
 					ctx.state._rk = key;
 					const info = `${FG_DIM}${d.lineCount} lines${RST}`;
-					ctx.state._rt = `  ${info}`;
+					ctx.state._rt = fillToolBackground(`  ${info}`);
 
 					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 = `  ${info}\n${rendered}`;
+							ctx.state._rt = fillToolBackground(`  ${info}\n${rendered}`);
 							ctx.invalidate();
 						})
 						.catch(() => {});
 				}
-				text.setText(ctx.state._rt ?? `  ${FG_DIM}${d.lineCount} lines${RST}`);
+				text.setText(ctx.state._rt ?? fillToolBackground(`  ${FG_DIM}${d.lineCount} lines${RST}`));
 				return text;
 			}
 
 			// Fallback
 			const fallback = result.content?.[0]?.text ?? "read";
-			text.setText(`  ${theme.fg("dim", String(fallback).slice(0, 120))}`);
+			text.setText(fillToolBackground(`  ${theme.fg("dim", String(fallback).slice(0, 120))}`));
 			return text;
 		},
 	});
@@ -1009,7 +1147,7 @@ export default function piPrettyExtension(pi: any, deps?: PiPrettyDeps): void {
 				const text = ctx.lastComponent ?? new TextComponent("", 0, 0);
 				const timeout = args?.timeout ? ` ${theme.fg("muted", `(${args.timeout}s timeout)`)}` : "";
 				text.setText(
-					`${theme.fg("toolTitle", theme.bold("bash"))} ${theme.fg("accent", cmd.length > 80 ? cmd.slice(0, 77) + "…" : cmd)}${timeout}`,
+					fillToolBackground(`${theme.fg("toolTitle", theme.bold("bash"))} ${theme.fg("accent", cmd.length > 80 ? cmd.slice(0, 77) + "…" : cmd)}${timeout}`),
 				);
 				return text;
 			},
@@ -1024,7 +1162,7 @@ export default function piPrettyExtension(pi: any, deps?: PiPrettyDeps): void {
 							?.filter((c: any) => c.type === "text")
 							.map((c: any) => c.text || "")
 							.join("\n") ?? "Error";
-					text.setText(`\n${theme.fg("error", e)}`);
+					text.setText(renderToolError(e, theme));
 					return text;
 				}
 
@@ -1049,15 +1187,15 @@ export default function piPrettyExtension(pi: any, deps?: PiPrettyDeps): void {
 						if (lineCount > maxShow) {
 							out.push(`${FG_DIM}  … ${lineCount - maxShow} more lines${RST}`);
 						}
-						text.setText(out.join("\n"));
+						text.setText(fillToolBackground(out.join("\n")));
 					} else {
-						text.setText(header);
+						text.setText(fillToolBackground(header));
 					}
 					return text;
 				}
 
 				const fallback = result.content?.[0]?.text ?? "done";
-				text.setText(`  ${theme.fg("dim", String(fallback).slice(0, 120))}`);
+				text.setText(fillToolBackground(`  ${theme.fg("dim", String(fallback).slice(0, 120))}`));
 				return text;
 			},
 		});
@@ -1099,7 +1237,7 @@ export default function piPrettyExtension(pi: any, deps?: PiPrettyDeps): void {
 			resolveBaseBackground(theme);
 				const fp = args?.path ?? ".";
 				const text = ctx.lastComponent ?? new TextComponent("", 0, 0);
-				text.setText(`${theme.fg("toolTitle", theme.bold("ls"))} ${theme.fg("accent", sp(fp))}`);
+				text.setText(fillToolBackground(`${theme.fg("toolTitle", theme.bold("ls"))} ${theme.fg("accent", sp(fp))}`));
 				return text;
 			},
 
@@ -1113,7 +1251,7 @@ export default function piPrettyExtension(pi: any, deps?: PiPrettyDeps): void {
 							?.filter((c: any) => c.type === "text")
 							.map((c: any) => c.text || "")
 							.join("\n") ?? "Error";
-					text.setText(`\n${theme.fg("error", e)}`);
+					text.setText(renderToolError(e, theme));
 					return text;
 				}
 
@@ -1121,12 +1259,12 @@ export default function piPrettyExtension(pi: any, deps?: PiPrettyDeps): void {
 				if (d?._type === "lsResult" && d.text) {
 					const tree = renderTree(d.text, d.path);
 					const info = `${FG_DIM}${d.entryCount} entries${RST}`;
-					text.setText(`  ${info}\n${tree}`);
+					text.setText(fillToolBackground(`  ${info}\n${tree}`));
 					return text;
 				}
 
 				const fallback = result.content?.[0]?.text ?? "listed";
-				text.setText(`  ${theme.fg("dim", String(fallback).slice(0, 120))}`);
+				text.setText(fillToolBackground(`  ${theme.fg("dim", String(fallback).slice(0, 120))}`));
 				return text;
 			},
 		});
@@ -1205,7 +1343,7 @@ export default function piPrettyExtension(pi: any, deps?: PiPrettyDeps): void {
 				const pattern = args?.pattern ?? "";
 				const path = args?.path ? ` ${theme.fg("muted", `in ${sp(args.path)}`)}` : "";
 				const text = ctx.lastComponent ?? new TextComponent("", 0, 0);
-				text.setText(`${theme.fg("toolTitle", theme.bold("find"))} ${theme.fg("accent", pattern)}${path}`);
+				text.setText(fillToolBackground(`${theme.fg("toolTitle", theme.bold("find"))} ${theme.fg("accent", pattern)}${path}`));
 				return text;
 			},
 
@@ -1219,7 +1357,7 @@ export default function piPrettyExtension(pi: any, deps?: PiPrettyDeps): void {
 							?.filter((c: any) => c.type === "text")
 							.map((c: any) => c.text || "")
 							.join("\n") ?? "Error";
-					text.setText(`\n${theme.fg("error", e)}`);
+					text.setText(renderToolError(e, theme));
 					return text;
 				}
 
@@ -1227,12 +1365,12 @@ export default function piPrettyExtension(pi: any, deps?: PiPrettyDeps): void {
 				if (d?._type === "findResult" && d.text) {
 					const rendered = renderFindResults(d.text);
 					const info = `${FG_DIM}${d.matchCount} files${RST}`;
-					text.setText(`  ${info}\n${rendered}`);
+					text.setText(fillToolBackground(`  ${info}\n${rendered}`));
 					return text;
 				}
 
 				const fallback = result.content?.[0]?.text ?? "found";
-				text.setText(`  ${theme.fg("dim", String(fallback).slice(0, 120))}`);
+				text.setText(fillToolBackground(`  ${theme.fg("dim", String(fallback).slice(0, 120))}`));
 				return text;
 			},
 		});
@@ -1332,7 +1470,7 @@ export default function piPrettyExtension(pi: any, deps?: PiPrettyDeps): void {
 				const path = args?.path ? ` ${theme.fg("muted", `in ${sp(args.path)}`)}` : "";
 				const glob = args?.glob ? ` ${theme.fg("muted", `(${args.glob})`)}` : "";
 				const text = ctx.lastComponent ?? new TextComponent("", 0, 0);
-				text.setText(`${theme.fg("toolTitle", theme.bold("grep"))} ${theme.fg("accent", pattern)}${path}${glob}`);
+				text.setText(fillToolBackground(`${theme.fg("toolTitle", theme.bold("grep"))} ${theme.fg("accent", pattern)}${path}${glob}`));
 				return text;
 			},
 
@@ -1346,7 +1484,7 @@ export default function piPrettyExtension(pi: any, deps?: PiPrettyDeps): void {
 							?.filter((c: any) => c.type === "text")
 							.map((c: any) => c.text || "")
 							.join("\n") ?? "Error";
-					text.setText(`\n${theme.fg("error", e)}`);
+					text.setText(renderToolError(e, theme));
 					return text;
 				}
 
@@ -1356,22 +1494,22 @@ export default function piPrettyExtension(pi: any, deps?: PiPrettyDeps): void {
 					if (ctx.state._gk !== key) {
 						ctx.state._gk = key;
 						const info = `${FG_DIM}${d.matchCount} matches${RST}`;
-						ctx.state._gt = `  ${info}`;
+						ctx.state._gt = fillToolBackground(`  ${info}`);
 
 						renderGrepResults(d.text, d.pattern)
 							.then((rendered: string) => {
 								if (ctx.state._gk !== key) return;
-								ctx.state._gt = `  ${info}\n${rendered}`;
+								ctx.state._gt = fillToolBackground(`  ${info}\n${rendered}`);
 								ctx.invalidate();
 							})
 							.catch(() => {});
 					}
-					text.setText(ctx.state._gt ?? `  ${FG_DIM}${d.matchCount} matches${RST}`);
+					text.setText(ctx.state._gt ?? fillToolBackground(`  ${FG_DIM}${d.matchCount} matches${RST}`));
 					return text;
 				}
 
 				const fallback = result.content?.[0]?.text ?? "searched";
-				text.setText(`  ${theme.fg("dim", String(fallback).slice(0, 120))}`);
+				text.setText(fillToolBackground(`  ${theme.fg("dim", String(fallback).slice(0, 120))}`));
 				return text;
 			},
 		});

package/test/fff-integration.test.ts

@@ -175,6 +175,9 @@ describe("piPrettyExtension integration", () => {
 
 	function makeDeps(withFFF: boolean, finderOverrides?: Record<string, any>): PiPrettyDeps {
 		const finder = mkFinder(finderOverrides);
+		const fffModule = finderOverrides?.FileFinder
+			? { FileFinder: finderOverrides.FileFinder }
+			: { FileFinder: { create: vi.fn().mockReturnValue({ ok: true, value: finder }) } };
 		return {
 			sdk: {
 				createReadToolDefinition: mockToolFactory(readExec),
@@ -185,9 +188,7 @@ describe("piPrettyExtension integration", () => {
 				getAgentDir: () => "/tmp/pi-pretty-test",
 			},
 			TextComponent: class { private t = ""; setText(v: string) { this.t = v; } getText() { return this.t; } },
-			fffModule: withFFF
-				? { FileFinder: { create: vi.fn().mockReturnValue({ ok: true, value: finder }) } }
-				: undefined,
+			fffModule: withFFF ? fffModule : undefined,
 		};
 	}
 
@@ -445,6 +446,18 @@ describe("piPrettyExtension integration", () => {
 	// ---- session lifecycle ---------------------------------------------
 
 	describe("session lifecycle", () => {
+		it("stores FFF data under a pi-pretty-specific directory", async () => {
+			const create = vi.fn().mockReturnValue({ ok: true, value: mkFinder() });
+			load(true, { FileFinder: { create } });
+			const start = events.get("session_start")!;
+			expect(start, "session_start not registered").toBeDefined();
+			await start({}, { cwd: "/tmp/test" });
+			expect(create).toHaveBeenCalledWith(expect.objectContaining({
+				frecencyDbPath: "/tmp/pi-pretty-test/pi-pretty/fff/frecency.mdb",
+				historyDbPath: "/tmp/pi-pretty-test/pi-pretty/fff/history.mdb",
+			}));
+		});
+
 		it("shutdown → subsequent find falls back to SDK", async () => {
 			await loadWithFFF();
 			await events.get("session_shutdown")!();

package/test/image-rendering.test.ts

@@ -0,0 +1,165 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import piPrettyExtension, { __imageInternals } from "../src/index.js";
+
+const ENV_KEYS = [
+	"TMUX",
+	"TERM",
+	"TERM_PROGRAM",
+	"LC_TERMINAL",
+	"GHOSTTY_RESOURCES_DIR",
+	"KITTY_WINDOW_ID",
+	"KITTY_PID",
+	"WEZTERM_EXECUTABLE",
+	"WEZTERM_CONFIG_DIR",
+	"WEZTERM_CONFIG_FILE",
+	"COLORTERM",
+	"PRETTY_IMAGE_PROTOCOL",
+] as const;
+
+class MockText {
+	private text = "";
+	constructor(_text = "", _x = 0, _y = 0) {}
+	setText(value: string) {
+		this.text = value;
+	}
+	getText() {
+		return this.text;
+	}
+}
+
+function mockToolFactory(exec: any) {
+	return (_cwd: string) => ({
+		name: "mock",
+		description: "mock",
+		parameters: { type: "object", properties: {} },
+		execute: exec,
+	});
+}
+
+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: () => {},
+	};
+
+	piPrettyExtension(pi, {
+		sdk: {
+			createReadToolDefinition: mockToolFactory(readExec),
+			createBashToolDefinition: mockToolFactory(noopExec),
+			createLsToolDefinition: mockToolFactory(noopExec),
+			createFindToolDefinition: mockToolFactory(noopExec),
+			createGrepToolDefinition: mockToolFactory(noopExec),
+			getAgentDir: () => "/tmp/pi-pretty-test",
+		},
+		TextComponent: MockText,
+	});
+
+	return tools.get("read");
+}
+
+describe("image rendering terminal detection", () => {
+	const envSnapshot = new Map<string, string | undefined>();
+
+	beforeEach(() => {
+		for (const key of ENV_KEYS) {
+			envSnapshot.set(key, process.env[key]);
+			delete process.env[key];
+		}
+		__imageInternals.resetCachesForTests();
+	});
+
+	afterEach(() => {
+		for (const key of ENV_KEYS) {
+			const value = envSnapshot.get(key);
+			if (value === undefined) delete process.env[key];
+			else process.env[key] = value;
+		}
+		__imageInternals.resetCachesForTests();
+	});
+
+	it("detects kitty protocol inside tmux via KITTY_WINDOW_ID", () => {
+		process.env.TMUX = "/tmp/tmux-1000/default,123,0";
+		process.env.TERM_PROGRAM = "tmux";
+		process.env.KITTY_WINDOW_ID = "1";
+
+		expect(__imageInternals.getOuterTerminal()).toBe("kitty");
+		expect(__imageInternals.detectImageProtocol()).toBe("kitty");
+	});
+
+	it("detects wezterm protocol inside tmux via WEZTERM_EXECUTABLE", () => {
+		process.env.TMUX = "/tmp/tmux-1000/default,123,0";
+		process.env.TERM_PROGRAM = "tmux";
+		process.env.WEZTERM_EXECUTABLE = "/Applications/WezTerm.app/Contents/MacOS/wezterm";
+
+		expect(__imageInternals.getOuterTerminal()).toBe("WezTerm");
+		expect(__imageInternals.detectImageProtocol()).toBe("iterm2");
+	});
+
+	it("falls back to tmux client term for outer terminal detection", () => {
+		process.env.TMUX = "/tmp/tmux-1000/default,123,0";
+		process.env.TERM_PROGRAM = "tmux";
+		__imageInternals.setTmuxClientTermOverrideForTests("xterm-kitty");
+
+		expect(__imageInternals.getOuterTerminal()).toBe("kitty");
+		expect(__imageInternals.detectImageProtocol()).toBe("kitty");
+	});
+
+	it("reports warning when tmux allow-passthrough is off", () => {
+		process.env.TMUX = "/tmp/tmux-1000/default,123,0";
+		__imageInternals.setTmuxAllowPassthroughOverrideForTests(false);
+
+		expect(__imageInternals.getTmuxPassthroughWarning("kitty")).toContain("allow-passthrough is off");
+	});
+
+	it("does not warn when tmux allow-passthrough is enabled", () => {
+		process.env.TMUX = "/tmp/tmux-1000/default,123,0";
+		__imageInternals.setTmuxAllowPassthroughOverrideForTests(true);
+
+		expect(__imageInternals.getTmuxPassthroughWarning("kitty")).toBeNull();
+	});
+
+	it("renders explicit warning for read image when tmux passthrough is off", async () => {
+		process.env.TMUX = "/tmp/tmux-1000/default,123,0";
+		process.env.TERM_PROGRAM = "tmux";
+		process.env.KITTY_WINDOW_ID = "1";
+		__imageInternals.setTmuxAllowPassthroughOverrideForTests(false);
+
+		const readTool = loadReadTool(async () => ({
+			content: [{ type: "image", data: Buffer.from("fake").toString("base64"), mimeType: "image/png" }],
+		}));
+
+		const result = await readTool.execute("t1", { path: "media/inline-image.png" }, null, null, {});
+		const rendered = readTool.renderResult(result, {}, {}, {
+			lastComponent: new MockText(),
+			isError: false,
+			state: {},
+			expanded: false,
+			invalidate: () => {},
+		});
+
+		expect(rendered.getText()).toContain("allow-passthrough is off");
+	});
+
+	it("warns on non-PNG payloads for kitty protocol", async () => {
+		process.env.TERM_PROGRAM = "kitty";
+
+		const readTool = loadReadTool(async () => ({
+			content: [{ type: "image", data: Buffer.from("jpeg").toString("base64"), mimeType: "image/jpeg" }],
+		}));
+
+		const result = await readTool.execute("t1", { path: "media/photo.jpg" }, null, null, {});
+		const rendered = readTool.renderResult(result, {}, {}, {
+			lastComponent: new MockText(),
+			isError: false,
+			state: {},
+			expanded: false,
+			invalidate: () => {},
+		});
+
+		expect(rendered.getText()).toContain("supports PNG payloads");
+	});
+});