pi-paster 0.1.0

package/README.md

@@ -0,0 +1,135 @@
+# paster
+
+`paster` is a pi extension that turns pasted, drag-dropped, or clipboard-provided images into first-class image attachments.
+
+Instead of leaving raw local image paths in your prompt, paster replaces them with readable placeholders such as `[#image 1]` and attaches the matching image content to the same user turn.
+
+## Preview
+
+<!-- Replace this with the project screenshot/demo image. -->
+
+![paster preview](./docs/preview.png)
+
+## Why this exists
+
+Terminal image workflows are awkward: dragging a screenshot into a terminal usually inserts a local file path, and pasting an image from the clipboard may require special handling. For multimodal models, that path is not enough—the image bytes need to be attached to the message.
+
+`paster` bridges that gap for pi interactive mode:
+
+1. Paste or drag/drop an image path into the editor.
+2. The path is replaced with a placeholder like `[#image 1]`.
+3. The image is stored in memory immediately.
+4. When you submit, pi sends your text with the placeholder plus the actual image attachment.
+5. The submitted image is rendered back in the conversation so you can confirm what was attached.
+
+## Features
+
+- Converts pasted or drag-dropped image paths into placeholders.
+- Supports PNG, JPEG, WebP, and GIF by magic-byte detection.
+- Supports absolute, relative, home-relative, quoted, and shell-escaped paths.
+- Attaches only placeholders still present in the submitted prompt.
+- Preserves attachment order by first placeholder occurrence.
+- Shows submitted image previews in chat history.
+- Optional custom editor integration:
+  - cursor-based image preview above the input
+  - atomic deletion of whole image placeholders
+  - macOS clipboard image paste via pi's image paste keybinding
+
+## Installation
+
+Once published to npm, install the package with pi:
+
+```bash
+pi install npm:pi-paster
+```
+
+Or try it without installing:
+
+```bash
+pi -e npm:pi-paster
+```
+
+For local development/testing:
+
+```bash
+pi -e .
+```
+
+## Usage
+
+Start pi interactive mode with the extension enabled.
+
+Then paste or drag/drop an image path:
+
+```text
+/Users/me/Desktop/screenshot.png
+```
+
+The editor will insert:
+
+```text
+[#image 1]
+```
+
+You can also write normal text around it:
+
+```text
+What is wrong in this screenshot? [#image 1]
+```
+
+On submit, the text and matching image attachment are sent together.
+
+## Clipboard image paste
+
+On macOS, pi exposes an image paste action through its keybinding system. In the default pi keybindings this is `Ctrl+V`.
+
+`Cmd+V` is handled by the terminal emulator itself. In Ghostty, if the clipboard contains text, Ghostty pastes the text into pi; if the clipboard contains only image data, pi may receive no input. Use pi's image paste keybinding for direct clipboard-image paste.
+
+## Configuration
+
+By default all editor integrations are enabled.
+
+To customize behavior, load a small wrapper extension:
+
+```ts
+import { createPaster } from "pi-paster";
+
+export default createPaster({
+  customEditor: {
+    enabled: true,
+    showImagePreview: true,
+    deletePlaceholderAsBlock: true,
+  },
+});
+```
+
+### Options
+
+| Option                                  | Default | Description                                                                                                                 |
+| --------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `customEditor.enabled`                  | `true`  | Replaces pi's input editor with paster's editor integration. Disable this to keep pi's default editor.                      |
+| `customEditor.showImagePreview`         | `true`  | Shows an image preview above the input when the cursor is inside an image placeholder. Requires `customEditor.enabled`.     |
+| `customEditor.deletePlaceholderAsBlock` | `true`  | Makes backspace/delete remove the whole placeholder when editing inside or adjacent to it. Requires `customEditor.enabled`. |
+
+When `customEditor.enabled` is `false`, paster still handles bracketed terminal paste/drop image paths, but cursor previews, atomic placeholder deletion, and paster's clipboard-image handler are disabled.
+
+## Development
+
+This repo uses Vite+ via `vp` with pnpm.
+
+```bash
+vp install
+vp check
+vp test run
+vp run build
+```
+
+The package manifest exposes the extension through:
+
+```json
+{
+  "pi": {
+    "extensions": ["./src/index.ts"]
+  }
+}
+```

package/dist/index.d.mts

@@ -0,0 +1,177 @@
+import * as _$_earendil_works_pi_tui0 from "@earendil-works/pi-tui";
+import { Component, EditorTheme, ImageDimensions, ImageTheme, TUI } from "@earendil-works/pi-tui";
+import { CustomEditor, ExtensionAPI, KeybindingsManager } from "@earendil-works/pi-coding-agent";
+
+//#region src/config.d.ts
+interface PasterConfig {
+  customEditor?: {
+    /** Replace pi's input editor to enable inline image UX features. */enabled?: boolean; /** Show an image preview above the input while the cursor is inside an image placeholder. */
+    showImagePreview?: boolean; /** Treat image placeholders as atomic blocks for backspace/delete. */
+    deletePlaceholderAsBlock?: boolean;
+  };
+}
+interface ResolvedPasterConfig {
+  customEditor: {
+    enabled: boolean;
+    showImagePreview: boolean;
+    deletePlaceholderAsBlock: boolean;
+  };
+}
+declare const DEFAULT_PASTER_CONFIG: ResolvedPasterConfig;
+declare function resolvePasterConfig(config?: PasterConfig): ResolvedPasterConfig;
+//#endregion
+//#region src/types.d.ts
+declare const EXTENSION_NAME = "paster";
+declare const MAX_IMAGE_BYTES: number;
+type SupportedImageMimeType = "image/png" | "image/jpeg" | "image/webp" | "image/gif";
+interface ImageAttachment {
+  id: number;
+  placeholder: string;
+  originalPath: string;
+  mimeType: SupportedImageMimeType;
+  data: string;
+  dimensions?: ImageDimensions;
+  createdAt: number;
+}
+interface LoadedImage {
+  originalPath: string;
+  mimeType: SupportedImageMimeType;
+  data: string;
+  dimensions?: ImageDimensions;
+}
+interface PasterImageContent {
+  type: "image";
+  mimeType: string;
+  data: string;
+}
+type LoadImageResult = {
+  ok: true;
+  image: LoadedImage;
+} | {
+  ok: false;
+  reason: "missing" | "not-file" | "too-large" | "unsupported" | "read-error";
+  path: string;
+};
+interface PasterPreviewDetails {
+  placeholders: string[];
+}
+//#endregion
+//#region src/clipboard.d.ts
+type ClipboardImageResult = {
+  ok: true;
+  image: LoadedImage;
+} | {
+  ok: false;
+  reason: "empty" | "unsupported-platform" | "too-large" | "unsupported" | "read-error";
+};
+declare function readClipboardImage(maxBytes?: number): ClipboardImageResult;
+//#endregion
+//#region src/store.d.ts
+declare class AttachmentStore {
+  private nextId;
+  private readonly attachments;
+  clear(): void;
+  list(): ImageAttachment[];
+  add(input: Omit<ImageAttachment, "id" | "placeholder" | "createdAt">): ImageAttachment;
+  get(placeholder: string): ImageAttachment | undefined;
+  matchingPlaceholders(text: string): ImageAttachment[];
+}
+//#endregion
+//#region src/editor.d.ts
+declare const PASTE_START = "\u001B[200~";
+declare const PASTE_END = "\u001B[201~";
+declare class PasterEditor extends CustomEditor {
+  private readonly pasterKeybindings;
+  private readonly pasterOptions;
+  private pasterPasteBuffer;
+  private activePreviewPlaceholder;
+  constructor(tui: TUI, theme: EditorTheme, pasterKeybindings: KeybindingsManager, pasterOptions: {
+    cwd: string;
+    store: AttachmentStore;
+    notify: (message: string) => void;
+    deletePlaceholderAsBlock: boolean;
+    setCursorPreview: (attachment: ImageAttachment | undefined) => void;
+    pasteClipboardImage?: () => Promise<ImageAttachment | undefined> | ImageAttachment | undefined;
+  });
+  insertTextAtCursor(text: string): void;
+  handleInput(data: string): void;
+  clearCursorPreview(): void;
+  private handlePasteClipboardImage;
+  private handleBracketedPaste;
+  private handleAtomicPlaceholderDelete;
+  private deleteLineRange;
+  private transform;
+  private updateCursorPreview;
+}
+//#endregion
+//#region src/image-utils.d.ts
+interface PathToken {
+  raw: string;
+  value: string;
+  start: number;
+  end: number;
+}
+declare function detectImageMimeType(bytes: Uint8Array): SupportedImageMimeType | undefined;
+declare function resolveImagePath(input: string, cwd: string): string;
+declare function shellUnescape(input: string): string;
+declare function tokenizePathLikeText(text: string): PathToken[];
+declare function dimensionsForImage(data: string, mimeType: SupportedImageMimeType): _$_earendil_works_pi_tui0.ImageDimensions | undefined;
+declare function loadImageFromPath(inputPath: string, cwd: string, maxBytes?: number): LoadImageResult;
+declare function replaceImagePathsInText(text: string, options: {
+  cwd: string;
+  store: AttachmentStore;
+  loadImage?: (path: string, cwd: string) => LoadImageResult;
+  onReject?: (result: Exclude<LoadImageResult, {
+    ok: true;
+  }>) => void;
+}): {
+  text: string;
+  replaced: number;
+  accepted: ImageAttachment[];
+};
+declare function imagesForText(store: AttachmentStore, text: string, existing?: PasterImageContent[]): PasterImageContent[];
+//#endregion
+//#region src/preview.d.ts
+declare class ImagePreviewMessage implements Component {
+  private readonly attachments;
+  private readonly theme;
+  private readonly images;
+  constructor(attachments: ImageAttachment[], theme: ImageTheme);
+  render(width: number): string[];
+  invalidate(): void;
+}
+interface CursorPreviewTheme {
+  title: (text: string) => string;
+  muted: (text: string) => string;
+  accent: (text: string) => string;
+}
+declare class CursorImagePreviewWidget implements Component {
+  private attachment;
+  private readonly theme;
+  private image;
+  constructor(attachment: ImageAttachment, theme: CursorPreviewTheme);
+  render(width: number): string[];
+  invalidate(): void;
+  private headerLine;
+  private createImage;
+  private constrainedImageWidth;
+}
+//#endregion
+//#region src/terminal-input.d.ts
+type TerminalInputResult = {
+  consume?: boolean;
+  data?: string;
+} | undefined;
+declare function createImagePasteTerminalInputHandler(options: {
+  cwd: string;
+  store: AttachmentStore;
+  notify?: (message: string) => void;
+  onAccept?: (attachments: ImageAttachment[]) => void;
+  loadImage?: (path: string, cwd: string) => LoadImageResult;
+}): (data: string) => TerminalInputResult;
+//#endregion
+//#region src/index.d.ts
+declare function createPaster(config?: PasterConfig): (pi: ExtensionAPI) => void;
+declare function paster(pi: ExtensionAPI, config?: PasterConfig): void;
+//#endregion
+export { AttachmentStore, ClipboardImageResult, CursorImagePreviewWidget, DEFAULT_PASTER_CONFIG, EXTENSION_NAME, ImageAttachment, ImagePreviewMessage, LoadImageResult, LoadedImage, MAX_IMAGE_BYTES, PASTE_END, PASTE_START, PasterConfig, PasterEditor, PasterImageContent, PasterPreviewDetails, ResolvedPasterConfig, SupportedImageMimeType, TerminalInputResult, createImagePasteTerminalInputHandler, createPaster, paster as default, detectImageMimeType, dimensionsForImage, imagesForText, loadImageFromPath, readClipboardImage, replaceImagePathsInText, resolveImagePath, resolvePasterConfig, shellUnescape, tokenizePathLikeText };