@heyhuynhgiabuu/pi-pretty 0.3.0 → 0.3.2

package/README.md

@@ -41,7 +41,15 @@ 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`)
 
 ## Configuration
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@heyhuynhgiabuu/pi-pretty",
-	"version": "0.3.0",
+	"version": "0.3.2",
 	"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/src/fff-helpers.ts

@@ -0,0 +1,73 @@
+/**
+ * FFF helper functions — extracted for testability.
+ *
+ * Pure functions and classes used by the FFF integration in index.ts.
+ */
+
+/**
+ * Store for FFF grep pagination cursors.
+ * Evicts oldest entry when exceeding maxSize.
+ */
+export class CursorStore {
+	private cursors = new Map<string, any>();
+	private counter = 0;
+	private maxSize: number;
+
+	constructor(maxSize = 200) {
+		this.maxSize = maxSize;
+	}
+
+	store(cursor: any): string {
+		const id = `fff_c${++this.counter}`;
+		this.cursors.set(id, cursor);
+		if (this.cursors.size > this.maxSize) {
+			const first = this.cursors.keys().next().value;
+			if (first) this.cursors.delete(first);
+		}
+		return id;
+	}
+
+	get(id: string): any | undefined {
+		return this.cursors.get(id);
+	}
+
+	get size(): number {
+		return this.cursors.size;
+	}
+}
+
+/**
+ * Convert FFF GrepResult items to ripgrep-style "file:line:content" text.
+ * This ensures pi-pretty's renderGrepResults works unchanged.
+ */
+export function fffFormatGrepText(items: any[], limit: number): string {
+	const capped = items.slice(0, limit);
+	if (!capped.length) return "No matches found";
+
+	const lines: string[] = [];
+	let currentFile = "";
+
+	for (const match of capped) {
+		if (match.relativePath !== currentFile) {
+			if (currentFile) lines.push("");
+			currentFile = match.relativePath;
+		}
+		if (match.contextBefore?.length) {
+			const startLine = match.lineNumber - match.contextBefore.length;
+			for (let i = 0; i < match.contextBefore.length; i++) {
+				lines.push(`${match.relativePath}-${startLine + i}-${match.contextBefore[i]}`);
+			}
+		}
+		const content =
+			match.lineContent.length > 500 ? `${match.lineContent.slice(0, 500)}...` : match.lineContent;
+		lines.push(`${match.relativePath}:${match.lineNumber}:${content}`);
+		if (match.contextAfter?.length) {
+			const startLine = match.lineNumber + 1;
+			for (let i = 0; i < match.contextAfter.length; i++) {
+				lines.push(`${match.relativePath}-${startLine + i}-${match.contextAfter[i]}`);
+			}
+		}
+	}
+
+	return lines.join("\n");
+}

package/src/index.ts

@@ -23,12 +23,15 @@
  *   • 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";
 
 import { codeToANSI } from "@shikijs/cli";
 import type { BundledLanguage, BundledTheme } from "shiki";
 
+import { CursorStore, fffFormatGrepText } from "./fff-helpers.js";
+
 // ---------------------------------------------------------------------------
 // Config
 // ---------------------------------------------------------------------------
@@ -215,7 +218,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.
@@ -223,27 +264,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";
@@ -253,18 +301,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
@@ -676,25 +773,6 @@ async function renderGrepResults(text: string, pattern: string): Promise<string>
 // If not, falls back to wrapping SDK tools (current behavior).
 // ---------------------------------------------------------------------------
 
-class CursorStore {
-	private cursors = new Map<string, any>();
-	private counter = 0;
-
-	store(cursor: any): string {
-		const id = `fff_c${++this.counter}`;
-		this.cursors.set(id, cursor);
-		if (this.cursors.size > 200) {
-			const first = this.cursors.keys().next().value;
-			if (first) this.cursors.delete(first);
-		}
-		return id;
-	}
-
-	get(id: string): any | undefined {
-		return this.cursors.get(id);
-	}
-}
-
 const _cursorStore = new CursorStore();
 let _fffModule: any = null;
 let _fffFinder: any = null;
@@ -730,47 +808,21 @@ function fffDestroy(): void {
 	_fffPartialIndex = false;
 }
 
-/**
- * Convert FFF GrepResult items to ripgrep-style "file:line:content" text.
- * This ensures pi-pretty's renderGrepResults works unchanged.
- */
-function fffFormatGrepText(items: any[], limit: number): string {
-	const capped = items.slice(0, limit);
-	if (!capped.length) return "No matches found";
-
-	const lines: string[] = [];
-	let currentFile = "";
-
-	for (const match of capped) {
-		if (match.relativePath !== currentFile) {
-			if (currentFile) lines.push("");
-			currentFile = match.relativePath;
-		}
-		if (match.contextBefore?.length) {
-			const startLine = match.lineNumber - match.contextBefore.length;
-			for (let i = 0; i < match.contextBefore.length; i++) {
-				lines.push(`${match.relativePath}-${startLine + i}-${match.contextBefore[i]}`);
-			}
-		}
-		const content =
-			match.lineContent.length > 500 ? `${match.lineContent.slice(0, 500)}...` : match.lineContent;
-		lines.push(`${match.relativePath}:${match.lineNumber}:${content}`);
-		if (match.contextAfter?.length) {
-			const startLine = match.lineNumber + 1;
-			for (let i = 0; i < match.contextAfter.length; i++) {
-				lines.push(`${match.relativePath}-${startLine + i}-${match.contextAfter[i]}`);
-			}
-		}
-	}
-
-	return lines.join("\n");
-}
-
 // ---------------------------------------------------------------------------
 // Extension entry point
 // ---------------------------------------------------------------------------
 
-export default function piPrettyExtension(pi: any): void {
+/**
+ * Dependencies that can be injected for testing.
+ * In production, omit `deps` — the extension uses require() to load them.
+ */
+export interface PiPrettyDeps {
+	sdk: any;
+	TextComponent: any;
+	fffModule?: any;
+}
+
+export default function piPrettyExtension(pi: any, deps?: PiPrettyDeps): void {
 	let createReadTool: any;
 	let createBashTool: any;
 	let createLsTool: any;
@@ -780,16 +832,31 @@ export default function piPrettyExtension(pi: any): void {
 
 	let sdk: any;
 
-	try {
-		sdk = require("@mariozechner/pi-coding-agent");
+	if (deps) {
+		// Test path: use injected dependencies, reset module state
+		sdk = deps.sdk;
 		createReadTool = sdk.createReadToolDefinition ?? sdk.createReadTool;
 		createBashTool = sdk.createBashToolDefinition ?? sdk.createBashTool;
 		createLsTool = sdk.createLsToolDefinition ?? sdk.createLsTool;
 		createFindTool = sdk.createFindToolDefinition ?? sdk.createFindTool;
 		createGrepTool = sdk.createGrepToolDefinition ?? sdk.createGrepTool;
-		TextComponent = require("@mariozechner/pi-tui").Text;
-	} catch {
-		return;
+		TextComponent = deps.TextComponent;
+		_fffModule = deps.fffModule ?? null;
+		_fffFinder = null;
+		_fffPartialIndex = false;
+		_fffDbDir = null;
+	} else {
+		try {
+			sdk = require("@mariozechner/pi-coding-agent");
+			createReadTool = sdk.createReadToolDefinition ?? sdk.createReadTool;
+			createBashTool = sdk.createBashToolDefinition ?? sdk.createBashTool;
+			createLsTool = sdk.createLsToolDefinition ?? sdk.createLsTool;
+			createFindTool = sdk.createFindToolDefinition ?? sdk.createFindTool;
+			createGrepTool = sdk.createGrepToolDefinition ?? sdk.createGrepTool;
+			TextComponent = require("@mariozechner/pi-tui").Text;
+		} catch {
+			return;
+		}
 	}
 	if (!createReadTool || !TextComponent) return;
 
@@ -802,16 +869,24 @@ export default function piPrettyExtension(pi: any): void {
 	// ===================================================================
 
 	const getAgentDir = (sdk as any).getAgentDir;
-	try {
-		_fffModule = require("@ff-labs/fff-node");
-		if (getAgentDir) {
-			_fffDbDir = join(getAgentDir(), "fff");
-			try {
-				mkdirSync(_fffDbDir, { recursive: true });
-			} catch {}
+	if (!deps) {
+		// Only try require() in production — tests inject fffModule via deps
+		try {
+			_fffModule = require("@ff-labs/fff-node");
+			if (getAgentDir) {
+				_fffDbDir = join(getAgentDir(), "fff");
+				try {
+					mkdirSync(_fffDbDir, { recursive: true });
+				} catch {}
+			}
+		} catch {
+			/* FFF not installed — SDK tools will be used */
 		}
-	} catch {
-		/* FFF not installed — SDK tools will be used */
+	} else if (_fffModule && getAgentDir) {
+		_fffDbDir = join(getAgentDir(), "fff");
+		try {
+			mkdirSync(_fffDbDir, { recursive: true });
+		} catch {}
 	}
 
 	pi.on("session_start", async (_event: any, ctx: any) => {
@@ -936,9 +1011,16 @@ export default function piPrettyExtension(pi: any): 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(

package/test/fff-integration.test.ts

@@ -0,0 +1,455 @@
+/**
+ * Tests for pi-pretty FFF integration vs SDK fallback.
+ *
+ * 1. Unit tests for CursorStore + fffFormatGrepText (extracted helpers)
+ * 2. Integration tests via dependency injection (PiPrettyDeps)
+ *    - SDK fallback path (no FFF)
+ *    - FFF path (FFF injected)
+ *    - Graceful degradation (FFF fails → SDK fallback)
+ */
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { CursorStore, fffFormatGrepText } from "../src/fff-helpers.js";
+import piPrettyExtension, { type PiPrettyDeps } from "../src/index.js";
+
+// =========================================================================
+// 1. Unit tests — pure functions
+// =========================================================================
+
+describe("CursorStore", () => {
+	it("stores and retrieves a cursor", () => {
+		const store = new CursorStore();
+		const cursor = { page: 2, offset: 50 };
+		const id = store.store(cursor);
+		expect(id).toMatch(/^fff_c\d+$/);
+		expect(store.get(id)).toBe(cursor);
+	});
+
+	it("returns undefined for unknown id", () => {
+		expect(new CursorStore().get("fff_c999")).toBeUndefined();
+	});
+
+	it("increments ids sequentially", () => {
+		const store = new CursorStore();
+		const n1 = Number.parseInt(store.store("a").slice(5), 10);
+		const n2 = Number.parseInt(store.store("b").slice(5), 10);
+		expect(n2).toBe(n1 + 1);
+	});
+
+	it("evicts oldest when exceeding maxSize", () => {
+		const store = new CursorStore(3);
+		const id1 = store.store("a");
+		store.store("b"); store.store("c");
+		expect(store.size).toBe(3);
+		store.store("d");
+		expect(store.size).toBe(3);
+		expect(store.get(id1)).toBeUndefined();
+	});
+
+	it("default maxSize is 200", () => {
+		const store = new CursorStore();
+		const ids: string[] = [];
+		for (let i = 0; i < 201; i++) ids.push(store.store(i));
+		expect(store.size).toBe(200);
+		expect(store.get(ids[0])).toBeUndefined();
+		expect(store.get(ids[200])).toBe(200);
+	});
+});
+
+describe("fffFormatGrepText", () => {
+	it("empty → 'No matches found'", () => {
+		expect(fffFormatGrepText([], 100)).toBe("No matches found");
+	});
+
+	it("single match → file:line:content", () => {
+		const items = [{ relativePath: "src/a.ts", lineNumber: 42, lineContent: "const x = 1;" }];
+		expect(fffFormatGrepText(items, 100)).toBe("src/a.ts:42:const x = 1;");
+	});
+
+	it("groups by file with blank separator", () => {
+		const items = [
+			{ relativePath: "a.ts", lineNumber: 1, lineContent: "L1" },
+			{ relativePath: "a.ts", lineNumber: 5, lineContent: "L5" },
+			{ relativePath: "b.ts", lineNumber: 10, lineContent: "LB" },
+		];
+		expect(fffFormatGrepText(items, 100).split("\n")).toEqual(["a.ts:1:L1", "a.ts:5:L5", "", "b.ts:10:LB"]);
+	});
+
+	it("truncates >500 char lines", () => {
+		const items = [{ relativePath: "a.ts", lineNumber: 1, lineContent: "x".repeat(600) }];
+		expect(fffFormatGrepText(items, 100)).toBe(`a.ts:1:${"x".repeat(500)}...`);
+	});
+
+	it("respects limit", () => {
+		const items = [
+			{ relativePath: "a.ts", lineNumber: 1, lineContent: "one" },
+			{ relativePath: "a.ts", lineNumber: 2, lineContent: "two" },
+			{ relativePath: "a.ts", lineNumber: 3, lineContent: "three" },
+		];
+		expect(fffFormatGrepText(items, 2).split("\n")).toHaveLength(2);
+	});
+
+	it("contextBefore with dash format", () => {
+		const items = [{
+			relativePath: "a.ts", lineNumber: 5, lineContent: "match",
+			contextBefore: ["before1", "before2"],
+		}];
+		const lines = fffFormatGrepText(items, 100).split("\n");
+		expect(lines[0]).toBe("a.ts-3-before1");
+		expect(lines[1]).toBe("a.ts-4-before2");
+		expect(lines[2]).toBe("a.ts:5:match");
+	});
+
+	it("contextAfter with dash format", () => {
+		const items = [{
+			relativePath: "a.ts", lineNumber: 5, lineContent: "match",
+			contextAfter: ["after1"],
+		}];
+		const lines = fffFormatGrepText(items, 100).split("\n");
+		expect(lines[0]).toBe("a.ts:5:match");
+		expect(lines[1]).toBe("a.ts-6-after1");
+	});
+});
+
+// =========================================================================
+// 2. Integration tests — via PiPrettyDeps injection
+// =========================================================================
+
+// Mock SDK tool factories
+function mockToolFactory(exec: ReturnType<typeof vi.fn>) {
+	return (_cwd: string) => ({
+		name: "mock",
+		description: "mock",
+		parameters: { type: "object", properties: {} },
+		execute: exec,
+	});
+}
+
+// Mock FFF finder
+function mkFinder(overrides?: Record<string, any>) {
+	return {
+		isDestroyed: false,
+		waitForScan: vi.fn().mockResolvedValue({ ok: true, value: true }),
+		fileSearch: vi.fn().mockReturnValue({
+			ok: true,
+			value: {
+				items: [{ relativePath: "src/index.ts" }, { relativePath: "src/main.ts" }],
+				totalMatched: 2,
+			},
+		}),
+		grep: vi.fn().mockReturnValue({
+			ok: true,
+			value: {
+				items: [{ relativePath: "src/index.ts", lineNumber: 42, lineContent: "const x = 1;" }],
+				totalMatched: 1,
+				nextCursor: null,
+			},
+		}),
+		multiGrep: vi.fn().mockReturnValue({
+			ok: true,
+			value: {
+				items: [
+					{ relativePath: "src/index.ts", lineNumber: 10, lineContent: "import {foo}" },
+					{ relativePath: "src/main.ts", lineNumber: 5, lineContent: "const baz" },
+				],
+				totalMatched: 2,
+				nextCursor: null,
+			},
+		}),
+		destroy: vi.fn(),
+		...overrides,
+	};
+}
+
+describe("piPrettyExtension integration", () => {
+	let tools: Map<string, any>;
+	let events: Map<string, Function>;
+	let mockPi: any;
+
+	// SDK execute mocks
+	const findExec = vi.fn();
+	const grepExec = vi.fn();
+	const readExec = vi.fn();
+	const bashExec = vi.fn();
+	const lsExec = vi.fn();
+
+	function makeDeps(withFFF: boolean, finderOverrides?: Record<string, any>): PiPrettyDeps {
+		const finder = mkFinder(finderOverrides);
+		return {
+			sdk: {
+				createReadToolDefinition: mockToolFactory(readExec),
+				createBashToolDefinition: mockToolFactory(bashExec),
+				createLsToolDefinition: mockToolFactory(lsExec),
+				createFindToolDefinition: mockToolFactory(findExec),
+				createGrepToolDefinition: mockToolFactory(grepExec),
+				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,
+		};
+	}
+
+	beforeEach(() => {
+		tools = new Map();
+		events = new Map();
+		mockPi = {
+			registerTool: vi.fn((t: any) => tools.set(t.name, t)),
+			registerCommand: vi.fn((c: any) => {}),
+			on: vi.fn((e: string, h: Function) => events.set(e, h)),
+		};
+
+		for (const fn of [findExec, grepExec, readExec, bashExec, lsExec]) fn.mockReset();
+		findExec.mockResolvedValue({ content: [{ type: "text", text: "src/index.ts\nsrc/main.ts" }] });
+		grepExec.mockResolvedValue({ content: [{ type: "text", text: "src/index.ts:10:const x = 1;" }] });
+		readExec.mockResolvedValue({ content: [{ type: "text", text: "content" }] });
+		bashExec.mockResolvedValue({ content: [{ type: "text", text: "output" }] });
+		lsExec.mockResolvedValue({ content: [{ type: "text", text: "f1\nf2" }] });
+	});
+
+	function load(withFFF = false, finderOverrides?: Record<string, any>) {
+		const deps = makeDeps(withFFF, finderOverrides);
+		piPrettyExtension(mockPi, deps);
+	}
+
+	async function loadWithFFF(finderOverrides?: Record<string, any>) {
+		load(true, finderOverrides);
+		const start = events.get("session_start")!;
+		expect(start, "session_start not registered").toBeDefined();
+		await start({}, { cwd: "/tmp/test" });
+	}
+
+	// ---- registration --------------------------------------------------
+
+	describe("tool registration", () => {
+		it("registers core tools (find, grep, read, bash, ls)", () => {
+			load();
+			for (const n of ["find", "grep", "read", "bash", "ls"]) {
+				expect(tools.has(n), `missing: ${n}`).toBe(true);
+			}
+		});
+
+		it("registers multi_grep when FFF available", () => {
+			load(true);
+			expect(tools.has("multi_grep")).toBe(true);
+		});
+
+		it("NO multi_grep when FFF unavailable", () => {
+			load(false);
+			expect(tools.has("multi_grep")).toBe(false);
+		});
+
+		it("registers session_start + session_shutdown", () => {
+			load();
+			expect(events.has("session_start")).toBe(true);
+			expect(events.has("session_shutdown")).toBe(true);
+		});
+	});
+
+	// ---- find: SDK fallback (no FFF) -----------------------------------
+
+	describe("find — SDK fallback", () => {
+		it("delegates to SDK when FFF not loaded", async () => {
+			load(false);
+			const r = await tools.get("find")!.execute("t1", { pattern: "*.ts" }, null, null, {});
+			expect(findExec).toHaveBeenCalledOnce();
+			expect(r.details._type).toBe("findResult");
+			expect(r.details.pattern).toBe("*.ts");
+		});
+
+		it("counts matches from SDK text", async () => {
+			findExec.mockResolvedValue({ content: [{ type: "text", text: "a.ts\nb.ts\nc.ts" }] });
+			load(false);
+			const r = await tools.get("find")!.execute("t1", { pattern: "*.ts" }, null, null, {});
+			expect(r.details.matchCount).toBe(3);
+		});
+	});
+
+	// ---- grep: SDK fallback (no FFF) -----------------------------------
+
+	describe("grep — SDK fallback", () => {
+		it("delegates to SDK when FFF not loaded", async () => {
+			load(false);
+			const r = await tools.get("grep")!.execute("t1", { pattern: "TODO" }, null, null, {});
+			expect(grepExec).toHaveBeenCalledOnce();
+			expect(r.details._type).toBe("grepResult");
+		});
+
+		it("counts ripgrep-style matches", async () => {
+			grepExec.mockResolvedValue({
+				content: [{ type: "text", text: "a.ts:1:TODO\na.ts:5:TODO\nb.ts:10:TODO" }],
+			});
+			load(false);
+			const r = await tools.get("grep")!.execute("t1", { pattern: "TODO" }, null, null, {});
+			expect(r.details.matchCount).toBe(3);
+		});
+	});
+
+	// ---- find: FFF path ------------------------------------------------
+
+	describe("find — FFF path", () => {
+		it("uses FFF fileSearch when initialized", async () => {
+			await loadWithFFF();
+			const r = await tools.get("find")!.execute("t1", { pattern: "*.ts" }, null, null, {});
+			expect(findExec).not.toHaveBeenCalled();
+			expect(r.details._type).toBe("findResult");
+			expect(r.content[0].text).toContain("src/index.ts");
+		});
+
+		it("falls back to SDK on FFF { ok: false }", async () => {
+			await loadWithFFF({
+				fileSearch: vi.fn().mockReturnValue({ ok: false, error: "fail" }),
+			});
+			await tools.get("find")!.execute("t1", { pattern: "*.ts" }, null, null, {});
+			expect(findExec).toHaveBeenCalledOnce();
+		});
+
+		it("falls back to SDK on FFF throw", async () => {
+			await loadWithFFF({
+				fileSearch: vi.fn().mockImplementation(() => { throw new Error("crash"); }),
+			});
+			await tools.get("find")!.execute("t1", { pattern: "*.ts" }, null, null, {});
+			expect(findExec).toHaveBeenCalledOnce();
+		});
+
+		it("respects limit param", async () => {
+			const fileSearch = vi.fn().mockReturnValue({
+				ok: true,
+				value: { items: Array.from({ length: 50 }, (_, i) => ({ relativePath: `f${i}.ts` })), totalMatched: 50 },
+			});
+			await loadWithFFF({ fileSearch });
+			await tools.get("find")!.execute("t1", { pattern: "*.ts", limit: 5 }, null, null, {});
+			expect(fileSearch).toHaveBeenCalledWith(expect.any(String), expect.objectContaining({ pageSize: 5 }));
+		});
+
+		it("includes path in search query", async () => {
+			const fileSearch = vi.fn().mockReturnValue({ ok: true, value: { items: [], totalMatched: 0 } });
+			await loadWithFFF({ fileSearch });
+			await tools.get("find")!.execute("t1", { pattern: "*.ts", path: "src/" }, null, null, {});
+			expect(fileSearch).toHaveBeenCalledWith("src/ *.ts", expect.any(Object));
+		});
+
+		it("shows partial-index + limit notices", async () => {
+			await loadWithFFF({
+				waitForScan: vi.fn().mockResolvedValue({ ok: true, value: false }),
+				fileSearch: vi.fn().mockReturnValue({
+					ok: true,
+					value: { items: Array.from({ length: 200 }, (_, i) => ({ relativePath: `f${i}` })), totalMatched: 500 },
+				}),
+			});
+			const text = (await tools.get("find")!.execute("t1", { pattern: "*" }, null, null, {})).content[0].text;
+			expect(text).toContain("partial file index");
+			expect(text).toContain("200 limit reached");
+			expect(text).toContain("500 total matches");
+		});
+	});
+
+	// ---- grep: FFF path ------------------------------------------------
+
+	describe("grep — FFF path", () => {
+		it("uses FFF grep when initialized", async () => {
+			await loadWithFFF();
+			const r = await tools.get("grep")!.execute("t1", { pattern: "TODO" }, null, null, {});
+			expect(grepExec).not.toHaveBeenCalled();
+			expect(r.content[0].text).toContain("src/index.ts:42:const x = 1;");
+		});
+
+		it("literal=true → mode=plain", async () => {
+			const grep = vi.fn().mockReturnValue({ ok: true, value: { items: [], totalMatched: 0, nextCursor: null } });
+			await loadWithFFF({ grep });
+			await tools.get("grep")!.execute("t1", { pattern: "foo", literal: true }, null, null, {});
+			expect(grep).toHaveBeenCalledWith(expect.any(String), expect.objectContaining({ mode: "plain" }));
+		});
+
+		it("no literal → mode=regex", async () => {
+			const grep = vi.fn().mockReturnValue({ ok: true, value: { items: [], totalMatched: 0, nextCursor: null } });
+			await loadWithFFF({ grep });
+			await tools.get("grep")!.execute("t1", { pattern: "foo.*bar" }, null, null, {});
+			expect(grep).toHaveBeenCalledWith(expect.any(String), expect.objectContaining({ mode: "regex" }));
+		});
+
+		it("glob prepended to query", async () => {
+			const grep = vi.fn().mockReturnValue({ ok: true, value: { items: [], totalMatched: 0, nextCursor: null } });
+			await loadWithFFF({ grep });
+			await tools.get("grep")!.execute("t1", { pattern: "TODO", glob: "*.ts" }, null, null, {});
+			expect(grep).toHaveBeenCalledWith("*.ts TODO", expect.any(Object));
+		});
+
+		it("falls back to SDK on throw", async () => {
+			await loadWithFFF({ grep: vi.fn().mockImplementation(() => { throw new Error("crash"); }) });
+			const r = await tools.get("grep")!.execute("t1", { pattern: "TODO" }, null, null, {});
+			expect(grepExec).toHaveBeenCalledOnce();
+			expect(r.details._type).toBe("grepResult");
+		});
+
+		it("cursor notice when nextCursor present", async () => {
+			await loadWithFFF({
+				grep: vi.fn().mockReturnValue({
+					ok: true,
+					value: { items: [{ relativePath: "a.ts", lineNumber: 1, lineContent: "hit" }], totalMatched: 1, nextCursor: { p: 2 } },
+				}),
+			});
+			const text = (await tools.get("grep")!.execute("t1", { pattern: "hit" }, null, null, {})).content[0].text;
+			expect(text).toContain("More results available");
+			expect(text).toMatch(/cursor="fff_c\d+"/);
+		});
+	});
+
+	// ---- multi_grep (FFF only) -----------------------------------------
+
+	describe("multi_grep", () => {
+		it("error for empty patterns", async () => {
+			await loadWithFFF();
+			const r = await tools.get("multi_grep")!.execute("t1", { patterns: [] }, null, null, null);
+			expect(r.content[0].text).toContain("patterns array must have at least 1 element");
+		});
+
+		it("error when FFF not initialized (no session_start)", async () => {
+			load(true);
+			const r = await tools.get("multi_grep")!.execute("t1", { patterns: ["foo"] }, null, null, null);
+			expect(r.content[0].text).toContain("FFF not initialized");
+		});
+
+		it("returns multiGrep results", async () => {
+			await loadWithFFF();
+			const r = await tools.get("multi_grep")!.execute("t1", { patterns: ["foo", "bar"] }, null, null, null);
+			expect(r.details._type).toBe("grepResult");
+			expect(r.content[0].text).toContain("src/index.ts");
+		});
+
+		it("aborted signal → Aborted", async () => {
+			await loadWithFFF();
+			const r = await tools.get("multi_grep")!.execute("t1", { patterns: ["x"] }, { aborted: true }, null, null);
+			expect(r.content[0].text).toBe("Aborted");
+		});
+
+		it("multiGrep failure → error text", async () => {
+			await loadWithFFF({
+				multiGrep: vi.fn().mockReturnValue({ ok: false, error: "compile failed" }),
+			});
+			const r = await tools.get("multi_grep")!.execute("t1", { patterns: ["[bad"] }, null, null, null);
+			expect(r.content[0].text).toContain("compile failed");
+		});
+
+		it("passes constraints and context", async () => {
+			const multiGrep = vi.fn().mockReturnValue({ ok: true, value: { items: [], totalMatched: 0, nextCursor: null } });
+			await loadWithFFF({ multiGrep });
+			await tools.get("multi_grep")!.execute("t1", { patterns: ["a", "b"], constraints: "*.ts", context: 2 }, null, null, null);
+			expect(multiGrep).toHaveBeenCalledWith(expect.objectContaining({
+				patterns: ["a", "b"], constraints: "*.ts", beforeContext: 2, afterContext: 2,
+			}));
+		});
+	});
+
+	// ---- session lifecycle ---------------------------------------------
+
+	describe("session lifecycle", () => {
+		it("shutdown → subsequent find falls back to SDK", async () => {
+			await loadWithFFF();
+			await events.get("session_shutdown")!();
+			await tools.get("find")!.execute("t1", { pattern: "*.ts" }, null, null, {});
+			expect(findExec).toHaveBeenCalledOnce();
+		});
+	});
+});

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");
+	});
+});