tmux-ide 2.9.7 → 2.9.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tmux-ide",
-  "version": "2.9.7",
+  "version": "2.9.9",
   "description": "The open-source workspace for coding agents: run Claude Code, Codex and other agents in tmux with live status",
   "type": "module",
   "bin": {
@@ -105,7 +105,7 @@
     "test:tui-gallery": "bun test --preload @opentui/solid/preload --preload ./packages/daemon/test-support/opentui-renderer-preload.ts ./scripts/tui-gallery/gallery.test.tsx",
     "typecheck:tui-gallery": "tsc --noEmit -p scripts/tsconfig.tui-gallery.json",
     "test:spark-qualification": "node --import tsx --test scripts/lib/spark-*.test.ts scripts/lib/spark-*.test.mjs",
-    "test:installer": "node --test scripts/install.test.mjs",
+    "test:installer": "node --test scripts/install.test.mjs scripts/lib/installer-service-qualification.test.mjs",
     "qualify:styled-ssh": "node scripts/qualify-styled-ssh.mjs"
   },
   "keywords": [

package/packages/contracts/src/pane-stream.ts

@@ -360,6 +360,22 @@ export const PaneStreamTerminalGraphicsRequestFrameSchemaZ = z
   })
   .strict();
 
+/** The renderer's terminal cell size in device pixels (see capability 103). */
+export const PaneStreamTerminalCellPixelsFrameSchemaZ = z
+  .object({
+    type: z.literal("terminal-cell-pixels"),
+    width: z.number().int().min(1).max(1024),
+    height: z.number().int().min(1).max(1024),
+    precise: z
+      .object({
+        width: z.number().int().min(1000).max(1024000),
+        height: z.number().int().min(1000).max(1024000),
+      })
+      .strict()
+      .optional(),
+  })
+  .strict();
+
 export const PaneStreamClientFrameSchemaZ = z.union([
   PaneStreamInputFrameSchemaZ,
   PaneStreamConsumedFrameSchemaZ,
@@ -374,6 +390,7 @@ export const PaneStreamClientFrameSchemaZ = z.union([
   PaneStreamAuthorityReleaseFrameSchemaZ,
   PaneStreamClockProbeFrameSchemaZ,
   PaneStreamTerminalGraphicsRequestFrameSchemaZ,
+  PaneStreamTerminalCellPixelsFrameSchemaZ,
 ]);
 export type PaneStreamClientFrame = z.infer<typeof PaneStreamClientFrameSchemaZ>;
 

package/packages/contracts/src/terminal-graphics.ts

@@ -15,16 +15,39 @@ import { z } from "zod";
  * version; daemons that know it send graphics frames only to such renderers.
  */
 export const TERMINAL_GRAPHICS_CAPABILITY_VERSION = 101;
+/** Renderers that inflate `rgba-zlib`/`rgb-zlib` themselves offer this too. */
+export const TERMINAL_GRAPHICS_ZLIB_CAPABILITY_VERSION = 102;
+/**
+ * Renderers that report their cell size in device pixels offer this; the
+ * daemon then marks graphics state with `cellPixels: true` and accepts
+ * `terminal-cell-pixels`, so programs size images 1:1 for the window.
+ */
+export const TERMINAL_GRAPHICS_CELL_PIXELS_CAPABILITY_VERSION = 103;
+/** Thousandths of a device pixel, avoiding accumulated per-cell rounding. */
+export const TERMINAL_GRAPHICS_PRECISE_PIXELS_CAPABILITY_VERSION = 104;
 /** Raw image bytes per blob frame (base64 on the wire stays below 1 MiB). */
 export const TERMINAL_GRAPHICS_BLOB_CHUNK_BYTES = 512 * 1024;
-/** Largest single image a daemon publishes. */
-export const TERMINAL_GRAPHICS_MAX_IMAGE_BYTES = 32 * 1024 * 1024;
+/** Largest single image a daemon publishes (a 4K RGBA frame is ~33 MB). */
+export const TERMINAL_GRAPHICS_MAX_IMAGE_BYTES = 64 * 1024 * 1024;
+/** What renderers without the zlib capability accept. */
+export const TERMINAL_GRAPHICS_LEGACY_MAX_IMAGE_BYTES = 32 * 1024 * 1024;
 export const TERMINAL_GRAPHICS_MAX_IMAGES = 256;
 export const TERMINAL_GRAPHICS_MAX_PLACEMENTS = 256;
 export const TERMINAL_GRAPHICS_MAX_REQUEST_DIGESTS = 64;
 
 export const TerminalGraphicsDigestSchemaZ = z.string().regex(/^[0-9a-f]{32}$/u);
-export const TerminalGraphicsFormatSchemaZ = z.enum(["png", "rgba", "rgb"]);
+/**
+ * `*-zlib` carry raw pixels still deflated as the program sent them (`o=z`);
+ * only renderers that offered {@link TERMINAL_GRAPHICS_ZLIB_CAPABILITY_VERSION}
+ * receive them.
+ */
+export const TerminalGraphicsFormatSchemaZ = z.enum([
+  "png",
+  "rgba",
+  "rgb",
+  "rgba-zlib",
+  "rgb-zlib",
+]);
 export type TerminalGraphicsFormat = z.infer<typeof TerminalGraphicsFormatSchemaZ>;
 const Dimension = z.number().int().min(1).max(10_000);
 const Cells = z.number().int().min(1).max(1_000);
@@ -66,6 +89,9 @@ export const TerminalGraphicsStateSchemaZ = z
     revision: z.number().int().nonnegative(),
     images: z.array(TerminalGraphicsImageSchemaZ).max(TERMINAL_GRAPHICS_MAX_IMAGES),
     placements: z.array(TerminalGraphicsPlacementSchemaZ).max(TERMINAL_GRAPHICS_MAX_PLACEMENTS),
+    /** The daemon accepts `terminal-cell-pixels` (only sent to renderers offering 103). */
+    cellPixels: z.literal(true).optional(),
+    preciseCellPixels: z.literal(true).optional(),
   })
   .strict();
 export type TerminalGraphicsState = z.infer<typeof TerminalGraphicsStateSchemaZ>;

package/packages/core/src/kitty-placeholders.ts

@@ -158,7 +158,19 @@ export function resolveKittyPlacements(
   grid: readonly TerminalReplicaRow[],
   state: TerminalGraphicsState,
 ): TerminalGraphicsPlacement[] {
-  const placements: TerminalGraphicsPlacement[] = [];
+  return resolveKittyImagePlacements(grid, state).map(({ placement }) => placement);
+}
+
+/**
+ * As {@link resolveKittyPlacements}, with the kitty image id each placement
+ * shows: exact for placeholder cells (they encode it); for cursor placements
+ * the first image with that content.
+ */
+export function resolveKittyImagePlacements(
+  grid: readonly TerminalReplicaRow[],
+  state: TerminalGraphicsState,
+): { placement: TerminalGraphicsPlacement; imageId: number }[] {
+  const placements: { placement: TerminalGraphicsPlacement; imageId: number }[] = [];
   const byId = new Map(state.images.map((image) => [image.imageId, image]));
   let scan = false;
   for (const image of state.images) if (image.placeholder) scan = true;
@@ -173,18 +185,24 @@ export function resolveKittyPlacements(
       )
         continue;
       placements.push({
-        digest: image.digest,
-        row: rect.row,
-        column: rect.column,
-        rows: rect.rows,
-        columns: rect.columns,
-        sourceRow: rect.srcRow,
-        sourceColumn: rect.srcCol,
-        totalRows: virtualGrid.rows,
-        totalColumns: virtualGrid.columns,
+        imageId: image.imageId,
+        placement: {
+          digest: image.digest,
+          row: rect.row,
+          column: rect.column,
+          rows: rect.rows,
+          columns: rect.columns,
+          sourceRow: rect.srcRow,
+          sourceColumn: rect.srcCol,
+          totalRows: virtualGrid.rows,
+          totalColumns: virtualGrid.columns,
+        },
       });
     }
   }
-  placements.push(...state.placements);
+  for (const placement of state.placements) {
+    const image = state.images.find((candidate) => candidate.digest === placement.digest);
+    if (image) placements.push({ placement, imageId: image.imageId });
+  }
   return placements;
 }

package/packages/daemon/dist/native/TmuxIdeNotifier.app/Contents/Info.plist

@@ -21,9 +21,9 @@
   <key>CFBundlePackageType</key>
   <string>APPL</string>
   <key>CFBundleShortVersionString</key>
-  <string>2.9.7</string>
+  <string>2.9.9</string>
   <key>CFBundleVersion</key>
-  <string>2.9.7</string>
+  <string>2.9.9</string>
   <key>LSMinimumSystemVersion</key>
   <string>11.0</string>
   <key>LSUIElement</key>

package/packages/daemon/dist/native/TmuxIdeNotifier.app/Contents/_CodeSignature/CodeResources

@@ -10,7 +10,7 @@
 		</data>
 		<key>Resources/Assets.car</key>
 		<data>
-		Qm5AzGjCw77rGEStuJKTDz8K1aw=
+		SmelhC8h5DucT+rzFXGF+vwuM4M=
 		</data>
 	</dict>
 	<key>files2</key>
@@ -26,7 +26,7 @@
 		<dict>
 			<key>hash2</key>
 			<data>
-			ZcHZD0tqsRi0ialJfr0XsFGJNpXz+YpfH7HT9lYpqVI=
+			jOmbXxbTijoy+G+1Ruyi6wQKiSnUSw3V8mkHnJwyMlg=
 			</data>
 		</dict>
 	</dict>

package/packages/daemon/dist/native/tmux/darwin-arm64/manifest.json

@@ -25,7 +25,11 @@
     },
     {
       "patch": "kitty-graphics.patch",
-      "patchSha256": "4a9a34701f0e31e48fe5ccc27bc31a53cb50b7bf24a871ba99cb1c72a411ea43"
+      "patchSha256": "1ff7b3022aa2a3d7014b7339c0f2ae868292d5d6df3c668cefa403509ecbc1f6"
+    },
+    {
+      "patch": "precise-cell-pixels.patch",
+      "patchSha256": "11b2f09f347d0369a744be5aef14e7be3407f4bfa6cae2047b9477234a01ba24"
     }
   ],
   "experimentalExtensions": [
@@ -44,7 +48,7 @@
   "platform": "darwin",
   "arch": "arm64",
   "files": {
-    "tmux": "e06c32b2173353c53e2b3e3e6cfb3db4aba06164e1d923d3463e3b72edc4f976",
+    "tmux": "78b5efc7cb7308e892487a0ea046c531a271680c812c8b8851796dbdf57b0fe8",
     "lib/libutf8proc.3.3.0.dylib": "da17133f84767a9873ff61402ac1a9d6a19ddfc1efb90cffc7c894df68532ce2",
     "lib/libncursesw.6.dylib": "c9b3c77b5874b0c694590774f7b7b1568b2bb13e82707bdf29cb7296446fe596",
     "lib/libevent_core-2.1.7.dylib": "65a205eee103b07356c1d6b1102b6b6ca08b0abaad44d960a0dad809722d0a9d",

package/packages/daemon/dist/native/tmux/linux-arm64/manifest.json

@@ -25,7 +25,11 @@
     },
     {
       "patch": "kitty-graphics.patch",
-      "patchSha256": "4a9a34701f0e31e48fe5ccc27bc31a53cb50b7bf24a871ba99cb1c72a411ea43"
+      "patchSha256": "1ff7b3022aa2a3d7014b7339c0f2ae868292d5d6df3c668cefa403509ecbc1f6"
+    },
+    {
+      "patch": "precise-cell-pixels.patch",
+      "patchSha256": "11b2f09f347d0369a744be5aef14e7be3407f4bfa6cae2047b9477234a01ba24"
     }
   ],
   "experimentalExtensions": [
@@ -72,7 +76,7 @@
   "platform": "linux",
   "arch": "arm64",
   "files": {
-    "tmux": "d6e98ac909428ddd6e0038437cf78a4e8e4b21ecd12c1d800cfe7c8864307d8f",
+    "tmux": "23ce24278d4c778f6ce974c492e46fcc09e20de577125a841f1d5f91b21a79ce",
     "lib/libutf8proc.so.3": "83cd7bce65037a46494b154b0f7bfd2479bc1659f56321b9ec896f4b64fb490c",
     "lib/libtinfo.so.6": "22952a4f434fd0f356fad23b92de42084e6666d8a594eadd11511b059cc5bb66",
     "lib/libevent_core-2.1.so.7": "80ad9f14cdea14f65c7a778fef4d831d51d23edc55efd263d7f265587eab73d4",

package/packages/daemon/dist/native/tmux/linux-x64/manifest.json

@@ -25,7 +25,11 @@
     },
     {
       "patch": "kitty-graphics.patch",
-      "patchSha256": "4a9a34701f0e31e48fe5ccc27bc31a53cb50b7bf24a871ba99cb1c72a411ea43"
+      "patchSha256": "1ff7b3022aa2a3d7014b7339c0f2ae868292d5d6df3c668cefa403509ecbc1f6"
+    },
+    {
+      "patch": "precise-cell-pixels.patch",
+      "patchSha256": "11b2f09f347d0369a744be5aef14e7be3407f4bfa6cae2047b9477234a01ba24"
     }
   ],
   "experimentalExtensions": [
@@ -72,7 +76,7 @@
   "platform": "linux",
   "arch": "x64",
   "files": {
-    "tmux": "5e1c6631e090ce04ce3712b9f0143a492d74f9ff45624f4d8e838ad07596c6d3",
+    "tmux": "ef3549656f724cb37e5e94f718d9997570fb3cf55bdafa2585fa1f827e66ba3c",
     "lib/libutf8proc.so.3": "a5aa10c99ac2e9a30c4e01fa4baa85a03dadf71eb73119c76fb3f9f54798962d",
     "lib/libtinfo.so.6": "170db4dd0c324ee73d8d5440a38708726066e1288aba942d57191c6f002240d9",
     "lib/libevent_core-2.1.so.7": "adf343350b739d3dba2b8a6cccbe0729cd9e9ee32b38ba69c08bd14f24a8431e",

package/packages/daemon/dist/terminal/attachments/native-runtime.js

@@ -583,6 +583,9 @@ function parsePaneSnapshot(stdout, expected) {
  * application-shell inventory. Names are resolved exactly to `$session_id`
  * before any pane query, and a second identity/topology snapshot closes races.
  */
+const INVENTORY_FENCE_ATTEMPTS = 4;
+/** 25, 50, 100 ms: enough for a mutation's identity stamps, bounded for every reader. */
+const settleDelay = (attempt) => new Promise((resolve) => setTimeout(resolve, 25 * 2 ** (attempt - 1)));
 export async function discoverWorkspaceRegistryTerminalInventory(registry, runner, signal) {
     const workspaces = registry.list();
     if (workspaces.length > MAX_DISCOVERED_WORKSPACES) {
@@ -604,13 +607,6 @@ export async function discoverWorkspaceRegistryTerminalInventory(registry, runne
         const before = await requiredTmuxResult(runner, argv, signal);
         if (before === null)
             continue;
-        const first = parsePaneSnapshot(before, identity);
-        const panes = first.panes;
-        const after = await requiredTmuxResult(runner, argv, signal);
-        if (after === null)
-            throw new NativeTerminalAttachmentRuntimeError("discovery-failed");
-        const second = parsePaneSnapshot(after, identity);
-        const latest = second.panes;
         // Foreground commands, titles, focus and paths can change while the same
         // pane remains valid. Fence binding/topology only, then publish one complete
         // latest snapshot rather than mixing presentation values across reads.
@@ -625,12 +621,29 @@ export async function discoverWorkspaceRegistryTerminalInventory(registry, runne
             "windowStamp",
             "index",
         ];
-        if (first.linksProof !== second.linksProof ||
-            panes.length !== latest.length ||
-            panes.some((pane, index) => proofKeys.some((key) => pane[key] !== latest[index][key]))) {
-            throw new NativeTerminalAttachmentRuntimeError("discovery-failed");
+        const matches = (first, second) => first.linksProof === second.linksProof &&
+            first.panes.length === second.panes.length &&
+            first.panes.every((pane, index) => proofKeys.every((key) => pane[key] === second.panes[index][key]));
+        // A just-created window or split is still being stamped, so topology can
+        // move between two reads. Let it settle for a bounded number of re-reads;
+        // only two consecutive matching reads are ever published.
+        let previous = parsePaneSnapshot(before, identity);
+        let stable = null;
+        for (let attempt = 0; attempt < INVENTORY_FENCE_ATTEMPTS && !stable; attempt += 1) {
+            if (attempt > 0)
+                await settleDelay(attempt);
+            const after = await requiredTmuxResult(runner, argv, signal);
+            if (after === null)
+                throw new NativeTerminalAttachmentRuntimeError("discovery-failed");
+            const next = parsePaneSnapshot(after, identity);
+            if (matches(previous, next))
+                stable = next;
+            else
+                previous = next;
         }
-        bySessionName.set(sessionName, latest);
+        if (!stable)
+            throw new NativeTerminalAttachmentRuntimeError("discovery-failed");
+        bySessionName.set(sessionName, stable.panes);
     }
     const panes = [];
     for (const workspace of workspaces) {

package/packages/daemon/dist/terminal/graphics/kitty-graphics.js

@@ -18,7 +18,7 @@
  *    marker OSC the scanner substitutes in place of the APC, so the VT parser
  *    reports the cursor at the exact byte position. tmux never sees these
  *    placements: they do not move the cursor, do not follow reflow, and are
- *    dropped by a capture reseed.
+ *    kept across capture reseeds only when the coordinate basis is unchanged.
  *
  * Limits: direct transmission (`t=d`) only — file and shared-memory media
  * cannot cross machines; `a=d` handles all and by-id; animation, relative
@@ -26,7 +26,7 @@
  * from the patched tmux, in stream order (native/tmux/kitty-graphics.patch).
  */
 import { createHash } from "node:crypto";
-import { inflateSync } from "node:zlib";
+import { deflateSync, inflateSync } from "node:zlib";
 import { TERMINAL_GRAPHICS_MAX_IMAGE_BYTES, TERMINAL_GRAPHICS_MAX_IMAGES, TERMINAL_GRAPHICS_MAX_PLACEMENTS, } from "@tmux-ide/contracts";
 /** Private OSC used to mark an APC's byte position for the VT parser. */
 export const KITTY_PLACEMENT_OSC = 6974;
@@ -296,11 +296,12 @@ export const DEFAULT_KITTY_IMAGE_BUDGET = new KittyImageBudget({
     perPaneBytes: 64 * 1024 * 1024,
     globalBytes: 256 * 1024 * 1024,
 });
-/** Per-pane image store. Survives reseeds; cursor placements do not. */
+/** Per-pane image store. Survives reseeds; the interpreter validates cursor placement coordinates. */
 export class KittyImageStore {
     #images = new Map();
     #used = new Map();
     #cursorPlacements = [];
+    /** `U=1` virtual placements per image, by placement id (0 when unnamed). */
     #virtual = new Map();
     #pending = null;
     #nextAnonymous = 0x7f000000;
@@ -340,7 +341,7 @@ export class KittyImageStore {
         this.#used.clear();
         this.#bytes = 0;
     }
-    /** A capture reseed replaced the grid: tmux holds no record of cursor placements. */
+    /** The coordinate basis changed: tmux holds no record to restore cursor anchors. */
     dropCursorPlacements() {
         if (this.#cursorPlacements.length === 0)
             return;
@@ -366,12 +367,17 @@ export class KittyImageStore {
             return 0;
         return this.#remove(victim);
     }
-    #remove(imageId) {
+    #remove(imageId, keepPlacements = false) {
         const image = this.#images.get(imageId);
         if (!image)
             return 0;
         this.#images.delete(imageId);
         this.#used.delete(imageId);
+        if (keepPlacements) {
+            this.#bytes -= image.data.byteLength;
+            this.#revision += 1;
+            return image.data.byteLength;
+        }
         this.#virtual.delete(imageId);
         this.#bytes -= image.data.byteLength;
         const kept = this.#cursorPlacements.filter((p) => p.imageId !== imageId);
@@ -404,7 +410,7 @@ export class KittyImageStore {
             return;
         }
         const action = control.get("a") ?? "t";
-        if ((action === "t" || action === "T") && more) {
+        if ((action === "t" || action === "T" || action === "f") && more) {
             this.#pending = { control, payload: [command.payload], bytes: command.payload.length };
             return;
         }
@@ -425,18 +431,18 @@ export class KittyImageStore {
             const image = this.#decode(imageId, control, payload);
             if (!image)
                 return;
-            this.#remove(imageId);
+            // Re-transmitting an id replaces its pixels; its placements keep showing it.
+            this.#remove(imageId, true);
             this.#images.set(imageId, image);
             this.#bytes += image.data.byteLength;
             this.#used.set(imageId, this.#budget.nextTick());
             this.#revision += 1;
-            while ((this.#bytes > this.#budget.perPaneBytes || this.#images.size > MAX_IMAGES_PER_PANE) &&
-                this.#images.size > 1)
-                this.evictOldest();
-            this.#budget.enforce();
+            this.#enforceBudget();
             if (action === "t" || !this.#images.has(imageId))
                 return;
         }
+        if (action === "f")
+            return this.#editFrame(imageId, control, payload);
         if (action !== "T" && action !== "p")
             return;
         const image = this.#images.get(imageId);
@@ -447,7 +453,24 @@ export class KittyImageStore {
         const rows = clampCells(int(control, "r") || Math.ceil(image.height / this.#cellHeight));
         const placementId = int(control, "p");
         if (control.get("U") === "1") {
-            this.#virtual.set(imageId, { columns, rows });
+            const placements = this.#virtual.get(imageId) ?? new Map();
+            placements.set(placementId, { columns, rows });
+            this.#virtual.set(imageId, placements);
+            let count = 0;
+            for (const entries of this.#virtual.values())
+                count += entries.size;
+            for (const [id, entries] of this.#virtual) {
+                for (const placement of entries.keys()) {
+                    if (count <= TERMINAL_GRAPHICS_MAX_PLACEMENTS)
+                        break;
+                    entries.delete(placement);
+                    count -= 1;
+                }
+                if (entries.size === 0)
+                    this.#virtual.delete(id);
+                if (count <= TERMINAL_GRAPHICS_MAX_PLACEMENTS)
+                    break;
+            }
         }
         else if (cursor) {
             const existing = this.#cursorPlacements.findIndex((p) => p.imageId === imageId && placementId !== 0 && p.placementId === placementId);
@@ -469,7 +492,13 @@ export class KittyImageStore {
     }
     #decode(imageId, control, payload) {
         let data = Buffer.from(payload, "base64");
-        if (control.get("o") === "z") {
+        const f = int(control, "f", 32);
+        const zlib = control.get("o") === "z";
+        // Raw pixels stay compressed end to end: renderers inflate off their UI
+        // thread, and the stream carries a fraction of the bytes. PNG and other
+        // compressed payloads are inflated here.
+        const keepCompressed = zlib && (f === 32 || f === 24);
+        if (zlib && !keepCompressed) {
             try {
                 data = inflateSync(data, { maxOutputLength: TERMINAL_GRAPHICS_MAX_IMAGE_BYTES });
             }
@@ -479,7 +508,6 @@ export class KittyImageStore {
         }
         if (data.byteLength === 0 || data.byteLength > TERMINAL_GRAPHICS_MAX_IMAGE_BYTES)
             return null;
-        const f = int(control, "f", 32);
         let format;
         let width;
         let height;
@@ -493,9 +521,16 @@ export class KittyImageStore {
         else if (f === 32 || f === 24) {
             width = int(control, "s");
             height = int(control, "v");
-            format = f === 32 ? "rgba" : "rgb";
-            if (!width || !height || data.length !== width * height * (f === 32 ? 4 : 3))
+            const bytes = width * height * (f === 32 ? 4 : 3);
+            if (!width || !height || bytes > MAX_RAW_IMAGE_BYTES)
                 return null;
+            if (keepCompressed)
+                format = f === 32 ? "rgba-zlib" : "rgb-zlib";
+            else {
+                format = f === 32 ? "rgba" : "rgb";
+                if (data.length !== bytes)
+                    return null;
+            }
         }
         else
             return null;
@@ -504,6 +539,75 @@ export class KittyImageStore {
         const digest = createHash("sha256").update(data).digest("hex").slice(0, 32);
         return { imageId, format, width, height, data, digest };
     }
+    /**
+     * `a=f` edits of the root frame (`r=1`): RGBA/RGB rectangles written at
+     * `x,y`, replacing (`X=1`) or alpha-blending the existing pixels. New
+     * animation frames, `c` base frames and PNG data are not modelled.
+     */
+    #editFrame(imageId, control, payload) {
+        const image = this.#images.get(imageId);
+        if (!image || int(control, "r") !== 1 || (control.get("t") ?? "d") !== "d")
+            return;
+        const source = image.format === "rgba" || image.format === "rgba-zlib" ? 4 : 3;
+        if (image.format === "png")
+            return;
+        let pixels;
+        let patch = Buffer.from(payload, "base64");
+        try {
+            pixels =
+                image.format === "rgba-zlib" || image.format === "rgb-zlib"
+                    ? inflateSync(image.data, { maxOutputLength: MAX_RAW_IMAGE_BYTES })
+                    : Uint8Array.from(image.data);
+            if (control.get("o") === "z")
+                patch = inflateSync(patch, { maxOutputLength: MAX_RAW_IMAGE_BYTES });
+        }
+        catch {
+            return;
+        }
+        const f = int(control, "f", 32);
+        const depth = f === 24 ? 3 : 4;
+        const width = int(control, "s") || image.width;
+        const height = int(control, "v") || image.height;
+        const x0 = int(control, "x");
+        const y0 = int(control, "y");
+        if ((f !== 32 && f !== 24) || patch.length !== width * height * depth)
+            return;
+        if (pixels.length !== image.width * image.height * source)
+            return;
+        const replace = control.get("X") === "1";
+        for (let row = 0; row < height && y0 + row < image.height; row += 1)
+            for (let col = 0; col < width && x0 + col < image.width; col += 1) {
+                const from = (row * width + col) * depth;
+                const to = ((y0 + row) * image.width + x0 + col) * source;
+                const alpha = depth === 4 && !replace ? patch[from + 3] / 255 : 1;
+                for (let channel = 0; channel < 3; channel += 1)
+                    pixels[to + channel] = Math.round(patch[from + channel] * alpha + pixels[to + channel] * (1 - alpha));
+                if (source === 4)
+                    pixels[to + 3] =
+                        depth === 4 && replace
+                            ? patch[from + 3]
+                            : Math.round(255 * alpha + pixels[to + 3] * (1 - alpha));
+            }
+        const data = deflateSync(pixels, { level: 1 });
+        const format = source === 4 ? "rgba-zlib" : "rgb-zlib";
+        this.#remove(imageId, true);
+        this.#images.set(imageId, {
+            ...image,
+            format,
+            data,
+            digest: createHash("sha256").update(data).digest("hex").slice(0, 32),
+        });
+        this.#bytes += data.byteLength;
+        this.#used.set(imageId, this.#budget.nextTick());
+        this.#revision += 1;
+        this.#enforceBudget();
+    }
+    #enforceBudget() {
+        while ((this.#bytes > this.#budget.perPaneBytes || this.#images.size > MAX_IMAGES_PER_PANE) &&
+            this.#images.size > 0)
+            this.evictOldest();
+        this.#budget.enforce();
+    }
     #delete(control) {
         const what = control.get("d") ?? "a";
         const id = int(control, "i");
@@ -511,23 +615,28 @@ export class KittyImageStore {
         const byId = (what === "i" || what === "I") && id !== 0;
         if (!all && !byId)
             return;
-        const keep = (imageId) => !all && imageId !== id;
-        const kept = this.#cursorPlacements.filter((p) => keep(p.imageId));
+        // With `p`, only that placement of the image goes (spec: d=i/I with p).
+        const placementId = control.has("p") ? int(control, "p") : null;
+        const doomed = (imageId, placement) => all || (imageId === id && (placementId === null || placement === placementId));
+        const kept = this.#cursorPlacements.filter((p) => !doomed(p.imageId, p.placementId));
         if (kept.length !== this.#cursorPlacements.length) {
             this.#cursorPlacements.length = 0;
             this.#cursorPlacements.push(...kept);
             this.#revision += 1;
         }
-        for (const key of [...this.#virtual.keys()])
-            if (!keep(key)) {
-                this.#virtual.delete(key);
-                this.#revision += 1;
-            }
+        for (const [imageId, placements] of [...this.#virtual])
+            for (const placement of [...placements.keys()])
+                if (doomed(imageId, placement)) {
+                    placements.delete(placement);
+                    if (placements.size === 0)
+                        this.#virtual.delete(imageId);
+                    this.#revision += 1;
+                }
         // Upper-case variants also free the image data.
         if (what === "A")
             for (const key of [...this.#images.keys()])
                 this.#remove(key);
-        if (what === "I")
+        if (what === "I" && placementId === null)
             this.#remove(id);
     }
     /**
@@ -543,7 +652,7 @@ export class KittyImageStore {
             width: image.width,
             height: image.height,
             bytes: image.data.byteLength,
-            placeholder: this.#virtual.get(image.imageId) ?? null,
+            placeholder: virtualGrid(this.#virtual.get(image.imageId)),
         }));
         const placements = [];
         for (const placement of this.#cursorPlacements) {
@@ -574,5 +683,17 @@ export class KittyImageStore {
     }
 }
 const MAX_IMAGES_PER_PANE = TERMINAL_GRAPHICS_MAX_IMAGES;
+/** Largest decoded raw image (a 4K RGBA frame is ~33 MB). */
+const MAX_RAW_IMAGE_BYTES = 64 * 1024 * 1024;
+/**
+ * Placeholder cells carry the image id; with several virtual placements the
+ * protocol picks one by the placement id in the underline colour. Renderers
+ * resolve cells by image id, so publish the most recently placed grid.
+ */
+function virtualGrid(placements) {
+    if (!placements || placements.size === 0)
+        return null;
+    return [...placements.values()].at(-1);
+}
 const MAX_IMAGE_SIDE = 10_000;
 const clampCells = (cells) => Math.max(1, Math.min(1_000, cells));

package/packages/daemon/dist/terminal/mirror/mirror-service.js

@@ -369,6 +369,12 @@ export class MirrorService {
         this.assertWindowOwnership(session);
         entry.channel.fitWindowViewport(semanticWindowId, cols, rows);
     }
+    setCellPixels(session, width, height, precise) {
+        const entry = this.channels.get(session);
+        if (!entry || entry.retired)
+            return;
+        entry.channel.setCellPixels(width, height, precise);
+    }
     clearWindowViewports(session) {
         const entry = this.channels.get(session);
         if (entry && !entry.retired)