@kcurtet/pi-image-preview 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,80 @@
-# Temporary Holding Version
+# pi-image-preview
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> Hover previews for image paths in the [pi](https://github.com/earendil-works/pi) coding agent — inspired by [better-claude/image-preview](https://github.com/midudev/better-claude/tree/main/plugins/image-preview).
+
+```text
+▣ 1 screenshot.png 1920×1080   hover: preview · click: open · /images
+```
+
+Paste an image, type an image path, or let the agent create one — and a row of **chips** appears. Hover a chip and the picture floats open right there, drawn by your terminal itself. Click it and it opens in your system's viewer.
+
+## ✨ Features
+
+### Chip row above the editor
+While you type, pi-image-preview watches your draft (poll every 400 ms) and lists every image it mentions — pasted screenshots (`/tmp/pi-clipboard-*.png`), paths you typed, anything that exists on disk:
+
+```text
+▣ 1 screenshot.png 1920×1080  ▣ 2 chart.png 640×480   hover: preview · click: open
+──────────────────────────────────────────────
+❯ what is wrong in this screenshot? /tmp/screenshot.png
+```
+
+### Chips under sent messages and tool results
+After you send a prompt — and after any tool call that produces or touches an image (a screenshot the agent took, a chart it generated, a `read` of an image file) — the same chips appear in the transcript. They survive resume: reopen the session and they are still there.
+
+```text
+❯ take a screenshot and tell me what you see
+  ⚙ bash: grim shot.png && ...
+  ▣ 1 shot.png 1920×1080          ← automatic
+  ⚙ read: shot.png
+  [inline image — native pi rendering]
+```
+
+### Hover preview
+Put the pointer on any chip and a floating preview opens next to it — no click, no focus stealing, nothing moves. Move away and it closes. The picture renders through your terminal's native image protocol:
+
+| Terminal | Rendering |
+| --- | --- |
+| kitty, Ghostty, WezTerm | kitty graphics protocol |
+| iTerm2, others | iTerm2 protocol |
+| No image support | informative card (name, size, format) |
+
+Non-PNG images (JPEG, WebP, GIF, BMP) are converted automatically for kitty terminals.
+
+### Click to open
+Click a chip and the image opens in your system's viewer — `open` on macOS, `explorer` on Windows, `xdg-open` on Linux.
+
+### `/images` — keyboard-only viewer
+A picker over every image seen this session (draft, sent, tool-produced), then a full viewer:
+
+```text
+q / esc    close
+o          open externally
+← / →      navigate (p / n also work)
+```
+
+Works in any terminal, mouse or not.
+
+## 📦 Install
+
+```bash
+pi install git:github.com/kcurtet/pi-image-preview
+```
+
+Update with `pi update --extensions`, remove with `pi remove git:github.com/kcurtet/pi-image-preview`.
+
+## 🔍 How it works
+
+- A 400 ms poll reads the editor text; path-like tokens are resolved against the filesystem and real images are loaded with magic-byte MIME detection (≤ 25 MB, max 12 at once).
+- Chips are pi-tui `MouseRegion` components; the preview is a **non-capturing overlay** hosting pi-tui's `Image` component, positioned above the pointer.
+- `tool_result` events are scanned for image paths (tool output + `path` / `command` / `file_path` inputs), deduplicated per session, and recorded as custom entries with an entry renderer — that is what makes transcript chips persist across resume.
+- The `/images` history keeps the last 24 images. Everything is cleaned up on `session_shutdown`.
+
+## ⚠️ Limits
+
+- Only paths that exist as local files are detected; URLs are not fetched.
+- Chips appear under the tool *after* it finishes; streaming partials are not scanned.
+
+## 📄 License
+
+MIT

package/index.ts

@@ -0,0 +1,576 @@
+/**
+ * pi-image-preview — hover previews for image paths in the pi editor.
+ *
+ * Paste an image (pi inserts a /tmp/pi-clipboard-*.png path) or type any image
+ * path, and a chip row appears above the editor:
+ *
+ *   ▣ 1 screenshot.png 1920×1080   hover: preview · click: open · /images
+ *
+ * - Hover a chip (fullscreen mode): a floating preview opens near the pointer,
+ *   drawn with the terminal's image protocol (kitty / iTerm2) when available.
+ * - Click a chip: open the image in the system viewer (open / xdg-open / explorer).
+ * - `/images`: keyboard viewer over draft images plus recently sent ones
+ *   (q/esc close · o open externally · ←/→ navigate).
+ *
+ * In terminals without mouse support (regular mode) the chip row still lists the
+ * images and /images always works.
+ */
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import {
+	Container,
+	HStack,
+	Image,
+	MouseRegion,
+	Text,
+	getCapabilities,
+	getImageDimensions,
+	type Component,
+	type ImageDimensions,
+	type OverlayHandle,
+	type TUI,
+	type TuiMouseEvent,
+} from "@earendil-works/pi-tui";
+import {
+	convertToPng,
+	detectSupportedImageMimeTypeFromFile,
+	type ExtensionAPI,
+	type Theme,
+} from "@earendil-works/pi-coding-agent";
+
+const WIDGET_KEY = "pi-image-preview";
+const ENTRY_TYPE = "pi-image-preview";
+const MAX_IMAGE_BYTES = 25 * 1024 * 1024;
+const MAX_IMAGES = 12;
+const MAX_HISTORY = 24;
+const POLL_MS = 400;
+const HOVER_EXPIRY_MS = 450;
+const EXPIRY_TICK_MS = 150;
+const PREVIEW_MAX_CELLS = 60;
+const PREVIEW_MAX_ROWS = 24;
+
+interface LoadedImage {
+	path: string;
+	/** Base64 actually handed to the renderer (may be PNG-converted for kitty). */
+	base64: string;
+	mimeType: string;
+	origMime: string;
+	dims: ImageDimensions | null;
+	bytes: number;
+}
+
+type SetWidgetFn = (content: unknown, options?: { placement?: string }) => void;
+
+/** Open a file with the platform viewer, detached. */
+function openExternal(file: string): void {
+	try {
+		let cmd = "xdg-open";
+		if (process.platform === "darwin") cmd = "open";
+		else if (process.platform === "win32") cmd = "explorer";
+		const child = spawn(cmd, [file], { detached: true, stdio: "ignore" });
+		child.on("error", () => {});
+		child.unref();
+	} catch {
+		// best effort
+	}
+}
+
+function formatBytes(bytes: number): string {
+	if (bytes < 1024) return `${bytes} B`;
+	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(0)} KB`;
+	return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+function formatDims(dims: ImageDimensions | null): string {
+	return dims ? `${dims.widthPx}×${dims.heightPx}` : "?×?";
+}
+
+/** Candidate image paths in a text: anything path-like that exists as a file. */
+function extractCandidatePaths(text: string, cwd: string): string[] {
+	const tokens = text.match(/[^\s`'"|<>{}[\]()]+/g) ?? [];
+	const out: string[] = [];
+	const seen = new Set<string>();
+	for (const raw of tokens) {
+		const trimmed = raw.replace(/[,.:;!?]+$/, "");
+		if (!trimmed || trimmed.length > 4096) continue;
+		let candidate = trimmed;
+		if (candidate.startsWith("~")) candidate = path.join(os.homedir(), candidate.slice(1));
+		// Only image extensions count — "any path that exists" would chip log files,
+		// config files and every other path a tool prints.
+		if (!/\.(png|jpe?g|gif|webp|bmp)$/i.test(candidate)) continue;
+		const absolute = path.resolve(cwd, candidate);
+		if (seen.has(absolute)) continue;
+		try {
+			const stat = fs.statSync(absolute);
+			if (stat.isFile() && stat.size <= MAX_IMAGE_BYTES) {
+				seen.add(absolute);
+				out.push(absolute);
+			}
+		} catch {
+			// not a file — ignore
+		}
+		if (out.length >= MAX_IMAGES) break;
+	}
+	return out;
+}
+
+class ImagePreviewCard extends Container {
+	constructor(image: LoadedImage, private readonly theme: Theme) {
+		super();
+		this.rebuild(image);
+	}
+
+	private rebuild(image: LoadedImage): void {
+		this.clear();
+		const caps = getCapabilities();
+		const name = path.basename(image.path);
+		const meta = `${formatDims(image.dims)} · ${formatBytes(image.bytes)} · ${image.origMime.replace("image/", "")}`;
+		if (caps.images && image.base64) {
+			this.addChild(
+				new Image(
+					image.base64,
+					image.mimeType,
+					{ fallbackColor: (s: string) => this.theme.fg("toolOutput", s) },
+					{ maxWidthCells: PREVIEW_MAX_CELLS, maxHeightCells: PREVIEW_MAX_ROWS, filename: name },
+					image.dims ?? undefined,
+				),
+			);
+			this.addChild(new Text(this.theme.fg("muted", `${name} · ${meta}`), 1, 0));
+		} else {
+			// Terminal cannot draw images: informative card instead.
+			this.addChild(new Text(this.theme.style(`▣ ${name}`, { fg: "accent", bold: true }), 1, 0));
+			this.addChild(new Text(this.theme.fg("muted", meta), 1, 0));
+			this.addChild(
+				new Text(this.theme.fg("dim", "terminal cannot draw images — click the chip to open"), 1, 0),
+			);
+		}
+	}
+}
+
+interface ImageRef {
+	path: string;
+	/** Loaded lazily; chips show "?×?" until ready. */
+	image?: LoadedImage;
+}
+
+class ChipsBar extends Container {
+	constructor(
+		private readonly mgr: PreviewManager,
+		private refs: ImageRef[] = [],
+		private readonly showHint = true,
+	) {
+		super();
+		this.rebuild();
+	}
+
+	update(refs: ImageRef[]): void {
+		if (!Array.isArray(refs)) return;
+		this.refs = refs;
+		this.rebuild();
+	}
+
+	rebuild(): void {
+		this.clear();
+		if (this.refs.length === 0) return;
+		const theme = this.mgr.theme;
+		if (!theme) return;
+		const chips: Component[] = [];
+		this.refs.forEach((ref, index) => {
+			const name = path.basename(ref.path);
+			const dims = ref.image ? formatDims(ref.image.dims) : "…";
+			const label =
+				theme.style(` ▣${index + 1} `, { fg: "accent", bold: true }) +
+				theme.fg("text", name) +
+				theme.fg("muted", ` ${dims}`);
+			chips.push(
+				new MouseRegion(new Text(label, 0, 0), (event: TuiMouseEvent) => this.mgr.onChipMouse(ref, event)),
+			);
+		});
+		if (this.showHint) {
+			chips.push(new Text(theme.fg("dim", "  hover: preview · click: open · /images"), 0, 0));
+		}
+		this.addChild(new HStack(chips, { gap: 1 }));
+	}
+}
+
+class ImageViewer implements Component {
+	private index: number;
+	private readonly imageComponents = new Map<number, Image>();
+
+	constructor(
+		private readonly tui: TUI,
+		private readonly theme: Theme,
+		private readonly images: LoadedImage[],
+		startIndex: number,
+		private readonly done: () => void,
+	) {
+		this.index = Math.min(Math.max(startIndex, 0), images.length - 1);
+	}
+
+	handleInput(data: string): void {
+		if (data === "\x1b" || data === "q") {
+			this.done();
+			return;
+		}
+		if (data === "o" || data === "O") {
+			openExternal(this.images[this.index]!.path);
+			return;
+		}
+		let delta = 0;
+		if (data === "\x1b[D" || data === "p" || data === "P") delta = -1;
+		else if (data === "\x1b[C" || data === "n" || data === "N") delta = 1;
+		if (delta !== 0 && this.images.length > 1) {
+			this.index = (this.index + delta + this.images.length) % this.images.length;
+			this.imageComponents.clear();
+			this.tui.requestRender();
+		}
+	}
+
+	invalidate(): void {
+		for (const image of this.imageComponents.values()) image.invalidate();
+	}
+
+	render(width: number): string[] {
+		const image = this.images[this.index]!;
+		const name = path.basename(image.path);
+		const header =
+			this.theme.style(`▣ ${this.index + 1}/${this.images.length} `, { fg: "accent", bold: true }) +
+			this.theme.fg("text", name) +
+			this.theme.fg("muted", ` ${formatDims(image.dims)} · ${formatBytes(image.bytes)}`);
+		const footer = this.theme.fg("dim", "q close · o open · ←/→ navigate");
+		const innerWidth = Math.max(10, Math.min(width - 2, PREVIEW_MAX_CELLS));
+		const lines: string[] = ["", ...new Text(header, 1, 0).render(width)];
+		if (getCapabilities().images && image.base64) {
+			let component = this.imageComponents.get(this.index);
+			if (!component) {
+				component = new Image(
+					image.base64,
+					image.mimeType,
+					{ fallbackColor: (s: string) => this.theme.fg("toolOutput", s) },
+					{ maxWidthCells: innerWidth, maxHeightCells: PREVIEW_MAX_ROWS, filename: name },
+					image.dims ?? undefined,
+				);
+				this.imageComponents.set(this.index, component);
+			}
+			lines.push(...component.render(width));
+		} else {
+			lines.push(...new Text(this.theme.fg("muted", "(terminal cannot draw images)"), 1, 0).render(width));
+		}
+		lines.push(...new Text(footer, 1, 0).render(width));
+		return lines;
+	}
+}
+
+class PreviewManager {
+	cwd: string;
+	theme: Theme | undefined;
+	private tui: TUI | undefined;
+	private bar: ChipsBar | undefined;
+	private currentPaths: string[] = [];
+	private readonly cache = new Map<string, LoadedImage>();
+	private readonly loading = new Set<string>();
+	private readonly sentHistory: LoadedImage[] = [];
+	private lastText: string | null = null;
+	private pollTimer: ReturnType<typeof setInterval> | undefined;
+	private expiryTimer: ReturnType<typeof setInterval> | undefined;
+	private overlay: OverlayHandle | undefined;
+	private overlayPath: string | undefined;
+	private lastMouseAt = 0;
+	private unregisterWidget: (() => void) | undefined;
+
+	constructor(private readonly getEditorText: () => string | undefined) {
+		this.cwd = process.cwd();
+	}
+
+	start(setWidget: SetWidgetFn): void {
+		this.stop();
+		// One always-registered widget: an empty bar renders no lines, so the cost
+		// matches the default layout (the container keeps its leading spacer).
+		setWidget(
+			(tui: TUI, theme: Theme) => {
+				this.tui = tui;
+				this.theme = theme;
+				this.bar = new ChipsBar(this, this.currentRefs());
+				return this.bar;
+			},
+			{ placement: "aboveEditor" },
+		);
+		this.unregisterWidget = () => setWidget(undefined);
+		this.pollTimer = setInterval(() => void this.poll(), POLL_MS);
+		this.expiryTimer = setInterval(() => this.checkExpiry(), EXPIRY_TICK_MS);
+	}
+
+	stop(): void {
+		if (this.pollTimer) clearInterval(this.pollTimer);
+		if (this.expiryTimer) clearInterval(this.expiryTimer);
+		this.pollTimer = this.expiryTimer = undefined;
+		this.hidePreview();
+		this.unregisterWidget?.();
+		this.unregisterWidget = undefined;
+		this.bar = undefined;
+		this.currentPaths = [];
+		this.lastText = null;
+	}
+
+	private currentRefs(): ImageRef[] {
+		return this.currentPaths.map((p) => ({ path: p, image: this.cache.get(p) }));
+	}
+
+	private refreshBar(): void {
+		this.bar?.update(this.currentRefs());
+		this.bar?.invalidate();
+		this.tui?.requestRender();
+	}
+
+	/** Kick async loads for paths not in cache; onChange runs after each settles. */
+	ensureLoaded(paths: string[], onChange?: () => void): void {
+		for (const p of paths) {
+			if (this.cache.has(p) || this.loading.has(p)) continue;
+			this.loading.add(p);
+			void this.load(p)
+				.then((loaded) => {
+					if (loaded) this.cache.set(p, loaded);
+				})
+				.catch(() => {})
+				.finally(() => {
+					this.loading.delete(p);
+					onChange?.();
+				});
+		}
+	}
+
+	cacheGet(pathname: string): LoadedImage | undefined {
+		return this.cache.get(pathname);
+	}
+
+	renderRequest(): void {
+		this.tui?.requestRender();
+	}
+
+	private async poll(): Promise<void> {
+		const text = this.getEditorText();
+		if (text === undefined || text === this.lastText) return;
+		this.lastText = text;
+		this.hidePreview();
+		const paths = extractCandidatePaths(text, this.cwd);
+		this.ensureLoaded(paths, () => {
+			this.syncCurrent();
+			this.refreshBar();
+		});
+		this.syncCurrent(paths);
+		this.refreshBar();
+	}
+
+	private syncCurrent(paths?: string[]): void {
+		const wanted = paths ?? extractCandidatePaths(this.lastText ?? "", this.cwd);
+		this.currentPaths = wanted;
+	}
+
+	private async load(pathname: string): Promise<LoadedImage | null> {
+		try {
+			const mime = await detectSupportedImageMimeTypeFromFile(pathname);
+			if (!mime) return null;
+			const stat = await fsp.stat(pathname);
+			if (!stat.isFile() || stat.size > MAX_IMAGE_BYTES) return null;
+			let base64 = await fsp.readFile(pathname, "base64");
+			let encMime = mime;
+			if (getCapabilities().images === "kitty" && mime !== "image/png") {
+				const converted = await convertToPng(base64, mime);
+				if (converted) {
+					base64 = converted.data;
+					encMime = converted.mimeType;
+				}
+			}
+			const dims = getImageDimensions(base64, encMime) ?? getImageDimensions(base64, mime);
+			return { path: pathname, base64, mimeType: encMime, origMime: mime, dims, bytes: stat.size };
+		} catch {
+			return null;
+		}
+	}
+
+	/** Track images from sent messages for the /images viewer. */
+	recordSent(text: string): void {
+		const paths = extractCandidatePaths(text, this.cwd);
+		if (paths.length === 0) return;
+		void Promise.all(
+			paths.map((p) => (this.cache.has(p) ? Promise.resolve(this.cache.get(p)!) : this.load(p))),
+		)
+			.then((loaded) => {
+				for (const image of loaded) {
+					if (!image) continue;
+					this.cache.set(image.path, image);
+					const existing = this.sentHistory.findIndex((entry) => entry.path === image.path);
+					if (existing !== -1) this.sentHistory.splice(existing, 1);
+					this.sentHistory.unshift(image);
+				}
+				while (this.sentHistory.length > MAX_HISTORY) this.sentHistory.pop();
+			})
+			.catch(() => {});
+	}
+
+	get images(): LoadedImage[] {
+		const seen = new Set<string>();
+		const all: LoadedImage[] = [];
+		const push = (image: LoadedImage | undefined) => {
+			if (image && !seen.has(image.path)) {
+				seen.add(image.path);
+				all.push(image);
+			}
+		};
+		for (const p of this.currentPaths) push(this.cache.get(p));
+		for (const image of this.sentHistory) push(image);
+		return all;
+	}
+
+	onChipMouse(ref: ImageRef, event: TuiMouseEvent) {
+		this.lastMouseAt = Date.now();
+		if (event.type === "click" && event.button === "left") {
+			openExternal(ref.path);
+			this.hidePreview();
+			return { handled: true };
+		}
+		if (event.type === "move" || event.type === "press" || event.type === "drag") {
+			// Resolve from cache at event time so freshly loaded images preview too.
+			const image = ref.image ?? this.cache.get(ref.path);
+			if (image) this.showPreview(image, event.screenX, event.screenY);
+		}
+		return undefined;
+	}
+
+	private showPreview(image: LoadedImage, screenX: number, screenY: number): void {
+		if (!this.tui || !this.theme) return;
+		if (this.overlay && this.overlayPath === image.path) return; // already showing this one
+		this.hidePreview();
+		const card = new ImagePreviewCard(image, this.theme);
+		const cols = process.stdout.columns || 80;
+		const rows = process.stdout.rows || 24;
+		const width = Math.max(20, Math.min(cols - 2, PREVIEW_MAX_CELLS + 2));
+		const height = card.render(width).length;
+		const col = Math.max(0, Math.min(screenX + 2, cols - width - 1));
+		const row =
+			screenY - height - 1 >= 0
+				? screenY - height - 1
+				: Math.min(screenY + 1, Math.max(0, rows - height - 1));
+		this.overlay = this.tui.showOverlay(card, { row, col, width, nonCapturing: true });
+		this.overlayPath = image.path;
+	}
+
+	hidePreview(): void {
+		if (this.overlay) {
+			try {
+				this.overlay.hide();
+			} catch {
+				// tui may have been replaced (mode switch)
+			}
+		}
+		this.overlay = undefined;
+		this.overlayPath = undefined;
+	}
+
+	private checkExpiry(): void {
+		if (this.overlay && Date.now() - this.lastMouseAt > HOVER_EXPIRY_MS) this.hidePreview();
+	}
+}
+
+export default function imagePreviewExtension(pi: ExtensionAPI) {
+	// One manager per extension runtime; start() is idempotent and re-binds on
+	// session switches, so old timers and widgets never linger.
+	let mgr: PreviewManager | undefined;
+
+	pi.on("session_start", (_event, ctx) => {
+		if (ctx.mode !== "tui" || !ctx.hasUI) return;
+		mgr = new PreviewManager(() => {
+			try {
+				return ctx.ui.getEditorText();
+			} catch {
+				return undefined;
+			}
+		});
+		mgr.cwd = ctx.sessionManager.getCwd();
+		mgr.start((content, options) => ctx.ui.setWidget(WIDGET_KEY, content as never, options as never));
+	});
+
+	// Sent messages get a chips entry right below them in the transcript: same
+	// hover preview / click-to-open as the editor bar, and it survives resume.
+	pi.registerEntryRenderer(ENTRY_TYPE, (entry, _options, theme) => {
+		if (!mgr) return undefined;
+		mgr.theme = mgr.theme ?? theme;
+		const paths = (entry.data as { paths?: string[] } | undefined)?.paths ?? [];
+		if (paths.length === 0) return undefined;
+		const refsFor = (): ImageRef[] => paths.map((p) => ({ path: p, image: mgr!.cacheGet(p) }));
+		const bar = new ChipsBar(mgr, refsFor(), false);
+		mgr.ensureLoaded(paths, () => {
+			bar.update(refsFor());
+			mgr!.renderRequest();
+		});
+		return bar;
+	});
+
+	pi.on("input", (event) => {
+		if (event.source === "extension" || !event.text) return;
+		const paths = mgr ? extractCandidatePaths(event.text, mgr.cwd) : [];
+		if (paths.length > 0) pi.appendEntry(ENTRY_TYPE, { paths });
+		mgr?.recordSent(event.text);
+	});
+
+	// Tool results: when the agent produces or reads images (screenshot via bash,
+	// a generated chart, read of an image file), leave chips under the tool row.
+	const recorded = new Set<string>();
+	pi.on("tool_result", (event) => {
+		if (!mgr) return;
+		const texts: string[] = [];
+		for (const block of event.content) {
+			if (block.type === "text") texts.push(block.text);
+		}
+		if (typeof event.input?.path === "string") texts.push(event.input.path);
+		if (typeof event.input?.command === "string") texts.push(event.input.command);
+		if (typeof event.input?.file_path === "string") texts.push(event.input.file_path);
+		const paths = extractCandidatePaths(texts.join("\n"), mgr.cwd).filter((p) => !recorded.has(p));
+		if (paths.length === 0) return;
+		for (const p of paths) recorded.add(p);
+		pi.appendEntry(ENTRY_TYPE, { paths, source: "tool" });
+		mgr.recordSent(paths.join(" "));
+	});
+
+	pi.on("session_shutdown", () => {
+		mgr?.stop();
+		mgr = undefined;
+	});
+
+	pi.registerCommand("images", {
+		description: "Preview images from the editor draft and recent messages",
+		handler: async (_args, ctx) => {
+			if (ctx.mode !== "tui" || !ctx.hasUI) {
+				ctx.ui.notify("Image preview needs the interactive UI", "warning");
+				return;
+			}
+			let images: LoadedImage[] = mgr ? mgr.images : [];
+			if (images.length === 0) {
+				ctx.ui.notify("No images detected — paste one or type an image path", "info");
+				return;
+			}
+			const labels = images.map(
+				(image, index) =>
+					`${index + 1}) ${path.basename(image.path)} · ${formatDims(image.dims)} · ${formatBytes(image.bytes)}`,
+			);
+			const choice = await ctx.ui.select("Image preview", labels);
+			if (choice === undefined) return;
+			const index = Math.max(0, labels.indexOf(choice));
+			await ctx.ui.custom(
+				(tui, theme, _keybindings, done) =>
+					new ImageViewer(tui, theme, images, index, () => done(undefined)),
+				{
+					overlay: true,
+					overlayOptions: {
+						anchor: "center",
+						width: Math.min((process.stdout.columns || 80) - 4, 68),
+					},
+				},
+			);
+		},
+	});
+}

package/package.json

@@ -1,6 +1,23 @@
 {
-  "name": "@kcurtet/pi-image-preview",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@kcurtet/pi-image-preview",
+	"version": "0.1.1",
+	"description": "Hover previews for image paths in the pi coding agent: chips above the editor and in the transcript, kitty/iTerm2 inline rendering, /images viewer",
+	"private": false,
+	"keywords": [
+		"pi-package"
+	],
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/kcurtet/pi-image-preview.git"
+	},
+	"pi": {
+		"extensions": [
+			"./index.ts"
+		]
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*"
+	}
+}