# @jordyvd/pi-image-attachments

A distributable Pi extension package that brings image attachment behavior to Pi without any external runtime dependency beyond Pi itself.

## Features

- `Ctrl+V` clipboard images attach as draft images instead of leaving temp-file paths in the editor.
- Dragging or pasting a local image path into the editor attaches it.
- Draft images are shown as `[Image #N]` placeholders.
- Placeholders are stripped from the submitted text; only the image content is sent.
- Drafts containing only image placeholders are sent as image-only user messages.
- Screenshot tool results that save to `filePath` are promoted into inline image content so the agent can inspect them agentically.
- The extension nudges Pi to prefer inline screenshots when the agent needs to inspect the image itself.

## Demo

[Watch the screen recording demo](https://github.com/jordyvandomselaar/pi-image-attachments/blob/main/media/pi-image-attachments-demo-2026-03-17.mp4)

## Install

From npm (recommended):

```bash
pi install npm:@jordyvd/pi-image-attachments
```

From source:

```bash
git clone https://github.com/jordyvandomselaar/pi-image-attachments.git
pi install ./pi-image-attachments
```

Try without installing:

```bash
pi -e npm:@jordyvd/pi-image-attachments
```

You can also point Pi at a local checkout while developing the extension.

## Package structure

This package uses Pi's `pi.extensions` manifest in `package.json`, so Pi can load it from npm, git, or a local path.

The npm publish is intentionally limited by the `files` whitelist in `package.json`, so repo-only assets like `media/pi-image-attachments-demo-2026-03-17.mp4` are kept out of the published package.

## Custom editor composability

`pi-image-attachments` targets Pi 0.71+ and uses the composable custom-editor API: it reads `ctx.ui.getEditorComponent()` before installing its own editor with `ctx.ui.setEditorComponent()`.

- If another extension installed an editor first, this package wraps that editor instance so its class and behavior remain active while image placeholders are layered on top.
- If no editor is installed yet, this package wraps Pi's default `CustomEditor` behavior.
- Load order still matters: install editor extensions that should be preserved before `pi-image-attachments`. A later extension that does not compose with `getEditorComponent()` can still replace the editor chain.
- Older Pi versions without `getEditorComponent()` are not supported by this package version; there is intentionally no fallback or compatibility shim.

## Tests

```bash
bun test
bun test --coverage --coverage-reporter=text --coverage-reporter=lcov
```