pi-orca-images 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.2.1
+
+- README: banner, before/after screenshot and a demo GIF of the `[Image N]` labels.
+
+## 0.2.0
+
+- Show pasted image paths as bold, colored `[Image N]` labels in the prompt; they expand back to the path on send. `PI_IMAGE_LABELS=0` turns them off.
+- `/orca-images status` reports whether image labels are on.
+- Fix: images in a session opened with `/resume`, `/new` or `/fork` showed only their first row; they are now redrawn in full.
+
 ## 0.1.0
 
 - Detect Orca from `ORCA_IMAGE_PROTOCOL` and enable Pi's inline images.

package/README.md

@@ -1,8 +1,17 @@
-# pi-orca-images
+<p align="center">
+  <img src="https://raw.githubusercontent.com/JlMoreno00/pi-orca-images/main/docs/banner.png" alt="pi-orca-images: inline images for the Pi coding agent inside Orca's terminal" width="100%">
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/pi-orca-images"><img src="https://img.shields.io/npm/v/pi-orca-images?color=8ab4f8&label=npm" alt="npm version"></a>
+  <a href="https://github.com/JlMoreno00/pi-orca-images/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/JlMoreno00/pi-orca-images/ci.yml?branch=main&label=ci" alt="CI"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/npm/l/pi-orca-images?color=8b92a3" alt="MIT license"></a>
+  <a href="https://pi.dev/packages"><img src="https://img.shields.io/badge/pi-package-ec4899" alt="Pi package"></a>
+</p>
 
 Inline images for the [Pi coding agent](https://pi.dev) inside [Orca](https://github.com/stablyai/orca)'s terminal.
 
-Pi draws images natively (screenshots it reads, image tool results, previews), but inside Orca you get a blank gap or `Read image file [image/png]` and nothing else. This package fixes that with no configuration.
+Pi draws images natively (screenshots it reads, image tool results, previews), but inside Orca you get a blank gap or `Read image file [image/png]` and nothing else. This package fixes that with no configuration, and adds OpenCode-style `[Image 1]` labels for pasted images.
 
 ```bash
 pi install npm:pi-orca-images
@@ -10,6 +19,10 @@ pi install npm:pi-orca-images
 
 Restart Pi in an Orca terminal and run `/orca-images test`. You should see a color gradient.
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/JlMoreno00/pi-orca-images/main/docs/before-after.png" alt="The same read of an image in Pi inside Orca: without the package only the tool card shows; with it, the image is drawn in full" width="860">
+</p>
+
 ## What it fixes
 
 Orca renders inline images through xterm.js's image addon. Three things keep Pi's images from showing up there:
@@ -20,11 +33,21 @@ Orca renders inline images through xterm.js's image addon. Three things keep Pi'
 | Only the first row of an image is drawn | The addon stores Kitty images per cell, so Pi's later line writes erase the rest | Turns on Pi's "draw images last" render path (the one Pi already uses for WezTerm), only while Pi renders; the variable never reaches commands Pi runs |
 | Images vanish after switching tabs | When output arrives while a pane is hidden, Orca rebuilds the pane from a snapshot that has no images ([stablyai/orca#32714](https://github.com/stablyai/orca/issues/32714)) | On focus-in, re-sends every visible image a few times over the next 5 seconds, until Orca's restore has finished |
 
+## Pasted image labels
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/JlMoreno00/pi-orca-images/main/docs/image-labels.gif" alt="Typing a prompt in Pi, pasting two image paths that turn into [Image 1] and [Image 2] labels, deleting one label with a single backspace, and the sent message containing the real paths" width="760">
+</p>
+
+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.
+
+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.
+
 ## Commands
 
 | Command | Effect |
 |---|---|
-| `/orca-images` or `/orca-images status` | Shows the detection decision, Pi's active image protocol, and whether the repaint fix is on |
+| `/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 redraw` | Re-sends every visible image right now |
 
@@ -34,7 +57,8 @@ It does nothing outside Orca. Your explicit choices always win:
 
 | Setting | Effect |
 |---|---|
-| `PI_ORCA_IMAGES=0` | Disables the package |
+| `PI_ORCA_IMAGES=0` | Disables the Orca image fixes |
+| `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 |
 | `terminal.showImages: false` | Pi still hides images |
@@ -44,6 +68,7 @@ It does nothing outside Orca. Your explicit choices always win:
 - Orca with inline images (v1.4.229 or later exports `ORCA_IMAGE_PROTOCOL`) and *Settings → Terminal → Inline Images* on (the default).
 - 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 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
@@ -52,8 +77,11 @@ It does nothing outside Orca. Your explicit choices always win:
 npm install
 npm run check          # typecheck + tests
 pi -e ./src/index.ts   # try it without installing
+python3 scripts/banner.py  # regenerate docs/banner.png (Pillow, Inter, JetBrains Mono)
 ```
 
+The screenshots in `docs/` are real captures of Pi 1.4 in Orca 1.4.229 on macOS.
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-orca-images",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Inline images for the Pi coding agent inside Orca's terminal",
   "type": "module",
   "license": "MIT",

package/src/detect.ts

@@ -42,3 +42,8 @@ export function decide(env: Env): Decision {
 	}
 	return { action: "apply", protocol, reason: `Orca detected (ORCA_IMAGE_PROTOCOL=${advertised})` };
 }
+
+/** Pasted-image labels work in any terminal; PI_IMAGE_LABELS=0 turns them off. */
+export function labelsEnabled(env: Env): boolean {
+	return !DISABLED.has((env.PI_IMAGE_LABELS ?? "").toLowerCase());
+}

package/src/image-paths.ts

@@ -0,0 +1,81 @@
+import { statSync } from "node:fs";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+
+const IMAGE_EXTENSION = /\.(png|jpe?g|gif|webp|bmp|tiff?|heic|heif|avif)$/i;
+
+export interface ParsedImagePaths {
+	leading: string;
+	trailing: string;
+	paths: string[];
+}
+
+export function isExistingFile(path: string): boolean {
+	try {
+		return statSync(path).isFile();
+	} catch {
+		return false;
+	}
+}
+
+/** Split on unquoted, unescaped whitespace; quotes and backslash escapes are removed. */
+function tokenize(text: string): string[] {
+	const tokens: string[] = [];
+	let current = "";
+	let quote: string | undefined;
+	let inToken = false;
+	for (let i = 0; i < text.length; i++) {
+		const ch = text[i]!;
+		if (quote) {
+			if (ch === quote) quote = undefined;
+			else current += ch;
+		} else if (ch === "\\" && i + 1 < text.length) {
+			current += text[++i];
+			inToken = true;
+		} else if (ch === "'" || ch === '"') {
+			quote = ch;
+			inToken = true;
+		} else if (/\s/.test(ch)) {
+			if (inToken) tokens.push(current);
+			current = "";
+			inToken = false;
+		} else {
+			current += ch;
+			inToken = true;
+		}
+	}
+	if (inToken) tokens.push(current);
+	return tokens;
+}
+
+function toPath(token: string): string | undefined {
+	if (token.startsWith("file://")) {
+		try {
+			return fileURLToPath(token);
+		} catch {
+			return undefined;
+		}
+	}
+	if (token === "~" || token.startsWith("~/")) return homedir() + token.slice(1);
+	return token;
+}
+
+/**
+ * Recognize text that consists only of image file paths, as pasted or dropped into a terminal.
+ * Returns null when any token is not an existing image file, so mixed text is never rewritten.
+ */
+export function parseImagePaths(
+	text: string,
+	isImageFile: (path: string) => boolean = isExistingFile,
+): ParsedImagePaths | null {
+	const match = /^(\s*)([\s\S]*?)(\s*)$/.exec(text);
+	const body = match?.[2] ?? "";
+	if (!body) return null;
+	const paths: string[] = [];
+	for (const token of tokenize(body)) {
+		const path = toPath(token);
+		if (!path || !IMAGE_EXTENSION.test(path) || !isImageFile(path)) return null;
+		paths.push(path);
+	}
+	return paths.length > 0 ? { leading: match?.[1] ?? "", trailing: match?.[3] ?? "", paths } : null;
+}

package/src/index.ts

@@ -1,7 +1,8 @@
 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, OWNED_ENV } from "./detect.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 { formatStatus } from "./status.ts";
 import { testImagePng } from "./test-image.ts";
@@ -28,20 +29,41 @@ function applyDecision(decision: Decision, env = process.env): void {
 export default function piOrcaImages(pi: ExtensionAPI) {
 	const decision = decide(process.env);
 	applyDecision(decision);
+	const labels = labelsEnabled(process.env);
 	let shim: Shim | undefined;
+	let watcher: EditorWatcher | undefined;
 
 	pi.on("session_start", async (_event, ctx) => {
-		if (decision.action !== "apply" || decision.protocol !== "kitty" || !ctx.hasUI) return;
+		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) => {
-			shim = installShim(tui as unknown as ShimTarget);
+			if (repaint) {
+				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
+				// factory while it renders.
+				const installed = shim;
+				setTimeout(() => installed.recover(), 0);
+			}
+			if (labels) {
+				watcher = watchEditors(tui as unknown as ShimTarget, {
+					style: (label) => ctx.ui.theme.fg("accent", ctx.ui.theme.bold(label)),
+				});
+			}
 			return { render: () => [], invalidate() {} };
 		});
 		ctx.ui.setWidget(WIDGET, undefined);
 	});
 
-	pi.on("session_shutdown", async () => {
-		shim?.uninstall();
+	pi.on("session_shutdown", async (event) => {
+		// The watcher styles labels through this session's ctx, which goes stale on replacement.
+		watcher?.uninstall();
+		watcher = 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.
+		if (event.reason === "quit") shim?.uninstall();
 		shim = undefined;
 	});
 
@@ -69,6 +91,7 @@ export default function piOrcaImages(pi: ExtensionAPI) {
 						images: getCapabilities().images,
 						shim,
 						orcaVersion: process.env.ORCA_APP_VERSION ?? process.env.TERM_PROGRAM_VERSION,
+						labels: labels && watcher !== undefined,
 					}),
 					"info",
 				);

package/src/labels.ts

@@ -0,0 +1,220 @@
+import { isExistingFile, parseImagePaths } from "./image-paths.ts";
+
+/** The parts of pi-tui's Editor this module wraps. */
+export interface LabelTarget {
+	handlePaste(text: string): void;
+	insertTextAtCursor(text: string): void;
+	segment(text: string, mode: "grapheme" | "word"): Iterable<SegmentLike>;
+	expandPasteMarkers(text: string): string;
+	submitValue(): void;
+	render(width: number): string[];
+	getText(): string;
+	getCursor?(): { line: number; col: number };
+}
+
+interface SegmentLike {
+	segment: string;
+	index: number;
+	input?: string;
+	isWordLike?: boolean;
+}
+
+export interface LabelOptions {
+	/** Styles a label for display, e.g. bold accent color. */
+	style: (label: string) => string;
+	isImageFile?: (path: string) => boolean;
+}
+
+export interface ImageLabels {
+	readonly count: number;
+	uninstall(): void;
+}
+
+const LABELS = Symbol.for("pi-orca-images.labels");
+const LABEL = /\[Image (\d+)\]/g;
+
+const labelText = (id: number) => `[Image ${id}]`;
+
+/**
+ * Show pasted image paths as atomic `[Image N]` labels in Pi's editor.
+ *
+ * The label is what the user sees and edits; the path is what Pi submits, so the model and
+ * the prompt history behave exactly as if the path had been pasted.
+ */
+export function installImageLabels(editor: LabelTarget, options: LabelOptions): ImageLabels {
+	const host = editor as LabelTarget & { [LABELS]?: ImageLabels };
+	const existing = host[LABELS];
+	if (existing) return existing;
+
+	const isImageFile = options.isImageFile ?? isExistingFile;
+	const original = {
+		handlePaste: editor.handlePaste,
+		insertTextAtCursor: editor.insertTextAtCursor,
+		segment: editor.segment,
+		expandPasteMarkers: editor.expandPasteMarkers,
+		submitValue: editor.submitValue,
+		render: editor.render,
+	};
+	const ownKeys = Object.keys(original).filter((key) => Object.hasOwn(editor, key));
+	const paths = new Map<number, string>();
+	let next = 1;
+
+	const known = (text: string) => [...text.matchAll(LABEL)].filter((m) => paths.has(Number(m[1])));
+
+	/** Returns the labeled replacement for text made only of image paths, or undefined. */
+	const labelFor = (text: string, spaceBefore: boolean, spaceAfter: boolean): string | undefined => {
+		const parsed = parseImagePaths(text, isImageFile);
+		if (!parsed) return undefined;
+		if (known(editor.getText()).length === 0) {
+			paths.clear();
+			next = 1;
+		}
+		const labels = parsed.paths.map((path) => {
+			const id = next++;
+			paths.set(id, path);
+			return labelText(id);
+		});
+		const leading = parsed.leading || (spaceBefore ? " " : "");
+		const trailing = parsed.trailing || (spaceAfter ? " " : "");
+		return `${leading}${labels.join(" ")}${trailing}`;
+	};
+
+	const neighbors = () => {
+		const cursor = editor.getCursor?.();
+		if (!cursor) return { before: "", after: "" };
+		const line = editor.getText().split("\n")[cursor.line] ?? "";
+		return { before: line[cursor.col - 1] ?? "", after: line[cursor.col] ?? "" };
+	};
+	const needsSpace = (ch: string) => ch !== "" && !/\s/.test(ch);
+
+	editor.handlePaste = function (text: string) {
+		const { before, after } = neighbors();
+		const labeled = labelFor(text, needsSpace(before), after === "" || needsSpace(after));
+		if (labeled === undefined) return original.handlePaste.call(this, text);
+		return original.insertTextAtCursor.call(this, labeled);
+	};
+
+	editor.insertTextAtCursor = function (text: string) {
+		const labeled = labelFor(text, false, false);
+		return original.insertTextAtCursor.call(this, labeled ?? text);
+	};
+
+	editor.segment = function (text: string, mode: "grapheme" | "word") {
+		const base = original.segment.call(this, text, mode);
+		const spans = known(text).map((m) => ({ start: m.index, end: m.index + m[0].length }));
+		if (spans.length === 0) return base;
+		const merged: SegmentLike[] = [];
+		let span = 0;
+		for (const seg of base) {
+			while (span < spans.length && spans[span]!.end <= seg.index) span++;
+			const current = spans[span];
+			if (current && seg.index >= current.start && seg.index < current.end) {
+				if (seg.index === current.start) {
+					merged.push({ ...seg, segment: text.slice(current.start, current.end), isWordLike: true });
+				}
+				continue;
+			}
+			merged.push(seg);
+		}
+		return merged;
+	};
+
+	editor.expandPasteMarkers = function (text: string) {
+		const expanded = text.replace(LABEL, (label, id: string) => paths.get(Number(id)) ?? label);
+		return original.expandPasteMarkers.call(this, expanded);
+	};
+
+	editor.submitValue = function () {
+		try {
+			return original.submitValue.call(this);
+		} finally {
+			paths.clear();
+			next = 1;
+		}
+	};
+
+	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)),
+		);
+	};
+
+	const labels: ImageLabels = {
+		get count() {
+			return paths.size;
+		},
+		uninstall() {
+			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.
+				if (ownKeys.includes(key)) target[key] = value;
+				else delete target[key];
+			}
+			delete host[LABELS];
+		},
+	};
+	host[LABELS] = labels;
+	return labels;
+}
+
+/** Find pi-tui editors in a component tree (TUI → containers → editor). */
+export function findEditors(root: unknown): LabelTarget[] {
+	const found: LabelTarget[] = [];
+	const seen = new Set<unknown>();
+	const visit = (node: unknown) => {
+		if (!node || typeof node !== "object" || seen.has(node)) return;
+		seen.add(node);
+		const candidate = node as Partial<LabelTarget> & { pastes?: unknown; children?: unknown };
+		if (
+			typeof candidate.handlePaste === "function" &&
+			typeof candidate.segment === "function" &&
+			typeof candidate.expandPasteMarkers === "function" &&
+			candidate.pastes instanceof Map
+		) {
+			found.push(candidate as LabelTarget);
+		}
+		if (Array.isArray(candidate.children)) for (const child of candidate.children) visit(child);
+	};
+	visit(root);
+	return found;
+}
+
+export interface EditorWatcher {
+	readonly editors: number;
+	uninstall(): void;
+}
+
+/**
+ * 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.
+ */
+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;
+	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));
+			}
+			return originalRender.apply(this, args);
+		};
+	}
+	return {
+		get editors() {
+			return installed.size;
+		},
+		uninstall() {
+			for (const labels of installed.values()) labels.uninstall();
+			installed.clear();
+			if (!originalRender) return;
+			if (hadOwn) tui.doRender = originalRender;
+			else delete tui.doRender;
+		},
+	};
+}

package/src/status.ts

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