@prjct.app/pi-clipboard 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0
+
+- Set the npm package identity to `@prjct.app/pi-clipboard`.
+- Clarify installation, project scope, updates, removal, usage, and limitations.
+- Document resource discovery and dependencies against the official Pi 0.85.1 guides.
+- Include contribution and package documentation in the release file list.
+
+Initial npm release. The documentation and naming changes preserve the existing extension runtime behavior.

package/CONTRIBUTING.md

@@ -0,0 +1,14 @@
+# Contributing
+
+- Integration branch: `main`. Create a feature branch from `main`.
+- Deliver changes through a pull request using `.github/pull_request_template.md`.
+- Use English for code, documentation, tests, issues, and pull requests.
+- Use strict TypeScript and Pi's public extension/TUI interfaces.
+- Keep image data local and limit file access to Pi clipboard files in the system temporary directory.
+- Keep tests offline and use temporary files rather than the real Pi configuration or clipboard.
+- Run `npm run check` and `npm test` before review.
+- Never push, open or merge a pull request, publish, or deploy without explicit authorization.
+
+## 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.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 prjct
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,71 @@
+# pi-clipboard
+
+Preview pasted images above the native Pi editor.
+
+`@prjct.app/pi-clipboard` · Clipboard image previews; one extension.
+
+## Install
+
+Requires Pi installed separately and Node.js **22.19 or later**. Compatibility is tested with **Pi 0.85.1**; newer versions are not yet verified. This is an independent community package.
+
+Install with Pi's package manager:
+
+```sh
+pi install npm:@prjct.app/pi-clipboard
+```
+
+For project-only installation, add `-l`: `pi install -l npm:@prjct.app/pi-clipboard`. Restart Pi after installation. Do not install the same extension from both GitHub and npm: Pi treats those as different package identities.
+
+## Usage
+
+1. Start an interactive Pi session after installing the package.
+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.
+
+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.
+
+
+## Manage the package
+
+For an npm installation:
+
+```sh
+pi list
+pi update npm:@prjct.app/pi-clipboard
+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.0, use `pi install npm:@prjct.app/pi-clipboard@0.1.0`. 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.
+
+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.
+
+## 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.
+
+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.
+
+## Development
+
+From a repository checkout:
+
+```sh
+npm ci --ignore-scripts
+npm run check
+npm test
+npm run check:package
+```
+
+Pi loads the TypeScript entry point directly; no build step is required. To try this checkout for one run, use `pi -e .`. Tests use isolated temporary state and do not call model APIs. See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution rules and [CHANGELOG.md](CHANGELOG.md) for release notes.
+
+## License
+
+[MIT](LICENSE).

package/docs/package.md

@@ -0,0 +1,54 @@
+# Package structure and compatibility
+
+## Identity
+
+- 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).
+- 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.
+
+## Resource manifest
+
+```json
+{
+  "name": "@prjct.app/pi-clipboard",
+  "keywords": [
+    "pi-package"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}
+```
+
+The `pi-package` keyword makes the package discoverable. Manifest paths are relative to the package root. The extension entry point is shipped as TypeScript because Pi loads it directly. There is no CLI binary or JavaScript build artifact to install separately.
+
+## Dependencies
+
+Pi-provided libraries imported by this package are declared in `peerDependencies` with `*`, as required by Pi's package guide. They are not bundled. Exact Pi 0.85.1 development dependencies establish the tested baseline; the peer wildcard is not a claim that every Pi release is supported.
+
+Third-party runtime dependencies belong in `dependencies`. Companion extensions are installed separately only when communication uses Pi's event bus; this package does not import code from a separately installed companion. A package that directly imports another Pi package's resources must instead bundle it following the official guide.
+
+## 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.
+
+## Published contents
+
+The `files` allowlist includes runtime resources, user documentation, and license files. Development tests, dependency folders, repository settings, and Git history are excluded. npm also includes `package.json` automatically. The npm lockfile remains in the repository for repeatable development installs.
+
+Run `npm run check:package` to inspect the exact prospective tarball before release. Check that each manifest entry and each referenced local document exists in the packed file list. Only claim npm availability after verifying a successful registry publication.
+
+## Official references
+
+These links are pinned to the tested Pi version rather than the moving main branch:
+
+- [Packages: manifest, sources, dependencies, filtering, and deduplication](https://github.com/earendil-works/pi/blob/v0.85.1/packages/coding-agent/docs/packages.md).
+- [Extensions: lifecycle, commands, tools, messages, and UI APIs](https://github.com/earendil-works/pi/blob/v0.85.1/packages/coding-agent/docs/extensions.md).
+- [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.

package/index.ts

@@ -0,0 +1 @@
+export { clipboardImagePaths, createImagePreviewExtension, default } from "./src/index.ts";

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@prjct.app/pi-clipboard",
+  "version": "0.1.0",
+  "description": "Preview pasted images above the native Pi editor.",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "clipboard",
+    "image",
+    "preview",
+    "terminal"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "scripts": {
+    "check": "tsc --noEmit",
+    "test": "node --import tsx --test tests/*.test.ts",
+    "check:package": "npm pack --dry-run --ignore-scripts"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.85.1",
+    "@earendil-works/pi-tui": "0.85.1",
+    "@types/node": "^22.19.0",
+    "tsx": "^4.20.0",
+    "typescript": "^5.9.3"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/prjct-app/pi-image-preview.git"
+  },
+  "homepage": "https://github.com/prjct-app/pi-image-preview#readme",
+  "bugs": {
+    "url": "https://github.com/prjct-app/pi-image-preview/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "README.md",
+    "LICENSE",
+    "CONTRIBUTING.md",
+    "CHANGELOG.md",
+    "docs/package.md"
+  ]
+}

package/src/index.ts

@@ -0,0 +1,402 @@
+import { constants } from "node:fs";
+import { lstat, open } 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 {
+  getCapabilities,
+  getImageDimensions,
+  imageFallback,
+  Image,
+  truncateToWidth,
+  visibleWidth,
+  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");
+const IMAGE_MIME_TYPES: Record<string, string> = {
+  ".gif": "image/gif",
+  ".jpeg": "image/jpeg",
+  ".jpg": "image/jpeg",
+  ".png": "image/png",
+  ".webp": "image/webp",
+};
+
+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];
+
+interface PreviewSource {
+  filePath: string;
+  data: Buffer;
+  mimeType: string;
+  dimensions: ImageDimensions;
+}
+
+interface GalleryLayout {
+  columns: number;
+  rows: number;
+  displayWidth: number;
+  displayHeight: number;
+}
+
+interface RenderedGallery {
+  signature: string;
+  image: Image;
+}
+
+interface Scheduler {
+  setInterval(callback: () => void, intervalMs: number): ReturnType<typeof setInterval>;
+  clearInterval(handle: ReturnType<typeof setInterval>): void;
+}
+
+export interface ImagePreviewOptions {
+  pollIntervalMs?: number;
+  scheduler?: Scheduler;
+}
+
+const systemScheduler: Scheduler = {
+  setInterval: (callback, intervalMs) => setInterval(callback, intervalMs),
+  clearInterval: (handle) => clearInterval(handle),
+};
+
+/** Resolve only filenames produced by Pi's native clipboard flow. */
+export function clipboardImagePaths(editorText: string): string[] {
+  const paths = new Set<string>();
+  const matcher = new RegExp(CLIPBOARD_IMAGE_FILENAME.source, CLIPBOARD_IMAGE_FILENAME.flags);
+  for (const match of editorText.matchAll(matcher)) {
+    const fileName = match[0];
+    const filePath = resolve(tmpdir(), fileName);
+    if (editorText.includes(filePath)) paths.add(filePath);
+  }
+  return [...paths];
+}
+
+async function readPreviewSource(filePath: string): Promise<PreviewSource | undefined> {
+  if (dirname(resolve(filePath)) !== resolve(tmpdir())) return undefined;
+  const mimeType = IMAGE_MIME_TYPES[extname(filePath).toLowerCase()];
+  if (!mimeType || !CLIPBOARD_IMAGE_BASENAME.test(basename(filePath))) return undefined;
+
+  try {
+    const before = await lstat(filePath);
+    if (!before.isFile() || before.isSymbolicLink() || before.size > MAX_PREVIEW_FILE_BYTES) return undefined;
+
+    const handle = await open(filePath, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+      const opened = await handle.stat();
+      const after = await lstat(filePath);
+      if (
+        !opened.isFile()
+        || after.isSymbolicLink()
+        || opened.size > MAX_PREVIEW_FILE_BYTES
+        || opened.dev !== after.dev
+        || opened.ino !== after.ino
+      ) return undefined;
+
+      const data = await handle.readFile();
+      return {
+        filePath,
+        data,
+        mimeType,
+        dimensions: getImageDimensions(data.toString("base64"), mimeType) ?? { widthPx: 800, heightPx: 600 },
+      };
+    } finally {
+      await handle.close();
+    }
+  } catch {
+    return undefined;
+  }
+}
+
+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;
+  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");
+  } catch {
+    png = undefined;
+  }
+  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 });
+  }
+  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;
+
+  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(" "));
+      }
+    }
+
+    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();
+    });
+  }
+
+  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);
+  }
+
+  invalidate(): void {
+    this.gallery?.image.invalidate();
+  }
+
+  dispose(): void {
+    this.buildGeneration += 1;
+    this.gallery?.image.invalidate();
+    this.gallery = undefined;
+  }
+}
+
+function renderPreviewWidget(ctx: ExtensionContext, sources: PreviewSource[]): void {
+  if (sources.length === 0) {
+    ctx.ui.setWidget(WIDGET_KEY, undefined);
+    return;
+  }
+
+  const snapshot = [...sources];
+  ctx.ui.setWidget(WIDGET_KEY, (tui, theme) =>
+    new ImagePreviewGallery(tui, snapshot, (text) => theme.fg("muted", text)));
+}
+
+export function createImagePreviewExtension(options: ImagePreviewOptions = {}) {
+  const scheduler = options.scheduler ?? systemScheduler;
+  const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+
+  return function imagePreview(pi: ExtensionAPI): void {
+    let timer: ReturnType<typeof setInterval> | undefined;
+    let generation = 0;
+    let activeContext: ExtensionContext | undefined;
+    let sources = new Map<string, PreviewSource>();
+    let syncInFlight = false;
+    let syncAgain = false;
+
+    const stop = (ctx?: ExtensionContext) => {
+      generation += 1;
+      if (timer) scheduler.clearInterval(timer);
+      timer = undefined;
+      activeContext = undefined;
+      sources = new Map();
+      syncInFlight = false;
+      syncAgain = false;
+      if (ctx?.mode === "tui") ctx.ui.setWidget(WIDGET_KEY, undefined);
+    };
+
+    const syncOnce = async (ctx: ExtensionContext, expectedGeneration: number) => {
+      let editorText: string;
+      try {
+        editorText = ctx.ui.getEditorText();
+      } catch {
+        return;
+      }
+
+      const paths = clipboardImagePaths(editorText);
+      const pathSet = new Set(paths);
+      let changed = false;
+
+      for (const path of sources.keys()) {
+        if (!pathSet.has(path)) {
+          sources.delete(path);
+          changed = true;
+        }
+      }
+
+      const additions = await Promise.all(paths
+        .filter((path) => !sources.has(path))
+        .map(async (path) => [path, await readPreviewSource(path)] as const));
+      if (expectedGeneration !== generation || ctx !== activeContext) return;
+
+      for (const [path, source] of additions) {
+        if (source && !sources.has(path)) {
+          sources.set(path, source);
+          changed = true;
+        }
+      }
+
+      if (changed) renderPreviewWidget(ctx, [...sources.values()]);
+    };
+
+    const sync = async (ctx: ExtensionContext, expectedGeneration: number) => {
+      if (syncInFlight) {
+        syncAgain = true;
+        return;
+      }
+      syncInFlight = true;
+      try {
+        do {
+          syncAgain = false;
+          await syncOnce(ctx, expectedGeneration);
+        } while (syncAgain && expectedGeneration === generation && ctx === activeContext);
+      } finally {
+        syncInFlight = false;
+      }
+    };
+
+    pi.on("session_start", async (_event, ctx) => {
+      stop();
+      if (ctx.mode !== "tui") return;
+
+      activeContext = ctx;
+      const expectedGeneration = generation;
+      await sync(ctx, expectedGeneration);
+      if (expectedGeneration !== generation || ctx !== activeContext) return;
+
+      timer = scheduler.setInterval(() => {
+        void sync(ctx, expectedGeneration);
+      }, pollIntervalMs);
+      timer.unref?.();
+    });
+
+    pi.on("session_shutdown", (_event, ctx) => {
+      stop(ctx);
+    });
+  };
+}
+
+export default createImagePreviewExtension();

package/src/png.ts

@@ -0,0 +1,214 @@
+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

@@ -0,0 +1,116 @@
+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);
+    }
+  }
+}