pi-orca-images 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 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.
+
 ## 0.2.2
 
 - Gallery: preview image (`pi.image`) and shorter description for the pi.dev package page.

package/README.md

@@ -43,21 +43,32 @@ Paste an image (or drop an image file) into Pi's prompt and the path is shown as
 
 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.
 
+## 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 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 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_ORCA_IMAGES=0` | Disables the Orca image fixes and preview feature |
 | `PI_IMAGE_LABELS=0` | Disables pasted image labels |
 | `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 |
@@ -69,6 +80,7 @@ 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.
+- 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.2",
+  "version": "0.3.0",
   "description": "Inline images for Pi inside Orca's terminal, plus [Image N] paste labels.",
   "type": "module",
   "license": "MIT",

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

package/src/index.ts

@@ -4,6 +4,7 @@ import { completeSubcommand, SUBCOMMANDS } from "./commands.ts";
 import { decide, type Decision, labelsEnabled, OWNED_ENV } from "./detect.ts";
 import { type EditorWatcher, watchEditors } from "./labels.ts";
 import { installShim, type Shim, type ShimTarget } from "./shim.ts";
+import { installPreviews } from "./preview.ts";
 import { formatStatus } from "./status.ts";
 import { testImagePng } from "./test-image.ts";
 
@@ -32,8 +33,13 @@ export default function piOrcaImages(pi: ExtensionAPI) {
 	const labels = labelsEnabled(process.env);
 	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.
@@ -57,6 +63,8 @@ export default function piOrcaImages(pi: ExtensionAPI) {
 	});
 
 	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;
@@ -80,7 +88,7 @@ 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, or open",
 		getArgumentCompletions: completeSubcommand,
 		handler: async (args, ctx) => {
 			const sub = (args ?? "").trim() || "status";
@@ -97,6 +105,9 @@ export default function piOrcaImages(pi: ExtensionAPI) {
 				);
 			} 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

@@ -189,18 +189,24 @@ export interface EditorWatcher {
 /**
  * Label every editor in the TUI tree, checked before each render. Pi and extensions can swap the
  * editor at any time (custom editors, settings changes), so a one-time lookup is not enough.
+ *
+ * Pi hands extensions a Proxy over the TUI whose own-property checks and deletes never reach the
+ * TUI, so uninstall restores by assignment and the wrapper turns inert even if something else
+ * still holds it: a leftover wrapper would relabel editors with a stale session's style.
  */
 export function watchEditors(
 	tui: { doRender?: (...args: unknown[]) => unknown },
 	options: LabelOptions,
 ): EditorWatcher {
 	const installed = new Map<LabelTarget, ImageLabels>();
-	const hadOwn = Object.hasOwn(tui, "doRender");
 	const originalRender = tui.doRender;
+	let active = true;
 	if (originalRender) {
 		tui.doRender = function (this: unknown, ...args: unknown[]) {
-			for (const editor of findEditors(tui)) {
-				if (!installed.has(editor)) installed.set(editor, installImageLabels(editor, options));
+			if (active) {
+				for (const editor of findEditors(tui)) {
+					if (!installed.has(editor)) installed.set(editor, installImageLabels(editor, options));
+				}
 			}
 			return originalRender.apply(this, args);
 		};
@@ -210,11 +216,10 @@ export function watchEditors(
 			return installed.size;
 		},
 		uninstall() {
+			active = false;
 			for (const labels of installed.values()) labels.uninstall();
 			installed.clear();
-			if (!originalRender) return;
-			if (hadOwn) tui.doRender = originalRender;
-			else delete tui.doRender;
+			if (originalRender) tui.doRender = originalRender;
 		},
 	};
 }

package/src/preview.ts

@@ -0,0 +1,96 @@
+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");
+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) return lines;
+		if (!paths.has(this)) {
+			// Pi exposes no image-data accessor; fail closed if its internal fields change.
+			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/shim.ts

@@ -85,7 +85,8 @@ export function installShim(tui: ShimTarget, options: ShimOptions = {}): Shim {
 			cancel();
 			if (shim.renderPatched) tui.doRender = originalRender;
 			if (shim.focusPatched) tui.handleViewportInput = originalInput;
-			delete host[SHIM];
+			// Assign, not delete: a delete through Pi's TUI Proxy never reaches the TUI.
+			host[SHIM] = undefined;
 		},
 	};