# pi-power-paste

English | [中文](./README_CN.md)

OpenCode-grade clipboard paste for [pi](https://github.com/earendil-works/pi) on Windows.

| Clipboard content | What you get |
|---|---|
| Image (screenshot, copied image) | `[#image 1]` placeholder + real image attachment sent to the model |
| Files copied in Explorer (Ctrl+C) | Image files → `[#image N]` attachments; text files → collapsed `[paste #N +X lines]` blocks (full content sent at submit); binaries/folders → plain path |
| Large text (>3 lines or >1000 chars) | Collapsed `[paste #N +X lines]` marker, expanded at submit |
| Small text | Inserted as-is |

Two extras that make it feel native:

- **Persistent PowerShell clipboard helper** — pi core spawns a cold PowerShell (~500ms) for every clipboard image read; power-paste keeps one alive and answers in **~5-10ms**.
- **Ctrl+V that actually works** — registered through pi's Kitty-protocol-aware shortcut layer (see [Windows Terminal setup](#windows-terminal-ctrlv-setup) below). `Alt+V` (pi's default image-paste binding) also works out of the box.

Built on top of [pi-paster](https://github.com/beowulf11/pi-paster) (MIT) — it is bundled as a library (placeholder store, editor, image optimizer, preview widgets); its own extension is not loaded.

## Installation

```bash
pi install npm:pi-power-paste
```

Or try it without installing:

```bash
pi -e npm:pi-power-paste
```

## Windows Terminal Ctrl+V setup

Windows Terminal binds **Ctrl+V to its own "paste text" action**, so the key never reaches pi (or any other TUI app). Symptoms: Ctrl+V does nothing for images; Win+V → Enter doesn't work either. Fix — unbind it in WT's `settings.json`:

```json
"actions": [
    { "command": "unbound", "keys": "ctrl+v" }
]
```

WT hot-reloads the file, no restart needed. PowerShell's own PSReadLine still pastes with Ctrl+V, and right-click paste keeps working, so the trade-off is minimal.

Notes:

- Both stable and Preview WT have **separate** settings files — edit the one you actually run (`%LOCALAPPDATA%\Packages\Microsoft.WindowsTerminal[Preview]_8wekyb3d8bbwe\LocalState\settings.json`).
- **VS Code integrated terminal** intercepts Ctrl+V too; unbind `workbench.action.terminal.paste` for `terminalFocus` if you want it there.
- Without any of this, `Alt+V` still gives you the full power-paste flow.

## Commands

- `/power-paste` — live self-test: probes the clipboard and reports helper mode (`persistent helper` vs `one-shot fallback`), latency, clipboard content kind, and pending attachment count.

## How it works

- One PowerShell process (`-STA -NoExit`) is spawned lazily on first paste; each probe is a single-line script over stdin with a sentinel-delimited reply (WinForms clipboard API: `GetFileDropList` → files, `GetImage` → PNG bytes, `GetText` → text). If it dies or times out, a one-shot `spawnSync` probe takes over — paste never breaks.
- Images become `[#image N]` placeholders with real attachments (optimized before send), text/file content uses pi's native `[paste #N]` collapsing so blocks are atomic-deletable and expanded at submit.
- Ctrl+V matching goes through `pi.registerShortcut` — with the Kitty keyboard protocol active (Windows Terminal 1.22+), Ctrl+V arrives as a CSI-u sequence, not `\x16`. Matching raw bytes is a trap.

## Requirements

- Windows for the full experience; on macOS/Linux the extension degrades to pi-paster's original clipboard-image behavior.
- Windows Terminal users: the Ctrl+V unbind above (or just use Alt+V).

## Credits

- [pi-paster](https://github.com/beowulf11/pi-paster) by beowulf11 (MIT) — attachment store, editor base, image pipeline. Bundled as a library; see [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md) for its license text.
- Built with [pi](https://github.com/earendil-works/pi).

## License

MIT