pi-image-tools 1.2.1 → 1.3.1

package/src/config.ts

@@ -18,6 +18,10 @@ export interface ImageToolsConfig {
   shortcuts: ImageToolsShortcutConfig;
 }
 
+export interface LoadImageToolsConfigOptions {
+  platform?: NodeJS.Platform;
+}
+
 export function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -34,9 +38,9 @@ function formatConfigPath(path: string, property: string): string {
   return `${path}${property.length > 0 ? ` property \"${property}\"` : ""}`;
 }
 
-function parseBoolean(value: unknown, property: string, path: string): boolean {
+function parseBoolean(value: unknown, property: string, path: string, defaultValue = false): boolean {
   if (value === undefined) {
-    return false;
+    return defaultValue;
   }
 
   if (typeof value !== "boolean") {
@@ -82,12 +86,17 @@ function parseShortcutList(value: unknown, property: string, path: string): KeyI
   return shortcuts;
 }
 
-function parseShortcutConfig(value: unknown, path: string): ImageToolsShortcutConfig {
+function getDefaultShortcutConfig(_platform: NodeJS.Platform): ImageToolsShortcutConfig {
+  return {
+    avoidBuiltinConflicts: true,
+    suppressBuiltinConflictWarnings: false,
+  };
+}
+
+function parseShortcutConfig(value: unknown, path: string, platform: NodeJS.Platform): ImageToolsShortcutConfig {
+  const defaults = getDefaultShortcutConfig(platform);
   if (value === undefined) {
-    return {
-      avoidBuiltinConflicts: false,
-      suppressBuiltinConflictWarnings: false,
-    };
+    return defaults;
   }
 
   if (!isRecord(value)) {
@@ -98,11 +107,13 @@ function parseShortcutConfig(value: unknown, path: string): ImageToolsShortcutCo
     value.avoidBuiltinConflicts,
     "shortcuts.avoidBuiltinConflicts",
     path,
+    defaults.avoidBuiltinConflicts,
   );
   const suppressBuiltinConflictWarnings = parseBoolean(
     value.suppressBuiltinConflictWarnings,
     "shortcuts.suppressBuiltinConflictWarnings",
     path,
+    defaults.suppressBuiltinConflictWarnings,
   );
   const pasteImage = parseShortcutList(value.pasteImage, "shortcuts.pasteImage", path);
 
@@ -111,31 +122,29 @@ function parseShortcutConfig(value: unknown, path: string): ImageToolsShortcutCo
     : { avoidBuiltinConflicts, suppressBuiltinConflictWarnings, pasteImage };
 }
 
-function parseConfig(rawConfig: unknown, path: string): ImageToolsConfig {
+function parseConfig(rawConfig: unknown, path: string, platform: NodeJS.Platform): 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),
+    shortcuts: parseShortcutConfig(rawConfig.shortcuts, path, platform),
   };
 }
 
-export function loadImageToolsConfig(path = getConfigPath()): ImageToolsConfig {
+export function loadImageToolsConfig(path = getConfigPath(), options: LoadImageToolsConfigOptions = {}): ImageToolsConfig {
+  const platform = options.platform ?? process.platform;
   if (!existsSync(path)) {
     return {
       debug: false,
-      shortcuts: {
-        avoidBuiltinConflicts: false,
-        suppressBuiltinConflictWarnings: false,
-      },
+      shortcuts: getDefaultShortcutConfig(platform),
     };
   }
 
   try {
     const rawConfig = JSON.parse(readFileSync(path, "utf-8")) as unknown;
-    return parseConfig(rawConfig, path);
+    return parseConfig(rawConfig, path, platform);
   } catch (error) {
     if (error instanceof SyntaxError) {
       throw new Error(`Invalid pi-image-tools config at ${path}: ${error.message}`);

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}`,
+  );
+}

package/src/index.ts

@@ -1,34 +1,89 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
-import { readClipboardImage } from "./clipboard.js";
 import { registerPasteImageCommand } from "./commands.js";
 import { loadImageToolsConfig } from "./config.js";
 import { DebugLogger } from "./debug-logger.js";
 import { getErrorMessage } from "./errors.js";
 import { assertImageWithinByteLimit } from "./image-size.js";
-import {
-  IMAGE_PREVIEW_CUSTOM_TYPE,
-  buildPreviewItems,
-  registerImagePreviewDisplay,
-  type ImagePayload,
-} from "./image-preview.js";
-import { registerInlineUserImagePreview } from "./inline-user-preview.js";
 import { registerImagePasteKeybindings } from "./keybindings.js";
-import {
-  RECENT_IMAGE_CACHE_DIR_ENV_VAR,
-  RECENT_IMAGE_ENV_VAR,
-  discoverRecentImages,
-  formatRecentImageLabel,
-  getRecentImageCacheDirectory,
-  loadRecentImage,
-  persistImageToRecentCache,
-} from "./recent-images.js";
 import type { ClipboardImage, PasteContext } from "./types.js";
 
 const IMAGE_ATTACHMENT_INDICATOR = "[󰈟 Image Attached]";
+const IMAGE_PREVIEW_CUSTOM_TYPE = "pi-image-tools-preview";
+const RECENT_IMAGE_ENV_VAR = "PI_IMAGE_TOOLS_RECENT_DIRS";
+const RECENT_IMAGE_CACHE_DIR_ENV_VAR = "PI_IMAGE_TOOLS_RECENT_CACHE_DIR";
+
+type ImagePayload = {
+  type: "image";
+  data: string;
+  mimeType: string;
+};
 
 interface PendingImage extends ImagePayload {}
 
+type ClipboardModule = typeof import("./clipboard.js");
+type ImagePreviewModule = typeof import("./image-preview.js");
+type InlineUserPreviewModule = typeof import("./inline-user-preview.js");
+type RecentImagesModule = typeof import("./recent-images.js");
+
+let clipboardModulePromise: Promise<ClipboardModule> | undefined;
+let imagePreviewModulePromise: Promise<ImagePreviewModule> | undefined;
+let inlineUserPreviewModulePromise: Promise<InlineUserPreviewModule> | undefined;
+let recentImagesModulePromise: Promise<RecentImagesModule> | undefined;
+const imagePreviewDisplayRegistrations = new WeakSet<ExtensionAPI>();
+const inlineUserPreviewRegistrations = new WeakSet<ExtensionAPI>();
+const previewRegistrationPromises = new WeakMap<ExtensionAPI, Promise<void>>();
+
+function loadClipboardModule(): Promise<ClipboardModule> {
+  clipboardModulePromise ??= import("./clipboard.js");
+  return clipboardModulePromise;
+}
+
+function loadImagePreviewModule(): Promise<ImagePreviewModule> {
+  imagePreviewModulePromise ??= import("./image-preview.js");
+  return imagePreviewModulePromise;
+}
+
+function loadInlineUserPreviewModule(): Promise<InlineUserPreviewModule> {
+  inlineUserPreviewModulePromise ??= import("./inline-user-preview.js");
+  return inlineUserPreviewModulePromise;
+}
+
+function loadRecentImagesModule(): Promise<RecentImagesModule> {
+  recentImagesModulePromise ??= import("./recent-images.js");
+  return recentImagesModulePromise;
+}
+
+async function ensureImagePreviewDisplayRegistered(
+  pi: ExtensionAPI,
+  logger: DebugLogger,
+): Promise<ImagePreviewModule> {
+  const module = await loadImagePreviewModule();
+  if (!imagePreviewDisplayRegistrations.has(pi)) {
+    imagePreviewDisplayRegistrations.add(pi);
+    module.registerImagePreviewDisplay(pi, { logger });
+  }
+  return module;
+}
+
+async function ensurePreviewRegistrations(pi: ExtensionAPI, logger: DebugLogger): Promise<void> {
+  let registrationPromise = previewRegistrationPromises.get(pi);
+  if (!registrationPromise) {
+    registrationPromise = (async () => {
+      await ensureImagePreviewDisplayRegistered(pi, logger);
+
+      if (!inlineUserPreviewRegistrations.has(pi)) {
+        const module = await loadInlineUserPreviewModule();
+        inlineUserPreviewRegistrations.add(pi);
+        module.registerInlineUserImagePreview(pi, { logger });
+      }
+    })();
+    previewRegistrationPromises.set(pi, registrationPromise);
+  }
+
+  await registrationPromise;
+}
+
 function imageToBase64(image: ClipboardImage): string {
   assertImageWithinByteLimit(image.bytes.length, "Image attachment");
   return Buffer.from(image.bytes).toString("base64");
@@ -59,6 +114,20 @@ function removeAttachmentIndicators(text: string): string {
   return withoutMarkers.replace(/\n{3,}/g, "\n\n").trim();
 }
 
+async function cacheImageForRecentPicker(ctx: PasteContext, image: ClipboardImage): Promise<void> {
+  try {
+    const { persistImageToRecentCache } = await loadRecentImagesModule();
+    persistImageToRecentCache(image);
+  } catch (error) {
+    if (ctx.hasUI) {
+      ctx.ui.notify(
+        `Image attached, but failed to cache for /paste-image recent: ${getErrorMessage(error)}`,
+        "warning",
+      );
+    }
+  }
+}
+
 function queueImageAttachment(
   ctx: PasteContext,
   pendingImages: PendingImage[],
@@ -73,16 +142,7 @@ function queueImageAttachment(
   });
 
   if (options.cacheForRecentPicker) {
-    try {
-      persistImageToRecentCache(image);
-    } catch (error) {
-      if (ctx.hasUI) {
-        ctx.ui.notify(
-          `Image attached, but failed to cache for /paste-image recent: ${getErrorMessage(error)}`,
-          "warning",
-        );
-      }
-    }
+    void cacheImageForRecentPicker(ctx, image);
   }
 
   if (!ctx.hasUI) {
@@ -93,12 +153,14 @@ function queueImageAttachment(
   ctx.ui.notify(successMessage, "info");
 }
 
-function buildRecentImageEmptyStateMessage(searchedDirectories: readonly string[]): string {
+function buildRecentImageEmptyStateMessage(
+  searchedDirectories: readonly string[],
+  cacheDirectory: string,
+): string {
   const searched =
     searchedDirectories.length > 0
       ? searchedDirectories.join("; ")
       : "No directories configured";
-  const cacheDirectory = getRecentImageCacheDirectory();
 
   return [
     `No recent images found. Searched: ${searched}`,
@@ -114,6 +176,7 @@ async function showRecentSelectionPreview(
   cwd: string,
   logger: DebugLogger,
 ): Promise<void> {
+  const { buildPreviewItems } = await ensureImagePreviewDisplayRegistered(pi, logger);
   const previewItems = await buildPreviewItems(
     [
       {
@@ -151,8 +214,15 @@ export default function imageToolsExtension(pi: ExtensionAPI): void {
     pasteImageShortcutsConfigured: config.shortcuts.pasteImage !== undefined,
   });
 
-  registerInlineUserImagePreview(pi, { logger });
-  registerImagePreviewDisplay(pi, { logger });
+  pi.on("session_start", async (_event, ctx) => {
+    try {
+      const { setActiveTerminalImageSettingsCwd } = await import("./terminal-image-width.js");
+      setActiveTerminalImageSettingsCwd(ctx.cwd);
+      await ensurePreviewRegistrations(pi, logger);
+    } catch (error) {
+      logger.log("preview.lazy_registration_failed", { error: getErrorMessage(error) });
+    }
+  });
 
   const pasteImageFromClipboard = async (ctx: PasteContext): Promise<void> => {
     if (!ctx.hasUI) {
@@ -160,6 +230,7 @@ export default function imageToolsExtension(pi: ExtensionAPI): void {
     }
 
     try {
+      const { readClipboardImage } = await loadClipboardModule();
       const image = await readClipboardImage();
       if (!image) {
         ctx.ui.notify("No image found in clipboard.", "warning");
@@ -185,9 +256,21 @@ export default function imageToolsExtension(pi: ExtensionAPI): void {
     }
 
     try {
+      const {
+        discoverRecentImages,
+        formatRecentImageLabel,
+        getRecentImageCacheDirectory,
+        loadRecentImage,
+      } = await loadRecentImagesModule();
       const discovery = discoverRecentImages();
       if (discovery.candidates.length === 0) {
-        ctx.ui.notify(buildRecentImageEmptyStateMessage(discovery.searchedDirectories), "warning");
+        ctx.ui.notify(
+          buildRecentImageEmptyStateMessage(
+            discovery.searchedDirectories,
+            getRecentImageCacheDirectory(),
+          ),
+          "warning",
+        );
         return;
       }