@prjct.app/pi-clipboard 0.1.1 → 0.1.4

package/CHANGELOG.md

@@ -1,5 +1,19 @@
+## [0.1.4](https://github.com/prjct-app/pi-clipboard/compare/v0.1.3...v0.1.4) (2026-09-10)
+
+### Bug Fixes
+
+* delete previewed clipboard temp files on session shutdown ([a64a2b4](https://github.com/prjct-app/pi-clipboard/commit/a64a2b446565fc7867395186097a63b62779e3f4))
+* render clipboard previews with Pi's native image components ([312295b](https://github.com/prjct-app/pi-clipboard/commit/312295b422d2c29bf5708be88c3254cb4bd17e45))
+
 # Changelog
 
+## 0.1.3
+
+- Clarify the package description and add focused discovery keywords.
+- Declare the cover image for the official Pi package gallery.
+
+- Align repository, documentation, and cover URLs with the npm package name.
+
 ## 0.1.1
 
 - Add a dedicated cover to the GitHub and npm README.

package/CONTRIBUTING.md

@@ -12,3 +12,7 @@
 ## Package documentation
 
 Follow [docs/package.md](docs/package.md) and its versioned official references. Keep README examples consistent with registered commands, distinguish tested behavior from unverified compatibility, and verify `npm run check:package` before release.
+
+## Releases
+
+Merging a releasable change into `main` automatically publishes to npm. Use conventional commit messages and read [Automatic releases](docs/releases.md) before merging. The workflow manages versions and authenticates with npm through OIDC.

package/README.md

@@ -1,8 +1,8 @@
 # pi-clipboard
 
-[![pi-clipboard — extension for PI Agent](https://raw.githubusercontent.com/prjct-app/pi-image-preview/main/docs/cover.png)](https://pi.dev)
+[![pi-clipboard — extension for PI Agent](https://raw.githubusercontent.com/prjct-app/pi-clipboard/main/docs/cover.png)](https://pi.dev)
 
-Preview pasted images above the native Pi editor.
+Preview pasted images in PI Agent before sending them, with inline thumbnails and a compact attachment gallery.
 
 `@prjct.app/pi-clipboard` · Clipboard image previews; one extension.
 
@@ -24,9 +24,9 @@ For project-only installation, add `-l`: `pi install -l npm:@prjct.app/pi-clipbo
 2. Paste an image using Pi's native clipboard flow.
 3. Inspect the preview above the editor, then submit your message normally.
 
-Previews appear automatically; there is no slash command to enable them. Removing an attachment path from the editor removes its preview. Multiple images form a gallery.
+Previews appear automatically; there is no slash command to enable them. Removing an attachment path from the editor removes its preview. Each attachment renders as its own preview.
 
-Only Pi-created temporary clipboard attachments are eligible. Arbitrary image paths do not produce previews. Supported filenames end in PNG, JPEG, WebP, or GIF; individual files over 50 MiB and symbolic links are rejected. Inline thumbnails depend on Pi's terminal image capabilities; other terminals show text cards. The extension itself makes no network requests. Submitting an image still follows Pi's normal model-provider attachment flow.
+Only Pi-created temporary clipboard attachments are eligible. Arbitrary image paths do not produce previews. Supported filenames end in PNG, JPEG, WebP, or GIF; individual files over 50 MiB and symbolic links are rejected. Clipboard images stay on disk as the temporary files Pi created; the files this session previewed are deleted when the Pi session ends. Previews render through Pi's native terminal image support; terminals without it show Pi's native `[Image: ...]` text fallback. The extension itself makes no network requests. Submitting an image still follows Pi's normal model-provider attachment flow.
 
 
 ## Manage the package
@@ -41,17 +41,17 @@ pi remove npm:@prjct.app/pi-clipboard
 
 Use `pi config` to enable or disable individual resources. Use `pi config -l` for project settings and add `-l` to removal when you installed locally.
 
-To pin version 0.1.1, use `pi install npm:@prjct.app/pi-clipboard@0.1.1`. Pi skips pinned npm versions during package updates. For a Git installation, update or remove using the same `git:github.com/prjct-app/pi-image-preview` source instead of the npm source.
+To pin version 0.1.3, use `pi install npm:@prjct.app/pi-clipboard@0.1.3`. Pi skips pinned npm versions during package updates. For a Git installation, update or remove using the same `git:github.com/prjct-app/pi-clipboard` source instead of the npm source.
 
 When switching from GitHub to npm, remove the Git installation first, then install the npm package and restart Pi.
 
 ## Troubleshooting
 
-If no preview appears, confirm you are in interactive TUI mode and pasted through Pi. Text cards are the expected fallback when inline images are unavailable.
+If no preview appears, confirm you are in interactive TUI mode and pasted through Pi. The `[Image: ...]` text line is the expected fallback when inline images are unavailable.
 
 ## Package and API documentation
 
-Uses `session_start`, `session_shutdown`, `ctx.ui.getEditorText()`, `ctx.ui.setWidget()`, and Pi TUI image components. It retains the native editor and attachment submission flow.
+Uses `session_start`, `session_shutdown`, `ctx.ui.getEditorText()`, `ctx.ui.setWidget()`, and Pi TUI `Image`/`Container` components. Kitty placements receive PNG payloads through Pi's native `convertToPng`. Clipboard files previewed by the session are deleted on `session_shutdown` after revalidating that they are still Pi-owned temporary files. It retains the native editor and attachment submission flow.
 
 See [Package structure and compatibility](docs/package.md) for the manifest, dependency policy, shipped resources, and official references. This package follows the [official Pi package guide](https://github.com/earendil-works/pi/blob/v0.85.1/packages/coding-agent/docs/packages.md) and [extension API guide](https://github.com/earendil-works/pi/blob/v0.85.1/packages/coding-agent/docs/extensions.md) for the tested version.
 

package/docs/package.md

@@ -4,7 +4,7 @@
 
 - npm name: `@prjct.app/pi-clipboard`.
 - Initial version: `0.1.0`.
-- Source repository: [prjct-app/pi-image-preview](https://github.com/prjct-app/pi-image-preview).
+- Source repository: [prjct-app/pi-clipboard](https://github.com/prjct-app/pi-clipboard).
 - Tested host: Pi `0.85.1`; Node.js `22.19+`.
 
 The npm name and repository name may differ. Repository URLs remain unchanged. Existing runtime command names, event names, persisted entry types, and settings keys are unchanged by the package rename.
@@ -35,7 +35,7 @@ Third-party runtime dependencies belong in `dependencies`. Companion extensions
 
 ## Public interfaces
 
-Uses `session_start`, `session_shutdown`, `ctx.ui.getEditorText()`, `ctx.ui.setWidget()`, and Pi TUI image components. It retains the native editor and attachment submission flow.
+Uses `session_start`, `session_shutdown`, `ctx.ui.getEditorText()`, `ctx.ui.setWidget()`, and Pi TUI `Image`/`Container` components. Kitty placements receive PNG payloads through Pi's native `convertToPng`. Clipboard files previewed by the session are deleted on `session_shutdown` after revalidating that they are still Pi-owned temporary files. It retains the native editor and attachment submission flow.
 
 ## Published contents
 
@@ -52,3 +52,7 @@ These links are pinned to the tested Pi version rather than the moving main bran
 - [TUI: components, rendering, terminal widths, and image support](https://github.com/earendil-works/pi/blob/v0.85.1/packages/coding-agent/docs/tui.md).
 
 The installed `@earendil-works/pi-coding-agent@0.85.1` package ships the same guides under `docs/`. The [current official guide](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/packages.md) may describe changes beyond this tested baseline.
+
+## Discovery metadata
+
+The `pi-package` keyword identifies this package for the official Pi gallery. Focused keywords describe its actual features. The `pi.image` field points to its public cover, following the [official gallery metadata format](https://github.com/earendil-works/pi/blob/v0.85.1/packages/coding-agent/docs/packages.md#gallery-metadata).

package/docs/releases.md

@@ -0,0 +1,29 @@
+# Automatic releases
+
+Merging a releasable change into `main` starts the **Release** workflow. It checks TypeScript, runs the tests, and checks the package contents before publishing.
+
+The workflow uses semantic-release to calculate the version, update `package.json`, `package-lock.json` and `CHANGELOG.md`, create a `vX.Y.Z` tag, publish to npm, and create a GitHub release. Release-tool dependencies are locked separately under `.github/release/` and are not installed with the extension.
+
+## Commit messages
+
+- `fix:` and `perf:` publish a patch version.
+- `feat:` publishes a minor version.
+- A `BREAKING CHANGE:` footer or a conventional `!` marker publishes a major version.
+- `docs:`, `refactor:`, `build:`, `ci(release):`, and `chore(deps):` publish a patch version.
+- Other changes, such as tests alone, do not publish a version.
+
+Use these prefixes on commits. When squash merging, use a conventional prefix in the pull request title. Let the workflow manage release versions instead of editing the version by hand.
+
+## Authentication
+
+npm trusts this repository's `.github/workflows/release.yml` through GitHub Actions OIDC. No npm token or interactive one-time password is needed for each release. The workflow is restricted to `main`; it uses GitHub's short-lived repository token to write the version commit, tag, and release. Private repositories do not produce npm provenance attestations.
+
+The corresponding npm trusted publisher must use organization `prjct-app`, this repository's name, workflow filename `release.yml`, no environment name, and permission to publish directly with `npm publish`.
+
+## Preview and recovery
+
+Run **Release** from the Actions tab on `main` with `dry_run` enabled to preview the next version and release notes. No version commit, tag, npm publication, or GitHub release is created by a dry run.
+
+Runs are serialized and an outdated checkout is skipped. Never cancel a run during publication. If a run fails, inspect its logs and the existing npm version and GitHub tag before retrying: publication is not a transaction across both services. Do not delete a published version or move an existing release tag to recover.
+
+References: [semantic-release](https://semantic-release.gitbook.io/semantic-release/), [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/).

package/package.json

@@ -1,20 +1,27 @@
 {
   "name": "@prjct.app/pi-clipboard",
-  "version": "0.1.1",
-  "description": "Preview pasted images above the native Pi editor.",
+  "version": "0.1.4",
+  "description": "Preview pasted images in PI Agent before sending them, with inline thumbnails and a compact attachment gallery.",
   "type": "module",
   "keywords": [
     "pi-package",
     "pi",
+    "pi-agent",
+    "pi-coding-agent",
+    "pi-extension",
+    "ai-coding",
+    "developer-tools",
     "clipboard",
-    "image",
-    "preview",
-    "terminal"
+    "image-preview",
+    "screenshots",
+    "terminal",
+    "tui"
   ],
   "pi": {
     "extensions": [
       "./index.ts"
-    ]
+    ],
+    "image": "https://raw.githubusercontent.com/prjct-app/pi-clipboard/main/docs/cover.png"
   },
   "scripts": {
     "check": "tsc --noEmit",
@@ -38,11 +45,11 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/prjct-app/pi-image-preview.git"
+    "url": "git+https://github.com/prjct-app/pi-clipboard.git"
   },
-  "homepage": "https://github.com/prjct-app/pi-image-preview#readme",
+  "homepage": "https://github.com/prjct-app/pi-clipboard#readme",
   "bugs": {
-    "url": "https://github.com/prjct-app/pi-image-preview/issues"
+    "url": "https://github.com/prjct-app/pi-clipboard/issues"
   },
   "publishConfig": {
     "access": "public"
@@ -54,6 +61,7 @@
     "LICENSE",
     "CONTRIBUTING.md",
     "CHANGELOG.md",
-    "docs/package.md"
+    "docs/package.md",
+    "docs/releases.md"
   ]
 }

package/src/index.ts

@@ -1,29 +1,24 @@
 import { constants } from "node:fs";
-import { lstat, open } from "node:fs/promises";
+import { lstat, open, unlink } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { basename, dirname, extname, resolve } from "node:path";
 
 import {
   convertToPng,
-  resizeImage,
   type ExtensionAPI,
   type ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
 import {
+  Container,
   getCapabilities,
   getImageDimensions,
-  imageFallback,
   Image,
-  truncateToWidth,
-  visibleWidth,
+  imageFallback,
+  Text,
   type Component,
   type ImageDimensions,
-  type TUI,
 } from "@earendil-works/pi-tui";
 
-import { decodePng, encodePng, type RgbaImage } from "./png.ts";
-import { blit, createImage, fillRoundedRect, fitWithin, strokeRoundedRect, type Rgba } from "./raster.ts";
-
 const CLIPBOARD_IMAGE_NAME_SOURCE = "pi-clipboard-[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\\.(?:png|jpe?g|webp|gif)";
 const CLIPBOARD_IMAGE_FILENAME = new RegExp(CLIPBOARD_IMAGE_NAME_SOURCE, "gi");
 const CLIPBOARD_IMAGE_BASENAME = new RegExp(`^${CLIPBOARD_IMAGE_NAME_SOURCE}$`, "i");
@@ -38,39 +33,16 @@ const IMAGE_MIME_TYPES: Record<string, string> = {
 const WIDGET_KEY = "pi-image-preview";
 const DEFAULT_POLL_INTERVAL_MS = 150;
 const MAX_PREVIEW_FILE_BYTES = 50 * 1024 * 1024;
-const CARD_WIDTH_CELLS = 14;
-const FALLBACK_CARD_WIDTH_CELLS = 28;
-const CARD_GAP_CELLS = 1;
-const MAX_CARDS_PER_ROW = 6;
-const CARD_WIDTH_PX = 160;
-const CARD_HEIGHT_PX = 112;
-const CARD_GAP_PX = 8;
-const THUMBNAIL_INSET_PX = 8;
-const THUMBNAIL_WIDTH_PX = CARD_WIDTH_PX - THUMBNAIL_INSET_PX * 2;
-const THUMBNAIL_HEIGHT_PX = CARD_HEIGHT_PX - THUMBNAIL_INSET_PX * 2;
-const CARD_RADIUS_PX = 16;
-const CARD_BORDER_PX = 2;
-const THUMBNAIL_RADIUS_PX = 12;
-const CARD_FILL: Rgba = [0x11, 0x18, 0x27, Math.round(0.92 * 255)];
-const CARD_BORDER: Rgba = [0x9c, 0xa3, 0xaf, 255];
+const PREVIEW_MAX_WIDTH_CELLS = 60;
+const PREVIEW_MAX_HEIGHT_CELLS = 12;
 
 interface PreviewSource {
   filePath: string;
-  data: Buffer;
+  base64: string;
   mimeType: string;
   dimensions: ImageDimensions;
-}
-
-interface GalleryLayout {
-  columns: number;
-  rows: number;
-  displayWidth: number;
-  displayHeight: number;
-}
-
-interface RenderedGallery {
-  signature: string;
-  image: Image;
+  /** PNG variant for Kitty placements (f=100 only decodes PNG). Undefined while unconverted. */
+  kittyBase64?: string;
 }
 
 interface Scheduler {
@@ -122,11 +94,12 @@ async function readPreviewSource(filePath: string): Promise<PreviewSource | unde
       ) return undefined;
 
       const data = await handle.readFile();
+      const base64 = data.toString("base64");
       return {
         filePath,
-        data,
+        base64,
         mimeType,
-        dimensions: getImageDimensions(data.toString("base64"), mimeType) ?? { widthPx: 800, heightPx: 600 },
+        dimensions: getImageDimensions(base64, mimeType) ?? { widthPx: 800, heightPx: 600 },
       };
     } finally {
       await handle.close();
@@ -136,161 +109,99 @@ async function readPreviewSource(filePath: string): Promise<PreviewSource | unde
   }
 }
 
-function galleryLayout(width: number, count: number): GalleryLayout {
-  const available = Math.max(1, width);
-  const columns = Math.min(
-    count,
-    MAX_CARDS_PER_ROW,
-    Math.max(1, Math.floor((available + CARD_GAP_CELLS) / (CARD_WIDTH_CELLS + CARD_GAP_CELLS))),
-  );
-  const rows = Math.ceil(count / columns);
-  return {
-    columns,
-    rows,
-    displayWidth: Math.min(available, columns * CARD_WIDTH_CELLS + (columns - 1) * CARD_GAP_CELLS),
-    displayHeight: rows * 7 + Math.max(0, rows - 1),
-  };
-}
-
-function padLine(text: string, width: number): string {
-  const truncated = truncateToWidth(text, width);
-  return truncated + " ".repeat(Math.max(0, width - visibleWidth(truncated)));
-}
-
-async function thumbnailPixels(source: PreviewSource): Promise<RgbaImage | undefined> {
-  let png: Uint8Array | undefined;
+/**
+ * Delete a clipboard image previously previewed by this session. Revalidates
+ * the same containment rules used for reads before unlinking, so only real
+ * Pi-owned temporary clipboard files are removed; anything else stays put.
+ */
+async function deleteClipboardImage(filePath: string): Promise<void> {
+  if (dirname(resolve(filePath)) !== resolve(tmpdir())) return;
+  if (!CLIPBOARD_IMAGE_BASENAME.test(basename(filePath))) return;
   try {
-    const resized = await resizeImage(source.data, source.mimeType, {
-      maxWidth: THUMBNAIL_WIDTH_PX,
-      maxHeight: THUMBNAIL_HEIGHT_PX,
-    });
-    const converted = resized ? await convertToPng(resized.data, resized.mimeType) : null;
-    if (converted) png = Buffer.from(converted.data, "base64");
+    const info = await lstat(filePath);
+    if (!info.isFile() || info.isSymbolicLink()) return;
+    await unlink(filePath);
   } catch {
-    png = undefined;
+    // Already removed or unreadable; nothing to clean up.
   }
-  if (!png && source.mimeType === "image/png") png = source.data;
-  const decoded = png ? decodePng(png) : null;
-  return decoded ? fitWithin(decoded, THUMBNAIL_WIDTH_PX, THUMBNAIL_HEIGHT_PX) : undefined;
 }
 
-async function roundedCard(source: PreviewSource): Promise<RgbaImage> {
-  const card = createImage(CARD_WIDTH_PX, CARD_HEIGHT_PX);
-  const outline = { x: 0, y: 0, width: CARD_WIDTH_PX, height: CARD_HEIGHT_PX };
-  fillRoundedRect(card, {
-    x: CARD_BORDER_PX / 2,
-    y: CARD_BORDER_PX / 2,
-    width: CARD_WIDTH_PX - CARD_BORDER_PX,
-    height: CARD_HEIGHT_PX - CARD_BORDER_PX,
-  }, CARD_RADIUS_PX - CARD_BORDER_PX / 2, CARD_FILL);
-  strokeRoundedRect(card, outline, CARD_RADIUS_PX, CARD_BORDER_PX, CARD_BORDER);
-
-  const thumbnail = await thumbnailPixels(source);
-  if (thumbnail) {
-    const box = { x: THUMBNAIL_INSET_PX, y: THUMBNAIL_INSET_PX, width: THUMBNAIL_WIDTH_PX, height: THUMBNAIL_HEIGHT_PX };
-    const left = box.x + Math.floor((box.width - thumbnail.width) / 2);
-    const top = box.y + Math.floor((box.height - thumbnail.height) / 2);
-    blit(card, thumbnail, left, top, { rect: box, radius: THUMBNAIL_RADIUS_PX });
+/**
+ * Kitty graphics placements (f=100) only decode PNG, so non-PNG sources need a
+ * PNG variant. Conversion uses Pi's native `convertToPng` (bundled WASM, no
+ * external tools) and runs once per source, off the render path.
+ */
+async function prepareKittyVariant(source: PreviewSource): Promise<void> {
+  if (source.mimeType === "image/png") {
+    source.kittyBase64 = source.base64;
+    return;
+  }
+  try {
+    const converted = await convertToPng(source.base64, source.mimeType);
+    source.kittyBase64 = converted?.data;
+  } catch {
+    source.kittyBase64 = undefined;
   }
-  return card;
-}
-
-async function buildGallery(sources: PreviewSource[], layout: GalleryLayout): Promise<Buffer> {
-  const cards = await Promise.all(sources.map(roundedCard));
-  const width = layout.columns * CARD_WIDTH_PX + (layout.columns - 1) * CARD_GAP_PX;
-  const height = layout.rows * CARD_HEIGHT_PX + (layout.rows - 1) * CARD_GAP_PX;
-  const gallery = createImage(width, height);
-  cards.forEach((card, index) => {
-    blit(
-      gallery,
-      card,
-      (index % layout.columns) * (CARD_WIDTH_PX + CARD_GAP_PX),
-      Math.floor(index / layout.columns) * (CARD_HEIGHT_PX + CARD_GAP_PX),
-    );
-  });
-  return encodePng(gallery);
 }
 
-class ImagePreviewGallery implements Component {
-  private gallery?: RenderedGallery;
-  private pendingSignature?: string;
-  private buildGeneration = 0;
+/**
+ * Renders one native Pi `Image` per clipboard attachment inside a `Container`.
+ * The `Image` component owns Kitty/iTerm2 placement and the `[Image: ...]`
+ * text fallback for terminals without inline-image support.
+ */
+class ClipboardPreviewGallery implements Component {
+  private container?: Container;
+  private containerKey?: string;
 
   constructor(
-    private readonly tui: TUI,
     private readonly sources: PreviewSource[],
     private readonly fallbackColor: (text: string) => string,
   ) {}
 
-  private renderFallback(width: number): string[] {
-    const innerWidth = Math.max(1, Math.min(FALLBACK_CARD_WIDTH_CELLS - 2, width - 2));
-    const cardWidth = innerWidth + 2;
-    const columns = Math.max(1, Math.floor((width + CARD_GAP_CELLS) / (cardWidth + CARD_GAP_CELLS)));
-    const lines: string[] = [];
-
-    for (let start = 0; start < this.sources.length; start += columns) {
-      const row = this.sources.slice(start, start + columns);
-      const cards = row.map((source) => {
-        const label = imageFallback(source.mimeType, source.dimensions);
-        return [
-          `╭${"─".repeat(innerWidth)}╮`,
-          `│${padLine(this.fallbackColor(label), innerWidth)}│`,
-          `╰${"─".repeat(innerWidth)}╯`,
-        ];
-      });
-      for (let line = 0; line < 3; line += 1) {
-        lines.push(cards.map((card) => card[line]).join(" "));
+  private build(): Container {
+    const kitty = getCapabilities().images === "kitty";
+    const container = new Container();
+    for (const source of this.sources) {
+      if (kitty && !source.kittyBase64) {
+        const label = imageFallback(source.mimeType, source.dimensions, source.filePath);
+        container.addChild(new Text(this.fallbackColor(label), 1, 0));
+        continue;
       }
+      container.addChild(new Image(
+        kitty ? source.kittyBase64! : source.base64,
+        kitty ? "image/png" : source.mimeType,
+        { fallbackColor: this.fallbackColor },
+        {
+          maxWidthCells: PREVIEW_MAX_WIDTH_CELLS,
+          maxHeightCells: PREVIEW_MAX_HEIGHT_CELLS,
+          filename: source.filePath,
+        },
+        source.dimensions,
+      ));
     }
-
-    return lines;
-  }
-
-  private requestGallery(layout: GalleryLayout, signature: string): void {
-    if (this.pendingSignature === signature) return;
-    this.pendingSignature = signature;
-    const generation = ++this.buildGeneration;
-
-    void buildGallery(this.sources, layout).then((data) => {
-      if (generation !== this.buildGeneration) return;
-      this.gallery = {
-        signature,
-        image: new Image(data.toString("base64"), "image/png", {
-          fallbackColor: this.fallbackColor,
-        }, {
-          maxWidthCells: layout.displayWidth,
-          maxHeightCells: layout.displayHeight,
-        }),
-      };
-      this.pendingSignature = undefined;
-      this.tui.requestRender();
-    }).catch(() => {
-      if (generation !== this.buildGeneration) return;
-      this.pendingSignature = undefined;
-      this.tui.requestRender();
-    });
+    return container;
   }
 
   render(width: number): string[] {
     if (this.sources.length === 0) return [];
-    if (!getCapabilities().images) return this.renderFallback(width);
-
-    const layout = galleryLayout(width, this.sources.length);
-    const signature = `${this.sources.map((source) => source.filePath).join("\0")}\0${layout.columns}`;
-    if (this.gallery?.signature === signature) return this.gallery.image.render(width);
-
-    this.requestGallery(layout, signature);
-    return this.renderFallback(width);
+    const key = [
+      getCapabilities().images ?? "none",
+      ...this.sources.map((source) => `${source.filePath} ${source.kittyBase64 ? "png" : "raw"}`),
+    ].join("\0");
+    if (!this.container || this.containerKey !== key) {
+      this.container = this.build();
+      this.containerKey = key;
+    }
+    return this.container.render(Math.max(1, width));
   }
 
   invalidate(): void {
-    this.gallery?.image.invalidate();
+    this.container?.invalidate();
   }
 
   dispose(): void {
-    this.buildGeneration += 1;
-    this.gallery?.image.invalidate();
-    this.gallery = undefined;
+    this.container = undefined;
+    this.containerKey = undefined;
   }
 }
 
@@ -301,8 +212,8 @@ function renderPreviewWidget(ctx: ExtensionContext, sources: PreviewSource[]): v
   }
 
   const snapshot = [...sources];
-  ctx.ui.setWidget(WIDGET_KEY, (tui, theme) =>
-    new ImagePreviewGallery(tui, snapshot, (text) => theme.fg("muted", text)));
+  ctx.ui.setWidget(WIDGET_KEY, (_tui, theme) =>
+    new ClipboardPreviewGallery(snapshot, (text) => theme.fg("muted", text)));
 }
 
 export function createImagePreviewExtension(options: ImagePreviewOptions = {}) {
@@ -314,6 +225,7 @@ export function createImagePreviewExtension(options: ImagePreviewOptions = {}) {
     let generation = 0;
     let activeContext: ExtensionContext | undefined;
     let sources = new Map<string, PreviewSource>();
+    let trackedFiles = new Set<string>();
     let syncInFlight = false;
     let syncAgain = false;
 
@@ -323,6 +235,7 @@ export function createImagePreviewExtension(options: ImagePreviewOptions = {}) {
       timer = undefined;
       activeContext = undefined;
       sources = new Map();
+      trackedFiles = new Set();
       syncInFlight = false;
       syncAgain = false;
       if (ctx?.mode === "tui") ctx.ui.setWidget(WIDGET_KEY, undefined);
@@ -349,12 +262,17 @@ export function createImagePreviewExtension(options: ImagePreviewOptions = {}) {
 
       const additions = await Promise.all(paths
         .filter((path) => !sources.has(path))
-        .map(async (path) => [path, await readPreviewSource(path)] as const));
+        .map(async (path) => {
+          const source = await readPreviewSource(path);
+          if (source) await prepareKittyVariant(source);
+          return [path, source] as const;
+        }));
       if (expectedGeneration !== generation || ctx !== activeContext) return;
 
       for (const [path, source] of additions) {
         if (source && !sources.has(path)) {
           sources.set(path, source);
+          trackedFiles.add(path);
           changed = true;
         }
       }
@@ -393,8 +311,10 @@ export function createImagePreviewExtension(options: ImagePreviewOptions = {}) {
       timer.unref?.();
     });
 
-    pi.on("session_shutdown", (_event, ctx) => {
+    pi.on("session_shutdown", async (_event, ctx) => {
+      const tracked = [...trackedFiles];
       stop(ctx);
+      await Promise.all(tracked.map(deleteClipboardImage));
     });
   };
 }

package/src/png.ts

@@ -1,214 +0,0 @@
-import { deflateSync, inflateSync } from "node:zlib";
-
-/** Straight-alpha RGBA8 raster. */
-export interface RgbaImage {
-  width: number;
-  height: number;
-  data: Uint8Array;
-}
-
-const SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
-const CHANNELS_BY_COLOR_TYPE: Record<number, number> = { 0: 1, 2: 3, 3: 1, 4: 2, 6: 4 };
-
-const CRC_TABLE = (() => {
-  const table = new Uint32Array(256);
-  for (let n = 0; n < 256; n += 1) {
-    let c = n;
-    for (let k = 0; k < 8; k += 1) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
-    table[n] = c >>> 0;
-  }
-  return table;
-})();
-
-function crc32(...parts: Uint8Array[]): number {
-  let crc = 0xffffffff;
-  for (const part of parts) {
-    for (const byte of part) crc = CRC_TABLE[(crc ^ byte) & 0xff]! ^ (crc >>> 8);
-  }
-  return (crc ^ 0xffffffff) >>> 0;
-}
-
-function paeth(a: number, b: number, c: number): number {
-  const p = a + b - c;
-  const pa = Math.abs(p - a);
-  const pb = Math.abs(p - b);
-  const pc = Math.abs(p - c);
-  if (pa <= pb && pa <= pc) return a;
-  return pb <= pc ? b : c;
-}
-
-function unfilter(raw: Uint8Array, stride: number, height: number, bytesPerPixel: number): Uint8Array | null {
-  const out = new Uint8Array(stride * height);
-  let offset = 0;
-  for (let y = 0; y < height; y += 1) {
-    const filter = raw[offset];
-    offset += 1;
-    const row = out.subarray(y * stride, (y + 1) * stride);
-    const prev = y > 0 ? out.subarray((y - 1) * stride, y * stride) : undefined;
-    for (let x = 0; x < stride; x += 1) {
-      const value = raw[offset + x]!;
-      const left = x >= bytesPerPixel ? row[x - bytesPerPixel]! : 0;
-      const up = prev ? prev[x]! : 0;
-      const upLeft = prev && x >= bytesPerPixel ? prev[x - bytesPerPixel]! : 0;
-      let decoded: number;
-      switch (filter) {
-        case 0: decoded = value; break;
-        case 1: decoded = value + left; break;
-        case 2: decoded = value + up; break;
-        case 3: decoded = value + ((left + up) >> 1); break;
-        case 4: decoded = value + paeth(left, up, upLeft); break;
-        default: return null;
-      }
-      row[x] = decoded & 0xff;
-    }
-    offset += stride;
-  }
-  return out;
-}
-
-/**
- * Decode a non-interlaced PNG (any color type, bit depths 1-16) into RGBA8.
- * Returns null for anything it cannot represent so callers can fall back.
- */
-export function decodePng(bytes: Uint8Array): RgbaImage | null {
-  if (bytes.length < 8 || SIGNATURE.some((byte, index) => bytes[index] !== byte)) return null;
-  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
-
-  let width = 0;
-  let height = 0;
-  let bitDepth = 0;
-  let colorType = 0;
-  let interlace = 0;
-  let palette: Uint8Array | undefined;
-  let transparency: Uint8Array | undefined;
-  const idat: Uint8Array[] = [];
-
-  let offset = 8;
-  while (offset + 8 <= bytes.length) {
-    const length = view.getUint32(offset);
-    const type = String.fromCharCode(bytes[offset + 4]!, bytes[offset + 5]!, bytes[offset + 6]!, bytes[offset + 7]!);
-    const start = offset + 8;
-    const end = start + length;
-    if (end + 4 > bytes.length) return null;
-    const chunk = bytes.subarray(start, end);
-    if (type === "IHDR") {
-      width = view.getUint32(start);
-      height = view.getUint32(start + 4);
-      bitDepth = bytes[start + 8]!;
-      colorType = bytes[start + 9]!;
-      interlace = bytes[start + 12]!;
-    } else if (type === "PLTE") {
-      palette = chunk;
-    } else if (type === "tRNS") {
-      transparency = chunk;
-    } else if (type === "IDAT") {
-      idat.push(chunk);
-    } else if (type === "IEND") {
-      break;
-    }
-    offset = end + 4;
-  }
-
-  const channels = CHANNELS_BY_COLOR_TYPE[colorType];
-  if (!width || !height || interlace !== 0 || idat.length === 0 || !channels) return null;
-  if (![1, 2, 4, 8, 16].includes(bitDepth)) return null;
-  if (colorType === 3 && !palette) return null;
-
-  const bitsPerPixel = channels * bitDepth;
-  const bytesPerPixel = Math.max(1, bitsPerPixel >> 3);
-  const stride = Math.ceil((width * bitsPerPixel) / 8);
-
-  let raw: Uint8Array;
-  try {
-    raw = inflateSync(Buffer.concat(idat));
-  } catch {
-    return null;
-  }
-  if (raw.length < (stride + 1) * height) return null;
-  const scanlines = unfilter(raw, stride, height, bytesPerPixel);
-  if (!scanlines) return null;
-
-  const maxSample = (1 << bitDepth) - 1;
-  const readSample = (row: Uint8Array, index: number): number => {
-    if (bitDepth === 8) return row[index]!;
-    if (bitDepth === 16) return row[index * 2]!;
-    const bitOffset = index * bitDepth;
-    const byte = row[bitOffset >> 3]!;
-    return (byte >> (8 - bitDepth - (bitOffset & 7))) & maxSample;
-  };
-  const scale = (sample: number): number => (bitDepth === 8 || bitDepth === 16 ? sample : Math.round((sample * 255) / maxSample));
-
-  const data = new Uint8Array(width * height * 4);
-  for (let y = 0; y < height; y += 1) {
-    const row = scanlines.subarray(y * stride, (y + 1) * stride);
-    for (let x = 0; x < width; x += 1) {
-      const out = (y * width + x) * 4;
-      const base = x * channels;
-      switch (colorType) {
-        case 0: {
-          const gray = scale(readSample(row, base));
-          data[out] = gray; data[out + 1] = gray; data[out + 2] = gray; data[out + 3] = 255;
-          break;
-        }
-        case 2:
-          data[out] = scale(readSample(row, base));
-          data[out + 1] = scale(readSample(row, base + 1));
-          data[out + 2] = scale(readSample(row, base + 2));
-          data[out + 3] = 255;
-          break;
-        case 3: {
-          const index = readSample(row, base);
-          data[out] = palette![index * 3] ?? 0;
-          data[out + 1] = palette![index * 3 + 1] ?? 0;
-          data[out + 2] = palette![index * 3 + 2] ?? 0;
-          data[out + 3] = transparency?.[index] ?? 255;
-          break;
-        }
-        case 4: {
-          const gray = scale(readSample(row, base));
-          data[out] = gray; data[out + 1] = gray; data[out + 2] = gray;
-          data[out + 3] = scale(readSample(row, base + 1));
-          break;
-        }
-        default:
-          data[out] = scale(readSample(row, base));
-          data[out + 1] = scale(readSample(row, base + 1));
-          data[out + 2] = scale(readSample(row, base + 2));
-          data[out + 3] = scale(readSample(row, base + 3));
-      }
-    }
-  }
-
-  return { width, height, data };
-}
-
-function chunk(type: string, payload: Uint8Array): Buffer {
-  const header = Buffer.alloc(8);
-  header.writeUInt32BE(payload.length, 0);
-  header.write(type, 4, "ascii");
-  const crc = Buffer.alloc(4);
-  crc.writeUInt32BE(crc32(header.subarray(4), payload), 0);
-  return Buffer.concat([header, payload, crc]);
-}
-
-/** Encode an RGBA8 raster as a non-interlaced 8-bit RGBA PNG. */
-export function encodePng(image: RgbaImage): Buffer {
-  const stride = image.width * 4;
-  const raw = Buffer.alloc((stride + 1) * image.height);
-  for (let y = 0; y < image.height; y += 1) {
-    raw[y * (stride + 1)] = 0;
-    raw.set(image.data.subarray(y * stride, (y + 1) * stride), y * (stride + 1) + 1);
-  }
-  const ihdr = Buffer.alloc(13);
-  ihdr.writeUInt32BE(image.width, 0);
-  ihdr.writeUInt32BE(image.height, 4);
-  ihdr[8] = 8; // bit depth
-  ihdr[9] = 6; // RGBA
-  ihdr[10] = 0; ihdr[11] = 0; ihdr[12] = 0;
-  return Buffer.concat([
-    Buffer.from(SIGNATURE),
-    chunk("IHDR", ihdr),
-    chunk("IDAT", deflateSync(raw)),
-    chunk("IEND", new Uint8Array(0)),
-  ]);
-}

package/src/raster.ts

@@ -1,116 +0,0 @@
-import type { RgbaImage } from "./png.ts";
-
-export type Rgba = readonly [r: number, g: number, b: number, a: number];
-
-export interface Rect {
-  x: number;
-  y: number;
-  width: number;
-  height: number;
-}
-
-export function createImage(width: number, height: number): RgbaImage {
-  return { width, height, data: new Uint8Array(width * height * 4) };
-}
-
-/** Box-filter resample (area average when shrinking, nearest when enlarging). */
-export function resample(image: RgbaImage, width: number, height: number): RgbaImage {
-  if (width === image.width && height === image.height) return image;
-  const out = createImage(width, height);
-  const scaleX = image.width / width;
-  const scaleY = image.height / height;
-  for (let y = 0; y < height; y += 1) {
-    const y0 = Math.floor(y * scaleY);
-    const y1 = Math.max(y0 + 1, Math.min(image.height, Math.ceil((y + 1) * scaleY)));
-    for (let x = 0; x < width; x += 1) {
-      const x0 = Math.floor(x * scaleX);
-      const x1 = Math.max(x0 + 1, Math.min(image.width, Math.ceil((x + 1) * scaleX)));
-      let r = 0; let g = 0; let b = 0; let a = 0; let count = 0;
-      for (let sy = y0; sy < y1; sy += 1) {
-        for (let sx = x0; sx < x1; sx += 1) {
-          const i = (sy * image.width + sx) * 4;
-          const alpha = image.data[i + 3]!;
-          r += image.data[i]! * alpha;
-          g += image.data[i + 1]! * alpha;
-          b += image.data[i + 2]! * alpha;
-          a += alpha;
-          count += 1;
-        }
-      }
-      const o = (y * width + x) * 4;
-      if (a > 0) {
-        out.data[o] = Math.round(r / a);
-        out.data[o + 1] = Math.round(g / a);
-        out.data[o + 2] = Math.round(b / a);
-      }
-      out.data[o + 3] = Math.round(a / count);
-    }
-  }
-  return out;
-}
-
-/** Scale to fit inside the box while preserving aspect ratio (enlarging allowed). */
-export function fitWithin(image: RgbaImage, maxWidth: number, maxHeight: number): RgbaImage {
-  const scale = Math.min(maxWidth / image.width, maxHeight / image.height);
-  const width = Math.max(1, Math.round(image.width * scale));
-  const height = Math.max(1, Math.round(image.height * scale));
-  return resample(image, width, height);
-}
-
-/** Anti-aliased coverage (0..1) of the pixel at (px, py) by a rounded rectangle. */
-export function roundedRectCoverage(px: number, py: number, rect: Rect, radius: number): number {
-  const r = Math.max(0, Math.min(radius, rect.width / 2, rect.height / 2));
-  const dx = Math.abs(px + 0.5 - (rect.x + rect.width / 2)) - (rect.width / 2 - r);
-  const dy = Math.abs(py + 0.5 - (rect.y + rect.height / 2)) - (rect.height / 2 - r);
-  const distance = Math.hypot(Math.max(dx, 0), Math.max(dy, 0)) + Math.min(Math.max(dx, dy), 0) - r;
-  return Math.min(1, Math.max(0, 0.5 - distance));
-}
-
-function blendPixel(canvas: RgbaImage, x: number, y: number, color: Rgba, coverage: number): void {
-  if (coverage <= 0 || x < 0 || y < 0 || x >= canvas.width || y >= canvas.height) return;
-  const i = (y * canvas.width + x) * 4;
-  const sa = (color[3] / 255) * coverage;
-  if (sa <= 0) return;
-  const da = canvas.data[i + 3]! / 255;
-  const outA = sa + da * (1 - sa);
-  for (let c = 0; c < 3; c += 1) {
-    canvas.data[i + c] = Math.round((color[c]! * sa + canvas.data[i + c]! * da * (1 - sa)) / outA);
-  }
-  canvas.data[i + 3] = Math.round(outA * 255);
-}
-
-function forEachPixel(rect: Rect, canvas: RgbaImage, visit: (x: number, y: number) => void): void {
-  const x0 = Math.max(0, Math.floor(rect.x));
-  const y0 = Math.max(0, Math.floor(rect.y));
-  const x1 = Math.min(canvas.width, Math.ceil(rect.x + rect.width));
-  const y1 = Math.min(canvas.height, Math.ceil(rect.y + rect.height));
-  for (let y = y0; y < y1; y += 1) {
-    for (let x = x0; x < x1; x += 1) visit(x, y);
-  }
-}
-
-export function fillRoundedRect(canvas: RgbaImage, rect: Rect, radius: number, color: Rgba): void {
-  forEachPixel(rect, canvas, (x, y) => blendPixel(canvas, x, y, color, roundedRectCoverage(x, y, rect, radius)));
-}
-
-/** Stroke drawn inside `rect`, `width` pixels wide, following its rounded outline. */
-export function strokeRoundedRect(canvas: RgbaImage, rect: Rect, radius: number, width: number, color: Rgba): void {
-  const inner: Rect = { x: rect.x + width, y: rect.y + width, width: rect.width - width * 2, height: rect.height - width * 2 };
-  forEachPixel(rect, canvas, (x, y) => {
-    const coverage = roundedRectCoverage(x, y, rect, radius) - roundedRectCoverage(x, y, inner, radius - width);
-    blendPixel(canvas, x, y, color, coverage);
-  });
-}
-
-/** Source-over blit; when `mask` is given, source alpha is clipped to that rounded rectangle. */
-export function blit(canvas: RgbaImage, image: RgbaImage, left: number, top: number, mask?: { rect: Rect; radius: number }): void {
-  for (let y = 0; y < image.height; y += 1) {
-    for (let x = 0; x < image.width; x += 1) {
-      const cx = left + x;
-      const cy = top + y;
-      const coverage = mask ? roundedRectCoverage(cx, cy, mask.rect, mask.radius) : 1;
-      const i = (y * image.width + x) * 4;
-      blendPixel(canvas, cx, cy, [image.data[i]!, image.data[i + 1]!, image.data[i + 2]!, image.data[i + 3]!], coverage);
-    }
-  }
-}