tmux-ide 2.9.6 → 2.9.7

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

@@ -0,0 +1,578 @@
+/**
+ * Kitty graphics protocol extraction for the daemon pane feed.
+ *
+ * tmux parses and drops APC sequences, so its grid never holds images. Its
+ * control-mode `%output` stream, however, carries the pane's raw bytes before
+ * that parse (octal-escaped, then decoded by `decodeControlBytes`), so the
+ * daemon sees every `ESC _ G … ESC \` intact — split across arbitrary
+ * `%output` lines. This module is the pure half: a streaming scanner, a
+ * control-key parser, and a budgeted per-pane image store.
+ *
+ * Placement models:
+ *
+ *  - Unicode placeholders (`U=1` virtual placement + U+10EEEE cells): the
+ *    position is ordinary grid text, so tmux keeps it through scroll, resize,
+ *    copy-mode and capture-pane. The store only records the image and its
+ *    virtual cell grid; renderers resolve the cells (`@tmux-ide/core`).
+ *  - cursor-anchored (`a=T`/`a=p` without `U=1`), best effort: positioned by a
+ *    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.
+ *
+ * Limits: direct transmission (`t=d`) only — file and shared-memory media
+ * cannot cross machines; `a=d` handles all and by-id; animation, relative
+ * placements and z-ordering are not modelled. Acknowledgements (`a=q`) come
+ * from the patched tmux, in stream order (native/tmux/kitty-graphics.patch).
+ */
+import { createHash } from "node:crypto";
+import { 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;
+const ESC = 0x1b;
+const MAX_COMMAND_BYTES = 32 * 1024 * 1024;
+const PASSTHROUGH_PREFIX = [0x74, 0x6d, 0x75, 0x78, 0x3b]; // "tmux;"
+/** PURE — parse `G<control>;<payload>` (the APC body after `ESC _`). */
+export function parseKittyCommand(body) {
+    if (!body.startsWith("G"))
+        return null;
+    const separator = body.indexOf(";");
+    const controlText = separator < 0 ? body.slice(1) : body.slice(1, separator);
+    const payload = separator < 0 ? "" : body.slice(separator + 1);
+    const control = new Map();
+    for (const pair of controlText.split(",")) {
+        if (!pair)
+            continue;
+        const eq = pair.indexOf("=");
+        if (eq !== 1)
+            return null;
+        control.set(pair[0], pair.slice(2));
+    }
+    return { control, payload };
+}
+/**
+ * Streaming extractor. One instance per pane feed; chunks may split any
+ * sequence at any byte. Also unwraps tmux DCS passthrough
+ * (`ESC P tmux; … ESC \` with doubled ESCs), which reaches control mode
+ * verbatim regardless of `allow-passthrough`.
+ */
+export class KittyApcScanner {
+    #state = "ground";
+    #held = [];
+    #body = [];
+    #bodyBytes = 0;
+    #prefixMatched = 0;
+    #inner = [];
+    #nextMarker = 1;
+    #overflowed = false;
+    scan(chunk) {
+        // Verbatim runs stay views of the chunk; ordinary output is never copied.
+        const parts = [];
+        const emit = (...bytes) => void parts.push(Uint8Array.from(bytes));
+        const commands = [];
+        let ground = -1; // start of a pending verbatim run
+        let escAt = -1; // index of a held ESC inside this chunk (-1: held from an earlier chunk)
+        const flushGround = (end) => {
+            if (ground >= 0) {
+                if (end > ground)
+                    parts.push(chunk.subarray(ground, end));
+                ground = -1;
+            }
+        };
+        const complete = (bodyBytes) => {
+            const command = parseKittyCommand(Buffer.from(bodyBytes).toString("latin1"));
+            if (!command)
+                return;
+            const marker = this.#nextMarker++;
+            commands.push({ ...command, marker });
+            parts.push(Buffer.from(`\x1b]${KITTY_PLACEMENT_OSC};${marker}\x07`, "latin1"));
+        };
+        for (let i = 0; i < chunk.length; i += 1) {
+            const byte = chunk[i];
+            switch (this.#state) {
+                case "ground":
+                    // The ESC stays in the verbatim run until it turns out to start an APC/DCS.
+                    if (ground < 0)
+                        ground = i;
+                    if (byte === ESC) {
+                        escAt = i;
+                        this.#held = [byte];
+                        this.#state = "esc";
+                    }
+                    break;
+                case "esc":
+                    if (byte === 0x5f || byte === 0x50) {
+                        if (escAt >= 0)
+                            flushGround(escAt);
+                        this.#held.push(byte);
+                        if (byte === 0x50)
+                            this.#prefixMatched = 0;
+                        this.#state = byte === 0x5f ? "apc-start" : "dcs-start";
+                    }
+                    else {
+                        if (escAt < 0) {
+                            emit(...this.#held);
+                            ground = i;
+                        }
+                        if (byte === ESC) {
+                            escAt = i;
+                            this.#held = [byte];
+                        }
+                        else {
+                            this.#held = [];
+                            this.#state = "ground";
+                        }
+                    }
+                    break;
+                case "apc-start":
+                    if (byte === 0x47) {
+                        this.#body = [Uint8Array.of(byte)];
+                        this.#bodyBytes = 1;
+                        this.#overflowed = false;
+                        this.#held = [];
+                        this.#state = "apc-body";
+                    }
+                    else {
+                        // Another APC: the VT parser ignores it; pass it through untouched.
+                        emit(...this.#held, byte);
+                        this.#held = [];
+                        this.#state = "ground";
+                    }
+                    break;
+                case "apc-body": {
+                    const end = chunk.indexOf(ESC, i);
+                    const stop = end < 0 ? chunk.length : end;
+                    if (!this.#overflowed && this.#bodyBytes + (stop - i) <= MAX_COMMAND_BYTES) {
+                        this.#body.push(chunk.subarray(i, stop).slice());
+                        this.#bodyBytes += stop - i;
+                    }
+                    else
+                        this.#overflowed = true;
+                    i = stop - 1;
+                    if (end >= 0) {
+                        i = end;
+                        this.#state = "apc-esc";
+                    }
+                    break;
+                }
+                case "apc-esc": {
+                    const body = this.#overflowed ? null : Buffer.concat(this.#body);
+                    this.#body = [];
+                    this.#bodyBytes = 0;
+                    if (body)
+                        complete(body);
+                    this.#state = "ground";
+                    // ESC \ is the terminator; anything else aborts the string and is reparsed.
+                    if (byte !== 0x5c) {
+                        this.#state = "esc";
+                        this.#held = [ESC];
+                        escAt = -1;
+                        i -= 1;
+                    }
+                    break;
+                }
+                case "dcs-start":
+                    if (byte === PASSTHROUGH_PREFIX[this.#prefixMatched]) {
+                        this.#held.push(byte);
+                        this.#prefixMatched += 1;
+                        if (this.#prefixMatched === PASSTHROUGH_PREFIX.length) {
+                            this.#held = [];
+                            this.#inner = [];
+                            this.#state = "pt-body";
+                        }
+                    }
+                    else {
+                        emit(...this.#held, byte);
+                        this.#held = [];
+                        this.#state = "ground";
+                    }
+                    break;
+                case "pt-body":
+                    if (byte === ESC)
+                        this.#state = "pt-esc";
+                    else if (this.#inner.length < MAX_COMMAND_BYTES)
+                        this.#inner.push(byte);
+                    break;
+                case "pt-esc":
+                    if (byte === ESC) {
+                        this.#inner.push(ESC);
+                        this.#state = "pt-body";
+                    }
+                    else if (byte === 0x5c) {
+                        // Passthrough content targets the outer terminal — which is us.
+                        // Only its kitty commands matter; other wrapped output is dropped.
+                        const nested = new KittyApcScanner();
+                        nested.#nextMarker = this.#nextMarker;
+                        const result = nested.scan(Uint8Array.from(this.#inner));
+                        this.#nextMarker = nested.#nextMarker;
+                        for (const command of result.commands) {
+                            commands.push(command);
+                            parts.push(Buffer.from(`\x1b]${KITTY_PLACEMENT_OSC};${command.marker}\x07`, "latin1"));
+                        }
+                        this.#inner = [];
+                        this.#state = "ground";
+                    }
+                    else {
+                        this.#inner.push(ESC, byte);
+                        this.#state = "pt-body";
+                    }
+                    break;
+            }
+        }
+        // A trailing ESC is held for the next chunk, not forwarded twice.
+        flushGround(this.#state === "esc" && escAt >= 0 ? escAt : chunk.length);
+        const forward = parts.length === 1 && parts[0].length === chunk.length && parts[0].buffer === chunk.buffer
+            ? chunk
+            : Uint8Array.from(Buffer.concat(parts));
+        return { forward, commands };
+    }
+}
+function int(control, key, fallback = 0) {
+    const value = control.get(key);
+    if (value === undefined || !/^-?[0-9]+$/u.test(value))
+        return fallback;
+    return Number(value);
+}
+/** PURE — width/height from a PNG IHDR, or null. */
+export function pngDimensions(data) {
+    if (data.length < 24)
+        return null;
+    const signature = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+    if (signature.some((b, i) => data[i] !== b))
+        return null;
+    const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    return { width: view.getUint32(16), height: view.getUint32(20) };
+}
+/**
+ * Byte quotas shared by every pane store in the daemon. Each pane keeps at
+ * most `perPaneBytes`; across panes the least recently used image goes first.
+ * An evicted image disappears from its pane's graphics state, so renderers
+ * stop placing it (placeholder cells then render as blank).
+ */
+export class KittyImageBudget {
+    perPaneBytes;
+    globalBytes;
+    #stores = new Set();
+    #tick = 0;
+    constructor(options) {
+        this.perPaneBytes = options.perPaneBytes;
+        this.globalBytes = options.globalBytes;
+    }
+    get totalBytes() {
+        let total = 0;
+        for (const store of this.#stores)
+            total += store.bytes;
+        return total;
+    }
+    register(store) {
+        this.#stores.add(store);
+    }
+    unregister(store) {
+        this.#stores.delete(store);
+    }
+    nextTick() {
+        return ++this.#tick;
+    }
+    enforce() {
+        let total = this.totalBytes;
+        while (total > this.globalBytes) {
+            let victim = null;
+            let oldest = Infinity;
+            for (const store of this.#stores) {
+                const used = store.oldestUse();
+                if (used < oldest) {
+                    oldest = used;
+                    victim = store;
+                }
+            }
+            if (!victim)
+                return;
+            total -= victim.evictOldest();
+        }
+    }
+}
+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. */
+export class KittyImageStore {
+    #images = new Map();
+    #used = new Map();
+    #cursorPlacements = [];
+    #virtual = new Map();
+    #pending = null;
+    #nextAnonymous = 0x7f000000;
+    #bytes = 0;
+    #cellWidth;
+    #cellHeight;
+    #budget;
+    #revision = 0;
+    constructor(options = {}) {
+        this.#cellWidth = options.cellWidthPx ?? 10;
+        this.#cellHeight = options.cellHeightPx ?? 20;
+        this.#budget = options.budget ?? DEFAULT_KITTY_IMAGE_BUDGET;
+        this.#budget.register(this);
+    }
+    /** Bumps whenever images or placements change. */
+    get revision() {
+        return this.#revision;
+    }
+    get bytes() {
+        return this.#bytes;
+    }
+    images() {
+        return this.#images;
+    }
+    imageByDigest(digest) {
+        for (const image of this.#images.values())
+            if (image.digest === digest)
+                return image;
+        return undefined;
+    }
+    cursorPlacements() {
+        return this.#cursorPlacements;
+    }
+    dispose() {
+        this.#budget.unregister(this);
+        this.#images.clear();
+        this.#used.clear();
+        this.#bytes = 0;
+    }
+    /** A capture reseed replaced the grid: tmux holds no record of cursor placements. */
+    dropCursorPlacements() {
+        if (this.#cursorPlacements.length === 0)
+            return;
+        this.#cursorPlacements.length = 0;
+        this.#revision += 1;
+    }
+    oldestUse() {
+        let oldest = Infinity;
+        for (const used of this.#used.values())
+            oldest = Math.min(oldest, used);
+        return oldest;
+    }
+    /** Evict the least recently used image; returns the bytes freed. */
+    evictOldest() {
+        let victim = null;
+        let oldest = Infinity;
+        for (const [id, used] of this.#used)
+            if (used < oldest) {
+                oldest = used;
+                victim = id;
+            }
+        if (victim === null)
+            return 0;
+        return this.#remove(victim);
+    }
+    #remove(imageId) {
+        const image = this.#images.get(imageId);
+        if (!image)
+            return 0;
+        this.#images.delete(imageId);
+        this.#used.delete(imageId);
+        this.#virtual.delete(imageId);
+        this.#bytes -= image.data.byteLength;
+        const kept = this.#cursorPlacements.filter((p) => p.imageId !== imageId);
+        this.#cursorPlacements.length = 0;
+        this.#cursorPlacements.push(...kept);
+        this.#revision += 1;
+        return image.data.byteLength;
+    }
+    /**
+     * Apply one command. `cursor` is the parser's position at the command's byte
+     * offset (from the marker OSC); null when unavailable.
+     */
+    apply(command, cursor) {
+        let { control } = command;
+        const more = control.get("m") === "1";
+        if (this.#pending) {
+            // Continuation chunks carry only m (and q); the first chunk's keys rule.
+            this.#pending.payload.push(command.payload);
+            this.#pending.bytes += command.payload.length;
+            if (this.#pending.bytes > MAX_COMMAND_BYTES) {
+                this.#pending = null;
+                return;
+            }
+            if (more)
+                return;
+            control = this.#pending.control;
+            const payload = this.#pending.payload.join("");
+            this.#pending = null;
+            this.#finish(control, payload, cursor);
+            return;
+        }
+        const action = control.get("a") ?? "t";
+        if ((action === "t" || action === "T") && more) {
+            this.#pending = { control, payload: [command.payload], bytes: command.payload.length };
+            return;
+        }
+        this.#finish(control, command.payload, cursor);
+    }
+    #finish(control, payload, cursor) {
+        const action = control.get("a") ?? "t";
+        if (action === "d")
+            return this.#delete(control);
+        if (action === "q")
+            return; // Answered by the patched tmux; nothing to store.
+        let imageId = int(control, "i");
+        if (action === "t" || action === "T") {
+            if ((control.get("t") ?? "d") !== "d")
+                return; // file/shm cannot cross machines.
+            if (imageId === 0)
+                imageId = this.#nextAnonymous++;
+            const image = this.#decode(imageId, control, payload);
+            if (!image)
+                return;
+            this.#remove(imageId);
+            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();
+            if (action === "t" || !this.#images.has(imageId))
+                return;
+        }
+        if (action !== "T" && action !== "p")
+            return;
+        const image = this.#images.get(imageId);
+        if (!image)
+            return;
+        this.#used.set(imageId, this.#budget.nextTick());
+        const columns = clampCells(int(control, "c") || Math.ceil(image.width / this.#cellWidth));
+        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 });
+        }
+        else if (cursor) {
+            const existing = this.#cursorPlacements.findIndex((p) => p.imageId === imageId && placementId !== 0 && p.placementId === placementId);
+            if (existing >= 0)
+                this.#cursorPlacements.splice(existing, 1);
+            if (this.#cursorPlacements.length >= TERMINAL_GRAPHICS_MAX_PLACEMENTS)
+                this.#cursorPlacements.shift();
+            this.#cursorPlacements.push({
+                imageId,
+                placementId,
+                line: cursor.line,
+                column: cursor.x,
+                columns,
+                rows,
+                alternate: cursor.alternate,
+            });
+        }
+        this.#revision += 1;
+    }
+    #decode(imageId, control, payload) {
+        let data = Buffer.from(payload, "base64");
+        if (control.get("o") === "z") {
+            try {
+                data = inflateSync(data, { maxOutputLength: TERMINAL_GRAPHICS_MAX_IMAGE_BYTES });
+            }
+            catch {
+                return null;
+            }
+        }
+        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;
+        if (f === 100) {
+            const size = pngDimensions(data);
+            if (!size)
+                return null;
+            ({ width, height } = size);
+            format = "png";
+        }
+        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;
+        }
+        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 };
+    }
+    #delete(control) {
+        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) => !all && imageId !== id;
+        const kept = this.#cursorPlacements.filter((p) => keep(p.imageId));
+        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;
+            }
+        // 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);
+    }
+    /**
+     * The pane's graphics state for renderers: the image registry (with each
+     * image's placeholder grid) and cursor placements clipped to the viewport.
+     * `viewportTop` is the absolute line of grid row 0.
+     */
+    state(viewportTop, gridRows, cols, alternate) {
+        const images = [...this.#images.values()].slice(-TERMINAL_GRAPHICS_MAX_IMAGES).map((image) => ({
+            imageId: image.imageId,
+            digest: image.digest,
+            format: image.format,
+            width: image.width,
+            height: image.height,
+            bytes: image.data.byteLength,
+            placeholder: this.#virtual.get(image.imageId) ?? null,
+        }));
+        const placements = [];
+        for (const placement of this.#cursorPlacements) {
+            if (placement.alternate !== alternate)
+                continue;
+            const image = this.#images.get(placement.imageId);
+            if (!image)
+                continue;
+            const top = placement.line - viewportTop;
+            const first = Math.max(0, top);
+            const last = Math.min(gridRows, top + placement.rows);
+            const right = Math.min(cols, placement.column + placement.columns);
+            if (first >= last || placement.column >= right)
+                continue;
+            placements.push({
+                digest: image.digest,
+                row: first,
+                column: placement.column,
+                rows: last - first,
+                columns: right - placement.column,
+                sourceRow: first - top,
+                sourceColumn: 0,
+                totalRows: placement.rows,
+                totalColumns: placement.columns,
+            });
+        }
+        return { revision: this.#revision, images, placements };
+    }
+}
+const MAX_IMAGES_PER_PANE = TERMINAL_GRAPHICS_MAX_IMAGES;
+const MAX_IMAGE_SIDE = 10_000;
+const clampCells = (cells) => Math.max(1, Math.min(1_000, cells));

package/packages/daemon/dist/terminal/mirror/control-channel.js

@@ -868,6 +868,16 @@ export class ControlChannelCore {
         }));
     }
 }
+/**
+ * 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",
+];
 export function mirrorControlAttachArgs(options, pauseAfterSeconds = DEFAULT_PAUSE_AFTER_SECONDS) {
     const attach = [
         "attach",
@@ -1009,7 +1019,13 @@ export class MirrorControlChannel {
                 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() {
         return this.viewerIdentity ? { ...this.viewerIdentity } : null;

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

@@ -532,6 +532,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/dist/terminal/mirror/native-grid-capture.js

@@ -1,3 +1,11 @@
+/** 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) {
+    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] ?? ""));
+}
 const MAX_BYTES = 16 * 1024 * 1024;
 const MAX_ROWS = MAX_BYTES / 64;
 const MAX_CELLS = 1_000_000;

package/packages/daemon/dist/terminal/mirror/native-grid-reader.js

@@ -1,4 +1,4 @@
-import { decodeNativeGridCapture } from "./native-grid-capture.js";
+import { decodeNativeGridCapture, isStockRawGridCapture, } from "./native-grid-capture.js";
 /** One experimental capability owner per control connection. */
 export class NativeGridCaptureReader {
     io;
@@ -57,6 +57,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
                         ? {