@quandev104/pi-style 0.2.1 → 0.2.3

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

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

@@ -1,3 +1,5 @@
+import { visibleWidth as tuiVisibleWidth } from "@earendil-works/pi-tui";
+
 function isFinal(byte: string): boolean {
 	return byte >= "@" && byte <= "~";
 }
@@ -91,8 +93,12 @@ export function stripAnsi(value: string): string {
 	}
 	return output;
 }
+/**
+ * Terminal-correct visible width: delegates to pi-tui (ANSI-stripping,
+ * ASCII fast path, per-string cache, wide chars = 2 columns, tabs = 3).
+ */
 export function visibleWidth(value: string): number {
-	return [...stripAnsi(value)].length;
+	return tuiVisibleWidth(value);
 }
 export function resetAnsi(value: string): string {
 	return `${value}\x1b[0m`;
@@ -105,9 +111,10 @@ export function fitAnsiWidth(value: string, width: number, ellipsis = "…"): st
 export function truncateAnsi(value: string, width: number, ellipsis = "…"): string {
 	if (width <= 0) return "";
 	if (visibleWidth(value) <= width) return resetAnsi(value);
+	const ellipsisWidth = visibleWidth(ellipsis);
 	let output = "";
 	let visible = 0;
-	for (let i = 0; i < value.length && visible < width - visibleWidth(ellipsis); i++) {
+	for (let i = 0; i < value.length && visible < width - ellipsisWidth; i++) {
 		if (value.charCodeAt(i) === 27) {
 			const start = i;
 			i++;
@@ -125,12 +132,17 @@ export function wrapAnsi(value: string, width: number): string[] {
 	if (width <= 0) return [""];
 	const lines: string[] = [];
 	let line = "";
+	let lineWidth = 0;
 	for (const word of value.split(/\s+/)) {
-		const next = line ? `${line} ${word}` : word;
-		if (visibleWidth(next) <= width) line = next;
-		else {
+		const wordWidth = visibleWidth(word);
+		const nextWidth = line ? lineWidth + 1 + wordWidth : wordWidth;
+		if (nextWidth <= width) {
+			line = line ? `${line} ${word}` : word;
+			lineWidth = nextWidth;
+		} else {
 			if (line) lines.push(resetAnsi(line));
 			line = truncateAnsi(word, width);
+			lineWidth = visibleWidth(line);
 		}
 	}
 	if (line || lines.length === 0) lines.push(resetAnsi(line));

package/extension-src/pi-style/shared/box.ts

@@ -149,12 +149,63 @@ export function countLines(text: string): number {
 	return normalized.split("\n").length;
 }
 
+// Word-character membership table powering countWords. ASCII and the UTF-16
+// surrogate range are initialized eagerly; every other BMP code point is
+// resolved through the Unicode letter/digit class on first sight and memoized,
+// so repeat scans are pure table lookups. The per-code-point regex dispatch
+// this replaces measured ~1.9ms per 90KB output on every boxed footer render;
+// note that String.match with a \p{L}\p{N} class is no faster on V8 — the
+// memoized scan is the only variant that hit the <0.2ms budget.
+const WORD_CP_UNKNOWN = 255;
+const WORD_CP_SURROGATE = 254;
+const WORD_CP_CLASS = new Uint8Array(0x10000).fill(WORD_CP_UNKNOWN);
+for (let code = 0x30; code <= 0x39; code++) WORD_CP_CLASS[code] = 1; // 0-9
+for (let code = 0x41; code <= 0x5a; code++) WORD_CP_CLASS[code] = 1; // A-Z
+for (let code = 0x61; code <= 0x7a; code++) WORD_CP_CLASS[code] = 1; // a-z
+WORD_CP_CLASS[0x27] = 1; // '
+WORD_CP_CLASS[0x2d] = 1; // -
+WORD_CP_CLASS[0x5f] = 1; // _
+WORD_CP_CLASS.fill(WORD_CP_SURROGATE, 0xd800, 0xe000);
+const NON_ASCII_WORD_RE = /[\p{L}\p{N}]/u;
+const ASTRAL_WORD_CP = new Map<number, 0 | 1>();
+
+function astralWordMembership(codePoint: number): 0 | 1 {
+	const cached = ASTRAL_WORD_CP.get(codePoint);
+	if (cached !== undefined) return cached;
+	const membership: 0 | 1 = NON_ASCII_WORD_RE.test(String.fromCodePoint(codePoint)) ? 1 : 0;
+	ASTRAL_WORD_CP.set(codePoint, membership);
+	return membership;
+}
+
+/** Counts words as maximal runs of word characters (letters, digits,
+ *  underscore, apostrophe, hyphen) — identical counts to a per-code-point
+ *  `\p{L}\p{N}_'-` class test, in one table-driven pass with no allocations. */
 export function countWords(text: string): number {
+	const len = text.length;
 	let count = 0;
-	let inWord = false;
-	for (const char of text) {
-		const isWord = /[\p{L}\p{N}_'-]/u.test(char);
-		if (isWord && !inWord) count++;
+	let inWord: number = 0;
+	for (let i = 0; i < len; i++) {
+		const code = text.charCodeAt(i);
+		const membership = WORD_CP_CLASS[code] ?? 0;
+		let isWord: number;
+		if (membership <= 1) {
+			isWord = membership;
+		} else if (membership === WORD_CP_SURROGATE) {
+			const next = i + 1 < len ? text.charCodeAt(i + 1) : 0;
+			if (code <= 0xdbff && next >= 0xdc00 && next <= 0xdfff) {
+				// Astral word characters (e.g. mathematical alphanumerics) count as
+				// one code point, exactly like the previous code-point iteration.
+				isWord = astralWordMembership(0x10000 + ((code - 0xd800) << 10) + (next - 0xdc00));
+				i++; // consumed the pair's low surrogate half
+			} else {
+				isWord = 0; // lone surrogate half: never a word character
+			}
+		} else {
+			// First sight of this non-ASCII BMP code point: resolve once, memoize.
+			isWord = NON_ASCII_WORD_RE.test(String.fromCharCode(code)) ? 1 : 0;
+			WORD_CP_CLASS[code] = isWord;
+		}
+		count += isWord & (inWord ^ 1);
 		inWord = isWord;
 	}
 	return count;
@@ -210,6 +261,9 @@ const BOX_DIVIDER_RIGHT = "┤";
 /** Dash run before the right corner when a right-side border label is present. */
 const BOX_LABELED_RIGHT_DASH_MIN = 3;
 const BOX_WIDTH_CACHE = new Map<string, number>();
+/** Hard cap for BOX_WIDTH_CACHE; the oldest entry is evicted beyond this. Keys
+ *  embed full bash commands, so the cache must stay bounded across a session. */
+const BOX_WIDTH_CACHE_MAX_ENTRIES = 512;
 
 export function boxWidth(width: number): number {
 	return Math.max(BOX_MIN_WIDTH, width);
@@ -236,6 +290,13 @@ function _tightBoxWidth(
 	if (!widthKey) return measuredWidth;
 	const cachedWidth = BOX_WIDTH_CACHE.get(widthKey) ?? 0;
 	const nextWidth = Math.min(boxWidth(availableWidth), Math.max(cachedWidth, measuredWidth));
+	// Bounded LRU: Map preserves insertion order, so delete+set refreshes the
+	// key's recency and the first key is the oldest evict candidate.
+	BOX_WIDTH_CACHE.delete(widthKey);
+	if (BOX_WIDTH_CACHE.size >= BOX_WIDTH_CACHE_MAX_ENTRIES) {
+		const oldestKey = BOX_WIDTH_CACHE.keys().next().value;
+		if (oldestKey !== undefined) BOX_WIDTH_CACHE.delete(oldestKey);
+	}
 	BOX_WIDTH_CACHE.set(widthKey, nextWidth);
 	return nextWidth;
 }
@@ -244,6 +305,11 @@ export function boxedToolWidthKey(toolName: string, detail: string): string {
 	return `${toolName}:${detail}`;
 }
 
+/** Test-only debug view of the bounded box width cache. */
+export function __getBoxWidthCacheDebugState(): { size: number } {
+	return { size: BOX_WIDTH_CACHE.size };
+}
+
 export function formatToolName(toolName: string): string {
 	const spaced = toolName
 		.replace(/[_-]+/g, " ")

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

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

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

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