pi-image-tools 1.0.0 → 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/CHANGELOG.md +10 -0
  2. package/README.md +110 -115
  3. package/asset/pi-image-tools.png +0 -0
  4. package/package.json +2 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,15 @@
1
1
  # Changelog
2
2
 
3
+ ## [1.0.2] - 2026-03-04
4
+
5
+ ### Changed
6
+ - Rewrote README.md with professional documentation standards
7
+ - Added comprehensive feature documentation, configuration reference, and usage examples
8
+
9
+ ## 1.0.1
10
+
11
+ - Included `asset/` in the npm package whitelist so README image assets ship in the tarball.
12
+
3
13
  ## 1.0.0
4
14
 
5
15
  - Standardized repository layout to `src/` + root shim entrypoint.
package/README.md CHANGED
@@ -1,47 +1,42 @@
1
- # pi-image-tools
1
+ # 🖼️ pi-image-tools
2
2
 
3
3
  Image attachment and preview extension for the **Pi coding agent**.
4
4
 
5
- This extension focuses on one workflow: quickly attach a clipboard image (or pick a recent screenshot) to the message you are about to send, and then render an inline preview in the TUI chat.
5
+ Quickly attach clipboard images or recent screenshots to your messages, with inline preview rendering in the TUI chat.
6
6
 
7
- > **Windows-only:** `pi-image-tools` only registers commands/shortcuts on Windows (`win32`). On macOS/Linux it does nothing.
7
+ > ⚠️ **Windows-only:** This extension only registers commands and shortcuts on Windows (`win32`). On other platforms, it does nothing.
8
8
 
9
- ![pi-image-tools](asset/pi-image-tools.png)
9
+ ![pi-image-tools preview](asset/pi-image-tools.png)
10
10
 
11
11
  ## Features
12
12
 
13
- - Paste images into your next message:
14
- - `/paste-image clipboard` (default) reads an image from the clipboard and queues it for the next send.
15
- - `/paste-image recent` opens a picker for recent screenshots/images and queues the selected file.
16
- - Keyboard shortcuts for fast paste:
17
- - `alt+v`
18
- - `ctrl+alt+v`
19
- - Inline image preview in the chat after you send your message (up to **3** images previewed per message).
20
- - Recent-images support:
21
- - Searches common Windows screenshot locations by default.
22
- - Caches images you pasted from clipboard so they also show up in the recent picker.
23
- - Preview modes:
24
- - **Sixel** (preferred on Windows) when the PowerShell `Sixel` module is available.
25
- - **Native** fallback rendering when Sixel conversion is unavailable.
13
+ - **Clipboard paste** – Attach images directly from your clipboard
14
+ - **Recent image picker** – Browse and select from recent screenshots
15
+ - **Keyboard shortcuts** – Fast paste with `Alt+V` or `Ctrl+Alt+V`
16
+ - **Inline preview** – See attached images rendered in the TUI (up to 3 per message)
17
+ - **Sixel rendering** – High-quality terminal graphics when available
18
+ - **Automatic caching** – Clipboard-pasted images appear in the recent picker
26
19
 
27
20
  ## Installation
28
21
 
29
- ### Local extension folder
22
+ ### Extension Folder (Recommended)
30
23
 
31
- Place this folder in:
24
+ Place this folder in one of these locations:
32
25
 
33
- - Global: `~/.pi/agent/extensions/pi-image-tools`
34
- - Project: `.pi/extensions/pi-image-tools`
26
+ | Scope | Path |
27
+ |---------|-------------------------------------------|
28
+ | Global | `~/.pi/agent/extensions/pi-image-tools` |
29
+ | Project | `.pi/extensions/pi-image-tools` |
35
30
 
36
- Pi auto-discovers these paths.
31
+ Pi auto-discovers extensions in these paths.
37
32
 
38
- ### As an npm package
33
+ ### Via npm
39
34
 
40
35
  ```bash
41
36
  pi install npm:pi-image-tools
42
37
  ```
43
38
 
44
- Or from git:
39
+ ### Via Git
45
40
 
46
41
  ```bash
47
42
  pi install git:github.com/MasuRii/pi-image-tools
@@ -49,159 +44,159 @@ pi install git:github.com/MasuRii/pi-image-tools
49
44
 
50
45
  ## Usage
51
46
 
52
- ### Paste from clipboard
47
+ ### Commands
53
48
 
54
- Command:
49
+ #### Paste from Clipboard
55
50
 
56
51
  ```text
57
52
  /paste-image clipboard
58
53
  ```
59
54
 
60
- Notes:
55
+ Or simply:
61
56
 
62
- - `/paste-image` (with no args) behaves the same as `/paste-image clipboard`.
63
- - The extension inserts a marker into your draft (`[󰈟 Image Attached]`). When you send, that marker is removed and the queued image(s) are attached to the outgoing message.
64
- - If you remove all markers from your draft before sending, the pending queued images are discarded.
57
+ ```text
58
+ /paste-image
59
+ ```
60
+
61
+ This reads an image from your clipboard and queues it for attachment. A marker (`[󰈟 Image Attached]`) appears in your draft. When you send the message, the marker is removed and the image is attached.
65
62
 
66
- ### Paste from recent images
63
+ > **Tip:** Remove all markers from your draft before sending to discard pending images.
64
+
65
+ #### Paste from Recent Images
67
66
 
68
67
  ```text
69
68
  /paste-image recent
70
69
  ```
71
70
 
72
- This opens an interactive picker (requires Pi’s interactive TUI mode). The extension searches for recent images and shows a list like:
71
+ Opens an interactive picker showing recent screenshots and cached images:
73
72
 
74
73
  ```text
75
74
  01. Screenshot 2026-03-02 142233.png • 2m ago • 412 KB • C:\Users\...\Pictures\Screenshots\...
75
+ 02. IMG_20260301_120000.png • 1d ago • 1.2 MB • C:\Users\...\Desktop\...
76
76
  ```
77
77
 
78
- After selection, the image is queued for your next send.
79
-
80
- ### Shortcuts
81
-
82
- These shortcuts are equivalent to `/paste-image clipboard`:
83
-
84
- - `alt+v`
85
- - `ctrl+alt+v`
86
-
87
- ## Recent images: what gets searched
88
-
89
- `/paste-image recent` searches Windows paths in this order:
78
+ Select an image to queue it for your next message.
90
79
 
91
- 1. The **recent cache directory** (images you pasted via clipboard are cached here).
92
- 2. If configured via environment, the directories from `PI_IMAGE_TOOLS_RECENT_DIRS`.
93
- 3. Otherwise, these defaults:
94
- - `~/Pictures/Screenshots`
95
- - `~/OneDrive/Pictures/Screenshots`
96
- - `~/Desktop` (only files with screenshot-like names such as `Screenshot*`, `Snip*`, `IMG_*`, etc.)
80
+ ### Keyboard Shortcuts
97
81
 
98
- Supported file types: `.png`, `.jpg`/`.jpeg`, `.webp`, `.gif`, `.bmp`.
82
+ | Shortcut | Action |
83
+ |----------------|---------------------------|
84
+ | `Alt+V` | Paste image from clipboard|
85
+ | `Ctrl+Alt+V` | Paste image from clipboard|
99
86
 
100
- ### Environment variables
101
-
102
- - `PI_IMAGE_TOOLS_RECENT_DIRS`
103
- - Semicolon-separated list of directories to search (Windows-style):
104
- - Example: `C:\Users\you\Pictures\Screenshots;D:\Shares\Screens`
105
- - `PI_IMAGE_TOOLS_RECENT_CACHE_DIR`
106
- - Overrides where clipboard-pasted images are cached.
107
- - Default: `%TEMP%\pi-image-tools\recent-cache`
87
+ ## Configuration
108
88
 
109
- ## Preview rendering (native vs Sixel)
89
+ ### Environment Variables
110
90
 
111
- When Pi displays a user message that contains image attachments, `pi-image-tools` renders an inline preview block under the message.
91
+ | Variable | Description | Default |
92
+ |----------------------------------|--------------------------------------------------|---------------------------------------|
93
+ | `PI_IMAGE_TOOLS_RECENT_DIRS` | Semicolon-separated directories to search | See default locations below |
94
+ | `PI_IMAGE_TOOLS_RECENT_CACHE_DIR`| Custom cache directory for clipboard images | `%TEMP%\pi-image-tools\recent-cache` |
112
95
 
113
- - **Sixel preview (Windows):**
114
- - The extension tries to detect (and, if missing, install) the PowerShell module `Sixel` under the current user.
115
- - It then converts the image to a Sixel escape sequence via PowerShell and renders it inline.
116
- - **Native preview fallback:**
117
- - If Sixel is unavailable or conversion fails, the extension renders via `@mariozechner/pi-tui`’s `Image` component.
118
- - When a fallback is used, a warning line may be shown under the preview (and a one-time warning notification can appear on session start).
96
+ **Example:**
119
97
 
120
- Limit: only the first **3** images in a message are previewed.
98
+ ```powershell
99
+ $env:PI_IMAGE_TOOLS_RECENT_DIRS = "C:\Users\me\Pictures\Screenshots;D:\Shares\Screens"
100
+ ```
121
101
 
122
- ## Dependencies / PowerShell notes
102
+ ### Default Search Locations
123
103
 
124
- ### Clipboard access
104
+ The recent picker searches these Windows paths:
125
105
 
126
- - **Optional native module:** `@mariozechner/clipboard` (declared as an optional dependency).
127
- - If it is available, `pi-image-tools` uses it first.
128
- - **PowerShell fallback (Windows):** if the native module is unavailable, the extension calls `powershell.exe` to read an image from the clipboard using .NET (`System.Windows.Forms.Clipboard`).
106
+ 1. **Cache directory** – Images previously pasted from clipboard
107
+ 2. `~/Pictures/Screenshots`
108
+ 3. `~/OneDrive/Pictures/Screenshots`
109
+ 4. `~/Desktop` – Only files with screenshot-like names (`Screenshot*`, `Snip*`, `IMG_*`, etc.)
129
110
 
130
- ### Sixel module
111
+ ### Supported Image Formats
131
112
 
132
- - Sixel preview uses the **PowerShell module** `Sixel`.
133
- - `pi-image-tools` attempts to install it automatically (CurrentUser scope) using either `Install-Module` or `Install-PSResource` (depending on what your PowerShell supports).
113
+ `.png`, `.jpg`, `.jpeg`, `.webp`, `.gif`, `.bmp`
134
114
 
135
- If your environment blocks module installation, you can install it manually (in a PowerShell prompt):
115
+ ### Runtime Config
136
116
 
137
- ```powershell
138
- Install-Module -Name Sixel -Scope CurrentUser -Force -AllowClobber
139
- ```
140
-
141
- ## Configuration
142
-
143
- Runtime config is stored at:
117
+ A configuration file can be placed at:
144
118
 
145
119
  ```text
146
120
  ~/.pi/agent/extensions/pi-image-tools/config.json
147
121
  ```
148
122
 
149
- A starter file is included as:
123
+ See `config/config.example.json` for the template:
150
124
 
151
- ```text
152
- config/config.example.json
125
+ ```json
126
+ {
127
+ "enabled": true
128
+ }
153
129
  ```
154
130
 
155
- Currently the template only contains:
131
+ ## Technical Details
156
132
 
157
- ```json
158
- { "enabled": true }
159
- ```
133
+ ### Preview Rendering
160
134
 
161
- ## Troubleshooting
135
+ When you send a message with images, the extension renders an inline preview:
162
136
 
163
- ### Nothing happens on `/paste-image` or shortcuts
137
+ | Mode | Description |
138
+ |--------|------------------------------------------------------------------|
139
+ | Sixel | High-quality graphics using PowerShell `Sixel` module (preferred)|
140
+ | Native | Fallback using `@mariozechner/pi-tui` Image component |
164
141
 
165
- - This extension is **Windows-only**. On non-Windows platforms it does not register `/paste-image`.
142
+ - Maximum **3 images** previewed per message
143
+ - Warnings displayed if Sixel is unavailable
166
144
 
167
- ### “/paste-image recent requires interactive TUI mode.”
145
+ ### Clipboard Access
168
146
 
169
- - The recent picker uses an interactive selection UI. Run Pi in interactive mode (TUI) and retry.
147
+ The extension uses multiple methods to read clipboard images:
170
148
 
171
- ### “No image found in clipboard.”
149
+ 1. **Native module** – `@mariozechner/clipboard` (optional dependency)
150
+ 2. **PowerShell fallback** – Uses `System.Windows.Forms.Clipboard` via PowerShell
172
151
 
173
- - Confirm you copied an actual image (not just a file path or text).
174
- - If clipboard reads are failing in general, PowerShell may be restricted by policy or your environment may not allow access to `System.Windows.Forms.Clipboard`.
152
+ ### Sixel Module Auto-Installation
175
153
 
176
- ### Recent picker is empty
154
+ The extension attempts to install the PowerShell `Sixel` module automatically (CurrentUser scope). If blocked by policy, install manually:
177
155
 
178
- - By default only a few directories are searched. Configure additional directories via `PI_IMAGE_TOOLS_RECENT_DIRS`.
179
- - Clipboard-pasted images are cached under `%TEMP%\pi-image-tools\recent-cache` (override with `PI_IMAGE_TOOLS_RECENT_CACHE_DIR`).
156
+ ```powershell
157
+ Install-Module -Name Sixel -Scope CurrentUser -Force -AllowClobber
158
+ ```
180
159
 
181
- ### Preview shows a warning about Sixel
160
+ ### Architecture
182
161
 
183
- - The extension falls back to native preview when the `Sixel` PowerShell module is missing or cannot be installed.
184
- - Install the module manually (see above) and restart Pi.
162
+ | File | Purpose |
163
+ |---------------------------|---------------------------------------------------|
164
+ | `index.ts` | Root entrypoint for Pi auto-discovery |
165
+ | `src/commands.ts` | `/paste-image` command registration |
166
+ | `src/keybindings.ts` | Keyboard shortcut registration |
167
+ | `src/clipboard.ts` | Clipboard image reading (native + PowerShell) |
168
+ | `src/recent-images.ts` | Recent image discovery and cache management |
169
+ | `src/image-preview.ts` | Preview building and Sixel conversion |
170
+ | `src/inline-user-preview.ts` | TUI message patching for inline previews |
171
+ | `src/temp-file.ts` | Temporary file management with cleanup |
172
+ | `src/types.ts` | TypeScript type definitions |
173
+
174
+ ## Troubleshooting
175
+
176
+ | Issue | Solution |
177
+ |-------|----------|
178
+ | Nothing happens on `/paste-image` | Ensure you're on Windows. This extension is Windows-only. |
179
+ | "requires interactive TUI mode" | Run Pi in interactive TUI mode to use the recent picker. |
180
+ | "No image found in clipboard" | Confirm you copied an actual image, not a file path or text. |
181
+ | Recent picker is empty | Add directories via `PI_IMAGE_TOOLS_RECENT_DIRS` or paste images from clipboard first. |
182
+ | Sixel warning shown | Install the Sixel module manually (see above) and restart Pi. |
185
183
 
186
184
  ## Development
187
185
 
188
186
  ```bash
187
+ # Type-check (build)
189
188
  npm run build
189
+
190
+ # Lint
190
191
  npm run lint
192
+
193
+ # Run tests
191
194
  npm run test
195
+
196
+ # All checks
192
197
  npm run check
193
198
  ```
194
199
 
195
- ## Project layout
196
-
197
- - `index.ts` - root Pi auto-discovery entrypoint
198
- - `src/commands.ts` - `/paste-image` command registration and argument handling
199
- - `src/keybindings.ts` - `alt+v` / `ctrl+alt+v` shortcut registration
200
- - `src/clipboard.ts` - clipboard image read (optional native module + PowerShell fallback)
201
- - `src/recent-images.ts` - recent discovery + cache management (`PI_IMAGE_TOOLS_RECENT_DIRS`, `PI_IMAGE_TOOLS_RECENT_CACHE_DIR`)
202
- - `src/image-preview.ts` - preview item building, Sixel conversion, and message renderer
203
- - `src/inline-user-preview.ts` - patches Pi TUI message rendering to show inline previews
204
-
205
200
  ## License
206
201
 
207
202
  MIT
package/asset/pi-image-tools.png ADDED
Binary file
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-image-tools",
3
- "version": "1.0.0",
3
+ "version": "1.0.2",
4
4
  "description": "Image attachment and rendering extension for Pi TUI",
5
5
  "type": "module",
6
6
  "main": "./index.ts",
@@ -11,6 +11,7 @@
11
11
  "index.ts",
12
12
  "src",
13
13
  "config/config.example.json",
14
+ "asset",
14
15
  "README.md",
15
16
  "CHANGELOG.md",
16
17
  "LICENSE"