@heyhuynhgiabuu/pi-pretty 0.5.3 → 0.6.0

package/package.json

@@ -1,16 +1,16 @@
 {
 	"name": "@heyhuynhgiabuu/pi-pretty",
-	"version": "0.5.3",
+	"version": "0.6.0",
 	"description": "Pretty terminal output for pi — syntax-highlighted file reads, colored bash output, tree-view directory listings, and more.",
 	"author": "huynhgiabuu",
 	"license": "MIT",
 	"repository": {
 		"type": "git",
-		"url": "git+https://github.com/buddingnewinsights/pi-pretty.git"
+		"url": "git+https://github.com/heyhuynhgiabuu/pi-pretty.git"
 	},
-	"homepage": "https://github.com/buddingnewinsights/pi-pretty#readme",
+	"homepage": "https://github.com/heyhuynhgiabuu/pi-pretty#readme",
 	"bugs": {
-		"url": "https://github.com/buddingnewinsights/pi-pretty/issues"
+		"url": "https://github.com/heyhuynhgiabuu/pi-pretty/issues"
 	},
 	"keywords": [
 		"pi-package",
@@ -22,14 +22,12 @@
 		"pretty-print"
 	],
 	"dependencies": {
-		"@ff-labs/fff-node": "0.5.2",
+		"@ff-labs/fff-node": "^0.9.4",
 		"@shikijs/cli": "^4.0.2"
 	},
 	"peerDependencies": {
 		"@earendil-works/pi-coding-agent": "*",
-		"@earendil-works/pi-tui": "*",
-		"@mariozechner/pi-coding-agent": "*",
-		"@mariozechner/pi-tui": "*"
+		"@earendil-works/pi-tui": "*"
 	},
 	"devDependencies": {
 		"@earendil-works/pi-coding-agent": "*",

package/src/config.ts

@@ -0,0 +1,250 @@
+/**
+ * pi-pretty: ANSI codes, icons, theme, and environment config.
+ */
+
+import { readFileSync } from "node:fs";
+import { basename, extname, join } from "node:path";
+
+// ---------------------------------------------------------------------------
+// ANSI
+// ---------------------------------------------------------------------------
+
+export let RST = "\x1b[0m";
+const BOLD = "\x1b[1m";
+
+export const FG_LNUM = "\x1b[38;2;100;100;100m";
+export const FG_DIM = "\x1b[38;2;80;80;80m";
+export const FG_RULE = "\x1b[38;2;50;50;50m";
+export const FG_GREEN = "\x1b[38;2;100;180;120m";
+export const FG_RED = "\x1b[38;2;200;100;100m";
+export const FG_YELLOW = "\x1b[38;2;220;180;80m";
+export const FG_BLUE = "\x1b[38;2;100;140;220m";
+export const FG_MUTED = "\x1b[38;2;139;148;158m";
+
+const BG_DEFAULT = "\x1b[49m";
+export let BG_BASE = BG_DEFAULT;
+export let BG_ERROR = BG_DEFAULT;
+
+// ---------------------------------------------------------------------------
+// Theme
+// ---------------------------------------------------------------------------
+
+import type { ThemeLike } from "./types.js";
+
+type BgThemeLike = { getBgAnsi?: (key: string) => string };
+
+const ESC_RE = "\u001b";
+
+function parseAnsiRgb(ansi: string): { r: number; g: number; b: number } | null {
+	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;
+}
+
+function getThemeBgAnsi(theme: BgThemeLike, key: string): string | null {
+	try {
+		const bgAnsi = theme.getBgAnsi?.(key);
+		return bgAnsi && parseAnsiRgb(bgAnsi) ? bgAnsi : null;
+	} catch {
+		return null;
+	}
+}
+
+function hexToAnsiBg(hex: string): string | null {
+	const m = hex.match(/^#?([0-9a-fA-F]{2})([0-9a-fA-F]{2})([0-9a-fA-F]{2})$/);
+	if (!m) return null;
+	const r = Number.parseInt(m[1], 16);
+	const g = Number.parseInt(m[2], 16);
+	const b = Number.parseInt(m[3], 16);
+	return `\x1b[48;2;${r};${g};${b}m`;
+}
+
+interface PrettyConfig {
+	background?: {
+		tool?: string;
+		error?: string;
+	};
+}
+
+function readPrettyConfig(agentDir?: string): PrettyConfig {
+	if (!agentDir) return {};
+	try {
+		const raw = readFileSync(join(agentDir, "pi-pretty.json"), "utf8");
+		const parsed = JSON.parse(raw) as PrettyConfig;
+		if (parsed.background) {
+			if (parsed.background.tool && !hexToAnsiBg(parsed.background.tool)) {
+				parsed.background.tool = undefined;
+			}
+			if (parsed.background.error && !hexToAnsiBg(parsed.background.error)) {
+				parsed.background.error = undefined;
+			}
+			if (!parsed.background.tool && !parsed.background.error) {
+				parsed.background = undefined;
+			}
+		}
+		return parsed;
+	} catch {
+		return {};
+	}
+}
+
+function applyPrettyConfigBg(agentDir?: string): boolean {
+	const config = readPrettyConfig(agentDir);
+	if (!config.background?.tool) return false;
+	const toolBg = hexToAnsiBg(config.background.tool);
+	if (!toolBg) return false;
+	BG_BASE = toolBg;
+	BG_ERROR = config.background.error ? (hexToAnsiBg(config.background.error) ?? toolBg) : toolBg;
+	RST = "\x1b[0m";
+	return true;
+}
+
+export function resolveBaseBackground(theme: BgThemeLike | null | undefined): void {
+	const home = process.env.HOME;
+	const configDir = process.env.PRETTY_CONFIG_DIR ?? (home ? join(home, ".pi/agent") : undefined);
+	if (applyPrettyConfigBg(configDir)) return;
+	if (!theme?.getBgAnsi) return;
+	BG_BASE = getThemeBgAnsi(theme, "toolSuccessBg") ?? getThemeBgAnsi(theme, "toolBg") ?? getThemeBgAnsi(theme, "background") ?? BG_DEFAULT;
+	BG_ERROR = getThemeBgAnsi(theme, "toolErrorBg") ?? BG_BASE;
+	RST = "\x1b[0m";
+}
+
+// ---------------------------------------------------------------------------
+// Terminal
+// ---------------------------------------------------------------------------
+
+export function termWidth(): number {
+	if (process.stdout.columns) return Math.max(1, Math.min(process.stdout.columns, 210));
+	const raw = (process.stderr as NodeJS.WriteStream & { columns?: number }).columns ||
+		Number.parseInt(process.env.COLUMNS ?? "", 10) || 200;
+	return Math.max(1, Math.min(raw - 4, 210));
+}
+
+// ---------------------------------------------------------------------------
+// File-type icons — Nerd Font glyphs
+// ---------------------------------------------------------------------------
+
+const ICONS_MODE = (process.env.PRETTY_ICONS ?? "nerd").toLowerCase();
+export const USE_ICONS = ICONS_MODE !== "none" && ICONS_MODE !== "off";
+
+export const NF_DIR = `${FG_BLUE}\ue5ff${RST}`;
+export const NF_DEFAULT = `${FG_DIM}\uf15b${RST}`;
+
+const EXT_ICON: Record<string, string> = {
+	ts: `\x1b[38;2;49;120;198m\ue628${RST}`,
+	tsx: `\x1b[38;2;49;120;198m\ue7ba${RST}`,
+	js: `\x1b[38;2;241;224;90m\ue74e${RST}`,
+	jsx: `\x1b[38;2;97;218;251m\ue7ba${RST}`,
+	mjs: `\x1b[38;2;241;224;90m\ue74e${RST}`,
+	cjs: `\x1b[38;2;241;224;90m\ue74e${RST}`,
+	py: `\x1b[38;2;55;118;171m\ue73c${RST}`,
+	rs: `\x1b[38;2;222;165;132m\ue7a8${RST}`,
+	go: `\x1b[38;2;0;173;216m\ue724${RST}`,
+	java: `\x1b[38;2;204;62;68m\ue738${RST}`,
+	swift: `\x1b[38;2;255;172;77m\ue755${RST}`,
+	rb: `\x1b[38;2;204;52;45m\ue739${RST}`,
+	kt: `\x1b[38;2;126;103;200m\ue634${RST}`,
+	c: `\x1b[38;2;85;154;211m\ue61e${RST}`,
+	cpp: `\x1b[38;2;85;154;211m\ue61d${RST}`,
+	cs: `\x1b[38;2;104;33;122m\ue648${RST}`,
+	html: `\x1b[38;2;228;77;38m\ue736${RST}`,
+	css: `\x1b[38;2;66;165;245m\ue749${RST}`,
+	scss: `\x1b[38;2;207;100;154m\ue749${RST}`,
+	vue: `\x1b[38;2;65;184;131m\ue6a0${RST}`,
+	svelte: `\x1b[38;2;255;62;0m\ue697${RST}`,
+	json: `\x1b[38;2;241;224;90m\ue60b${RST}`,
+	yaml: `\x1b[38;2;160;116;196m\ue6a8${RST}`,
+	yml: `\x1b[38;2;160;116;196m\ue6a8${RST}`,
+	toml: `\x1b[38;2;160;116;196m\ue6b2${RST}`,
+	xml: `\x1b[38;2;228;77;38m\ue619${RST}`,
+	md: `\x1b[38;2;66;165;245m\ue73e${RST}`,
+	mdx: `\x1b[38;2;66;165;245m\ue73e${RST}`,
+	sql: `\x1b[38;2;218;218;218m\ue706${RST}`,
+	sh: `\x1b[38;2;137;180;130m\ue795${RST}`,
+	bash: `\x1b[38;2;137;180;130m\ue795${RST}`,
+	zsh: `\x1b[38;2;137;180;130m\ue795${RST}`,
+	lua: `\x1b[38;2;81;160;207m\ue620${RST}`,
+	php: `\x1b[38;2;137;147;186m\ue73d${RST}`,
+	dart: `\x1b[38;2;87;182;240m\ue798${RST}`,
+	png: `\x1b[38;2;160;116;196m\uf1c5${RST}`,
+	jpg: `\x1b[38;2;160;116;196m\uf1c5${RST}`,
+	svg: `\x1b[38;2;255;180;50m\uf1c5${RST}`,
+	webp: `\x1b[38;2;160;116;196m\uf1c5${RST}`,
+	lock: `\x1b[38;2;130;130;130m\uf023${RST}`,
+	env: `\x1b[38;2;241;224;90m\ue615${RST}`,
+	graphql: `\x1b[38;2;224;51;144m\ue662${RST}`,
+	dockerfile: `\x1b[38;2;56;152;236m\ue7b0${RST}`,
+};
+
+const NAME_ICON: Record<string, string> = {
+	"package.json": `\x1b[38;2;137;180;130m\ue71e${RST}`,
+	"package-lock.json": `\x1b[38;2;130;130;130m\ue71e${RST}`,
+	"tsconfig.json": `\x1b[38;2;49;120;198m\ue628${RST}`,
+	".gitignore": `\x1b[38;2;222;165;132m\ue702${RST}`,
+	".env": `\x1b[38;2;241;224;90m\ue615${RST}`,
+	dockerfile: `\x1b[38;2;56;152;236m\ue7b0${RST}`,
+	makefile: `\x1b[38;2;130;130;130m\ue615${RST}`,
+	"readme.md": `\x1b[38;2;66;165;245m\ue73e${RST}`,
+	license: `\x1b[38;2;218;218;218m\ue60a${RST}`,
+};
+
+export function fileIcon(fp: string): string {
+	if (!USE_ICONS) return "";
+	const base = basename(fp).toLowerCase();
+	if (NAME_ICON[base]) return `${NAME_ICON[base]} `;
+	const ext = extname(fp).slice(1).toLowerCase();
+	return EXT_ICON[ext] ? `${EXT_ICON[ext]} ` : `${NF_DEFAULT} `;
+}
+
+export function dirIcon(): string {
+	return USE_ICONS ? `${NF_DIR} ` : "";
+}
+
+// ---------------------------------------------------------------------------
+// Language detection
+// ---------------------------------------------------------------------------
+
+import type { BundledLanguage } from "shiki";
+
+const EXT_LANG: Record<string, BundledLanguage> = {
+	ts: "typescript", tsx: "tsx", js: "javascript", jsx: "jsx",
+	mjs: "javascript", cjs: "javascript",
+	py: "python", rb: "ruby", rs: "rust", go: "go", java: "java",
+	c: "c", cpp: "cpp", h: "c", hpp: "cpp",
+	cs: "csharp", swift: "swift", kt: "kotlin",
+	html: "html", css: "css", scss: "scss", less: "css",
+	json: "json", jsonc: "jsonc", yaml: "yaml", yml: "yaml",
+	toml: "toml", md: "markdown", mdx: "mdx", sql: "sql",
+	sh: "bash", bash: "bash", zsh: "bash", lua: "lua", php: "php",
+	dart: "dart", xml: "xml", graphql: "graphql", svelte: "svelte", vue: "vue",
+	dockerfile: "dockerfile", makefile: "make",
+	zig: "zig", nim: "nim", elixir: "elixir",
+};
+
+export function detectLang(fp: string): BundledLanguage | undefined {
+	const base = basename(fp).toLowerCase();
+	if (base === "dockerfile") return "dockerfile";
+	if (base === "makefile" || base === "gnumakefile") return "make";
+	return EXT_LANG[extname(fp).slice(1).toLowerCase()];
+}
+
+// ---------------------------------------------------------------------------
+// Env helpers
+// ---------------------------------------------------------------------------
+
+export function envInt(name: string, fallback: number): number {
+	const v = Number.parseInt(process.env[name] ?? "", 10);
+	return Number.isFinite(v) && v > 0 ? v : fallback;
+}
+
+export const MAX_HL_CHARS = envInt("PRETTY_MAX_HL_CHARS", 80_000);
+export const MAX_PREVIEW_LINES = envInt("PRETTY_MAX_PREVIEW_LINES", 80);
+export const CACHE_LIMIT = envInt("PRETTY_CACHE_LIMIT", 128);
+
+// ---------------------------------------------------------------------------
+// Agent directory helpers
+// ---------------------------------------------------------------------------
+
+export function getDefaultAgentDir(): string | undefined {
+	const home = process.env.HOME ?? "";
+	return home ? join(home, ".pi/agent") : undefined;
+}

package/src/fff.ts

@@ -0,0 +1,147 @@
+/**
+ * pi-pretty: FFF lifecycle management.
+ *
+ * Manages the FFF file finder lifecycle: create, wait for scan, destroy.
+ * Tools check `isAvailable` and use `finder` directly for search operations.
+ * Graceful fallback: if FFF is not installed or fails, tools degrade to SDK.
+ */
+
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+
+import type { FileFinder as FffFileFinder, GrepCursor } from "@ff-labs/fff-node";
+
+// ---------------------------------------------------------------------------
+// Cursor store — pagination cursors for grep
+// ---------------------------------------------------------------------------
+
+export class CursorStore {
+	private cursors = new Map<string, GrepCursor>();
+	private counter = 0;
+	private maxSize: number;
+
+	constructor(maxSize = 200) {
+		this.maxSize = maxSize;
+	}
+
+	store(cursor: GrepCursor): 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): GrepCursor | undefined {
+		return this.cursors.get(id);
+	}
+
+	get size(): number {
+		return this.cursors.size;
+	}
+}
+
+// ---------------------------------------------------------------------------
+// FffService — wraps a single FileFinder instance
+// ---------------------------------------------------------------------------
+
+export class FffService {
+	finder: FffFileFinder | null = null;
+	partialIndex = false;
+	cursorStore = new CursorStore();
+
+	private fffModule: typeof import("@ff-labs/fff-node") | null = null;
+	private dbDir: string | null = null;
+	private finderPromise: Promise<void> | null = null;
+
+	constructor(fffModule?: typeof import("@ff-labs/fff-node"), agentDir?: string) {
+		if (fffModule) {
+			this.fffModule = fffModule;
+			if (agentDir) {
+				this.dbDir = join(agentDir, "pi-pretty", "fff");
+				try {
+					mkdirSync(this.dbDir, { recursive: true });
+				} catch { /* ignore */ }
+			}
+		}
+	}
+
+	/** Returns true if the FFF native module is loaded (installed). */
+	isModuleLoaded(): boolean {
+		return this.fffModule !== null;
+	}
+
+	get isAvailable(): boolean {
+		return this.finder !== null && !this.finder.isDestroyed;
+	}
+
+	/** Attempt to load FFF module dynamically (called during session_start if not injected). */
+	async tryLoadModule(): Promise<boolean> {
+		if (this.fffModule) return true;
+		try {
+			const mod = await import("@ff-labs/fff-node");
+			this.fffModule = mod;
+			if (!this.dbDir && process.env.HOME) {
+				this.dbDir = join(process.env.HOME, ".pi/agent", "pi-pretty", "fff");
+				try {
+					mkdirSync(this.dbDir, { recursive: true });
+				} catch { /* ignore */ }
+			}
+			return true;
+		} catch {
+			return false;
+		}
+	}
+
+	async ensureFinder(cwd: string): Promise<void> {
+		if (this.finder && !this.finder.isDestroyed) return;
+		if (this.finderPromise) return this.finderPromise;
+
+		this.finderPromise = this._createFinder(cwd);
+		await this.finderPromise;
+		this.finderPromise = null;
+	}
+
+	private async _createFinder(cwd: string): Promise<void> {
+		if (!this.fffModule) return;
+
+		if (this.finder && !this.finder.isDestroyed) {
+			this.finder.destroy();
+			this.finder = null;
+		}
+
+		const result = this.fffModule.FileFinder.create({
+			basePath: cwd,
+			frecencyDbPath: this.dbDir ? join(this.dbDir, "frecency.mdb") : "",
+			historyDbPath: this.dbDir ? join(this.dbDir, "history.mdb") : "",
+			aiMode: true,
+		});
+
+		if (!result.ok) {
+			throw new Error(`FFF init failed: ${result.error}`);
+		}
+
+		this.finder = result.value;
+		const scan = await this.finder.waitForScan(15_000);
+		this.partialIndex = scan.ok && !scan.value;
+	}
+
+	destroy(): void {
+		if (this.finder && !this.finder.isDestroyed) {
+			this.finder.destroy();
+			this.finder = null;
+		}
+		this.partialIndex = false;
+		this.finderPromise = null;
+	}
+
+	getFinder(): import("@ff-labs/fff-node").FileFinder | null {
+		return this.finder;
+	}
+
+	getCursorStore(): CursorStore {
+		return this.cursorStore;
+	}
+}

package/src/helpers.ts

@@ -0,0 +1,124 @@
+/**
+ * pi-pretty: utility helpers.
+ */
+
+import { relative } from "node:path";
+
+// ---------------------------------------------------------------------------
+// String / normalization
+// ---------------------------------------------------------------------------
+
+export function normalizeLineEndings(text: string): string {
+	return text.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+}
+
+export function shortPath(cwd: string, home: string, p: string): string {
+	if (!p) return "";
+	const r = relative(cwd, p);
+	if (!r.startsWith("..") && !r.startsWith("/")) return r;
+	return p.replace(home, "~");
+}
+
+export function trimToUndefined(value: string | undefined): string | undefined {
+	const trimmed = value?.trim();
+	return trimmed ? trimmed : undefined;
+}
+
+export function escapeRegexLiteral(text: string): string {
+	return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+export function buildLiteralAlternationPattern(patterns: string[]): string {
+	return patterns
+		.map(escapeRegexLiteral)
+		.sort((a, b) => b.length - a.length)
+		.join("|");
+}
+
+export function shouldIgnoreCaseForPatterns(patterns: string[]): boolean {
+	return patterns.every((pattern) => pattern.toLowerCase() === pattern);
+}
+
+export function getConstraintBackedPath(constraints: string | undefined): string | undefined {
+	const trimmed = trimToUndefined(constraints);
+	if (!trimmed || /\s/.test(trimmed) || trimmed.includes("!") || trimmed.endsWith("/") || /[*?[{]/.test(trimmed)) {
+		return undefined;
+	}
+	return trimmed;
+}
+
+export function getErrorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+export function humanSize(bytes: number): string {
+	if (bytes < 1024) return `${bytes}B`;
+	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
+	return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}
+
+// ---------------------------------------------------------------------------
+// Ripgrep match detection
+// ---------------------------------------------------------------------------
+
+export function countRipgrepMatches(text: string): number {
+	return text
+		.trim()
+		.split("\n")
+		.filter((line) => /^.+?[:-]\d+[:-]/.test(line)).length;
+}
+
+export function stripBashExitStatusLine(text: string): string {
+	return normalizeLineEndings(text)
+		.split("\n")
+		.filter((line) => !/^Command exited with code \d+$/i.test(line.trim()))
+		.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Tool metrics
+// ---------------------------------------------------------------------------
+
+export function formatElapsedMs(ms: number | undefined): string {
+	if (typeof ms !== "number" || !Number.isFinite(ms)) return "";
+	if (ms < 1000) return `${Math.round(ms)}ms`;
+	const s = ms / 1000;
+	return s < 10 ? `${s.toFixed(1)}s` : `${Math.round(s)}s`;
+}
+
+export function formatCharCount(chars: number | undefined): string {
+	if (typeof chars !== "number" || !Number.isFinite(chars) || chars <= 0) return "";
+	if (chars < 1000) return `${chars} chars`;
+	if (chars < 10_000) return `${(chars / 1000).toFixed(1)}k chars`;
+	return `${Math.round(chars / 1000)}k chars`;
+}
+
+export const ELAPSED_KEY = "__prettyElapsedMs";
+export const CHARS_KEY = "__prettyOutputChars";
+
+// ---------------------------------------------------------------------------
+// Infer bash exit code
+// ---------------------------------------------------------------------------
+
+export function inferBashExitCode(text: string, fallback: number | null): number | null {
+	const exitMatch = text.match(/(?:exit code|exited with(?: code)?|exit status)[:\s]*(\d+)/i);
+	if (exitMatch) return Number(exitMatch[1]);
+	if (text.includes("command not found") || text.includes("No such file")) return 1;
+	return fallback;
+}
+
+// ---------------------------------------------------------------------------
+// Compact error lines
+// ---------------------------------------------------------------------------
+
+export function compactErrorLines(error: string): string[] {
+	const compactedLines: string[] = [];
+	let previousBlank = false;
+	for (const line of normalizeLineEndings(error).trim().split("\n")) {
+		const isBlank = line.trim() === "";
+		if (isBlank && previousBlank) continue;
+		compactedLines.push(line);
+		previousBlank = isBlank;
+	}
+	return compactedLines;
+}

package/src/image.ts

@@ -0,0 +1,129 @@
+/**
+ * pi-pretty: Terminal image rendering (iTerm2 / Kitty / Ghostty inline image protocols).
+ * Handles tmux passthrough for image protocols.
+ */
+
+import { execFileSync } from "node:child_process";
+
+type ImageProtocol = "iterm2" | "kitty" | "none";
+
+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 = 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;
+}
+
+function getOuterTerminal(): string {
+	if (process.env.LC_TERMINAL === "iTerm2") return "iTerm.app";
+	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";
+	}
+	const termProgram = process.env.TERM_PROGRAM ?? "";
+	if (termProgram && termProgram !== "tmux" && termProgram !== "screen") {
+		return normalizeTerminalName(termProgram);
+	}
+	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();
+	if (term === "ghostty" || term === "kitty") return "kitty";
+	if (["iTerm.app", "WezTerm", "mintty"].includes(term)) return "iterm2";
+	if (process.env.LC_TERMINAL === "iTerm2") return "iterm2";
+	return "none";
+}
+
+function tmuxAllowsPassthrough(): boolean | null {
+	if (_tmuxAllowPassthroughOverrideForTests !== undefined) return _tmuxAllowPassthroughOverrideForTests;
+	if (!isTmuxSession()) return null;
+	if (_tmuxAllowPassthroughCache !== undefined) return _tmuxAllowPassthroughCache;
+	try {
+		const value = 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;
+}
+
+function tmuxWrap(seq: string): string {
+	if (!isTmuxSession()) return seq;
+	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;
+	},
+};