pi-image-tools 1.2.1 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [1.3.0] - 2026-06-01
+
+### Added
+- Added a provider registry for platform-specific clipboard readers.
+- Added macOS `pngpaste` and `osascript` clipboard fallbacks.
+- Added an inline preview queue and chat component for user image previews.
+
+### Changed
+- Deferred preview, clipboard, and recent-image module loading from the extension entrypoint.
+- Made shortcut conflict defaults platform-aware.
+- Updated Pi peer dependency ranges and the optional clipboard dependency for 0.78-compatible runtimes.
+
+### Fixed
+- Improved shell and session handling for clipboard command providers.
+
 ## [1.2.1] - 2026-05-26
 
 ### Changed

package/README.md

@@ -25,11 +25,9 @@ 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 |
-| macOS | Yes* | Yes | Clipboard paste depends on `@mariozechner/clipboard` being available |
+| 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 |
 
-\* macOS clipboard image support relies on the optional native clipboard module.
-
 ## Installation
 
 ### Extension folder
@@ -273,7 +271,9 @@ Preview behavior:
   - `xclip` in X11 sessions
   - `@mariozechner/clipboard` fallback
 - **macOS**
-  - `@mariozechner/clipboard`
+  - `pngpaste`
+  - `osascript` PNG clipboard readers
+  - `@mariozechner/clipboard` fallback
 
 If a platform-specific reader exists but no image is currently on the clipboard, the command returns a normal “No image found in clipboard” message. If no usable reader exists at all, the extension surfaces a setup-oriented error.
 

package/package.json

@@ -1,69 +1,69 @@
-{
-  "name": "pi-image-tools",
-  "version": "1.2.1",
-  "description": "Image attachment and rendering extension for Pi TUI",
-  "type": "module",
-  "main": "./index.ts",
-  "exports": {
-    ".": "./index.ts"
-  },
-  "files": [
-    "index.ts",
-    "src",
-    "config/config.example.json",
-    "README.md",
-    "CHANGELOG.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "typecheck": "npx --yes -p typescript@5.7.3 tsc -p tsconfig.json --noEmit",
-    "build": "npm run typecheck",
-    "lint": "npm run typecheck",
-    "test": "node --test",
-    "check": "npm run build && npm run test"
-  },
-  "keywords": [
-    "pi-package",
-    "pi",
-    "pi-extension",
-    "pi-coding-agent",
-    "pi-tui",
-    "coding-agent",
-    "image",
-    "image-attachment",
-    "image-preview",
-    "clipboard",
-    "preview",
-    "windows",
-    "linux",
-    "cross-platform"
-  ],
-  "author": "MasuRii",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/MasuRii/pi-image-tools.git"
-  },
-  "homepage": "https://github.com/MasuRii/pi-image-tools#readme",
-  "bugs": {
-    "url": "https://github.com/MasuRii/pi-image-tools/issues"
-  },
-  "engines": {
-    "node": ">=20"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "pi": {
-    "extensions": [
-      "./index.ts"
-    ]
-  },
-  "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.74.0 || ^0.75.0",
-    "@earendil-works/pi-tui": "^0.74.0 || ^0.75.0"
-  },
-  "optionalDependencies": {
-    "@mariozechner/clipboard": "^0.3.6"
-  }
-}
+{
+  "name": "pi-image-tools",
+  "version": "1.3.0",
+  "description": "Image attachment and rendering extension for Pi TUI",
+  "type": "module",
+  "main": "./index.ts",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "config/config.example.json",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "typecheck": "npx --yes -p typescript@5.7.3 tsc -p tsconfig.json --noEmit",
+    "build": "npm run typecheck",
+    "lint": "npm run typecheck",
+    "test": "node --test test/*.test.js test/providers/*.test.js",
+    "check": "npm run build && npm run test"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "pi-coding-agent",
+    "pi-tui",
+    "coding-agent",
+    "image",
+    "image-attachment",
+    "image-preview",
+    "clipboard",
+    "preview",
+    "windows",
+    "linux",
+    "cross-platform"
+  ],
+  "author": "MasuRii",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MasuRii/pi-image-tools.git"
+  },
+  "homepage": "https://github.com/MasuRii/pi-image-tools#readme",
+  "bugs": {
+    "url": "https://github.com/MasuRii/pi-image-tools/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "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"
+  },
+  "optionalDependencies": {
+    "@mariozechner/clipboard": "^0.3.9"
+  }
+}

package/src/clipboard.ts

@@ -1,336 +1,89 @@
-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);
-
-const LIST_TYPES_TIMEOUT_MS = 1000;
-const READ_TIMEOUT_MS = 5000;
-const MAX_BUFFER_BYTES = 50 * 1024 * 1024;
-let cachedClipboardModule: ClipboardModule | null | undefined;
-
-interface CommandResult {
-  ok: boolean;
-  stdout: Buffer;
-  missingCommand: boolean;
-}
-
-interface ClipboardReadResult {
-  available: boolean;
-  image: ClipboardImage | null;
-}
-
-export function hasGraphicalSession(platform: NodeJS.Platform, environment: NodeJS.ProcessEnv): boolean {
-  return platform !== "linux" || Boolean(environment.DISPLAY || environment.WAYLAND_DISPLAY);
-}
-
-function isWaylandSession(environment: NodeJS.ProcessEnv): boolean {
-  return Boolean(environment.WAYLAND_DISPLAY) || environment.XDG_SESSION_TYPE === "wayland";
-}
-
-function loadClipboardModule(
-  platform: NodeJS.Platform = process.platform,
-  environment: NodeJS.ProcessEnv = process.env,
-): ClipboardModule | null {
-  if (cachedClipboardModule !== undefined) {
-    return cachedClipboardModule;
-  }
-
-  if (environment.TERMUX_VERSION || !hasGraphicalSession(platform, environment)) {
-    cachedClipboardModule = null;
-    return cachedClipboardModule;
-  }
-
-  try {
-    cachedClipboardModule = require("@mariozechner/clipboard") as ClipboardModule;
-  } catch {
-    cachedClipboardModule = null;
-  }
-
-  return cachedClipboardModule;
-}
-
-async function readClipboardImageViaNativeModule(
-  platform: NodeJS.Platform,
-  environment: NodeJS.ProcessEnv,
-): Promise<ClipboardReadResult> {
-  const clipboard = loadClipboardModule(platform, environment);
-  if (!clipboard) {
-    return { available: false, image: null };
-  }
-
-  if (!clipboard.hasImage()) {
-    return { available: true, image: null };
-  }
-
-  const imageData = await clipboard.getImageBinary();
-  if (!imageData || imageData.length === 0) {
-    return { available: true, image: null };
-  }
-
-  const bytes = imageData instanceof Uint8Array ? imageData : Uint8Array.from(imageData);
-  return {
-    available: true,
-    image: {
-      bytes,
-      mimeType: "image/png",
-    },
-  };
-}
-
-function runCommand(
-  command: string,
-  args: string[],
-  timeout: number,
-): CommandResult {
-  const result = spawnSync(command, args, {
-    timeout,
-    maxBuffer: MAX_BUFFER_BYTES,
-  });
-
-  if (result.error) {
-    return {
-      ok: false,
-      stdout: Buffer.alloc(0),
-      missingCommand: isErrnoException(result.error) && result.error.code === "ENOENT",
-    };
-  }
-
-  const stdout = Buffer.isBuffer(result.stdout)
-    ? result.stdout
-    : Buffer.from(result.stdout ?? "", typeof result.stdout === "string" ? "utf8" : undefined);
-
-  return {
-    ok: result.status === 0,
-    stdout,
-    missingCommand: false,
-  };
-}
-
-function readClipboardImageViaPowerShell(): ClipboardReadResult {
-  const script = `
-$ErrorActionPreference = 'Stop'
-Add-Type -AssemblyName System.Windows.Forms
-Add-Type -AssemblyName System.Drawing
-
-if (-not [System.Windows.Forms.Clipboard]::ContainsImage()) {
-  return
-}
-
-$image = [System.Windows.Forms.Clipboard]::GetImage()
-if ($null -eq $image) {
-  return
-}
-
-$stream = New-Object System.IO.MemoryStream
-try {
-  $image.Save($stream, [System.Drawing.Imaging.ImageFormat]::Png)
-  [System.Convert]::ToBase64String($stream.ToArray())
-} finally {
-  $stream.Dispose()
-  $image.Dispose()
-}
-`;
-
-  const result = runPowerShellCommand(script, {
-    encoded: true,
-    sta: true,
-    timeout: READ_TIMEOUT_MS,
-    maxBuffer: MAX_BUFFER_BYTES,
-  });
-
-  if (result.missingCommand) {
-    return { available: false, image: null };
-  }
-
-  if (!result.ok) {
-    return { available: true, image: null };
-  }
-
-  const base64 = result.stdout.trim();
-  if (!base64) {
-    return { available: true, image: null };
-  }
-
-  try {
-    const bytes = Buffer.from(base64, "base64");
-    if (bytes.length === 0) {
-      return { available: true, image: null };
-    }
-
-    return {
-      available: true,
-      image: {
-        bytes: new Uint8Array(bytes),
-        mimeType: "image/png",
-      },
-    };
-  } catch {
-    return { available: true, image: null };
-  }
-}
-
-function readClipboardImageViaWlPaste(): ClipboardReadResult {
-  const listTypes = runCommand("wl-paste", ["--list-types"], LIST_TYPES_TIMEOUT_MS);
-  if (listTypes.missingCommand) {
-    return { available: false, image: null };
-  }
-
-  if (!listTypes.ok) {
-    return { available: true, image: null };
-  }
-
-  const mimeTypes = listTypes.stdout
-    .toString("utf8")
-    .split(/\r?\n/)
-    .map((mimeType) => mimeType.trim())
-    .filter((mimeType) => mimeType.length > 0);
-
-  const selectedMimeType = selectPreferredImageMimeType(mimeTypes);
-  if (!selectedMimeType) {
-    return { available: true, image: null };
-  }
-
-  const imageData = runCommand(
-    "wl-paste",
-    ["--type", selectedMimeType, "--no-newline"],
-    READ_TIMEOUT_MS,
-  );
-
-  if (!imageData.ok || imageData.stdout.length === 0) {
-    return { available: true, image: null };
-  }
-
-  return {
-    available: true,
-    image: {
-      bytes: new Uint8Array(imageData.stdout),
-      mimeType: normalizeMimeType(selectedMimeType),
-    },
-  };
-}
-
-function readClipboardImageViaXclip(): ClipboardReadResult {
-  const targets = runCommand(
-    "xclip",
-    ["-selection", "clipboard", "-t", "TARGETS", "-o"],
-    LIST_TYPES_TIMEOUT_MS,
-  );
-
-  if (targets.missingCommand) {
-    return { available: false, image: null };
-  }
-
-  const advertisedMimeTypes = targets.ok
-    ? targets.stdout
-        .toString("utf8")
-        .split(/\r?\n/)
-        .map((mimeType) => mimeType.trim())
-        .filter((mimeType) => mimeType.length > 0)
-    : [];
-
-  const preferredMimeType =
-    advertisedMimeTypes.length > 0 ? selectPreferredImageMimeType(advertisedMimeTypes) : null;
-  const mimeTypesToTry = preferredMimeType
-    ? [preferredMimeType, ...SUPPORTED_IMAGE_MIME_TYPES]
-    : [...SUPPORTED_IMAGE_MIME_TYPES];
-
-  for (const mimeType of mimeTypesToTry) {
-    const imageData = runCommand(
-      "xclip",
-      ["-selection", "clipboard", "-t", mimeType, "-o"],
-      READ_TIMEOUT_MS,
-    );
-
-    if (imageData.ok && imageData.stdout.length > 0) {
-      return {
-        available: true,
-        image: {
-          bytes: new Uint8Array(imageData.stdout),
-          mimeType: normalizeMimeType(mimeType),
-        },
-      };
-    }
-  }
-
-  return { available: true, image: null };
-}
-
-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. 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;
-}): 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 readerResults: ClipboardReadResult[] = [];
-
-  const recordResult = (result: ClipboardReadResult): ClipboardImage | null => {
-    readerResults.push(result);
-    return result.image;
-  };
-
-  if (platform === "win32") {
-    const nativeImage = recordResult(await readClipboardImageViaNativeModule(platform, environment));
-    if (nativeImage) {
-      return nativeImage;
-    }
-
-    const powerShellImage = recordResult(readClipboardImageViaPowerShell());
-    if (powerShellImage) {
-      return powerShellImage;
-    }
-  } else if (platform === "linux") {
-    const sessionReaders = isWaylandSession(environment)
-      ? [readClipboardImageViaWlPaste, readClipboardImageViaXclip]
-      : [readClipboardImageViaXclip, readClipboardImageViaWlPaste];
-
-    for (const reader of sessionReaders) {
-      const image = recordResult(reader());
-      if (image) {
-        return image;
-      }
-    }
-
-    const nativeImage = recordResult(await readClipboardImageViaNativeModule(platform, environment));
-    if (nativeImage) {
-      return nativeImage;
-    }
-  } else {
-    const nativeImage = recordResult(await readClipboardImageViaNativeModule(platform, environment));
-    if (nativeImage) {
-      return nativeImage;
-    }
-  }
-
-  if (readerResults.some((result) => result.available)) {
-    return null;
-  }
-
-  throw new Error(getUnavailableReaderMessage(platform));
-}
+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));
+}