pi-orca-images 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 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.
+- Draw Kitty images in full inside Orca (draw-images-last render path).
+- Restore images lost while a tab was hidden, on focus-in.
+- `/orca-images status|test|redraw`.
+- `PI_ORCA_IMAGES=0` opt-out; explicit `PI_IMAGE_PROTOCOL` always wins.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JlMoreno00
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,67 @@
-# Temporary Holding Version
+# pi-orca-images
 
-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.
+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.
+
+```bash
+pi install npm:pi-orca-images
+```
+
+Restart Pi in an Orca terminal and run `/orca-images test`. You should see a color gradient.
+
+## What it fixes
+
+Orca renders inline images through xterm.js's image addon. Three things keep Pi's images from showing up there:
+
+| Problem | Cause | What this package does |
+|---|---|---|
+| No images at all | Pi does not recognize `TERM_PROGRAM=Orca` and ignores the `ORCA_IMAGE_PROTOCOL=kitty` hint that Orca exports | Sets `PI_IMAGE_PROTOCOL` from `ORCA_IMAGE_PROTOCOL` at startup |
+| 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
+
+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 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 |
+
+## Configuration
+
+It does nothing outside Orca. 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_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 |
+
+## Requirements and limits
+
+- 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
+
+```bash
+npm install
+npm run check          # typecheck + tests
+pi -e ./src/index.ts   # try it without installing
+```
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "pi-orca-images",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Inline images for the Pi coding agent inside Orca's terminal",
+  "type": "module",
+  "license": "MIT",
+  "author": "JlMoreno00",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JlMoreno00/pi-orca-images.git"
+  },
+  "homepage": "https://github.com/JlMoreno00/pi-orca-images#readme",
+  "bugs": "https://github.com/JlMoreno00/pi-orca-images/issues",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "orca",
+    "kitty-graphics",
+    "inline-images",
+    "terminal"
+  ],
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "engines": {
+    "node": ">=22.18"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "check": "npm run typecheck && npm test"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "1.4.0",
+    "@earendil-works/pi-tui": "1.4.0",
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.0"
+  }
+}

package/src/commands.ts

@@ -0,0 +1,12 @@
+export const SUBCOMMANDS = ["status", "test", "redraw"] as const;
+
+/**
+ * Argument completions for /orca-images. A complete subcommand yields none, so the first
+ * Enter runs the command instead of accepting a suggestion identical to the input.
+ */
+export function completeSubcommand(prefix: string): Array<{ value: string; label: string }> | null {
+	const typed = prefix.trim();
+	if ((SUBCOMMANDS as readonly string[]).includes(typed)) return null;
+	const matches = SUBCOMMANDS.filter((value) => value.startsWith(typed)).map((value) => ({ value, label: value }));
+	return matches.length > 0 ? matches : null;
+}

package/src/detect.ts

@@ -0,0 +1,49 @@
+export type ImageProtocol = "kitty" | "iterm2";
+
+export type Decision =
+	| { action: "apply"; protocol: ImageProtocol; reason: string }
+	| { action: "skip"; reason: string }
+	| { action: "clear-inherited"; reason: string };
+
+export type Env = Record<string, string | undefined>;
+
+/** Records the PI_IMAGE_PROTOCOL value this package set, so a later run can tell it from a user choice. */
+export const OWNED_ENV = "PI_ORCA_IMAGES_OWNED";
+
+const DISABLED = new Set(["0", "false", "off", "no"]);
+
+/** Decide whether Pi should draw images, from the environment alone. */
+export function decide(env: Env): Decision {
+	const owned = env[OWNED_ENV];
+	const current = env.PI_IMAGE_PROTOCOL;
+	const inherited = current !== undefined && current === owned;
+	const skip = (reason: string): Decision =>
+		inherited ? { action: "clear-inherited", reason } : { action: "skip", reason };
+
+	if (DISABLED.has((env.PI_ORCA_IMAGES ?? "").toLowerCase())) return skip("disabled by PI_ORCA_IMAGES");
+	if (current && !inherited) return { action: "skip", reason: `PI_IMAGE_PROTOCOL=${current} is set explicitly` };
+
+	const term = (env.TERM ?? "").toLowerCase();
+	if (env.TMUX || term.startsWith("tmux") || term.startsWith("screen")) {
+		return skip("inside tmux or screen; image escapes do not reach Orca");
+	}
+
+	const advertised = env.ORCA_IMAGE_PROTOCOL;
+	if (!advertised) {
+		if ((env.TERM_PROGRAM ?? "").toLowerCase() === "orca") {
+			return skip("Orca does not advertise inline images (ORCA_IMAGE_PROTOCOL is unset); update Orca");
+		}
+		return skip("not running inside Orca");
+	}
+
+	const protocol = advertised.toLowerCase();
+	if (protocol !== "kitty" && protocol !== "iterm2") {
+		return skip(`Orca advertises ORCA_IMAGE_PROTOCOL=${advertised}, which Pi cannot draw`);
+	}
+	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

@@ -0,0 +1,108 @@
+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 { 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";
+
+const COMMAND = "orca-images";
+const TEST_ENTRY = "pi-orca-images:test";
+const WIDGET = "pi-orca-images:probe";
+const USAGE = `Usage: /${COMMAND} [${SUBCOMMANDS.join("|")}]`;
+
+/** Apply the decision to the process environment, before Pi reads its capabilities. */
+function applyDecision(decision: Decision, env = process.env): void {
+	if (decision.action === "apply") {
+		env.PI_IMAGE_PROTOCOL = decision.protocol;
+		env[OWNED_ENV] = decision.protocol;
+	} else if (decision.action === "clear-inherited") {
+		delete env.PI_IMAGE_PROTOCOL;
+		delete env[OWNED_ENV];
+	} else {
+		return;
+	}
+	resetCapabilitiesCache();
+}
+
+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) => {
+		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) {
+				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 (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;
+	});
+
+	pi.registerEntryRenderer<{ width: number; height: number }>(TEST_ENTRY, (entry, _options, theme) => {
+		const { width = 240, height = 120 } = entry.data ?? {};
+		const box = new Container();
+		box.addChild(new Text(theme.fg("muted", `pi-orca-images test image (${width}x${height})`), 0, 0));
+		box.addChild(
+			new Image(testImagePng(width, height), "image/png", { fallbackColor: (s: string) => theme.fg("warning", s) }, {
+				maxWidthCells: 30,
+			}),
+		);
+		return box;
+	});
+
+	pi.registerCommand(COMMAND, {
+		description: "Inline images in Orca: status, test, or redraw",
+		getArgumentCompletions: completeSubcommand,
+		handler: async (args, ctx) => {
+			const sub = (args ?? "").trim() || "status";
+			if (sub === "status") {
+				ctx.ui.notify(
+					formatStatus({
+						decision,
+						images: getCapabilities().images,
+						shim,
+						orcaVersion: process.env.ORCA_APP_VERSION ?? process.env.TERM_PROGRAM_VERSION,
+						labels: labels && watcher !== undefined,
+					}),
+					"info",
+				);
+			} else if (sub === "test") {
+				pi.appendEntry(TEST_ENTRY, { width: 240, height: 120 });
+			} 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");
+			} else {
+				ctx.ui.notify(USAGE, "warning");
+			}
+		},
+	});
+}

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/shim.ts

@@ -0,0 +1,116 @@
+/** Focus-in report; Pi enables focus reporting (DECSET 1004) in fullscreen mode. */
+export const FOCUS_IN = "\x1b[I";
+
+/**
+ * Orca rebuilds a pane from its snapshot about 1.5-3 s after the tab is shown again,
+ * which wipes every inline image. Repainting at several points outlasts that restore.
+ */
+export const RECOVERY_DELAYS_MS = [300, 1500, 3000, 5000];
+
+/** The parts of Pi's TUI the shim touches. Every member except requestRender is optional. */
+export interface ShimTarget {
+	doRender?: (...args: unknown[]) => unknown;
+	handleViewportInput?: (data: string) => unknown;
+	uploadedKittyImages?: { clear(): void };
+	requestRender(force?: boolean): void;
+}
+
+export interface ShimOptions {
+	env?: Record<string, string | undefined>;
+	setTimer?: (fn: () => void, ms: number) => unknown;
+	clearTimer?: (handle: unknown) => void;
+	delays?: readonly number[];
+}
+
+export interface Shim {
+	readonly renderPatched: boolean;
+	readonly focusPatched: boolean;
+	readonly recoveries: number;
+	recover(): void;
+	uninstall(): void;
+}
+
+const SHIM = Symbol.for("pi-orca-images.shim");
+const WEZTERM_MARKER = "pi-orca-images";
+
+const defaultSetTimer = (fn: () => void, ms: number) => {
+	const handle = setTimeout(fn, ms);
+	handle.unref?.();
+	return handle;
+};
+const defaultClearTimer = (handle: unknown) => clearTimeout(handle as ReturnType<typeof setTimeout>);
+
+/**
+ * Patch one Pi TUI instance for Orca.
+ *
+ * Render: xterm's image addon stores Kitty images per cell, so Pi's later line writes erase
+ * every row but the first. Pi already draws images last for WezTerm, which has the same
+ * behavior; the shim enables that path only during the synchronous render, so the variable
+ * never reaches child processes.
+ *
+ * Focus: when the tab is shown again, the shim clears Pi's upload cache and forces a full
+ * render, so images Orca dropped while hidden are sent again.
+ */
+export function installShim(tui: ShimTarget, options: ShimOptions = {}): Shim {
+	const host = tui as ShimTarget & { [SHIM]?: Shim };
+	const existing = host[SHIM];
+	if (existing) return existing;
+
+	const env = options.env ?? process.env;
+	const setTimer = options.setTimer ?? defaultSetTimer;
+	const clearTimer = options.clearTimer ?? defaultClearTimer;
+	const delays = options.delays ?? RECOVERY_DELAYS_MS;
+	const originalRender = tui.doRender;
+	const originalInput = tui.handleViewportInput;
+	let timers: unknown[] = [];
+	let recoveries = 0;
+
+	const cancel = () => {
+		for (const timer of timers) clearTimer(timer);
+		timers = [];
+	};
+
+	const shim: Shim = {
+		renderPatched: typeof originalRender === "function",
+		focusPatched: typeof originalInput === "function",
+		get recoveries() {
+			return recoveries;
+		},
+		recover() {
+			recoveries++;
+			tui.uploadedKittyImages?.clear();
+			tui.requestRender(true);
+		},
+		uninstall() {
+			cancel();
+			if (shim.renderPatched) tui.doRender = originalRender;
+			if (shim.focusPatched) tui.handleViewportInput = originalInput;
+			delete host[SHIM];
+		},
+	};
+
+	if (originalRender) {
+		tui.doRender = function (this: unknown, ...args: unknown[]) {
+			if (env.WEZTERM_PANE !== undefined) return originalRender.apply(this, args);
+			env.WEZTERM_PANE = WEZTERM_MARKER;
+			try {
+				return originalRender.apply(this, args);
+			} finally {
+				delete env.WEZTERM_PANE;
+			}
+		};
+	}
+
+	if (originalInput) {
+		tui.handleViewportInput = function (this: unknown, data: string) {
+			if (data === FOCUS_IN) {
+				cancel();
+				timers = delays.map((ms) => setTimer(() => shim.recover(), ms));
+			}
+			return originalInput.call(this, data);
+		};
+	}
+
+	host[SHIM] = shim;
+	return shim;
+}

package/src/status.ts

@@ -0,0 +1,27 @@
+import type { Decision } from "./detect.ts";
+import type { Shim } from "./shim.ts";
+
+export interface StatusInput {
+	decision: Decision;
+	images: string | null | undefined;
+	shim: Pick<Shim, "renderPatched" | "focusPatched" | "recoveries"> | undefined;
+	orcaVersion: string | undefined;
+	labels: boolean;
+}
+
+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: ${
+				shim.focusPatched ? `on (recoveries: ${shim.recoveries})` : "unavailable"
+			}`
+		: "repaint fix: off";
+	return [
+		"pi-orca-images",
+		`  decision: ${action}: ${decision.reason}`,
+		`  Pi image protocol: ${images ?? "none"}`,
+		`  ${repaint}`,
+		`  image labels: ${labels ? "on" : "off (PI_IMAGE_LABELS)"}`,
+		`  Orca: ${orcaVersion ?? "not detected"}`,
+	].join("\n");
+}

package/src/test-image.ts

@@ -0,0 +1,46 @@
+import { deflateSync } from "node:zlib";
+
+const CRC_TABLE = Array.from({ length: 256 }, (_, n) => {
+	let c = n;
+	for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+	return c >>> 0;
+});
+
+function crc32(data: Buffer): number {
+	let c = 0xffffffff;
+	for (const byte of data) c = CRC_TABLE[(c ^ byte) & 0xff]! ^ (c >>> 8);
+	return (c ^ 0xffffffff) >>> 0;
+}
+
+function chunk(type: string, data: Buffer): Buffer {
+	const length = Buffer.alloc(4);
+	length.writeUInt32BE(data.length);
+	const body = Buffer.concat([Buffer.from(type, "ascii"), data]);
+	const crc = Buffer.alloc(4);
+	crc.writeUInt32BE(crc32(body));
+	return Buffer.concat([length, body, crc]);
+}
+
+/** A diagonal color gradient as a base64 PNG; it needs no file and shows full-height rendering at a glance. */
+export function testImagePng(width = 240, height = 120): string {
+	const header = Buffer.alloc(13);
+	header.writeUInt32BE(width, 0);
+	header.writeUInt32BE(height, 4);
+	header.set([8, 2, 0, 0, 0], 8);
+	const rowLength = 1 + width * 3;
+	const raw = Buffer.alloc(rowLength * height);
+	for (let y = 0; y < height; y++) {
+		for (let x = 0; x < width; x++) {
+			const offset = y * rowLength + 1 + x * 3;
+			raw[offset] = Math.round((255 * x) / Math.max(1, width - 1));
+			raw[offset + 1] = Math.round((255 * y) / Math.max(1, height - 1));
+			raw[offset + 2] = 200;
+		}
+	}
+	return Buffer.concat([
+		Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+		chunk("IHDR", header),
+		chunk("IDAT", deflateSync(raw)),
+		chunk("IEND", Buffer.alloc(0)),
+	]).toString("base64");
+}