pi-orca-images 0.2.3 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.4.0
+
+- `[Image N]` labels are links to their image file: Cmd-click a label to check the pasted image before sending it (Orca, iTerm2, Ghostty, WezTerm, Kitty).
+- Pasted image preview: a thumbnail of one pasted image above the prompt, with a compact `[Image N] n/total · Ctrl+Shift+←/→` legend below it (just `[Image 1]` for a single image) and no Open image link. It follows new pastes and the label under the cursor; Ctrl+Shift+←/→ steps between images. `PI_IMAGE_PREVIEW=0` turns it off.
+- `/orca-images status` reports whether the image preview is on.
+- `/orca-images open N` opens `[Image N]` in macOS Preview, from the prompt or the last sent message, in any terminal.
+
+## 0.3.0
+
+- Open image previews: each inline image gets an **Open image** link, and `/orca-images open` opens the latest image in macOS Preview. Previews are written to temporary files. Thanks to [@Ky1ezer0](https://github.com/Ky1ezer0) (#1).
+
 ## 0.2.3
 
 - Fix: Pi crashed with "This extension ctx is stale after session replacement or reload" when an `[Image N]` label was in the prompt after `/resume`, `/new`, `/fork` or `/reload`. Pi hands extensions a Proxy over the TUI that ignores `delete`, so the old session's render hook was never removed and kept styling labels with its stale ctx.

package/README.md

@@ -41,24 +41,53 @@ Orca renders inline images through xterm.js's image addon. Three things keep Pi'
 
 Paste an image (or drop an image file) into Pi's prompt and the path is shown as a bold, colored `[Image 1]` label, as in OpenCode. Labels are numbered per message, move and delete as one unit, and become the real path again when you send the message, so the model sees exactly what it saw before.
 
+Each label is also a link to its image file: **Cmd-click** `[Image 1]` to check what you pasted before sending it. In Orca this opens an image tab with zoom controls; other terminals open it if they support OSC 8 links (iTerm2, Ghostty, WezTerm, Kitty). In any terminal on macOS, `/orca-images open 1` opens `[Image 1]` in Preview. It looks in the current prompt first, then in the last sent message that had labels, since typing the command replaces the prompt.
+
 It recognizes pastes made only of existing image files (`png`, `jpg`, `gif`, `webp`, `bmp`, `tiff`, `heic`, `avif`): plain paths, `~/` paths, quoted or backslash-escaped paths, and `file://` URLs. Text that mixes a path with other words is left alone. This works in every terminal, not only Orca, including Pi's own clipboard paste. Set `PI_IMAGE_LABELS=0` to turn it off.
 
+## Pasted image preview
+
+While the prompt has pasted images, a small thumbnail of one of them is shown above it, with a compact navigator legend below the thumbnail:
+
+```text
+[Image 2] 2/3 · Ctrl+Shift+←/→
+```
+
+With a single pasted image the legend is just `[Image 1]`. The thumbnail has no **Open image** link; Cmd-click its `[Image N]` label in the prompt instead.
+
+It shows the image you just pasted; moving the cursor onto an `[Image N]` label shows that one, and **Ctrl+Shift+←/→** steps to the previous or next image. Only one thumbnail is drawn at a time, so the prompt stays in view and every terminal that draws Pi's images draws it the same way. The preview disappears when you send the message.
+
+In terminals without inline images the legend follows a text line with the image type, size and file name. Set `PI_IMAGE_PREVIEW=0` to turn the preview off; it is also off when `PI_IMAGE_LABELS=0`.
+
+## Open image previews
+
+Each rendered image gets an **Open image** file link beneath it. **Cmd-click** the link on macOS to open the preview through your terminal. In our Orca test, this opens an Orca image tab with zoom controls. Direct image clicks and hover-to-zoom are not supported.
+
+On macOS, `/orca-images open` opens the last image rendered by Pi in **Preview**, using `open -a Preview`.
+
+Preview copies are saved in a private `pi-orca-images-*` directory under the OS temporary directory, never in the project. Identical images reuse a file within each loaded extension instance. Files survive `/reload` and are deleted on normal Pi process exit; links expire when their files are removed. Crashes or forced termination can leave files behind, and long-running sessions can still accumulate previews. Older `.pi/image-previews/` folders are not automatically removed.
+
+The saved bytes are those available to Pi and may already have been resized by a tool. Previews require automatic Orca detection and a writable temporary directory. They are inactive when `PI_ORCA_IMAGES=0` or an explicit `PI_IMAGE_PROTOCOL` overrides detection. The link and Preview command were tested with Pi 1.5.2 on macOS; opening through the command requires macOS Preview.
+
 ## Commands
 
 | Command | Effect |
 |---|---|
-| `/orca-images` or `/orca-images status` | Shows the detection decision, Pi's active image protocol, and whether the repaint fix and image labels are on |
+| `/orca-images` or `/orca-images status` | Shows the detection decision, Pi's active image protocol, and whether the repaint fix, image labels and image preview are on |
 | `/orca-images test` | Draws a test gradient (it is not sent to the model) |
+| `/orca-images open` | Opens the last rendered image in macOS Preview |
+| `/orca-images open N` | Opens the pasted `[Image N]` in macOS Preview, from the prompt or the last sent message |
 | `/orca-images redraw` | Re-sends every visible image right now |
 
 ## Configuration
 
-It does nothing outside Orca. Your explicit choices always win:
+The rendering fixes and preview links activate only in Orca; pasted image labels can work in any terminal. Your explicit choices always win:
 
 | Setting | Effect |
 |---|---|
-| `PI_ORCA_IMAGES=0` | Disables the Orca image fixes |
-| `PI_IMAGE_LABELS=0` | Disables pasted image labels |
+| `PI_ORCA_IMAGES=0` | Disables the Orca image fixes and preview feature |
+| `PI_IMAGE_LABELS=0` | Disables pasted image labels (and the preview above the prompt) |
+| `PI_IMAGE_PREVIEW=0` | Disables the pasted image preview above the prompt |
 | `PI_IMAGE_PROTOCOL=…` | Used as is; the package does not override it |
 | `terminal.images` in Pi settings | Applied by Pi on top of the package's choice |
 | `terminal.showImages: false` | Pi still hides images |
@@ -69,6 +98,8 @@ It does nothing outside Orca. Your explicit choices always win:
 - Pi 1.4 in its default `fullscreen` TUI mode. In `regular` mode detection still works, but the repaint fix and tab recovery do not apply.
 - Not inside tmux or screen: image escapes do not reach Orca through them.
 - Image labels wrap internal methods of Pi's editor (`handlePaste`, `segment`, `expandPasteMarkers`, `render`). If a Pi release changes them, pasted paths simply stay as paths.
+- The preview above the prompt reads the pasted file when it is shown; Ctrl+Shift+←/→ does nothing if your terminal or Pi keybindings already use those keys, but moving the cursor onto a label still switches the image.
+- Preview links read internal fields of Pi's image component. If those fields change or preview copies cannot be saved, links are omitted.
 - The repaint fix wraps two internal methods of Pi's TUI. If a Pi release renames them, `/orca-images status` reports the fix as `unavailable` and images fall back to the first-row behavior; detection keeps working.
 
 ## Development

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-orca-images",
-  "version": "0.2.3",
+  "version": "0.4.0",
   "description": "Inline images for Pi inside Orca's terminal, plus [Image N] paste labels.",
   "type": "module",
   "license": "MIT",

package/src/carousel.ts

@@ -0,0 +1,135 @@
+import { readFileSync } from "node:fs";
+import { basename } from "node:path";
+import { Image, truncateToWidth } from "@earendil-works/pi-tui";
+import type { ImageEntry, ImageLabels } from "./labels.ts";
+import { NO_PREVIEW_LINK } from "./preview.ts";
+
+/** The parts of the editor's image labels the carousel reads. */
+export type CarouselLabels = Pick<ImageLabels, "entries" | "cursorLabel" | "pastes" | "lastPasted">;
+
+export interface CarouselView {
+	entries: ImageEntry[];
+	selected: ImageEntry;
+	index: number;
+}
+
+export const CAROUSEL_HINT = "Ctrl+Shift+←/→";
+/** Thumbnail size in terminal cells: small enough to keep the prompt in view. */
+const THUMBNAIL = { maxWidthCells: 24, maxHeightCells: 6 } as const;
+
+/**
+ * Which pasted image the preview shows. The latest event wins: a paste shows the new image,
+ * the cursor moving onto a label shows that label, and a shortcut step shows the next one.
+ */
+export class Carousel {
+	#selected: number | undefined;
+	#lastCursor: number | undefined;
+	#lastPastes = 0;
+	#entries: ImageEntry[] = [];
+
+	resolve(labels: CarouselLabels | undefined): CarouselView | undefined {
+		const entries = labels?.entries() ?? [];
+		this.#entries = entries;
+		if (!labels || entries.length === 0) {
+			this.#selected = undefined;
+			return undefined;
+		}
+		if (labels.pastes !== this.#lastPastes) {
+			this.#lastPastes = labels.pastes;
+			this.#selected = labels.lastPasted;
+		}
+		const cursor = labels.cursorLabel();
+		if (cursor !== this.#lastCursor) {
+			this.#lastCursor = cursor;
+			if (cursor !== undefined) this.#selected = cursor;
+		}
+		let index = entries.findIndex((entry) => entry.id === this.#selected);
+		if (index === -1) index = entries.length - 1;
+		const selected = entries[index] ?? entries[0];
+		if (!selected) return undefined;
+		this.#selected = selected.id;
+		return { entries, selected, index };
+	}
+
+	/** Show the next (1) or previous (-1) image, wrapping around. */
+	step(delta: 1 | -1): void {
+		const count = this.#entries.length;
+		if (count === 0) return;
+		const current = Math.max(0, this.#entries.findIndex((entry) => entry.id === this.#selected));
+		this.#selected = this.#entries[(current + delta + count) % count]?.id;
+	}
+}
+
+export interface LoadedImage {
+	data: string;
+	mimeType: string;
+}
+
+const MIME_TYPES: Record<string, string> = {
+	png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", gif: "image/gif", webp: "image/webp",
+	bmp: "image/bmp", tif: "image/tiff", tiff: "image/tiff", heic: "image/heic", heif: "image/heif",
+	avif: "image/avif",
+};
+
+export function loadImageFile(path: string): LoadedImage | undefined {
+	const mimeType = MIME_TYPES[path.split(".").pop()?.toLowerCase() ?? ""];
+	if (!mimeType) return undefined;
+	try {
+		return { data: readFileSync(path).toString("base64"), mimeType };
+	} catch {
+		return undefined;
+	}
+}
+
+export interface CarouselWidgetOptions {
+	labels: () => CarouselLabels | undefined;
+	carousel: Carousel;
+	theme: { muted: (text: string) => string; fallback?: (text: string) => string };
+	load?: (path: string) => LoadedImage | undefined;
+}
+
+/**
+ * A preview above the prompt: one thumbnail of the selected image with a compact navigator
+ * legend below it, `[Image 2] 2/3 · Ctrl+Shift+←/→`, or just `[Image 1]` for a single image.
+ * Terminals without inline images get Pi's text fallback (type, size and file name).
+ */
+export function createCarouselWidget(options: CarouselWidgetOptions) {
+	const load = options.load ?? loadImageFile;
+	const { muted } = options.theme;
+	const images = new Map<string, Image | null>();
+	return {
+		render(width: number): string[] {
+			const view = options.carousel.resolve(options.labels());
+			if (!view) {
+				images.clear();
+				return [];
+			}
+			// Keyed by label, not path: pasting the same path again (an overwritten screenshot) reads it anew.
+			const key = (entry: ImageEntry) => `${entry.id}:${entry.path}`;
+			const live = new Set(view.entries.map(key));
+			for (const cached of images.keys()) if (!live.has(cached)) images.delete(cached);
+
+			const { selected, index, entries } = view;
+			const label = `[Image ${selected.id}]`;
+			const legend = muted(entries.length === 1 ? label : `${label} ${index + 1}/${entries.length} · ${CAROUSEL_HINT}`);
+			if (!images.has(key(selected))) {
+				const loaded = load(selected.path);
+				const image = loaded
+					? new Image(loaded.data, loaded.mimeType, { fallbackColor: options.theme.fallback ?? ((s) => s) }, {
+						...THUMBNAIL,
+						filename: basename(selected.path),
+					})
+					: null;
+				// The legend below names the image; an Open image link there would crowd it.
+				if (image) Object.assign(image, { [NO_PREVIEW_LINK]: true });
+				images.set(key(selected), image);
+			}
+			const image = images.get(key(selected));
+			const body = image ? image.render(width) : [truncateToWidth(muted(`Cannot read ${selected.path}`), width)];
+			return [...body, truncateToWidth(legend, width)];
+		},
+		invalidate() {
+			for (const image of images.values()) image?.invalidate();
+		},
+	};
+}

package/src/commands.ts

@@ -1,4 +1,4 @@
-export const SUBCOMMANDS = ["status", "test", "redraw"] as const;
+export const SUBCOMMANDS = ["status", "test", "redraw", "open"] as const;
 
 /**
  * Argument completions for /orca-images. A complete subcommand yields none, so the first
@@ -10,3 +10,19 @@ export function completeSubcommand(prefix: string): Array<{ value: string; label
 	const matches = SUBCOMMANDS.filter((value) => value.startsWith(typed)).map((value) => ({ value, label: value }));
 	return matches.length > 0 ? matches : null;
 }
+
+export type ParsedCommand =
+	| { sub: (typeof SUBCOMMANDS)[number]; image?: number }
+	| { sub: "invalid" };
+
+/** Parse /orca-images arguments: a subcommand, plus an optional image number for `open`. */
+export function parseCommand(args: string | undefined): ParsedCommand {
+	const [sub = "status", ...rest] = (args ?? "").trim().split(/\s+/).filter(Boolean);
+	if (!(SUBCOMMANDS as readonly string[]).includes(sub)) return { sub: "invalid" };
+	if (rest.length === 0) return { sub: sub as (typeof SUBCOMMANDS)[number] };
+	const [number] = rest;
+	if (sub === "open" && rest.length === 1 && number !== undefined && /^[1-9]\d*$/.test(number)) {
+		return { sub, image: Number(number) };
+	}
+	return { sub: "invalid" };
+}

package/src/detect.ts

@@ -47,3 +47,8 @@ export function decide(env: Env): Decision {
 export function labelsEnabled(env: Env): boolean {
 	return !DISABLED.has((env.PI_IMAGE_LABELS ?? "").toLowerCase());
 }
+
+/** The preview above the prompt shows pasted labels, so it needs them; PI_IMAGE_PREVIEW=0 turns it off. */
+export function previewEnabled(env: Env): boolean {
+	return labelsEnabled(env) && !DISABLED.has((env.PI_IMAGE_PREVIEW ?? "").toLowerCase());
+}

package/src/index.ts

@@ -1,16 +1,19 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Container, getCapabilities, Image, resetCapabilitiesCache, Text } from "@earendil-works/pi-tui";
-import { completeSubcommand, SUBCOMMANDS } from "./commands.ts";
-import { decide, type Decision, labelsEnabled, OWNED_ENV } from "./detect.ts";
+import { Carousel, createCarouselWidget } from "./carousel.ts";
+import { completeSubcommand, parseCommand, SUBCOMMANDS } from "./commands.ts";
+import { decide, type Decision, labelsEnabled, OWNED_ENV, previewEnabled } from "./detect.ts";
 import { type EditorWatcher, watchEditors } from "./labels.ts";
 import { installShim, type Shim, type ShimTarget } from "./shim.ts";
+import { installPreviews, openInPreview } from "./preview.ts";
 import { formatStatus } from "./status.ts";
 import { testImagePng } from "./test-image.ts";
 
 const COMMAND = "orca-images";
 const TEST_ENTRY = "pi-orca-images:test";
 const WIDGET = "pi-orca-images:probe";
-const USAGE = `Usage: /${COMMAND} [${SUBCOMMANDS.join("|")}]`;
+const PREVIEW_WIDGET = "pi-orca-images:preview";
+const USAGE = `Usage: /${COMMAND} [${SUBCOMMANDS.join("|")}], or /${COMMAND} open N for [Image N]`;
 
 /** Apply the decision to the process environment, before Pi reads its capabilities. */
 function applyDecision(decision: Decision, env = process.env): void {
@@ -30,15 +33,24 @@ export default function piOrcaImages(pi: ExtensionAPI) {
 	const decision = decide(process.env);
 	applyDecision(decision);
 	const labels = labelsEnabled(process.env);
+	const preview = previewEnabled(process.env);
+	let carousel: Carousel | undefined;
+	let previewTui: { requestRender(): void } | undefined;
 	let shim: Shim | undefined;
 	let watcher: EditorWatcher | undefined;
+	let previews: ReturnType<typeof installPreviews> | undefined;
 
 	pi.on("session_start", async (_event, ctx) => {
+		if (ctx.hasUI && decision.action === "apply") {
+			previews?.uninstall();
+			previews = installPreviews({ onError: (message) => ctx.ui.notify(message, "error") });
+		}
 		const repaint = decision.action === "apply" && decision.protocol === "kitty";
 		if (!ctx.hasUI || (!repaint && !labels)) return;
 		// The widget factory is the only public hook that hands an extension the TUI instance.
 		ctx.ui.setWidget(WIDGET, (tui) => {
 			if (repaint) {
+				// SAFETY: installShim treats every TUI member except requestRender as optional and checks it.
 				shim = installShim(tui as unknown as ShimTarget);
 				// Resend whatever Pi drew before the fix was in place (first startup render, or a
 				// session switch on a Pi that calls this factory late). Deferred: Pi may call the
@@ -47,6 +59,7 @@ export default function piOrcaImages(pi: ExtensionAPI) {
 				setTimeout(() => installed.recover(), 0);
 			}
 			if (labels) {
+				// SAFETY: watchEditors only wraps doRender when present and finds editors by duck typing.
 				watcher = watchEditors(tui as unknown as ShimTarget, {
 					style: (label) => ctx.ui.theme.fg("accent", ctx.ui.theme.bold(label)),
 				});
@@ -54,12 +67,45 @@ export default function piOrcaImages(pi: ExtensionAPI) {
 			return { render: () => [], invalidate() {} };
 		});
 		ctx.ui.setWidget(WIDGET, undefined);
+		if (preview) {
+			const shown = new Carousel();
+			carousel = shown;
+			ctx.ui.setWidget(
+				PREVIEW_WIDGET,
+				(tui, theme) => {
+					previewTui = tui;
+					return createCarouselWidget({
+						// Read through the closure, never a stale session's ctx: watcher is reset on shutdown.
+						labels: () => (carousel === shown ? watcher?.current() : undefined),
+						carousel: shown,
+						theme: {
+							muted: (text) => theme.fg("muted", text),
+							fallback: (text) => theme.fg("warning", text),
+						},
+					});
+				},
+				{ placement: "aboveEditor" },
+			);
+		}
 	});
 
+	if (preview) {
+		const step = (delta: 1 | -1) => () => {
+			carousel?.step(delta);
+			previewTui?.requestRender();
+		};
+		pi.registerShortcut("ctrl+shift+left", { description: "Previous pasted image preview", handler: step(-1) });
+		pi.registerShortcut("ctrl+shift+right", { description: "Next pasted image preview", handler: step(1) });
+	}
+
 	pi.on("session_shutdown", async (event) => {
+		previews?.uninstall();
+		previews = undefined;
 		// The watcher styles labels through this session's ctx, which goes stale on replacement.
 		watcher?.uninstall();
 		watcher = undefined;
+		carousel = undefined;
+		previewTui = undefined;
 		// On /resume, /new, /fork and /reload Pi draws the next transcript before session_start,
 		// so the repaint fix must stay in place; the next session reuses it (installShim is
 		// idempotent per TUI). Only quitting removes it.
@@ -80,11 +126,22 @@ export default function piOrcaImages(pi: ExtensionAPI) {
 	});
 
 	pi.registerCommand(COMMAND, {
-		description: "Inline images in Orca: status, test, or redraw",
+		description: "Inline images in Orca: status, test, redraw, open, or open N for [Image N]",
 		getArgumentCompletions: completeSubcommand,
 		handler: async (args, ctx) => {
-			const sub = (args ?? "").trim() || "status";
-			if (sub === "status") {
+			const { sub, image } = { image: undefined, ...parseCommand(args) };
+			if (sub === "open" && image !== undefined) {
+				const path = watcher?.pathOf(image);
+				if (!path) {
+					ctx.ui.notify(`No [Image ${image}] in the prompt or the last sent message.`, "warning");
+					return;
+				}
+				try {
+					await openInPreview(path);
+				} catch (error) {
+					ctx.ui.notify(`Could not open [Image ${image}]: ${error instanceof Error ? error.message : String(error)}`, "error");
+				}
+			} else if (sub === "status") {
 				ctx.ui.notify(
 					formatStatus({
 						decision,
@@ -92,11 +149,15 @@ export default function piOrcaImages(pi: ExtensionAPI) {
 						shim,
 						orcaVersion: process.env.ORCA_APP_VERSION ?? process.env.TERM_PROGRAM_VERSION,
 						labels: labels && watcher !== undefined,
+						preview: preview && carousel !== undefined,
 					}),
 					"info",
 				);
 			} else if (sub === "test") {
 				pi.appendEntry(TEST_ENTRY, { width: 240, height: 120 });
+			} else if (sub === "open") {
+				if (previews) await previews.openLatest();
+				else ctx.ui.notify("Image previews are not active in this terminal.", "warning");
 			} else if (sub === "redraw") {
 				if (shim) shim.recover();
 				else ctx.ui.notify("pi-orca-images is not active in this terminal; nothing to redraw.", "warning");

package/src/labels.ts

@@ -1,3 +1,4 @@
+import { pathToFileURL } from "node:url";
 import { isExistingFile, parseImagePaths } from "./image-paths.ts";
 
 /** The parts of pi-tui's Editor this module wraps. */
@@ -25,8 +26,23 @@ export interface LabelOptions {
 	isImageFile?: (path: string) => boolean;
 }
 
+export interface ImageEntry {
+	id: number;
+	path: string;
+}
+
 export interface ImageLabels {
 	readonly count: number;
+	/** Path of `[Image N]` in the draft, or in the last sent message that had labels. */
+	pathOf(id: number): string | undefined;
+	/** Pasted labels still in the draft, in text order. */
+	entries(): ImageEntry[];
+	/** Id of the draft label the cursor touches (inside, or right before or after), if any. */
+	cursorLabel(): number | undefined;
+	/** Labels created so far; grows on every image paste, across messages. */
+	readonly pastes: number;
+	/** Id of the most recently created label. */
+	readonly lastPasted: number | undefined;
 	uninstall(): void;
 }
 
@@ -57,7 +73,10 @@ export function installImageLabels(editor: LabelTarget, options: LabelOptions):
 	};
 	const ownKeys = Object.keys(original).filter((key) => Object.hasOwn(editor, key));
 	const paths = new Map<number, string>();
+	let sent = new Map<number, string>();
 	let next = 1;
+	let pastes = 0;
+	let lastPasted: number | undefined;
 
 	const known = (text: string) => [...text.matchAll(LABEL)].filter((m) => paths.has(Number(m[1])));
 
@@ -72,6 +91,8 @@ export function installImageLabels(editor: LabelTarget, options: LabelOptions):
 		const labels = parsed.paths.map((path) => {
 			const id = next++;
 			paths.set(id, path);
+			pastes++;
+			lastPasted = id;
 			return labelText(id);
 		});
 		const leading = parsed.leading || (spaceBefore ? " " : "");
@@ -124,20 +145,30 @@ export function installImageLabels(editor: LabelTarget, options: LabelOptions):
 		return original.expandPasteMarkers.call(this, expanded);
 	};
 
+	/** Labels still in the draft text; `paths` also keeps labels the user deleted. */
+	const inDraft = () => new Map(known(editor.getText()).map((m) => [Number(m[1]), paths.get(Number(m[1])) ?? ""]));
+
 	editor.submitValue = function () {
+		const submitted = inDraft();
 		try {
 			return original.submitValue.call(this);
 		} finally {
+			if (submitted.size > 0) sent = submitted;
 			paths.clear();
 			next = 1;
 		}
 	};
 
+	// Each known label is an OSC 8 link to its file: Cmd-click opens it in terminals that support links.
 	editor.render = function (width: number) {
 		const lines = original.render.call(this, width);
 		if (paths.size === 0) return lines;
 		return lines.map((line) =>
-			line.replace(LABEL, (label, id: string) => (paths.has(Number(id)) ? options.style(label) : label)),
+			line.replace(LABEL, (label, id: string) => {
+				const path = paths.get(Number(id));
+				if (path === undefined) return label;
+				return `\x1b]8;;${pathToFileURL(path).href}\x07${options.style(label)}\x1b]8;;\x07`;
+			}),
 		);
 	};
 
@@ -145,7 +176,27 @@ export function installImageLabels(editor: LabelTarget, options: LabelOptions):
 		get count() {
 			return paths.size;
 		},
+		pathOf(id: number) {
+			return inDraft().get(id) ?? sent.get(id);
+		},
+		entries() {
+			return known(editor.getText()).map((m) => ({ id: Number(m[1]), path: paths.get(Number(m[1])) ?? "" }));
+		},
+		cursorLabel() {
+			const cursor = editor.getCursor?.();
+			if (!cursor || paths.size === 0) return undefined;
+			const line = editor.getText().split("\n")[cursor.line] ?? "";
+			const hit = known(line).find((m) => cursor.col >= m.index && cursor.col <= m.index + m[0].length);
+			return hit ? Number(hit[1]) : undefined;
+		},
+		get pastes() {
+			return pastes;
+		},
+		get lastPasted() {
+			return lastPasted;
+		},
 		uninstall() {
+			// SAFETY: every key restored below is one of the editor methods captured in `original`.
 			const target = editor as unknown as Record<string, unknown>;
 			for (const [key, value] of Object.entries(original)) {
 				// Restore earlier own wrappers; otherwise fall back to the prototype method.
@@ -183,6 +234,10 @@ export function findEditors(root: unknown): LabelTarget[] {
 
 export interface EditorWatcher {
 	readonly editors: number;
+	/** Path of `[Image N]` in any watched editor, as in {@link ImageLabels.pathOf}. */
+	pathOf(id: number): string | undefined;
+	/** Labels of the editor that has pasted images in its draft, else of the first watched editor. */
+	current(): ImageLabels | undefined;
 	uninstall(): void;
 }
 
@@ -215,6 +270,17 @@ export function watchEditors(
 		get editors() {
 			return installed.size;
 		},
+		pathOf(id: number) {
+			for (const labels of installed.values()) {
+				const path = labels.pathOf(id);
+				if (path !== undefined) return path;
+			}
+			return undefined;
+		},
+		current() {
+			const all = [...installed.values()];
+			return all.find((labels) => labels.count > 0) ?? all[0];
+		},
 		uninstall() {
 			active = false;
 			for (const labels of installed.values()) labels.uninstall();

package/src/preview.ts

@@ -0,0 +1,99 @@
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { promisify } from "node:util";
+import { Image, truncateToWidth } from "@earendil-works/pi-tui";
+
+const run = promisify(execFile);
+const EXTENSIONS: Record<string, string> = {
+	"image/png": "png", "image/jpeg": "jpg", "image/gif": "gif",
+	"image/webp": "webp", "image/bmp": "bmp", "image/tiff": "tiff",
+	"image/avif": "avif", "image/heic": "heic",
+};
+
+let previewDirectory: string | undefined;
+
+/** Retain temporary previews until this module's process exits, including across /reload. */
+export function savePreview(data: string, mimeType: string): string {
+	const extension = EXTENSIONS[mimeType];
+	if (!extension) throw new Error(`Unsupported preview format: ${mimeType}`);
+	if (!previewDirectory) {
+		previewDirectory = mkdtempSync(join(tmpdir(), "pi-orca-images-"));
+		const directory = previewDirectory;
+		process.once("exit", () => {
+			try { rmSync(directory, { recursive: true, force: true }); } catch { /* OS temp cleanup is the fallback. */ }
+		});
+	}
+	const directory = previewDirectory;
+	const bytes = Buffer.from(data, "base64");
+	const path = join(directory, `${createHash("sha256").update(bytes).digest("hex")}.${extension}`);
+	writeFileSync(path, bytes, { mode: 0o600 });
+	return path;
+}
+
+export async function openInPreview(path: string): Promise<void> {
+	if (process.platform !== "darwin") throw new Error("Opening previews requires macOS Preview.");
+	await run("/usr/bin/open", ["-a", "Preview", path], { timeout: 10_000 });
+}
+
+const PREVIEW = Symbol.for("pi-orca-images.preview");
+/** Set on an Image to keep it without an Open image link, e.g. the pasted-image thumbnail. */
+export const NO_PREVIEW_LINK = Symbol.for("pi-orca-images.no-preview-link");
+type PreviewHost = typeof Image.prototype & { [PREVIEW]?: { uninstall(): void } };
+
+export function installPreviews(options: {
+	open?: (path: string) => Promise<void>;
+	save?: (data: string, mimeType: string) => string;
+	onError: (message: string) => void;
+}) {
+	const prototype = Image.prototype as PreviewHost;
+	prototype[PREVIEW]?.uninstall();
+	const originalRender = prototype.render;
+	const paths = new WeakMap<Image, string | null>();
+	let latest: string | undefined;
+	let active = true;
+	const open = async (path: string) => {
+		try {
+			await (options.open ?? openInPreview)(path);
+		} catch (error) {
+			if (active) options.onError(`Could not open image in Preview: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	};
+	prototype.render = function (width) {
+		const lines = originalRender.call(this, width);
+		if (!active || (this as { [NO_PREVIEW_LINK]?: boolean })[NO_PREVIEW_LINK]) return lines;
+		if (!paths.has(this)) {
+			// Pi exposes no image-data accessor; fail closed if its internal fields change.
+			// SAFETY: both fields are type-checked below before use.
+			const source = this as unknown as { base64Data?: string; mimeType?: string };
+			try {
+				paths.set(this, typeof source.base64Data === "string" && typeof source.mimeType === "string"
+					? (options.save ?? savePreview)(source.base64Data, source.mimeType) : null);
+			} catch {
+				paths.set(this, null);
+			}
+		}
+		const path = paths.get(this);
+		if (!path) return lines;
+		latest = path;
+		const label = truncateToWidth("Open image", width);
+		return [...lines, `\x1b]8;;${pathToFileURL(path).href}\x07\x1b[4m${label}\x1b[24m\x1b]8;;\x07`];
+	};
+	const preview = {
+		async openLatest() {
+			if (latest) await open(latest);
+			else options.onError("No image has been rendered yet. Try /orca-images test first.");
+		},
+		uninstall() {
+			if (!active) return;
+			active = false;
+			prototype.render = originalRender;
+			if (prototype[PREVIEW] === preview) delete prototype[PREVIEW];
+		},
+	};
+	prototype[PREVIEW] = preview;
+	return preview;
+}

package/src/status.ts

@@ -7,9 +7,10 @@ export interface StatusInput {
 	shim: Pick<Shim, "renderPatched" | "focusPatched" | "recoveries"> | undefined;
 	orcaVersion: string | undefined;
 	labels: boolean;
+	preview: boolean;
 }
 
-export function formatStatus({ decision, images, shim, orcaVersion, labels }: StatusInput): string {
+export function formatStatus({ decision, images, shim, orcaVersion, labels, preview }: StatusInput): string {
 	const action = decision.action === "apply" ? `apply ${decision.protocol}` : decision.action;
 	const repaint = shim
 		? `repaint fix: ${shim.renderPatched ? "on" : "unavailable"}, focus recovery: ${
@@ -22,6 +23,7 @@ export function formatStatus({ decision, images, shim, orcaVersion, labels }: St
 		`  Pi image protocol: ${images ?? "none"}`,
 		`  ${repaint}`,
 		`  image labels: ${labels ? "on" : "off (PI_IMAGE_LABELS)"}`,
+		`  image preview: ${preview ? "on" : "off (PI_IMAGE_PREVIEW)"}`,
 		`  Orca: ${orcaVersion ?? "not detected"}`,
 	].join("\n");
 }