tmux-ide 2.9.7 → 2.9.8

package/packages/daemon/src/terminal/graphics/kitty-graphics.ts

@@ -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,
@@ -356,12 +356,13 @@ export interface KittyImageStoreOptions {
   readonly budget?: KittyImageBudget;
 }
 
-/** 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 {
   readonly #images = new Map<number, KittyImage>();
   readonly #used = new Map<number, number>();
   readonly #cursorPlacements: KittyCursorPlacement[] = [];
-  readonly #virtual = new Map<number, { columns: number; rows: number }>();
+  /** `U=1` virtual placements per image, by placement id (0 when unnamed). */
+  readonly #virtual = new Map<number, Map<number, { columns: number; rows: number }>>();
   #pending: { control: ReadonlyMap<string, string>; payload: string[]; bytes: number } | null =
     null;
   #nextAnonymous = 0x7f000000;
@@ -407,7 +408,7 @@ export class KittyImageStore {
     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(): void {
     if (this.#cursorPlacements.length === 0) return;
     this.#cursorPlacements.length = 0;
@@ -433,11 +434,16 @@ export class KittyImageStore {
     return this.#remove(victim);
   }
 
-  #remove(imageId: number): number {
+  #remove(imageId: number, keepPlacements = false): number {
     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);
@@ -470,7 +476,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;
     }
@@ -491,19 +497,16 @@ export class KittyImageStore {
       if (imageId === 0) imageId = this.#nextAnonymous++;
       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);
     if (!image) return;
@@ -512,7 +515,20 @@ 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,
@@ -539,7 +555,13 @@ export class KittyImageStore {
     payload: string,
   ): KittyImage | null {
     let data: Uint8Array = 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 });
       } catch {
@@ -547,7 +569,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: KittyImageFormat;
     let width: number;
     let height: number;
@@ -559,35 +580,115 @@ 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)) return null;
+      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;
     if (width < 1 || height < 1 || width > MAX_IMAGE_SIDE || height > MAX_IMAGE_SIDE) return null;
     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: number, control: ReadonlyMap<string, string>, payload: string): void {
+    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: Uint8Array;
+    let patch: Uint8Array = 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(): void {
+    while (
+      (this.#bytes > this.#budget.perPaneBytes || this.#images.size > MAX_IMAGES_PER_PANE) &&
+      this.#images.size > 0
+    )
+      this.evictOldest();
+    this.#budget.enforce();
+  }
+
   #delete(control: ReadonlyMap<string, string>): void {
     const what = control.get("d") ?? "a";
     const id = int(control, "i");
     const all = what === "a" || what === "A";
     const byId = (what === "i" || what === "I") && id !== 0;
     if (!all && !byId) return;
-    const keep = (imageId: number) => !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: number, placement: number) =>
+      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") this.#remove(id);
+    if (what === "I" && placementId === null) this.#remove(id);
   }
 
   /**
@@ -608,7 +709,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: TerminalGraphicsPlacement[] = [];
     for (const placement of this.#cursorPlacements) {
@@ -637,5 +738,19 @@ 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: ReadonlyMap<number, { columns: number; rows: number }> | undefined,
+): { columns: number; rows: number } | null {
+  if (!placements || placements.size === 0) return null;
+  return [...placements.values()].at(-1)!;
+}
 const MAX_IMAGE_SIDE = 10_000;
 const clampCells = (cells: number) => Math.max(1, Math.min(1_000, cells));

package/packages/daemon/src/terminal/mirror/mirror-service.ts

@@ -565,6 +565,17 @@ export class MirrorService {
     entry.channel.fitWindowViewport(semanticWindowId, cols, rows);
   }
 
+  setCellPixels(
+    session: string,
+    width: number,
+    height: number,
+    precise?: { width: number; height: number },
+  ): void {
+    const entry = this.channels.get(session);
+    if (!entry || entry.retired) return;
+    entry.channel.setCellPixels(width, height, precise);
+  }
+
   clearWindowViewports(session: string): void {
     const entry = this.channels.get(session);
     if (entry && !entry.retired) entry.channel.clearWindowViewports();

package/packages/daemon/src/terminal/mirror/session-channel.ts

@@ -1309,7 +1309,66 @@ export class SessionChannel {
     this.input.flush();
     this.clearWindowViewports();
     this.restoreWindowSizing(this.attachedIdentity?.runtimeSessionId ?? `=${this.opts.session}`);
-    this.io.send(`refresh-client -C ${cols}x${rows}`);
+    this.io.send(`refresh-client -C ${cols}x${rows}${this.cellPixelSuffix()}`);
+    this.clientViewport = { cols, rows };
+  }
+
+  private clientViewport: { cols: number; rows: number } | null = null;
+  private cellPixels: {
+    width: number;
+    height: number;
+    precise?: { width: number; height: number };
+  } | null = null;
+
+  /** "/WxH" for tmux's refresh-client -C (patched tmux; stock ignores it). */
+  private cellPixelSuffix(): string {
+    if (!this.cellPixels) return "";
+    const { width, height, precise } = this.cellPixels;
+    return `/${width}x${height}` + (precise ? `/${precise.width}x${precise.height}` : "");
+  }
+
+  /**
+   * The renderer's cell size in device pixels. tmux answers CSI 14t/16t and
+   * sets TIOCGWINSZ pixels from it, so image programs render 1:1 for the
+   * window. Re-applies the current viewport when the size changes.
+   */
+  setCellPixels(width: number, height: number, precise?: { width: number; height: number }): void {
+    if (
+      !Number.isSafeInteger(width) ||
+      !Number.isSafeInteger(height) ||
+      width < 1 ||
+      height < 1 ||
+      width > 1024 ||
+      height > 1024
+    )
+      throw new RangeError("cell pixel size out of range");
+    if (
+      precise &&
+      [precise.width, precise.height].some(
+        (value) => !Number.isSafeInteger(value) || value < 1000 || value > 1024000,
+      )
+    )
+      throw new RangeError("precise cell pixel size out of range");
+    if (
+      this.cellPixels?.width === width &&
+      this.cellPixels.height === height &&
+      this.cellPixels.precise?.width === precise?.width &&
+      this.cellPixels.precise?.height === precise?.height
+    )
+      return;
+    this.cellPixels = { width, height, ...(precise ? { precise } : {}) };
+    if (!this.geometryParticipating) return;
+    this.input.flush();
+    if (this.fittedWindows.size > 0) {
+      for (const [runtimeId, size] of this.fittedWindows)
+        if (this.windowsByRuntime.has(runtimeId))
+          this.io.send(
+            `refresh-client -C ${runtimeId}:${size.cols}x${size.rows}${this.cellPixelSuffix()}`,
+          );
+    } else if (this.clientViewport)
+      this.io.send(
+        `refresh-client -C ${this.clientViewport.cols}x${this.clientViewport.rows}${this.cellPixelSuffix()}`,
+      );
   }
 
   private restoreWindowSizing(target: string): void {
@@ -1359,7 +1418,7 @@ export class SessionChannel {
     if (previous?.cols === cols && previous.rows === rows) return;
     this.input.flush();
     this.restoreWindowSizing(window.runtimeId);
-    this.io.send(`refresh-client -C ${window.runtimeId}:${cols}x${rows}`);
+    this.io.send(`refresh-client -C ${window.runtimeId}:${cols}x${rows}${this.cellPixelSuffix()}`);
     this.fittedWindows.set(window.runtimeId, { cols, rows });
   }
 

package/packages/daemon/src/terminal/pane-stream/pane-stream-websocket.ts

@@ -1,3 +1,4 @@
+import { inflateSync } from "node:zlib";
 import { PaneStreamLayoutSnapshotFrameSchemaZ, type WindowLinkTopology } from "@tmux-ide/contracts";
 import type { TerminalDeliveryGraphics } from "../session-runtime/terminal-delivery-hub.ts";
 import { z } from "zod";
@@ -10,6 +11,11 @@ import {
   PANE_STREAM_REDEEM_PATH,
   PANE_STREAM_WEBSOCKET_SUBPROTOCOL,
   TERMINAL_GRAPHICS_BLOB_CHUNK_BYTES,
+  TERMINAL_GRAPHICS_CELL_PIXELS_CAPABILITY_VERSION,
+  TERMINAL_GRAPHICS_PRECISE_PIXELS_CAPABILITY_VERSION,
+  TERMINAL_GRAPHICS_LEGACY_MAX_IMAGE_BYTES,
+  TERMINAL_GRAPHICS_ZLIB_CAPABILITY_VERSION,
+  type TerminalGraphicsState,
   PaneStreamClientFrameSchemaZ,
   PaneStreamLoopbackWebSocketUrlSchemaZ,
   PaneStreamRedeemFrameSchemaZ,
@@ -305,6 +311,7 @@ export interface SessionRuntimePaneStreamTransportBinding {
     rows: number,
     semanticWindowId?: string,
   ): void;
+  setCellPixels?(width: number, height: number, precise?: { width: number; height: number }): void;
   close(): Promise<void>;
 }
 
@@ -1046,6 +1053,10 @@ interface PaneChannel {
   graphicsAnnounced: boolean;
   graphicsQueue: string[];
   graphicsSending: boolean;
+  /** Image id → digest last served; a replacement for the same id is pushed. */
+  graphicsServed: Map<number, string>;
+  graphicsState: TerminalGraphicsState | null;
+  graphicsZlib?: boolean;
 }
 
 interface QueuedSend {
@@ -1054,6 +1065,26 @@ interface QueuedSend {
 }
 
 const GRAPHICS_MAX_QUEUED_DIGESTS = 256;
+
+/** Graphics state as renderers without zlib support must see it. */
+export function rawGraphicsState(state: TerminalGraphicsState): TerminalGraphicsState {
+  const legacy = state.images.map((image): TerminalGraphicsState["images"][number] =>
+    image.format === "rgba-zlib" || image.format === "rgb-zlib"
+      ? {
+          ...image,
+          format: image.format === "rgba-zlib" ? "rgba" : "rgb",
+          bytes: image.width * image.height * (image.format === "rgba-zlib" ? 4 : 3),
+        }
+      : image,
+  );
+  const images = legacy.filter((image) => image.bytes <= TERMINAL_GRAPHICS_LEGACY_MAX_IMAGE_BYTES);
+  const kept = new Set(images.map((image) => image.digest));
+  return {
+    ...state,
+    images,
+    placements: state.placements.filter((placement) => kept.has(placement.digest)),
+  };
+}
 const GRAPHICS_SEND_WINDOW_BYTES = 2 * 1024 * 1024;
 
 export class PaneStreamLiveConnection {
@@ -1227,6 +1258,8 @@ export class PaneStreamLiveConnection {
         graphicsAnnounced: false,
         graphicsQueue: [],
         graphicsSending: false,
+        graphicsServed: new Map(),
+        graphicsState: null,
       });
     }
   }
@@ -1748,17 +1781,72 @@ export class PaneStreamLiveConnection {
   #startGraphics(channel: PaneChannel): void {
     const graphics = channel.delivery?.graphics;
     if (!graphics) return;
+    // Renderers that cannot inflate see raw formats; their bytes are inflated
+    // when served.
+    const zlib =
+      this.#descriptor.terminalDelivery?.protocolVersions.includes(
+        TERMINAL_GRAPHICS_ZLIB_CAPABILITY_VERSION,
+      ) === true;
+    channel.graphicsZlib = zlib;
+    // Renderers that report cell pixels learn up front that this daemon
+    // accepts them, before any image exists.
+    const cellPixels =
+      this.#descriptor.terminalDelivery?.protocolVersions.includes(
+        TERMINAL_GRAPHICS_CELL_PIXELS_CAPABILITY_VERSION,
+      ) === true;
+    const preciseCellPixels =
+      this.#descriptor.terminalDelivery?.protocolVersions.includes(
+        TERMINAL_GRAPHICS_PRECISE_PIXELS_CAPABILITY_VERSION,
+      ) === true;
+    let announced = false;
     graphics.subscribe((state) => {
+      announced = true;
       if (this.#closed || channel.closed) return;
       channel.graphicsAnnounced = true;
-      this.#sendFrame(null, { type: "terminal-graphics", pane: channel.semanticPaneId, state });
+      channel.graphicsState = state;
+      // A program redrawing one image id (every frame of an animation or a
+      // page) needs the new bytes at once: push them instead of waiting for
+      // the renderer's round trip.
+      const pushed: string[] = [];
+      for (const image of state.images) {
+        const served = channel.graphicsServed.get(image.imageId);
+        if (served !== undefined && served !== image.digest) pushed.push(image.digest);
+      }
+      this.#sendFrame(null, {
+        type: "terminal-graphics",
+        pane: channel.semanticPaneId,
+        state: {
+          ...(zlib ? state : rawGraphicsState(state)),
+          ...(cellPixels ? { cellPixels: true as const } : {}),
+          ...(preciseCellPixels ? { preciseCellPixels: true as const } : {}),
+        },
+      });
+      if (pushed.length > 0) this.#queueGraphics(channel, pushed);
     });
+    if (cellPixels && !announced && !this.#closed && !channel.closed) {
+      channel.graphicsAnnounced = true;
+      this.#sendFrame(null, {
+        type: "terminal-graphics",
+        pane: channel.semanticPaneId,
+        state: {
+          revision: 0,
+          images: [],
+          placements: [],
+          cellPixels: true,
+          ...(preciseCellPixels ? { preciseCellPixels: true as const } : {}),
+        },
+      });
+    }
   }
 
   #requestGraphics(pane: string, digests: readonly string[]): void {
     const channel = this.#panes.get(pane);
     // Requests are only meaningful after an announcement; ignore stray ones.
     if (!channel || channel.closed || !channel.graphicsAnnounced) return;
+    this.#queueGraphics(channel, digests);
+  }
+
+  #queueGraphics(channel: PaneChannel, digests: readonly string[]): void {
     for (const digest of digests)
       if (
         !channel.graphicsQueue.includes(digest) &&
@@ -1778,28 +1866,49 @@ export class PaneStreamLiveConnection {
     try {
       while (!this.#closed && !channel.closed && channel.graphicsQueue.length > 0) {
         const digest = channel.graphicsQueue.shift()!;
-        const image = channel.delivery?.graphics?.image(digest);
-        if (!image) continue;
-        const total = image.data.byteLength;
+        const graphics = channel.delivery?.graphics;
+        const image = graphics?.image(digest);
+        if (!graphics || !image) continue;
+        for (const entry of channel.graphicsState?.images ?? [])
+          if (entry.digest === digest) channel.graphicsServed.set(entry.imageId, digest);
+        const raw = !channel.graphicsZlib && image.format.endsWith("-zlib");
+        let data: Uint8Array = image.data;
+        if (raw) {
+          const expected = image.width * image.height * (image.format === "rgba-zlib" ? 4 : 3);
+          if (expected < 1 || expected > TERMINAL_GRAPHICS_LEGACY_MAX_IMAGE_BYTES) continue;
+          try {
+            data = inflateSync(image.data, { maxOutputLength: expected });
+          } catch {
+            continue;
+          }
+          if (data.byteLength !== expected) continue;
+        }
+        if (!channel.graphicsZlib && data.byteLength > TERMINAL_GRAPHICS_LEGACY_MAX_IMAGE_BYTES)
+          continue;
+        const format = raw ? (image.format === "rgba-zlib" ? "rgba" : "rgb") : image.format;
+        const total = data.byteLength;
         for (let offset = 0; offset < total; offset += TERMINAL_GRAPHICS_BLOB_CHUNK_BYTES) {
           while ((this.#socket.bufferedAmount ?? 0) > GRAPHICS_SEND_WINDOW_BYTES) {
             if (this.#closed || channel.closed) return;
             await new Promise((resolve) => setTimeout(resolve, 5));
           }
           if (this.#closed || channel.closed) return;
+          // A superseded frame (the id was redrawn) is abandoned mid-transfer;
+          // the renderer drops the partial image and shows the newer one.
+          if (offset > 0 && graphics.image(digest) !== image) break;
           const end = Math.min(total, offset + TERMINAL_GRAPHICS_BLOB_CHUNK_BYTES);
           this.#sendFrame(null, {
             type: "terminal-graphics-blob",
             pane: channel.semanticPaneId,
             blob: {
               digest,
-              format: image.format,
+              format,
               width: image.width,
               height: image.height,
               total,
               offset,
             },
-            data: Buffer.from(image.data.subarray(offset, end)).toString("base64"),
+            data: Buffer.from(data.subarray(offset, end)).toString("base64"),
           });
         }
       }
@@ -2383,6 +2492,14 @@ export class PaneStreamLiveConnection {
       this.#requestGraphics(frame.pane, frame.digests);
       return;
     }
+    if (frame.type === "terminal-cell-pixels") {
+      try {
+        this.#sessionRuntimeBinding?.setCellPixels?.(frame.width, frame.height, frame.precise);
+      } catch {
+        // A retired runtime simply keeps tmux's default cell size.
+      }
+      return;
+    }
     if (frame.type === "viewport") {
       if (
         !this.#descriptor.terminalDelivery ||

package/packages/daemon/src/terminal/session-runtime/registry.ts

@@ -256,6 +256,8 @@ export interface SessionRuntimeConsumer {
     rows: number,
     semanticWindowId?: string,
   ): void;
+  /** Renderer cell size in device pixels, forwarded to tmux. */
+  setCellPixels?(width: number, height: number, precise?: { width: number; height: number }): void;
   fitViewportWithAuthority(
     lease: SessionRuntimeAuthorityLease,
     cols: number,
@@ -1767,6 +1769,17 @@ class SessionRuntime {
     }
   }
 
+  /** Renderer cell size in device pixels; benign, so any connected client may set it. */
+  setCellPixels(
+    clientId: string,
+    width: number,
+    height: number,
+    precise?: { width: number; height: number },
+  ): void {
+    this.#assertConnected(clientId);
+    this.#mirror.setCellPixels?.(this.session, width, height, precise);
+  }
+
   fitViewportWithAuthority(
     clientId: string,
     lease: SessionRuntimeAuthorityLease,
@@ -2342,6 +2355,11 @@ class SessionRuntimeConsumerImpl implements SessionRuntimeConsumer {
     this.#runtime.fitViewport(this.clientId, lease, cols, rows, semanticWindowId);
   }
 
+  setCellPixels(width: number, height: number, precise?: { width: number; height: number }): void {
+    this.#assertOpen();
+    this.#runtime.setCellPixels(this.clientId, width, height, precise);
+  }
+
   fitViewportWithAuthority(
     lease: SessionRuntimeAuthorityLease,
     cols: number,

package/packages/daemon/src/terminal/session-runtime/terminal-replica-interpreter.ts

@@ -422,8 +422,17 @@ export class TerminalReplicaInterpreter {
       const previous = this.#backend;
       this.#backend = replacement;
       this.#attachKitty(replacement);
-      // tmux never saw cursor-anchored placements; a capture cannot restore them.
-      this.#kitty.dropCursorPlacements();
+      // A capture replay does not erase graphics already observed by this owner.
+      // Keep anchors only when both backends agree on their coordinate basis;
+      // reflow, history replacement and authoritative stream resets are ambiguous.
+      const sameGraphicsBasis =
+        operation.bootstrap === "painted-capture" &&
+        previous.cols === replacement.cols &&
+        previous.rows === replacement.rows &&
+        previous.graphicsViewportTop?.() !== undefined &&
+        previous.graphicsViewportTop?.() === replacement.graphicsViewportTop?.() &&
+        previous.modes().alternateScreen === replacement.modes().alternateScreen;
+      if (!sameGraphicsBasis) this.#kitty.dropCursorPlacements();
       this.#nativeReseedRequested = false;
       this.#scrollback = scrollback;
       this.#bootstrap = {
@@ -459,6 +468,8 @@ export class TerminalReplicaInterpreter {
       return;
     }
     if (operation.type === "resize") {
+      if (operation.cols !== this.#backend.cols || operation.rows !== this.#backend.rows)
+        this.#kitty.dropCursorPlacements();
       this.#causalCell?.fail("geometry-drift");
       if (this.#backend.modes().synchronizedOutput) {
         // Geometry is part of the admitted FIFO even while publication is
@@ -512,6 +523,11 @@ export class TerminalReplicaInterpreter {
     // Always forward the scanner's output: tmux splits %output (~2 KiB) inside
     // kitty APCs (~4 KiB chunks), so a chunk with no completed command can still
     // be all image payload that must never reach the VT parser as text.
+    // A chunk entirely inside image payload changes nothing the parser can
+    // see. Skipping it matters: every parser write settles on a later timer
+    // turn, so a frame split into dozens of %output chunks would otherwise
+    // serialize dozens of turns and fall behind a 30 fps image stream.
+    if (scanned.forward.byteLength === 0) return;
     await this.#writeToBackend(this.#backend, scanned.forward);
     if (this.#observability.enabled)
       this.#observability.recordSpan(