pi-image-tools 1.3.0 → 1.3.1

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [Unreleased]
+
+## [1.3.1] - 2026-06-16
+
+### Fixed
+- Default paste-image shortcuts now avoid Pi built-in shortcut conflicts on all platforms, including macOS. Previously macOS defaulted to overriding Pi's built-in `ctrl+v` image paste binding and printed a startup conflict warning. (reported by @gaodes in [#8](https://github.com/MasuRii/pi-image-tools/issues/8))
+- Transcode clipboard images that arrive in MIME types model providers reject (most notably `image/bmp` from WSLg's Wayland clipboard bridge for Windows clipboard images, and `image/tiff` from some macOS sources) into PNG via ImageMagick before attaching them. Previously, pasting a Windows screenshot inside WSL produced an `Unknown image type: image/bmp` error from the model provider that blocked the message from being sent. (contributed by @codeviking428 in [#9](https://github.com/MasuRii/pi-image-tools/pull/9))
+
 ## [1.3.0] - 2026-06-01
 
 ### Added

package/README.md

@@ -25,6 +25,7 @@ Image attachment and preview extension for the **Pi coding agent**.
 |----------|-----------------|---------------------|-------|
 | Windows | Yes | Yes | Uses native clipboard module first, then PowerShell fallback |
 | Linux | Yes | Yes | Requires a graphical session; uses `wl-paste` or `xclip`, then native module fallback |
+| WSL2 (WSLg) | Yes | Yes | Linux providers see Windows clipboard images as `image/bmp`; install ImageMagick (`magick`/`convert`) so they can be transcoded to PNG before attaching |
 | macOS | Yes | Yes | Uses `pngpaste` first, then `osascript` and native module fallbacks |
 | Termux / headless Linux | No | Limited | Clipboard image paste is disabled without a graphical session |
 
@@ -122,13 +123,15 @@ $env:PI_IMAGE_TOOLS_RECENT_DIRS = "C:\Users\me\Pictures\Screenshots;D:\Shares\Sc
 
 ### Runtime config
 
-A config file can be placed at:
+A config file can be placed at the `pi-image-tools` package/install root next to `index.ts`. For npm-installed extensions this is the package directory under Pi's npm install area, for example:
 
 ```text
-Default global path: ~/.pi/agent/extensions/pi-image-tools/config.json
-Actual global path: $PI_CODING_AGENT_DIR/extensions/pi-image-tools/config.json when PI_CODING_AGENT_DIR is set
+~/.pi/agent/npm/node_modules/pi-image-tools/config.json
+$PI_CODING_AGENT_DIR/npm/node_modules/pi-image-tools/config.json when PI_CODING_AGENT_DIR is set
 ```
 
+For a local checkout or extension path, place `config.json` in that `pi-image-tools` directory.
+
 Starter template:
 
 ```json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-image-tools",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "Image attachment and rendering extension for Pi TUI",
   "type": "module",
   "main": "./index.ts",
@@ -60,8 +60,8 @@
     ]
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.74.0 || ^0.75.0 || ^0.77.0 || ^0.78.0",
-    "@earendil-works/pi-tui": "^0.74.0 || ^0.75.0 || ^0.77.0 || ^0.78.0"
+    "@earendil-works/pi-coding-agent": "^0.74.0 || ^0.75.0 || ^0.77.0 || ^0.78.0 || ^0.79.0",
+    "@earendil-works/pi-tui": "^0.74.0 || ^0.75.0 || ^0.77.0 || ^0.78.0 || ^0.79.0"
   },
   "optionalDependencies": {
     "@mariozechner/clipboard": "^0.3.9"

package/src/clipboard.ts

@@ -1,89 +1,99 @@
-import { hasGraphicalSession, isWaylandSession } from "./shell-environment.js";
-import { NativeModuleProvider } from "./providers/native-module.js";
-import { OsascriptPngfProvider } from "./providers/mac-osascript-pngf.js";
-import { OsascriptPublicPngProvider } from "./providers/mac-osascript-publicpng.js";
-import { PngpasteProvider } from "./providers/mac-pngpaste.js";
-import { PowerShellFormsProvider } from "./providers/powershell-forms.js";
-import { ClipboardProviderRegistry } from "./providers/registry.js";
-import { WlPasteProvider } from "./providers/wl-paste.js";
-import { XclipProvider } from "./providers/xclip.js";
-import type { ClipboardImage } from "./types.js";
-
-export { hasGraphicalSession } from "./shell-environment.js";
-
-export function buildDefaultClipboardProviderRegistry(
-  platform: NodeJS.Platform,
-  environment: NodeJS.ProcessEnv,
-): ClipboardProviderRegistry {
-  const registry = new ClipboardProviderRegistry();
-
-  if (platform === "win32") {
-    registry
-      .register(new NativeModuleProvider({ priority: 10 }))
-      .register(new PowerShellFormsProvider({ priority: 20 }));
-    return registry;
-  }
-
-  if (platform === "linux") {
-    const waylandFirst = isWaylandSession(environment);
-    registry
-      .register(new WlPasteProvider({ priority: waylandFirst ? 10 : 20 }))
-      .register(new XclipProvider({ priority: waylandFirst ? 20 : 10 }))
-      .register(new NativeModuleProvider({ priority: 30 }));
-    return registry;
-  }
-
-  if (platform === "darwin") {
-    registry
-      .register(new PngpasteProvider({ priority: 10 }))
-      .register(new OsascriptPublicPngProvider({ priority: 20 }))
-      .register(new OsascriptPngfProvider({ priority: 30 }))
-      .register(new NativeModuleProvider({ priority: 40 }));
-    return registry;
-  }
-
-  registry.register(new NativeModuleProvider({ priority: 100 }));
-  return registry;
-}
-
-function getUnavailableReaderMessage(platform: NodeJS.Platform): string {
-  switch (platform) {
-    case "linux":
-      return "No Linux clipboard image reader is available. Install wl-clipboard or xclip, or ensure @mariozechner/clipboard is installed.";
-    case "darwin":
-      return "No macOS clipboard image reader is available. Install pngpaste, ensure osascript is available, or ensure @mariozechner/clipboard is installed.";
-    case "win32":
-      return "No Windows clipboard image reader is available. Ensure PowerShell is available or @mariozechner/clipboard is installed.";
-    default:
-      return `Clipboard image paste is not supported on platform: ${platform}`;
-  }
-}
-
-export async function readClipboardImage(options?: {
-  environment?: NodeJS.ProcessEnv;
-  platform?: NodeJS.Platform;
-  registry?: ClipboardProviderRegistry;
-}): Promise<ClipboardImage | null> {
-  const environment = options?.environment ?? process.env;
-  const platform = options?.platform ?? process.platform;
-
-  if (environment.TERMUX_VERSION) {
-    return null;
-  }
-
-  if (!hasGraphicalSession(platform, environment)) {
-    throw new Error("Clipboard image paste requires a graphical desktop session with DISPLAY or WAYLAND_DISPLAY.");
-  }
-
-  const registry = options?.registry ?? buildDefaultClipboardProviderRegistry(platform, environment);
-  const result = await registry.read({ platform, environment });
-  if (result.image) {
-    return result.image;
-  }
-
-  if (result.attempts.some((attempt) => attempt.available)) {
-    return null;
-  }
-
-  throw new Error(getUnavailableReaderMessage(platform));
-}
+import { hasGraphicalSession, isWaylandSession } from "./shell-environment.js";
+import { transcodeToSupportedFormat, type TranscodeOptions } from "./image-transcode.js";
+import { NativeModuleProvider } from "./providers/native-module.js";
+import { OsascriptPngfProvider } from "./providers/mac-osascript-pngf.js";
+import { OsascriptPublicPngProvider } from "./providers/mac-osascript-publicpng.js";
+import { PngpasteProvider } from "./providers/mac-pngpaste.js";
+import { PowerShellFormsProvider } from "./providers/powershell-forms.js";
+import { ClipboardProviderRegistry } from "./providers/registry.js";
+import { WlPasteProvider } from "./providers/wl-paste.js";
+import { XclipProvider } from "./providers/xclip.js";
+import type { ClipboardImage } from "./types.js";
+
+export { hasGraphicalSession } from "./shell-environment.js";
+
+export function buildDefaultClipboardProviderRegistry(
+  platform: NodeJS.Platform,
+  environment: NodeJS.ProcessEnv,
+): ClipboardProviderRegistry {
+  const registry = new ClipboardProviderRegistry();
+
+  if (platform === "win32") {
+    registry
+      .register(new NativeModuleProvider({ priority: 10 }))
+      .register(new PowerShellFormsProvider({ priority: 20 }));
+    return registry;
+  }
+
+  if (platform === "linux") {
+    const waylandFirst = isWaylandSession(environment);
+    registry
+      .register(new WlPasteProvider({ priority: waylandFirst ? 10 : 20 }))
+      .register(new XclipProvider({ priority: waylandFirst ? 20 : 10 }))
+      .register(new NativeModuleProvider({ priority: 30 }));
+    return registry;
+  }
+
+  if (platform === "darwin") {
+    registry
+      .register(new PngpasteProvider({ priority: 10 }))
+      .register(new OsascriptPublicPngProvider({ priority: 20 }))
+      .register(new OsascriptPngfProvider({ priority: 30 }))
+      .register(new NativeModuleProvider({ priority: 40 }));
+    return registry;
+  }
+
+  registry.register(new NativeModuleProvider({ priority: 100 }));
+  return registry;
+}
+
+function getUnavailableReaderMessage(platform: NodeJS.Platform): string {
+  switch (platform) {
+    case "linux":
+      return "No Linux clipboard image reader is available. Install wl-clipboard or xclip, or ensure @mariozechner/clipboard is installed.";
+    case "darwin":
+      return "No macOS clipboard image reader is available. Install pngpaste, ensure osascript is available, or ensure @mariozechner/clipboard is installed.";
+    case "win32":
+      return "No Windows clipboard image reader is available. Ensure PowerShell is available or @mariozechner/clipboard is installed.";
+    default:
+      return `Clipboard image paste is not supported on platform: ${platform}`;
+  }
+}
+
+export async function readClipboardImage(options?: {
+  environment?: NodeJS.ProcessEnv;
+  platform?: NodeJS.Platform;
+  registry?: ClipboardProviderRegistry;
+  /**
+   * Hooks for the post-read transcoding step that normalizes images into a
+   * MIME type accepted by model providers. Mainly for tests; the default
+   * implementation shells out to ImageMagick only when the source format isn't
+   * already supported.
+   */
+  transcode?: TranscodeOptions;
+}): Promise<ClipboardImage | null> {
+  const environment = options?.environment ?? process.env;
+  const platform = options?.platform ?? process.platform;
+
+  if (environment.TERMUX_VERSION) {
+    return null;
+  }
+
+  if (!hasGraphicalSession(platform, environment)) {
+    throw new Error("Clipboard image paste requires a graphical desktop session with DISPLAY or WAYLAND_DISPLAY.");
+  }
+
+  const registry = options?.registry ?? buildDefaultClipboardProviderRegistry(platform, environment);
+  const result = await registry.read({ platform, environment });
+  if (result.image) {
+    // Providers (notably wl-paste under WSLg) may return formats like
+    // image/bmp that model providers reject. Normalize to PNG when needed.
+    return transcodeToSupportedFormat(result.image, { platform, ...options?.transcode });
+  }
+
+  if (result.attempts.some((attempt) => attempt.available)) {
+    return null;
+  }
+
+  throw new Error(getUnavailableReaderMessage(platform));
+}

package/src/config.ts

@@ -86,9 +86,9 @@ function parseShortcutList(value: unknown, property: string, path: string): KeyI
   return shortcuts;
 }
 
-function getDefaultShortcutConfig(platform: NodeJS.Platform): ImageToolsShortcutConfig {
+function getDefaultShortcutConfig(_platform: NodeJS.Platform): ImageToolsShortcutConfig {
   return {
-    avoidBuiltinConflicts: platform !== "darwin",
+    avoidBuiltinConflicts: true,
     suppressBuiltinConflictWarnings: false,
   };
 }

package/src/image-size.ts

@@ -1,63 +1,62 @@
-export const IMAGE_TOOLS_MAX_IMAGE_BYTES_ENV_VAR = "PI_IMAGE_TOOLS_MAX_IMAGE_BYTES";
-export const DEFAULT_MAX_IMAGE_BYTES = 20 * 1024 * 1024;
-
-function parseMaxImageBytes(environment: NodeJS.ProcessEnv): number {
-  const rawValue = environment[IMAGE_TOOLS_MAX_IMAGE_BYTES_ENV_VAR]?.trim();
-  if (!rawValue) {
-    return DEFAULT_MAX_IMAGE_BYTES;
-  }
-
-  const parsed = Number(rawValue);
-  if (!Number.isFinite(parsed) || parsed < 1) {
-    throw new Error(
-      `${IMAGE_TOOLS_MAX_IMAGE_BYTES_ENV_VAR} must be a positive byte count when set.`,
-    );
-  }
-
-  return Math.floor(parsed);
-}
-
-export function getMaxImageBytes(environment: NodeJS.ProcessEnv = process.env): number {
-  return parseMaxImageBytes(environment);
-}
-
-export function formatByteLimit(bytes: number): string {
-  if (bytes < 1024) {
-    return `${bytes} B`;
-  }
-
-  const units = ["KB", "MB", "GB"] as const;
-  let value = bytes / 1024;
-  let unitIndex = 0;
-
-  while (value >= 1024 && unitIndex < units.length - 1) {
-    value /= 1024;
-    unitIndex += 1;
-  }
-
-  return `${value.toFixed(value >= 10 ? 0 : 1)} ${units[unitIndex]}`;
-}
-
-export function assertImageWithinByteLimit(
-  sizeBytes: number,
-  label: string,
-  environment: NodeJS.ProcessEnv = process.env,
-): void {
-  const maxImageBytes = getMaxImageBytes(environment);
-  if (sizeBytes > maxImageBytes) {
-    throw new Error(
-      `${label} is too large (${formatByteLimit(sizeBytes)}). The pi-image-tools limit is ${formatByteLimit(maxImageBytes)}. Set ${IMAGE_TOOLS_MAX_IMAGE_BYTES_ENV_VAR} to a larger byte count if needed.`,
-    );
-  }
-}
-
-export function getBase64DecodedByteLength(base64Data: string): number {
-  const normalized = base64Data.trim().replace(/^data:[^,]*,/, "").replace(/\s/g, "");
-  if (normalized.length === 0) {
-    return 0;
-  }
-
-  const padding = normalized.endsWith("==") ? 2 : normalized.endsWith("=") ? 1 : 0;
-  return Math.max(0, Math.floor((normalized.length * 3) / 4) - padding);
-}
-
+export const IMAGE_TOOLS_MAX_IMAGE_BYTES_ENV_VAR = "PI_IMAGE_TOOLS_MAX_IMAGE_BYTES";
+export const DEFAULT_MAX_IMAGE_BYTES = 20 * 1024 * 1024;
+
+function parseMaxImageBytes(environment: NodeJS.ProcessEnv): number {
+  const rawValue = environment[IMAGE_TOOLS_MAX_IMAGE_BYTES_ENV_VAR]?.trim();
+  if (!rawValue) {
+    return DEFAULT_MAX_IMAGE_BYTES;
+  }
+
+  const parsed = Number(rawValue);
+  if (!Number.isFinite(parsed) || parsed < 1) {
+    throw new Error(
+      `${IMAGE_TOOLS_MAX_IMAGE_BYTES_ENV_VAR} must be a positive byte count when set.`,
+    );
+  }
+
+  return Math.floor(parsed);
+}
+
+export function getMaxImageBytes(environment: NodeJS.ProcessEnv = process.env): number {
+  return parseMaxImageBytes(environment);
+}
+
+export function formatByteLimit(bytes: number): string {
+  if (bytes < 1024) {
+    return `${bytes} B`;
+  }
+
+  const units = ["KB", "MB", "GB"] as const;
+  let value = bytes / 1024;
+  let unitIndex = 0;
+
+  while (value >= 1024 && unitIndex < units.length - 1) {
+    value /= 1024;
+    unitIndex += 1;
+  }
+
+  return `${value.toFixed(value >= 10 ? 0 : 1)} ${units[unitIndex]}`;
+}
+
+export function assertImageWithinByteLimit(
+  sizeBytes: number,
+  label: string,
+  environment: NodeJS.ProcessEnv = process.env,
+): void {
+  const maxImageBytes = getMaxImageBytes(environment);
+  if (sizeBytes > maxImageBytes) {
+    throw new Error(
+      `${label} is too large (${formatByteLimit(sizeBytes)}). The pi-image-tools limit is ${formatByteLimit(maxImageBytes)}. Set ${IMAGE_TOOLS_MAX_IMAGE_BYTES_ENV_VAR} to a larger byte count if needed.`,
+    );
+  }
+}
+
+export function getBase64DecodedByteLength(base64Data: string): number {
+  const normalized = base64Data.trim().replace(/^data:[^,]*,/, "").replace(/\s/g, "");
+  if (normalized.length === 0) {
+    return 0;
+  }
+
+  return Buffer.from(normalized, "base64").length;
+}
+

package/src/image-transcode.ts

@@ -0,0 +1,198 @@
+import { spawnSync, type SpawnSyncReturns } from "node:child_process";
+
+import { normalizeMimeType } from "./image-mime.js";
+import type { ClipboardImage } from "./types.js";
+
+const DEFAULT_PRIMARY_TRANSCODE_TOOL = "magick";
+const LEGACY_UNIX_TRANSCODE_TOOL = "convert";
+
+/**
+ * Maximum wall-clock time for a single ImageMagick invocation. Bounded so a
+ * malformed input cannot hang the extension indefinitely; well above what a
+ * typical clipboard-sized image needs to convert.
+ */
+const TRANSCODE_TIMEOUT_MS = 30_000;
+
+/**
+ * Maximum buffered output from ImageMagick. PNG re-encoding of a typical
+ * Windows screenshot is well under 5 MB; 64 MB gives us several orders of
+ * magnitude of headroom while still bounding memory.
+ */
+const TRANSCODE_MAX_BUFFER_BYTES = 64 * 1024 * 1024;
+
+/**
+ * MIME types that the major model providers (Anthropic, OpenAI, Bedrock, Gemini)
+ * accept as image input. Anything outside this set must be transcoded before
+ * being attached to a user message, otherwise providers return errors such as
+ * "Unknown image type: image/bmp".
+ *
+ * Distinct from `SUPPORTED_IMAGE_MIME_TYPES` in `./image-mime.ts`, which
+ * describes formats the *clipboard providers* know how to read (including
+ * `image/bmp`). The two sets serve opposite ends of the pipeline.
+ */
+export const MODEL_PROVIDER_IMAGE_MIME_TYPES: ReadonlySet<string> = new Set([
+  "image/png",
+  "image/jpeg",
+  "image/gif",
+  "image/webp",
+]);
+
+/**
+ * Aliases and legacy MIME spellings that providers or clipboard sources may
+ * emit. Canonicalization keeps supported formats on the fast path and gives
+ * ImageMagick stable input format names for formats that need transcoding.
+ */
+const MIME_ALIASES: ReadonlyMap<string, string> = new Map([
+  ["image/jpg", "image/jpeg"],
+  ["image/pjpeg", "image/jpeg"],
+  ["image/x-png", "image/png"],
+  ["image/x-bmp", "image/bmp"],
+  ["image/x-ms-bmp", "image/bmp"],
+  ["image/tif", "image/tiff"],
+]);
+
+const IMAGE_MAGICK_INPUT_FORMAT_BY_MIME_TYPE: ReadonlyMap<string, string> = new Map([
+  ["image/bmp", "bmp"],
+  ["image/tiff", "tiff"],
+  ["image/svg+xml", "svg"],
+  ["image/heic", "heic"],
+  ["image/heif", "heif"],
+  ["image/avif", "avif"],
+]);
+
+function getDefaultTranscodeTools(platform?: NodeJS.Platform): readonly string[] {
+  if (platform === "win32") {
+    // Windows ships C:\Windows\System32\convert.exe, which is unrelated to
+    // ImageMagick and can produce confusing failures. Prefer the modern
+    // ImageMagick 7 `magick` launcher by default on Windows; callers that know
+    // they have an ImageMagick `convert` on PATH can still pass `tools`.
+    return [DEFAULT_PRIMARY_TRANSCODE_TOOL];
+  }
+
+  return [DEFAULT_PRIMARY_TRANSCODE_TOOL, LEGACY_UNIX_TRANSCODE_TOOL];
+}
+
+function describeTranscodeTools(tools: readonly string[]): string {
+  const uniqueTools = [...new Set(tools.length > 0 ? tools : [DEFAULT_PRIMARY_TRANSCODE_TOOL])];
+  if (uniqueTools.length === 1) {
+    return `\`${uniqueTools[0]}\``;
+  }
+
+  const quotedTools = uniqueTools.map((tool) => `\`${tool}\``);
+  return `${quotedTools.slice(0, -1).join(", ")} or ${quotedTools[quotedTools.length - 1]}`;
+}
+
+function imageMagickInputFormatForMimeType(canonicalMimeType: string): string {
+  const mappedFormat = IMAGE_MAGICK_INPUT_FORMAT_BY_MIME_TYPE.get(canonicalMimeType);
+  if (mappedFormat) {
+    return mappedFormat;
+  }
+
+  if (!canonicalMimeType.startsWith("image/")) {
+    return "";
+  }
+
+  const subtype = canonicalMimeType.slice("image/".length);
+  return subtype.split("+")[0] ?? "";
+}
+
+function isMissingCommandError(error: Error): boolean {
+  return (error as NodeJS.ErrnoException).code === "ENOENT";
+}
+
+function canonicalizeMimeType(mimeType: string): string {
+  const normalized = normalizeMimeType(mimeType);
+  return MIME_ALIASES.get(normalized) ?? normalized;
+}
+
+export interface TranscodeRunner {
+  (
+    command: string,
+    args: readonly string[],
+    input: Uint8Array,
+  ): SpawnSyncReturns<Buffer>;
+}
+
+const defaultTranscodeRunner: TranscodeRunner = (command, args, input) =>
+  spawnSync(command, args as string[], {
+    input: Buffer.from(input),
+    maxBuffer: TRANSCODE_MAX_BUFFER_BYTES,
+    timeout: TRANSCODE_TIMEOUT_MS,
+    windowsHide: true,
+  });
+
+export interface TranscodeOptions {
+  /** Override the spawn implementation. Mainly for tests. */
+  runner?: TranscodeRunner;
+  /** Override the list of candidate ImageMagick executables. */
+  tools?: readonly string[];
+  /** Platform used to choose safe default ImageMagick executable fallbacks. */
+  platform?: NodeJS.Platform;
+}
+
+/**
+ * Ensure a clipboard image is in a MIME type accepted by model providers.
+ *
+ * Images already in a supported format are returned with a canonicalized MIME
+ * (lower-cased, parameters stripped, `image/jpg` upgraded to `image/jpeg`) and
+ * otherwise unchanged bytes. Other formats (most notably `image/bmp`, which is
+ * what WSLg exposes for Windows clipboard images on the Wayland clipboard, and
+ * `image/tiff` from some macOS sources) are piped through ImageMagick and
+ * re-encoded as PNG.
+ *
+ * Throws if the source format is unsupported and no ImageMagick binary
+ * (`magick` or the legacy `convert`) is available, or if the conversion fails.
+ */
+export function transcodeToSupportedFormat(
+  image: ClipboardImage,
+  options: TranscodeOptions = {},
+): ClipboardImage {
+  const canonicalMimeType = canonicalizeMimeType(image.mimeType);
+
+  if (MODEL_PROVIDER_IMAGE_MIME_TYPES.has(canonicalMimeType)) {
+    // Fast path: bytes are already in a provider-accepted format.
+    // Return the canonicalized MIME so downstream consumers don't have to
+    // worry about parameters/casing/aliases.
+    return canonicalMimeType === image.mimeType
+      ? image
+      : { bytes: image.bytes, mimeType: canonicalMimeType };
+  }
+
+  const runner = options.runner ?? defaultTranscodeRunner;
+  const platform = options.platform ?? process.platform;
+  const tools = options.tools ?? getDefaultTranscodeTools(platform);
+
+  const inputFormat = imageMagickInputFormatForMimeType(canonicalMimeType);
+  const inputSpec = inputFormat.length > 0 ? `${inputFormat}:-` : "-";
+
+  const failures: string[] = [];
+  for (const tool of tools) {
+    const result = runner(tool, [inputSpec, "png:-"], image.bytes);
+    if (result.error) {
+      failures.push(`${tool}: ${result.error.message}`);
+      if (isMissingCommandError(result.error)) {
+        continue;
+      }
+      break;
+    }
+    if (result.status !== 0 || !result.stdout || result.stdout.length === 0) {
+      const stderr = result.stderr ? result.stderr.toString("utf8").trim() : "";
+      failures.push(`${tool} exited with status ${result.status}${stderr ? `: ${stderr}` : ""}`);
+      break;
+    }
+    return {
+      bytes: new Uint8Array(result.stdout),
+      mimeType: "image/png",
+    };
+  }
+
+  const detail = failures.length > 0
+    ? ` (${failures.join("; ")})`
+    : tools.length === 0
+      ? " (no transcode tools configured)"
+      : "";
+  throw new Error(
+    `Clipboard image is in unsupported format "${image.mimeType}" and could not be transcoded to PNG. ` +
+      `Install ImageMagick (${describeTranscodeTools(tools)}) so pi-image-tools can convert images that providers don't accept natively.${detail}`,
+  );
+}