@quandev104/pi-style 0.2.2 → 0.2.3

package/extension-src/pi-style/features/messages/image-preview.ts

@@ -0,0 +1,288 @@
+// Inline previews for user-prompt images (ADR 0008).
+//
+// Absorbs the presentation half of @pi-archimedes/image-paste: images attached
+// to the user's prompt render inline directly below the user message. The
+// channel is a display-only CustomEntry (documented as "not sent to the LLM";
+// ignored by buildSessionContext) — unlike image-paste's display-only custom
+// *messages*, whose custom_message entries map into the session's context
+// message list (sessionEntryToContextMessages) and would ride the context
+// pipeline for the rest of the session.
+//
+// Ordering (verified against Pi 0.84.2): appending at `before_agent_start`
+// lands the entry ABOVE the user message — the user message enters the feed
+// only when UI listeners process `message_start(user)` and persists at
+// `message_end(user)`, both AFTER extension handlers. So the append is staged
+// at `before_agent_start` (the only event carrying the prompt's `images`) and
+// flushed at the first `message_start(assistant)`: by then the user message is
+// in the feed and persisted, and the host inserts the entry below it (spliced
+// before the streaming component, or appended at the chat tail).
+//
+// Layout: `#N · WxH` label rows tie each image to its `[Image #N]` marker;
+// multiple images render side-by-side on kitty-capable terminals (kitty
+// graphics sequences are zero-width, so line zipping composes them), stacked
+// elsewhere. Width is capped by `messages.previewMaxWidth` (default 30);
+// Pi's global expansion (Ctrl+O) lifts the cap for a closer look.
+//
+// Fail-closed rules: unknown/malformed entry data renders zero lines (never
+// an error box, never base64 leakage); a theme without fg disables the
+// surface; the config leaf gates both the stage and the render side.
+
+import {
+	type Component,
+	getCapabilities,
+	getImageDimensions,
+	Image,
+	type ImageDimensions,
+} from "@earendil-works/pi-tui";
+import { visibleWidth } from "../../shared/ansi.js";
+import { getMessagesRenderConfig } from "./render-config.js";
+
+/** Session-entry customType for user-prompt image previews. */
+export const IMAGE_PREVIEW_ENTRY_TYPE = "pi-style-image-preview";
+
+/** Expanded-state (Ctrl+O) width cap — closer look without config changes. */
+export const IMAGE_PREVIEW_EXPANDED_MAX_WIDTH_CELLS = 60;
+
+/** Hard bounds for the `messages.previewMaxWidth` leaf. */
+export const IMAGE_PREVIEW_MIN_WIDTH_CELLS = 8;
+export const IMAGE_PREVIEW_MAX_WIDTH_CELLS = 60;
+
+/** Grid layout constants (kitty side-by-side). */
+const GRID_GAP = 2;
+const GRID_MIN_COLUMN = 14;
+
+/** Persisted entry payload: base64 data + mime type per attached image. */
+export interface ImagePreviewImage {
+	readonly data: string;
+	readonly mimeType: string;
+}
+
+export interface ImagePreviewEntryData {
+	readonly images: readonly ImagePreviewImage[];
+}
+
+/**
+ * Structural port over the host APIs this surface uses. The pi/ layer passes
+ * the ExtensionAPI; tests pass fakes.
+ */
+export interface ImagePreviewHostPort {
+	registerEntryRenderer(
+		customType: string,
+		renderer: (entry: unknown, options: unknown, theme: unknown) => unknown,
+	): void;
+	appendEntry(customType: string, data?: unknown): void;
+}
+
+function isPreviewableImage(value: unknown): value is ImagePreviewImage {
+	if (!value || typeof value !== "object") return false;
+	const data = (value as { data?: unknown }).data;
+	const mimeType = (value as { mimeType?: unknown }).mimeType;
+	return typeof data === "string" && data.length > 0 && typeof mimeType === "string" && mimeType.length > 0;
+}
+
+/**
+ * Entry-data view of a prompt's attached images: drops malformed blocks,
+ * returns undefined when nothing previewable remains (no entry is appended).
+ * Config-gated (`messages.showImagePreviews`).
+ */
+export function stageImagePreviewData(images: readonly unknown[]): ImagePreviewEntryData | undefined {
+	if (!getMessagesRenderConfig().showImagePreviews) return undefined;
+	const valid = images.filter(isPreviewableImage).map((image) => ({ data: image.data, mimeType: image.mimeType }));
+	return valid.length > 0 ? { images: valid } : undefined;
+}
+
+/** Flush a staged preview as a session entry (display-only CustomEntry). */
+export function flushImagePreviewEntry(pi: ImagePreviewHostPort, data: ImagePreviewEntryData): void {
+	if (!getMessagesRenderConfig().showImagePreviews) return;
+	pi.appendEntry(IMAGE_PREVIEW_ENTRY_TYPE, data);
+}
+
+/** Validated images from a persisted entry's data field; undefined = malformed. */
+function previewImagesFromEntryData(data: unknown): readonly ImagePreviewImage[] | undefined {
+	if (!data || typeof data !== "object") return undefined;
+	const images = (data as { images?: unknown }).images;
+	if (!Array.isArray(images) || images.length === 0) return undefined;
+	if (!images.every(isPreviewableImage)) return undefined;
+	return images;
+}
+
+type FgColor = (color: string, text: string) => string;
+
+/** `#N` label for entry position N (1-based — matches `[Image #N]` markers).
+ *  Dimensions arrive pre-parsed (parseImageDimensions) — no decode here. */
+function imageLabel(theme: { fg: FgColor }, index: number, dims?: ImageDimensions): string {
+	const dimsPart = dims ? ` · ${dims.widthPx}×${dims.heightPx}` : "";
+	return theme.fg("dim", `#${index}${dimsPart}`);
+}
+
+/** Test hook: counts parseImageDimensions invocations (entry-reuse contract). */
+export const __dimensionParsesForTest = { count: 0 };
+
+/** Parse image dimensions from a base64 PREFIX first — 256 chars (a whole
+ *  number of base64 blocks, ~192 bytes) covers the PNG/GIF/WebP headers and
+ *  the usual early JPEG SOF marker. Only when the prefix fails (rare — a
+ *  late JPEG SOF) do we decode the full payload. Avoids decoding a ~1.3MB
+ *  screenshot just to read ~24 header bytes on every rebuild. */
+function parseImageDimensions(image: ImagePreviewImage): ImageDimensions | undefined {
+	__dimensionParsesForTest.count++;
+	const fromPrefix = getImageDimensions(image.data.slice(0, 256), image.mimeType);
+	return fromPrefix ?? getImageDimensions(image.data, image.mimeType) ?? undefined;
+}
+
+/** Per-entry render artifacts (components, labels). */
+interface PreviewCache {
+	readonly images: readonly ImagePreviewImage[];
+	readonly components: Image[];
+	readonly labels: string[];
+}
+
+/** The host's CustomEntryComponent re-invokes the renderer on every resize,
+ *  Ctrl+O toggle, and cell-size response — always with the SAME entry object
+ *  (rebuild() passes this.entry). Keying on that object lets Image components
+ *  keep their internal line caches and kitty image ids (no re-chunking, no id
+ *  churn) and labels their parsed dimensions across rebuilds. */
+const previewCache = new WeakMap<object, PreviewCache>();
+
+/**
+ * Entry renderer for `pi-style-image-preview` entries. Returns undefined
+ * (zero-line render) when the surface is disabled, the entry data is
+ * malformed, or the theme lacks fg — never throws, never leaks base64 into a
+ * rendered line (the pi-tui Image fallback vocabulary is mime + dimensions).
+ */
+export function renderImagePreviewEntry(entry: unknown, options: unknown, theme: unknown): Component | undefined {
+	if (!getMessagesRenderConfig().showImagePreviews) return undefined;
+	const images = previewImagesFromEntryData((entry as { data?: unknown } | null | undefined)?.data);
+	if (!images) return undefined;
+	const fg = (theme as { fg?: FgColor } | null | undefined)?.fg;
+	if (typeof fg !== "function") return undefined;
+	const expanded = (options as { expanded?: boolean } | null | undefined)?.expanded === true;
+	try {
+		const themed = { fg: fg.bind(theme) } as { fg: FgColor };
+		let cached = previewCache.get(entry as object);
+		if (!cached) {
+			const dims = images.map(parseImageDimensions);
+			const components = images.map(
+				(image, index) =>
+					new Image(
+						image.data,
+						image.mimeType,
+						{ fallbackColor: (text: string) => themed.fg("toolOutput", text) },
+						{},
+						dims[index],
+					),
+			);
+			const labels = images.map((_image, index) => imageLabel(themed, index + 1, dims[index]));
+			cached = { images, components, labels };
+			previewCache.set(entry as object, cached);
+		}
+		const { components, labels } = cached;
+		// Memoized output: render passes tick on every streaming update; the
+		// same width/expansion/config/capability key returns the SAME array
+		// reference, skipping the grid re-zip and the host's per-line diff.
+		let memo: { key: string; lines: string[] } | undefined;
+		return {
+			invalidate() {
+				memo = undefined;
+				for (const component of components) component.invalidate();
+			},
+			render(width: number): string[] {
+				const config = getMessagesRenderConfig();
+				const kitty = getCapabilities().images === "kitty";
+				const key = `${width}|${expanded}|${config.previewMaxWidth}|${config.showImagePreviews}|${kitty}`;
+				if (memo && memo.key === key) return memo.lines;
+				const maxWidth = expanded
+					? IMAGE_PREVIEW_EXPANDED_MAX_WIDTH_CELLS
+					: Math.min(config.previewMaxWidth, IMAGE_PREVIEW_MAX_WIDTH_CELLS);
+				let lines: string[];
+				if (width <= 0) lines = [];
+				else if (images.length === 1 || !kitty) lines = renderStacked(width, maxWidth, labels, components);
+				else lines = renderGrid(width, maxWidth, labels, components);
+				memo = { key, lines };
+				return lines;
+			},
+		};
+	} catch {
+		return undefined;
+	}
+}
+
+/** One labeled image per block, a blank line between (also the fallback path). */
+function renderStacked(width: number, maxWidth: number, labels: string[], components: Image[]): string[] {
+	const lines: string[] = [];
+	for (const [index, component] of components.entries()) {
+		if (index > 0) lines.push("");
+		lines.push(labels[index] ?? "");
+		lines.push(...component.render(Math.min(width, Math.max(1, maxWidth + 2))));
+	}
+	return lines;
+}
+
+/** Strip trailing spaces without scanning the whole line: kitty rows always
+ *  end with the `ESC \` terminator (never trailing spaces), so the fast path
+ *  is one endsWith check; only space-padded rows pay for the strip. */
+function stripTrailingSpaces(line: string): string {
+	if (!line.endsWith(" ")) return line;
+	let end = line.length;
+	while (end > 0 && line.charCodeAt(end - 1) === 0x20) end--;
+	return line.slice(0, end);
+}
+
+/**
+ * Side-by-side grid (kitty graphics only — sequences are zero-width so
+ * per-row line zipping composes columns). Columns shrink to fit the width;
+ * when fewer than two usable columns fit, this degrades to stacked.
+ */
+function renderGrid(width: number, maxWidth: number, labels: string[], components: Image[]): string[] {
+	const usable = Math.max(1, width - 2);
+	const maxColumns = Math.floor((usable + GRID_GAP) / (GRID_MIN_COLUMN + GRID_GAP));
+	const columns = Math.max(1, Math.min(components.length, maxColumns, 3));
+	if (columns < 2) return renderStacked(width, maxWidth, labels, components);
+	const columnWidth = Math.min(maxWidth, Math.floor((usable - (columns - 1) * GRID_GAP) / columns));
+	if (columnWidth < GRID_MIN_COLUMN) return renderStacked(width, maxWidth, labels, components);
+
+	const lines: string[] = [];
+	for (let start = 0; start < components.length; start += columns) {
+		const group = components.slice(start, start + columns);
+		const groupLabels = labels.slice(start, start + columns);
+		if (start > 0) lines.push("");
+		const rendered = group.map((component) => component.render(columnWidth));
+		// Label row: each label padded to its column width, gap between.
+		const labelRow = groupLabels
+			.map((label, _index) => {
+				const pad = Math.max(0, columnWidth - visibleWidth(stripFormatting(label)));
+				return label + " ".repeat(pad);
+			})
+			.join(" ".repeat(GRID_GAP))
+			.trimEnd();
+		lines.push(labelRow);
+		// Image rows: zip columns line by line. Kitty places each image at the
+		// CURSOR position when its transmission completes, and the sequences are
+		// zero-width — so after image 1 the cursor is still at column 0 and the
+		// second transmission would land ON TOP of image 1. Each subsequent
+		// column therefore starts with a CHA jump (`ESC[<col>G`, 1-based) to its
+		// start column; terminal/herdr cursor tracking follows, and both images
+		// composite side by side.
+		const rows = Math.max(...rendered.map((column) => column.length));
+		for (let row = 0; row < rows; row++) {
+			let line = "";
+			for (let column = 0; column < rendered.length; column++) {
+				if (column > 0) {
+					const startCol = column * (columnWidth + GRID_GAP);
+					line += `\x1b[${startCol + 1}G`;
+				}
+				line += rendered[column]?.[row] ?? "";
+			}
+			lines.push(stripTrailingSpaces(line));
+		}
+	}
+	return lines;
+}
+
+/** Label text may carry ANSI color; measure only the visible part.
+ *  Reuses the shared ANSI-stripping utility (no local control-char regex). */
+import { stripAnsi as stripFormatting } from "../../shared/ansi.js";
+
+/** Register the entry renderer (extension load; before any entry can exist). */
+export function registerImagePreviewSurface(pi: ImagePreviewHostPort): void {
+	pi.registerEntryRenderer(IMAGE_PREVIEW_ENTRY_TYPE, renderImagePreviewEntry);
+}

package/extension-src/pi-style/features/messages/render-config.ts

@@ -0,0 +1,36 @@
+// Per-session render configuration for message-surface features.
+//
+// Mirrors the tools surface's session-config pattern (features/tools/boxed/
+// session-config.ts): set once per session by the compatibility coordinator,
+// read inside renderers, and kept out of the render path (no filesystem or
+// config reads during render).
+
+export interface MessagesRenderConfig {
+	/** Inline previews for user-prompt images (ADR 0008). Gates both the
+	 *  stage side (before_agent_start) and the render side (entry renderer). */
+	showImagePreviews: boolean;
+	/** Clipboard image input (ADR 0009): upgrade built-in paste temp paths to
+	 *  real image attachments on submit. Gates the input transform only. */
+	clipboardImages: boolean;
+	/** Max cell width per preview image (ADR 0008); Ctrl+O expansion uses 60. */
+	previewMaxWidth: number;
+}
+
+let sessionMessagesConfig: MessagesRenderConfig = {
+	showImagePreviews: true,
+	clipboardImages: true,
+	previewMaxWidth: 30,
+};
+
+export function setMessagesRenderConfig(config: Partial<MessagesRenderConfig>): void {
+	sessionMessagesConfig = { ...sessionMessagesConfig, ...config };
+}
+
+export function getMessagesRenderConfig(): MessagesRenderConfig {
+	return sessionMessagesConfig;
+}
+
+/** Reset to defaults (test isolation). */
+export function resetMessagesRenderConfig(): void {
+	sessionMessagesConfig = { showImagePreviews: true, clipboardImages: true, previewMaxWidth: 30 };
+}

package/extension-src/pi-style/pi/index.ts

@@ -1,5 +1,12 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { StatusSnapshot } from "../domain/status.js";
+import { resolvePendingImageMarkers, transformClipboardImages } from "../features/messages/image-input.js";
+import {
+	flushImagePreviewEntry,
+	type ImagePreviewEntryData,
+	registerImagePreviewSurface,
+	stageImagePreviewData,
+} from "../features/messages/image-preview.js";
 import { closeActiveBatch } from "../features/tools/boxed/batch.js";
 import {
 	beginAgentRun,
@@ -64,6 +71,27 @@ export default function piStyleExtension(pi: ExtensionAPI): void {
 	pi.registerFlag("pi-style-ascii", { type: "boolean", description: "Use ASCII pi-style markers" });
 	const coordinator = createPiStyleSessionCoordinator(pi, compatibilityTestHooks);
 	registerPiStyleCommand(pi, coordinator.app);
+	// User-prompt image previews (ADR 0008): the entry renderer must be
+	// registered before the first entry of this type can exist — the host drops
+	// entries whose customType has no renderer — and once at extension load is
+	// enough (persisted entries from previous sessions render on resume).
+	registerImagePreviewSurface(pi);
+	// User-prompt image previews (ADR 0008): stage at `before_agent_start` (the
+	// only event carrying the prompt's `images`), flush as a display-only entry
+	// at the first `message_start(assistant)`. Appending at before_agent_start
+	// would land the entry ABOVE the user message — the user message enters the
+	// feed only when UI listeners process message_start(user) and persists at
+	// message_end(user), both after extension handlers. At the first assistant
+	// message the user message is already rendered and persisted, so the host
+	// inserts the entry below it (spliced before the streaming component) and
+	// the session file records user → preview → assistant for identical resume.
+	// Edge: a steered prompt arriving before the first flush overwrites the
+	// staged slot (last write wins) — steer-with-image is a rare corner.
+	let stagedImagePreview: ImagePreviewEntryData | undefined;
+	pi.on("before_agent_start", (event) => {
+		const staged = stageImagePreviewData(event.images ?? []);
+		if (staged) stagedImagePreview = staged;
+	});
 	pi.on("session_start", async (event, ctx) => {
 		resetUsageFromSessionCache(ctx.sessionManager);
 		// Pi only activates read/bash/edit/write by default; grep/find/ls are
@@ -81,7 +109,7 @@ export default function piStyleExtension(pi: ExtensionAPI): void {
 		// (user request → agent_end), not pi's per-message turn_end.
 		beginAgentRun();
 	});
-	pi.on("input", (event, _ctx) => {
+	pi.on("input", async (event, _ctx) => {
 		coordinator.app.runtime.current?.dismissStartup();
 		// Bare `!`/`!!` submit guard: Pi treats `!`-prefixed input as a direct bash
 		// command but falls through to normal message submission when the bang has
@@ -97,6 +125,23 @@ export default function piStyleExtension(pi: ExtensionAPI): void {
 				if (trimmed.slice(bangLength).trim() === "") return { action: "handled" };
 			}
 		}
+		// Clipboard image input (ADR 0009): `[Image #N]` markers resolve for EVERY
+		// submit source — a submit is a submit (image-paste semantics); consuming
+		// the registry one-shot on rpc/extension submits too keeps a pasted marker
+		// from dangling into a later, unrelated prompt. No-op when the registry is
+		// empty. Raw clipboard path tokens, in contrast, only ever come from the
+		// interactive editor's built-in paste — that upgrade stays interactive-only.
+		// Combined images flow on to before_agent_start, where the ADR 0008 preview
+		// entry picks them up.
+		const markerResult = await resolvePendingImageMarkers(event.text);
+		const pathResult = event.source === "interactive" ? await transformClipboardImages(event.text) : undefined;
+		if (markerResult || pathResult) {
+			return {
+				action: "transform" as const,
+				text: pathResult?.text ?? event.text,
+				images: [...(markerResult?.images ?? []), ...(pathResult?.images ?? [])],
+			};
+		}
 		return undefined;
 	});
 	pi.on("tool_execution_start", () => coordinator.app.runtime.current?.dismissStartup());
@@ -114,10 +159,16 @@ export default function piStyleExtension(pi: ExtensionAPI): void {
 	pi.on("session_info_changed", (event) =>
 		coordinator.app.update({ sessionName: event.name }, "coalesced", { refreshExtensionStatuses: true }),
 	);
-	pi.on("message_start", () => {
+	pi.on("message_start", (event) => {
 		// A new message is a batch boundary: quiet-tool (read/ls/find) calls of the
 		// new message start a fresh batch instead of joining the previous one.
 		closeActiveBatch();
+		// Flush the staged image preview below the just-rendered user message
+		// (ADR 0008 ordering — see the before_agent_start comment above).
+		if (stagedImagePreview && event.message?.role === "assistant") {
+			flushImagePreviewEntry(pi, stagedImagePreview);
+			stagedImagePreview = undefined;
+		}
 		// grep/bash tree panels are NOT cleared here: historical panels must keep
 		// their state so Pi re-renders of previous messages (scroll/resume) stay
 		// intact. Only session boundaries reset them (session-coordinator).

package/extension-src/pi-style/pi/session-coordinator.ts

@@ -3,6 +3,8 @@ import { type KeyId, matchesKey } from "@earendil-works/pi-tui";
 import type { ConfigFilePort } from "../app/config-storage.js";
 import { createPiStyleApp, type PiStyleApp } from "../app/index.js";
 import { resolveTheme } from "../domain/theme.js";
+import { resetPendingImageRegistry } from "../features/messages/image-input.js";
+import { setMessagesRenderConfig } from "../features/messages/render-config.js";
 import { setSpecialBlockTheme } from "../features/messages/special-blocks.js";
 import { setBashExecutionTheme } from "../features/tools/bash-execution.js";
 import { resetBashTreeRegistry } from "../features/tools/boxed/bash.js";
@@ -95,6 +97,14 @@ export function createPiStyleSessionCoordinator(pi: ExtensionAPI, hooks: Compati
 	 */
 	const applyMessagesConfig = (config: import("../domain/config-types.js").NormalizedPiStyleConfig) => {
 		sessionUi?.setHiddenThinkingLabel?.(config.messages.hideThinkingLabel ? "" : undefined);
+		// User-prompt image previews (ADR 0008) + clipboard image input (ADR
+		// 0009): the leaves gate their respective sides (preview: stage+render;
+		// clipboard: input transform) and size the preview images.
+		setMessagesRenderConfig({
+			showImagePreviews: config.messages.showImagePreviews,
+			clipboardImages: config.messages.clipboardImages,
+			previewMaxWidth: config.messages.previewMaxWidth,
+		});
 	};
 	/**
 	 * Auto-apply the configured pi-style theme (default "titanium") once per TUI
@@ -176,6 +186,8 @@ export function createPiStyleSessionCoordinator(pi: ExtensionAPI, hooks: Compati
 			resetBatchRegistry();
 			resetGrepRegistry();
 			resetBashTreeRegistry();
+			// Clipboard image pending markers (ADR 0009) never cross sessions.
+			resetPendingImageRegistry();
 			// Turn summaries (ADR 0007): rebuild the registry from session content so
 			// restored/forked history renders collapsed before the first render pass
 			// (deterministic; no in-process turn_end events needed).
@@ -253,6 +265,7 @@ export function createPiStyleSessionCoordinator(pi: ExtensionAPI, hooks: Compati
 			resetBatchRegistry();
 			resetGrepRegistry();
 			resetBashTreeRegistry();
+			resetPendingImageRegistry();
 			resetTurnRegistry();
 			stopAllElapsedTickers();
 			app.sessionShutdown();

package/extension-src/pi-style/shared/clipboard-path.ts

@@ -0,0 +1,98 @@
+// Clipboard-paste path pattern (ADR 0009).
+//
+// Pi's built-in Ctrl+V (app.clipboard.pasteImage) materializes clipboard
+// images as `<os.tmpdir()>/pi-clipboard-<uuid>.<ext>` files and inserts that
+// absolute path into the editor as text. This module owns the shape of those
+// artifacts so the editor feature (marker interception) and the messages
+// feature (submit transform) share one definition without cross-feature
+// imports (the pattern is a shared primitive).
+
+import { tmpdir } from "node:os";
+
+/** crypto.randomUUID() shape: lowercase v4, 8-4-4-4-12 hex groups. */
+export const UUID_PATTERN = "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}";
+
+/** Extensions Pi's clipboard paste writes (extensionForImageMimeType / png). */
+export const CLIPBOARD_IMAGE_EXTENSIONS = ["png", "jpg", "jpeg", "webp", "gif"] as const;
+
+/** Marker inserted by the editor interception for a pending pasted image. */
+export function clipboardImageMarker(index: number): string {
+	return `[Image #${index}]`;
+}
+
+/** `[Image #N]` marker token (editor interception; ADR 0009 marker surface). */
+export const CLIPBOARD_IMAGE_MARKER_PATTERN = /\[Image #([0-9]+)\]/g;
+
+function escapeRegExp(text: string): string {
+	return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** Memoized regexes keyed by tmp root: tmpdir() call + escapeRegExp + regex
+ *  compile happen once per root instead of on every submit/paste probe.
+ *  Bounded because tests inject arbitrary roots — past the cap the oldest
+ *  entry is evicted. Sharing one global instance per root is safe:
+ *  String.matchAll clones the regex into its iterator (original untouched),
+ *  and String.match/.replace with /g reset lastIndex themselves. */
+const clipboardPathRegexCache = new Map<string, RegExp>();
+const CLIPBOARD_PATH_REGEX_CACHE_MAX = 16;
+
+/** Regex matching Pi clipboard-paste paths under the given tmpdir (default: process).
+ *  Boundaries are non-alphanumeric (not whitespace-only): users type
+ *  punctuation straight after a pasted path (`<path>, đây là...`), so a
+ *  whitespace-or-EOL lookahead would miss the most common real shapes.
+ *  Alphanumeric neighbors still reject glued text (`x<path>`). */
+export function clipboardPathRegex(tmpRoot: string = tmpdir()): RegExp {
+	const cached = clipboardPathRegexCache.get(tmpRoot);
+	if (cached) return cached;
+	const exts = CLIPBOARD_IMAGE_EXTENSIONS.join("|");
+	const regex = new RegExp(
+		`(?<![a-zA-Z0-9])(${escapeRegExp(tmpRoot)}/pi-clipboard-${UUID_PATTERN}\\.(${exts}))(?![a-zA-Z0-9])`,
+		"g",
+	);
+	if (clipboardPathRegexCache.size >= CLIPBOARD_PATH_REGEX_CACHE_MAX) {
+		const oldest = clipboardPathRegexCache.keys().next().value;
+		if (oldest !== undefined) clipboardPathRegexCache.delete(oldest);
+	}
+	clipboardPathRegexCache.set(tmpRoot, regex);
+	return regex;
+}
+
+/** Test seam: clear the memoization cache (isolation between suites). */
+export function resetClipboardPathRegexCache(): void {
+	clipboardPathRegexCache.clear();
+}
+
+/** Test seam: current memoized-regex count (memoization observability). */
+export function __regexCacheSizeForTest(): number {
+	return clipboardPathRegexCache.size;
+}
+
+/** True when the whole string is exactly one clipboard-paste path token —
+ *  the shape Pi's handleClipboardPaste passes to insertTextAtCursor. */
+export function isSingleClipboardImagePath(text: string, tmpRoot?: string): boolean {
+	if (!text || /\s/.test(text)) return false;
+	const match = text.match(clipboardPathRegex(tmpRoot ?? tmpdir()));
+	return match !== null && match.length === 1 && match[0] === text;
+}
+
+/** All distinct clipboard-paste path tokens in the text (verbatim matches).
+ *  `tmpRoot` defaults to the process tmpdir; tests inject a fixed root. */
+export function extractClipboardImageTokens(text: string, tmpRoot?: string): string[] {
+	const tokens = new Set<string>();
+	for (const match of text.matchAll(clipboardPathRegex(tmpRoot ?? tmpdir()))) {
+		const token = match[1];
+		if (token) tokens.add(token);
+	}
+	return [...tokens];
+}
+
+const MARKER_AT_END_PATTERN = /\[Image #([0-9]+)\]( ?)$/;
+
+/** When `text` ends with a clipboard image marker, return its index and total
+ *  length (including the trailing space when present). Used by the editor's
+ *  atomic backspace: the marker directly before the cursor deletes as a unit. */
+export function clipboardMarkerAtEnd(text: string): { index: number; length: number } | undefined {
+	const match = MARKER_AT_END_PATTERN.exec(text);
+	if (!match) return undefined;
+	return { index: Number(match[1]), length: match[0].length };
+}

package/extension-src/pi-style/shared/clipboard-presence.ts

@@ -0,0 +1,112 @@
+// Sync clipboard-image presence probe (ADR 0009 instant-marker surface).
+//
+// Pi's built-in paste reads the clipboard asynchronously (native module,
+// ~90ms for a screenshot) before it can tell whether the clipboard even holds
+// an image. The native module also exposes a synchronous hasImage() poll —
+// resolving it through Pi's own install lets the editor insert the
+// `[Image #N] ` marker at keystroke time (zero-latency feedback) instead of
+// after the read, while text pastes stay untouched (no marker flash).
+//
+// Resolution mirrors Pi's clipboard-native.js: require "@mariozechner/clipboard"
+// relative to the pi-coding-agent package, where the module is installed.
+// Unresolvable (bundled/aliased hosts, Termux) → null → caller falls back to
+// the artifact-time marker path.
+
+import { realpathSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname } from "node:path";
+
+interface ClipboardPresenceModule {
+	hasImage(): boolean;
+	getImageBinary?(): Promise<Array<number> | Uint8Array>;
+}
+
+let cachedModule: ClipboardPresenceModule | null | undefined;
+
+/** Resolution roots, ordered: the running pi process's own module graph first
+ *  (process.argv[1] is pi's cli — its install carries @mariozechner/clipboard
+ *  as an optionalDependency, possibly nested and NOT visible from the
+ *  extension project's node_modules), then the extension's own graph.
+ *  argv[1] may be a symlink (bin/pi) — realpath it first so the require root
+ *  lands inside the real install. */
+function clipboardResolutionRoots(): string[] {
+	const roots: string[] = [];
+	const argvMain = process.argv[1];
+	if (typeof argvMain === "string" && argvMain.startsWith("/")) {
+		try {
+			roots.push(dirname(realpathSync(argvMain)));
+		} catch {
+			roots.push(dirname(argvMain));
+		}
+	}
+	roots.push(import.meta.url);
+	return roots;
+}
+
+function loadClipboardModule(): ClipboardPresenceModule | null {
+	if (cachedModule !== undefined) return cachedModule;
+	if (process.env.TERMUX_VERSION) {
+		cachedModule = null;
+		return cachedModule;
+	}
+	for (const root of clipboardResolutionRoots()) {
+		try {
+			const require = createRequire(root);
+			const resolved = require("@mariozechner/clipboard") as ClipboardPresenceModule;
+			if (resolved && typeof resolved.hasImage === "function") {
+				cachedModule = resolved;
+				return cachedModule;
+			}
+		} catch {
+			// Try the next resolution root.
+		}
+	}
+	cachedModule = null;
+	return cachedModule;
+}
+
+/**
+ * True when the system clipboard currently holds an image; null when the
+ * native clipboard module is unavailable (caller must not use the result to
+ * gate instant feedback — fall back to the async path instead).
+ */
+export function clipboardHasImageSync(): boolean | null {
+	const clipboard = loadClipboardModule();
+	if (!clipboard || typeof clipboard.hasImage !== "function") return null;
+	try {
+		return clipboard.hasImage() === true;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Read the clipboard image bytes directly through the native module (PNG on
+ * platforms where the module reports images). Null when unavailable or the
+ * clipboard holds no image — callers fall back to artifact-time handling.
+ * `skipPresenceProbe`: for callers that already confirmed presence via
+ * hasImage() (the owned-paste path probes at keystroke time) — skips the
+ * redundant second native probe. Default behavior is unchanged.
+ */
+export async function readClipboardImageBinary(options: { skipPresenceProbe?: boolean } = {}): Promise<{
+	bytes: Uint8Array;
+} | null> {
+	const clipboard = loadClipboardModule();
+	if (!clipboard || typeof clipboard.hasImage !== "function" || typeof clipboard.getImageBinary !== "function") {
+		return null;
+	}
+	try {
+		if (!options.skipPresenceProbe && !clipboard.hasImage()) return null;
+		const imageData = await clipboard.getImageBinary();
+		if (!imageData || imageData.length === 0) return null;
+		const bytes = imageData instanceof Uint8Array ? imageData : Uint8Array.from(imageData);
+		return bytes.length > 0 ? { bytes } : null;
+	} catch {
+		return null;
+	}
+}
+
+/** Test seam: forget the cached module resolution. */
+export function resetClipboardPresenceCache(): void {
+	cachedModule = undefined;
+}