@quandev104/pi-style 0.2.2 → 0.2.4

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

@@ -0,0 +1,335 @@
+// 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);
+// Kitty slots use the actual rendered image width to avoid portrait-image gaps;
+// strongly height-mismatched images stack instead of leaving empty rows. 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 CellDimensions,
+	type Component,
+	getCapabilities,
+	getCellDimensions,
+	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;
+const GRID_MAX_HEIGHT_RATIO = 1.5;
+const FALLBACK_IMAGE_DIMENSIONS: ImageDimensions = { widthPx: 800, heightPx: 600 };
+
+/** 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 dimensions: readonly (ImageDimensions | undefined)[];
+	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, dimensions: dims, components, labels };
+			previewCache.set(entry as object, cached);
+		}
+		const { components, dimensions, 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, dimensions);
+				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;
+ * compact slots follow actual image widths; strongly height-mismatched groups
+ * degrade to stacked. When fewer than two usable columns fit, this also
+ * degrades to stacked.
+ */
+function renderGrid(
+	width: number,
+	maxWidth: number,
+	labels: string[],
+	components: Image[],
+	dimensions: readonly (ImageDimensions | undefined)[],
+): 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[] = [];
+	const cellDimensions = getCellDimensions();
+	for (let start = 0; start < components.length; start += columns) {
+		const group = components.slice(start, start + columns);
+		const groupLabels = labels.slice(start, start + columns);
+		const groupDimensions = dimensions.slice(start, start + columns);
+		if (start > 0) lines.push("");
+		const rendered = group.map((component) => component.render(columnWidth));
+		const sizes = groupDimensions.map((imageDimensions) => imageCellSize(imageDimensions, columnWidth, cellDimensions));
+
+		// Avoid keeping a short neighbor's column alive for a much taller image.
+		// Similar screenshots remain side-by-side; strongly mismatched images stack.
+		const rowCounts = rendered.map((column) => column.length).filter((count) => count > 0);
+		const minRows = Math.min(...rowCounts);
+		const maxRows = Math.max(...rowCounts);
+		if (rowCounts.length > 1 && minRows > 0 && maxRows >= minRows * GRID_MAX_HEIGHT_RATIO) {
+			return renderStacked(width, maxWidth, labels, components);
+		}
+
+		// Use actual image widths for the slots instead of the shared max width.
+		// This removes unused horizontal space around narrow portrait images.
+		const slotWidths = groupLabels.map((label, index) =>
+			Math.max(sizes[index]?.columns ?? 1, visibleWidth(stripFormatting(label))),
+		);
+		const labelRow = groupLabels
+			.map((label, index) => {
+				const pad = Math.max(0, (slotWidths[index] ?? 0) - visibleWidth(stripFormatting(label)));
+				return label + " ".repeat(pad);
+			})
+			.join(" ".repeat(GRID_GAP))
+			.trimEnd();
+		lines.push(labelRow);
+
+		// Kitty sequences are zero-width, so each image starts with a CHA jump.
+		// The offset is based on cumulative compact slot widths, not columnWidth.
+		const rows = Math.max(...rendered.map((column) => column.length));
+		for (let row = 0; row < rows; row++) {
+			let line = "";
+			let startCol = 0;
+			for (let column = 0; column < rendered.length; column++) {
+				if (column > 0) line += `\x1b[${startCol + 1}G`;
+				line += rendered[column]?.[row] ?? "";
+				startCol += (slotWidths[column] ?? 0) + GRID_GAP;
+			}
+			lines.push(stripTrailingSpaces(line));
+		}
+	}
+	return lines;
+}
+
+/** Match pi-tui Image.render's Kitty cell-size calculation for slot sizing. */
+function imageCellSize(
+	dimensions: ImageDimensions | undefined,
+	requestedWidth: number,
+	cellDimensions: CellDimensions,
+): { columns: number; rows: number } {
+	const imageDimensions = dimensions ?? FALLBACK_IMAGE_DIMENSIONS;
+	const maxWidth = Math.max(1, Math.min(requestedWidth - 2, 60));
+	const maxHeight = Math.max(1, Math.ceil((maxWidth * cellDimensions.widthPx) / cellDimensions.heightPx));
+	const imageWidth = Math.max(1, imageDimensions.widthPx);
+	const imageHeight = Math.max(1, imageDimensions.heightPx);
+	const widthScale = (maxWidth * cellDimensions.widthPx) / imageWidth;
+	const heightScale = (maxHeight * cellDimensions.heightPx) / imageHeight;
+	const scale = Math.min(widthScale, heightScale);
+	return {
+		columns: Math.max(1, Math.min(maxWidth, Math.ceil((imageWidth * scale) / cellDimensions.widthPx))),
+		rows: Math.max(1, Math.min(maxHeight, Math.ceil((imageHeight * scale) / cellDimensions.heightPx))),
+	};
+}
+
+/** 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,26 @@ 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): the prompt's `images` are only
+	// available at `before_agent_start`, but appending there would place the entry
+	// above the user message because extension handlers run before the UI handles
+	// `message_start(user)`. Capture there, then flush on the next event-loop turn
+	// after `message_start(user)` so the preview appears immediately below it.
+	// The assistant-start handler is a synchronous fallback for runtimes that begin
+	// the assistant before the deferred flush runs. A steered prompt arriving before
+	// flush replaces the staged slot (last write wins).
+	let stagedImagePreview: ImagePreviewEntryData | undefined;
+	let previewFlushTimer: ReturnType<typeof setTimeout> | undefined;
+	pi.on("before_agent_start", (event) => {
+		// Always replace the slot: a subsequent image-less prompt must not
+		// accidentally flush the previous prompt's preview.
+		stagedImagePreview = stageImagePreviewData(event.images ?? []);
+	});
 	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 +108,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 +124,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 +158,32 @@ 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();
+		if (event.message?.role === "user" && stagedImagePreview && !previewFlushTimer) {
+			// Extension handlers run before Pi's interactive listener adds the user
+			// message to the chat. Defer one turn so the entry is appended below the
+			// visible user message, but do not wait for assistant content to arrive.
+			const pending = stagedImagePreview;
+			previewFlushTimer = setTimeout(() => {
+				previewFlushTimer = undefined;
+				if (stagedImagePreview !== pending) return;
+				flushImagePreviewEntry(pi, pending);
+				stagedImagePreview = undefined;
+			}, 0);
+		}
+		// Fallback for runtimes that start the assistant before the deferred turn
+		// runs. This preserves the ordering below the user and never duplicates.
+		if (stagedImagePreview && event.message?.role === "assistant") {
+			if (previewFlushTimer) {
+				clearTimeout(previewFlushTimer);
+				previewFlushTimer = undefined;
+			}
+			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 };
+}