pi-paster 0.2.0 → 0.2.1

package/README.md

@@ -87,7 +87,7 @@ On macOS, pi exposes an image paste action through its keybinding system. In the
 
 ## Configuration
 
-By default all editor integrations are enabled.
+By default all editor integrations are enabled, and submitted image previews render in the raw chat-history style.
 
 To customize behavior, load a small wrapper extension:
 
@@ -95,6 +95,8 @@ To customize behavior, load a small wrapper extension:
 import { createPaster } from "pi-paster";
 
 export default createPaster({
+  submittedPreviewStyle: "raw",
+  includeImagePathsInPrompt: true,
   customEditor: {
     enabled: true,
     showImagePreview: true,
@@ -105,11 +107,13 @@ export default createPaster({
 
 ### Options
 
-| Option                                  | Default | Description                                                                                                                 |
-| --------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------- |
-| `customEditor.enabled`                  | `true`  | Replaces pi's input editor with paster's editor integration. Disable this to keep pi's default editor.                      |
-| `customEditor.showImagePreview`         | `true`  | Shows an image preview above the input when the cursor is inside an image placeholder. Requires `customEditor.enabled`.     |
-| `customEditor.deletePlaceholderAsBlock` | `true`  | Makes backspace/delete remove the whole placeholder when editing inside or adjacent to it. Requires `customEditor.enabled`. |
+| Option                                  | Default | Description                                                                                                                             |
+| --------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `submittedPreviewStyle`                 | `"raw"` | How submitted image previews render in chat history. Use `"collapsible"` to wrap them in pi's ctrl+o expandable/collapsible message UI. |
+| `includeImagePathsInPrompt`             | `true`  | Appends placeholder-to-local-path mappings to the submitted prompt so the agent can manipulate the source image files when asked.       |
+| `customEditor.enabled`                  | `true`  | Replaces pi's input editor with paster's editor integration. Disable this to keep pi's default editor.                                  |
+| `customEditor.showImagePreview`         | `true`  | Shows an image preview above the input when the cursor is inside an image placeholder. Requires `customEditor.enabled`.                 |
+| `customEditor.deletePlaceholderAsBlock` | `true`  | Makes backspace/delete remove the whole placeholder when editing inside or adjacent to it. Requires `customEditor.enabled`.             |
 
 When `customEditor.enabled` is `false`, paster still handles bracketed terminal paste/drop image paths, but cursor previews, atomic placeholder deletion, and paster's clipboard-image handler are disabled.
 

package/dist/index.d.mts

@@ -3,7 +3,12 @@ import { Component, EditorTheme, ImageDimensions, ImageTheme, TUI } from "@earen
 import { CustomEditor, ExtensionAPI, KeybindingsManager } from "@earendil-works/pi-coding-agent";
 
 //#region src/config.d.ts
+type SubmittedPreviewStyle = "raw" | "collapsible";
 interface PasterConfig {
+  /** How submitted attachment previews render in chat history. */
+  submittedPreviewStyle?: SubmittedPreviewStyle;
+  /** Append local image paths to the submitted prompt so the agent can manipulate the source files. */
+  includeImagePathsInPrompt?: boolean;
   customEditor?: {
     /** Replace pi's input editor to enable inline image UX features. */enabled?: boolean; /** Show an image preview above the input while the cursor is inside an image placeholder. */
     showImagePreview?: boolean; /** Treat image placeholders as atomic blocks for backspace/delete. */
@@ -11,6 +16,8 @@ interface PasterConfig {
   };
 }
 interface ResolvedPasterConfig {
+  submittedPreviewStyle: SubmittedPreviewStyle;
+  includeImagePathsInPrompt: boolean;
   customEditor: {
     enabled: boolean;
     showImagePreview: boolean;
@@ -109,6 +116,7 @@ declare class AttachmentStore {
 //#region src/editor.d.ts
 declare const PASTE_START = "\u001B[200~";
 declare const PASTE_END = "\u001B[201~";
+declare function segmentTextWithAtomicImages(text: string, store: AttachmentStore, validPasteIds?: Set<number>): Intl.SegmentData[];
 declare class PasterEditor extends CustomEditor {
   private readonly pasterKeybindings;
   private readonly pasterOptions;
@@ -125,9 +133,12 @@ declare class PasterEditor extends CustomEditor {
   insertTextAtCursor(text: string): void;
   handleInput(data: string): void;
   clearCursorPreview(): void;
+  private installAtomicImageSegmentation;
   private handlePasteClipboardImage;
   private handleBracketedPaste;
+  private handleAtomicPlaceholderNavigation;
   private handleAtomicPlaceholderDelete;
+  private setCursor;
   private deleteLineRange;
   private transform;
   private updateCursorPreview;
@@ -165,6 +176,7 @@ declare function replaceImagePathsInText(text: string, options: {
   accepted: ImageAttachment[];
 };
 declare function imagesForText(store: AttachmentStore, text: string, existing?: PasterImageContent[]): PasterImageContent[];
+declare function appendImagePathContext(text: string, attachments: ImageAttachment[]): string;
 /**
  * Async variant of imagesForText that runs each attachment through the
  * Anthropic-aware image optimizer (resize to 8000px cap, JPEG ladder to stay
@@ -180,13 +192,25 @@ declare function describeReject(result: Exclude<LoadImageResult, {
 }>, notify?: (message: string) => void): void;
 //#endregion
 //#region src/preview.d.ts
+type ImagePreviewMessageStyle = "raw" | "collapsible";
+interface ImagePreviewMessageTheme extends ImageTheme {
+  background?: (text: string) => string;
+  title?: (text: string) => string;
+  muted?: (text: string) => string;
+}
 declare class ImagePreviewMessage implements Component {
   private readonly attachments;
   private readonly theme;
+  private readonly options;
   private readonly images;
-  constructor(attachments: ImageAttachment[], theme: ImageTheme);
-  render(width: number): string[];
+  constructor(attachments: ImageAttachment[], theme: ImagePreviewMessageTheme, options?: {
+    expanded?: boolean;
+    style?: ImagePreviewMessageStyle;
+  });
   invalidate(): void;
+  render(width: number): string[];
+  private renderRaw;
+  private renderCollapsible;
 }
 interface CursorPreviewTheme {
   title: (text: string) => string;
@@ -222,4 +246,4 @@ declare function createImagePasteTerminalInputHandler(options: {
 declare function createPaster(config?: PasterConfig): (pi: ExtensionAPI) => void;
 declare function paster(pi: ExtensionAPI, config?: PasterConfig): void;
 //#endregion
-export { ANTHROPIC_MAX_DIMENSION, ANTHROPIC_MAX_IMAGE_BYTES, AttachmentStore, ClipboardImageResult, CursorImagePreviewWidget, DEFAULT_PASTER_CONFIG, EXTENSION_NAME, ImageAttachment, ImagePreviewMessage, LoadImageResult, LoadedImage, MAX_IMAGE_BYTES, OptimizeResult, PASTE_END, PASTE_START, PasterConfig, PasterEditor, PasterImageContent, PasterPreviewDetails, ResolvedPasterConfig, SupportedImageMimeType, TerminalInputResult, createImagePasteTerminalInputHandler, createPaster, paster as default, describeReject, detectImageMimeType, dimensionsForImage, imagesForText, imagesForTextOptimized, isWindowsDrivePath, isWindowsLikePath, isWindowsUncPath, isWsl, loadImageFromPath, optimizeImageBytes, readClipboardImage, replaceImagePathsInText, resolveImagePath, resolvePasterConfig, shellUnescape, tokenizePathLikeText, windowsToWslPath };
+export { ANTHROPIC_MAX_DIMENSION, ANTHROPIC_MAX_IMAGE_BYTES, AttachmentStore, ClipboardImageResult, CursorImagePreviewWidget, DEFAULT_PASTER_CONFIG, EXTENSION_NAME, ImageAttachment, ImagePreviewMessage, ImagePreviewMessageStyle, LoadImageResult, LoadedImage, MAX_IMAGE_BYTES, OptimizeResult, PASTE_END, PASTE_START, PasterConfig, PasterEditor, PasterImageContent, PasterPreviewDetails, ResolvedPasterConfig, SubmittedPreviewStyle, SupportedImageMimeType, TerminalInputResult, appendImagePathContext, createImagePasteTerminalInputHandler, createPaster, paster as default, describeReject, detectImageMimeType, dimensionsForImage, imagesForText, imagesForTextOptimized, isWindowsDrivePath, isWindowsLikePath, isWindowsUncPath, isWsl, loadImageFromPath, optimizeImageBytes, readClipboardImage, replaceImagePathsInText, resolveImagePath, resolvePasterConfig, segmentTextWithAtomicImages, shellUnescape, tokenizePathLikeText, windowsToWslPath };

package/dist/index.mjs

@@ -4,7 +4,7 @@ import { existsSync, readFileSync, statSync, unlinkSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { isAbsolute, join, resolve } from "node:path";
 import { platform } from "node:process";
-import { Image, getCellDimensions, getImageDimensions, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { Box, Container, Image, Spacer, Text, getCellDimensions, getImageDimensions, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import { CustomEditor } from "@earendil-works/pi-coding-agent";
 //#region src/types.ts
 const EXTENSION_NAME = "paster";
@@ -447,6 +447,10 @@ function imagesForText(store, text, existing = []) {
 		data: attachment.data
 	}))];
 }
+function appendImagePathContext(text, attachments) {
+	if (attachments.length === 0) return text;
+	return `${text}\n\nAttached image paths:\n${attachments.map((attachment) => `- ${attachment.placeholder}: ${attachment.originalPath}`).join("\n")}`;
+}
 /**
 * Async variant of imagesForText that runs each attachment through the
 * Anthropic-aware image optimizer (resize to 8000px cap, JPEG ladder to stay
@@ -644,23 +648,72 @@ function readMacOSClipboardImage(maxBytes) {
 }
 //#endregion
 //#region src/config.ts
-const DEFAULT_PASTER_CONFIG = { customEditor: {
-	enabled: true,
-	showImagePreview: true,
-	deletePlaceholderAsBlock: true
-} };
+const DEFAULT_PASTER_CONFIG = {
+	submittedPreviewStyle: "raw",
+	includeImagePathsInPrompt: true,
+	customEditor: {
+		enabled: true,
+		showImagePreview: true,
+		deletePlaceholderAsBlock: true
+	}
+};
 function resolvePasterConfig(config = {}) {
-	return { customEditor: {
-		enabled: config.customEditor?.enabled ?? DEFAULT_PASTER_CONFIG.customEditor.enabled,
-		showImagePreview: config.customEditor?.showImagePreview ?? DEFAULT_PASTER_CONFIG.customEditor.showImagePreview,
-		deletePlaceholderAsBlock: config.customEditor?.deletePlaceholderAsBlock ?? DEFAULT_PASTER_CONFIG.customEditor.deletePlaceholderAsBlock
-	} };
+	return {
+		submittedPreviewStyle: config.submittedPreviewStyle ?? DEFAULT_PASTER_CONFIG.submittedPreviewStyle,
+		includeImagePathsInPrompt: config.includeImagePathsInPrompt ?? DEFAULT_PASTER_CONFIG.includeImagePathsInPrompt,
+		customEditor: {
+			enabled: config.customEditor?.enabled ?? DEFAULT_PASTER_CONFIG.customEditor.enabled,
+			showImagePreview: config.customEditor?.showImagePreview ?? DEFAULT_PASTER_CONFIG.customEditor.showImagePreview,
+			deletePlaceholderAsBlock: config.customEditor?.deletePlaceholderAsBlock ?? DEFAULT_PASTER_CONFIG.customEditor.deletePlaceholderAsBlock
+		}
+	};
 }
 //#endregion
 //#region src/editor.ts
 const PASTE_START = "\x1B[200~";
 const PASTE_END = "\x1B[201~";
 const PLACEHOLDER_REGEX = /\[#image \d+\]/g;
+const PASTE_MARKER_REGEX = /\[paste #(\d+)( (\+\d+ lines|\d+ chars))?\]/g;
+const baseSegmenter = new Intl.Segmenter();
+function atomicSpansForText(text, validPasteIds) {
+	const spans = [];
+	for (const match of text.matchAll(PASTE_MARKER_REGEX)) {
+		const id = Number.parseInt(match[1], 10);
+		if (!validPasteIds.has(id)) continue;
+		spans.push({
+			start: match.index,
+			end: match.index + match[0].length
+		});
+	}
+	for (const match of text.matchAll(PLACEHOLDER_REGEX)) {
+		const placeholder = match[0];
+		spans.push({
+			start: match.index,
+			end: match.index + placeholder.length
+		});
+	}
+	return spans.sort((a, b) => a.start - b.start || a.end - b.end);
+}
+function segmentTextWithAtomicImages(text, store, validPasteIds = /* @__PURE__ */ new Set()) {
+	const spans = atomicSpansForText(text, validPasteIds);
+	if (spans.length === 0) return [...baseSegmenter.segment(text)];
+	const result = [];
+	let spanIndex = 0;
+	for (const segment of baseSegmenter.segment(text)) {
+		while (spanIndex < spans.length && spans[spanIndex].end <= segment.index) spanIndex++;
+		const span = spans[spanIndex];
+		if (span && segment.index >= span.start && segment.index < span.end) {
+			if (segment.index === span.start) result.push({
+				segment: text.slice(span.start, span.end),
+				index: span.start,
+				input: text
+			});
+			continue;
+		}
+		result.push(segment);
+	}
+	return result;
+}
 function findPlaceholderAtCursor(store, lines, cursor, mode) {
 	const line = lines[cursor.line] ?? "";
 	for (const match of line.matchAll(PLACEHOLDER_REGEX)) {
@@ -668,21 +721,24 @@ function findPlaceholderAtCursor(store, lines, cursor, mode) {
 		const start = match.index;
 		const end = start + placeholder.length;
 		const attachment = store.get(placeholder);
-		if (!attachment) continue;
+		if (!attachment && mode !== "hover") continue;
 		if (mode === "hover" && cursor.col >= start && cursor.col < end) return {
 			attachment,
+			placeholder,
 			line: cursor.line,
 			start,
 			end
 		};
 		if (mode === "backspace" && cursor.col > start && cursor.col <= end) return {
 			attachment,
+			placeholder,
 			line: cursor.line,
 			start,
 			end
 		};
 		if (mode === "delete" && cursor.col >= start && cursor.col < end) return {
 			attachment,
+			placeholder,
 			line: cursor.line,
 			start,
 			end
@@ -696,6 +752,7 @@ var PasterEditor = class extends CustomEditor {
 		super(tui, theme, pasterKeybindings);
 		this.pasterKeybindings = pasterKeybindings;
 		this.pasterOptions = pasterOptions;
+		this.installAtomicImageSegmentation();
 		this.onPasteImage = () => {
 			this.handlePasteClipboardImage();
 		};
@@ -707,6 +764,7 @@ var PasterEditor = class extends CustomEditor {
 	}
 	handleInput(data) {
 		if (this.handleBracketedPaste(data)) return;
+		if (this.handleAtomicPlaceholderNavigation(data)) return;
 		if (this.pasterOptions.deletePlaceholderAsBlock && this.handleAtomicPlaceholderDelete(data)) return;
 		super.handleInput(data);
 		this.updateCursorPreview();
@@ -715,6 +773,10 @@ var PasterEditor = class extends CustomEditor {
 		this.activePreviewPlaceholder = void 0;
 		this.pasterOptions.setCursorPreview(void 0);
 	}
+	installAtomicImageSegmentation() {
+		const editor = this;
+		editor.segment = (text) => segmentTextWithAtomicImages(text, this.pasterOptions.store, new Set(editor.pastes?.keys() ?? []));
+	}
 	async handlePasteClipboardImage() {
 		const attachment = await this.pasterOptions.pasteClipboardImage?.();
 		if (!attachment) return;
@@ -755,6 +817,20 @@ var PasterEditor = class extends CustomEditor {
 		this.updateCursorPreview();
 		return true;
 	}
+	handleAtomicPlaceholderNavigation(data) {
+		const isLeft = this.pasterKeybindings.matches(data, "tui.editor.cursorLeft");
+		const isRight = this.pasterKeybindings.matches(data, "tui.editor.cursorRight");
+		if (!isLeft && !isRight) return false;
+		const line = this.getLines()[this.getCursor().line] ?? "";
+		const cursor = this.getCursor();
+		const matches = [...line.matchAll(PLACEHOLDER_REGEX)];
+		const target = isRight ? matches.find((match) => cursor.col >= match.index && cursor.col < match.index + match[0].length) : matches.find((match) => cursor.col > match.index && cursor.col <= match.index + match[0].length);
+		if (!target) return false;
+		this.setCursor(target.index + (isRight ? target[0].length : 0));
+		this.updateCursorPreview();
+		this.tui.requestRender();
+		return true;
+	}
 	handleAtomicPlaceholderDelete(data) {
 		const isBackspace = this.pasterKeybindings.matches(data, "tui.editor.deleteCharBackward");
 		const isDelete = this.pasterKeybindings.matches(data, "tui.editor.deleteCharForward");
@@ -766,14 +842,18 @@ var PasterEditor = class extends CustomEditor {
 		this.updateCursorPreview();
 		return true;
 	}
+	setCursor(col) {
+		const editor = this;
+		if (editor.setCursorCol) editor.setCursorCol(col);
+		else editor.state.cursorCol = col;
+	}
 	deleteLineRange(lineIndex, start, end) {
 		const editor = this;
 		editor.pushUndoSnapshot?.();
 		const line = editor.state.lines[lineIndex] ?? "";
 		editor.state.lines[lineIndex] = line.slice(0, start) + line.slice(end);
 		editor.state.cursorLine = lineIndex;
-		if (editor.setCursorCol) editor.setCursorCol(start);
-		else editor.state.cursorCol = start;
+		this.setCursor(start);
 		editor.lastAction = null;
 		editor.historyIndex = -1;
 		this.onChange?.(this.getText());
@@ -788,7 +868,7 @@ var PasterEditor = class extends CustomEditor {
 	}
 	updateCursorPreview() {
 		const target = findPlaceholderAtCursor(this.pasterOptions.store, this.getLines(), this.getCursor(), "hover");
-		const nextPlaceholder = target?.attachment.placeholder;
+		const nextPlaceholder = target?.attachment?.placeholder;
 		if (nextPlaceholder === this.activePreviewPlaceholder) return;
 		this.activePreviewPlaceholder = nextPlaceholder;
 		this.pasterOptions.setCursorPreview(target?.attachment);
@@ -803,16 +883,23 @@ function formatAttachmentLine(attachment, width, style) {
 }
 var ImagePreviewMessage = class {
 	images;
-	constructor(attachments, theme) {
+	constructor(attachments, theme, options = {}) {
 		this.attachments = attachments;
 		this.theme = theme;
+		this.options = options;
 		this.images = attachments.map((attachment) => new Image(attachment.data, attachment.mimeType, theme, {
 			maxWidthCells: 60,
 			maxHeightCells: 16,
 			filename: attachment.placeholder
 		}));
 	}
+	invalidate() {
+		for (const image of this.images) image.invalidate();
+	}
 	render(width) {
+		return this.options.style === "collapsible" ? this.renderCollapsible(width) : this.renderRaw(width);
+	}
+	renderRaw(width) {
 		const lines = [];
 		const safeWidth = Math.max(1, width);
 		for (let index = 0; index < this.attachments.length; index++) {
@@ -822,8 +909,22 @@ var ImagePreviewMessage = class {
 		}
 		return lines;
 	}
-	invalidate() {
-		for (const image of this.images) image.invalidate();
+	renderCollapsible(width) {
+		const container = new Container();
+		container.addChild(new Spacer(1));
+		const box = new Box(1, 1, this.theme.background);
+		container.addChild(box);
+		const title = this.theme.title ?? this.theme.fallbackColor;
+		const muted = this.theme.muted ?? this.theme.fallbackColor;
+		const summary = this.attachments.length === 1 ? `Attached ${this.attachments[0].placeholder}` : `Attached ${this.attachments.length} images`;
+		const suffix = this.options.expanded ? " (ctrl+o to collapse)" : " (ctrl+o to expand)";
+		box.addChild(new Text(`${title(summary)}${muted(suffix)}`, 0, 0));
+		for (const attachment of this.attachments) box.addChild(new Text(formatAttachmentLine(attachment, width, muted), 0, 0));
+		const lines = container.render(width);
+		if (!this.options.expanded) return lines;
+		const safeWidth = Math.max(1, width);
+		for (let index = 0; index < this.attachments.length; index++) lines.push(...this.images[index].render(safeWidth));
+		return lines;
 	}
 };
 var CursorImagePreviewWidget = class {
@@ -937,11 +1038,19 @@ function paster(pi, config = {}) {
 	let pendingPreview = [];
 	let activeEditor;
 	let unsubscribeTerminalInput;
-	pi.registerMessageRenderer("paster-preview", (message, _options, theme) => {
+	pi.registerMessageRenderer("paster-preview", (message, options, theme) => {
 		const placeholders = message.details?.placeholders ?? [];
 		const attachments = store.list().filter((attachment) => placeholders.includes(attachment.placeholder));
 		if (attachments.length === 0) return void 0;
-		return new ImagePreviewMessage(attachments, { fallbackColor: (text) => theme.fg("muted", text) });
+		return new ImagePreviewMessage(attachments, {
+			fallbackColor: (text) => theme.fg("muted", text),
+			background: (text) => theme.bg("toolSuccessBg", text),
+			title: (text) => theme.fg("toolTitle", theme.bold(text)),
+			muted: (text) => theme.fg("muted", text)
+		}, {
+			expanded: options.expanded,
+			style: resolvedConfig.submittedPreviewStyle
+		});
 	});
 	pi.on("session_start", (_event, ctx) => {
 		store.clear();
@@ -1017,7 +1126,7 @@ function paster(pi, config = {}) {
 		const images = await imagesForTextOptimized(store, event.text, event.images);
 		return {
 			action: "transform",
-			text: event.text,
+			text: resolvedConfig.includeImagePathsInPrompt ? appendImagePathContext(event.text, attachments) : event.text,
 			images
 		};
 	});
@@ -1029,4 +1138,4 @@ function paster(pi, config = {}) {
 	});
 }
 //#endregion
-export { ANTHROPIC_MAX_DIMENSION, ANTHROPIC_MAX_IMAGE_BYTES, AttachmentStore, CursorImagePreviewWidget, DEFAULT_PASTER_CONFIG, EXTENSION_NAME, ImagePreviewMessage, MAX_IMAGE_BYTES, PASTE_END, PASTE_START, PasterEditor, createImagePasteTerminalInputHandler, createPaster, paster as default, describeReject, detectImageMimeType, dimensionsForImage, imagesForText, imagesForTextOptimized, isWindowsDrivePath, isWindowsLikePath, isWindowsUncPath, isWsl, loadImageFromPath, optimizeImageBytes, readClipboardImage, replaceImagePathsInText, resolveImagePath, resolvePasterConfig, shellUnescape, tokenizePathLikeText, windowsToWslPath };
+export { ANTHROPIC_MAX_DIMENSION, ANTHROPIC_MAX_IMAGE_BYTES, AttachmentStore, CursorImagePreviewWidget, DEFAULT_PASTER_CONFIG, EXTENSION_NAME, ImagePreviewMessage, MAX_IMAGE_BYTES, PASTE_END, PASTE_START, PasterEditor, appendImagePathContext, createImagePasteTerminalInputHandler, createPaster, paster as default, describeReject, detectImageMimeType, dimensionsForImage, imagesForText, imagesForTextOptimized, isWindowsDrivePath, isWindowsLikePath, isWindowsUncPath, isWsl, loadImageFromPath, optimizeImageBytes, readClipboardImage, replaceImagePathsInText, resolveImagePath, resolvePasterConfig, segmentTextWithAtomicImages, shellUnescape, tokenizePathLikeText, windowsToWslPath };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-paster",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Pi extension that turns pasted image paths into first-class image attachments.",
   "keywords": [
     "image-attachments",
@@ -58,6 +58,6 @@
     "extensions": [
       "./src/index.ts"
     ],
-    "image": "https://unpkg.com/pi-paster@0.2.0/docs/preview.png"
+    "image": "https://unpkg.com/pi-paster@0.2.1/docs/preview.png"
   }
 }

package/src/config.ts

@@ -1,4 +1,10 @@
+export type SubmittedPreviewStyle = "raw" | "collapsible";
+
 export interface PasterConfig {
+  /** How submitted attachment previews render in chat history. */
+  submittedPreviewStyle?: SubmittedPreviewStyle;
+  /** Append local image paths to the submitted prompt so the agent can manipulate the source files. */
+  includeImagePathsInPrompt?: boolean;
   customEditor?: {
     /** Replace pi's input editor to enable inline image UX features. */
     enabled?: boolean;
@@ -10,6 +16,8 @@ export interface PasterConfig {
 }
 
 export interface ResolvedPasterConfig {
+  submittedPreviewStyle: SubmittedPreviewStyle;
+  includeImagePathsInPrompt: boolean;
   customEditor: {
     enabled: boolean;
     showImagePreview: boolean;
@@ -18,6 +26,8 @@ export interface ResolvedPasterConfig {
 }
 
 export const DEFAULT_PASTER_CONFIG: ResolvedPasterConfig = {
+  submittedPreviewStyle: "raw",
+  includeImagePathsInPrompt: true,
   customEditor: {
     enabled: true,
     showImagePreview: true,
@@ -27,6 +37,10 @@ export const DEFAULT_PASTER_CONFIG: ResolvedPasterConfig = {
 
 export function resolvePasterConfig(config: PasterConfig = {}): ResolvedPasterConfig {
   return {
+    submittedPreviewStyle:
+      config.submittedPreviewStyle ?? DEFAULT_PASTER_CONFIG.submittedPreviewStyle,
+    includeImagePathsInPrompt:
+      config.includeImagePathsInPrompt ?? DEFAULT_PASTER_CONFIG.includeImagePathsInPrompt,
     customEditor: {
       enabled: config.customEditor?.enabled ?? DEFAULT_PASTER_CONFIG.customEditor.enabled,
       showImagePreview:

package/src/editor.ts

@@ -7,6 +7,59 @@ import type { ImageAttachment } from "./types.ts";
 export const PASTE_START = "\x1b[200~";
 export const PASTE_END = "\x1b[201~";
 const PLACEHOLDER_REGEX = /\[#image \d+\]/g;
+const PASTE_MARKER_REGEX = /\[paste #(\d+)( (\+\d+ lines|\d+ chars))?\]/g;
+const baseSegmenter = new Intl.Segmenter();
+
+interface AtomicSpan {
+  start: number;
+  end: number;
+}
+
+interface EditorSegmentationAccess {
+  segment?: (text: string) => Iterable<Intl.SegmentData>;
+  pastes?: Map<number, string>;
+}
+
+function atomicSpansForText(text: string, validPasteIds: Set<number>): AtomicSpan[] {
+  const spans: AtomicSpan[] = [];
+
+  for (const match of text.matchAll(PASTE_MARKER_REGEX)) {
+    const id = Number.parseInt(match[1]!, 10);
+    if (!validPasteIds.has(id)) continue;
+    spans.push({ start: match.index, end: match.index + match[0].length });
+  }
+
+  for (const match of text.matchAll(PLACEHOLDER_REGEX)) {
+    const placeholder = match[0];
+    spans.push({ start: match.index, end: match.index + placeholder.length });
+  }
+
+  return spans.sort((a, b) => a.start - b.start || a.end - b.end);
+}
+
+export function segmentTextWithAtomicImages(
+  text: string,
+  store: AttachmentStore,
+  validPasteIds: Set<number> = new Set(),
+): Intl.SegmentData[] {
+  const spans = atomicSpansForText(text, validPasteIds);
+  if (spans.length === 0) return [...baseSegmenter.segment(text)];
+
+  const result: Intl.SegmentData[] = [];
+  let spanIndex = 0;
+  for (const segment of baseSegmenter.segment(text)) {
+    while (spanIndex < spans.length && spans[spanIndex]!.end <= segment.index) spanIndex++;
+    const span = spans[spanIndex];
+    if (span && segment.index >= span.start && segment.index < span.end) {
+      if (segment.index === span.start) {
+        result.push({ segment: text.slice(span.start, span.end), index: span.start, input: text });
+      }
+      continue;
+    }
+    result.push(segment);
+  }
+  return result;
+}
 
 interface EditorCursor {
   line: number;
@@ -14,7 +67,8 @@ interface EditorCursor {
 }
 
 interface PlaceholderAtCursor {
-  attachment: ImageAttachment;
+  attachment?: ImageAttachment;
+  placeholder: string;
   line: number;
   start: number;
   end: number;
@@ -32,16 +86,16 @@ function findPlaceholderAtCursor(
     const start = match.index;
     const end = start + placeholder.length;
     const attachment = store.get(placeholder);
-    if (!attachment) continue;
+    if (!attachment && mode !== "hover") continue;
 
     if (mode === "hover" && cursor.col >= start && cursor.col < end) {
-      return { attachment, line: cursor.line, start, end };
+      return { attachment, placeholder, line: cursor.line, start, end };
     }
     if (mode === "backspace" && cursor.col > start && cursor.col <= end) {
-      return { attachment, line: cursor.line, start, end };
+      return { attachment, placeholder, line: cursor.line, start, end };
     }
     if (mode === "delete" && cursor.col >= start && cursor.col < end) {
-      return { attachment, line: cursor.line, start, end };
+      return { attachment, placeholder, line: cursor.line, start, end };
     }
   }
   return undefined;
@@ -76,6 +130,7 @@ export class PasterEditor extends CustomEditor {
     },
   ) {
     super(tui, theme, pasterKeybindings);
+    this.installAtomicImageSegmentation();
     this.onPasteImage = () => {
       void this.handlePasteClipboardImage();
     };
@@ -89,6 +144,7 @@ export class PasterEditor extends CustomEditor {
 
   override handleInput(data: string): void {
     if (this.handleBracketedPaste(data)) return;
+    if (this.handleAtomicPlaceholderNavigation(data)) return;
     if (this.pasterOptions.deletePlaceholderAsBlock && this.handleAtomicPlaceholderDelete(data))
       return;
 
@@ -101,6 +157,16 @@ export class PasterEditor extends CustomEditor {
     this.pasterOptions.setCursorPreview(undefined);
   }
 
+  private installAtomicImageSegmentation(): void {
+    const editor = this as unknown as EditorSegmentationAccess;
+    editor.segment = (text: string) =>
+      segmentTextWithAtomicImages(
+        text,
+        this.pasterOptions.store,
+        new Set(editor.pastes?.keys() ?? []),
+      );
+  }
+
   private async handlePasteClipboardImage(): Promise<void> {
     const attachment = await this.pasterOptions.pasteClipboardImage?.();
     if (!attachment) return;
@@ -149,6 +215,29 @@ export class PasterEditor extends CustomEditor {
     return true;
   }
 
+  private handleAtomicPlaceholderNavigation(data: string): boolean {
+    const isLeft = this.pasterKeybindings.matches(data, "tui.editor.cursorLeft");
+    const isRight = this.pasterKeybindings.matches(data, "tui.editor.cursorRight");
+    if (!isLeft && !isRight) return false;
+
+    const line = this.getLines()[this.getCursor().line] ?? "";
+    const cursor = this.getCursor();
+    const matches = [...line.matchAll(PLACEHOLDER_REGEX)];
+    const target = isRight
+      ? matches.find(
+          (match) => cursor.col >= match.index && cursor.col < match.index + match[0].length,
+        )
+      : matches.find(
+          (match) => cursor.col > match.index && cursor.col <= match.index + match[0].length,
+        );
+    if (!target) return false;
+
+    this.setCursor(target.index + (isRight ? target[0].length : 0));
+    this.updateCursorPreview();
+    this.tui.requestRender();
+    return true;
+  }
+
   private handleAtomicPlaceholderDelete(data: string): boolean {
     const isBackspace = this.pasterKeybindings.matches(data, "tui.editor.deleteCharBackward");
     const isDelete = this.pasterKeybindings.matches(data, "tui.editor.deleteCharForward");
@@ -168,17 +257,22 @@ export class PasterEditor extends CustomEditor {
     return true;
   }
 
+  private setCursor(col: number): void {
+    const editor = this as unknown as EditorStateAccess;
+    if (editor.setCursorCol) {
+      editor.setCursorCol(col);
+    } else {
+      editor.state.cursorCol = col;
+    }
+  }
+
   private deleteLineRange(lineIndex: number, start: number, end: number): void {
     const editor = this as unknown as EditorStateAccess;
     editor.pushUndoSnapshot?.();
     const line = editor.state.lines[lineIndex] ?? "";
     editor.state.lines[lineIndex] = line.slice(0, start) + line.slice(end);
     editor.state.cursorLine = lineIndex;
-    if (editor.setCursorCol) {
-      editor.setCursorCol(start);
-    } else {
-      editor.state.cursorCol = start;
-    }
+    this.setCursor(start);
     editor.lastAction = null;
     editor.historyIndex = -1;
     this.onChange?.(this.getText());
@@ -200,7 +294,7 @@ export class PasterEditor extends CustomEditor {
       this.getCursor(),
       "hover",
     );
-    const nextPlaceholder = target?.attachment.placeholder;
+    const nextPlaceholder = target?.attachment?.placeholder;
     if (nextPlaceholder === this.activePreviewPlaceholder) return;
     this.activePreviewPlaceholder = nextPlaceholder;
     this.pasterOptions.setCursorPreview(target?.attachment);

package/src/image-utils.ts

@@ -357,6 +357,14 @@ export function imagesForText(
   ];
 }
 
+export function appendImagePathContext(text: string, attachments: ImageAttachment[]): string {
+  if (attachments.length === 0) return text;
+  const lines = attachments.map(
+    (attachment) => `- ${attachment.placeholder}: ${attachment.originalPath}`,
+  );
+  return `${text}\n\nAttached image paths:\n${lines.join("\n")}`;
+}
+
 /**
  * Async variant of imagesForText that runs each attachment through the
  * Anthropic-aware image optimizer (resize to 8000px cap, JPEG ladder to stay

package/src/index.ts

@@ -2,7 +2,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { readClipboardImage } from "./clipboard.ts";
 import { type PasterConfig, resolvePasterConfig } from "./config.ts";
 import { PasterEditor } from "./editor.ts";
-import { imagesForTextOptimized } from "./image-utils.ts";
+import { appendImagePathContext, imagesForTextOptimized } from "./image-utils.ts";
 import { CursorImagePreviewWidget, ImagePreviewMessage } from "./preview.ts";
 import { AttachmentStore } from "./store.ts";
 import { createImagePasteTerminalInputHandler } from "./terminal-input.ts";
@@ -29,15 +29,22 @@ export default function paster(pi: ExtensionAPI, config: PasterConfig = {}): voi
   let activeEditor: PasterEditor | undefined;
   let unsubscribeTerminalInput: (() => void) | undefined;
 
-  pi.registerMessageRenderer<PasterPreviewDetails>("paster-preview", (message, _options, theme) => {
+  pi.registerMessageRenderer<PasterPreviewDetails>("paster-preview", (message, options, theme) => {
     const placeholders = message.details?.placeholders ?? [];
     const attachments = store
       .list()
       .filter((attachment) => placeholders.includes(attachment.placeholder));
     if (attachments.length === 0) return undefined;
-    return new ImagePreviewMessage(attachments, {
-      fallbackColor: (text) => theme.fg("muted", text),
-    });
+    return new ImagePreviewMessage(
+      attachments,
+      {
+        fallbackColor: (text) => theme.fg("muted", text),
+        background: (text) => theme.bg("toolSuccessBg", text),
+        title: (text) => theme.fg("toolTitle", theme.bold(text)),
+        muted: (text) => theme.fg("muted", text),
+      },
+      { expanded: options.expanded, style: resolvedConfig.submittedPreviewStyle },
+    );
   });
 
   pi.on("session_start", (_event, ctx) => {
@@ -142,10 +149,13 @@ export default function paster(pi: ExtensionAPI, config: PasterConfig = {}): voi
     // 32 MB/request caps. Per-attachment caching means each image is only
     // resized/recompressed once across the whole session.
     const images = await imagesForTextOptimized(store, event.text, event.images);
+    const text = resolvedConfig.includeImagePathsInPrompt
+      ? appendImagePathContext(event.text, attachments)
+      : event.text;
 
     return {
       action: "transform" as const,
-      text: event.text,
+      text,
       images,
     };
   });

package/src/preview.ts

@@ -1,8 +1,12 @@
 import {
+  Box,
+  Container,
   getCellDimensions,
   Image,
   type Component,
   type ImageTheme,
+  Spacer,
+  Text,
   truncateToWidth,
   visibleWidth,
 } from "@earendil-works/pi-tui";
@@ -18,12 +22,21 @@ function formatAttachmentLine(
   return visibleWidth(line) > maxWidth ? truncateToWidth(line, maxWidth, "") : line;
 }
 
+export type ImagePreviewMessageStyle = "raw" | "collapsible";
+
+interface ImagePreviewMessageTheme extends ImageTheme {
+  background?: (text: string) => string;
+  title?: (text: string) => string;
+  muted?: (text: string) => string;
+}
+
 export class ImagePreviewMessage implements Component {
   private readonly images: Image[];
 
   constructor(
     private readonly attachments: ImageAttachment[],
-    private readonly theme: ImageTheme,
+    private readonly theme: ImagePreviewMessageTheme,
+    private readonly options: { expanded?: boolean; style?: ImagePreviewMessageStyle } = {},
   ) {
     this.images = attachments.map(
       (attachment) =>
@@ -35,7 +48,17 @@ export class ImagePreviewMessage implements Component {
     );
   }
 
+  invalidate(): void {
+    for (const image of this.images) image.invalidate();
+  }
+
   render(width: number): string[] {
+    return this.options.style === "collapsible"
+      ? this.renderCollapsible(width)
+      : this.renderRaw(width);
+  }
+
+  private renderRaw(width: number): string[] {
     const lines: string[] = [];
     const safeWidth = Math.max(1, width);
     for (let index = 0; index < this.attachments.length; index++) {
@@ -46,8 +69,33 @@ export class ImagePreviewMessage implements Component {
     return lines;
   }
 
-  invalidate(): void {
-    for (const image of this.images) image.invalidate();
+  private renderCollapsible(width: number): string[] {
+    const container = new Container();
+    container.addChild(new Spacer(1));
+    const box = new Box(1, 1, this.theme.background);
+    container.addChild(box);
+
+    const title = this.theme.title ?? this.theme.fallbackColor;
+    const muted = this.theme.muted ?? this.theme.fallbackColor;
+    const summary =
+      this.attachments.length === 1
+        ? `Attached ${this.attachments[0]!.placeholder}`
+        : `Attached ${this.attachments.length} images`;
+    const suffix = this.options.expanded ? " (ctrl+o to collapse)" : " (ctrl+o to expand)";
+    box.addChild(new Text(`${title(summary)}${muted(suffix)}`, 0, 0));
+
+    for (const attachment of this.attachments) {
+      box.addChild(new Text(formatAttachmentLine(attachment, width, muted), 0, 0));
+    }
+
+    const lines = container.render(width);
+    if (!this.options.expanded) return lines;
+
+    const safeWidth = Math.max(1, width);
+    for (let index = 0; index < this.attachments.length; index++) {
+      lines.push(...this.images[index]!.render(safeWidth));
+    }
+    return lines;
   }
 }