pi-image-preview 0.1.5 → 0.2.0

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.
package/README.md CHANGED
@@ -6,13 +6,16 @@ Image preview extension for [pi coding agent](https://github.com/badlogic/pi-mon
6
6
 
7
7
  ## Features
8
8
 
9
- - **Inline image preview** — paste an image (`Ctrl+V`) and a thumbnail renders above the editor
9
+ - **Inline image preview** — paste (`Ctrl+V`), drag-and-drop a file, or type a path, and a thumbnail renders above the editor
10
+ - **Drag-and-drop & spaces in paths** — recognizes backslash-escaped and single/double-quoted paths, so filenames containing spaces work
11
+ - **Any format, any size** — thumbnails are resized and converted to PNG (the format the kitty protocol transmits), so JPEG/WebP/GIF previews render and large images don't overflow the graphics transmission
10
12
  - **Horizontal layout** — multiple images display side by side
11
13
  - **tmux support** — uses kitty's Unicode placeholder protocol (`U=1`) so images are pane-aware (no ghosting across panes)
12
14
  - **Auto-cleanup** — delete the image path from editor text and the preview disappears
13
15
  - **No editor conflicts** — works alongside vim mode and other editor extensions (does not use `setEditorComponent`)
14
- - **Image resizing** — leverages pi's built-in WASM image resizer for efficient thumbnails
15
16
  - **Screenshot integration** — automatically inlines images from screenshot tool results
17
+ - **Chat images inside tmux** — images in the transcript (`read` results, pasted images) render inline in tmux, as they do in kitty outside tmux
18
+ - **Mixed clients** — when a non-kitty client (for example, a phone over SSH) views the same tmux session, images fall back to text so no kitty escape codes reach it
16
19
 
17
20
  ## Install
18
21
 
@@ -22,11 +25,11 @@ pi install npm:pi-image-preview
22
25
 
23
26
  ## How it works
24
27
 
25
- 1. **Paste** an image with `Ctrl+V`
26
- 2. Pi saves the clipboard to a temp file and inserts the path into the editor
27
- 3. The extension **detects the image path**, reads the file, and renders a thumbnail above the editor
28
- 4. The raw file path stays in the editor — the label below the thumbnail shows a truncated version
29
- 5. On **submit**, image paths are stripped from the text and the images are attached to your message
28
+ 1. **Add an image** — paste with `Ctrl+V`, drag a file onto the terminal, or type/paste a path
29
+ 2. For `Ctrl+V`, pi saves the clipboard to a temp file and inserts its path; drag-and-drop and typing insert the path directly
30
+ 3. The extension **detects the path** — including backslash-escaped or quoted paths that contain spaces — reads the file, and renders a thumbnail above the editor
31
+ 4. The thumbnail is resized and converted to PNG for a compact, reliably-rendered preview; the label below shows the filename
32
+ 5. On **submit**, the full-resolution image is attached to your message (the path text stays in the message)
30
33
 
31
34
  ## Prerequisites
32
35
 
@@ -65,7 +68,9 @@ This allows kitty graphics escape sequences to pass through tmux to the terminal
65
68
  - GIF (first frame)
66
69
  - WebP
67
70
 
68
- Maximum file size: **50 MB** (larger files are silently skipped).
71
+ Non-PNG formats are converted to PNG for display, since the kitty graphics protocol transmits PNG. Maximum file size: **50 MB** (larger files are silently skipped).
72
+
73
+ Images larger than **~5 MB** are automatically downscaled to fit the provider's per-image API limit before the message is submitted (the inline preview thumbnail is a separate, smaller image). The original file on disk is never modified.
69
74
 
70
75
  ## Limitations
71
76
 
@@ -74,9 +79,10 @@ Maximum file size: **50 MB** (larger files are silently skipped).
74
79
  - **tmux requires `allow-passthrough all`** — without it, images won't render inside tmux (the extension still works, but shows text fallback)
75
80
  - **No image selection/navigation** — this is a simple preview, not a gallery browser
76
81
  - **Thumbnail size is fixed** — images are scaled to fit within 25 columns; not configurable yet
77
- - **Images are not preserved in chat history** — after submitting, the preview clears; the image is sent as an attachment to the model
82
+ - **Attachment preview clears on submit** — the image is sent to the model and shown in the transcript instead (inside tmux, too)
78
83
  - **GIF animation** — only the first frame is displayed
79
84
  - **SSH sessions** — kitty graphics protocol does not work over SSH unless using `kitten ssh` (kitty's SSH kitten)
85
+ - **Inline chat images depend on pi internals** — tested against pi-tui 1.5.2; a pi update can change the private fields the patch reads, in which case chat images fall back to pi's default behaviour
80
86
  - **Multiple tmux panes showing pi** — each pane renders independently; switching panes clears/restores images correctly via Unicode placeholders, but rapid switching may briefly show artifacts
81
87
 
82
88
  ## How tmux support works
@@ -91,6 +97,14 @@ This extension uses kitty's **Unicode placeholder protocol** instead:
91
97
  4. Switching panes swaps the text buffer → placeholders disappear → image disappears
92
98
  5. Switching back → placeholders redrawn → image reappears
93
99
 
100
+ ### Which clients get images
101
+
102
+ Inside tmux, the environment (`KITTY_WINDOW_ID`, `TERM_PROGRAM`) describes the terminal that started the tmux server, not the terminals viewing the pane now. The extension asks tmux once a second which clients are attached to the pane's session:
103
+
104
+ - **Only kitty-protocol terminals** (kitty, Ghostty, WezTerm) — images render inline
105
+ - **Any other terminal attached** — text fallback, and no kitty commands are sent
106
+ - **Viewers change, or the window becomes visible** — pi redraws, and images are sent again to the terminals that missed them
107
+
94
108
  ## Development
95
109
 
96
110
  ```bash
package/index.ts CHANGED
@@ -1,59 +1,42 @@
1
- import { createRequire } from "node:module";
2
- import path from "node:path";
3
- import { pathToFileURL } from "node:url";
1
+ import { convertToPng, resizeImage } from "@earendil-works/pi-coding-agent";
4
2
  import {
5
3
  loadImageContentFromPath,
6
- maybeResizeImage,
7
4
  readImageContentFromPathAsync,
8
5
  type ImageResizer,
9
6
  } from "./src/image-content.ts";
10
7
  import { registerImagePreviewExtension } from "./src/extension-runtime.ts";
11
- import { debugLog } from "./src/debug.ts";
8
+ import { installInlineImages } from "./src/inline-images.ts";
9
+ import { resizeForPreview } from "./src/preview-resize.ts";
10
+ import { resizeForSubmission } from "./src/submission-resize.ts";
12
11
 
13
- let cachedResizerPromise: Promise<ImageResizer | null> | undefined;
12
+ // pi bundles the WASM image resizer and PNG converter and exposes them on its
13
+ // package entry. The extension is loaded through jiti, which aliases the
14
+ // "@earendil-works/*" specifier to the host build, so this import resolves to
15
+ // the running agent's implementation (no fragile filesystem lookup needed).
16
+ const buildPreviewThumbnail: ImageResizer = (image) =>
17
+ resizeForPreview(image, { resizeImage, convertToPng });
14
18
 
15
- async function loadPiImageResizer(): Promise<ImageResizer | null> {
16
- if (cachedResizerPromise) return cachedResizerPromise;
17
-
18
- cachedResizerPromise = (async () => {
19
- try {
20
- const require = createRequire(import.meta.url);
21
- const piEntry = require.resolve("@earendil-works/pi-coding-agent");
22
- const distDir = path.dirname(piEntry);
23
- const moduleUrl = pathToFileURL(
24
- path.join(distDir, "utils", "image-resize.js"),
25
- ).href;
26
- const mod = (await import(moduleUrl)) as {
27
- resizeImage?: (image: {
28
- type: "image";
29
- data: string;
30
- mimeType: string;
31
- }) => Promise<{ data: string; mimeType: string }>;
32
- };
33
- if (!mod.resizeImage) return null;
34
- return async (image) => {
35
- const resized = await mod.resizeImage!(image);
36
- return {
37
- type: "image",
38
- data: resized.data,
39
- mimeType: resized.mimeType,
40
- };
41
- };
42
- } catch (err) {
43
- debugLog("Failed to load pi image resizer", err);
44
- return null;
45
- }
46
- })();
47
-
48
- return cachedResizerPromise;
49
- }
19
+ // Cap the full-size attachment below the provider's per-image byte limit so a
20
+ // large image is downscaled before it is submitted (no PNG conversion needed).
21
+ const shrinkAttachmentForSubmission: ImageResizer = (image) =>
22
+ resizeForSubmission(image, { resizeImage });
50
23
 
51
24
  export default function (pi: any): void {
52
25
  registerImagePreviewExtension(pi, {
53
26
  readImageContentFromPathAsync,
54
- maybeResizeImage: async (image) =>
55
- maybeResizeImage(image, await loadPiImageResizer()),
56
- loadImageContentFromPath: async (filePath) =>
57
- loadImageContentFromPath(filePath, await loadPiImageResizer()),
27
+ maybeResizeImage: buildPreviewThumbnail,
28
+ resizeForSubmission: shrinkAttachmentForSubmission,
29
+ loadImageContentFromPath: (filePath) => loadImageContentFromPath(filePath),
30
+ });
31
+
32
+ // Chat images inline inside tmux, matching what pi draws in kitty or Rex.
33
+ let uninstall: (() => void) | undefined;
34
+ pi.on("session_start", (_event: unknown, ctx: { hasUI?: boolean }) => {
35
+ if (ctx.hasUI === false || uninstall) return;
36
+ uninstall = installInlineImages();
37
+ });
38
+ pi.on("session_shutdown", () => {
39
+ uninstall?.();
40
+ uninstall = undefined;
58
41
  });
59
42
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-image-preview",
3
- "version": "0.1.5",
3
+ "version": "0.2.0",
4
4
  "description": "Image preview extension for pi coding agent — renders inline image thumbnails above the editor using kitty graphics protocol with tmux support",
5
5
  "keywords": [
6
6
  "pi-package",
@@ -14,6 +14,10 @@
14
14
  "license": "MIT",
15
15
  "author": "rielj",
16
16
  "type": "module",
17
+ "scripts": {
18
+ "test": "vitest run",
19
+ "test:watch": "vitest"
20
+ },
17
21
  "files": [
18
22
  "index.ts",
19
23
  "src/",
@@ -30,6 +34,12 @@
30
34
  "url": "git+https://github.com/rielj/pi-image-preview.git"
31
35
  },
32
36
  "peerDependencies": {
33
- "@mariozechner/pi-coding-agent": "*"
37
+ "@earendil-works/pi-coding-agent": "*",
38
+ "@earendil-works/pi-tui": "*"
39
+ },
40
+ "devDependencies": {
41
+ "@earendil-works/pi-tui": "1.5.2",
42
+ "@types/node": "24.19.2",
43
+ "vitest": "^4.1.9"
34
44
  }
35
45
  }
@@ -1,6 +1,7 @@
1
1
  import path from "node:path";
2
2
  import type { ImageContent, ContentBlock } from "./content.ts";
3
3
  import { ImageGallery, type GalleryImage } from "./image-gallery.ts";
4
+ import { extractImagePaths } from "./image-paths.ts";
4
5
  import { upgradeScreenshotToolResult } from "./tool-result-upgrader.ts";
5
6
  import { debugLog } from "./debug.ts";
6
7
 
@@ -8,7 +9,10 @@ import { debugLog } from "./debug.ts";
8
9
 
9
10
  type TrackedImage = {
10
11
  filePath: string;
12
+ /** Full-resolution image attached to the submitted message. */
11
13
  image: ImageContent;
14
+ /** Small PNG thumbnail used only for the inline gallery preview. */
15
+ previewImage?: ImageContent;
12
16
  label: string;
13
17
  };
14
18
 
@@ -20,6 +24,9 @@ export type ExtensionDeps = {
20
24
  loadImageContentFromPath: (
21
25
  filePath: string,
22
26
  ) => Promise<ImageContent | null>;
27
+ /** Downscale the full-size attachment below the provider's per-image byte
28
+ * limit before it is submitted. Absent means submit the image unchanged. */
29
+ resizeForSubmission?: (image: ImageContent) => Promise<ImageContent>;
23
30
  };
24
31
 
25
32
  type PiLike = {
@@ -68,15 +75,6 @@ type ToolResultEvent = import("./tool-result-upgrader.ts").ToolResultEventLike;
68
75
  const WIDGET_KEY = "image-preview";
69
76
  const POLL_INTERVAL_MS = 250;
70
77
 
71
- // Matches image file paths:
72
- // - Absolute: /path/to/image.png
73
- // - Home-relative: ~/screenshots/image.png
74
- // - Relative: ./images/image.png, ../images/image.png
75
- // Supports common path characters including spaces (escaped with \),
76
- // parens, #, +, and other special characters.
77
- const IMAGE_PATH_RE =
78
- /((?:~\/|\.\.?\/|\/)[^\s:*?"<>|][^\s:*?"<>|]*\.(?:png|jpe?g|gif|webp))(?=\s|$)/gi;
79
-
80
78
  /** Produce a label from an image path — just the filename. */
81
79
  function trimImageLabel(filePath: string): string {
82
80
  return path.basename(filePath);
@@ -105,11 +103,14 @@ export function registerImagePreviewExtension(
105
103
  return;
106
104
  }
107
105
 
108
- const galleryImages: GalleryImage[] = [...tracked.values()].map((t) => ({
109
- data: t.image.data,
110
- mimeType: t.image.mimeType,
111
- label: t.label,
112
- }));
106
+ const galleryImages: GalleryImage[] = [...tracked.values()].map((t) => {
107
+ const preview = t.previewImage ?? t.image;
108
+ return {
109
+ data: preview.data,
110
+ mimeType: preview.mimeType,
111
+ label: t.label,
112
+ };
113
+ });
113
114
 
114
115
  // Dispose the previous gallery to free kitty image resources before replacement
115
116
  if (gallery) {
@@ -165,44 +166,46 @@ export function registerImagePreviewExtension(
165
166
  return;
166
167
  }
167
168
 
168
- // Find all image paths currently in the text
169
- // Create a fresh regex each time to avoid stale lastIndex from the `g` flag
170
- const imagePathRe = new RegExp(IMAGE_PATH_RE.source, IMAGE_PATH_RE.flags);
171
- const matches = [...text.matchAll(imagePathRe)];
169
+ // Find all image paths currently in the text. Handles plain, relative,
170
+ // home-relative, backslash-escaped, and quoted paths (typed, pasted, or
171
+ // inserted by drag-and-drop). Track by the exact editor substring (`raw`)
172
+ // so removal and submit matching stay in sync with the visible text, but
173
+ // read the file and build the label from the resolved `path`.
174
+ const detected = extractImagePaths(text);
172
175
  const currentPaths = new Set<string>();
173
176
 
174
177
  let changed = false;
175
178
 
176
- for (const match of matches) {
177
- const rawPath = match[1];
178
- if (!rawPath) continue;
179
- currentPaths.add(rawPath);
179
+ for (const { raw, path: filePath } of detected) {
180
+ currentPaths.add(raw);
180
181
 
181
182
  // Already tracked?
182
- if (tracked.has(rawPath)) continue;
183
+ if (tracked.has(raw)) continue;
183
184
 
184
185
  // New path — try to load it (async to avoid blocking event loop)
185
- const image = await deps.readImageContentFromPathAsync(rawPath);
186
+ const image = await deps.readImageContentFromPathAsync(filePath);
186
187
  if (!image) continue;
187
188
 
188
- tracked.set(rawPath, {
189
- filePath: rawPath,
189
+ tracked.set(raw, {
190
+ filePath,
190
191
  image,
191
- label: trimImageLabel(rawPath),
192
+ label: trimImageLabel(filePath),
192
193
  });
193
194
  changed = true;
194
195
 
195
- // Async resize in background
196
+ // Build the small PNG preview thumbnail in the background so a large
197
+ // image renders instead of overflowing kitty/tmux transmission. The
198
+ // full image stays in `entry.image` for the message attachment.
196
199
  if (deps.maybeResizeImage) {
197
- const entry = tracked.get(rawPath)!;
200
+ const entry = tracked.get(raw)!;
198
201
  void deps.maybeResizeImage(image).then((resized) => {
199
202
  // Guard against the entry having been removed while resize was in-flight
200
- if (tracked.has(rawPath) && tracked.get(rawPath) === entry) {
201
- entry.image = resized;
203
+ if (tracked.has(raw) && tracked.get(raw) === entry) {
204
+ entry.previewImage = resized;
202
205
  if (latestCtx) refreshWidget(latestCtx);
203
206
  }
204
207
  }).catch((err) => {
205
- debugLog(`Failed to resize image ${rawPath}`, err);
208
+ debugLog(`Failed to resize image ${filePath}`, err);
206
209
  });
207
210
  }
208
211
  }
@@ -293,14 +296,18 @@ export function registerImagePreviewExtension(
293
296
  return { action: "continue" };
294
297
  }
295
298
 
296
- // Collect images for all tracked paths in the submitted text
297
- const usedImages: ImageContent[] = [];
298
-
299
- for (const [trackedPath, entry] of tracked) {
300
- if (fullText.includes(trackedPath)) {
301
- usedImages.push(entry.image);
302
- }
303
- }
299
+ // Collect images for all tracked paths in the submitted text, resizing
300
+ // them concurrently while preserving their order in the submitted text.
301
+ const matched = [...tracked.entries()]
302
+ .filter(([trackedPath]) => fullText.includes(trackedPath))
303
+ .map(([, entry]) => entry);
304
+ const usedImages: ImageContent[] = await Promise.all(
305
+ matched.map((entry) =>
306
+ deps.resizeForSubmission
307
+ ? deps.resizeForSubmission(entry.image)
308
+ : Promise.resolve(entry.image),
309
+ ),
310
+ );
304
311
 
305
312
  if (usedImages.length === 0) {
306
313
  return { action: "continue" };
@@ -1,36 +1,16 @@
1
1
  import {
2
2
  type Component,
3
- getCapabilities,
4
- type ImageProtocol,
5
3
  getImageDimensions,
6
4
  calculateImageRows,
7
5
  getCellDimensions,
8
6
  } from "@earendil-works/pi-tui";
9
-
10
- /**
11
- * Detect image protocol support, working around pi-tui ≥0.67.6 which
12
- * hardcodes `images: null` inside tmux/screen for safety. Our extension
13
- * uses the Unicode placeholder protocol which is specifically designed
14
- * to work inside tmux, so we can safely detect kitty-in-tmux ourselves.
15
- */
16
- function detectImageProtocol(): ImageProtocol | null {
17
- const caps = getCapabilities();
18
- if (caps.images) return caps.images;
19
-
20
- // pi-tui returns null inside tmux — check if the outer terminal is kitty
21
- const inTmux = !!process.env.TMUX || (process.env.TERM?.toLowerCase() || "").startsWith("tmux");
22
- if (inTmux) {
23
- if (process.env.KITTY_WINDOW_ID || (process.env.TERM_PROGRAM?.toLowerCase() || "") === "kitty") {
24
- return "kitty";
25
- }
26
- // ghostty and wezterm also support kitty graphics in tmux
27
- const termProgram = process.env.TERM_PROGRAM?.toLowerCase() || "";
28
- if (termProgram === "ghostty" || process.env.GHOSTTY_RESOURCES_DIR) return "kitty";
29
- if (termProgram === "wezterm" || process.env.WEZTERM_PANE) return "kitty";
30
- }
31
-
32
- return null;
33
- }
7
+ import { detectImageProtocol, imageEpoch } from "./image-protocol.ts";
8
+ import {
9
+ allocateImageId,
10
+ buildPlaceholderRow,
11
+ deleteImage,
12
+ transmitImageWithPlaceholder,
13
+ } from "./kitty-placeholder.ts";
34
14
 
35
15
  export interface GalleryTheme {
36
16
  accent: (s: string) => string;
@@ -49,160 +29,6 @@ const THUMB_MAX_WIDTH = 25;
49
29
  const THUMB_MAX_ROWS = 15; // cap height so tall images don't overflow the terminal
50
30
  const GAP = 2; // columns between images
51
31
 
52
- // Monotonic counter for kitty image IDs — avoids birthday-paradox collisions
53
- // that occurred with the previous Math.random() * 254 approach.
54
- // Uses the full 24-bit range (1–16,777,215) supported by kitty's true-color encoding.
55
- let nextImageId = 1;
56
- function allocateImageId(): number {
57
- const id = nextImageId;
58
- nextImageId = (nextImageId % 0xffffff) + 1; // wrap at 16M, skip 0
59
- return id;
60
- }
61
-
62
- // ── Kitty Unicode Placeholder Protocol ─────────────────────
63
- // Instead of rendering pixels directly (which ghost across tmux panes),
64
- // we transmit the image data and then output U+10EEEE placeholder
65
- // characters with diacritics encoding row/col. Since these are just
66
- // text characters, tmux manages them per-pane — images appear/disappear
67
- // naturally when switching panes.
68
- //
69
- // Protocol:
70
- // 1. Transmit image: ESC_G a=T,U=1,f=100,i=<id>,c=<cols>,r=<rows>,q=2; base64 ESC\
71
- // 2. Print placeholder chars with foreground color set to image_id:
72
- // ESC[38;5;<id>m <U+10EEEE><row_diac><col_diac> ... ESC[39m
73
- //
74
- // Diacritics: row 0 = U+0305, row 1 = U+030D, row 2 = U+030E, etc.
75
- // See kitty docs rowcolumn-diacritics.txt
76
-
77
- // Row/column diacritics from kitty's rowcolumn-diacritics.txt
78
- // These are the combining characters used to encode row and column numbers
79
- const ROW_COL_DIACRITICS = [
80
- 0x0305, 0x030d, 0x030e, 0x0310, 0x0312, 0x033d, 0x033e, 0x033f,
81
- 0x0346, 0x034a, 0x034b, 0x034c, 0x0350, 0x0351, 0x0352, 0x0353,
82
- 0x0357, 0x035b, 0x0363, 0x0364, 0x0365, 0x0366, 0x0367, 0x0368,
83
- 0x0369, 0x036a, 0x036b, 0x036c, 0x036d, 0x036e, 0x036f, 0x0483,
84
- 0x0484, 0x0485, 0x0486, 0x0592, 0x0593, 0x0594, 0x0595, 0x0597,
85
- 0x0598, 0x0599, 0x059c, 0x059d, 0x059e, 0x059f, 0x05a0, 0x05a1,
86
- 0x05a8, 0x05a9, 0x05ab, 0x05ac, 0x05af, 0x05c4, 0x0610, 0x0611,
87
- 0x0612, 0x0613, 0x0614, 0x0615, 0x0616, 0x0617, 0x0618, 0x0619,
88
- 0x061a, 0x064b, 0x064c, 0x064d, 0x064e, 0x064f, 0x0650, 0x0651,
89
- 0x0652, 0x0653, 0x0654, 0x0655, 0x0656, 0x0657, 0x0658, 0x0659,
90
- 0x065a, 0x065b, 0x065c, 0x065d, 0x065e, 0x065f, 0x0670, 0x06d6,
91
- 0x06d7, 0x06d8, 0x06d9, 0x06da, 0x06db, 0x06dc, 0x06df, 0x06e0,
92
- 0x06e1, 0x06e2, 0x06e3, 0x06e4, 0x06e7, 0x06e8, 0x06ea, 0x06eb,
93
- 0x06ec, 0x06ed,
94
- ];
95
-
96
- const PLACEHOLDER_CHAR = String.fromCodePoint(0x10EEEE);
97
-
98
- function diacriticFor(n: number): string {
99
- if (n < ROW_COL_DIACRITICS.length) {
100
- return String.fromCodePoint(ROW_COL_DIACRITICS[n]);
101
- }
102
- // Fallback for very large values (shouldn't happen for thumbnails)
103
- return String.fromCodePoint(ROW_COL_DIACRITICS[0]);
104
- }
105
-
106
- function isInTmux(): boolean {
107
- return Boolean(process.env.TMUX);
108
- }
109
-
110
- /**
111
- * Wrap kitty APC sequences in DCS passthrough for tmux.
112
- */
113
- function wrapForTmux(sequence: string): string {
114
- if (!isInTmux()) return sequence;
115
- return sequence.replace(
116
- /\x1b_G([^\x1b]*)\x1b\\/g,
117
- (_match, content) =>
118
- `\x1bPtmux;\x1b\x1b_G${content}\x1b\x1b\\\x1b\\`,
119
- );
120
- }
121
-
122
- /**
123
- * Transmit image and create virtual placement using Unicode placeholder mode.
124
- * The image data is sent to kitty but NOT displayed directly.
125
- * Display happens via U+10EEEE placeholder characters.
126
- */
127
- function transmitImageWithPlaceholder(
128
- base64Data: string,
129
- imageId: number,
130
- columns: number,
131
- rows: number,
132
- ): void {
133
- // Transmit image + create virtual placement in one command
134
- // a=T: transmit and display, U=1: use unicode placeholders
135
- // q=2: suppress all responses (important in tmux)
136
- const CHUNK_SIZE = 4096;
137
-
138
- if (base64Data.length <= CHUNK_SIZE) {
139
- const seq = `\x1b_Ga=T,U=1,f=100,i=${imageId},c=${columns},r=${rows},q=2;${base64Data}\x1b\\`;
140
- process.stdout.write(wrapForTmux(seq));
141
- } else {
142
- // Chunked transfer
143
- let offset = 0;
144
- let isFirst = true;
145
- while (offset < base64Data.length) {
146
- const chunk = base64Data.slice(offset, offset + CHUNK_SIZE);
147
- const isLast = offset + CHUNK_SIZE >= base64Data.length;
148
- let seq: string;
149
-
150
- if (isFirst) {
151
- seq = `\x1b_Ga=T,U=1,f=100,i=${imageId},c=${columns},r=${rows},q=2,m=1;${chunk}\x1b\\`;
152
- isFirst = false;
153
- } else if (isLast) {
154
- seq = `\x1b_Gm=0;${chunk}\x1b\\`;
155
- } else {
156
- seq = `\x1b_Gm=1;${chunk}\x1b\\`;
157
- }
158
-
159
- process.stdout.write(wrapForTmux(seq));
160
- offset += CHUNK_SIZE;
161
- }
162
- }
163
- }
164
-
165
- /**
166
- * Delete a kitty image by ID.
167
- */
168
- function deleteImage(imageId: number): void {
169
- const seq = `\x1b_Ga=d,d=I,i=${imageId},q=2\x1b\\`;
170
- process.stdout.write(wrapForTmux(seq));
171
- }
172
-
173
- /**
174
- * Build a row of Unicode placeholder characters for the given image.
175
- * Uses foreground color to encode image_id, diacritics to encode row/col.
176
- */
177
- function buildPlaceholderRow(
178
- imageId: number,
179
- row: number,
180
- columns: number,
181
- ): string {
182
- // Set foreground color to image_id (using 24-bit true color for large IDs)
183
- const r = (imageId >> 16) & 0xff;
184
- const g = (imageId >> 8) & 0xff;
185
- const b = imageId & 0xff;
186
- const fgStart = imageId < 256
187
- ? `\x1b[38;5;${imageId}m`
188
- : `\x1b[38;2;${r};${g};${b}m`;
189
- const fgEnd = `\x1b[39m`;
190
-
191
- let line = fgStart;
192
-
193
- // First cell: full diacritics (row + col)
194
- line += PLACEHOLDER_CHAR + diacriticFor(row) + diacriticFor(0);
195
-
196
- // Subsequent cells: no diacritics needed — kitty auto-increments
197
- // column index from the left neighbor's col diacritic
198
- for (let col = 1; col < columns; col++) {
199
- line += PLACEHOLDER_CHAR;
200
- }
201
-
202
- line += fgEnd;
203
- return line;
204
- }
205
-
206
32
  // ── Gallery Component ──────────────────────────────────────
207
33
 
208
34
  /**
@@ -215,6 +41,7 @@ export class ImageGallery implements Component {
215
41
  private theme: GalleryTheme;
216
42
  private cachedLines?: string[];
217
43
  private cachedWidth?: number;
44
+ private cachedEpoch?: number;
218
45
  private activeImageIds: number[] = [];
219
46
 
220
47
  constructor(theme: GalleryTheme) {
@@ -232,22 +59,31 @@ export class ImageGallery implements Component {
232
59
  }
233
60
 
234
61
  dispose(): void {
235
- for (const id of this.activeImageIds) {
236
- deleteImage(id);
62
+ this.deleteActiveImages(detectImageProtocol());
63
+ }
64
+
65
+ /** Kitty commands would reach non-kitty viewers as junk; only forget IDs then. */
66
+ private deleteActiveImages(imageProtocol: string | null): void {
67
+ if (imageProtocol === "kitty") {
68
+ for (const id of this.activeImageIds) deleteImage(id);
237
69
  }
238
70
  this.activeImageIds = [];
239
71
  }
240
72
 
241
73
  render(width: number): string[] {
242
- if (this.cachedLines && this.cachedWidth === width) {
74
+ // A new epoch means a client joined that never received the image data.
75
+ if (
76
+ this.cachedLines &&
77
+ this.cachedWidth === width &&
78
+ this.cachedEpoch === imageEpoch()
79
+ ) {
243
80
  return this.cachedLines;
244
81
  }
82
+ this.cachedEpoch = imageEpoch();
245
83
 
84
+ const imageProtocol = detectImageProtocol();
246
85
  // Delete previous images before re-rendering
247
- for (const id of this.activeImageIds) {
248
- deleteImage(id);
249
- }
250
- this.activeImageIds = [];
86
+ this.deleteActiveImages(imageProtocol);
251
87
 
252
88
  if (this.images.length === 0) {
253
89
  this.cachedLines = [];
@@ -256,7 +92,6 @@ export class ImageGallery implements Component {
256
92
  }
257
93
 
258
94
  const lines: string[] = [];
259
- const imageProtocol = detectImageProtocol();
260
95
 
261
96
  // Header
262
97
  const count = this.images.length;
@@ -0,0 +1,46 @@
1
+ export interface DetectedImagePath {
2
+ /** Exact substring as it appears in the editor text (used for tracking/removal). */
3
+ raw: string;
4
+ /** Filesystem path with surrounding quotes stripped and shell escapes resolved. */
5
+ path: string;
6
+ }
7
+
8
+ const IMAGE_EXT = "(?:png|jpe?g|gif|webp)";
9
+ // A bare path segment is either a backslash-escaped character (e.g. "\ " for a
10
+ // space in a dragged path) or any character that is not whitespace or a
11
+ // shell/glob metacharacter.
12
+ const BARE_PATH = `(?:~/|\\.\\.?/|/)(?:\\\\.|[^\\s:*?"<>|])*\\.${IMAGE_EXT}(?=\\s|$)`;
13
+ // A double-quoted path may contain spaces verbatim; terminals quote dragged
14
+ // paths this way as an alternative to backslash-escaping.
15
+ // The closing quote must sit at a token boundary: it may be followed by
16
+ // whitespace, end of text, or punctuation (e.g. a comma), but not by another
17
+ // filename-ish character, so a trailing `"x.png"junk` does not match.
18
+ const QUOTE_END = "(?![A-Za-z0-9._-])";
19
+ const DOUBLE_QUOTED_PATH = `"(?:\\\\.|[^"\\\\])*\\.${IMAGE_EXT}"${QUOTE_END}`;
20
+ const SINGLE_QUOTED_PATH = `'(?:\\\\.|[^'\\\\])*\\.${IMAGE_EXT}'${QUOTE_END}`;
21
+ const IMAGE_PATH_RE = new RegExp(
22
+ `${DOUBLE_QUOTED_PATH}|${SINGLE_QUOTED_PATH}|${BARE_PATH}`,
23
+ "gi",
24
+ );
25
+
26
+ /** Strip surrounding quotes and resolve shell-style backslash escapes. */
27
+ function normalizePath(raw: string): string {
28
+ let value = raw;
29
+ const quoted =
30
+ (value.startsWith('"') && value.endsWith('"')) ||
31
+ (value.startsWith("'") && value.endsWith("'"));
32
+ if (quoted) {
33
+ value = value.slice(1, -1);
34
+ }
35
+ return value.replace(/\\(.)/g, "$1");
36
+ }
37
+
38
+ export function extractImagePaths(text: string): DetectedImagePath[] {
39
+ const re = new RegExp(IMAGE_PATH_RE.source, IMAGE_PATH_RE.flags);
40
+ const results: DetectedImagePath[] = [];
41
+ for (const match of text.matchAll(re)) {
42
+ const raw = match[0];
43
+ results.push({ raw, path: normalizePath(raw) });
44
+ }
45
+ return results;
46
+ }