Support Kitty graphics protocol mvp

.github/workflows/ci.yml

@@ -41,6 +41,9 @@ jobs:
           ./addons/addon-image/lib/* \
           ./addons/addon-image/out/* \
           ./addons/addon-image/out-*/* \
+          ./addons/addon-kitty-graphics/lib/* \
+          ./addons/addon-kitty-graphics/out/* \
+          ./addons/addon-kitty-graphics/out-*/* \
           ./addons/addon-ligatures/lib/* \
           ./addons/addon-ligatures/out/* \
           ./addons/addon-ligatures/out-*/* \
@@ -216,6 +219,8 @@ jobs:
       run: npm run test-integration-${{ matrix.browser }} --workers=50% --forbid-only --suite=addon-fit
     - name: Integration tests (addon-image)
       run: npm run test-integration-${{ matrix.browser }} --workers=50% --forbid-only --suite=addon-image
+    - name: Integration tests (addon-kitty-graphics)
+      run: npm run test-integration-${{ matrix.browser }} --workers=50% --forbid-only --suite=addon-kitty-graphics
     - name: Integration tests (addon-progress)
       run: npm run test-integration-${{ matrix.browser }} --workers=50% --forbid-only --suite=addon-progress
     - name: Integration tests (addon-search)

addons/addon-kitty-graphics/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2025, The xterm.js authors (https://github.com/xtermjs/xterm.js)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

addons/addon-kitty-graphics/README.md

@@ -0,0 +1,47 @@
+# @xterm/addon-kitty-graphics
+
+An addon for [xterm.js](https://github.com/xtermjs/xterm.js) that adds support for the [Kitty graphics protocol](https://sw.kovidgoyal.net/kitty/graphics-protocol/).
+
+## Install
+
+```bash
+npm install --save @xterm/addon-kitty-graphics @xterm/xterm
+```
+
+## Usage
+
+```typescript
+import { Terminal } from '@xterm/xterm';
+import { KittyGraphicsAddon } from '@xterm/addon-kitty-graphics';
+
+const terminal = new Terminal();
+const kittyGraphicsAddon = new KittyGraphicsAddon();
+terminal.loadAddon(kittyGraphicsAddon);
+```
+
+## Features
+
+This addon implements the Kitty graphics protocol, allowing applications to display images directly in the terminal using APC (Application Program Command) escape sequences.
+
+### Supported Features
+
+- PNG image transmission (f=100)
+- Direct RGB/RGBA pixel data (f=24, f=32)
+- Image placement at cursor position
+- Basic query support (a=q)
+
+### Protocol Format
+
+The Kitty graphics protocol uses APC escape sequences:
+
+```
+<ESC>_G<key>=<value>,<key>=<value>,...;<base64 data><ESC>\
+```
+
+Key parameters:
+- `a`: Action (t=transmit, T=transmit+display, q=query)
+- `f`: Format (100=PNG, 24=RGB, 32=RGBA)
+- `i`: Image ID
+- `m`: More data follows (1=yes, 0=no)
+
+See the [Kitty graphics protocol documentation](https://sw.kovidgoyal.net/kitty/graphics-protocol/) for full details.

addons/addon-kitty-graphics/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@xterm/addon-kitty-graphics",
+  "version": "0.1.0",
+  "author": {
+    "name": "The xterm.js authors",
+    "url": "https://xtermjs.org/"
+  },
+  "main": "lib/addon-kitty-graphics.js",
+  "module": "lib/addon-kitty-graphics.mjs",
+  "types": "typings/addon-kitty-graphics.d.ts",
+  "repository": "https://github.com/xtermjs/xterm.js/tree/master/addons/addon-kitty-graphics",
+  "license": "MIT",
+  "keywords": [
+    "terminal",
+    "xterm",
+    "xterm.js",
+    "kitty",
+    "graphics"
+  ],
+  "scripts": {
+    "build": "../../node_modules/.bin/tsc -p .",
+    "prepackage": "npm run build",
+    "package": "../../node_modules/.bin/webpack",
+    "prepublishOnly": "npm run package",
+    "start": "node ../../demo/start"
+  }
+}

addons/addon-kitty-graphics/src/KittyGraphicsAddon.test.ts

@@ -0,0 +1,156 @@
+/**
+ * Copyright (c) 2025 The xterm.js authors. All rights reserved.
+ * @license MIT
+ */
+import { assert } from 'chai';
+import { Terminal } from 'browser/public/Terminal';
+import { KittyGraphicsAddon, parseKittyCommand } from './KittyGraphicsAddon';
+
+/**
+ * Write data to terminal and wait for completion.
+ */
+function writeP(terminal: Terminal, data: string | Uint8Array): Promise<void> {
+  return new Promise(r => terminal.write(data, r));
+}
+
+// Test image: 1x1 black PNG (captured from `send-png fixture/black-1x1.png`)
+// Get the below base64-encoded PNG file by: `python3 send-png addons/addon-kitty-graphics/fixture/black-1x1.png`
+const BLACK_1X1_BASE64 = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAMAAAAoyzS7AAAAA1BMVEUAAACnej3aAAAACklEQVR4nGNgAAAAAgABSK+kcQAAAAt0RVh0Q29tbWVudAAA1LTqjgAAAApJREFUeJxjYAAAAGQA2AAAAAt0RVh0Q29tbWVudAAA1LTqjg5JREFUAAAAASUVORK5CYII=';
+
+// Test image: 3x1 RGB PNG (red, green, blue pixels)
+const RGB_3X1_BASE64 = 'iVBORw0KGgoAAAANSUhEUgAAAAMAAAABCAMAAAAsPuSGAAAACVBMVEX/AAAA/wAAAP8tSs2KAAAADElEQVR4nGNgYGQCAAAIAAQ24LCmAAAAHXRFWHRTb2Z0d2FyZQBAbHVuYXBhaW50L3BuZy1jb2RlY/VDGR4AAAAASUVORK5CYII=';
+
+// Currently tests the flow: write escape sequence -> addon stores image.
+// Pixel-level verification of rendered images is done in Playwright tests.
+describe('KittyGraphicsAddon', () => {
+  let terminal: Terminal;
+  let addon: KittyGraphicsAddon;
+
+  beforeEach(() => {
+    terminal = new Terminal({ cols: 80, rows: 24, allowProposedApi: true });
+    addon = new KittyGraphicsAddon({ debug: false });
+    terminal.loadAddon(addon);
+  });
+
+  describe('parseKittyCommand', () => {
+    it('should parse control data with action and format', () => {
+      const cmd = parseKittyCommand('a=T,f=100');
+      assert.equal(cmd.action, 'T');
+      assert.equal(cmd.format, 100);
+    });
+
+    it('should parse control data with all options', () => {
+      const cmd = parseKittyCommand('a=t,f=32,i=5,s=10,v=20,c=3,r=2,m=1,q=2');
+      assert.equal(cmd.action, 't');
+      assert.equal(cmd.format, 32);
+      assert.equal(cmd.id, 5);
+      assert.equal(cmd.width, 10);
+      assert.equal(cmd.height, 20);
+      assert.equal(cmd.columns, 3);
+      assert.equal(cmd.rows, 2);
+      assert.equal(cmd.more, 1);
+      assert.equal(cmd.quiet, 2);
+    });
+
+    it('should handle empty control data', () => {
+      const cmd = parseKittyCommand('');
+      assert.equal(cmd.action, undefined);
+      assert.equal(cmd.format, undefined);
+    });
+
+    it('should parse transmit action', () => {
+      const cmd = parseKittyCommand('a=t,f=100');
+      assert.equal(cmd.action, 't');
+      assert.equal(cmd.format, 100);
+    });
+
+    it('should parse delete action', () => {
+      const cmd = parseKittyCommand('a=d,i=5');
+      assert.equal(cmd.action, 'd');
+      assert.equal(cmd.id, 5);
+    });
+  });
+
+  describe('APC handler', () => {
+    it('should store image when transmit+display sequence is written', async () => {
+      // Write Kitty graphics sequence: ESC _ G <control>;<payload> ESC \
+      const sequence = `\x1b_Ga=T,f=100;${BLACK_1X1_BASE64}\x1b\\`;
+      await writeP(terminal, sequence);
+
+      // Addon should have stored the image
+      assert.equal(addon.images.size, 1);
+
+      const image = addon.images.get(1)!;
+      assert.exists(image);
+      assert.equal(image.format, 100); // PNG format
+      assert.equal(image.data, BLACK_1X1_BASE64);
+    });
+
+    it('should store RGB image with correct payload', async () => {
+      const sequence = `\x1b_Ga=T,f=100;${RGB_3X1_BASE64}\x1b\\`;
+      await writeP(terminal, sequence);
+
+      assert.equal(addon.images.size, 1);
+      const image = addon.images.get(1)!;
+      assert.equal(image.data, RGB_3X1_BASE64);
+    });
+
+    it('should use explicit image id when provided', async () => {
+      const sequence = `\x1b_Ga=T,f=100,i=42;${BLACK_1X1_BASE64}\x1b\\`;
+      await writeP(terminal, sequence);
+
+      assert.equal(addon.images.size, 1);
+      assert.isTrue(addon.images.has(42));
+      assert.isFalse(addon.images.has(1));
+    });
+
+    it('should handle transmit-only (a=t) without display', async () => {
+      const sequence = `\x1b_Ga=t,f=100;${BLACK_1X1_BASE64}\x1b\\`;
+      await writeP(terminal, sequence);
+
+      // Image should still be stored??
+      assert.equal(addon.images.size, 1);
+    });
+
+    it('should delete image by id', async () => {
+      // First store an image with id=5
+      await writeP(terminal, `\x1b_Ga=T,f=100,i=5;${BLACK_1X1_BASE64}\x1b\\`);
+      assert.equal(addon.images.size, 1);
+
+      // Delete it
+      await writeP(terminal, `\x1b_Ga=d,i=5\x1b\\`);
+      assert.equal(addon.images.size, 0);
+    });
+
+    it('should delete all images when no id specified', async () => {
+      // Store multiple images
+      await writeP(terminal, `\x1b_Ga=T,f=100,i=1;${BLACK_1X1_BASE64}\x1b\\`);
+      await writeP(terminal, `\x1b_Ga=T,f=100,i=2;${RGB_3X1_BASE64}\x1b\\`);
+      assert.equal(addon.images.size, 2);
+
+      // Delete all
+      await writeP(terminal, `\x1b_Ga=d\x1b\\`);
+      assert.equal(addon.images.size, 0);
+    });
+
+    it('should handle chunked transmission (m=1 flag)', async () => {
+      // Split payload into chunks using m=1 (more data coming)
+      const half = Math.floor(BLACK_1X1_BASE64.length / 2);
+      const chunk1 = BLACK_1X1_BASE64.substring(0, half);
+      const chunk2 = BLACK_1X1_BASE64.substring(half);
+
+      // First chunk with m=1
+      await writeP(terminal, `\x1b_Ga=t,f=100,i=10,m=1;${chunk1}\x1b\\`);
+      // Image not complete yet (pending)
+      assert.equal(addon.images.size, 0);
+
+      // Final chunk without m=1
+      await writeP(terminal, `\x1b_Ga=t,f=100,i=10;${chunk2}\x1b\\`);
+      // Now image should be stored
+      assert.equal(addon.images.size, 1);
+
+      const image = addon.images.get(10)!;
+      assert.equal(image.data, BLACK_1X1_BASE64);
+    });
+  });
+});