pi-image-tools 1.0.10 → 1.1.0

package/CHANGELOG.md

@@ -1,25 +1,26 @@
 # Changelog
 
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [Unreleased]
-
-## [1.0.10] - 2026-04-22
+## [1.1.0] - 2026-05-03
 
 ### Added
-- Added preview width resolution from Pi terminal settings so inline and recent-image previews can honor `terminal.imageWidthCells`.
+- Added centralized image MIME, image-size, PowerShell, and error utilities used by clipboard, preview, attachment, and recent-image flows.
+- Added size-limit enforcement for image attachments, recent-cache writes, recent-image loads, and Sixel preview conversion through `PI_IMAGE_TOOLS_MAX_IMAGE_BYTES`.
 
 ### Changed
-- Updated recent image selection previews to resolve terminal settings from the active session working directory before rendering.
-- Windows Sixel fallback now activates only when native terminal image support is unavailable, with environment toggles to force or disable Sixel rendering.
-- Clarified README global install and config paths when `PI_CODING_AGENT_DIR` is set.
-- Updated `@mariozechner/pi-coding-agent` and `@mariozechner/pi-tui` peer dependencies to ^0.68.1.
+- Reworked recent-image caching to use an extension-owned cache directory with safe pruning that preserves user files.
+- Reworked Sixel preview rendering to use an existing PowerShell `Sixel` module only, normalize converter output into complete terminal sequences, and fall back to native previews with actionable warnings.
+- Reworked terminal image width resolution to honor Pi project/global `terminal.imageWidthCells` settings with a documented default fallback.
 
 ### Fixed
-- Ensured generated Sixel output is emitted as a complete DCS sequence and preserved inline image protocol rows during preview width fitting.
+- Prevented extension debug logging from writing terminal output; debug events now remain file-based and disabled by default.
+- Preserved Sixel, Kitty, and iTerm inline image protocol rows during preview width fitting.
+
+## [1.0.11] - 2026-04-25
+
+### Changed
+- Avoid Pi's built-in image paste shortcut by default while preserving the previous primary shortcut when users disable or rebind `app.clipboard.pasteImage` (thanks to @danielcherubini for reporting this in PR #3).
+- Replaced the placeholder `enabled` config with validated `debug`, explicit `shortcuts.pasteImage`, configurable built-in conflict avoidance, and built-in warning suppression settings.
+- Removed obsolete packaged README image assets now that the README uses a GitHub-hosted image.
 
 ## [1.0.9] - 2026-04-01
 
@@ -74,12 +75,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Rewrote README.md with professional documentation standards
 - Added comprehensive feature documentation, configuration reference, and usage examples
 
-## [1.0.1] - 2026-03-04
-
-- Included `asset/` in the npm package whitelist so README image assets ship in the tarball.
-
-## [1.0.0] - 2026-03-02
+## 1.0.0
 
 - Standardized repository layout to `src/` + root shim entrypoint.
 - Added TypeScript/Bundler project config, package metadata, and publish whitelist.
-- Added standard docs, license, and config template/runtime placeholder files.
+- Added standard docs, license, and initial runtime config files.

package/README.md

@@ -1,5 +1,7 @@
 # 🖼️ pi-image-tools
 
+[![npm version](https://img.shields.io/npm/v/pi-image-tools?style=flat-square)](https://www.npmjs.com/package/pi-image-tools) [![License](https://img.shields.io/github/license/MasuRii/pi-image-tools?style=flat-square)](LICENSE)
+
 Image attachment and preview extension for the **Pi coding agent**.
 
 `pi-image-tools` lets you attach clipboard images or recent screenshots to your next user message, then preview them inline in the TUI before the message is sent.
@@ -93,8 +95,16 @@ Selecting an entry queues that image for your next message.
 
 | Platform | Shortcuts |
 |----------|-----------|
-| Windows | `Alt+V`, `Ctrl+Alt+V` |
-| Linux / macOS | `Ctrl+V`, `Alt+V`, `Ctrl+Alt+V` |
+| Windows | `Ctrl+Alt+V`; `Alt+V` when Pi's built-in `app.clipboard.pasteImage` shortcut is disabled or rebound |
+| Linux / macOS | `Alt+V`, `Ctrl+Alt+V`; `Ctrl+V` when Pi's built-in `app.clipboard.pasteImage` shortcut is disabled or rebound |
+
+Pi's built-in image paste shortcut is not overridden by default. To keep the previous primary shortcut behavior without startup conflict warnings, disable the built-in binding manually in `~/.pi/agent/keybindings.json`:
+
+```json
+{
+  "app.clipboard.pasteImage": []
+}
+```
 
 ## Configuration
 
@@ -104,6 +114,7 @@ Selecting an entry queues that image for your next message.
 |----------|-------------|---------|
 | `PI_IMAGE_TOOLS_RECENT_DIRS` | Semicolon-separated directories to search for recent images | Platform defaults listed below |
 | `PI_IMAGE_TOOLS_RECENT_CACHE_DIR` | Custom cache directory for clipboard-pasted images | OS temp dir + `pi-image-tools/recent-cache` |
+| `PI_IMAGE_TOOLS_MAX_IMAGE_BYTES` | Maximum accepted image payload size before attachment, recent-cache writes, and preview conversion | `20971520` (20 MB) |
 
 Example:
 
@@ -124,12 +135,85 @@ Starter template:
 
 ```json
 {
-  "enabled": true
+  "debug": false,
+  "shortcuts": {
+    "pasteImage": ["ctrl+alt+v"],
+    "avoidBuiltinConflicts": true,
+    "suppressBuiltinConflictWarnings": true
+  }
 }
 ```
 
 See `config/config.example.json` for the same template.
 
+#### Debug logging
+
+Debug logging is disabled by default. Set `debug` to `true` to append debug events to `debug/debug.log` inside the extension directory:
+
+```json
+{
+  "debug": true,
+  "shortcuts": {
+    "pasteImage": ["ctrl+alt+v"],
+    "avoidBuiltinConflicts": true,
+    "suppressBuiltinConflictWarnings": true
+  }
+}
+```
+
+When `debug` is `false` or omitted, no debug log file is opened or written.
+
+#### Custom shortcuts
+
+Set `shortcuts.pasteImage` to choose the exact shortcuts registered by `pi-image-tools`. The value can be a single shortcut string or an array of shortcut strings. Add multiple entries when you want several key combinations to run the same paste-image action:
+
+```json
+{
+  "debug": false,
+  "shortcuts": {
+    "pasteImage": ["ctrl+alt+v", "alt+v", "ctrl+shift+v"],
+    "avoidBuiltinConflicts": true,
+    "suppressBuiltinConflictWarnings": true
+  }
+}
+```
+
+A single shortcut is also valid:
+
+```json
+{
+  "debug": false,
+  "shortcuts": {
+    "pasteImage": "ctrl+alt+v",
+    "avoidBuiltinConflicts": true,
+    "suppressBuiltinConflictWarnings": true
+  }
+}
+```
+
+Config changes are applied the next time the extension loads, so restart Pi or reload extensions after editing `config.json`.
+
+Not every terminal can transmit every key combination to Pi. Triple-modifier shortcuts such as `ctrl+shift+alt+v` may be intercepted by the OS, terminal, shell, SSH, or tmux before Pi can see them. If a configured shortcut does not work, try a simpler shortcut such as `ctrl+alt+v`, `ctrl+shift+v`, `alt+p`, `f8`, or another function key.
+
+Keep `shortcuts.avoidBuiltinConflicts` set to `true` to skip configured paste-image shortcuts that overlap any effective Pi built-in shortcut. Keep `shortcuts.suppressBuiltinConflictWarnings` set to `true` when your goal is specifically to remove Pi's startup conflict warning noise. Both options use the same safe mechanism: `pi-image-tools` does not register the overlapping shortcut, so Pi has nothing to warn about. For example, `ctrl+p` is skipped because Pi uses it for built-in model/session actions.
+
+If both options are `false`, Pi handles conflicts itself. Non-reserved built-in conflicts may be taken over by `pi-image-tools`, but Pi can still print a startup warning. Reserved built-in shortcuts cannot be stolen through the extension shortcut API; Pi skips those registrations before `pi-image-tools` can handle them. To use a reserved Pi shortcut, rebind or disable the relevant built-in action in `~/.pi/agent/keybindings.json`, then restart Pi or reload extensions.
+
+Use an empty array to disable the extension's paste-image shortcuts while keeping `/paste-image` available:
+
+```json
+{
+  "debug": false,
+  "shortcuts": {
+    "pasteImage": [],
+    "avoidBuiltinConflicts": true,
+    "suppressBuiltinConflictWarnings": true
+  }
+}
+```
+
+If `shortcuts.pasteImage` is omitted, `pi-image-tools` uses non-conflicting defaults and automatically restores the previous primary shortcut when Pi's built-in `app.clipboard.pasteImage` binding is disabled or rebound.
+
 ## Default recent-image search locations
 
 ### Windows
@@ -171,8 +255,10 @@ When you queue one or more images, the extension renders an inline preview insid
 
 Preview behavior:
 - up to **3 images** are previewed per message
-- Sixel rendering is attempted on Windows when available
+- Sixel rendering is attempted on Windows when the PowerShell `Sixel` module is already installed
+- no PowerShell modules are installed automatically at runtime
 - native TUI image rendering is used as the fallback
+- image payloads over `PI_IMAGE_TOOLS_MAX_IMAGE_BYTES` are rejected before attachment, recent-cache writes, or Sixel conversion
 - inline width fitting now preserves Sixel, Kitty, and iTerm image protocol rows instead of truncating them like plain text
 
 ### Clipboard readers
@@ -200,16 +286,21 @@ pi-image-tools/
 │   ├── index.ts                # Extension bootstrap and message flow
 │   ├── commands.ts             # /paste-image command registration
 │   ├── clipboard.ts            # Cross-platform clipboard image reading
+│   ├── config.ts               # Runtime config loading and validation
+│   ├── debug-logger.ts         # File-based debug logging
+│   ├── errors.ts               # Shared error normalization
+│   ├── image-mime.ts           # Shared image MIME and extension mapping
+│   ├── image-size.ts           # Shared image byte-size limits
 │   ├── recent-images.ts        # Recent image discovery and cache management
 │   ├── image-preview.ts        # Preview building and Sixel/native rendering
 │   ├── inline-user-preview.ts  # Inline preview patching for user messages
 │   ├── keybindings.ts          # Keyboard shortcut registration
-│   ├── temp-file.ts            # Temporary file management and cleanup
+│   ├── powershell.ts           # Shared PowerShell command runner
+│   ├── sixel-protocol.ts       # Sixel protocol normalization and render lines
+│   ├── terminal-image-width.ts # Terminal image width settings resolution
 │   └── types.ts                # Shared TypeScript types
-├── config/
-│   └── config.example.json     # Starter runtime config
-└── asset/
-    └── pi-image-tools.png      # README preview image
+└── config/
+    └── config.example.json     # Starter runtime config
 ```
 
 ## Troubleshooting

package/config/config.example.json

@@ -1,3 +1,8 @@
-{
-  "enabled": true
-}
+{
+  "debug": false,
+  "shortcuts": {
+    "pasteImage": ["ctrl+alt+v"],
+    "avoidBuiltinConflicts": true,
+    "suppressBuiltinConflictWarnings": true
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-image-tools",
-  "version": "1.0.10",
+  "version": "1.1.0",
   "description": "Image attachment and rendering extension for Pi TUI",
   "type": "module",
   "main": "./index.ts",
@@ -11,7 +11,6 @@
     "index.ts",
     "src",
     "config/config.example.json",
-    "asset",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
@@ -58,10 +57,10 @@
     ]
   },
   "peerDependencies": {
-    "@mariozechner/pi-coding-agent": "^0.68.1",
-    "@mariozechner/pi-tui": "^0.68.1"
+    "@mariozechner/pi-coding-agent": "^0.72.0",
+    "@mariozechner/pi-tui": "^0.72.0"
   },
   "optionalDependencies": {
-    "@mariozechner/clipboard": "^0.3.2"
+    "@mariozechner/clipboard": "^0.3.5"
   }
 }

package/src/clipboard.ts

@@ -1,6 +1,9 @@
 import { spawnSync } from "node:child_process";
 import { createRequire } from "node:module";
 
+import { isErrnoException } from "./errors.js";
+import { normalizeMimeType, selectPreferredImageMimeType, SUPPORTED_IMAGE_MIME_TYPES } from "./image-mime.js";
+import { runPowerShellCommand } from "./powershell.js";
 import type { ClipboardImage, ClipboardModule } from "./types.js";
 
 const require = createRequire(import.meta.url);
@@ -8,14 +11,6 @@ const require = createRequire(import.meta.url);
 const LIST_TYPES_TIMEOUT_MS = 1000;
 const READ_TIMEOUT_MS = 5000;
 const MAX_BUFFER_BYTES = 50 * 1024 * 1024;
-const SUPPORTED_IMAGE_MIME_TYPES = [
-  "image/png",
-  "image/jpeg",
-  "image/webp",
-  "image/gif",
-  "image/bmp",
-] as const;
-
 let cachedClipboardModule: ClipboardModule | null | undefined;
 
 interface CommandResult {
@@ -29,10 +24,6 @@ interface ClipboardReadResult {
   image: ClipboardImage | null;
 }
 
-function isErrnoException(error: Error): error is NodeJS.ErrnoException {
-  return "code" in error;
-}
-
 function hasGraphicalSession(platform: NodeJS.Platform, environment: NodeJS.ProcessEnv): boolean {
   return platform !== "linux" || Boolean(environment.DISPLAY || environment.WAYLAND_DISPLAY);
 }
@@ -41,27 +32,6 @@ function isWaylandSession(environment: NodeJS.ProcessEnv): boolean {
   return Boolean(environment.WAYLAND_DISPLAY) || environment.XDG_SESSION_TYPE === "wayland";
 }
 
-function normalizeMimeType(mimeType: string): string {
-  return mimeType.split(";")[0]?.trim().toLowerCase() ?? mimeType.toLowerCase();
-}
-
-function selectPreferredImageMimeType(mimeTypes: readonly string[]): string | null {
-  const normalized = mimeTypes
-    .map((mimeType) => mimeType.trim())
-    .filter((mimeType) => mimeType.length > 0)
-    .map((mimeType) => ({ raw: mimeType, normalized: normalizeMimeType(mimeType) }));
-
-  for (const preferredMimeType of SUPPORTED_IMAGE_MIME_TYPES) {
-    const match = normalized.find((mimeType) => mimeType.normalized === preferredMimeType);
-    if (match) {
-      return match.raw;
-    }
-  }
-
-  const firstImage = normalized.find((mimeType) => mimeType.normalized.startsWith("image/"));
-  return firstImage?.raw ?? null;
-}
-
 function loadClipboardModule(
   platform: NodeJS.Platform = process.platform,
   environment: NodeJS.ProcessEnv = process.env,
@@ -141,10 +111,6 @@ function runCommand(
   };
 }
 
-function encodePowerShell(script: string): string {
-  return Buffer.from(script, "utf16le").toString("base64");
-}
-
 function readClipboardImageViaPowerShell(): ClipboardReadResult {
   const script = `
 $ErrorActionPreference = 'Stop'
@@ -170,33 +136,18 @@ try {
 }
 `;
 
-  const result = spawnSync(
-    "powershell.exe",
-    [
-      "-NoProfile",
-      "-NonInteractive",
-      "-ExecutionPolicy",
-      "Bypass",
-      "-STA",
-      "-EncodedCommand",
-      encodePowerShell(script),
-    ],
-    {
-      encoding: "utf8",
-      timeout: READ_TIMEOUT_MS,
-      maxBuffer: MAX_BUFFER_BYTES,
-      windowsHide: true,
-    },
-  );
+  const result = runPowerShellCommand(script, {
+    encoded: true,
+    sta: true,
+    timeout: READ_TIMEOUT_MS,
+    maxBuffer: MAX_BUFFER_BYTES,
+  });
 
-  if (result.error) {
-    return {
-      available: !isErrnoException(result.error) || result.error.code !== "ENOENT",
-      image: null,
-    };
+  if (result.missingCommand) {
+    return { available: false, image: null };
   }
 
-  if (result.status !== 0) {
+  if (!result.ok) {
     return { available: true, image: null };
   }
 

package/src/config.ts

@@ -0,0 +1,146 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import type { KeyId } from "@mariozechner/pi-tui";
+
+const CONFIG_FILE_NAME = "config.json";
+const EXTENSION_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+export interface ImageToolsShortcutConfig {
+  avoidBuiltinConflicts: boolean;
+  suppressBuiltinConflictWarnings: boolean;
+  pasteImage?: KeyId[];
+}
+
+export interface ImageToolsConfig {
+  debug: boolean;
+  shortcuts: ImageToolsShortcutConfig;
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function getExtensionRoot(): string {
+  return EXTENSION_ROOT;
+}
+
+export function getConfigPath(): string {
+  return join(getExtensionRoot(), CONFIG_FILE_NAME);
+}
+
+function formatConfigPath(path: string, property: string): string {
+  return `${path}${property.length > 0 ? ` property \"${property}\"` : ""}`;
+}
+
+function parseBoolean(value: unknown, property: string, path: string): boolean {
+  if (value === undefined) {
+    return false;
+  }
+
+  if (typeof value !== "boolean") {
+    throw new Error(`Invalid pi-image-tools config at ${formatConfigPath(path, property)}: expected a boolean.`);
+  }
+
+  return value;
+}
+
+function normalizeShortcut(value: unknown, property: string, path: string): KeyId {
+  if (typeof value !== "string") {
+    throw new Error(`Invalid pi-image-tools config at ${formatConfigPath(path, property)}: expected a string shortcut.`);
+  }
+
+  const shortcut = value.trim();
+  if (shortcut.length === 0) {
+    throw new Error(`Invalid pi-image-tools config at ${formatConfigPath(path, property)}: shortcut cannot be empty.`);
+  }
+
+  return shortcut as KeyId;
+}
+
+function parseShortcutList(value: unknown, property: string, path: string): KeyId[] | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+
+  const rawShortcuts = Array.isArray(value) ? value : [value];
+  const shortcuts: KeyId[] = [];
+  const seen = new Set<string>();
+
+  for (const [index, rawShortcut] of rawShortcuts.entries()) {
+    const shortcut = normalizeShortcut(rawShortcut, `${property}[${index}]`, path);
+    const normalized = shortcut.toLowerCase();
+    if (seen.has(normalized)) {
+      continue;
+    }
+
+    seen.add(normalized);
+    shortcuts.push(shortcut);
+  }
+
+  return shortcuts;
+}
+
+function parseShortcutConfig(value: unknown, path: string): ImageToolsShortcutConfig {
+  if (value === undefined) {
+    return {
+      avoidBuiltinConflicts: false,
+      suppressBuiltinConflictWarnings: false,
+    };
+  }
+
+  if (!isRecord(value)) {
+    throw new Error(`Invalid pi-image-tools config at ${formatConfigPath(path, "shortcuts")}: expected an object.`);
+  }
+
+  const avoidBuiltinConflicts = parseBoolean(
+    value.avoidBuiltinConflicts,
+    "shortcuts.avoidBuiltinConflicts",
+    path,
+  );
+  const suppressBuiltinConflictWarnings = parseBoolean(
+    value.suppressBuiltinConflictWarnings,
+    "shortcuts.suppressBuiltinConflictWarnings",
+    path,
+  );
+  const pasteImage = parseShortcutList(value.pasteImage, "shortcuts.pasteImage", path);
+
+  return pasteImage === undefined
+    ? { avoidBuiltinConflicts, suppressBuiltinConflictWarnings }
+    : { avoidBuiltinConflicts, suppressBuiltinConflictWarnings, pasteImage };
+}
+
+function parseConfig(rawConfig: unknown, path: string): ImageToolsConfig {
+  if (!isRecord(rawConfig)) {
+    throw new Error(`Invalid pi-image-tools config at ${path}: expected a JSON object.`);
+  }
+
+  return {
+    debug: parseBoolean(rawConfig.debug, "debug", path),
+    shortcuts: parseShortcutConfig(rawConfig.shortcuts, path),
+  };
+}
+
+export function loadImageToolsConfig(path = getConfigPath()): ImageToolsConfig {
+  if (!existsSync(path)) {
+    return {
+      debug: false,
+      shortcuts: {
+        avoidBuiltinConflicts: false,
+        suppressBuiltinConflictWarnings: false,
+      },
+    };
+  }
+
+  try {
+    const rawConfig = JSON.parse(readFileSync(path, "utf-8")) as unknown;
+    return parseConfig(rawConfig, path);
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      throw new Error(`Invalid pi-image-tools config at ${path}: ${error.message}`);
+    }
+
+    throw error;
+  }
+}

package/src/debug-logger.ts

@@ -0,0 +1,41 @@
+import { appendFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+
+import { getExtensionRoot, type ImageToolsConfig } from "./config.js";
+import { getErrorMessage } from "./errors.js";
+
+const DEBUG_DIRECTORY_NAME = "debug";
+const DEBUG_LOG_FILE_NAME = "debug.log";
+
+type DebugFields = Record<string, unknown>;
+
+export class DebugLogger {
+  private readonly logPath: string | undefined;
+
+  private constructor(private readonly enabled: boolean) {
+    this.logPath = enabled ? join(getExtensionRoot(), DEBUG_DIRECTORY_NAME, DEBUG_LOG_FILE_NAME) : undefined;
+  }
+
+  static create(config: ImageToolsConfig): DebugLogger {
+    return new DebugLogger(config.debug);
+  }
+
+  log(event: string, fields: DebugFields = {}): void {
+    if (!this.enabled || !this.logPath) {
+      return;
+    }
+
+    const debugDirectory = join(getExtensionRoot(), DEBUG_DIRECTORY_NAME);
+
+    try {
+      mkdirSync(debugDirectory, { recursive: true });
+      appendFileSync(
+        this.logPath,
+        `${JSON.stringify({ timestamp: new Date().toISOString(), event, ...fields })}\n`,
+        "utf-8",
+      );
+    } catch (error) {
+      throw new Error(`pi-image-tools debug logging failed at ${this.logPath}: ${getErrorMessage(error)}`);
+    }
+  }
+}

package/src/errors.ts

@@ -0,0 +1,11 @@
+export function getErrorMessage(error: unknown): string {
+  if (error instanceof Error && error.message.trim().length > 0) {
+    return error.message;
+  }
+
+  return "Unknown error";
+}
+
+export function isErrnoException(error: unknown): error is NodeJS.ErrnoException {
+  return error instanceof Error && "code" in error;
+}

package/src/image-mime.ts

@@ -0,0 +1,60 @@
+const PREFERRED_IMAGE_MIME_TYPES = [
+  "image/png",
+  "image/jpeg",
+  "image/webp",
+  "image/gif",
+  "image/bmp",
+] as const;
+
+const MIME_TYPE_TO_EXTENSION = new Map<string, string>([
+  ["image/png", "png"],
+  ["image/jpeg", "jpg"],
+  ["image/webp", "webp"],
+  ["image/gif", "gif"],
+  ["image/bmp", "bmp"],
+  ["image/tiff", "tiff"],
+]);
+
+const EXTENSION_TO_MIME_TYPE = new Map<string, string>([
+  [".png", "image/png"],
+  [".jpg", "image/jpeg"],
+  [".jpeg", "image/jpeg"],
+  [".webp", "image/webp"],
+  [".gif", "image/gif"],
+  [".bmp", "image/bmp"],
+]);
+
+export const SUPPORTED_IMAGE_MIME_TYPES: readonly string[] = PREFERRED_IMAGE_MIME_TYPES;
+
+export function normalizeMimeType(mimeType: string): string {
+  return mimeType.split(";")[0]?.trim().toLowerCase() ?? mimeType.toLowerCase();
+}
+
+export function selectPreferredImageMimeType(mimeTypes: readonly string[]): string | null {
+  const normalized = mimeTypes
+    .map((mimeType) => mimeType.trim())
+    .filter((mimeType) => mimeType.length > 0)
+    .map((mimeType) => ({ raw: mimeType, normalized: normalizeMimeType(mimeType) }));
+
+  for (const preferredMimeType of SUPPORTED_IMAGE_MIME_TYPES) {
+    const match = normalized.find((mimeType) => mimeType.normalized === preferredMimeType);
+    if (match) {
+      return match.raw;
+    }
+  }
+
+  const firstImage = normalized.find((mimeType) => mimeType.normalized.startsWith("image/"));
+  return firstImage?.raw ?? null;
+}
+
+export function mimeTypeToExtension(mimeType: string, fallbackExtension = "png"): string {
+  return MIME_TYPE_TO_EXTENSION.get(normalizeMimeType(mimeType)) ?? fallbackExtension;
+}
+
+export function extensionToMimeType(fileNameOrExtension: string): string | null {
+  const extension = fileNameOrExtension.startsWith(".")
+    ? fileNameOrExtension.toLowerCase()
+    : `.${fileNameOrExtension.toLowerCase()}`;
+
+  return EXTENSION_TO_MIME_TYPE.get(extension) ?? null;
+}