tmux-ide 2.9.6 → 2.9.8

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

@@ -1189,8 +1189,21 @@ export interface MirrorControlChannelOptions {
   pauseAfterSeconds?: number;
   /** Qualification-only clock. Omitted in production's zero-observer path. */
   nowMicros?: () => number;
+  /** Ask tmux to acknowledge kitty graphics commands (patched tmux; stock ignores it). */
+  kittyGraphics?: boolean;
 }
 
+/**
+ * Server-wide, idempotent: `-q` keeps a stock tmux (no such option) quiet.
+ * Images reach this control client either way; the option only lets programs
+ * detect support, and the environment tells new panes' programs that this
+ * server's renderer shows placeholder images.
+ */
+export const KITTY_GRAPHICS_SETUP = [
+  "set-option -gq kitty-graphics on",
+  "set-environment -g TMUX_IDE_GRAPHICS kitty",
+] as const;
+
 export function mirrorControlAttachArgs(
   options: Pick<
     MirrorControlChannelOptions,
@@ -1348,7 +1361,11 @@ export class MirrorControlChannel implements MirrorChannelIo {
         this.core.fail(String(err));
         reject(err);
       });
-    }).then(() => this.initializeNativeViewer());
+    }).then(() => {
+      // One command per send: tmux answers a `;` list with one block per command.
+      if (this.opts.kittyGraphics) for (const command of KITTY_GRAPHICS_SETUP) this.send(command);
+      return this.initializeNativeViewer();
+    });
   }
 
   get nativeViewerIdentity(): NativeJournalIdentity | null {

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

@@ -79,6 +79,8 @@ export interface MirrorServiceOptions {
   /** `tmux -f <file>` — tests pass /dev/null. */
   configFile?: string;
   pauseAfterSeconds?: number;
+  /** Enable kitty graphics acknowledgements on attach (default: on unless TMUX_IDE_KITTY_GRAPHICS=0). */
+  kittyGraphics?: boolean;
   /** Explicit capture tail override. Omitted preserves native retained history. */
   historyLines?: number;
   internalReadHookEmission?: SessionChannelOptions["internalReadHookEmission"];
@@ -563,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();
@@ -737,6 +750,7 @@ export class MirrorService {
               nativeServerIdentity: this.opts.nativeServerIdentity,
               configFile: this.opts.configFile,
               pauseAfterSeconds: this.opts.pauseAfterSeconds,
+              kittyGraphics: this.opts.kittyGraphics ?? process.env.TMUX_IDE_KITTY_GRAPHICS !== "0",
               nowMicros: this.opts.nowMicros,
               nativeViewer: ownedViewer?.controlOptions(),
               nativeViewerReady: ownedViewer

package/packages/daemon/src/terminal/mirror/native-grid-capture.ts

@@ -1,3 +1,14 @@
+/** Upstream tmux 3.8 reuses -R for a textual grid dump, not our JSON extension.
+ * Require the generated grid and first-row headers; arbitrary malformed native
+ * replies must remain errors rather than silently downgrading capture fidelity.
+ */
+export function isStockRawGridCapture(lines: readonly string[]): boolean {
+  return (
+    /^G [1-9][0-9]*x[1-9][0-9]* \([0-9]+\/[0-9]+\)$/.test(lines[0] ?? "") &&
+    /^\tL 0 \((?:-|0)\) flags=/.test(lines[1] ?? "")
+  );
+}
+
 /** Private native capture experiment; this is not the canonical renderer schema. */
 export interface NativeGridCaptureCell {
   readonly flags: number;

package/packages/daemon/src/terminal/mirror/native-grid-reader.ts

@@ -1,5 +1,9 @@
 import type { MirrorChannelIo } from "./control-channel.ts";
-import { decodeNativeGridCapture, type NativeGridCapture } from "./native-grid-capture.ts";
+import {
+  decodeNativeGridCapture,
+  isStockRawGridCapture,
+  type NativeGridCapture,
+} from "./native-grid-capture.ts";
 
 export type NativeGridReadResult =
   | {
@@ -83,6 +87,11 @@ export class NativeGridCaptureReader {
               finish({ status: "changed" });
               return;
             }
+            if (isStockRawGridCapture(reply.lines)) {
+              this.unsupported = true;
+              finish({ status: "unsupported" });
+              return;
+            }
             const snapshot = decodeNativeGridCapture(reply.lines.join("\n"));
             finish(
               snapshot

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

@@ -10,6 +10,7 @@ import {
 import { boundedTmuxInteractionAppendCommand } from "../../lib/tmux-interaction-retention.ts";
 import {
   decodeNativeGridCapture,
+  isStockRawGridCapture,
   isNativeBootstrapCapture,
   type NativeGridCapture,
 } from "./native-grid-capture.ts";
@@ -212,7 +213,10 @@ function nativeBootstrapUnsupported(
   native: NativeGridCapture | null,
 ): boolean {
   if (ok)
-    return native !== null && (native.version !== 2 || native.currentAttributes === undefined);
+    return (
+      isStockRawGridCapture(lines) ||
+      (native !== null && (native.version !== 2 || native.currentAttributes === undefined))
+    );
   return lines.some((line) =>
     /^(?:parse error: )?(?:command capture-pane: )?unknown flag -R$/.test(line.trim()),
   );
@@ -345,6 +349,7 @@ interface SnapshotLease {
   cancelFence: (() => void) | null;
   cleanup?: () => void;
   ownsPause?: boolean;
+  attemptCharged?: boolean;
 }
 
 interface RecoveryRecord {
@@ -1304,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 {
@@ -1354,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 });
   }
 
@@ -1959,6 +2023,7 @@ export class SessionChannel {
       return;
     }
     recovery.attempts += 1;
+    lease.attemptCharged = true;
     recovery.stage = "stock-pause";
     recovery.stock = new StockPaneSnapshot(this.snapshotContext(pane));
     // These rows were received before this pause and belong to the new seed,
@@ -2135,6 +2200,7 @@ export class SessionChannel {
       return;
     }
     recovery.attempts += 1;
+    lease.attemptCharged = true;
     const ordinal = ++recovery.reseedOrdinal;
     const participants = [...pane.subs]
       .filter((sub) => !sub.closed && !sub.frozen)
@@ -2924,6 +2990,12 @@ export class SessionChannel {
         if (pane.windowRuntimeId !== change.windowId) continue;
         const recovery = this.recoveries.get(pane.runtimeId);
         if (recovery?.lease && !recovery.lease.retired) {
+          // A newer layout cancels this capture; it is not a failed snapshot.
+          // Refund only this lease, retaining earlier failures and the original deadline.
+          if (recovery.lease.attemptCharged) {
+            recovery.lease.attemptCharged = false;
+            recovery.attempts -= 1;
+          }
           this.awaitSnapshotLayout(recovery);
           this.retrySnapshot(recovery);
         }

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

@@ -1,4 +1,6 @@
+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";
 import {
   PANE_STREAM_MAX_HELD_DELTAS,
@@ -8,6 +10,12 @@ import {
   PANE_STREAM_PROTOCOL_VERSION,
   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,
@@ -303,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>;
 }
 
@@ -314,6 +323,7 @@ export interface SessionRuntimeTerminalDeliveryConnection {
   nack(nack: TerminalDeliveryNack): void;
   setVisibility(visibility: TerminalDeliveryVisibility): void;
   close(): Promise<void>;
+  readonly graphics?: TerminalDeliveryGraphics;
 }
 
 interface PendingTicket {
@@ -1039,6 +1049,14 @@ interface PaneChannel {
   frozenByWire: boolean;
   closed: boolean;
   batch: SeedBatch | null;
+  /** Kitty graphics: state announced to this client, and blob digests queued. */
+  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 {
@@ -1046,6 +1064,29 @@ interface QueuedSend {
   remaining: number;
 }
 
+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 {
   readonly #clientId: string;
   readonly #socket: DirectTerminalSocket;
@@ -1214,6 +1255,11 @@ export class PaneStreamLiveConnection {
         frozenByWire: false,
         closed: false,
         batch: null,
+        graphicsAnnounced: false,
+        graphicsQueue: [],
+        graphicsSending: false,
+        graphicsServed: new Map(),
+        graphicsState: null,
       });
     }
   }
@@ -1619,6 +1665,7 @@ export class PaneStreamLiveConnection {
         await this.#sendTerminalDelivery(channel.semanticPaneId, message);
       pending.length = 0;
       markReady();
+      this.#startGraphics(channel);
     }
     this.#closeIfAllPanesGone();
   }
@@ -1730,6 +1777,146 @@ export class PaneStreamLiveConnection {
     await this.#awaitSemanticCredit(pane);
   }
 
+  /** Announce the pane's kitty graphics state; the client pulls bytes it lacks. */
+  #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;
+      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) &&
+        channel.graphicsQueue.length < GRAPHICS_MAX_QUEUED_DIGESTS
+      )
+        channel.graphicsQueue.push(digest);
+    if (!channel.graphicsSending) void this.#drainGraphics(channel);
+  }
+
+  /**
+   * Blob bytes yield to terminal frames: each chunk waits until the socket's
+   * buffered bytes fall below a small window, so images never trip the
+   * socket-wide backpressure ceiling or delay a pane's next seed for long.
+   */
+  async #drainGraphics(channel: PaneChannel): Promise<void> {
+    channel.graphicsSending = true;
+    try {
+      while (!this.#closed && !channel.closed && channel.graphicsQueue.length > 0) {
+        const digest = channel.graphicsQueue.shift()!;
+        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,
+              width: image.width,
+              height: image.height,
+              total,
+              offset,
+            },
+            data: Buffer.from(data.subarray(offset, end)).toString("base64"),
+          });
+        }
+      }
+    } finally {
+      channel.graphicsSending = false;
+    }
+  }
+
   #awaitSemanticCredit(pane: string): Promise<void> {
     // Backpressure is pane-local. Aggregate pressure is guarded by the hard
     // socket ceiling in #drainNow, but must not let a noisy sibling prevent a
@@ -2301,6 +2488,18 @@ export class PaneStreamLiveConnection {
       this.#acceptSemanticIntent(frame.operationId, frame.intent);
       return;
     }
+    if (frame.type === "terminal-graphics-request") {
+      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/protocol/session-descriptor-discovery.ts

@@ -183,7 +183,6 @@ export function parseSessionPaneDescriptorReply(
       !bounded(type, 256) ||
       !bounded(currentCommand, 512) ||
       !bounded(cwd, 4_096) ||
-      !bounded(title, 1_024) ||
       !bounded(windowName, 1_024) ||
       !bounded(name, 256) ||
       !bounded(missionStamp, 256) ||
@@ -203,7 +202,9 @@ export function parseSessionPaneDescriptorReply(
       type: nonempty(type),
       currentCommand: nonempty(currentCommand),
       cwd: nonempty(cwd),
-      title: nonempty(title),
+      // Stock tmux turns any APC, including kitty graphics payloads, into the
+      // pane title; an overlong title names nothing and must not drop the pane.
+      title: bounded(title, 1_024) ? nonempty(title) : null,
       windowIndex,
       windowName: nonempty(windowName),
       windowId: /^@(?:0|[1-9][0-9]*)$/u.test(windowId) ? windowId : null,