@quandev104/pi-style 0.2.2 → 0.2.3

package/extension-src/pi-style/app/command-service.ts

@@ -49,6 +49,9 @@ const allowedPaths = new Set([
 	"messages.specialBlocks",
 	"messages.hideThinkingLabel",
 	"messages.hideInterimText",
+	"messages.showImagePreviews",
+	"messages.clipboardImages",
+	"messages.previewMaxWidth",
 	"tools.enabled",
 	"tools.style",
 	"tools.maxCollapsedLines",
@@ -82,6 +85,9 @@ function validatePathValue(path: string, value: unknown): boolean {
 			"messages.specialBlocks",
 			"messages.hideThinkingLabel",
 			"messages.hideInterimText",
+			"messages.showImagePreviews",
+			"messages.clipboardImages",
+			"messages.previewMaxWidth",
 			"tools.enabled",
 			"tools.showElapsed",
 			"tools.dimOutput",
@@ -105,6 +111,8 @@ function validatePathValue(path: string, value: unknown): boolean {
 		return typeof value === "string";
 	if (path === "tools.maxCollapsedLines" || path === "tools.maxExpandedLines")
 		return typeof value === "number" && Number.isFinite(value) && value >= 0;
+	if (path === "messages.previewMaxWidth")
+		return typeof value === "number" && Number.isFinite(value) && value >= 8 && value <= 60;
 	if (path === "statusLine.bottomMargin" || path === "statusLine.contextBarWidth")
 		return typeof value === "number" && Number.isFinite(value) && value >= 0;
 	if (path.endsWith(".colors") || path.endsWith(".glyphs"))

package/extension-src/pi-style/app/runtime.ts

@@ -5,6 +5,7 @@ import type { GitCommandRunner } from "../domain/providers.js";
 import type { ContextSnapshot, StatusSnapshot } from "../domain/status.js";
 import { normalizeThinkingLevel } from "../domain/status.js";
 import { installEditor } from "../features/editor/index.js";
+import { createClipboardImagePasteSurface } from "../features/messages/image-input.js";
 import {
 	installStartup,
 	type StartupHost,
@@ -198,6 +199,9 @@ export function createPiStyleRuntime(
 				generation,
 				initialSnapshot: currentSnapshot,
 				isCurrent: () => !disposed,
+				// Clipboard image paste surface (ADR 0009): instant `[Image #N] `
+				// markers at keystroke time, artifact fallback, atomic backspace.
+				clipboardImagePaste: createClipboardImagePasteSurface(),
 			});
 			if (editor) {
 				disposables.add(editor);

package/extension-src/pi-style/domain/config-normalization.ts

@@ -16,7 +16,7 @@ export const DEFAULT_CONFIG: NormalizedPiStyleConfig = Object.freeze({
 	startup: Object.freeze({ mode: "compact", showResources: false, alwaysExpanded: false }),
 	statusLine: Object.freeze({
 		enabled: true,
-		separator: "powerline-thin",
+		separator: "|",
 		layout: Object.freeze({
 			left: ["path", "git", "context_bar", "cost"],
 			right: ["model_effort"],
@@ -34,6 +34,9 @@ export const DEFAULT_CONFIG: NormalizedPiStyleConfig = Object.freeze({
 		specialBlocks: true,
 		hideThinkingLabel: true,
 		hideInterimText: true,
+		showImagePreviews: true,
+		clipboardImages: true,
+		previewMaxWidth: 30,
 	}),
 	tools: Object.freeze({
 		enabled: true,
@@ -178,6 +181,9 @@ export function normalizeConfig(
 			specialBlocks: bool(messages.specialBlocks, defaults.messages.specialBlocks),
 			hideThinkingLabel: bool(messages.hideThinkingLabel, defaults.messages.hideThinkingLabel),
 			hideInterimText: bool(messages.hideInterimText, defaults.messages.hideInterimText),
+			showImagePreviews: bool(messages.showImagePreviews, defaults.messages.showImagePreviews),
+			clipboardImages: bool(messages.clipboardImages, defaults.messages.clipboardImages),
+			previewMaxWidth: boundedInt(messages.previewMaxWidth, defaults.messages.previewMaxWidth, 8, 60),
 		}),
 		tools: Object.freeze({
 			enabled: bool(tools.enabled, defaults.tools.enabled),
@@ -239,6 +245,8 @@ const BOOL_PATHS = new Set([
 	"messages.specialBlocks",
 	"messages.hideThinkingLabel",
 	"messages.hideInterimText",
+	"messages.showImagePreviews",
+	"messages.clipboardImages",
 	"tools.enabled",
 	"tools.showElapsed",
 	"tools.dimOutput",
@@ -289,6 +297,8 @@ function validLeaf(path: string, value: unknown): boolean {
 		return typeof value === "string";
 	if (path === "tools.maxCollapsedLines" || path === "tools.maxExpandedLines")
 		return typeof value === "number" && Number.isFinite(value) && value >= 0;
+	if (path === "messages.previewMaxWidth")
+		return typeof value === "number" && Number.isFinite(value) && value >= 8 && value <= 60;
 	if (path === "statusLine.bottomMargin" || path === "statusLine.contextBarWidth")
 		return typeof value === "number" && Number.isFinite(value) && value >= 0;
 	if (STRING_ARRAY_PATHS.has(path)) return Array.isArray(value) && value.every((item) => typeof item === "string");

package/extension-src/pi-style/domain/config-types.ts

@@ -38,6 +38,12 @@ export interface PiStyleConfig {
 		specialBlocks?: boolean;
 		hideThinkingLabel?: boolean;
 		hideInterimText?: boolean;
+		/** Inline previews for user-prompt images (ADR 0008); gates append and render. */
+		showImagePreviews?: boolean;
+		/** Clipboard image input (ADR 0009): upgrade built-in paste temp paths to attachments. */
+		clipboardImages?: boolean;
+		/** Max cell width per user-prompt image preview (ADR 0008); default 30. */
+		previewMaxWidth?: number;
 	};
 	tools?: {
 		enabled?: boolean;
@@ -97,6 +103,12 @@ export interface NormalizedPiStyleConfig {
 		specialBlocks: boolean;
 		hideThinkingLabel: boolean;
 		hideInterimText: boolean;
+		/** Inline previews for user-prompt images (ADR 0008); gates append and render. */
+		showImagePreviews: boolean;
+		/** Clipboard image input (ADR 0009): upgrade built-in paste temp paths to attachments. */
+		clipboardImages: boolean;
+		/** Max cell width per user-prompt image preview (ADR 0008); default 30. */
+		previewMaxWidth: number;
 	};
 	readonly tools: {
 		enabled: boolean;

package/extension-src/pi-style/domain/status-renderer.ts

@@ -56,7 +56,7 @@ export function renderStatus(
 	options: StatusRendererOptions,
 ): StatusRenderResult {
 	if (width <= 0) return { primary: "", lines: [], visibleSegments: [] };
-	const separator = options.separator ?? "│";
+	const separator = options.separator ?? "|";
 	const padding = options.padding ?? " ";
 	const normalized = uniqueLayout(layout);
 	const context: SegmentContext = { snapshot, theme: options.theme, options: options.options ?? {}, width };

package/extension-src/pi-style/domain/status.ts

@@ -252,12 +252,21 @@ export function createBuiltinSegments(): ReadonlyMap<StatusSegmentId, StatusSegm
 			const percent = contextPercent(snapshot.context ?? {});
 			if (percent === undefined) return { visible: false, content: "" };
 			const token = contextBarToken(percent);
-			const window = snapshot.context?.windowTokens;
-			const label = `ctx${window !== undefined ? ` (${formatTokens(window)})` : ""}:`;
 			const width = (options.context_bar?.width as number | undefined) ?? CONTEXT_BAR_WIDTH;
+			// Pipe-delimited context block: `[█████░░░░░] | 47% used | 235K/1.0M`.
+			// Uses plain `|` (not the tall `│`) so the inline block stays visually short.
+			// No boundary pipes: the status renderer's segment separator already
+			// delimits the block, and extra pipes would double it up.
+			const pipe = theme.apply("separator", "|");
+			const bar = `${theme.apply("muted", "[")}${theme.apply(token, contextBar(percent, width))}${theme.apply("muted", "]")}`;
+			const parts = [bar, `${theme.apply(token, `${Math.round(percent)}%`)}${theme.apply("muted", " used")}`];
+			const current = snapshot.context?.currentTokens;
+			const window = snapshot.context?.windowTokens;
+			if (current !== undefined && window !== undefined)
+				parts.push(theme.apply("muted", `${formatTokens(current)}/${formatTokens(window)}`));
 			return {
 				visible: true,
-				content: `${theme.apply("muted", label)} ${theme.apply(token, contextBar(percent, width))} ${theme.apply(token, `${Math.round(percent)}%`)}`,
+				content: parts.join(` ${pipe} `),
 				compactContent: theme.apply(token, `${Math.round(percent)}%`),
 			};
 		}),
@@ -362,10 +371,7 @@ function contextBarToken(percent: number): SemanticToken {
 }
 
 function formatTokens(value: number): string {
-	if (value >= 1_000_000) {
-		const millions = value / 1_000_000;
-		return `${Number.isInteger(millions) ? millions : millions.toFixed(1)}M`;
-	}
+	if (value >= 1_000_000) return `${(value / 1_000_000).toFixed(1)}M`;
 	if (value >= 1_000) {
 		const thousands = value / 1_000;
 		return `${Number.isInteger(thousands) ? thousands : thousands.toFixed(1)}K`;

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

@@ -6,6 +6,7 @@ import { contextPercent, type StatusSnapshot, type ThinkingLevel } from "../../d
 import type { ResolvedTheme } from "../../domain/theme.js";
 import { resolveTheme } from "../../domain/theme.js";
 import { stripAnsi, truncateAnsi } from "../../shared/ansi.js";
+import { clipboardMarkerAtEnd, isSingleClipboardImagePath } from "../../shared/clipboard-path.js";
 
 export const EDITOR_DIAGNOSTIC_KEY = "pi-style.editor";
 type SetEditorComponent = NonNullable<ExtensionUIContext["setEditorComponent"]>;
@@ -30,6 +31,18 @@ export interface EditorInstallation {
 	dispose(): void;
 }
 
+/** Structural clipboard-image paste surface (ADR 0009) consumed by the
+ *  editor. Structural so this feature needs no cross-feature import; the
+ *  app layer passes the instance built in features/messages. */
+interface ClipboardImagePasteSurface {
+	enabled(): boolean;
+	clipboardHasImage(): boolean | null;
+	markerFromClipboard(): string;
+	markerFromArtifact(path: string): Promise<string>;
+	isMarkerIndexRegistered(index: number): boolean;
+	discardMarkerIndex(index: number): void;
+}
+
 interface EditorOptions {
 	config: NormalizedPiStyleConfig;
 	snapshot: StatusSnapshot;
@@ -37,6 +50,22 @@ interface EditorOptions {
 	/** Full Pi theme for thinking-level border colors (optional; falls back to borderColor). */
 	fullTheme?: { getThinkingBorderColor?: (level: ThinkingLevel) => (str: string) => string };
 	onSnapshot: (snapshot: StatusSnapshot) => void;
+	/** Clipboard image paste surface (ADR 0009): instant `[Image #N] ` markers
+	 *  at keystroke time, artifact-path fallback, atomic marker backspace.
+	 *  Undefined keeps native behavior entirely. */
+	clipboardImagePaste?: ClipboardImagePasteSurface;
+}
+
+/** Pi-tui Editor internals mirrored for O(1) atomic marker surgery. All are
+ *  runtime-present on the Editor prototype chain but TS-private; the typed
+ *  cast follows the autocompleteState-access pattern used in render(). */
+interface EditorInternals {
+	readonly state: { lines: string[]; cursorLine: number; cursorCol: number };
+	lastAction: string | null;
+	readonly onChange?: (text: string) => void;
+	exitHistoryBrowsing(): void;
+	setCursorCol(col: number): void;
+	cancelAutocomplete(): void;
 }
 
 interface RenderPlan {
@@ -150,6 +179,10 @@ export class StyledEditor extends CustomEditor implements EditorComponent {
 	private semanticDirty = false;
 	private disposed = false;
 	private renderPlanCache: { key: string; plan: RenderPlan } | undefined;
+	private readonly clipboardImagePaste: ClipboardImagePasteSurface | undefined;
+	/** Keybinding matcher (the factory's KeybindingsManager) for keystroke-level
+	 *  interception: the paste keybinding and backspace checks below. */
+	private readonly editorKeybindings: { matches(data: string, keybinding: string): boolean };
 
 	constructor(tui: Tui, theme: PiEditorTheme, keybindings: Keybindings, options: EditorOptions) {
 		super(tui, theme, keybindings);
@@ -158,6 +191,8 @@ export class StyledEditor extends CustomEditor implements EditorComponent {
 		this.piTheme = theme;
 		this.fullTheme = options.fullTheme;
 		this.onSnapshot = options.onSnapshot;
+		this.clipboardImagePaste = options.clipboardImagePaste;
+		this.editorKeybindings = keybindings as unknown as { matches(data: string, keybinding: string): boolean };
 		this.semantic = semanticTheme(theme, options.config);
 		this.setPaddingX(0);
 	}
@@ -177,10 +212,100 @@ export class StyledEditor extends CustomEditor implements EditorComponent {
 
 	override handleInput(data: string): void {
 		if (this.disposed) return;
+		if (this.handleClipboardImagePasteKeystroke(data)) return;
+		if (this.handleAtomicMarkerBackspace(data)) return;
 		super.handleInput(data);
 		this.onSnapshot({ ...this.snapshot });
 	}
 
+	/**
+	 * Instant marker (ADR 0009): when the built-in paste keybinding fires, the
+	 * clipboard holds an image (sync native probe), and the surface is enabled,
+	 * the keystroke is owned here — an `[Image #N] ` marker is inserted
+	 * immediately (zero-latency feedback) and the bytes fill the registry
+	 * entry asynchronously. Pi's own paste handler never runs for this
+	 * keystroke, so no temp artifact is written. Text pastes (no image) and
+	 * probe-unavailable hosts fall through to the native path untouched.
+	 */
+	private handleClipboardImagePasteKeystroke(data: string): boolean {
+		const surface = this.clipboardImagePaste;
+		if (!surface?.enabled()) return false;
+		if (!this.editorKeybindings.matches(data, "app.clipboard.pasteImage")) return false;
+		if (surface.clipboardHasImage() !== true) return false;
+		super.insertTextAtCursor(surface.markerFromClipboard());
+		this.onSnapshot({ ...this.snapshot });
+		return true;
+	}
+
+	/**
+	 * Atomic marker backspace (ADR 0009): backspacing directly after a
+	 * registered `[Image #N] ` marker deletes the whole marker as one unit —
+	 * the image is discarded (image-paste semantics). Direct state surgery
+	 * (O(1)) mirroring pi-tui's handleBackspace mutation protocol: no setText
+	 * round-trip (it clears the pastes registry, and undo snapshots store that
+	 * Map by reference — silently breaking `[paste #N]` atomicity on undo) and
+	 * no per-column left-arrow inputs (O(K·L) through the keybinding chain and
+	 * visual line maps). No undo snapshot is pushed: the discarded image
+	 * cannot be restored, so the deletion is intentionally non-undoable.
+	 */
+	private handleAtomicMarkerBackspace(data: string): boolean {
+		const surface = this.clipboardImagePaste;
+		if (!surface?.enabled()) return false;
+		const isBackspace = this.editorKeybindings.matches(data, "tui.editor.deleteCharBackward") || data === "\x7f";
+		if (!isBackspace) return false;
+		const lines = this.getLines();
+		const cursor = this.getCursor();
+		const current = lines[cursor.line];
+		if (current === undefined) return false;
+		const before = current.slice(0, cursor.col);
+		const hit = clipboardMarkerAtEnd(before);
+		if (!hit || !surface.isMarkerIndexRegistered(hit.index)) return false;
+		const editor = this as unknown as EditorInternals;
+		const targetCol = cursor.col - hit.length;
+		editor.exitHistoryBrowsing();
+		editor.lastAction = null;
+		editor.cancelAutocomplete();
+		// Splice the marker out of its line in place (deletion never removes a
+		// line, so cursorLine is unchanged). setCursorCol also clears
+		// preferredVisualCol/snappedFromCursorCol. scrollOffset is left alone;
+		// render() re-clamps it to keep the cursor visible.
+		editor.state.lines[cursor.line] = current.slice(0, targetCol) + current.slice(cursor.col);
+		editor.setCursorCol(targetCol);
+		editor.onChange?.(this.getText());
+		surface.discardMarkerIndex(hit.index);
+		this.invalidate();
+		this.onSnapshot({ ...this.snapshot });
+		return true;
+	}
+
+	/**
+	 * Artifact-path fallback (ADR 0009): when the keystroke was not owned
+	 * (probe unavailable, native editor path, config toggled) Pi's built-in
+	 * paste still inserts a `<tmpdir>/pi-clipboard-<uuid>.<ext>` path through
+	 * this method. Convert it to a marker when the artifact reads successfully;
+	 * every failure inserts the original text verbatim (exact native behavior).
+	 */
+	override insertTextAtCursor(text: string): void {
+		const surface = this.clipboardImagePaste;
+		if (!surface?.enabled() || !isSingleClipboardImagePath(text)) {
+			super.insertTextAtCursor(text);
+			return;
+		}
+		void (async () => {
+			let replacement = text;
+			try {
+				replacement = await surface.markerFromArtifact(text);
+			} catch {
+				// Unreadable artifact or surface failure: keep native behavior.
+			}
+			super.insertTextAtCursor(replacement);
+			// The caller (Pi's handleClipboardPaste) requested its render before
+			// this async insert completed — without a repaint the marker stays
+			// invisible until the next keystroke. Request one now.
+			this.tui.requestRender();
+		})();
+	}
+
 	override invalidate(): void {
 		super.invalidate();
 		// The semantic theme is derived from (piTheme, config); piTheme is fixed per
@@ -412,6 +537,7 @@ export function installEditor(options: {
 	generation: number;
 	initialSnapshot: StatusSnapshot;
 	isCurrent?: () => boolean;
+	clipboardImagePaste?: EditorOptions["clipboardImagePaste"];
 }): EditorInstallation | undefined {
 	if (!options.host.setEditorComponent) return undefined;
 	const previous = options.host.getEditorComponent?.();
@@ -436,6 +562,7 @@ export function installEditor(options: {
 			snapshot,
 			theme,
 			...(options.host.theme ? { fullTheme: options.host.theme } : {}),
+			...(options.clipboardImagePaste ? { clipboardImagePaste: options.clipboardImagePaste } : {}),
 			onSnapshot: (next) => {
 				if (!disposed && options.isCurrent?.() !== false) snapshot = next;
 			},

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

@@ -0,0 +1,205 @@
+// Clipboard image input (ADR 0009): submit-side wiring.
+//
+// The editor surface (StyledEditor) owns the keystroke-time behavior:
+// instant `[Image #N] ` markers via the shared pending registry. This module
+// owns what happens at submit: resolve markers against the registry
+// (one-shot; removed markers discard their images), then upgrade any raw
+// clipboard artifact path tokens that bypassed the editor (native editor
+// style, config toggled after paste, non-pi-style surfaces) to `[image]` +
+// attachments. Fail-safe at every step: missing/oversized files keep their
+// text, nothing is lost. Filesystem reads happen on the input path only —
+// renderers stay I/O-free (TOOL-007).
+
+import { readFile, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { clipboardPathRegex, extractClipboardImageTokens as sharedExtractTokens } from "../../shared/clipboard-path.js";
+import { clipboardHasImageSync, readClipboardImageBinary } from "../../shared/clipboard-presence.js";
+import {
+	allocatePendingImage,
+	discardPendingMarkerIndex,
+	fillPendingImageBytes,
+	fillPendingImageFromPath,
+	isPendingImageFilled,
+	isPendingMarkerIndex,
+	type PendingImageAttachment,
+	resolvePendingImagesForSubmit as sharedResolve,
+} from "../../shared/pending-images.js";
+import { getMessagesRenderConfig } from "./render-config.js";
+
+/** Replacement token for an attached clipboard image (marker vocabulary). */
+export const IMAGE_TOKEN = "[image]";
+
+/** Mirrors image-paste's guard; larger files keep the path. */
+const MAX_ATTACHABLE_BYTES = 20 * 1024 * 1024;
+
+const MIME_BY_EXTENSION: Readonly<Record<string, string>> = Object.freeze({
+	png: "image/png",
+	jpg: "image/jpeg",
+	jpeg: "image/jpeg",
+	webp: "image/webp",
+	gif: "image/gif",
+});
+
+export { extractClipboardImageTokens, isSingleClipboardImagePath } from "../../shared/clipboard-path.js";
+export {
+	type PendingImageAttachment,
+	resetPendingImageRegistry,
+	resolvePendingImagesForSubmit,
+} from "../../shared/pending-images.js";
+
+// ── Clipboard image paste surface (editor wiring; ADR 0009) ─────────────
+
+/** Structural surface the editor consumes (kept structural so the editor
+ *  feature needs no cross-feature import; app/runtime passes the instance). */
+export interface ClipboardImagePasteSurface {
+	/** Config gate (`messages.clipboardImages`). */
+	enabled(): boolean;
+	/** Sync clipboard image presence; null when the probe is unavailable. */
+	clipboardHasImage(): boolean | null;
+	/** Instant marker: allocate + insert-time text; the bytes fill
+	 *  asynchronously from the clipboard. */
+	markerFromClipboard(): string;
+	/** Marker (or the original path on failure) from a clipboard artifact
+	 *  file — the fallback when the keystroke wasn't owned. */
+	markerFromArtifact(path: string): Promise<string>;
+	isMarkerIndexRegistered(index: number): boolean;
+	discardMarkerIndex(index: number): void;
+}
+
+/** Test seam for the native clipboard probes. */
+export interface ClipboardImagePasteDeps {
+	hasImage?: () => boolean | null;
+	readBinary?: () => Promise<{ bytes: Uint8Array } | null>;
+}
+
+export function createClipboardImagePasteSurface(deps: ClipboardImagePasteDeps = {}): ClipboardImagePasteSurface {
+	const hasImage = deps.hasImage ?? clipboardHasImageSync;
+	// Owned-paste path: markerFromClipboard runs only after clipboardHasImage()
+	// returned true (editor keystroke handler), so the default binary read
+	// skips the redundant second native presence probe.
+	const readBinary = deps.readBinary ?? (() => readClipboardImageBinary({ skipPresenceProbe: true }));
+	return {
+		enabled: () => getMessagesRenderConfig().clipboardImages,
+		clipboardHasImage: () => {
+			try {
+				return hasImage();
+			} catch {
+				return null;
+			}
+		},
+		markerFromClipboard() {
+			const { index, marker } = allocatePendingImage();
+			// Async fill: bytes land in the registry entry before submit resolves.
+			void (async () => {
+				try {
+					const image = await readBinary();
+					if (image) {
+						// Zero-copy view (offset+length explicit so Uint8Array views over a
+						// larger backing buffer encode exactly their own range — avoids a
+						// second full copy of a ~1.3MB screenshot per paste).
+						fillPendingImageBytes(
+							index,
+							Buffer.from(image.bytes.buffer, image.bytes.byteOffset, image.bytes.byteLength).toString("base64"),
+							"image/png",
+						);
+						return;
+					}
+				} catch {
+					// Read failure below discards the entry.
+				}
+				// No bytes: discard so a submit never dangles on this entry (the
+				// marker stays plain text — documented degradation, nothing lost).
+				discardPendingMarkerIndex(index);
+			})();
+			return marker;
+		},
+		async markerFromArtifact(path: string) {
+			const { index, marker } = allocatePendingImage();
+			await fillPendingImageFromPath(index, path);
+			return isPendingImageFilled(index) ? marker : path;
+		},
+		isMarkerIndexRegistered: (index) => isPendingMarkerIndex(index),
+		discardMarkerIndex: (index) => discardPendingMarkerIndex(index),
+	};
+}
+
+/**
+ * Resolve `[Image #N]` markers for a submit (delegates to the shared
+ * registry; one-shot per submit). Config-gated.
+ */
+export async function resolvePendingImageMarkers(
+	text: string,
+): Promise<{ images: PendingImageAttachment[] } | undefined> {
+	if (!getMessagesRenderConfig().clipboardImages) return undefined;
+	return sharedResolve(text);
+}
+
+// ── Submit transform (raw artifact tokens) ─────────────────────────────────
+
+/**
+ * Input transform for raw clipboard-paste path tokens that bypassed the
+ * editor interception: read each token, attach the bytes as ImageContent,
+ * rewrite the token to `[image]`. Tokens whose file is missing/unreadable or
+ * over the size guard keep their original text. Returns undefined when
+ * nothing changed (caller keeps `action: "continue"`).
+ */
+export async function transformClipboardImages(
+	text: string,
+	deps: {
+		readFile?: (path: string) => Promise<Uint8Array>;
+		statSize?: (path: string) => Promise<number | undefined>;
+		tmpRoot?: string;
+	} = {},
+): Promise<{ text: string; images: PendingImageAttachment[] } | undefined> {
+	if (!getMessagesRenderConfig().clipboardImages) return undefined;
+	const tokens = sharedExtractTokens(text, deps.tmpRoot);
+	if (tokens.length === 0) return undefined;
+
+	const attached: PendingImageAttachment[] = [];
+	const rewritten = new Map<string, string>();
+	for (const token of tokens) {
+		const image = await readAttachable(token, deps);
+		if (!image) continue;
+		attached.push({ type: "image", data: image.data, mimeType: image.mimeType });
+		rewritten.set(token, IMAGE_TOKEN);
+	}
+	if (attached.length === 0) return undefined;
+	return { text: rewriteTokens(text, rewritten, deps.tmpRoot), images: attached };
+}
+
+async function readAttachable(
+	path: string,
+	deps:
+		| { readFile?: (path: string) => Promise<Uint8Array>; statSize?: (path: string) => Promise<number | undefined> }
+		| undefined,
+): Promise<{ data: string; mimeType: string } | undefined> {
+	const extension = path.split(".").pop() ?? "";
+	const mimeType = MIME_BY_EXTENSION[extension];
+	if (!mimeType) return undefined;
+	const readFileImpl = deps?.readFile ?? ((p: string) => readFile(p));
+	const statSizeImpl =
+		deps?.statSize ??
+		(async (p: string) => {
+			try {
+				return (await stat(p)).size;
+			} catch {
+				return undefined;
+			}
+		});
+	try {
+		const size = await statSizeImpl(path);
+		if (size === undefined || size <= 0 || size > MAX_ATTACHABLE_BYTES) return undefined;
+		const bytes = await readFileImpl(path);
+		if (bytes.length === 0 || bytes.length > MAX_ATTACHABLE_BYTES) return undefined;
+		return { data: Buffer.from(bytes).toString("base64"), mimeType };
+	} catch {
+		return undefined;
+	}
+}
+
+function rewriteTokens(text: string, rewritten: Map<string, string>, tmpRoot?: string): string {
+	if (rewritten.size === 0) return text;
+	return text.replace(clipboardPathRegex(tmpRoot ?? tmpdir()), (match, token: string) =>
+		rewritten.has(token) ? IMAGE_TOKEN : match,
+	);
+}