Align browser registerMarker alt-buffer guard with headless

Block registerMarker on the alternate buffer in CoreBrowserTerminal,
matching headless addMarker behavior. Update public typings to
IMarker | undefined and add regression tests.

Fixes #5937

Co-authored-by: Daniel Imms <Tyriar@users.noreply.github.com>

.agents/skills/benchmark/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: benchmark
+description: Run and author benchmark tests in xterm.js. Use when editing benchmark files, working in `*.benchmark.ts`, or when asked how to run the full benchmark suite, a single benchmark file, or a single benchmark case.
+---
+
+# Benchmark Run Instructions
+
+## Running Benchmarks
+
+- Full suite: `npm run benchmark`
+- Single benchmark file:
+  - Tree: `npm run benchmark -- -t out-test/benchmark/Event.benchmark.js`
+  - Run file: `npm run benchmark -- -s "out-test/benchmark/Event.benchmark.js" out-test/benchmark/Event.benchmark.js`
+- Single context/case:
+  - Use `-t` to get the path, then:
+  - `npm run benchmark -- -s "<path>" out-test/benchmark/Event.benchmark.js`
+
+## Benchmark Case Selection
+
+When writing benchmark instructions:
+
+- Use `RuntimeCase` to measure pure runtime in ms.
+- Use `ThroughputRuntimeCase` when measuring throughput in MB/s.
+
+## Notes
+
+- Benchmarks run from built JS in `out-test/benchmark/*.benchmark.js`.
+- Keep `NODE_PATH=./out` (handled by the npm script).

.agents/skills/unit-test/SKILL.md

@@ -1,7 +1,11 @@
 ---
-applyTo: '**/*.test.ts'
+name: unit-test
+description: Write and review xterm.js unit tests with project conventions. Use when editing `*.test.ts` files or when asked for test authoring guidelines.
 ---
-When writing unit tests follow these rules:
+
+# Unit Test Instructions
+
+When writing unit tests, follow these rules:
 
 - When writing unit tests for addons, always create a real xterm.js instance instead of mocking it.
 - Prefer `assert.ok` over `assert.notStrictEqual` when checking something is undefined or not.

.github/workflows/ci.yml

@@ -207,31 +207,31 @@ jobs:
     - name: Build demo server
       run: npm run esbuild-demo-server
     - name: Integration tests (core) # Tests use 50% workers to reduce flakiness
-      run: npm run test-integration-${{ matrix.browser }} --workers=50% --forbid-only --suite=core
+      run: npm run test-integration-${{ matrix.browser }} -- --workers=50% --forbid-only --suite=core
     - name: Integration tests (addon-attach)
-      run: npm run test-integration-${{ matrix.browser }} --workers=50% --forbid-only --suite=addon-attach
+      run: npm run test-integration-${{ matrix.browser }} -- --workers=50% --forbid-only --suite=addon-attach
     - name: Integration tests (addon-clipboard)
-      run: npm run test-integration-${{ matrix.browser }} --workers=50% --forbid-only --suite=addon-clipboard
+      run: npm run test-integration-${{ matrix.browser }} -- --workers=50% --forbid-only --suite=addon-clipboard
     - name: Integration tests (addon-fit)
-      run: npm run test-integration-${{ matrix.browser }} --workers=50% --forbid-only --suite=addon-fit
+      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
+      run: npm run test-integration-${{ matrix.browser }} -- --workers=50% --forbid-only --suite=addon-image
     - name: Integration tests (addon-progress)
-      run: npm run test-integration-${{ matrix.browser }} --workers=50% --forbid-only --suite=addon-progress
+      run: npm run test-integration-${{ matrix.browser }} -- --workers=50% --forbid-only --suite=addon-progress
     - name: Integration tests (addon-search)
-      run: npm run test-integration-${{ matrix.browser }} --workers=50% --forbid-only --suite=addon-search
+      run: npm run test-integration-${{ matrix.browser }} -- --workers=50% --forbid-only --suite=addon-search
     - name: Integration tests (addon-serialize)
-      run: npm run test-integration-${{ matrix.browser }} --workers=50% --forbid-only --suite=addon-serialize
+      run: npm run test-integration-${{ matrix.browser }} -- --workers=50% --forbid-only --suite=addon-serialize
     - name: Integration tests (addon-unicode-graphemes)
-      run: npm run test-integration-${{ matrix.browser }} --workers=50% --forbid-only --suite=addon-unicode-graphemes
+      run: npm run test-integration-${{ matrix.browser }} -- --workers=50% --forbid-only --suite=addon-unicode-graphemes
     - name: Integration tests (addon-unicode11)
-      run: npm run test-integration-${{ matrix.browser }} --workers=50% --forbid-only --suite=addon-unicode11
+      run: npm run test-integration-${{ matrix.browser }} -- --workers=50% --forbid-only --suite=addon-unicode11
     - name: Integration tests (addon-web-fonts)
-      run: npm run test-integration-${{ matrix.browser }} --workers=50% --forbid-only --suite=addon-web-fonts
+      run: npm run test-integration-${{ matrix.browser }} -- --workers=50% --forbid-only --suite=addon-web-fonts
     - name: Integration tests (addon-web-links)
-      run: npm run test-integration-${{ matrix.browser }} --workers=50% --forbid-only --suite=addon-web-links
+      run: npm run test-integration-${{ matrix.browser }} -- --workers=50% --forbid-only --suite=addon-web-links
     - name: Integration tests (addon-webgl)
-      run: npm run test-integration-${{ matrix.browser }} --workers=50% --forbid-only --suite=addon-webgl
+      run: npm run test-integration-${{ matrix.browser }} -- --workers=50% --forbid-only --suite=addon-webgl
 
   release-dry-run:
     needs: build

.gitignore

@@ -22,6 +22,9 @@ build/
 yarn.lock
 test-results/
 
+# Tracing/debug files
+.cursor/nal-trace/
+
 # Keep bundled code out of Git
 dist/
 demo/dist/

AGENTS.md

@@ -22,10 +22,10 @@ npm run build && npm run esbuild # Build all TypeScript and bundle
 **Testing**:
 - Unit tests: `npm run test-unit` (Mocha)
 - Unit tests filtering to file: `npm run test-unit -- **/fileName.ts
-- Per-addon unit tests: `npm run test-unit addons/addon-image/out-esbuild/*.test.js`
+- Per-addon unit tests: `npm run test-unit -- addons/addon-image/out-esbuild/*.test.js`
 - Integration tests: `npm run test-integration` (Playwright across Chrome/Firefox/WebKit)
 - Integration tests by file: `npm run test-integration -- test/playwright/InputHandler.test.ts`. Never use grep to filter tests, it doesn't work
-- Integration tests by addon: `npm run test-integration --suite=addon-search`. Suites always follow the format `addon-<something>`
+- Integration tests by addon: `npm run test-integration -- --suite=addon-search`. Suites always follow the format `addon-<something>`
 - Lint changes: `npm run lint-changes` to lint only changed files, `npm run lint-changes-fix` to fix them
 
 ## Addon Development Pattern
@@ -57,6 +57,13 @@ export class MyAddon implements ITerminalAddon {
 - Proposed APIs require `allowProposedApi: true` option
 - Constructor-only options (cols, rows) cannot be changed after instantiation
 
+**Disposable Management**:
+- When a disposable object can be replaced over time, prefer a registered `MutableDisposable` over manual dispose/reassign logic.
+- Register it on the owning class (for example, `this._register(new MutableDisposable())`) and assign through `.value`; this automatically disposes the previous value and avoids accidentally leaking resources.
+
+**TypeScript Constants**:
+- Prefer `const enum` over top-level `const` declarations for primitive constants when appropriate, since values are inlined and avoid runtime property lookups.
+
 **Testing Utilities**: Use `TestUtils.ts` helpers:
 - `openTerminal(ctx, options)` for setup
 - `pollFor(page, fn, expectedValue)` for async assertions

README.md

@@ -24,7 +24,36 @@ First, you need to install the module. We ship exclusively through [npm](https:/
 npm install --save @xterm/xterm
 ```
 
-To start using xterm.js on your browser, add the `xterm.js` and `xterm.css` to the head of your HTML page. Then create a `<div id="terminal"></div>` onto which xterm can attach itself. Finally, instantiate the `Terminal` object and then call the `open` function with the DOM object of the `div`.
+The recommended way to load xterm.js with the ES module syntax, either using TypeScript or a modern JS tooling. Note that both CommonJS and ES module files are shipped with the npm package.
+
+```javascript
+import { Terminal } from '@xterm/xterm';
+```
+
+Then instantiate a `Terminal` object, open it on an element and write to it:
+
+```javascript
+const term = new Terminal();
+term.open(document.getElementById('terminal'));
+term.write('Hello from \x1B[1;3;31mxterm.js\x1B[0m $ ')
+```
+
+Most use cases will hook up input and output to a pseudoterminal API such as [node-pty](https://www.npmjs.com/package/node-pty) which will drive the terminal.
+
+```javascript
+pty.onData(data => term.write(data));
+term.onData(data => pty.write(data));
+```
+
+Then make sure to also include the `css/xterm.css` file, for example in HTML:
+
+```html
+<link rel="stylesheet" href="node_modules/@xterm/xterm/css/xterm.css" />
+```
+
+### Standalone example
+
+Here is a complete standalone example in a HTML file:
 
 ```html
 <!doctype html>
@@ -36,7 +65,7 @@ To start using xterm.js on your browser, add the `xterm.js` and `xterm.css` to t
     <body>
       <div id="terminal"></div>
       <script>
-        var term = new Terminal();
+        const term = new Terminal();
         term.open(document.getElementById('terminal'));
         term.write('Hello from \x1B[1;3;31mxterm.js\x1B[0m $ ')
       </script>
@@ -44,14 +73,6 @@ To start using xterm.js on your browser, add the `xterm.js` and `xterm.css` to t
   </html>
 ```
 
-### Importing
-
-The recommended way to load xterm.js is via the ES6 module syntax:
-
-```javascript
-import { Terminal } from '@xterm/xterm';
-```
-
 ### Addons
 
 Addons are separate modules that extend the `Terminal` by building on the [xterm.js API](https://github.com/xtermjs/xterm.js/blob/master/typings/xterm.d.ts). To use an addon, you first need to install it in your project:
@@ -94,7 +115,7 @@ Since xterm.js is typically implemented as a developer tool, generally only mode
 
 ### Node.js Support
 
-We also publish [`xterm-headless`](https://www.npmjs.com/package/xterm-headless) which is a stripped down version of xterm.js that runs headless in Node.js. An example use case for this is to keep track of a terminal's state where the process is running and using the [serialize addon](https://www.npmjs.com/package/@xterm/addon-serialize) so it can get all state restored upon reconnection.
+We also publish [`@xterm/headless`](https://www.npmjs.com/package/@xterm/headless) which is a stripped down version of xterm.js that runs headless in Node.js. An example use case for this is to keep track of a terminal's state where the process is running and using the [serialize addon](https://www.npmjs.com/package/@xterm/addon-serialize) so it can get all state restored upon reconnection.
 
 ## API
 
@@ -229,6 +250,10 @@ Xterm.js is used in many world-class applications to provide great terminal expe
 - [**ecmaOS**](https://ecmaos.sh): A kernel and suite of applications tying modern web technologies into a browser-based operating system.
 - [**LabEx**](https://labex.io): Interactive learning platform with hands-on labs and xterm.js-based online terminals, focused on learn-by-doing approach.
 - [**EmuDevz**](https://afska.github.io/emudevz): A free coding game where players learn how to build an emulator from scratch.
+- [**SSH Connection Manager**](https://github.com/Amtrend/ssh-manager): Modern web-based SSH terminal and SFTP manager with AES-256 encryption, PWA support, and session management.
+- [**WooTTY**](https://github.com/icoretech/wootty): Flawless browser terminal for real operators.
+- [**Orca**](https://github.com/stablyai/orca): Agentic development environment for 100x builders.
+- [**4bit**](https://ciembor.github.io/4bit): Terminal Color Scheme Designer.
 - [And much more...](https://github.com/xtermjs/xterm.js/network/dependents?package_id=UGFja2FnZS0xNjYzMjc4OQ%3D%3D)
 
 Do you use xterm.js in your application as well? Please [open a Pull Request](https://github.com/sourcelair/xterm.js/pulls) to include it here. We would love to have it on our list. Please add any new contributions to the end of the list.

addons/addon-attach/package.json

@@ -16,7 +16,7 @@
     "xterm.js"
   ],
   "scripts": {
-    "build": "../../node_modules/.bin/tsc -p .",
+    "build": "../../node_modules/.bin/tsgo -p .",
     "prepackage": "npm run build",
     "package": "../../node_modules/.bin/webpack",
     "prepublishOnly": "npm run package",

addons/addon-attach/src/AttachAddon.ts

@@ -12,7 +12,7 @@ interface IAttachOptions {
   bidirectional?: boolean;
 }
 
-export class AttachAddon implements ITerminalAddon , IAttachApi {
+export class AttachAddon implements ITerminalAddon, IAttachApi {
   private _socket: WebSocket;
   private _bidirectional: boolean;
   private _disposables: IDisposable[] = [];

addons/addon-attach/test/playwright.config.ts

@@ -5,10 +5,9 @@ const config: PlaywrightTestConfig = {
   timeout: 10000,
   projects: [
     {
-      name: 'ChromeStable',
+      name: 'Chromium',
       use: {
-        browserName: 'chromium',
-        channel: 'chrome'
+        browserName: 'chromium'
       }
     },
     {

addons/addon-attach/test/tsconfig.json

@@ -9,13 +9,15 @@
     "outDir": "../out-test",
     "sourceMap": true,
     "removeComments": true,
-    "baseUrl": ".",
     "paths": {
       "common/*": [
         "../../../src/common/*"
       ],
       "browser/*": [
         "../../../src/browser/*"
+      ],
+      "*": [
+        "./*"
       ]
     },
     "strict": true,

addons/addon-clipboard/package.json

@@ -16,13 +16,10 @@
     "xterm.js"
   ],
   "scripts": {
-    "build": "../../node_modules/.bin/tsc -p .",
+    "build": "../../node_modules/.bin/tsgo -p .",
     "prepackage": "npm run build",
     "package": "../../node_modules/.bin/webpack",
     "prepublishOnly": "npm run package",
     "start": "node ../../demo/start"
-  },
-  "dependencies": {
-    "js-base64": "^3.7.5"
   }
 }

addons/addon-clipboard/src/ClipboardAddon.ts

@@ -4,8 +4,7 @@
  */
 
 import type { IDisposable, ITerminalAddon, Terminal } from '@xterm/xterm';
-import { type IClipboardProvider, ClipboardSelectionType, type IBase64 } from '@xterm/addon-clipboard';
-import { Base64 as JSBase64 } from 'js-base64';
+import { type IClipboardProvider, type IBase64 } from '@xterm/addon-clipboard';
 
 export class ClipboardAddon implements ITerminalAddon {
   private _terminal?: Terminal;
@@ -25,7 +24,7 @@ export class ClipboardAddon implements ITerminalAddon {
     return this._disposable?.dispose();
   }
 
-  private _readText(sel: ClipboardSelectionType, data: string): void {
+  private _readText(sel: string, data: string): void {
     const b64 = this._base64.encodeText(data);
     this._terminal?.input(`\x1b]52;${sel};${b64}\x07`, false);
   }
@@ -36,7 +35,7 @@ export class ClipboardAddon implements ITerminalAddon {
       return true;
     }
 
-    const pc = args[0] as ClipboardSelectionType;
+    const pc = args[0];
     const pd = args[1];
     if (pd === '?') {
       const text = this._provider.readText(pc);
@@ -70,30 +69,23 @@ export class ClipboardAddon implements ITerminalAddon {
 }
 
 export class BrowserClipboardProvider implements IClipboardProvider {
-  public async readText(selection: ClipboardSelectionType): Promise<string> {
-    if (selection !== 'c') {
-      return Promise.resolve('');
-    }
+  public readText(selection: string): Promise<string> {
     return navigator.clipboard.readText();
   }
 
-  public async writeText(selection: ClipboardSelectionType, text: string): Promise<void> {
-    if (selection !== 'c') {
-      return Promise.resolve();
-    }
+  public writeText(selection: string, text: string): Promise<void> {
     return navigator.clipboard.writeText(text);
   }
 }
 
 export class Base64 implements IBase64 {
   public encodeText(data: string): string {
-    return JSBase64.encode(data);
+    return btoa(data);
   }
   public decodeText(data: string): string {
-    const text = JSBase64.decode(data);
-    if (!JSBase64.isValid(data) || JSBase64.encode(text) !== data) {
-      return '';
-    }
-    return text;
+    try {
+      return atob(data);
+    } catch {}
+    return '';
   }
 }

addons/addon-clipboard/test/ClipboardAddon.test.ts

@@ -20,7 +20,7 @@ test.describe('ClipboardAddon', () => {
 
   test.beforeEach(async ({}, testInfo) => {
     // DEBT: This test doesn't work since the migration to @playwright/test
-    if (ctx.browser.browserType().name() !== 'chromium') {
+    if (ctx.browser.browserType().name() === 'webkit') {
       testInfo.skip();
       return;
     }
@@ -48,6 +48,14 @@ test.describe('ClipboardAddon', () => {
       await ctx.proxy.write(`\x1b]52;c;${testDataEncoded}\x07`);
       deepEqual(await ctx.page.evaluate(() => window.navigator.clipboard.readText()), testDataDecoded);
     });
+    test('primary selection', async () => {
+      await ctx.proxy.write(`\x1b]52;p;${testDataEncoded}\x07`);
+      deepEqual(await ctx.page.evaluate(() => window.navigator.clipboard.readText()), testDataDecoded);
+    });
+    test('empty selection (default)', async () => {
+      await ctx.proxy.write(`\x1b]52;;${testDataEncoded}\x07`);
+      deepEqual(await ctx.page.evaluate(() => window.navigator.clipboard.readText()), testDataDecoded);
+    });
     test('invalid base64 string', async () => {
       await ctx.proxy.write(`\x1b]52;c;${testDataEncoded}invalid\x07`);
       deepEqual(await ctx.page.evaluate(() => window.navigator.clipboard.readText()), '');
@@ -60,15 +68,24 @@ test.describe('ClipboardAddon', () => {
   });
 
   test.describe('read data', async function (): Promise<any> {
-    test('simple string', async () => {
+    test.beforeAll(async () => {
       await ctx.page.evaluate(`
         window.data = [];
         window.term.onData(e => data.push(e));
       `);
+    });
+    test('simple string', async () => {
+      await ctx.page.evaluate('window.data.length = 0;');
       await ctx.page.evaluate(() => window.navigator.clipboard.writeText('hello world'));
       await ctx.proxy.write(`\x1b]52;c;?\x07`);
       deepEqual(await ctx.page.evaluate('window.data'), [`\x1b]52;c;${testDataEncoded}\x07`]);
     });
+    test('primary selection', async () => {
+      await ctx.page.evaluate('window.data.length = 0;');
+      await ctx.page.evaluate(() => window.navigator.clipboard.writeText('hello world'));
+      await ctx.proxy.write(`\x1b]52;p;?\x07`);
+      deepEqual(await ctx.page.evaluate('window.data'), [`\x1b]52;p;${testDataEncoded}\x07`]);
+    });
     test('clear clipboard', async () => {
       await ctx.proxy.write(`\x1b]52;c;!\x07`);
       await ctx.proxy.write(`\x1b]52;c;?\x07`);

addons/addon-clipboard/test/playwright.config.ts

@@ -5,10 +5,9 @@ const config: PlaywrightTestConfig = {
   timeout: 10000,
   projects: [
     {
-      name: 'ChromeStable',
+      name: 'Chromium',
       use: {
-        browserName: 'chromium',
-        channel: 'chrome'
+        browserName: 'chromium'
       }
     },
     {

addons/addon-clipboard/test/tsconfig.json

@@ -9,13 +9,15 @@
     "outDir": "../out-test",
     "sourceMap": true,
     "removeComments": true,
-    "baseUrl": ".",
     "paths": {
       "common/*": [
         "../../../src/common/*"
       ],
       "browser/*": [
         "../../../src/browser/*"
+      ],
+      "*": [
+        "./*"
       ]
     },
     "strict": true,

addons/addon-clipboard/typings/addon-clipboard.d.ts

@@ -30,18 +30,6 @@ declare module '@xterm/addon-clipboard' {
     public dispose(): void
   }
 
-  /**
-   * Clipboard selection type. This is used to specify which selection buffer to
-   * read or write to.
-   * - SYSTEM `c`: The system clipboard.
-   * - PRIMARY `p`: The primary clipboard. This is provided for compatibility
-   *  with Linux X11.
-   */
-  export const enum ClipboardSelectionType {
-    SYSTEM = 'c',
-    PRIMARY = 'p',
-  }
-
   export interface IBase64 {
     /**
     * Converts a utf-8 string to a base64 string.
@@ -78,36 +66,39 @@ declare module '@xterm/addon-clipboard' {
   export interface IClipboardProvider {
     /**
      * Gets the clipboard content.
-     * @param selection The clipboard selection to read.
+     * @param selection The clipboard selection to read (see OSC 52 spec of xterm).
      * @returns A promise that resolves with clipboard selection data.
      */
-    readText(selection: ClipboardSelectionType): string | Promise<string>;
+    readText(selection: string): string | Promise<string>;
 
     /**
      * Sets the clipboard content.
-     * @param selection The clipboard selection to set.
+     * @param selection The clipboard selection to set (see OSC 52 spec of xterm).
      * @param data The clipboard text to write.
      */
-    writeText(selection: ClipboardSelectionType, text: string): void | Promise<void>;
+    writeText(selection: string, text: string): void | Promise<void>;
   }
 
   /**
-   * The clipboard provider interface that enables xterm.js to access the system clipboard.
+   * The clipboard provider interface that enables xterm.js to access the browser clipboard.
+   *
+   * Note this this clipboard provider does not implement own cut buffers as xterm does,
+   * but redirect the selection parameter always to navigator.clipboard.
    */
   export class BrowserClipboardProvider implements IClipboardProvider{
     /**
      * Reads text from the clipboard.
-     * @param selection The selection type to read from.
+     * @param selection The selection type to read from (always refers to navigator.clipboard).
      * @returns A promise that resolves with the text from the clipboard.
      */
-    public readText(selection: ClipboardSelectionType): Promise<string>;
+    public readText(selection: string): Promise<string>;
 
     /**
      * Writes text to the clipboard.
-     * @param selection The selection type to write to.
+     * @param selection The selection type to write to (always refers to navigator.clipboard).
      * @param data The text to write to the clipboard.
      * @returns A promise that resolves when the text has been written to the clipboard.
      */
-    public writeText(selection: ClipboardSelectionType, data: string): Promise<void>;
+    public writeText(selection: string, data: string): Promise<void>;
   }
 }

addons/addon-fit/package.json

@@ -16,7 +16,7 @@
     "xterm.js"
   ],
   "scripts": {
-    "build": "../../node_modules/.bin/tsc -p .",
+    "build": "../../node_modules/.bin/tsgo -p .",
     "prepackage": "npm run build",
     "package": "../../node_modules/.bin/webpack",
     "prepublishOnly": "npm run package",

addons/addon-fit/src/FitAddon.ts

@@ -19,8 +19,10 @@ interface ITerminalDimensions {
   cols: number;
 }
 
-const MINIMUM_COLS = 2;
-const MINIMUM_ROWS = 1;
+const enum Constants {
+  MINIMUM_COLS = 2,
+  MINIMUM_ROWS = 1
+}
 
 function getWindow(e: Node): Window {
   if (e?.ownerDocument?.defaultView) {
@@ -33,7 +35,7 @@ function _getComputedStyle(el: HTMLElement): CSSStyleDeclaration {
   return getWindow(el).getComputedStyle(el, null);
 }
 
-export class FitAddon implements ITerminalAddon , IFitApi {
+export class FitAddon implements ITerminalAddon, IFitApi {
   private _terminal: Terminal | undefined;
 
   public activate(terminal: Terminal): void {
@@ -48,10 +50,7 @@ export class FitAddon implements ITerminalAddon , IFitApi {
       return;
     }
 
-    // Force a full render
-    if (this._terminal.rows !== dims.rows || this._terminal.cols !== dims.cols) {
-      this._terminal.resize(dims.cols, dims.rows);
-    }
+    this._terminal.resize(dims.cols, dims.rows);
   }
 
   public proposeDimensions(): ITerminalDimensions | undefined {
@@ -69,9 +68,10 @@ export class FitAddon implements ITerminalAddon , IFitApi {
       return undefined;
     }
 
-    const scrollbarWidth = (this._terminal.options.scrollback === 0
+    const showScrollbar = this._terminal.options.scrollbar?.showScrollbar ?? true;
+    const scrollbarWidth = (this._terminal.options.scrollback === 0 || !showScrollbar
       ? 0
-      : (this._terminal.options.overviewRuler?.width || ViewportConstants.DEFAULT_SCROLL_BAR_WIDTH));
+      : (this._terminal.options.scrollbar?.width ?? ViewportConstants.DEFAULT_SCROLL_BAR_WIDTH));
 
     const parentElementStyle = _getComputedStyle(this._terminal.element.parentElement);
     const parentElementHeight = parseInt(parentElementStyle.getPropertyValue('height'));
@@ -88,8 +88,8 @@ export class FitAddon implements ITerminalAddon , IFitApi {
     const availableHeight = parentElementHeight - elementPaddingVer;
     const availableWidth = parentElementWidth - elementPaddingHor - scrollbarWidth;
     const geometry = {
-      cols: Math.max(MINIMUM_COLS, Math.floor(availableWidth / dims.css.cell.width)),
-      rows: Math.max(MINIMUM_ROWS, Math.floor(availableHeight / dims.css.cell.height))
+      cols: Math.max(Constants.MINIMUM_COLS, Math.floor(availableWidth / dims.css.cell.width)),
+      rows: Math.max(Constants.MINIMUM_ROWS, Math.floor(availableHeight / dims.css.cell.height))
     };
     return geometry;
   }

addons/addon-fit/test/FitAddon.test.ts

@@ -119,6 +119,17 @@ test.describe('FitAddon', () => {
       strictEqual(await ctx.proxy.cols, 2);
       strictEqual(await ctx.proxy.rows, 1);
     });
+
+    test('same dimensions', async function(): Promise<any> {
+      await setDimensions();
+      await ctx.page.evaluate(`window.fit.fit()`);
+      const cols: number = await ctx.proxy.cols;
+      const rows: number = await ctx.proxy.rows;
+      // Calling fit() again at the same container size should not throw
+      await ctx.page.evaluate(`window.fit.fit()`);
+      strictEqual(await ctx.proxy.cols, cols);
+      strictEqual(await ctx.proxy.rows, rows);
+    });
   });
 });
 

addons/addon-fit/test/playwright.config.ts

@@ -5,10 +5,9 @@ const config: PlaywrightTestConfig = {
   timeout: 10000,
   projects: [
     {
-      name: 'ChromeStable',
+      name: 'Chromium',
       use: {
-        browserName: 'chromium',
-        channel: 'chrome'
+        browserName: 'chromium'
       }
     },
     {

addons/addon-fit/test/tsconfig.json

@@ -9,13 +9,15 @@
     "outDir": "../out-test",
     "sourceMap": true,
     "removeComments": true,
-    "baseUrl": ".",
     "paths": {
       "common/*": [
         "../../../src/common/*"
       ],
       "browser/*": [
         "../../../src/browser/*"
+      ],
+      "*": [
+        "./*"
       ]
     },
     "strict": true,

addons/addon-image/README.md

@@ -25,12 +25,14 @@ const customSettings: IImageAddonOptions = {
   pixelLimit: 16777216,       // max. pixel size of a single image
   sixelSupport: true,         // enable sixel support
   sixelScrolling: true,       // whether to scroll on image output
-  sixelPaletteLimit: 256,     // initial sixel palette size
-  sixelSizeLimit: 25000000,   // size limit of a single sixel sequence
+  sixelPaletteLimit: 4096,    // initial sixel palette size
+  sixelSizeLimit: 33554432,   // size limit of a single sixel sequence
   storageLimit: 128,          // FIFO storage limit in MB
   showPlaceholder: true,      // whether to show a placeholder for evicted images
   iipSupport: true,           // enable iTerm IIP support
-  iipSizeLimit: 20000000      // size limit of a single IIP sequence
+  iipSizeLimit: 33554432,     // size limit of a single IIP sequence
+  kittySupport: true,         // enable Kitty graphics support
+  kittySizeLimit: 33554432    // size limit of a single Kitty sequence
 }
 
 // initialization

addons/addon-image/package.json

@@ -18,13 +18,13 @@
     "xterm.js"
   ],
   "scripts": {
-    "prepackage": "../../node_modules/.bin/tsc -p .",
+    "prepackage": "../../node_modules/.bin/tsgo -p .",
     "package": "../../node_modules/.bin/webpack",
     "prepublishOnly": "npm run package",
     "start": "node ../../demo/start"
   },
   "devDependencies": {
     "sixel": "^0.16.0",
-    "xterm-wasm-parts": "^0.1.0"
+    "xterm-wasm-parts": "^0.4.1"
   }
 }

addons/addon-image/src/IIPHandler.ts

@@ -4,17 +4,22 @@
  */
 import { IImageAddonOptions, IOscHandler, IResetHandler, ITerminalExt } from './Types';
 import { ImageRenderer } from './ImageRenderer';
-import { ImageStorage, CELL_SIZE_DEFAULT } from './ImageStorage';
+import { IIPImageStorage } from './IIPImageStorage';
+import { CELL_SIZE_DEFAULT } from './ImageStorage';
 import Base64Decoder from 'xterm-wasm-parts/lib/base64/Base64Decoder.wasm';
+import QoiDecoder from 'xterm-wasm-parts/lib/qoi/QoiDecoder.wasm';
 import { HeaderParser, IHeaderFields, HeaderState } from './IIPHeaderParser';
 import { imageType, UNSUPPORTED_TYPE } from './IIPMetrics';
 
-
-// eslint-disable-next-line
-declare const Buffer: any;
-
-// limit hold memory in base64 decoder
-const KEEP_DATA = 4194304;
+// Local const enum mirror - esbuild can't inline const enums from external packages
+const enum DecoderConst {
+  // Limit held memory in base64 decoder (encoded bytes).
+  KEEP_DATA = 4194304,
+  // Initial buffer allocation for the decoder.
+  INITIAL_DATA = 1048576,
+  // Local mirror of const enum (esbuild can't inline const enums from external packages)
+  OK = 0
+}
 
 // default IIP header values
 const DEFAULT_HEADER: IHeaderFields = {
@@ -31,15 +36,21 @@ export class IIPHandler implements IOscHandler, IResetHandler {
   private _aborted = false;
   private _hp = new HeaderParser();
   private _header: IHeaderFields = DEFAULT_HEADER;
-  private _dec = new Base64Decoder(KEEP_DATA);
+  private _dec: Base64Decoder;
+  private _qoiDec: QoiDecoder;
   private _metrics = UNSUPPORTED_TYPE;
 
   constructor(
     private readonly _opts: IImageAddonOptions,
     private readonly _renderer: ImageRenderer,
-    private readonly _storage: ImageStorage,
+    private readonly _storage: IIPImageStorage,
     private readonly _coreTerminal: ITerminalExt
-  ) {}
+  ) {
+    const maxEncodedBytes = Math.ceil(this._opts.iipSizeLimit * 4 / 3);
+    const initialBytes = Math.min(DecoderConst.INITIAL_DATA, maxEncodedBytes);
+    this._dec = new Base64Decoder(DecoderConst.KEEP_DATA, maxEncodedBytes, initialBytes);
+    this._qoiDec = new QoiDecoder(DecoderConst.KEEP_DATA);
+  }
 
   public reset(): void {}
 
@@ -54,7 +65,7 @@ export class IIPHandler implements IOscHandler, IResetHandler {
     if (this._aborted) return;
 
     if (this._hp.state === HeaderState.END) {
-      if (this._dec.put(data, start, end)) {
+      if ((this._dec.put(data.subarray(start, end)) as number) !== DecoderConst.OK) {
         this._dec.release();
         this._aborted = true;
       }
@@ -70,8 +81,8 @@ export class IIPHandler implements IOscHandler, IResetHandler {
           this._aborted = true;
           return;
         }
-        this._dec.init(this._header.size);
-        if (this._dec.put(data, dataPos, end)) {
+        this._dec.init();
+        if ((this._dec.put(data.subarray(dataPos, end)) as number) !== DecoderConst.OK) {
           this._dec.release();
           this._aborted = true;
         }
@@ -89,13 +100,15 @@ export class IIPHandler implements IOscHandler, IResetHandler {
     let cond: number | boolean = true;
     if (cond = success) {
       if (cond = !this._dec.end()) {
-        this._metrics = imageType(this._dec.data8);
-        if (cond = this._metrics.mime !== 'unsupported') {
-          w = this._metrics.width;
-          h = this._metrics.height;
-          if (cond = w && h && w * h < this._opts.pixelLimit) {
-            [w, h] = this._resize(w, h).map(Math.floor);
-            cond = w && h && w * h < this._opts.pixelLimit;
+        if (cond = this._dec.data8.length === this._header.size) {
+          this._metrics = imageType(this._dec.data8);
+          if (cond = this._metrics.mime !== 'unsupported') {
+            w = this._metrics.width;
+            h = this._metrics.height;
+            if (cond = w && h && w * h < this._opts.pixelLimit) {
+              [w, h] = this._resize(w, h).map(Math.floor);
+              cond = w && h && w * h < this._opts.pixelLimit;
+            }
           }
         }
       }
@@ -105,26 +118,27 @@ export class IIPHandler implements IOscHandler, IResetHandler {
       return true;
     }
 
-    const blob = new Blob([new Uint8Array(this._dec.data8)], { type: this._metrics.mime });
-    this._dec.release();
-
-    if (!window.createImageBitmap) {
-      const url = URL.createObjectURL(blob);
-      const img = new Image();
-      return new Promise<boolean>(r => {
-        img.addEventListener('load', () => {
-          URL.revokeObjectURL(url);
-          const canvas = ImageRenderer.createCanvas(window.document, w, h);
-          canvas.getContext('2d')?.drawImage(img, 0, 0, w, h);
-          this._storage.addImage(canvas);
-          r(true);
-        });
-        img.src = url;
-        // sanity measure to avoid terminal blocking from dangling promise
-        // happens from corrupt data (onload never gets fired)
-        setTimeout(() => r(true), 1000);
-      });
+    let blob: Blob | ImageData;
+    if (this._metrics.mime === 'image/qoi') {
+      const data = this._qoiDec.decode(this._dec.data8);
+      blob = new ImageData(
+        new Uint8ClampedArray(data.buffer, data.byteOffset, data.byteLength),
+        this._qoiDec.width,
+        this._qoiDec.height
+      );
+      this._qoiDec.release();
+      if (w === this._qoiDec.width && h === this._qoiDec.height) {
+        // use fast-path if we don't need to rescale
+        this._dec.release();
+        const canvas = ImageRenderer.createCanvas(undefined, this._qoiDec.width, this._qoiDec.height);
+        canvas.getContext('2d')?.putImageData(blob, 0, 0);
+        this._storage.addImage(canvas);
+        return true;
+      }
+    } else {
+      blob = new Blob([this._dec.data8], { type: this._metrics.mime });
     }
+    this._dec.release();
     return createImageBitmap(blob, { resizeWidth: w, resizeHeight: h })
       .then(bm => {
         this._storage.addImage(bm);

addons/addon-image/src/IIPHeaderParser.ts

@@ -8,6 +8,7 @@ declare const Buffer: any;
 
 
 export interface IHeaderFields {
+  [key: string]: number | string | Uint32Array | null | undefined;
   // base-64 encoded filename. Defaults to "Unnamed file".
   name: string;
   // File size in bytes. The file transfer will be canceled if this size is exceeded.
@@ -81,7 +82,7 @@ function toName(data: Uint32Array): string {
   return new TextDecoder().decode(b);
 }
 
-const DECODERS: {[key: string]: (v: Uint32Array) => any} = {
+const DECODERS: {[key: string]: (v: Uint32Array) => number | string} = {
   inline: toInt,
   size: toInt,
   name: toName,
@@ -100,7 +101,7 @@ export class HeaderParser {
   private _buffer = new Uint32Array(MAX_FIELDCHARS);
   private _position = 0;
   private _key = '';
-  public fields: {[key: string]: any} = {};
+  public fields: {[key: string]: number | string | Uint32Array | null | undefined} = {};
 
   public reset(): void {
     this._buffer.fill(0);

addons/addon-image/src/IIPImageStorage.ts

@@ -0,0 +1,26 @@
+/**
+ * Copyright (c) 2023 The xterm.js authors. All rights reserved.
+ * @license MIT
+ */
+
+import { ImageStorage } from './ImageStorage';
+
+/**
+ * IIP (iTerm Image Protocol) specific image storage controller.
+ *
+ * Wraps the shared ImageStorage with IIP protocol semantics:
+ * - Always uses scrolling mode (cursor advances with image)
+ */
+export class IIPImageStorage {
+  constructor(
+    private readonly _storage: ImageStorage
+  ) {}
+
+  /**
+   * Add an IIP image to storage.
+   * Always uses scrolling mode — cursor advances past the image.
+   */
+  public addImage(img: HTMLCanvasElement | ImageBitmap): void {
+    this._storage.addImage(img, true);
+  }
+}

addons/addon-image/src/IIPMetrics.ts

@@ -4,7 +4,7 @@
  */
 
 
-export type ImageType = 'image/png' | 'image/jpeg' | 'image/gif' | 'unsupported' | '';
+export type ImageType = 'image/png' | 'image/jpeg' | 'image/gif' | 'image/qoi' | 'unsupported' | '';
 
 export interface IMetrics {
   mime: ImageType;
@@ -45,6 +45,14 @@ export function imageType(d: Uint8Array): IMetrics {
       height: d[9] << 8 | d[8]
     };
   }
+  // QOI: qoif
+  if (d32[0] === 0x66696F71) {
+    return {
+      mime: 'image/qoi',
+      width: d[4] << 24 | d[5] << 16 | d[6] << 8 | d[7],
+      height: d[8] << 24 | d[9] << 16 | d[10] << 8 | d[11]
+    };
+  }
   return UNSUPPORTED_TYPE;
 }
 

addons/addon-image/src/ImageAddon.ts

@@ -5,24 +5,72 @@
 
 import type { ITerminalAddon, IDisposable } from '@xterm/xterm';
 import type { ImageAddon as IImageApi } from '@xterm/addon-image';
+import { Emitter, type IEvent } from 'common/Event';
 import { IIPHandler } from './IIPHandler';
 import { ImageRenderer } from './ImageRenderer';
 import { ImageStorage, CELL_SIZE_DEFAULT } from './ImageStorage';
+import { KittyGraphicsHandler } from './kitty/KittyGraphicsHandler';
+import { KittyImageStorage } from './kitty/KittyImageStorage';
 import { SixelHandler } from './SixelHandler';
+import { SixelImageStorage } from './SixelImageStorage';
+import { IIPImageStorage } from './IIPImageStorage';
 import { ITerminalExt, IImageAddonOptions, IResetHandler } from './Types';
 
+
+/**
+ * Document VT features provided by this addon.
+ *
+ * @vt: #E[Supported via @xterm/addon-image.] DCS SIXEL "SIXEL Graphics"  "DCS Ps ; Ps ; Ps ; q Pt ST"  "Draw SIXEL image."
+ *
+ * Sixel support is provided by the addon @xterm/addon-image with these limitations:
+ * - immediate coloring (no shared palette, allows high color settings of `img2sixel`)
+ * - max. palette size of 4096 colors
+ * - max. pixel width of 16K
+ * - max. 25 MB per sixel sequence
+ * - VT340 cursor positioning (begin of last sixel data row)
+ *
+ * See [addon readme](https://github.com/xtermjs/xterm.js/tree/master/addons/addon-image) for more details.
+ *
+ *
+ * @vt: #E[Supported via @xterm/addon-image.] OSC 1337  "iTerm2 Commands"   "OSC 1337 ; Pt BEL"  "Custom iTerm2 commands."
+ *
+ * Only the inline image protocol (IIP) is supported by the addon @xterm/addon-image with
+ * the following limitations:
+ * - sequence:
+ *   - format: `OSC 1337 ; File=inline=1 ; size=<unencoded size> ; ... : <base64 payload> BEL`
+ *   - size param must be set and payload may not exceed CEIL(size * 4 / 3)
+ *   - strict base64 handling as of RFC4648 §4 (standard alphabet, optional padding,
+ *     no separator bytes allowed)
+ *   - supported params: size, name, width, height, preserveAspectRatio
+ * - image formats: PNG, JPEG and GIF
+ * - no animation support (renders first image of a GIF)
+ * - no multipart support
+ * - VT340 cursor positioning (begin of last sixel data row)
+ *
+ * See [addon readme](https://github.com/xtermjs/xterm.js/tree/master/addons/addon-image)
+ * and [iTerm2 IIP docs](https://iterm2.com/documentation-images.html) for more details.
+ *
+ *
+ * @vt: #E[Supported via @xterm/addon-image.] APC KITTY_GRAPHICS "Kitty Graphics"  "APC G Pt ST"  "Kitty Graphics Protocol."
+ *
+ * Kitty graphics support is provided by the addon @xterm/addon-image.
+ * Note that while basic image output already works, this is still work in progress.
+ */
+
 // default values of addon ctor options
 const DEFAULT_OPTIONS: IImageAddonOptions = {
   enableSizeReports: true,
   pixelLimit: 16777216, // limit to 4096 * 4096 pixels
   sixelSupport: true,
   sixelScrolling: true,
-  sixelPaletteLimit: 256,
-  sixelSizeLimit: 25000000,
+  sixelPaletteLimit: 4096,
+  sixelSizeLimit: 33554432,
   storageLimit: 128,
   showPlaceholder: true,
   iipSupport: true,
-  iipSizeLimit: 20000000
+  iipSizeLimit: 33554432,
+  kittySupport: true,
+  kittySizeLimit: 33554432
 };
 
 // max palette size supported by the sixel lib (compile time setting)
@@ -48,7 +96,7 @@ const enum GaStatus {
 }
 
 
-export class ImageAddon implements ITerminalAddon , IImageApi {
+export class ImageAddon implements ITerminalAddon, IImageApi {
   private _opts: IImageAddonOptions;
   private _defaultOpts: IImageAddonOptions;
   private _storage: ImageStorage | undefined;
@@ -56,6 +104,8 @@ export class ImageAddon implements ITerminalAddon , IImageApi {
   private _disposables: IDisposable[] = [];
   private _terminal: ITerminalExt | undefined;
   private _handlers: Map<String, IResetHandler> = new Map();
+  private readonly _onImageAdded = new Emitter<void>();
+  public readonly onImageAdded: IEvent<void> = this._onImageAdded.event;
 
   constructor(opts?: Partial<IImageAddonOptions>) {
     this._opts = Object.assign({}, DEFAULT_OPTIONS, opts);
@@ -68,6 +118,7 @@ export class ImageAddon implements ITerminalAddon , IImageApi {
     }
     this._disposables.length = 0;
     this._handlers.clear();
+    this._onImageAdded.dispose();
   }
 
   private _disposeLater(...args: IDisposable[]): void {
@@ -82,6 +133,7 @@ export class ImageAddon implements ITerminalAddon , IImageApi {
     // internal data structures
     this._renderer = new ImageRenderer(terminal);
     this._storage = new ImageStorage(terminal, this._renderer, this._opts);
+    this._storage.onImageAdded = () => this._onImageAdded.fire();
 
     // enable size reports
     if (this._opts.enableSizeReports) {
@@ -90,7 +142,7 @@ export class ImageAddon implements ITerminalAddon , IImageApi {
       // windowOptions.getCellSizePixels = true;
       // windowOptions.getWinSizeChars = true;
       // terminal.setOption('windowOptions', windowOptions);
-      const windowOps = terminal.options.windowOptions || {};
+      const windowOps = terminal.options.windowOptions ?? {};
       windowOps.getWinSizePixels = true;
       windowOps.getCellSizePixels = true;
       windowOps.getWinSizeChars = true;
@@ -129,7 +181,8 @@ export class ImageAddon implements ITerminalAddon , IImageApi {
 
     // SIXEL handler
     if (this._opts.sixelSupport) {
-      const sixelHandler = new SixelHandler(this._opts, this._storage!, terminal);
+      const sixelStorage = new SixelImageStorage(this._storage!, this._opts, this._renderer!, terminal);
+      const sixelHandler = new SixelHandler(this._opts, sixelStorage, terminal);
       this._handlers.set('sixel', sixelHandler);
       this._disposeLater(
         terminal._core._inputHandler._parser.registerDcsHandler({ final: 'q' }, sixelHandler)
@@ -138,12 +191,25 @@ export class ImageAddon implements ITerminalAddon , IImageApi {
 
     // iTerm IIP handler
     if (this._opts.iipSupport) {
-      const iipHandler = new IIPHandler(this._opts, this._renderer!, this._storage!, terminal);
+      const iipStorage = new IIPImageStorage(this._storage!);
+      const iipHandler = new IIPHandler(this._opts, this._renderer!, iipStorage, terminal);
       this._handlers.set('iip', iipHandler);
       this._disposeLater(
         terminal._core._inputHandler._parser.registerOscHandler(1337, iipHandler)
       );
     }
+
+    // Kitty graphics handler
+    if (this._opts.kittySupport) {
+      const kittyStorage = new KittyImageStorage(this._storage!);
+      const kittyHandler = new KittyGraphicsHandler(this._opts, this._renderer!, kittyStorage, terminal);
+      this._handlers.set('kitty', kittyHandler);
+      this._disposeLater(
+        kittyStorage,
+        kittyHandler,
+        terminal._core._inputHandler._parser.registerApcHandler({ final: 'G' }, kittyHandler)
+      );
+    }
   }
 
   // Note: storageLimit is skipped here to not intoduce a surprising side effect.

addons/addon-image/src/ImageRenderer.ts

@@ -5,11 +5,13 @@
 
 import { toRGBA8888 } from 'sixel/lib/Colors';
 import { IDisposable } from '@xterm/xterm';
-import { ICellSize, ITerminalExt, IImageSpec, IRenderDimensions, IRenderService } from './Types';
-import { Disposable, MutableDisposable, toDisposable } from 'vs/base/common/lifecycle';
+import { ICellSize, ImageLayer, ITerminalExt, IImageSpec, IRenderDimensions, IRenderService } from './Types';
+import { Disposable, MutableDisposable, toDisposable } from 'common/Lifecycle';
 
-const PLACEHOLDER_LENGTH = 4096;
-const PLACEHOLDER_HEIGHT = 24;
+const enum Constants {
+  PLACEHOLDER_LENGTH = 4096,
+  PLACEHOLDER_HEIGHT = 24
+}
 
 /**
  * ImageRenderer - terminal frontend extension:
@@ -18,8 +20,9 @@ const PLACEHOLDER_HEIGHT = 24;
  * - draw image tiles onRender
  */
 export class ImageRenderer extends Disposable implements IDisposable {
-  public canvas: HTMLCanvasElement | undefined;
-  private _ctx: CanvasRenderingContext2D | null | undefined;
+  /** @deprecated Kept for backward compat — points to top layer canvas. */
+  public get canvas(): HTMLCanvasElement | undefined { return this._layers.get('top')?.canvas; }
+  private _layers = new Map<ImageLayer, CanvasRenderingContext2D>();
   private _placeholder: HTMLCanvasElement | undefined;
   private _placeholderBitmap: ImageBitmap | undefined;
   private _optionsRefresh = this._register(new MutableDisposable());
@@ -38,7 +41,7 @@ export class ImageRenderer extends Disposable implements IDisposable {
      * Only the DOM output canvas should be on the terminal's document,
      * which gets explicitly checked in `insertLayerToDom`.
      */
-    const canvas = (localDocument || document).createElement('canvas');
+    const canvas = (localDocument ?? document).createElement('canvas');
     canvas.width = width | 0;
     canvas.height = height | 0;
     return canvas;
@@ -86,6 +89,7 @@ export class ImageRenderer extends Disposable implements IDisposable {
     });
     this._register(toDisposable(() => {
       this.removeLayerFromDom();
+      this.removeLayerFromDom('bottom');
       if (this._terminal._core && this._oldOpen) {
         this._terminal._core.open = this._oldOpen;
         this._oldOpen = undefined;
@@ -95,8 +99,7 @@ export class ImageRenderer extends Disposable implements IDisposable {
         this._oldSetRenderer = undefined;
       }
       this._renderService = undefined;
-      this.canvas = undefined;
-      this._ctx = undefined;
+      this._layers.clear();
       this._placeholderBitmap?.close();
       this._placeholderBitmap = undefined;
       this._placeholder = undefined;
@@ -109,7 +112,7 @@ export class ImageRenderer extends Disposable implements IDisposable {
   public showPlaceholder(value: boolean): void {
     if (value) {
       if (!this._placeholder && this.cellSize.height !== -1) {
-        this._createPlaceHolder(Math.max(this.cellSize.height + 1, PLACEHOLDER_HEIGHT));
+        this._createPlaceHolder(Math.max(this.cellSize.height + 1, Constants.PLACEHOLDER_HEIGHT));
       }
     } else {
       this._placeholderBitmap?.close();
@@ -140,27 +143,38 @@ export class ImageRenderer extends Disposable implements IDisposable {
   /**
    * Clear a region of the image layer canvas.
    */
-  public clearLines(start: number, end: number): void {
-    this._ctx?.clearRect(
-      0,
-      start * (this.dimensions?.css.cell.height || 0),
-      this.dimensions?.css.canvas.width || 0,
-      (++end - start) * (this.dimensions?.css.cell.height || 0)
-    );
+  public clearLines(start: number, end: number, layer?: ImageLayer): void {
+    const y = start * (this.dimensions?.css.cell.height || 0);
+    const w = this.dimensions?.css.canvas.width || 0;
+    const h = (++end - start) * (this.dimensions?.css.cell.height || 0);
+    if (!layer || layer === 'top') {
+      this._layers.get('top')?.clearRect(0, y, w, h);
+    }
+    if (!layer || layer === 'bottom') {
+      this._layers.get('bottom')?.clearRect(0, y, w, h);
+    }
   }
 
   /**
    * Clear whole image canvas.
    */
-  public clearAll(): void {
-    this._ctx?.clearRect(0, 0, this.canvas?.width || 0, this.canvas?.height || 0);
+  public clearAll(layer?: ImageLayer): void {
+    if (!layer || layer === 'top') {
+      const ctx = this._layers.get('top');
+      ctx?.clearRect(0, 0, ctx.canvas.width, ctx.canvas.height);
+    }
+    if (!layer || layer === 'bottom') {
+      const ctx = this._layers.get('bottom');
+      ctx?.clearRect(0, 0, ctx.canvas.width, ctx.canvas.height);
+    }
   }
 
   /**
    * Draw neighboring tiles on the image layer canvas.
    */
   public draw(imgSpec: IImageSpec, tileId: number, col: number, row: number, count: number = 1): void {
-    if (!this._ctx) {
+    const ctx = this._layers.get(imgSpec.layer);
+    if (!ctx) {
       return;
     }
     const { width, height } = this.cellSize;
@@ -187,7 +201,7 @@ export class ImageRenderer extends Disposable implements IDisposable {
     // Note: For not pixel perfect aligned cells like in the DOM renderer
     // this will move a tile slightly to the top/left (subpixel range, thus ignore it).
     // FIX #34: avoid striping on displays with pixelDeviceRatio != 1 by ceiling height and width
-    this._ctx.drawImage(
+    ctx.drawImage(
       img,
       Math.floor(sx), Math.floor(sy), Math.ceil(finalWidth), Math.ceil(finalHeight),
       Math.floor(dx), Math.floor(dy), Math.ceil(finalWidth), Math.ceil(finalHeight)
@@ -227,7 +241,8 @@ export class ImageRenderer extends Disposable implements IDisposable {
    * Draw a line with placeholder on the image layer canvas.
    */
   public drawPlaceholder(col: number, row: number, count: number = 1): void {
-    if (this._ctx) {
+    const ctx = this._layers.get('top');
+    if (ctx) {
       const { width, height } = this.cellSize;
 
       // Don't try to draw anything, if we cannot get valid renderer metrics.
@@ -236,13 +251,13 @@ export class ImageRenderer extends Disposable implements IDisposable {
       }
 
       if (!this._placeholder) {
-        this._createPlaceHolder(Math.max(height + 1, PLACEHOLDER_HEIGHT));
+        this._createPlaceHolder(Math.max(height + 1, Constants.PLACEHOLDER_HEIGHT));
       } else if (height >= this._placeholder!.height) {
         this._createPlaceHolder(height + 1);
       }
       if (!this._placeholder) return;
-      this._ctx.drawImage(
-        this._placeholderBitmap || this._placeholder!,
+      ctx.drawImage(
+        this._placeholderBitmap ?? this._placeholder!,
         col * width,
         (row * height) % 2 ? 0 : 1,  // needs %2 offset correction
         width * count,
@@ -260,12 +275,13 @@ export class ImageRenderer extends Disposable implements IDisposable {
    * Checked once from `ImageStorage.render`.
    */
   public rescaleCanvas(): void {
-    if (!this.canvas) {
-      return;
-    }
-    if (this.canvas.width !== this.dimensions!.css.canvas.width || this.canvas.height !== this.dimensions!.css.canvas.height) {
-      this.canvas.width = this.dimensions!.css.canvas.width || 0;
-      this.canvas.height = this.dimensions!.css.canvas.height || 0;
+    const w = this.dimensions?.css.canvas.width || 0;
+    const h = this.dimensions?.css.canvas.height || 0;
+    for (const ctx of this._layers.values()) {
+      if (ctx.canvas.width !== w || ctx.canvas.height !== h) {
+        ctx.canvas.width = w;
+        ctx.canvas.height = h;
+      }
     }
   }
 
@@ -304,38 +320,68 @@ export class ImageRenderer extends Disposable implements IDisposable {
     this._renderService = this._terminal._core._renderService;
     this._oldSetRenderer = this._renderService.setRenderer.bind(this._renderService);
     this._renderService.setRenderer = (renderer: any) => {
-      this.removeLayerFromDom();
+      for (const key of [...this._layers.keys()]) {
+        this.removeLayerFromDom(key);
+      }
       this._oldSetRenderer?.call(this._renderService, renderer);
     };
   }
 
-  public insertLayerToDom(): void {
+  public insertLayerToDom(layer: ImageLayer = 'top'): void {
     // make sure that the terminal is attached to a document and to DOM
-    if (this.document && this._terminal._core.screenElement) {
-      if (!this.canvas) {
-        this.canvas = ImageRenderer.createCanvas(
-          this.document, this.dimensions?.css.canvas.width || 0,
-          this.dimensions?.css.canvas.height || 0
-        );
-        this.canvas.classList.add('xterm-image-layer');
-        this._terminal._core.screenElement.appendChild(this.canvas);
-        this._ctx = this.canvas.getContext('2d', { alpha: true, desynchronized: true });
-        this.clearAll();
-      }
-    } else {
+    if (!this.document || !this._terminal._core.screenElement) {
       console.warn('image addon: cannot insert output canvas to DOM, missing document or screenElement');
+      return;
+    }
+    if (this._layers.has(layer)) {
+      return;
+    }
+    const canvas = ImageRenderer.createCanvas(
+      this.document, this.dimensions?.css.canvas.width || 0,
+      this.dimensions?.css.canvas.height || 0
+    );
+    canvas.classList.add(`xterm-image-layer-${layer}`);
+    const screenElement = this._terminal._core.screenElement;
+    // Use isolation to create a stacking context without overriding z-index,
+    // which would conflict with integrators (e.g. VS Code) that set their
+    // own z-index on the screen element.
+    screenElement.style.isolation = 'isolate';
+    if (layer === 'bottom') {
+      // Use z-index:-1 so it paints behind non-positioned text elements.
+      // The screen element needs to be a stacking context (via isolation)
+      // to contain the negative z-index, otherwise it would go behind the
+      // entire terminal.
+      canvas.style.zIndex = '-1';
+      screenElement.insertBefore(canvas, screenElement.firstChild);
+    } else {
+      // Explicit z-index ensures the image canvas reliably stacks above
+      // the text layer (DOM renderer rows). z-index: 0 is below the
+      // selection overlay (z-index: 1).
+      canvas.style.zIndex = '0';
+      screenElement.appendChild(canvas);
+    }
+    const ctx = canvas.getContext('2d', { alpha: true });
+    if (!ctx) {
+      canvas.remove();
+      return;
+    }
+    this._layers.set(layer, ctx);
+    this.clearAll(layer);
+  }
+
+  public removeLayerFromDom(layer: ImageLayer = 'top'): void {
+    const ctx = this._layers.get(layer);
+    if (ctx) {
+      ctx.canvas.remove();
+      this._layers.delete(layer);
     }
   }
 
-  public removeLayerFromDom(): void {
-    if (this.canvas) {
-      this._ctx = undefined;
-      this.canvas.remove();
-      this.canvas = undefined;
-    }
+  public hasLayer(layer: ImageLayer): boolean {
+    return this._layers.has(layer);
   }
 
-  private _createPlaceHolder(height: number = PLACEHOLDER_HEIGHT): void {
+  private _createPlaceHolder(height: number = Constants.PLACEHOLDER_HEIGHT): void {
     this._placeholderBitmap?.close();
     this._placeholderBitmap = undefined;
 
@@ -359,7 +405,7 @@ export class ImageRenderer extends Disposable implements IDisposable {
     ctx.putImageData(imgData, 0, 0);
 
     // create placeholder line, width aligned to blueprint width
-    const width = (screen.width + bWidth - 1) & ~(bWidth - 1) || PLACEHOLDER_LENGTH;
+    const width = (screen.width + bWidth - 1) & ~(bWidth - 1) || Constants.PLACEHOLDER_LENGTH;
     this._placeholder = ImageRenderer.createCanvas(this.document, width, height);
     const ctx2 = this._placeholder.getContext('2d', { alpha: false });
     if (!ctx2) {

addons/addon-image/src/ImageStorage.ts

@@ -5,7 +5,7 @@
 
 import { IDisposable } from '@xterm/xterm';
 import { ImageRenderer } from './ImageRenderer';
-import { ITerminalExt, IExtendedAttrsImage, IImageAddonOptions, IImageSpec, IBufferLineExt, BgFlags, Cell, Content, ICellSize, ExtFlags, Attributes, UnderlineStyle } from './Types';
+import { ITerminalExt, IExtendedAttrsImage, IImageAddonOptions, IImageSpec, IBufferLineExt, BgFlags, Cell, Content, ICellSize, ExtFlags, Attributes, UnderlineStyle, ImageLayer } from './Types';
 
 
 // fallback default cell size
@@ -124,6 +124,8 @@ export class ImageStorage implements IDisposable {
   private _pixelLimit: number = 2500000;
 
   private _viewportMetrics: { cols: number, rows: number };
+  public onImageAdded: (() => void) | undefined;
+  public onImageDeleted: ((storageId: number) => void) | undefined;
 
   constructor(
     private _terminal: ITerminalExt,
@@ -132,8 +134,10 @@ export class ImageStorage implements IDisposable {
   ) {
     try {
       this.setLimit(this._opts.storageLimit);
-    } catch (e: any) {
-      console.error(e.message);
+    } catch (e: unknown) {
+      if (e instanceof Error) {
+        console.error(e.message);
+      }
       console.warn(`storageLimit is set to ${this.getLimit()} MB`);
     }
     this._viewportMetrics = {
@@ -187,11 +191,13 @@ export class ImageStorage implements IDisposable {
 
   private _delImg(id: number): void {
     const spec = this._images.get(id);
+    if (!spec) return;
     this._images.delete(id);
     // FIXME: really ugly workaround to get bitmaps deallocated :(
-    if (spec && window.ImageBitmap && spec.orig instanceof ImageBitmap) {
+    if (window.ImageBitmap && spec.orig instanceof ImageBitmap) {
       spec.orig.close();
     }
+    this.onImageDeleted?.(id);
   }
 
   /**
@@ -215,27 +221,27 @@ export class ImageStorage implements IDisposable {
   }
 
   /**
-   * Only advance text cursor.
-   * This is an edge case from empty sixels carrying only a height but no pixels.
-   * Partially fixes https://github.com/jerch/xterm-addon-image/issues/37.
+   * Delete an image by its internal storage ID.
+   * Used by protocols that support explicit deletion (e.g. Kitty a=d).
    */
-  public advanceCursor(height: number): void {
-    if (this._opts.sixelScrolling) {
-      let cellSize = this._renderer.cellSize;
-      if (cellSize.width === -1 || cellSize.height === -1) {
-        cellSize = CELL_SIZE_DEFAULT;
-      }
-      const rows = Math.ceil(height / cellSize.height);
-      for (let i = 1; i < rows; ++i) {
-        this._terminal._core._inputHandler.lineFeed();
-      }
+  public deleteImage(id: number): void {
+    const spec = this._images.get(id);
+    if (spec) {
+      spec.marker?.dispose();
+      this._delImg(id);
     }
   }
 
   /**
    * Method to add an image to the storage.
+   * @param img - The image to add (canvas or bitmap).
+   * @param scrolling - When true, cursor advances with the image (lineFeed per row).
+   *   When false, image is placed at (0,0) and cursor is restored (DECSET 80 / sixel origin mode).
+   * @param layer - Which canvas layer to render on ('top' or 'bottom').
+   * @param zIndex - Z-index for image layering within the same layer.
+   * @returns The internal image ID assigned to the stored image.
    */
-  public addImage(img: HTMLCanvasElement | ImageBitmap): void {
+  public addImage(img: HTMLCanvasElement | ImageBitmap, scrolling: boolean, layer: ImageLayer = 'top', zIndex: number = 0): number {
     // never allow storage to exceed memory limit
     this._evictOldest(img.width * img.height);
 
@@ -257,7 +263,7 @@ export class ImageStorage implements IDisposable {
     let offset = originX;
     let tileCount = 0;
 
-    if (!this._opts.sixelScrolling) {
+    if (!scrolling) {
       buffer.x = 0;
       buffer.y = 0;
       offset = 0;
@@ -271,7 +277,7 @@ export class ImageStorage implements IDisposable {
         this._writeToCell(line as IBufferLineExt, offset + col, imageId, row * cols + col);
         tileCount++;
       }
-      if (this._opts.sixelScrolling) {
+      if (scrolling) {
         if (row < rows - 1) this._terminal._core._inputHandler.lineFeed();
       } else {
         if (++buffer.y >= termRows) break;
@@ -281,7 +287,7 @@ export class ImageStorage implements IDisposable {
     this._terminal._core._inputHandler._dirtyRowTracker.markDirty(buffer.y);
 
     // cursor positioning modes
-    if (this._opts.sixelScrolling) {
+    if (scrolling) {
       buffer.x = offset;
     } else {
       buffer.x = originX;
@@ -324,11 +330,15 @@ export class ImageStorage implements IDisposable {
       actualCellSize: { ...cellSize },  // clone needed, since later modified
       marker: endMarker || undefined,
       tileCount,
-      bufferType: this._terminal.buffer.active.type
+      bufferType: this._terminal.buffer.active.type,
+      layer,
+      zIndex
     };
 
     // finally add the image
     this._images.set(imageId, imgSpec);
+    this.onImageAdded?.();
+    return imageId;
   }
 
 
@@ -338,16 +348,30 @@ export class ImageStorage implements IDisposable {
    */
   // TODO: Should we move this to the ImageRenderer?
   public render(range: { start: number, end: number }): void {
-    // setup image canvas in case we have none yet, but have images in store
-    if (!this._renderer.canvas && this._images.size) {
-      this._renderer.insertLayerToDom();
-      // safety measure - in case we cannot spawn a canvas at all, just exit
-      if (!this._renderer.canvas) {
-        return;
+    // Determine which layers have images
+    let hasTopImages = false;
+    let hasBottomImages = false;
+    for (const spec of this._images.values()) {
+      if (spec.layer === 'bottom') {
+        hasBottomImages = true;
+      } else {
+        hasTopImages = true;
       }
+      if (hasTopImages && hasBottomImages) break;
     }
+
+    // Lazily insert layers that are needed
+    if (hasTopImages && !this._renderer.hasLayer('top')) {
+      this._renderer.insertLayerToDom('top');
+      if (!this._renderer.hasLayer('top')) return;
+    }
+    if (hasBottomImages && !this._renderer.hasLayer('bottom')) {
+      this._renderer.insertLayerToDom('bottom');
+    }
+
     // rescale if needed
     this._renderer.rescaleCanvas();
+
     // exit early if we dont have any images to test for
     if (!this._images.size) {
       if (!this._fullyCleared) {
@@ -355,12 +379,25 @@ export class ImageStorage implements IDisposable {
         this._fullyCleared = true;
         this._needsFullClear = false;
       }
-      if (this._renderer.canvas) {
-        this._renderer.removeLayerFromDom();
+      if (this._renderer.hasLayer('top')) {
+        this._renderer.removeLayerFromDom('top');
+      }
+      if (this._renderer.hasLayer('bottom')) {
+        this._renderer.removeLayerFromDom('bottom');
       }
       return;
     }
 
+    // Remove layers no longer needed
+    if (!hasTopImages && this._renderer.hasLayer('top')) {
+      this._renderer.clearAll('top');
+      this._renderer.removeLayerFromDom('top');
+    }
+    if (!hasBottomImages && this._renderer.hasLayer('bottom')) {
+      this._renderer.clearAll('bottom');
+      this._renderer.removeLayerFromDom('bottom');
+    }
+
     // buffer switches force a full clear
     if (this._needsFullClear) {
       this._renderer.clearAll();
@@ -375,50 +412,77 @@ export class ImageStorage implements IDisposable {
     // clear drawing area
     this._renderer.clearLines(start, end);
 
-    // walk all cells in viewport and draw tiles found
+    // Collect draw calls so we can sort by z-index (lower z drawn first).
+    const drawCalls: { imgSpec: IImageSpec, tileId: number, col: number, row: number, count: number }[] = [];
+    const placeholderCalls: { col: number, row: number, count: number }[] = [];
+
+    // walk all cells in viewport and collect tiles found
+    // Note: We check _extendedAttrs directly (not just HAS_EXTENDED flag)
+    // because text writes clear the BG flag but leave image tile data intact.
+    // This lets top-layer images survive text overwrites (kitty C=1 behavior).
     for (let row = start; row <= end; ++row) {
       const line = buffer.lines.get(row + buffer.ydisp) as IBufferLineExt;
       if (!line) return;
       for (let col = 0; col < cols; ++col) {
+        let e: IExtendedAttrsImage;
         if (line.getBg(col) & BgFlags.HAS_EXTENDED) {
-          let e: IExtendedAttrsImage = line._extendedAttrs[col] || EMPTY_ATTRS;
-          const imageId = e.imageId;
-          if (imageId === undefined || imageId === -1) {
+          e = line._extendedAttrs[col] ?? EMPTY_ATTRS;
+        } else {
+          const maybeImg = line._extendedAttrs[col] as IExtendedAttrsImage | undefined;
+          if (!maybeImg || maybeImg.imageId === undefined || maybeImg.imageId === -1) {
             continue;
           }
-          const imgSpec = this._images.get(imageId);
-          if (e.tileId !== -1) {
-            const startTile = e.tileId;
-            const startCol = col;
-            let count = 1;
-            /**
-             * merge tiles to the right into a single draw call, if:
-             * - not at end of line
-             * - cell has same image id
-             * - cell has consecutive tile id
-             */
-            while (
-              ++col < cols
-              && (line.getBg(col) & BgFlags.HAS_EXTENDED)
-              && (e = line._extendedAttrs[col] || EMPTY_ATTRS)
-              && (e.imageId === imageId)
-              && (e.tileId === startTile + count)
-            ) {
-              count++;
+          e = maybeImg;
+        }
+        const imageId = e.imageId;
+        if (imageId === undefined || imageId === -1) {
+          continue;
+        }
+        const imgSpec = this._images.get(imageId);
+        if (e.tileId !== -1) {
+          const startTile = e.tileId;
+          const startCol = col;
+          let count = 1;
+          /**
+           * merge tiles to the right into a single draw call, if:
+           * - not at end of line
+           * - cell has same image id
+           * - cell has consecutive tile id
+           * Also check _extendedAttrs directly for cells where text cleared HAS_EXTENDED.
+           */
+          while (++col < cols) {
+            const nextE = line._extendedAttrs[col] as IExtendedAttrsImage | undefined;
+            if (!nextE || nextE.imageId !== imageId || nextE.tileId !== startTile + count) {
+              break;
             }
-            col--;
-            if (imgSpec) {
-              if (imgSpec.actual) {
-                this._renderer.draw(imgSpec, startTile, startCol, row, count);
-              }
-            } else if (this._opts.showPlaceholder) {
-              this._renderer.drawPlaceholder(startCol, row, count);
-            }
-            this._fullyCleared = false;
+            e = nextE;
+            count++;
           }
+          col--;
+          if (imgSpec) {
+            if (imgSpec.actual) {
+              drawCalls.push({ imgSpec, tileId: startTile, col: startCol, row, count });
+            }
+          } else if (this._opts.showPlaceholder) {
+            placeholderCalls.push({ col: startCol, row, count });
+          }
+          this._fullyCleared = false;
         }
       }
     }
+
+    // Sort by z-index so lower z draws first (higher z renders on top)
+    drawCalls.sort((a, b) => a.imgSpec.zIndex - b.imgSpec.zIndex);
+
+    // Draw placeholders first (lowest priority)
+    for (const call of placeholderCalls) {
+      this._renderer.drawPlaceholder(call.col, call.row, call.count);
+    }
+
+    // Draw images in z-index order
+    for (const call of drawCalls) {
+      this._renderer.draw(call.imgSpec, call.tileId, call.col, call.row, call.count);
+    }
   }
 
   public viewportResize(metrics: { cols: number, rows: number }): void {
@@ -442,7 +506,7 @@ export class ImageStorage implements IDisposable {
     for (let row = 0; row < rows; ++row) {
       const line = buffer.lines.get(row) as IBufferLineExt;
       if (line.getBg(oldCol) & BgFlags.HAS_EXTENDED) {
-        const e: IExtendedAttrsImage = line._extendedAttrs[oldCol] || EMPTY_ATTRS;
+        const e: IExtendedAttrsImage = line._extendedAttrs[oldCol] ?? EMPTY_ATTRS;
         const imageId = e.imageId;
         if (imageId === undefined || imageId === -1) {
           continue;
@@ -487,7 +551,7 @@ export class ImageStorage implements IDisposable {
     const buffer = this._terminal._core.buffer;
     const line = buffer.lines.get(y) as IBufferLineExt;
     if (line && line.getBg(x) & BgFlags.HAS_EXTENDED) {
-      const e: IExtendedAttrsImage = line._extendedAttrs[x] || EMPTY_ATTRS;
+      const e: IExtendedAttrsImage = line._extendedAttrs[x] ?? EMPTY_ATTRS;
       if (e.imageId && e.imageId !== -1) {
         const orig = this._images.get(e.imageId)?.orig;
         if (window.ImageBitmap && orig instanceof ImageBitmap) {
@@ -507,7 +571,7 @@ export class ImageStorage implements IDisposable {
     const buffer = this._terminal._core.buffer;
     const line = buffer.lines.get(y) as IBufferLineExt;
     if (line && line.getBg(x) & BgFlags.HAS_EXTENDED) {
-      const e: IExtendedAttrsImage = line._extendedAttrs[x] || EMPTY_ATTRS;
+      const e: IExtendedAttrsImage = line._extendedAttrs[x] ?? EMPTY_ATTRS;
       if (e.imageId && e.imageId !== -1 && e.tileId !== -1) {
         const spec = this._images.get(e.imageId);
         if (spec) {

addons/addon-image/src/SixelHandler.ts

@@ -3,7 +3,7 @@
  * @license MIT
  */
 
-import { ImageStorage } from './ImageStorage';
+import { SixelImageStorage } from './SixelImageStorage';
 import { IDcsHandler, IParams, IImageAddonOptions, ITerminalExt, AttributeData, IResetHandler, ReadonlyColorSet } from './Types';
 import { toRGBA8888, BIG_ENDIAN, PALETTE_ANSI_256, PALETTE_VT340_COLOR } from 'sixel/lib/Colors';
 import { RGBA8888 } from 'sixel/lib/Types';
@@ -26,7 +26,7 @@ export class SixelHandler implements IDcsHandler, IResetHandler {
 
   constructor(
     private readonly _opts: IImageAddonOptions,
-    private readonly _storage: ImageStorage,
+    private readonly _storage: SixelImageStorage,
     private readonly _coreTerminal: ITerminalExt
   ) {
     DecoderAsync({
@@ -91,7 +91,7 @@ export class SixelHandler implements IDcsHandler, IResetHandler {
     const height = this._dec.height;
 
     // partial fix for https://github.com/jerch/xterm-addon-image/issues/37
-    if (!width || ! height) {
+    if (!width || !height) {
       if (height) {
         this._storage.advanceCursor(height);
       }

addons/addon-image/src/SixelImageStorage.ts

@@ -0,0 +1,50 @@
+/**
+ * Copyright (c) 2020 The xterm.js authors. All rights reserved.
+ * @license MIT
+ */
+
+import { ImageStorage, CELL_SIZE_DEFAULT } from './ImageStorage';
+import { IImageAddonOptions, ITerminalExt } from './Types';
+import { ImageRenderer } from './ImageRenderer';
+
+/**
+ * Sixel-specific image storage controller.
+ *
+ * Wraps the shared ImageStorage with sixel protocol semantics:
+ * - Cursor behavior governed by DECSET 80 (sixelScrolling option)
+ * - advanceCursor for empty sixels carrying only height
+ */
+export class SixelImageStorage {
+  constructor(
+    private readonly _storage: ImageStorage,
+    private readonly _opts: IImageAddonOptions,
+    private readonly _renderer: ImageRenderer,
+    private readonly _terminal: ITerminalExt
+  ) {}
+
+  /**
+   * Add a sixel image to storage.
+   * Cursor behavior depends on the sixelScrolling option (DECSET 80).
+   */
+  public addImage(img: HTMLCanvasElement | ImageBitmap): void {
+    this._storage.addImage(img, this._opts.sixelScrolling);
+  }
+
+  /**
+   * Only advance text cursor.
+   * This is an edge case from empty sixels carrying only a height but no pixels.
+   * Partially fixes https://github.com/jerch/xterm-addon-image/issues/37.
+   */
+  public advanceCursor(height: number): void {
+    if (this._opts.sixelScrolling) {
+      let cellSize = this._renderer.cellSize;
+      if (cellSize.width === -1 || cellSize.height === -1) {
+        cellSize = CELL_SIZE_DEFAULT;
+      }
+      const rows = Math.ceil(height / cellSize.height);
+      for (let i = 1; i < rows; ++i) {
+        this._terminal._core._inputHandler.lineFeed();
+      }
+    }
+  }
+}

addons/addon-image/src/Types.ts

@@ -8,7 +8,7 @@ import { IDisposable, IMarker, Terminal } from '@xterm/xterm';
 // private imports from base repo we build against
 import { Attributes, BgFlags, Content, ExtFlags, UnderlineStyle } from 'common/buffer/Constants';
 import type { AttributeData } from 'common/buffer/AttributeData';
-import type { IParams, IDcsHandler, IOscHandler, IEscapeSequenceParser } from 'common/parser/Types';
+import type { IParams, IDcsHandler, IOscHandler, IApcHandler, IEscapeSequenceParser } from 'common/parser/Types';
 import type { IBufferLine, IExtendedAttrs, IInputHandler } from 'common/Types';
 import type { ITerminal, ReadonlyColorSet } from 'browser/Types';
 import type { IRenderDimensions } from 'browser/renderer/shared/Types';
@@ -22,7 +22,7 @@ export const enum Cell {
 }
 
 // export some privates for local usage
-export { AttributeData, IParams, IDcsHandler, IOscHandler, BgFlags, IRenderDimensions, IRenderService, Content, ExtFlags, Attributes, UnderlineStyle, ReadonlyColorSet };
+export { AttributeData, IParams, IDcsHandler, IOscHandler, IApcHandler, BgFlags, IRenderDimensions, IRenderService, Content, ExtFlags, Attributes, UnderlineStyle, ReadonlyColorSet };
 
 /**
  * Plugin ctor options.
@@ -38,6 +38,8 @@ export interface IImageAddonOptions {
   sixelSizeLimit: number;
   iipSupport: boolean;
   iipSizeLimit: number;
+  kittySupport: boolean;
+  kittySizeLimit: number;
 }
 
 export interface IResetHandler {
@@ -97,6 +99,8 @@ export interface ICellSize {
   height: number;
 }
 
+export type ImageLayer = 'top' | 'bottom';
+
 export interface IImageSpec {
   orig: HTMLCanvasElement | ImageBitmap | undefined;
   origCellSize: ICellSize;
@@ -105,4 +109,6 @@ export interface IImageSpec {
   marker: IMarker | undefined;
   tileCount: number;
   bufferType: 'alternate' | 'normal';
+  layer: ImageLayer;
+  zIndex: number;
 }

addons/addon-image/src/kitty/KittyGraphicsHandler.ts

@@ -0,0 +1,819 @@
+/**
+ * Copyright (c) 2026 The xterm.js authors. All rights reserved.
+ * @license MIT
+ */
+
+import { IDisposable } from '@xterm/xterm';
+import { IApcHandler, IImageAddonOptions, IResetHandler, ITerminalExt, ImageLayer } from '../Types';
+import { ImageRenderer } from '../ImageRenderer';
+import { CELL_SIZE_DEFAULT } from '../ImageStorage';
+import { KittyImageStorage } from './KittyImageStorage';
+import Base64Decoder, { type DecodeStatus } from 'xterm-wasm-parts/lib/base64/Base64Decoder.wasm';
+import {
+  KittyAction,
+  KittyFormat,
+  KittyCompression,
+  IKittyCommand,
+  IPendingTransmission,
+  IKittyImageData,
+  KittyPixelConstants,
+  parseKittyCommand
+} from './KittyGraphicsTypes';
+
+const enum Constants {
+  // Memory limit for base64 decoder (4MB, same as IIPHandler)
+  DECODER_KEEP_DATA = 4194304,
+  DECODER_INITIAL_DATA = 4194304, // 4MB
+  // Local mirror of const enum (esbuild can't inline const enums from external packages)
+  DECODER_OK = 0,
+  // Maximum control data size
+  MAX_CONTROL_DATA_SIZE = 512,
+  // Semicolon codepoint
+  SEMICOLON = 0x3B
+}
+
+const DECODER_OK = Constants.DECODER_OK as unknown as DecodeStatus.OK;
+
+// Kitty graphics protocol handler with streaming base64 decoding.
+export class KittyGraphicsHandler implements IApcHandler, IResetHandler, IDisposable {
+  private _aborted = false;
+  private _decodeError = false;
+
+  private _activeDecoder: Base64Decoder | null = null;
+  private readonly _maxEncodedBytes: number;
+  private readonly _initialEncodedBytes: number;
+
+  // Streaming related states
+
+  // True while receiving control data (before semicolon).
+  private _inControlData = true;
+
+  // Buffer for control data.
+  private _controlData = new Uint32Array(Constants.MAX_CONTROL_DATA_SIZE);
+  private _controlLength = 0;
+
+  // Pre-calculated encoded size limit
+  private _encodedSizeLimit = 0;
+  private _totalEncodedSize = 0;
+
+  // Parsed command. These are the control data before semicolon.
+  private _parsedCommand: IKittyCommand | null = null;
+
+  // Storage related states
+
+  private _pendingTransmissions: Map<number, IPendingTransmission> = new Map();
+  // Tracks the pending key of the most recently started chunked upload.
+  // Per spec, subsequent chunks only need m= (and optionally q=), without i=.
+  // When a chunk arrives with no i=, this key is used to find the pending upload.
+  private _lastPendingKey: number | undefined;
+
+  constructor(
+    private readonly _opts: IImageAddonOptions,
+    private readonly _renderer: ImageRenderer,
+    private readonly _kittyStorage: KittyImageStorage,
+    private readonly _coreTerminal: ITerminalExt
+  ) {
+    // Convert decoded size limit -> max encoded bytes.
+    this._maxEncodedBytes = Math.ceil(this._opts.kittySizeLimit * 4 / 3);
+    // ensure we preallocate more than configured limit while using 4mb initial size.
+    this._initialEncodedBytes = Math.min(Constants.DECODER_INITIAL_DATA, this._maxEncodedBytes);
+  }
+
+  public reset(): void {
+    this._cleanupAllPending();
+    if (this._activeDecoder) {
+      this._activeDecoder.release();
+      this._activeDecoder = null;
+    }
+    this._kittyStorage.reset();
+  }
+
+  public dispose(): void {
+    this.reset();
+  }
+
+  private _removePendingEntry(key: number): void {
+    this._pendingTransmissions.delete(key);
+    if (this._lastPendingKey === key) {
+      this._lastPendingKey = undefined;
+    }
+  }
+
+  private _cleanupAllPending(): void {
+    for (const pending of this._pendingTransmissions.values()) {
+      pending.decoder.release();
+    }
+    this._pendingTransmissions.clear();
+    this._lastPendingKey = undefined;
+  }
+
+  public start(): void {
+    this._aborted = false;
+    this._decodeError = false;
+    this._inControlData = true;
+    this._controlLength = 0;
+    this._parsedCommand = null;
+    // Pre-calculate encoded limit once: base64 is 4 bytes encoded → 3 bytes decoded
+    this._encodedSizeLimit = this._maxEncodedBytes;
+    this._totalEncodedSize = 0;
+    this._activeDecoder = null;
+  }
+
+  public put(data: Uint32Array, start: number, end: number): void {
+    if (this._aborted) return;
+
+    if (!this._inControlData) {
+      this._streamPayload(data, start, end);
+    } else {
+      // Scan for semicolon
+      let controlEnd = end;
+      for (let i = start; i < end; i++) {
+        if (data[i] === Constants.SEMICOLON) {
+          this._inControlData = false;
+          controlEnd = i;
+          break;
+        }
+      }
+
+      // Copy control data
+      const copyLength = controlEnd - start;
+      if (this._controlLength + copyLength > Constants.MAX_CONTROL_DATA_SIZE) {
+        this._aborted = true;
+        return;
+      }
+      this._controlData.set(data.subarray(start, controlEnd), this._controlLength);
+      this._controlLength += copyLength;
+
+      if (!this._inControlData) {
+        // Found semicolon - parse control data early for validation
+        this._parsedCommand = parseKittyCommand(this._parseControlDataString());
+
+        // Early validation: i+I conflict
+        if (this._parsedCommand.id !== undefined && this._parsedCommand.imageNumber !== undefined) {
+          this._sendResponse(this._parsedCommand.id, 'EINVAL:cannot specify both i and I keys', this._parsedCommand.quiet ?? 0);
+          this._aborted = true;
+          return;
+        }
+
+        // Delete action doesn't need payload - skip streaming
+        if (this._parsedCommand.action === KittyAction.DELETE) {
+          return;
+        }
+
+        // Stream remaining as payload
+        const payloadStart = controlEnd + 1;
+        if (payloadStart < end) {
+          this._streamPayload(data, payloadStart, end);
+        }
+      }
+    }
+  }
+
+  // Stream payload bytes into the base64 decoder.
+  private _streamPayload(data: Uint32Array, start: number, end: number): void {
+    if (this._aborted) return;
+
+    // Check size limit (compare encoded bytes against pre-calculated limit)
+    // Include cumulative size from pending transmission for multi-chunk images.
+    // Per spec, subsequent chunks may omit i=, so fall back to _lastPendingKey.
+    const pendingKey = this._parsedCommand?.id ?? this._lastPendingKey ?? 0;
+    const pending = this._pendingTransmissions.get(pendingKey);
+    const previousEncodedSize = pending?.totalEncodedSize ?? 0;
+    this._totalEncodedSize += end - start;
+    const cumulativeEncodedSize = previousEncodedSize + this._totalEncodedSize;
+    if (cumulativeEncodedSize > this._encodedSizeLimit) {
+      const decoderToRelease = this._activeDecoder ?? pending?.decoder;
+      if (decoderToRelease) {
+        decoderToRelease.release();
+      }
+      this._activeDecoder = null;
+      if (pending) {
+        this._removePendingEntry(pendingKey);
+      }
+      this._aborted = true;
+      return;
+    }
+
+    if (this._decodeError) return;
+
+    if (pending?.decoder && !this._activeDecoder) {
+      this._activeDecoder = pending.decoder;
+    }
+    if (!this._activeDecoder) {
+      this._activeDecoder = new Base64Decoder(Constants.DECODER_KEEP_DATA, this._maxEncodedBytes, this._initialEncodedBytes);
+      this._activeDecoder.init();
+    }
+
+    if (this._activeDecoder.put(data.subarray(start, end)) !== DECODER_OK) {
+      this._activeDecoder.release();
+      this._activeDecoder = null;
+      this._decodeError = true;
+      if (pending) {
+        this._removePendingEntry(pendingKey);
+      }
+    }
+  }
+
+  public end(success: boolean): boolean | Promise<boolean> {
+    if (this._aborted || !success) {
+      if (this._activeDecoder) {
+        this._activeDecoder.release();
+        this._activeDecoder = null;
+      }
+      return true;
+    }
+
+    // No semicolon = no payload (delete, capability query)
+    if (this._inControlData) {
+      return this._handleNoPayloadCommand();
+    }
+
+    // Use command parsed early in put() - i+I already validated there
+    const cmd = this._parsedCommand!;
+
+    // Delete action was handled by skipping payload - just execute
+    if (cmd.action === KittyAction.DELETE) {
+      return this._handleDelete(cmd);
+    }
+
+    // Per spec, subsequent chunks may omit i=, so fall back to _lastPendingKey.
+    const pendingKey = cmd.id ?? this._lastPendingKey ?? 0;
+    const isMoreComing = cmd.more === 1;
+    const pending = this._pendingTransmissions.get(pendingKey);
+
+    if (isMoreComing) {
+      if (this._activeDecoder) {
+        if (pending) {
+          pending.totalEncodedSize += this._totalEncodedSize;
+          pending.decodeError = pending.decodeError || this._decodeError;
+        } else {
+          this._pendingTransmissions.set(pendingKey, {
+            cmd: { ...cmd },
+            decoder: this._activeDecoder,
+            totalEncodedSize: this._totalEncodedSize,
+            decodeError: this._decodeError
+          });
+        }
+        this._lastPendingKey = pendingKey;
+        this._activeDecoder = null;
+      }
+      return true;
+    }
+
+    // Final chunk received — clear the last pending key
+    if (pending) {
+      this._lastPendingKey = undefined;
+    }
+
+    let decodeError = this._decodeError;
+    let finalCmd = cmd;
+    let decoder = this._activeDecoder;
+
+    if (pending) {
+      finalCmd = pending.cmd;
+      decoder = pending.decoder;
+      decodeError = decodeError || pending.decodeError;
+      this._pendingTransmissions.delete(pendingKey);
+    }
+
+    let imageBytes = new Uint8Array(0);
+    if (decoder) {
+      if (decoder.end() !== DECODER_OK) {
+        decodeError = true;
+      }
+      imageBytes = decoder.data8;
+    }
+    this._activeDecoder = null;
+
+    // Handle command first — handlers create Blob/ImageData from imageBytes,
+    // which copies the data. Only then is it safe to release the decoder's
+    // wasm memory that imageBytes points into.
+    const result = this._handleCommandWithBytesAndCmd(finalCmd, imageBytes, decodeError);
+    if (decoder) {
+      decoder.release();
+    }
+    return result;
+  }
+
+  // Command handling
+
+  private _parseControlDataString(): string {
+    let str = '';
+    for (let i = 0; i < this._controlLength; i++) {
+      str += String.fromCodePoint(this._controlData[i]);
+    }
+    return str;
+  }
+
+  private _handleNoPayloadCommand(): boolean | Promise<boolean> {
+    const cmd = parseKittyCommand(this._parseControlDataString());
+
+    // Per spec: specifying both i and I is an error
+    if (cmd.id !== undefined && cmd.imageNumber !== undefined) {
+      this._sendResponse(cmd.id, 'EINVAL:cannot specify both i and I keys', cmd.quiet ?? 0);
+      return true;
+    }
+
+    const action = cmd.action ?? 't';
+
+    switch (action) {
+      case KittyAction.DELETE:
+        return this._handleDelete(cmd);
+      case KittyAction.QUERY:
+        this._sendResponse(cmd.id ?? 0, 'OK', cmd.quiet ?? 0);
+        return true;
+      case KittyAction.PLACEMENT:
+        return this._handlePlacement(cmd);
+      default:
+        // TODO: Implement remaining actions when needed:
+        // - a=f (frame): animation frame operations
+        // - a=a (animation): animation control
+        // - a=c (compose): compose images
+        if (cmd.id !== undefined) {
+          this._sendResponse(cmd.id, 'EINVAL:unsupported action', cmd.quiet ?? 0);
+        }
+        return true;
+    }
+  }
+
+  private _handleCommandWithBytesAndCmd(cmd: IKittyCommand, bytes: Uint8Array, decodeError: boolean): boolean | Promise<boolean> {
+    const action = cmd.action ?? 't';
+
+    switch (action) {
+      case KittyAction.TRANSMIT: {
+        const result = this._handleTransmit(cmd, bytes, decodeError);
+        // Only send response when _handleTransmit didn't already respond
+        // (it handles unsupported transmission medium responses internally)
+        if ((cmd.transmission ?? 'd') === 'd' && cmd.id !== undefined) {
+          if (decodeError) {
+            this._sendResponse(cmd.id, 'EINVAL:invalid base64 data', cmd.quiet ?? 0);
+          } else if (bytes.length > 0) {
+            this._sendResponse(cmd.id, 'OK', cmd.quiet ?? 0);
+          }
+        }
+        return result;
+      }
+      case KittyAction.TRANSMIT_DISPLAY:
+        return this._handleTransmitDisplay(cmd, bytes, decodeError);
+      case KittyAction.QUERY:
+        return this._handleQuery(cmd, bytes, decodeError);
+      case KittyAction.PLACEMENT:
+        // a=p ignores any payload — image data was already transmitted
+        return this._handlePlacement(cmd);
+      default:
+        // TODO: Implement remaining actions when needed:
+        // - a=f (frame): animation frame operations
+        // - a=a (animation): animation control
+        // - a=c (compose): compose images
+        if (cmd.id !== undefined) {
+          this._sendResponse(cmd.id, 'EINVAL:unsupported action', cmd.quiet ?? 0);
+        }
+        return true;
+    }
+  }
+
+  private _handlePlacement(cmd: IKittyCommand): boolean | Promise<boolean> {
+    if (cmd.id === undefined) {
+      return true;
+    }
+    const id = cmd.id;
+    const image = this._kittyStorage.getImage(id);
+    if (!image) {
+      this._sendResponse(id, 'ENOENT:image not found', cmd.quiet ?? 0, cmd.placementId);
+      return true;
+    }
+    const result = this._displayImage(image, cmd);
+    return result.then(success => {
+      this._sendResponse(id, success ? 'OK' : 'EINVAL:image rendering failed', cmd.quiet ?? 0, cmd.placementId);
+      return true;
+    });
+  }
+
+  private _handleTransmit(cmd: IKittyCommand, bytes: Uint8Array, decodeError: boolean): boolean {
+    // TODO: Support file-based transmission modes (t=f, t=t, t=s)
+    // Currently only supports direct transmission (t=d, the default).
+    // - t=f (file): Payload is base64-encoded file path. Terminal reads image from that path.
+    // - t=t (temp file): Payload is base64-encoded path in temp directory. Terminal reads, deletes.
+    // - t=s: Payload is base64-encoded POSIX shm name. Terminal reads from shared memory.
+    // These modes require filesystem/IPC access not available in browsers. For Node.js/Electron:
+    // 1. Check cmd.transmission (t key) before treating bytes as image data
+    // 2. For t=f/t/s: decode bytes as UTF-8 string (the path/name), then read file contents
+    // 3. For t=d: treat bytes as image data (current behavior)
+    // When implementing, also update _handleQuery to accept these transmission mediums.
+    const transmission = cmd.transmission ?? 'd';
+    if (transmission !== 'd') {
+      if (cmd.id !== undefined) {
+        this._sendResponse(cmd.id, 'EINVAL:unsupported transmission medium', cmd.quiet ?? 0);
+      }
+      return true;
+    }
+
+    if (decodeError || bytes.length === 0) return true;
+
+    this._kittyStorage.storeImage(cmd.id, {
+      data: new Blob([bytes as BlobPart]),
+      width: cmd.width ?? 0,
+      height: cmd.height ?? 0,
+      format: (cmd.format ?? KittyFormat.RGBA) as 24 | 32 | 100,
+      compression: cmd.compression ?? ''
+    });
+    return true;
+  }
+
+  private _handleTransmitDisplay(cmd: IKittyCommand, bytes: Uint8Array, decodeError: boolean): boolean | Promise<boolean> {
+    if (decodeError) {
+      if (cmd.id !== undefined) {
+        this._sendResponse(cmd.id, 'EINVAL:invalid base64 data', cmd.quiet ?? 0);
+      }
+      return true;
+    }
+
+    this._handleTransmit(cmd, bytes, decodeError);
+
+    const id = cmd.id ?? this._kittyStorage.lastImageId;
+    const image = this._kittyStorage.getImage(id);
+    if (image) {
+      const result = this._displayImage(image, cmd);
+      if (cmd.id !== undefined) {
+        return result.then(success => {
+          this._sendResponse(id, success ? 'OK' : 'EINVAL:image rendering failed', cmd.quiet ?? 0);
+          return true;
+        });
+      }
+      return result.then(() => true);
+    }
+    return true;
+  }
+
+  private _handleQuery(cmd: IKittyCommand, bytes: Uint8Array, decodeError: boolean): boolean {
+    const id = cmd.id ?? 0;
+    const quiet = cmd.quiet ?? 0;
+
+    // Per spec: reject unsupported transmission mediums (only t=d is supported atm)
+    // TODO: When filesystem support is added (Node.js/Electron), update this to accept
+    // t=f (file), t=t (temp file), and t=s (shared memory) and respond OK for queries.
+    const transmission = cmd.transmission ?? 'd';
+    if (transmission !== 'd') {
+      this._sendResponse(id, 'EINVAL:unsupported transmission medium', quiet);
+      return true;
+    }
+
+    // Check decode error first (invalid base64)
+    if (decodeError) {
+      this._sendResponse(id, 'EINVAL:invalid base64 data', quiet);
+      return true;
+    }
+
+    // Capability query (no payload) - just respond OK
+    if (bytes.length === 0) {
+      this._sendResponse(id, 'OK', quiet);
+      return true;
+    }
+
+    const format = cmd.format ?? KittyFormat.RGBA;
+
+    if (format === KittyFormat.PNG) {
+      this._sendResponse(id, 'OK', quiet);
+    } else {
+      const width = cmd.width ?? 0;
+      const height = cmd.height ?? 0;
+
+      if (!width || !height) {
+        this._sendResponse(id, 'EINVAL:width and height required for raw pixel data', quiet);
+        return true;
+      }
+
+      const bytesPerPixel = format === KittyFormat.RGBA ? KittyPixelConstants.BYTES_PER_PIXEL_RGBA : KittyPixelConstants.BYTES_PER_PIXEL_RGB;
+      const expectedBytes = width * height * bytesPerPixel;
+
+      if (bytes.length < expectedBytes) {
+        this._sendResponse(id, `EINVAL:insufficient pixel data`, quiet);
+        return true;
+      }
+
+      this._sendResponse(id, 'OK', quiet);
+    }
+    return true;
+  }
+
+  private _handleDelete(cmd: IKittyCommand): boolean {
+    // Per spec: default delete selector is 'a' (delete all visible placements)
+    const selector = cmd.deleteSelector ?? 'a';
+
+    // TODO: Distinguish lowercase (delete placements only) from uppercase
+    // (delete placements + free stored image data). Currently both variants
+    // free everything since we don't separate stored data from placements.
+    switch (selector) {
+      case 'a':
+      case 'A':
+        this._cleanupAllPending();
+        this._kittyStorage.deleteAll();
+        break;
+      case 'i':
+      case 'I':
+        // TODO: When placement id tracking is implemented (see TODO in
+        // KittyImageStorage), d=i with p=<pid> should delete only that
+        // specific placement, while d=i without p should delete all
+        // placements for the image.
+        if (cmd.id !== undefined) {
+          const pending = this._pendingTransmissions.get(cmd.id);
+          if (pending) {
+            pending.decoder.release();
+          }
+          this._removePendingEntry(cmd.id);
+          this._kittyStorage.deleteById(cmd.id);
+        }
+        break;
+      default:
+        // Unsupported selectors (c, n, p, q, r, x, y, z, f) — ignore for now
+        break;
+    }
+    return true;
+  }
+
+  private _sendResponse(id: number, message: string, quiet: number, placementId?: number): void {
+    const isOk = message === 'OK';
+    if (isOk && quiet >= 1) return;
+    if (!isOk && quiet >= 2) return;
+
+    const pPart = placementId ? `,p=${placementId}` : '';
+    const response = `\x1b_Gi=${id}${pPart};${message}\x1b\\`;
+    this._coreTerminal._core.coreService.triggerDataEvent(response);
+  }
+
+  // Image display
+
+  private _displayImage(image: IKittyImageData, cmd: IKittyCommand): Promise<boolean> {
+    return this._decodeAndDisplay(image, cmd)
+      .then(() => true)
+      .catch(() => false);
+  }
+
+  private async _decodeAndDisplay(image: IKittyImageData, cmd: IKittyCommand): Promise<void> {
+    let bitmap: ImageBitmap | undefined = await this._createBitmap(image);
+
+    try {
+      const cropX = Math.max(0, cmd.x ?? 0);
+      const cropY = Math.max(0, cmd.y ?? 0);
+      const cropW = cmd.sourceWidth || (bitmap.width - cropX);
+      const cropH = cmd.sourceHeight || (bitmap.height - cropY);
+
+      const maxCropW = Math.max(0, bitmap.width - cropX);
+      const maxCropH = Math.max(0, bitmap.height - cropY);
+      const finalCropW = Math.max(0, Math.min(cropW, maxCropW));
+      const finalCropH = Math.max(0, Math.min(cropH, maxCropH));
+
+      if (finalCropW === 0 || finalCropH === 0) {
+        throw new Error('invalid source rectangle');
+      }
+
+      if (cropX !== 0 || cropY !== 0 || finalCropW !== bitmap.width || finalCropH !== bitmap.height) {
+        const cropped = await createImageBitmap(bitmap, cropX, cropY, finalCropW, finalCropH);
+        bitmap.close();
+        bitmap = cropped;
+      }
+
+      const cw = this._renderer.dimensions?.css.cell.width || CELL_SIZE_DEFAULT.width;
+      const ch = this._renderer.dimensions?.css.cell.height || CELL_SIZE_DEFAULT.height;
+
+      // Per spec: c/r default to image's natural cell dimensions.
+      // If only one of c/r is specified, compute the other from image aspect ratio.
+      let imgCols: number;
+      let imgRows: number;
+      if (cmd.columns !== undefined && cmd.rows !== undefined) {
+        imgCols = cmd.columns;
+        imgRows = cmd.rows;
+      } else if (cmd.columns !== undefined) {
+        imgCols = cmd.columns;
+        imgRows = Math.max(1, Math.ceil((bitmap.height / bitmap.width) * (imgCols * cw) / ch));
+      } else if (cmd.rows !== undefined) {
+        imgRows = cmd.rows;
+        imgCols = Math.max(1, Math.ceil((bitmap.width / bitmap.height) * (imgRows * ch) / cw));
+      } else {
+        imgCols = Math.ceil(bitmap.width / cw);
+        imgRows = Math.ceil(bitmap.height / ch);
+      }
+
+      let w = bitmap.width;
+      let h = bitmap.height;
+
+      // Scale bitmap to fit placement rectangle when c/r are specified
+      if (cmd.columns !== undefined || cmd.rows !== undefined) {
+        w = Math.round(imgCols * cw);
+        h = Math.round(imgRows * ch);
+      }
+
+      if (w * h > this._opts.pixelLimit) {
+        throw new Error('image exceeds pixel limit');
+      }
+
+      // Save cursor position before addImage modifies it
+      const buffer = this._coreTerminal._core.buffer;
+      const savedX = buffer.x;
+      const savedY = buffer.y;
+      const savedYbase = buffer.ybase;
+
+      // Determine layer based on z-index: negative = behind text, 0+ = on top.
+      // When z<0 we always use the bottom layer even without allowTransparency —
+      // the image will simply be hidden behind the opaque text background, which
+      // is the correct behavior (client asked for "behind text").
+      const wantsBottom = cmd.zIndex !== undefined && cmd.zIndex < 0;
+      const layer: ImageLayer = wantsBottom ? 'bottom' : 'top';
+
+      if (w !== bitmap.width || h !== bitmap.height) {
+        const scaled = await createImageBitmap(bitmap, { resizeWidth: w, resizeHeight: h });
+        bitmap.close();
+        bitmap = scaled;
+      }
+
+      // Per spec: X/Y are pixel offsets within the first cell, so clamp to cell dimensions
+      const xOffset = Math.min(Math.max(0, cmd.xOffset ?? 0), cw - 1);
+      const yOffset = Math.min(Math.max(0, cmd.yOffset ?? 0), ch - 1);
+      if (xOffset !== 0 || yOffset !== 0) {
+        // Per spec: X/Y is not added to c/r area. When c/r are explicit, the
+        // total placement area remains c*cw × r*ch pixels and the offset image
+        // is clipped to fit. When c/r are unset, the padded canvas determines
+        // the natural cell dimensions.
+        const canvasW = (cmd.columns !== undefined) ? Math.round(imgCols * cw) : bitmap.width + xOffset;
+        const canvasH = (cmd.rows !== undefined) ? Math.round(imgRows * ch) : bitmap.height + yOffset;
+        const offsetCanvas = ImageRenderer.createCanvas(window.document, canvasW, canvasH);
+        const offsetCtx = offsetCanvas.getContext('2d');
+        if (!offsetCtx) {
+          throw new Error('Failed to create offset canvas context');
+        }
+        offsetCtx.drawImage(bitmap, xOffset, yOffset);
+
+        const offsetBitmap = await createImageBitmap(offsetCanvas);
+        offsetCanvas.width = offsetCanvas.height = 0;
+        bitmap.close();
+        bitmap = offsetBitmap;
+        w = bitmap.width;
+        h = bitmap.height;
+        if (w * h > this._opts.pixelLimit) {
+          throw new Error('image exceeds pixel limit');
+        }
+        if (cmd.columns === undefined) {
+          imgCols = Math.ceil(bitmap.width / cw);
+        }
+        if (cmd.rows === undefined) {
+          imgRows = Math.ceil(bitmap.height / ch);
+        }
+      }
+
+      const zIndex = cmd.zIndex ?? 0;
+      this._kittyStorage.addImage(image.id, bitmap, true, layer, zIndex);
+      bitmap = undefined;  // ownership transferred to storage
+
+      // Kitty cursor movement
+      // Per spec: cursor placed at first column after last image column,
+      // on the last row of the image. C=1 means don't move cursor.
+      if (cmd.cursorMovement === 1) {
+        // C=1: restore cursor to position before image was placed
+        const scrolled = buffer.ybase - savedYbase;
+        buffer.x = savedX;
+        // Can't restore cursor to scrollback?
+        buffer.y = Math.max(savedY - scrolled, 0);
+      } else {
+        // Default (C=0): advance cursor horizontally past the image
+        // addImage already positioned cursor on the last row via lineFeeds
+        buffer.x = Math.min(savedX + imgCols, this._coreTerminal.cols);
+      }
+    } catch (e) {
+      bitmap?.close();
+      throw e;
+    }
+  }
+
+  // Create ImageBitmap from already-decoded image data.
+  private async _createBitmap(image: IKittyImageData): Promise<ImageBitmap> {
+    let bytes: Uint8Array = new Uint8Array(await image.data.arrayBuffer());
+
+    if (image.compression === KittyCompression.ZLIB) {
+      bytes = await this._decompressZlib(bytes);
+    }
+
+    if (image.format === KittyFormat.PNG) {
+      const blob = new Blob([bytes as BlobPart], { type: 'image/png' });
+      if (!window.createImageBitmap) {
+        const url = URL.createObjectURL(blob);
+        const img = new Image();
+        return new Promise<ImageBitmap>((resolve, reject) => {
+          img.addEventListener('load', () => {
+            URL.revokeObjectURL(url);
+            const canvas = ImageRenderer.createCanvas(window.document, img.width, img.height);
+            canvas.getContext('2d')?.drawImage(img, 0, 0);
+            createImageBitmap(canvas).then(resolve).catch(reject);
+          });
+          img.addEventListener('error', () => {
+            URL.revokeObjectURL(url);
+            reject(new Error('Failed to load image'));
+          });
+          img.src = url;
+        });
+      }
+      return createImageBitmap(blob);
+    }
+
+    // Raw pixel data
+    const width = image.width;
+    const height = image.height;
+
+    if (!width || !height) {
+      throw new Error('Width and height required for raw pixel data');
+    }
+
+    const bytesPerPixel = image.format === KittyFormat.RGBA ? KittyPixelConstants.BYTES_PER_PIXEL_RGBA : KittyPixelConstants.BYTES_PER_PIXEL_RGB;
+    const expectedBytes = width * height * bytesPerPixel;
+
+    if (bytes.length < expectedBytes) {
+      throw new Error('Insufficient pixel data');
+    }
+
+    const pixelCount = width * height;
+
+    if (image.format === KittyFormat.RGBA) {
+      // RGBA: use bytes directly — no copy needed
+      return createImageBitmap(new ImageData(new Uint8ClampedArray(bytes.buffer as ArrayBuffer, bytes.byteOffset, pixelCount * KittyPixelConstants.BYTES_PER_PIXEL_RGBA), width, height));
+    }
+
+    // RGB→RGBA: interleave alpha using uint32 block processing (4 pixels per iteration).
+    // 3 uint32 reads + 4 uint32 writes per 4 pixels vs 28 byte reads/writes — ~6x faster.
+    // Assumes little-endian (all modern browsers/Node.js).
+    const data = new Uint8ClampedArray(pixelCount * KittyPixelConstants.BYTES_PER_PIXEL_RGBA);
+    const src32 = new Uint32Array(bytes.buffer, bytes.byteOffset, Math.floor(bytes.byteLength / 4));
+    const dst32 = new Uint32Array(data.buffer);
+    const alignedPixels = pixelCount & ~3;  // round down to multiple of 4
+
+    let srcOffset = 0;
+    let dstOffset = 0;
+    for (let i = 0; i < alignedPixels; i += 4) {
+      const b0 = src32[srcOffset++];
+      const b1 = src32[srcOffset++];
+      const b2 = src32[srcOffset++];
+      // Little-endian: pixel bytes are [R,G,B] → uint32 ABGR layout
+      dst32[dstOffset++] = 0xFF000000 | b0;
+      dst32[dstOffset++] = 0xFF000000 | (b0 >>> 24) | (b1 << 8);
+      dst32[dstOffset++] = 0xFF000000 | (b1 >>> 16) | (b2 << 16);
+      dst32[dstOffset++] = 0xFF000000 | (b2 >>> 8);
+    }
+
+    // Handle remaining 1–3 pixels
+    let srcByte = alignedPixels * KittyPixelConstants.BYTES_PER_PIXEL_RGB;
+    let dstByte = alignedPixels * KittyPixelConstants.BYTES_PER_PIXEL_RGBA;
+    for (let i = alignedPixels; i < pixelCount; i++) {
+      data[dstByte]     = bytes[srcByte];
+      data[dstByte + 1] = bytes[srcByte + 1];
+      data[dstByte + 2] = bytes[srcByte + 2];
+      data[dstByte + 3] = KittyPixelConstants.ALPHA_OPAQUE;
+      srcByte += KittyPixelConstants.BYTES_PER_PIXEL_RGB;
+      dstByte += KittyPixelConstants.BYTES_PER_PIXEL_RGBA;
+    }
+
+    return createImageBitmap(new ImageData(data, width, height));
+  }
+
+  private async _decompressZlib(compressed: Uint8Array): Promise<Uint8Array> {
+    try {
+      return await this._decompress(compressed, 'deflate');
+    } catch {
+      return await this._decompress(compressed, 'deflate-raw');
+    }
+  }
+
+  private async _decompress(compressed: Uint8Array, format: 'deflate' | 'deflate-raw'): Promise<Uint8Array> {
+    const ds = new DecompressionStream(format);
+    const writer = ds.writable.getWriter();
+    writer.write(compressed as BufferSource);
+    writer.close();
+
+    const chunks: Uint8Array[] = [];
+    const reader = ds.readable.getReader();
+
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      chunks.push(value);
+    }
+
+    const totalLength = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
+    const result = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const chunk of chunks) {
+      result.set(chunk, offset);
+      offset += chunk.length;
+    }
+    return result;
+  }
+
+  public get images(): ReadonlyMap<number, IKittyImageData> {
+    return this._kittyStorage.images;
+  }
+
+  public get _kittyIdToStorageId(): ReadonlyMap<number, number> {
+    return this._kittyStorage.kittyIdToStorageId;
+  }
+
+  public get pendingTransmissions(): ReadonlyMap<number, IPendingTransmission> {
+    return this._pendingTransmissions;
+  }
+}

addons/addon-image/src/kitty/KittyGraphicsTypes.test.ts

@@ -0,0 +1,149 @@
+/**
+ * Copyright (c) 2026 The xterm.js authors. All rights reserved.
+ * @license MIT
+ */
+import { assert } from 'chai';
+import { parseKittyCommand, KittyAction, KittyFormat } from './KittyGraphicsTypes';
+
+describe('KittyGraphicsTypes', () => {
+  describe('parseKittyCommand', () => {
+    it('should parse control data with action and format', () => {
+      const cmd = parseKittyCommand('a=T,f=100');
+      assert.strictEqual(cmd.action, 'T');
+      assert.strictEqual(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.strictEqual(cmd.action, 't');
+      assert.strictEqual(cmd.format, 32);
+      assert.strictEqual(cmd.id, 5);
+      assert.strictEqual(cmd.width, 10);
+      assert.strictEqual(cmd.height, 20);
+      assert.strictEqual(cmd.columns, 3);
+      assert.strictEqual(cmd.rows, 2);
+      assert.strictEqual(cmd.more, 1);
+      assert.strictEqual(cmd.quiet, 2);
+    });
+
+    it('should handle empty control data', () => {
+      const cmd = parseKittyCommand('');
+      assert.strictEqual(cmd.action, undefined);
+      assert.strictEqual(cmd.format, undefined);
+    });
+
+    it('should parse transmit action', () => {
+      const cmd = parseKittyCommand('a=t,f=100');
+      assert.strictEqual(cmd.action, KittyAction.TRANSMIT);
+      assert.strictEqual(cmd.format, KittyFormat.PNG);
+    });
+
+    it('should parse delete action', () => {
+      const cmd = parseKittyCommand('a=d,i=5');
+      assert.strictEqual(cmd.action, KittyAction.DELETE);
+      assert.strictEqual(cmd.id, 5);
+    });
+
+    it('should parse empty action as empty string', () => {
+      const cmd = parseKittyCommand('a=,f=100');
+      assert.strictEqual(cmd.action, '');
+      assert.strictEqual(cmd.format, 100);
+    });
+
+    it('should leave action undefined when key is not present', () => {
+      const cmd = parseKittyCommand('f=100,i=5');
+      assert.strictEqual(cmd.action, undefined);
+      assert.strictEqual(cmd.format, 100);
+      assert.strictEqual(cmd.id, 5);
+    });
+
+    it('should parse compression key', () => {
+      const cmd = parseKittyCommand('a=t,f=32,o=z');
+      assert.strictEqual(cmd.action, 't');
+      assert.strictEqual(cmd.format, 32);
+      assert.strictEqual(cmd.compression, 'z');
+    });
+
+    it('should parse cursor movement key', () => {
+      const cmd = parseKittyCommand('a=T,f=100,C=1');
+      assert.strictEqual(cmd.cursorMovement, 1);
+    });
+
+    it('should parse cursor movement key C=0', () => {
+      const cmd = parseKittyCommand('a=T,f=100,C=0');
+      assert.strictEqual(cmd.cursorMovement, 0);
+    });
+
+    it('should parse x and y offset', () => {
+      const cmd = parseKittyCommand('a=T,x=10,y=20');
+      assert.strictEqual(cmd.x, 10);
+      assert.strictEqual(cmd.y, 20);
+    });
+
+    it('should handle keys without values', () => {
+      const cmd = parseKittyCommand('a=t,f=,i=5');
+      assert.strictEqual(cmd.action, 't');
+      assert.ok(isNaN(cmd.format!));
+      assert.strictEqual(cmd.id, 5);
+    });
+
+    it('should parse z-index key with positive value', () => {
+      const cmd = parseKittyCommand('a=T,f=100,z=10');
+      assert.strictEqual(cmd.zIndex, 10);
+    });
+
+    it('should parse z-index key with zero', () => {
+      const cmd = parseKittyCommand('a=T,f=100,z=0');
+      assert.strictEqual(cmd.zIndex, 0);
+    });
+
+    it('should parse z-index key with negative value', () => {
+      const cmd = parseKittyCommand('a=T,f=100,z=-1');
+      assert.strictEqual(cmd.zIndex, -1);
+    });
+
+    it('should leave zIndex undefined when not specified', () => {
+      const cmd = parseKittyCommand('a=T,f=100');
+      assert.strictEqual(cmd.zIndex, undefined);
+    });
+
+    it('should parse delete selector key', () => {
+      const cmd = parseKittyCommand('a=d,d=i,i=5');
+      assert.strictEqual(cmd.action, 'd');
+      assert.strictEqual(cmd.deleteSelector, 'i');
+      assert.strictEqual(cmd.id, 5);
+    });
+
+    it('should parse uppercase delete selector', () => {
+      const cmd = parseKittyCommand('a=d,d=A');
+      assert.strictEqual(cmd.deleteSelector, 'A');
+    });
+
+    it('should parse delete selector d=a (all)', () => {
+      const cmd = parseKittyCommand('a=d,d=a');
+      assert.strictEqual(cmd.deleteSelector, 'a');
+    });
+
+    it('should leave deleteSelector undefined when not specified', () => {
+      const cmd = parseKittyCommand('a=d,i=5');
+      assert.strictEqual(cmd.deleteSelector, undefined);
+    });
+
+    it('should parse placement id key', () => {
+      const cmd = parseKittyCommand('a=d,d=i,i=5,p=3');
+      assert.strictEqual(cmd.placementId, 3);
+      assert.strictEqual(cmd.deleteSelector, 'i');
+      assert.strictEqual(cmd.id, 5);
+    });
+
+    it('should leave placementId undefined when not specified', () => {
+      const cmd = parseKittyCommand('a=d,d=i,i=5');
+      assert.strictEqual(cmd.placementId, undefined);
+    });
+
+    it('should parse image number key', () => {
+      const cmd = parseKittyCommand('a=t,f=100,I=42');
+      assert.strictEqual(cmd.imageNumber, 42);
+    });
+  });
+});

addons/addon-image/src/kitty/KittyGraphicsTypes.ts

@@ -0,0 +1,195 @@
+/**
+ * Copyright (c) 2026 The xterm.js authors. All rights reserved.
+ * @license MIT
+ *
+ * Kitty graphics protocol types, constants, and parsing utilities.
+ */
+
+import type Base64Decoder from 'xterm-wasm-parts/lib/base64/Base64Decoder.wasm';
+
+// Kitty graphics protocol action types.
+// See: https://sw.kovidgoyal.net/kitty/graphics-protocol/#control-data-reference under key 'a'.
+export const enum KittyAction {
+  TRANSMIT = 't',
+  TRANSMIT_DISPLAY = 'T',
+  QUERY = 'q',
+  PLACEMENT = 'p',
+  DELETE = 'd'
+}
+
+// Kitty graphics protocol format types.
+// See: https://sw.kovidgoyal.net/kitty/graphics-protocol/#control-data-reference
+export const enum KittyFormat {
+  RGB = 24,
+  RGBA = 32,
+  PNG = 100
+}
+
+// Kitty graphics protocol compression types.
+// See: https://sw.kovidgoyal.net/kitty/graphics-protocol/#control-data-reference under key 'o'.
+export const enum KittyCompression {
+  NONE = '',
+  ZLIB = 'z'
+}
+
+// Kitty graphics protocol control data keys.
+// See: https://sw.kovidgoyal.net/kitty/graphics-protocol/#control-data-reference
+export const enum KittyKey {
+  // Action to perform (t=transmit, T=transmit+display, q=query, p=placement, d=delete)
+  ACTION = 'a',
+  // Image format (24=RGB, 32=RGBA, 100=PNG)
+  FORMAT = 'f',
+  // Image ID for referencing stored images
+  ID = 'i',
+  // Image number (alternative to ID, terminal assigns ID)
+  IMAGE_NUMBER = 'I',
+  // Source image width in pixels
+  WIDTH = 's',
+  // Source image height in pixels
+  HEIGHT = 'v',
+  // The left edge (in pixels) of the image area to display
+  X_OFFSET = 'x',
+  // The top edge (in pixels) of the image area to display
+  Y_OFFSET = 'y',
+  // Width (in pixels) of the source rectangle to display
+  SOURCE_WIDTH = 'w',
+  // Height (in pixels) of the source rectangle to display
+  SOURCE_HEIGHT = 'h',
+  // Horizontal offset (in pixels) within the first cell
+  X_PLACEMENT_OFFSET = 'X',
+  // Vertical offset (in pixels) within the first cell
+  Y_PLACEMENT_OFFSET = 'Y',
+  // Number of terminal columns to display the image over
+  COLUMNS = 'c',
+  // Number of terminal rows to display the image over
+  ROWS = 'r',
+  // More data flag (1=more chunks coming, 0=final chunk)
+  MORE = 'm',
+  // Compression type (z=zlib). This is essential for chunking larger images.
+  COMPRESSION = 'o',
+  // Quiet mode (1=suppress OK responses, 2=suppress error responses)
+  QUIET = 'q',
+  // Cursor movement policy (0=move cursor after image, 1=don't move cursor)
+  CURSOR_MOVEMENT = 'C',
+  // Z-index for image layering (negative = behind text, 0+ = on top)
+  Z_INDEX = 'z',
+  // Transmission medium (d=direct, f=file, t=temp file, s=shared memory)
+  TRANSMISSION = 't',
+  // Delete selector (a/A=all, i/I=by id, c/C=at cursor, etc.) — only used when a=d
+  DELETE_SELECTOR = 'd',
+  // Placement ID for targeting specific placements
+  PLACEMENT_ID = 'p'
+}
+
+// Pixel format constants
+export const enum KittyPixelConstants {
+  BYTES_PER_PIXEL_RGB = 3,
+  BYTES_PER_PIXEL_RGBA = 4,
+  ALPHA_OPAQUE = 255
+}
+
+// Parsed Kitty graphics command.
+export interface IKittyCommand {
+  action?: string;
+  format?: number;
+  id?: number;
+  imageNumber?: number;
+  width?: number;
+  height?: number;
+  x?: number;
+  y?: number;
+  sourceWidth?: number;
+  sourceHeight?: number;
+  xOffset?: number;
+  yOffset?: number;
+  columns?: number;
+  rows?: number;
+  more?: number;
+  quiet?: number;
+  cursorMovement?: number;
+  zIndex?: number;
+  transmission?: string;
+  deleteSelector?: string;
+  placementId?: number;
+  compression?: string;
+  payload?: string;
+}
+
+// Pending chunked transmission state.
+// Stores metadata from the first chunk while accumulating decoded payload data.
+export interface IPendingTransmission {
+  // The parsed command from the first chunk (contains action, format, dimensions, etc.)
+  cmd: IKittyCommand;
+  // Decoder used across chunked payloads
+  decoder: Base64Decoder;
+  // Total encoded (base64) bytes received across all chunks - for size limit enforcement
+  totalEncodedSize: number;
+  // Whether any chunk has failed to decode
+  decodeError: boolean;
+}
+
+// Stored Kitty image data.
+export interface IKittyImageData {
+  id: number;
+  // Decoded image data stored as Blob (off JS heap) to avoid 2GB heap limit
+  data: Blob;
+  width: number;
+  height: number;
+  format: 24 | 32 | 100;
+  compression?: string;
+}
+
+// Parses Kitty graphics control data into a command object.
+export function parseKittyCommand(data: string): IKittyCommand {
+  const cmd: IKittyCommand = {};
+  const parts = data.split(',');
+
+  for (const part of parts) {
+    const eqIdx = part.indexOf('=');
+    if (eqIdx === -1) continue;
+
+    const key = part.substring(0, eqIdx);
+    const value = part.substring(eqIdx + 1);
+
+    // Handle string keys first
+    if (key === KittyKey.ACTION) {
+      cmd.action = value;
+      continue;
+    }
+    if (key === KittyKey.COMPRESSION) {
+      cmd.compression = value;
+      continue;
+    }
+    if (key === KittyKey.TRANSMISSION) {
+      cmd.transmission = value;
+      continue;
+    }
+    if (key === KittyKey.DELETE_SELECTOR) {
+      cmd.deleteSelector = value;
+      continue;
+    }
+    const numValue = parseInt(value);
+    switch (key) {
+      case KittyKey.FORMAT: cmd.format = numValue; break;
+      case KittyKey.ID: cmd.id = numValue; break;
+      case KittyKey.IMAGE_NUMBER: cmd.imageNumber = numValue; break;
+      case KittyKey.WIDTH: cmd.width = numValue; break;
+      case KittyKey.HEIGHT: cmd.height = numValue; break;
+      case KittyKey.X_OFFSET: cmd.x = numValue; break;
+      case KittyKey.Y_OFFSET: cmd.y = numValue; break;
+      case KittyKey.SOURCE_WIDTH: cmd.sourceWidth = numValue; break;
+      case KittyKey.SOURCE_HEIGHT: cmd.sourceHeight = numValue; break;
+      case KittyKey.X_PLACEMENT_OFFSET: cmd.xOffset = numValue; break;
+      case KittyKey.Y_PLACEMENT_OFFSET: cmd.yOffset = numValue; break;
+      case KittyKey.COLUMNS: cmd.columns = numValue; break;
+      case KittyKey.ROWS: cmd.rows = numValue; break;
+      case KittyKey.MORE: cmd.more = numValue; break;
+      case KittyKey.QUIET: cmd.quiet = numValue; break;
+      case KittyKey.CURSOR_MOVEMENT: cmd.cursorMovement = numValue; break;
+      case KittyKey.Z_INDEX: cmd.zIndex = numValue; break;
+      case KittyKey.PLACEMENT_ID: cmd.placementId = numValue; break;
+    }
+  }
+
+  return cmd;
+}

addons/addon-image/src/kitty/KittyImageStorage.ts

@@ -0,0 +1,151 @@
+/**
+ * Copyright (c) 2026 The xterm.js authors. All rights reserved.
+ * @license MIT
+ */
+
+import { IDisposable } from '@xterm/xterm';
+import { ImageStorage } from '../ImageStorage';
+import { ImageLayer } from '../Types';
+import { IKittyImageData } from './KittyGraphicsTypes';
+
+// Kitty-specific image storage controller.
+//
+// Wraps shared ImageStorage with kitty protocol semantics:
+// - tracks transmitted image payloads by kitty image id
+// - tracks kitty image id -> shared ImageStorage id mapping for displayed images
+// - mirrors shared-storage evictions into kitty maps
+// - applies protocol-level undisplayed-image eviction policy
+export class KittyImageStorage implements IDisposable {
+  private static readonly _maxStoredImages = 256;
+
+  private _nextImageId = 1;
+  private readonly _images: Map<number, IKittyImageData> = new Map();
+  // TODO: Support multiple placements per image. The kitty spec identifies
+  // placements by an (image id, placement id) pair — same i + different p
+  // values should coexist, and same i + same p should replace the prior
+  // placement. Currently we track only one storage entry per kitty image id,
+  // so multiple placements of the same image overwrite each other. Fixing
+  // this requires changing these maps to Map<number, Map<number, number>>
+  // (kittyId → placementId → storageId) and updating addImage/deleteById
+  // accordingly. The underlying shared ImageStorage would also need to
+  // support multiple entries per logical image.
+  private readonly _kittyIdToStorageId: Map<number, number> = new Map();
+  private readonly _storageIdToKittyId: Map<number, number> = new Map();
+
+  private readonly _previousOnImageDeleted: ((storageId: number) => void) | undefined;
+  private readonly _wrappedOnImageDeleted: (storageId: number) => void;
+  private readonly _handleStorageImageDeleted = (storageId: number): void => {
+    const kittyId = this._storageIdToKittyId.get(storageId);
+    if (kittyId !== undefined) {
+      this._kittyIdToStorageId.delete(kittyId);
+      this._storageIdToKittyId.delete(storageId);
+      this._images.delete(kittyId);
+    }
+  };
+
+  constructor(
+    private readonly _storage: ImageStorage
+  ) {
+    this._previousOnImageDeleted = this._storage.onImageDeleted;
+    this._wrappedOnImageDeleted = (storageId: number) => {
+      this._previousOnImageDeleted?.(storageId);
+      this._handleStorageImageDeleted(storageId);
+    };
+    this._storage.onImageDeleted = this._wrappedOnImageDeleted;
+  }
+
+  public reset(): void {
+    this._nextImageId = 1;
+    this._images.clear();
+    this._kittyIdToStorageId.clear();
+    this._storageIdToKittyId.clear();
+  }
+
+  public dispose(): void {
+    this.reset();
+    if (this._storage.onImageDeleted === this._wrappedOnImageDeleted) {
+      this._storage.onImageDeleted = this._previousOnImageDeleted;
+    }
+  }
+
+  public storeImage(id: number | undefined, imageData: Omit<IKittyImageData, 'id'>): number {
+    const imageId = id ?? this._nextImageId++;
+
+    const oldStorageId = this._kittyIdToStorageId.get(imageId);
+    if (oldStorageId !== undefined) {
+      this._storage.deleteImage(oldStorageId);
+      this._kittyIdToStorageId.delete(imageId);
+      this._storageIdToKittyId.delete(oldStorageId);
+    }
+
+    if (!this._images.has(imageId) && this._images.size >= KittyImageStorage._maxStoredImages) {
+      this._evictUndisplayedImages();
+    }
+
+    this._images.set(imageId, {
+      ...imageData,
+      id: imageId
+    });
+    return imageId;
+  }
+
+  public addImage(kittyId: number, image: HTMLCanvasElement | ImageBitmap, scrolling: boolean, layer: ImageLayer, zIndex: number): void {
+    // Clean up stale reverse-mapping from a previous placement of the same
+    // kitty image.  The old shared-storage entry is kept (it may still be
+    // visible on screen) but its reverse mapping is removed so that eviction
+    // of the old entry won't incorrectly delete the kitty image data.
+    const oldStorageId = this._kittyIdToStorageId.get(kittyId);
+    if (oldStorageId !== undefined) {
+      this._storageIdToKittyId.delete(oldStorageId);
+    }
+    const storageId = this._storage.addImage(image, scrolling, layer, zIndex);
+    this._kittyIdToStorageId.set(kittyId, storageId);
+    this._storageIdToKittyId.set(storageId, kittyId);
+  }
+
+  public getImage(kittyId: number): IKittyImageData | undefined {
+    return this._images.get(kittyId);
+  }
+
+  public deleteById(kittyId: number): void {
+    this._images.delete(kittyId);
+    const storageId = this._kittyIdToStorageId.get(kittyId);
+    if (storageId !== undefined) {
+      this._storage.deleteImage(storageId);
+      this._kittyIdToStorageId.delete(kittyId);
+      this._storageIdToKittyId.delete(storageId);
+    }
+  }
+
+  public deleteAll(): void {
+    this._images.clear();
+    for (const storageId of this._kittyIdToStorageId.values()) {
+      this._storage.deleteImage(storageId);
+    }
+    this._kittyIdToStorageId.clear();
+    this._storageIdToKittyId.clear();
+  }
+
+  public get images(): ReadonlyMap<number, IKittyImageData> {
+    return this._images;
+  }
+
+  public get kittyIdToStorageId(): ReadonlyMap<number, number> {
+    return this._kittyIdToStorageId;
+  }
+
+  public get lastImageId(): number {
+    return this._nextImageId - 1;
+  }
+
+  private _evictUndisplayedImages(): void {
+    for (const [kittyId] of this._images) {
+      if (this._images.size <= KittyImageStorage._maxStoredImages / 2) {
+        break;
+      }
+      if (!this._kittyIdToStorageId.has(kittyId)) {
+        this._images.delete(kittyId);
+      }
+    }
+  }
+}

addons/addon-image/src/tsconfig.json

@@ -11,12 +11,11 @@
     "types": [
       "../../../node_modules/@types/mocha"
     ],
-    "baseUrl": ".",
     "paths": {
       "browser/*": [ "../../../src/browser/*" ],
       "common/*": [ "../../../src/common/*" ],
-      "vs/*": [ "../../../src/vs/*" ],
-      "@xterm/addon-image": [ "../typings/addon-image.d.ts" ]
+      "@xterm/addon-image": [ "../typings/addon-image.d.ts" ],
+      "*": [ "./*" ]
     }
   },
   "include": [
@@ -25,7 +24,6 @@
   ],
   "references": [
     { "path": "../../../src/browser" },
-    { "path": "../../../src/common" },
-    { "path": "../../../src/vs" }
+    { "path": "../../../src/common" }
   ]
 }

addons/addon-image/test/ImageAddon.test.ts

@@ -8,6 +8,7 @@ import { readFileSync } from 'fs';
 import { FINALIZER, introducer, sixelEncode } from 'sixel';
 import { ITestContext, createTestContext, openTerminal, pollFor, timeout } from '../../../test/playwright/TestUtils';
 import { deepStrictEqual, ok, strictEqual } from 'assert';
+import QoiEncoder from 'xterm-wasm-parts/lib/qoi/QoiEncoder.wasm';
 
 /**
  * Plugin ctor options.
@@ -23,6 +24,8 @@ export interface IImageAddonOptions {
   sixelSizeLimit: number;
   iipSupport: boolean;
   iipSizeLimit: number;
+  kittySupport: boolean;
+  kittySizeLimit: number;
 }
 
 // eslint-disable-next-line
@@ -72,6 +75,10 @@ const TESTDATA_IIP: [string, [number, number]][] = [
   [readFileSync('./addons/addon-image/fixture/iip/w3c_jpg.iip', { encoding: 'utf-8' }), [72, 48]],
   [readFileSync('./addons/addon-image/fixture/iip/w3c_png.iip', { encoding: 'utf-8' }), [72, 48]]
 ];
+const PALETTE_PNG_BASE64 = readFileSync('./addons/addon-image/fixture/palette.png').toString('base64');
+const qoiEnc = new QoiEncoder(1024*1024);
+const qoiData = qoiEnc.encode(TESTDATA.bytes, 640, 80);
+const PALETTE_QOI_BASE64 = Buffer.from(qoiData).toString('base64');
 
 let ctx: ITestContext;
 test.beforeAll(async ({ browser }) => {
@@ -83,11 +90,6 @@ test.afterAll(async () => await ctx.page.close());
 test.describe('ImageAddon', () => {
 
   test.beforeEach(async ({}, testInfo) => {
-    // DEBT: This test never worked on webkit
-    if (ctx.browser.browserType().name() === 'webkit') {
-      testInfo.skip();
-      return;
-    }
     await ctx.page.evaluate(`
       window.term.reset()
       window.imageAddon?.dispose();
@@ -130,11 +132,13 @@ test.describe('ImageAddon', () => {
         sixelSupport: true,
         sixelScrolling: true,
         sixelPaletteLimit: 512,  // set to 512 to get example image working
-        sixelSizeLimit: 25000000,
+        sixelSizeLimit: 33554432,
         storageLimit: 128,
         showPlaceholder: true,
         iipSupport: true,
-        iipSizeLimit: 20000000
+        iipSizeLimit: 33554432,
+        kittySupport: true,
+        kittySizeLimit: 33554432
       };
       deepStrictEqual(await ctx.page.evaluate(`window.imageAddon._opts`), DEFAULT_OPTIONS);
     });
@@ -149,7 +153,9 @@ test.describe('ImageAddon', () => {
         storageLimit: 10,
         showPlaceholder: false,
         iipSupport: false,
-        iipSizeLimit: 1000
+        iipSizeLimit: 1000,
+        kittySupport: false,
+        kittySizeLimit: 1000
       };
       await ctx.page.evaluate(opts => {
         (window as any).imageAddonCustom = new ImageAddon(opts.opts);
@@ -190,6 +196,18 @@ test.describe('ImageAddon', () => {
   });
 
   test.describe('image lifecycle & eviction', () => {
+    test('onImageAdded fires for each image', async () => {
+      await ctx.page.evaluate(`
+        window._imageAddedCount = 0;
+        window.imageAddon.onImageAdded(() => { window._imageAddedCount++; });
+      `);
+      await ctx.proxy.write(SIXEL_SEQ_0);
+      await pollFor(ctx.page, 'window._imageAddedCount', 1);
+      await ctx.proxy.write(SIXEL_SEQ_0);
+      await pollFor(ctx.page, 'window._imageAddedCount', 2);
+      await ctx.proxy.write(SIXEL_SEQ_0);
+      await pollFor(ctx.page, 'window._imageAddedCount', 3);
+    });
     test('delete image once scrolled off', async () => {
       await ctx.proxy.write(SIXEL_SEQ_0);
       pollFor(ctx.page, 'window.imageAddon._storage._images.size', 1);
@@ -294,6 +312,68 @@ test.describe('ImageAddon', () => {
       deepStrictEqual(await getOrigSize(1), TESTDATA_IIP[4][1]);
     });
   });
+
+  test.describe('IIP - QOI support', () => {
+    test('palette should yield same bytes from PNG and QOI', async () => {
+      await ctx.proxy.write(`\x1b]1337;File=inline=1;size=525:${PALETTE_PNG_BASE64}\x07`);
+      deepStrictEqual(await getOrigSize(1), [640, 80]);
+      await ctx.proxy.write(`\x1b[10H\x1b]1337;File=inline=1;size=${qoiData.length}:${PALETTE_QOI_BASE64}\x07`);
+      deepStrictEqual(await getOrigSize(2), [640, 80]);
+      const pngScrape = await getImageAtBufferCell(0, 0);
+      const qoiScrape = await getImageAtBufferCell(0, 11);
+      deepStrictEqual(qoiScrape, pngScrape);
+    });
+  });
+
+  test.describe('IIP - resizing', () => {
+    /**
+     * The correct resize behavior is wonky and needs to be tested against iTerm2,
+     * especially for missing params to derive correct default behavior.
+     * We document the current behavior here w'o claiming to be fully in line with iTerm2.
+     * ref: https://iterm2.com/documentation-images.html
+     * imgcat: https://iterm2.com/utilities/imgcat
+     *
+     * NOTE: QOI has a slightly different parse path, thus we test resizing explicitly
+     */
+    const images = [
+      ['palette.png', 525, PALETTE_PNG_BASE64],
+      ['palette.qoi', qoiData.length, PALETTE_QOI_BASE64]
+    ];
+    for (const [name, size, payload] of images) {
+      test(name + ': N --> width=20 height=5 preserveAspectRatio=0', async () => {
+        // cell based resize
+        const header = 'width=20;height=5;preserveAspectRatio=0';
+        await ctx.proxy.write(`\x1b]1337;File=inline=1;size=${size};${header}:${payload}\x07`);
+        const dim = await getDimensions();
+        deepStrictEqual(await getOrigSize(1), [dim.cellWidth * 20, dim.cellHeight * 5]);
+      });
+      test(name + ': Npx --> width=320px height=160px preserveAspectRatio=0', async () => {
+        // pixel based resize
+        const header = 'width=320px;height=160px;preserveAspectRatio=0';
+        await ctx.proxy.write(`\x1b]1337;File=inline=1;size=${size};${header}:${payload}\x07`);
+        deepStrictEqual(await getOrigSize(1), [320, 160]);
+      });
+      test(name + ': N% --> width=50% height=30% preserveAspectRatio=0', async () => {
+        // % of viewport resize
+        const header = 'width=50%;height=30%;preserveAspectRatio=0';
+        await ctx.proxy.write(`\x1b]1337;File=inline=1;size=${size};${header}:${payload}\x07`);
+        const dim = await getDimensions();
+        deepStrictEqual(await getOrigSize(1), [Math.floor(dim.width * 0.5), Math.floor(dim.height * 0.3)]);
+      });
+      test(name + ': ommitted dimension assumes preserveAspectRatio=1', async () => {
+        // width provided in percent
+        const header = 'width=50%';
+        await ctx.proxy.write(`\x1b]1337;File=inline=1;size=${size};${header}:${payload}\x07`);
+        const dim = await getDimensions();
+        const width = Math.floor(dim.width * 0.5);
+        deepStrictEqual(await getOrigSize(1), [width, Math.floor(width * 80 / 640)]);
+        // height provided in pixel
+        const header2 = 'height=200px';
+        await ctx.proxy.write(`\x1b]1337;File=inline=1;size=${size};${header2}:${payload}\x07`);
+        deepStrictEqual(await getOrigSize(2), [Math.floor(200 * 640 / 80), 200]);
+      });
+    }
+  });
 });
 
 /**
@@ -327,3 +407,7 @@ async function getOrigSize(id: number): Promise<[number, number]> {
     window.imageAddon._storage._images.get(${id}).orig.height
   ]`);
 }
+
+async function getImageAtBufferCell(x: number, y: number): Promise<string | undefined> {
+  return ctx.page.evaluate<any>(`window.imageAddon.getImageAtBufferCell(${x}, ${y})?.toDataURL('image/png')`);
+}

addons/addon-image/test/playwright.config.ts

@@ -5,10 +5,9 @@ const config: PlaywrightTestConfig = {
   timeout: 10000,
   projects: [
     {
-      name: 'ChromeStable',
+      name: 'Chromium',
       use: {
-        browserName: 'chromium',
-        channel: 'chrome'
+        browserName: 'chromium'
       }
     },
     {

addons/addon-image/test/tsconfig.json

@@ -9,13 +9,15 @@
     "outDir": "../out-test",
     "sourceMap": true,
     "removeComments": true,
-    "baseUrl": ".",
     "paths": {
       "common/*": [
         "../../../src/common/*"
       ],
       "browser/*": [
         "../../../src/browser/*"
+      ],
+      "*": [
+        "./*"
       ]
     },
     "strict": true,

addons/addon-image/typings/addon-image.d.ts

@@ -3,7 +3,7 @@
  * @license MIT
  */
 
-import { Terminal, ITerminalAddon } from '@xterm/xterm';
+import { Terminal, ITerminalAddon, IEvent } from '@xterm/xterm';
 
 declare module '@xterm/addon-image' {
   export interface IImageAddonOptions {
@@ -76,6 +76,15 @@ declare module '@xterm/addon-image' {
     iipSupport?: boolean;
     /** IIP sequence size limit (default 20000000 bytes). */
     iipSizeLimit?: number;
+
+    /**
+     * Kitty graphics protocol settings
+     */
+
+    /** Whether Kitty graphics protocol is enabled (default is true). */
+    kittySupport?: boolean;
+    /** Kitty image size limit in bytes (default 20000000 bytes). */
+    kittySizeLimit?: number;
   }
 
   export class ImageAddon implements ITerminalAddon {
@@ -107,6 +116,11 @@ declare module '@xterm/addon-image' {
      */
     public showPlaceholder: boolean;
 
+    /**
+     * Event fired whenever a new image is added to storage.
+     */
+    public readonly onImageAdded: IEvent<void>;
+
     /**
      * Get original image canvas at buffer position.
      */

addons/addon-ligatures/package.json

@@ -14,13 +14,13 @@
     "node": ">8.0.0"
   },
   "scripts": {
-    "build": "tsc -p src",
-    "watch": "tsc -w -p src",
+    "build": "tsgo -p src",
+    "watch": "tsgo -w -p src",
     "prepackage": "npm run build",
     "package": "webpack",
     "pretest": "npm run build",
     "test": "nyc mocha out/**/*.test.js",
-    "prepublish": "npm run package"
+    "prepublishOnly": "npm run package"
   },
   "keywords": [
     "font",
@@ -37,9 +37,9 @@
   "devDependencies": {
     "@types/lru-cache": "^5.1.0",
     "@types/opentype.js": "^0.7.0",
-    "axios": "^1.6.0",
+    "axios": "^1.15.2",
     "font-finder": "^1.1.0",
     "mkdirp": "0.5.5",
-    "yauzl": "^2.10.0"
+    "yauzl": "^3.2.1"
   }
 }

addons/addon-ligatures/src/LigaturesAddon.ts

@@ -13,7 +13,7 @@ export interface ITerminalAddon {
   dispose(): void;
 }
 
-export class LigaturesAddon implements ITerminalAddon , ILigaturesApi {
+export class LigaturesAddon implements ITerminalAddon, ILigaturesApi {
   private readonly _fallbackLigatures: string[];
   private readonly _fontFeatureSettings?: string;
 
@@ -22,7 +22,7 @@ export class LigaturesAddon implements ITerminalAddon , ILigaturesApi {
 
   constructor(options?: Partial<ILigatureOptions>) {
     // Source: calt set from https://github.com/be5invis/Iosevka?tab=readme-ov-file#ligations
-    this._fallbackLigatures = (options?.fallbackLigatures || [
+    this._fallbackLigatures = (options?.fallbackLigatures ?? [
       '<--', '<---', '<<-', '<-', '->', '->>', '-->', '--->',
       '<==', '<===', '<<=', '<=', '=>', '=>>', '==>', '===>', '>=', '>>=',
       '<->', '<-->', '<--->', '<---->', '<=>', '<==>', '<===>', '<====>', '::', ':::',

addons/addon-ligatures/src/font.ts

@@ -42,11 +42,11 @@ export default async function load(fontFamily: string, cacheSize: number): Promi
         if (status && status.state !== 'granted') {
           throw new Error('Permission to access local fonts not granted.');
         }
-      } catch (err: any) {
+      } catch (err: unknown) {
         // A `TypeError` indicates the 'local-fonts'
         // permission is not yet implemented, so
         // only `throw` if this is _not_ the problem.
-        if (err.name !== 'TypeError') {
+        if (err instanceof Error && err.name !== 'TypeError') {
           throw err;
         }
       }
@@ -60,8 +60,10 @@ export default async function load(fontFamily: string, cacheSize: number): Promi
           fonts[metadata.family].push(metadata);
         }
         fontsPromise = Promise.resolve(fonts);
-      } catch (err: any) {
-        console.error(err.name, err.message);
+      } catch (err: unknown) {
+        if (err instanceof Error) {
+          console.error(err.name, err.message);
+        }
       }
     }
     // Latest proposal https://bugs.chromium.org/p/chromium/issues/detail?id=1312603
@@ -76,13 +78,13 @@ export default async function load(fontFamily: string, cacheSize: number): Promi
           fonts[metadata.family].push(metadata);
         }
         fontsPromise = Promise.resolve(fonts);
-      } catch (err: any) {
-        console.error(err.name, err.message);
+      } catch (err: unknown) {
+        if (err instanceof Error) {
+          console.error(err.name, err.message);
+        }
       }
     }
-    if (!fontsPromise) {
-      fontsPromise = Promise.resolve({});
-    }
+    fontsPromise ??= Promise.resolve({});
   }
 
   const fonts = await fontsPromise;

addons/addon-ligatures/src/fontLigatures/processors/helper.ts

@@ -52,12 +52,10 @@ export function processLookaheadPosition(
     }
     processedEntries.add(currentEntry.entry);
 
-    if (!currentEntry.entry.forward) {
-      currentEntry.entry.forward = {
-        individual: {},
-        range: []
-      };
-    }
+    currentEntry.entry.forward ??= {
+      individual: {},
+      range: []
+    };
 
     // All glyphs at this position share ONE entry - lookahead just needs to match,
     // all paths lead to the same result
@@ -97,12 +95,10 @@ export function processBacktrackPosition(
     }
     processedEntries.add(currentEntry.entry);
 
-    if (!currentEntry.entry.reverse) {
-      currentEntry.entry.reverse = {
-        individual: {},
-        range: []
-      };
-    }
+    currentEntry.entry.reverse ??= {
+      individual: {},
+      range: []
+    };
 
     // All glyphs at this position share ONE entry - backtrack just needs to match,
     // all paths lead to the same result

addons/addon-ligatures/src/fontLigatures/processors/substitution.ts

@@ -54,9 +54,6 @@ export function getIndividualSubstitutionGlyph(table: SubstitutionTable, glyphId
       return (glyphId + table.deltaGlyphId) % (2 ** 16);
     // https://docs.microsoft.com/en-us/typography/opentype/spec/gsub#12-single-substitution-format-2
     case 2:
-      // eslint-disable-next-line eqeqeq
-      return table.substitute[coverageIndex] != null
-        ? table.substitute[coverageIndex]
-        : null;
+      return table.substitute[coverageIndex] ?? null;
   }
 }

addons/addon-ligatures/src/index.ts

@@ -30,7 +30,7 @@ export function enableLigatures(term: Terminal, fallbackLigatures: string[] = []
   let currentFontName: string | undefined = undefined;
   let font: Font | undefined = undefined;
   let loadingState: LoadingState = LoadingState.UNLOADED;
-  let loadError: any | undefined = undefined;
+  let loadError: unknown = undefined;
 
   return term.registerCharacterJoiner((text: string): [number, number][] => {
     // If the font hasn't been loaded yet, load it and return an empty result

addons/addon-ligatures/test/tsconfig.json

@@ -9,8 +9,12 @@
     "outDir": "../out-esbuild-test",
     "sourceMap": true,
     "removeComments": true,
-    "baseUrl": ".",
     "strict": true,
+    "paths": {
+      "*": [
+        "./*"
+      ]
+    },
     "types": [
       "../../../node_modules/@types/mocha",
       "../../../node_modules/@types/node"

addons/addon-progress/package.json

@@ -16,7 +16,7 @@
     "xterm.js"
   ],
   "scripts": {
-    "build": "../../node_modules/.bin/tsc -p .",
+    "build": "../../node_modules/.bin/tsgo -p .",
     "prepackage": "npm run build",
     "package": "../../node_modules/.bin/webpack",
     "prepublishOnly": "npm run package",

addons/addon-progress/src/ProgressAddon.ts

@@ -5,7 +5,7 @@
 
 import type { Terminal, ITerminalAddon, IDisposable } from '@xterm/xterm';
 import type { ProgressAddon as IProgressApi, IProgressState } from '@xterm/addon-progress';
-import type { Emitter, Event } from 'vs/base/common/event';
+import type { Emitter, IEvent } from 'common/Event';
 
 
 const enum ProgressType {
@@ -39,7 +39,7 @@ export class ProgressAddon implements ITerminalAddon, IProgressApi {
   private _pr = 0;
   // HACK: This uses ! to align with the API, this should be fixed when 5283 is resolved
   private _onChange!: Emitter<IProgressState>;
-  public onChange!: Event<IProgressState>;
+  public onChange!: IEvent<IProgressState>;
 
   public dispose(): void {
     this._seqHandler?.dispose();

addons/addon-progress/src/tsconfig.json

@@ -15,12 +15,12 @@
       "../../../node_modules/@types/mocha"
     ],
     "paths": {
+      "common/*": [
+        "../../../src/common/*"
+      ],
       "browser/*": [
         "../../../src/browser/*"
       ],
-      "vs/*": [
-        "../../../src/vs/*"
-      ],
       "@xterm/addon-progress": [
         "../typings/addon-progress.d.ts"
       ]
@@ -35,7 +35,7 @@
       "path": "../../../src/browser"
     },
     {
-      "path": "../../../src/vs"
+      "path": "../../../src/common"
     }
   ]
 }

addons/addon-progress/test/playwright.config.ts

@@ -5,10 +5,9 @@ const config: PlaywrightTestConfig = {
   timeout: 10000,
   projects: [
     {
-      name: 'ChromeStable',
+      name: 'Chromium',
       use: {
-        browserName: 'chromium',
-        channel: 'chrome'
+        browserName: 'chromium'
       }
     },
     {

addons/addon-progress/test/tsconfig.json

@@ -9,13 +9,15 @@
     "outDir": "../out-test",
     "sourceMap": true,
     "removeComments": true,
-    "baseUrl": ".",
     "paths": {
       "common/*": [
         "../../../src/common/*"
       ],
       "browser/*": [
         "../../../src/browser/*"
+      ],
+      "*": [
+        "./*"
       ]
     },
     "strict": true,

addons/addon-search/package.json

@@ -16,7 +16,7 @@
     "xterm.js"
   ],
   "scripts": {
-    "prepackage": "../../node_modules/.bin/tsc -p .",
+    "prepackage": "../../node_modules/.bin/tsgo -p .",
     "package": "../../node_modules/.bin/webpack",
     "prepublishOnly": "npm run package",
     "start": "node ../../demo/start"

addons/addon-search/src/DecorationManager.ts

@@ -5,7 +5,7 @@
 
 import type { Terminal, IDisposable, IDecoration } from '@xterm/xterm';
 import type { ISearchDecorationOptions } from '@xterm/addon-search';
-import { dispose, Disposable, toDisposable } from 'vs/base/common/lifecycle';
+import { dispose, Disposable, toDisposable } from 'common/Lifecycle';
 import type { ISearchResult } from './SearchEngine';
 
 /**
@@ -131,6 +131,9 @@ export class DecorationManager extends Disposable {
     const decorations: IDecoration[] = [];
     for (const range of decorationRanges) {
       const marker = this._terminal.registerMarker(range[0]);
+      if (!marker) {
+        continue;
+      }
       const decoration = this._terminal.registerDecoration({
         marker,
         x: range[1],

addons/addon-search/src/SearchAddon.ts

@@ -4,10 +4,10 @@
  */
 
 import type { Terminal, IDisposable, ITerminalAddon } from '@xterm/xterm';
-import type { SearchAddon as ISearchApi, ISearchOptions, ISearchAddonOptions, ISearchResultChangeEvent } from '@xterm/addon-search';
-import { Emitter, Event } from 'vs/base/common/event';
-import { Disposable, MutableDisposable, toDisposable } from 'vs/base/common/lifecycle';
-import { disposableTimeout } from 'vs/base/common/async';
+import type { SearchAddon as ISearchApi, ISearchOptions, ISearchAddonOptions, ISearchResultChangeEvent, ISearchDecorationOptions } from '@xterm/addon-search';
+import { Emitter, type IEvent } from 'common/Event';
+import { Disposable, MutableDisposable, toDisposable } from 'common/Lifecycle';
+import { disposableTimeout } from 'common/Async';
 import { SearchLineCache } from './SearchLineCache';
 import { SearchState } from './SearchState';
 import { SearchEngine, type ISearchResult } from './SearchEngine';
@@ -47,7 +47,7 @@ export class SearchAddon extends Disposable implements ITerminalAddon, ISearchAp
   private readonly _onBeforeSearch = this._register(new Emitter<void>());
   public readonly onBeforeSearch = this._onBeforeSearch.event;
 
-  public get onDidChangeResults(): Event<ISearchResultChangeEvent> {
+  public get onDidChangeResults(): IEvent<ISearchResultChangeEvent> {
     return this._resultTracker.onDidChangeResults;
   }
 
@@ -222,7 +222,7 @@ export class SearchAddon extends Disposable implements ITerminalAddon, ISearchAp
    * @param result The result to select.
    * @returns Whether a result was selected.
    */
-  private _selectResult(result: ISearchResult | undefined, options?: any, noScroll?: boolean): boolean {
+  private _selectResult(result: ISearchResult | undefined, options?: ISearchDecorationOptions, noScroll?: boolean): boolean {
     if (!this._terminal || !this._decorationManager) {
       return false;
     }

addons/addon-search/src/SearchEngine.test.ts

@@ -7,7 +7,7 @@ import { SearchEngine } from './SearchEngine';
 import { SearchLineCache } from './SearchLineCache';
 import { Terminal } from 'browser/public/Terminal';
 import type { ISearchOptions } from '@xterm/addon-search';
-import { DisposableStore } from 'vs/base/common/lifecycle';
+import { DisposableStore } from 'common/Lifecycle';
 
 function writeP(terminal: Terminal, data: string): Promise<void> {
   return new Promise(r => terminal.write(data, r));

addons/addon-search/src/SearchEngine.ts

@@ -198,9 +198,7 @@ export class SearchEngine {
       }
     }
 
-    if (!result) {
-      result = this._findInLine(term, searchPosition, searchOptions, isReverseSearch);
-    }
+    result ??= this._findInLine(term, searchPosition, searchOptions, isReverseSearch);
 
     // Search from startRow - 1 to top
     if (!result) {

addons/addon-search/src/SearchLineCache.test.ts

@@ -5,7 +5,7 @@
 import { assert } from 'chai';
 import { SearchLineCache, LineCacheEntry } from './SearchLineCache';
 import { Terminal } from 'browser/public/Terminal';
-import { timeout } from 'vs/base/common/async';
+import { timeout } from 'common/Async';
 
 function writeP(terminal: Terminal, data: string): Promise<void> {
   return new Promise(r => terminal.write(data, r));

addons/addon-search/src/SearchLineCache.ts

@@ -4,8 +4,8 @@
  */
 
 import type { Terminal } from '@xterm/xterm';
-import { combinedDisposable, Disposable, MutableDisposable, toDisposable } from 'vs/base/common/lifecycle';
-import { disposableTimeout } from 'vs/base/common/async';
+import { combinedDisposable, Disposable, MutableDisposable, toDisposable } from 'common/Lifecycle';
+import { disposableTimeout } from 'common/Async';
 
 export type LineCacheEntry = [
   /**

addons/addon-search/src/SearchResultTracker.ts

@@ -5,8 +5,8 @@
 
 import type { ISearchResultChangeEvent } from '@xterm/addon-search';
 import type { IDisposable } from '@xterm/xterm';
-import { Emitter, Event } from 'vs/base/common/event';
-import { Disposable } from 'vs/base/common/lifecycle';
+import { Emitter, type IEvent } from 'common/Event';
+import { Disposable } from 'common/Lifecycle';
 import type { ISearchResult } from './SearchEngine';
 
 /**
@@ -25,7 +25,7 @@ export class SearchResultTracker extends Disposable {
   private _selectedDecoration: ISelectedDecoration | undefined;
 
   private readonly _onDidChangeResults = this._register(new Emitter<ISearchResultChangeEvent>());
-  public get onDidChangeResults(): Event<ISearchResultChangeEvent> { return this._onDidChangeResults.event; }
+  public get onDidChangeResults(): IEvent<ISearchResultChangeEvent> { return this._onDidChangeResults.event; }
 
   /**
    * Gets the current search results.

addons/addon-search/src/tsconfig.json

@@ -21,9 +21,6 @@
       "browser/*": [
         "../../../src/browser/*"
       ],
-      "vs/*": [
-        "../../../src/vs/*"
-      ],
       "@xterm/addon-search" : [
         "../typings/addon-search.d.ts"
       ]
@@ -39,9 +36,6 @@
     },
     {
       "path": "../../../src/browser"
-    },
-    {
-      "path": "../../../src/vs"
     }
   ]
 }

addons/addon-search/test/playwright.config.ts

@@ -5,10 +5,9 @@ const config: PlaywrightTestConfig = {
   timeout: 10000,
   projects: [
     {
-      name: 'ChromeStable',
+      name: 'Chromium',
       use: {
-        browserName: 'chromium',
-        channel: 'chrome'
+        browserName: 'chromium'
       }
     },
     {

addons/addon-search/test/tsconfig.json

@@ -9,13 +9,15 @@
     "outDir": "../out-test",
     "sourceMap": true,
     "removeComments": true,
-    "baseUrl": ".",
     "paths": {
       "common/*": [
         "../../../src/common/*"
       ],
       "browser/*": [
         "../../../src/browser/*"
+      ],
+      "*": [
+        "./*"
       ]
     },
     "strict": true,

addons/addon-serialize/benchmark/tsconfig.json

@@ -4,13 +4,13 @@
       "dom",
       "es2021"
     ],
+    "rootDir": "..",
     "outDir": "../out-benchmark",
     "types": ["../../../node_modules/@types/node"],
     "moduleResolution": "node",
     "strict": false,
     "target": "es2021",
     "module": "commonjs",
-    "baseUrl": ".",
     "paths": {
       "common/*": ["../../../src/common/*"],
       "browser/*": ["../../../src/browser/*"],

addons/addon-serialize/package.json

@@ -16,7 +16,7 @@
     "xterm.js"
   ],
   "scripts": {
-    "build": "../../node_modules/.bin/tsc -p .",
+    "build": "../../node_modules/.bin/tsgo -p .",
     "prepackage": "npm run build",
     "package": "../../node_modules/.bin/webpack",
     "prepublishOnly": "npm run package",

addons/addon-serialize/src/SerializeAddon.test.ts

@@ -116,7 +116,7 @@ describe('SerializeAddon', () => {
     describe('underline styles', () => {
       it('should serialize single underline with style', async () => {
         await writeP(terminal, sgr('4:1') + 'test' + sgr('24'));
-        assert.equal(serializeAddon.serialize(), '\u001b[4:1mtest\u001b[0m');
+        assert.equal(serializeAddon.serialize(), '\u001b[4mtest\u001b[0m');
       });
 
       it('should serialize double underline', async () => {
@@ -228,7 +228,7 @@ describe('SerializeAddon', () => {
     it('empty terminal with selection turned off', () => {
       const output = serializeAddon.serializeAsHTML();
       assert.notEqual(output, '');
-      assert.equal((output.match(/<div><span> {10}<\/span><\/div>/g) || []).length, 2);
+      assert.equal((output.match(/<div><span> {10}<\/span><\/div>/g) ?? []).length, 2);
     });
 
     it('empty terminal with no selection', () => {
@@ -245,7 +245,7 @@ describe('SerializeAddon', () => {
       const output = serializeAddon.serializeAsHTML({
         onlySelection: true
       });
-      assert.equal((output.match(/<div><span>terminal<\/span><\/div>/g) || []).length, 1, output);
+      assert.equal((output.match(/<div><span>terminal<\/span><\/div>/g) ?? []).length, 1, output);
     });
 
     it('basic terminal with html unsafe chars', async () => {
@@ -255,7 +255,7 @@ describe('SerializeAddon', () => {
       const output = serializeAddon.serializeAsHTML({
         onlySelection: true
       });
-      assert.equal((output.match(/<div><span>&lt;a>&amp;pi;<\/span><\/div>/g) || []).length, 1, output);
+      assert.equal((output.match(/<div><span>&lt;a>&amp;pi;<\/span><\/div>/g) ?? []).length, 1, output);
     });
 
     it('serializes rows within a provided range', async () => {
@@ -267,7 +267,7 @@ describe('SerializeAddon', () => {
           startCol: 4
         }
       });
-      const rowMatches = output.match(/<div><span>.*?<\/span><\/div>/g) || [];
+      const rowMatches = output.match(/<div><span>.*?<\/span><\/div>/g) ?? [];
       assert.equal(rowMatches.length, 1, output);
       assert.ok(rowMatches[0]?.includes('hello'));
       assert.ok(!output.includes('bye'));
@@ -278,56 +278,56 @@ describe('SerializeAddon', () => {
       await writeP(terminal, ' ' + sgr('1') + 'terminal' + sgr('22') + ' ');
 
       const output = serializeAddon.serializeAsHTML();
-      assert.equal((output.match(/<span style='font-weight: bold;'>terminal<\/span>/g) || []).length, 1, output);
+      assert.equal((output.match(/<span style='font-weight: bold;'>terminal<\/span>/g) ?? []).length, 1, output);
     });
 
     it('cells with italic styling', async () => {
       await writeP(terminal, ' ' + sgr('3') + 'terminal' + sgr('23') + ' ');
 
       const output = serializeAddon.serializeAsHTML();
-      assert.equal((output.match(/<span style='font-style: italic;'>terminal<\/span>/g) || []).length, 1, output);
+      assert.equal((output.match(/<span style='font-style: italic;'>terminal<\/span>/g) ?? []).length, 1, output);
     });
 
     it('cells with inverse styling', async () => {
       await writeP(terminal, ' ' + sgr('7') + 'terminal' + sgr('27') + ' ');
 
       const output = serializeAddon.serializeAsHTML();
-      assert.equal((output.match(/<span style='color: #000000; background-color: #BFBFBF;'>terminal<\/span>/g) || []).length, 1, output);
+      assert.equal((output.match(/<span style='color: #000000; background-color: #BFBFBF;'>terminal<\/span>/g) ?? []).length, 1, output);
     });
 
     it('cells with underline styling', async () => {
       await writeP(terminal, ' ' + sgr('4') + 'terminal' + sgr('24') + ' ');
 
       const output = serializeAddon.serializeAsHTML();
-      assert.equal((output.match(/<span style='text-decoration: underline;'>terminal<\/span>/g) || []).length, 1, output);
+      assert.equal((output.match(/<span style='text-decoration: underline;'>terminal<\/span>/g) ?? []).length, 1, output);
     });
 
     it('cells with double underline styling', async () => {
       await writeP(terminal, ' ' + sgr('4:2') + 'terminal' + sgr('24') + ' ');
 
       const output = serializeAddon.serializeAsHTML();
-      assert.equal((output.match(/<span style='text-decoration: underline double;'>terminal<\/span>/g) || []).length, 1, output);
+      assert.equal((output.match(/<span style='text-decoration: underline double;'>terminal<\/span>/g) ?? []).length, 1, output);
     });
 
     it('cells with curly underline styling', async () => {
       await writeP(terminal, ' ' + sgr('4:3') + 'terminal' + sgr('24') + ' ');
 
       const output = serializeAddon.serializeAsHTML();
-      assert.equal((output.match(/<span style='text-decoration: underline wavy;'>terminal<\/span>/g) || []).length, 1, output);
+      assert.equal((output.match(/<span style='text-decoration: underline wavy;'>terminal<\/span>/g) ?? []).length, 1, output);
     });
 
     it('cells with dotted underline styling', async () => {
       await writeP(terminal, ' ' + sgr('4:4') + 'terminal' + sgr('24') + ' ');
 
       const output = serializeAddon.serializeAsHTML();
-      assert.equal((output.match(/<span style='text-decoration: underline dotted;'>terminal<\/span>/g) || []).length, 1, output);
+      assert.equal((output.match(/<span style='text-decoration: underline dotted;'>terminal<\/span>/g) ?? []).length, 1, output);
     });
 
     it('cells with dashed underline styling', async () => {
       await writeP(terminal, ' ' + sgr('4:5') + 'terminal' + sgr('24') + ' ');
 
       const output = serializeAddon.serializeAsHTML();
-      assert.equal((output.match(/<span style='text-decoration: underline dashed;'>terminal<\/span>/g) || []).length, 1, output);
+      assert.equal((output.match(/<span style='text-decoration: underline dashed;'>terminal<\/span>/g) ?? []).length, 1, output);
     });
 
     it('cells with underline color (palette)', async () => {
@@ -350,49 +350,49 @@ describe('SerializeAddon', () => {
       await writeP(terminal, ' ' + sgr('8') + 'terminal' + sgr('28') + ' ');
 
       const output = serializeAddon.serializeAsHTML();
-      assert.equal((output.match(/<span style='visibility: hidden;'>terminal<\/span>/g) || []).length, 1, output);
+      assert.equal((output.match(/<span style='visibility: hidden;'>terminal<\/span>/g) ?? []).length, 1, output);
     });
 
     it('cells with dim styling', async () => {
       await writeP(terminal, ' ' + sgr('2') + 'terminal' + sgr('22') + ' ');
 
       const output = serializeAddon.serializeAsHTML();
-      assert.equal((output.match(/<span style='opacity: 0.5;'>terminal<\/span>/g) || []).length, 1, output);
+      assert.equal((output.match(/<span style='opacity: 0.5;'>terminal<\/span>/g) ?? []).length, 1, output);
     });
 
     it('cells with strikethrough styling', async () => {
       await writeP(terminal, ' ' + sgr('9') + 'terminal' + sgr('29') + ' ');
 
       const output = serializeAddon.serializeAsHTML();
-      assert.equal((output.match(/<span style='text-decoration: line-through;'>terminal<\/span>/g) || []).length, 1, output);
+      assert.equal((output.match(/<span style='text-decoration: line-through;'>terminal<\/span>/g) ?? []).length, 1, output);
     });
 
     it('cells with combined styling', async () => {
       await writeP(terminal, sgr('1') + ' ' + sgr('9') + 'termi' + sgr('22') + 'nal' + sgr('29') + ' ');
 
       const output = serializeAddon.serializeAsHTML();
-      assert.equal((output.match(/<span style='font-weight: bold;'> <\/span>/g) || []).length, 1, output);
-      assert.equal((output.match(/<span style='font-weight: bold; text-decoration: line-through;'>termi<\/span>/g) || []).length, 1, output);
-      assert.equal((output.match(/<span style='text-decoration: line-through;'>nal<\/span>/g) || []).length, 1, output);
+      assert.equal((output.match(/<span style='font-weight: bold;'> <\/span>/g) ?? []).length, 1, output);
+      assert.equal((output.match(/<span style='font-weight: bold; text-decoration: line-through;'>termi<\/span>/g) ?? []).length, 1, output);
+      assert.equal((output.match(/<span style='text-decoration: line-through;'>nal<\/span>/g) ?? []).length, 1, output);
     });
 
     it('cells with color styling', async () => {
       await writeP(terminal, ' ' + sgr('38;5;46') + 'terminal' + sgr('39') + ' ');
 
       const output = serializeAddon.serializeAsHTML();
-      assert.equal((output.match(/<span style='color: #00ff00;'>terminal<\/span>/g) || []).length, 1, output);
+      assert.equal((output.match(/<span style='color: #00ff00;'>terminal<\/span>/g) ?? []).length, 1, output);
     });
 
     it('cells with background styling', async () => {
       await writeP(terminal, ' ' + sgr('48;5;46') + 'terminal' + sgr('49') + ' ');
 
       const output = serializeAddon.serializeAsHTML();
-      assert.equal((output.match(/<span style='background-color: #00ff00;'>terminal<\/span>/g) || []).length, 1, output);
+      assert.equal((output.match(/<span style='background-color: #00ff00;'>terminal<\/span>/g) ?? []).length, 1, output);
     });
 
     it('empty terminal with default options', async () => {
       const output = serializeAddon.serializeAsHTML();
-      assert.equal((output.match(/color: #000000; background-color: #ffffff; font-family: monospace; font-size: 15px;/g) || []).length, 1, output);
+      assert.equal((output.match(/color: #000000; background-color: #ffffff; font-family: monospace; font-size: 15px;/g) ?? []).length, 1, output);
     });
 
     it('empty terminal with custom options', async () => {
@@ -405,14 +405,14 @@ describe('SerializeAddon', () => {
       const output = serializeAddon.serializeAsHTML({
         includeGlobalBackground: true
       });
-      assert.equal((output.match(/color: #ff00ff; background-color: #00ff00; font-family: verdana; font-size: 20px;/g) || []).length, 1, output);
+      assert.equal((output.match(/color: #ff00ff; background-color: #00ff00; font-family: verdana; font-size: 20px;/g) ?? []).length, 1, output);
     });
 
     it('empty terminal with background included', async () => {
       const output = serializeAddon.serializeAsHTML({
         includeGlobalBackground: true
       });
-      assert.equal((output.match(/color: #ffffff; background-color: #000000; font-family: monospace; font-size: 15px;/g) || []).length, 1, output);
+      assert.equal((output.match(/color: #ffffff; background-color: #000000; font-family: monospace; font-size: 15px;/g) ?? []).length, 1, output);
     });
 
     it('cells with custom color styling', async () => {
@@ -422,7 +422,7 @@ describe('SerializeAddon', () => {
       await writeP(terminal, ' ' + sgr('38;5;0') + 'terminal' + sgr('39') + ' ');
 
       const output = serializeAddon.serializeAsHTML();
-      assert.equal((output.match(/<span style='color: #ffa500;'>terminal<\/span>/g) || []).length, 1, output);
+      assert.equal((output.match(/<span style='color: #ffa500;'>terminal<\/span>/g) ?? []).length, 1, output);
     });
 
     it('cells with color styling - xterm headless', async () => {
@@ -432,7 +432,7 @@ describe('SerializeAddon', () => {
       await writeP(terminal, ' ' + sgr('38;5;46') + 'terminal' + sgr('39') + ' ');
 
       const output = serializeAddon.serializeAsHTML();
-      assert.equal((output.match(/<span style='color: #00ff00;'>terminal<\/span>/g) || []).length, 1, output);
+      assert.equal((output.match(/<span style='color: #00ff00;'>terminal<\/span>/g) ?? []).length, 1, output);
     });
   });
 });

addons/addon-serialize/src/SerializeAddon.ts

@@ -89,11 +89,19 @@ function equalUnderline(cell1: IBufferCell | IAttributeData, cell2: IBufferCell)
   if (!cell1.isUnderline() && !cell2.isUnderline()) {
     return true;
   }
-  const cell1Data = cell1 as unknown as IAttributeData;
-  const cell2Data = cell2 as unknown as IAttributeData;
-  return cell1Data.getUnderlineStyle() === cell2Data.getUnderlineStyle()
-    && cell1Data.getUnderlineColor() === cell2Data.getUnderlineColor()
-    && cell1Data.getUnderlineColorMode() === cell2Data.getUnderlineColorMode();
+  if (cell1.getUnderlineStyle() !== cell2.getUnderlineStyle()) {
+    return false;
+  }
+  const cell1Default = cell1.isUnderlineColorDefault();
+  const cell2Default = cell2.isUnderlineColorDefault();
+  if (cell1Default && cell2Default) {
+    return true;
+  }
+  if (cell1Default !== cell2Default) {
+    return false;
+  }
+  return cell1.getUnderlineColor() === cell2.getUnderlineColor()
+    && cell1.getUnderlineColorMode() === cell2.getUnderlineColorMode();
 }
 
 function equalFlags(cell1: IBufferCell | IAttributeData, cell2: IBufferCell): boolean {
@@ -109,6 +117,16 @@ function equalFlags(cell1: IBufferCell | IAttributeData, cell2: IBufferCell): bo
     && cell1.isStrikethrough() === cell2.isStrikethrough();
 }
 
+function attributesEquals(cell1: IBufferCell | IAttributeData, cell2: IBufferCell): boolean {
+  const cell1AsBufferCell = cell1 as IBufferCell;
+  if (typeof cell1AsBufferCell.attributesEquals === 'function') {
+    return cell1AsBufferCell.attributesEquals(cell2);
+  }
+  return equalFg(cell1, cell2)
+    && equalBg(cell1, cell2)
+    && equalFlags(cell1, cell2);
+}
+
 class StringSerializeHandler extends BaseSerializeHandler {
   private _rowIndex: number = 0;
   private _allRows: string[] = new Array<string>();
@@ -258,6 +276,9 @@ class StringSerializeHandler extends BaseSerializeHandler {
 
   private _diffStyle(cell: IBufferCell | IAttributeData, oldCell: IBufferCell): number[] {
     const sgrSeq: number[] = [];
+    if (attributesEquals(cell, oldCell)) {
+      return sgrSeq;
+    }
     const fgChanged = !equalFg(cell, oldCell);
     const bgChanged = !equalBg(cell, oldCell);
     const flagsChanged = !equalFlags(cell, oldCell);
@@ -290,17 +311,18 @@ class StringSerializeHandler extends BaseSerializeHandler {
           if (cell.isInverse() !== oldCell.isInverse()) { sgrSeq.push(cell.isInverse() ? 7 : 27); }
           if (cell.isBold() !== oldCell.isBold()) { sgrSeq.push(cell.isBold() ? 1 : 22); }
           if (!equalUnderline(cell, oldCell)) {
-            const cellData = cell as unknown as IAttributeData;
-            const style = cellData.getUnderlineStyle();
+            const style = cell.getUnderlineStyle();
             if (style === UnderlineStyle.NONE) {
               sgrSeq.push(24);
+            } else if (style === UnderlineStyle.SINGLE && cell.isUnderlineColorDefault()) {
+              sgrSeq.push(4);
             } else {
               // Use SGR 4:X format for underline styles
               sgrSeq.push('4:' + style as unknown as number);
               // Handle underline color
-              if (!cellData.isUnderlineColorDefault()) {
-                const color = cellData.getUnderlineColor();
-                if (cellData.isUnderlineColorRGB()) {
+              if (!cell.isUnderlineColorDefault()) {
+                const color = cell.getUnderlineColor();
+                if (cell.isUnderlineColorRGB()) {
                   sgrSeq.push('58:2::' + ((color >>> 16) & 0xFF) + ':' + ((color >>> 8) & 0xFF) + ':' + (color & 0xFF) as unknown as number);
                 } else {
                   sgrSeq.push('58:5:' + color as unknown as number);
@@ -457,7 +479,7 @@ class StringSerializeHandler extends BaseSerializeHandler {
   }
 }
 
-export class SerializeAddon implements ITerminalAddon , ISerializeApi {
+export class SerializeAddon implements ITerminalAddon, ISerializeApi {
   private _terminal: Terminal | undefined;
 
   public activate(terminal: Terminal): void {
@@ -601,7 +623,7 @@ export class SerializeAddon implements ITerminalAddon , ISerializeApi {
       throw new Error('Cannot use addon until it has been loaded');
     }
 
-    return this._serializeBufferAsHTML(this._terminal, options || {});
+    return this._serializeBufferAsHTML(this._terminal, options ?? {});
   }
 
   public dispose(): void { }
@@ -630,20 +652,6 @@ export class HTMLSerializeHandler extends BaseSerializeHandler {
     }
   }
 
-  private _padStart(target: string, targetLength: number, padString: string): string {
-    targetLength = targetLength >> 0;
-    padString = padString ?? ' ';
-    if (target.length > targetLength) {
-      return target;
-    }
-
-    targetLength -= target.length;
-    if (targetLength > padString.length) {
-      padString += padString.repeat(targetLength / padString.length);
-    }
-    return padString.slice(0, targetLength) + target;
-  }
-
   protected _beforeSerialize(rows: number, start: number, end: number): void {
     this._htmlContent += '<html><body><!--StartFragment--><pre>';
 
@@ -680,7 +688,7 @@ export class HTMLSerializeHandler extends BaseSerializeHandler {
         (color >>  8) & 255,
         (color      ) & 255
       ];
-      return '#' + rgb.map(x => this._padStart(x.toString(16), 2, '0')).join('');
+      return '#' + rgb.map(x => x.toString(16).padStart(2, '0')).join('');
     }
     if (isFg ? cell.isFgPalette() : cell.isBgPalette()) {
       return this._ansiColors[color].css;
@@ -689,26 +697,24 @@ export class HTMLSerializeHandler extends BaseSerializeHandler {
   }
 
   private _getUnderlineColor(cell: IBufferCell): string | undefined {
-    const cellData = cell as unknown as IAttributeData;
-    if (cellData.isUnderlineColorDefault()) {
+    if (cell.isUnderlineColorDefault()) {
       return undefined;
     }
-    const color = cellData.getUnderlineColor();
-    if (cellData.isUnderlineColorRGB()) {
+    const color = cell.getUnderlineColor();
+    if (cell.isUnderlineColorRGB()) {
       const rgb = [
         (color >> 16) & 255,
         (color >>  8) & 255,
         (color      ) & 255
       ];
-      return '#' + rgb.map(x => this._padStart(x.toString(16), 2, '0')).join('');
+      return '#' + rgb.map(x => x.toString(16).padStart(2, '0')).join('');
     }
     // Palette color
     return this._ansiColors[color].css;
   }
 
   private _getUnderlineStyle(cell: IBufferCell): string {
-    const cellData = cell as unknown as IAttributeData;
-    switch (cellData.getUnderlineStyle()) {
+    switch (cell.getUnderlineStyle()) {
       case UnderlineStyle.SINGLE:
         return 'underline';
       case UnderlineStyle.DOUBLE:
@@ -727,6 +733,10 @@ export class HTMLSerializeHandler extends BaseSerializeHandler {
   private _diffStyle(cell: IBufferCell, oldCell: IBufferCell): string[] | undefined {
     const content: string[] = [];
 
+    if (attributesEquals(cell, oldCell)) {
+      return undefined;
+    }
+
     const fgChanged = !equalFg(cell, oldCell);
     const bgChanged = !equalBg(cell, oldCell);
     const flagsChanged = !equalFlags(cell, oldCell);

addons/addon-serialize/src/tsconfig.json

@@ -10,7 +10,6 @@
     "outDir": "../out",
     "sourceMap": true,
     "removeComments": true,
-    "baseUrl": ".",
     "paths": {
       "common/*": [
         "../../../src/common/*"
@@ -23,6 +22,7 @@
       ]
     },
     "strict": true,
+    "skipLibCheck": true,
     "types": [
       "../../../node_modules/@types/mocha"
     ]

addons/addon-serialize/test/SerializeAddon.test.ts

@@ -49,7 +49,14 @@ test.describe('SerializeAddon', () => {
         for (let i = 0; i < buffer.length; i++) {
           // Do this intentionally to get content of underlining source
           const bufferLine = buffer.getLine(i)._line;
-          lines.push(JSON.stringify(bufferLine));
+          lines.push(JSON.stringify(bufferLine, (key, value) => {
+            // BufferLine caches are internal/transient and can legitimately differ
+            // across equivalent terminal states.
+            if (key === '_stringCache' || key === '_stringCacheEntryRef') {
+              return undefined;
+            }
+            return value;
+          }));
         }
         return {
           x: buffer.cursorX,
@@ -203,6 +210,46 @@ test.describe('SerializeAddon', () => {
     strictEqual(await ctx.page.evaluate(`window.serialize.serialize();`), lines.join('\r\n'));
   });
 
+  test('buffer cell attributesEquals compares underline style and color', async () => {
+    await ctx.proxy.write(`${sgr(UNDERLINE_DOUBLE, UNDERLINE_COLOR_RED)}A${sgr(UNDERLINE_DOUBLE, UNDERLINE_COLOR_RED)}B${sgr(NORMAL)}`);
+    const sameAttributes = await ctx.page.evaluate(`(() => {
+      const line = window.term.buffer.active.getLine(0);
+      const cellA = line?.getCell(0);
+      const cellB = line?.getCell(1);
+      if (!cellA || !cellB) {
+        return undefined;
+      }
+      return cellA.attributesEquals(cellB);
+    })()`);
+    strictEqual(sameAttributes, true);
+
+    await ctx.page.evaluate(`window.term.reset()`);
+    await ctx.proxy.write(`${sgr(UNDERLINE_DOUBLE, UNDERLINE_COLOR_RED)}A${sgr(UNDERLINE_DOUBLE, UNDERLINE_COLOR_GREEN)}B${sgr(NORMAL)}`);
+    const differentColor = await ctx.page.evaluate(`(() => {
+      const line = window.term.buffer.active.getLine(0);
+      const cellA = line?.getCell(0);
+      const cellB = line?.getCell(1);
+      if (!cellA || !cellB) {
+        return undefined;
+      }
+      return cellA.attributesEquals(cellB);
+    })()`);
+    strictEqual(differentColor, false);
+
+    await ctx.page.evaluate(`window.term.reset()`);
+    await ctx.proxy.write(`${sgr(UNDERLINE_DOUBLE, UNDERLINE_COLOR_RED)}A${sgr(UNDERLINED, UNDERLINE_COLOR_RED)}B${sgr(NORMAL)}`);
+    const differentStyle = await ctx.page.evaluate(`(() => {
+      const line = window.term.buffer.active.getLine(0);
+      const cellA = line?.getCell(0);
+      const cellB = line?.getCell(1);
+      if (!cellA || !cellB) {
+        return undefined;
+      }
+      return cellA.attributesEquals(cellB);
+    })()`);
+    strictEqual(differentStyle, false);
+  });
+
   test('serialize all rows of content with color256', async function(): Promise<any> {
     const rows = 32;
     const cols = 10;
@@ -602,6 +649,9 @@ const BOLD = '1';
 const DIM = '2';
 const ITALIC = '3';
 const UNDERLINED = '4';
+const UNDERLINE_DOUBLE = '4:2';
+const UNDERLINE_COLOR_RED = '58;5;196';
+const UNDERLINE_COLOR_GREEN = '58;5;46';
 const BLINK = '5';
 const INVERSE = '7';
 const INVISIBLE = '8';

addons/addon-serialize/test/playwright.config.ts

@@ -5,10 +5,9 @@ const config: PlaywrightTestConfig = {
   timeout: 10000,
   projects: [
     {
-      name: 'ChromeStable',
+      name: 'Chromium',
       use: {
-        browserName: 'chromium',
-        channel: 'chrome'
+        browserName: 'chromium'
       }
     },
     {

addons/addon-serialize/test/tsconfig.json

@@ -9,7 +9,6 @@
     "outDir": "../out-test",
     "sourceMap": true,
     "removeComments": true,
-    "baseUrl": ".",
     "paths": {
       "common/*": [
         "../../../src/common/*"

addons/addon-unicode-graphemes/benchmark/tsconfig.json

@@ -1,13 +1,13 @@
 {
   "compilerOptions": {
     "lib": ["dom", "es6"],
+    "rootDir": "..",
     "outDir": "../out-benchmark",
     "types": ["../../../node_modules/@types/node"],
     "moduleResolution": "node",
     "strict": false,
     "target": "es2015",
     "module": "commonjs",
-    "baseUrl": ".",
     "paths": {
       "common/*": ["../../../src/common/*"],
       "browser/*": ["../../../src/browser/*"],

addons/addon-unicode-graphemes/package.json

@@ -16,7 +16,7 @@
     "xterm.js"
   ],
   "scripts": {
-    "build": "../../node_modules/.bin/tsc -p .",
+    "build": "../../node_modules/.bin/tsgo -p .",
     "prepackage": "npm run build",
     "package": "../../node_modules/.bin/webpack",
     "prepublishOnly": "npm run package",

addons/addon-unicode-graphemes/src/UnicodeGraphemesAddon.ts

@@ -9,19 +9,15 @@ import type { Terminal, ITerminalAddon, IUnicodeHandling } from '@xterm/xterm';
 import type { UnicodeGraphemesAddon as IUnicodeGraphemesApi } from '@xterm/addon-unicode-graphemes';
 import { UnicodeGraphemeProvider } from './UnicodeGraphemeProvider';
 
-export class UnicodeGraphemesAddon implements ITerminalAddon , IUnicodeGraphemesApi {
+export class UnicodeGraphemesAddon implements ITerminalAddon, IUnicodeGraphemesApi {
   private _provider15Graphemes?: UnicodeGraphemeProvider;
   private _provider15?: UnicodeGraphemeProvider;
   private _unicode?: IUnicodeHandling;
   private _oldVersion: string = '';
 
   public activate(terminal: Terminal): void {
-    if (! this._provider15) {
-      this._provider15 = new UnicodeGraphemeProvider(false);
-    }
-    if (! this._provider15Graphemes) {
-      this._provider15Graphemes = new UnicodeGraphemeProvider(true);
-    }
+    this._provider15 ??= new UnicodeGraphemeProvider(false);
+    this._provider15Graphemes ??= new UnicodeGraphemeProvider(true);
     const unicode = terminal.unicode;
     this._unicode = unicode;
     unicode.register(this._provider15);

addons/addon-unicode-graphemes/src/third-party/UnicodeProperties.ts

@@ -1,7 +1,7 @@
 import UnicodeTrie from './unicode-trie';
 const trieRaw = "AAARAAAAAABwxwAAAb4LQfTtmw+sVmUdx58LL/ffe/kjzNBV80gW1F3yR+6CvbJiypoZa0paWmAWSluErSBbFtYkkuZykq6QamGJ4WRqo2kFGy6dYWtEq6G1MFAJbRbOVTQr+x7f5+x97q/n/3me87wXzm/3s+f/7/d7/p7znnvOlvGMbQM7wIPgEbAPHABPgcPgefAS+BfYwuv/F/Q2OulBxKcK6TMRPxu8FcwFbwcjYCFYDC4Cl4ArwNXgGvBJsA58UdBDwy+jbBO4La8DtoEd4H7wkNBuN+KPgn3gADgIngaHwFHwF/AyeAWMm4C+TGi3LdiJ/EnIex04A2RgFpgD5oKFYDG4CLwHXAo+IKSvAqt4/evA9bz9jWA6+Cq3dyvCP8HWNwX93wF38/ROcD94SCjP2+1B+BiPP4HwgOD/7xD/I08fRniMx48jPAFeBeuF+n29jE0G08FZvaPHYWZvh9mcEfAOjlhXx/qGfd2QvLO3zccmtMnzliC9lPt+GenD1nyMiK/LNf1cycs+gfAzPJ6vtxe4jhuQtx5sBLeA28G3eb3v8/Beif4HkPewxu5G6N/rMP4qfgEdvwZPgj+AZ8Cx3nYfxiE8Dk6AV0FfH/YEOB28AbwJDIPzQAtcAC4Gl/Z19F+J+NVCehWPr0b46b7RvixvdPg8yr7U10l/BfFN4La8DdgGdoAHwU/AI2AfOACeAofB8+AlcAKwfvyBKeCM/o7NrF9PXmdWv9/Ynot2I7ztIg8dF5I2a8i63CjZU+9Fm2Wcy4U4ZQVYyeOrwVoev57UuxHcJKRvFuJXgnU8/nUebtbYrKmpCUOx31P7UVNTU1NTU1NTU1OGLTz8Xr/77+W7+9vP0or0MxPMbXaizY8FW3sQ3wseB/t5/kGEh8DR/vbzwL8i/Af4Dy8fP8BYE0weaKenI/wV/DhrQG97JspngzlgLpgHzgPzwUhdVpfVZXVZXRa87HxwAVgQ4Pn5WEd85l5TUzOasvezFw/E3b/LoP9D4CpwrcTWWsGXNQOj748/G9k3G56d1KYxmbELwQbwKFiJvBM8nDWlHa5E+AOwCzwLzjkNeeB28NvTeB1OYyr0gQ1g99R23nGE50xj7MPgc+A+8K5Bxj4FHgB/G2z/T9XEzCZjd/S0WYX4Pc3/r/Nn5I0f6qQXIP5x8ENwBMyYyNhHJ3b0pOCuLrBvM941NTU1JyNHEp+BrC8dMyalt1/m3uWfhmeULzRGp9d3wf0WZSN8+prCr60Wz09tuNmx35sl9Y825HXvRN39KNveaL8flb9f913kbec67kHeTsR3gYcH2uV7ED4m2HhCYi/X9ZuBzvuXv0f8iKIfx5B/XCg7gTgbVPdvAsomCuWnD45eK28UyvL3Jt+s0fU2TVnOXJQvJHUWIb0ELAWXgCt4+UcMumSsEtpch/g6ouMGpG/ieZsc9N/q4YsLd3D9WyPbsWEbfNgO7hN82TWY/n8xKbmsC3xQsYKf+7sjrx2TH+u4H3vhx+OO6+X9hmtXN7C/4r15EPaeBs9J7L7YBeeED/k7wn8fbIf/Rji+yVizmd4vW6bB19cb/PU9w7MxMA60bzPHgM8+zG623+OnzOf55yNc3Gw/k303wveBy3nZcoTXgNVgLfiCRNcG5N3SbIebwZ08fhe4l8d/BH7K4yI/4+HPwS/BAfBks+PzIaHuc3x+ivSL4GUyZ68I6fwZYRNMG2qnz+Th2QjfMtTx/1zE5w61nyN+Q7C3aKgdin1dgrylYBn4INdhGn/Z2FfFiqH01/SUXMvnPD+jC+j85N/RqRhR/DYaS6T+P09K1mD+vzW+5zVqqeVUl0wTz2lK8odJHRGXfBufdGLSoSo3+ZFJ6sl0qvJVNmhI4z4i06mrZ6uT1le1z5h5HE3tMiHPtQ5javu+ItMXUr/MXpmwmyRL3D6U7UwIMyYfczGu0qdqb2pbhcw4xQkhWQBMerrZ/liXrGTbsQwTwrEu4zSczKLrd7fCSKiKn+zSo8BWXMe8myXWOivrUxWi60OPoQ7VIasbQ0S/Ukk3rZVullNhHEL1rYoxUF0PTfm6elWJzq54ZsU4z11ohOy0oxT2izFqCNj4TesXcWZo6+Jfqr1O+1O1beqDagypj2J9F1u2daucj3Eknmq/6PaHrK7Mb1o35DiW1a/a76LuhlDXZX25SOz11S33ErKxDb2/fc/bFKI6axskn+4/W90u9mOtbRf7smsoTdvOfwoRz0t6DaP9k81v6P7Re5aUQudTd303rX+bZzBl97/KR7E+Xbux9lLI+aNr1PfaYLpPDiW2/vrYTX1drMIeXbMye6HXlw8292Jl7ZXxLxRlxXbcaH9drjFlxfa3Qozx8NWRi834lPVZbD+SmN7EJPzc9TVCSVXXDps9L+513b2J7fMu176V2YOhx1A3JrJ8KrLxUumpcu5j/lYT+2tzLRVDZmhjO442a1Clu0ox9VPVXzE/lcS4V0k1D6LI1pJsz8fct9SGbO5l/rmKzTlvsxdj3IvRtC2uv0t1fotltvd2VaCy5Sp5m0EhnZG4CCNxXZrWp/VUIrOjapfnNw11ZNI0V/GWzKNuxtzGKKTEtJeR0NVmpojbtBuW5On0u0is9ZMxvU8ZM+8vEyadtu10oqtP9Q4rcJEm85+Two/QkpGwjI6YkgkhtUfzZOW6fFVexuRri+qj9TJJHZkdmW5abiu0rs6uj2TMfmx06bISUj9tZ9Lja8dVQtox6WpxTJKfW3M4MSTmvU4sWy1CU6BF4jIfdNeDjHWuO1lCWIm2Jr2ixNZvklD2fP0Q6+vsmO4hqN1hJvfDtV5G8mTlsvau4qPP1a64L1skT6QYEzEtq0PzGZOfCbSdSmcKTP7Qs86Ej/1hEpelaV6IMdT5ayu2+nT9tmnnO746XbLxE8t0qOrYtJWhmk9bvaLfsrotRVw1PnR+bcafSUKZ6Mps7smobybJLH2R6WqRkJa1DHV0UmbfUcksiSF0HExSpp+uY0zbTklMaCm7blzEtg8h1rNMXNaYi05ZXsbC75sQ/4+aUxFV2jL50Q3jE0rK2rVtN09By8OHoo1vH2LPSdE323mr2sdu0pUZiDkWLRKWnfeQY6taKzHF9n/GPv8jd/0/egiRvYMR24fU79iY3s9Qva9RlYR8n8HHtq9fMcT1HRWfdZXiHd9YInt/iI4PTaf+BimXKvdXYU+3hlRpHzs2dVK/cxhDn+xs0I2jzxjL5kpXz1VU72aLtkK/97sALKyQqu25SshvG6h08/cLrlKswRklKXvvXfa+pZt+y8nah5YUv2Oo/ap/X2URdRfico9K69hcp6r6XaCz5Wo/hs/iNTGF6N6tV92/9ZS0Wba9SlT3pKF/e6W674+x9ly+VRL73cPU8ygb31D3eSqfVd+iqET0y3YMYojoO11XqrTt2nPxmeq1HYeqxkmUMt8DiesjpoTSr+qDrD+qPZDiOZxMdH0pRPX8MFUfQtv0Xbs+a1a1NnRryNZ/2+tsaPG5ZoX0RXZei88yZGdo4UMPj/cwv/kMJboxLISuQbE+1VW12Mx7FWOrW3M9Hv7Y+uxyraPSo8B2TGPuLdOeZha+hBKf8Sjsm/oR+7pmsx/oeOraFWdXleeV6oyl41zm+mgSuq9C6ox1TsU8D+m4dwMmf8v2nz7Tm+fYfj7HV1K/x1HWjquvY+2dllxM64ue87Su772zzbXIVC+WxLZTRR9MdkMTypZNH1z6G0tUvoccwxA+hfLNdV+a7MaQqscztMi+7QnxDZXvd1dldWQOyMbApb1Jd2h91Ffx+y9Xfb7tClokboOvrRhrbVpFFO8z+65t2/u4su9MUx028znH01/TGVDmHAj13W1o+1USw+eUfYtpO+b82rRNsb6oPpV+1fdBqddB6n3WDXvdJDZrJ0QfQp6bsc/kqq4BIddHWXGdN1pmWveh58F1zYUW1zmOITHXWOg1XrZvZSWUf77tq1ofqear6muaT1lIQp3bofabSafJVlnfYo9B6LGr8uzz2Xchvzfw+T9PlgiV/A8=";
 
-declare const Buffer: any;
+declare const Buffer: { from(s: string, encoding: string): Uint8Array } | undefined;
 function _dec(s: string): Uint8Array {
     if (typeof Buffer !== 'undefined') return Buffer.from(s, 'base64');
     const bs = atob(s);

addons/addon-unicode-graphemes/src/tsconfig.json

@@ -11,7 +11,6 @@
     "sourceMap": true,
     "removeComments": true,
     "strict": true,
-    "baseUrl": ".",
     "paths": {
       "common/*": [
         "../../../src/common/*"

addons/addon-unicode-graphemes/test/playwright.config.ts

@@ -5,10 +5,9 @@ const config: PlaywrightTestConfig = {
   timeout: 10000,
   projects: [
     {
-      name: 'ChromeStable',
+      name: 'Chromium',
       use: {
-        browserName: 'chromium',
-        channel: 'chrome'
+        browserName: 'chromium'
       }
     },
     {

addons/addon-unicode-graphemes/test/tsconfig.json

@@ -9,7 +9,6 @@
     "outDir": "../out-test",
     "sourceMap": true,
     "removeComments": true,
-    "baseUrl": ".",
     "paths": {
       "common/*": [
         "../../../src/common/*"

addons/addon-unicode11/package.json

@@ -16,7 +16,7 @@
     "xterm.js"
   ],
   "scripts": {
-    "build": "../../node_modules/.bin/tsc -p .",
+    "build": "../../node_modules/.bin/tsgo -p .",
     "prepackage": "npm run build",
     "package": "../../node_modules/.bin/webpack",
     "prepublishOnly": "npm run package",

addons/addon-unicode11/src/Unicode11Addon.ts

@@ -9,7 +9,7 @@ import type { Terminal, ITerminalAddon } from '@xterm/xterm';
 import type { Unicode11Addon as IUnicode11Api } from '@xterm/addon-unicode11';
 import { UnicodeV11 } from './UnicodeV11';
 
-export class Unicode11Addon implements ITerminalAddon , IUnicode11Api {
+export class Unicode11Addon implements ITerminalAddon, IUnicode11Api {
   public activate(terminal: Terminal): void {
     terminal.unicode.register(new UnicodeV11());
   }

addons/addon-unicode11/src/tsconfig.json

@@ -11,13 +11,15 @@
     "sourceMap": true,
     "removeComments": true,
     "strict": true,
-    "baseUrl": ".",
     "paths": {
       "common/*": [
         "../../../src/common/*"
       ],
       "@xterm/addon-unicode11": [
         "../typings/addon-unicode11.d.ts"
+      ],
+      "*": [
+        "./*"
       ]
     },
     "types": [

addons/addon-unicode11/test/playwright.config.ts

@@ -5,10 +5,9 @@ const config: PlaywrightTestConfig = {
   timeout: 10000,
   projects: [
     {
-      name: 'ChromeStable',
+      name: 'Chromium',
       use: {
-        browserName: 'chromium',
-        channel: 'chrome'
+        browserName: 'chromium'
       }
     },
     {

addons/addon-unicode11/test/tsconfig.json

@@ -9,13 +9,15 @@
     "outDir": "../out-test",
     "sourceMap": true,
     "removeComments": true,
-    "baseUrl": ".",
     "paths": {
       "common/*": [
         "../../../src/common/*"
       ],
       "browser/*": [
         "../../../src/browser/*"
+      ],
+      "*": [
+        "./*"
       ]
     },
     "strict": true,

addons/addon-web-fonts/package.json

@@ -16,7 +16,7 @@
     "xterm.js"
   ],
   "scripts": {
-    "build": "../../node_modules/.bin/tsc -p .",
+    "build": "../../node_modules/.bin/tsgo -p .",
     "prepackage": "npm run build",
     "package": "../../node_modules/.bin/webpack",
     "prepublishOnly": "npm run package",

addons/addon-web-fonts/test/WebFontsAddon.test.ts

@@ -33,16 +33,16 @@ test.describe('WebFontsAddon', () => {
   test.describe('font loading at runtime', () => {
     test('loadFonts (JS)', async () => {
       await ctx.page.evaluate(`
-        const ff1 = new FontFace('Kongtext', "url(/kongtext.regular.ttf) format('truetype')");
-        const ff2 = new FontFace('BPdots', "url(/bpdots.regular.otf) format('opentype')");
+        const ff1 = new FontFace('Kongtext', "url(/fonts/kongtext.regular.ttf) format('truetype')");
+        const ff2 = new FontFace('BPdots', "url(/fonts/bpdots.regular.otf) format('opentype')");
         loadFonts([ff1, ff2]);
       `);
       deepStrictEqual(await getDocumentFonts(), [{ family: 'Kongtext', status: 'loaded' }, { family: 'BPdots', status: 'loaded' }]);
     });
     test('loadFonts (CSS, unquoted)', async () => {
       await ctx.page.evaluate(`
-        document.styleSheets[0].insertRule("@font-face {font-family: Kongtext; src: url(/kongtext.regular.ttf) format('truetype')}", 0);
-        document.styleSheets[0].insertRule("@font-face {font-family: BPdots; src: url(/bpdots.regular.otf) format('opentype')}", 1);
+        document.styleSheets[0].insertRule("@font-face {font-family: Kongtext; src: url(/fonts/kongtext.regular.ttf) format('truetype')}", 0);
+        document.styleSheets[0].insertRule("@font-face {font-family: BPdots; src: url(/fonts/bpdots.regular.otf) format('opentype')}", 1);
         loadFonts(['Kongtext', 'BPdots']);
       `);
       deepStrictEqual(await getDocumentFonts(), [{ family: 'Kongtext', status: 'loaded' }, { family: 'BPdots', status: 'loaded' }]);
@@ -50,8 +50,8 @@ test.describe('WebFontsAddon', () => {
     test('loadFonts (CSS, quoted)', async ({ browser }) => {
       // NOTE: firefox preserves family quotes from CSS rules in fontface, all other browsers unquote them
       await ctx.page.evaluate(`
-        document.styleSheets[0].insertRule("@font-face {font-family: 'Kongtext'; src: url(/kongtext.regular.ttf) format('truetype')}", 0);
-        document.styleSheets[0].insertRule("@font-face {font-family: 'BPdots'; src: url(/bpdots.regular.otf) format('opentype')}", 1);
+        document.styleSheets[0].insertRule("@font-face {font-family: 'Kongtext'; src: url(/fonts/kongtext.regular.ttf) format('truetype')}", 0);
+        document.styleSheets[0].insertRule("@font-face {font-family: 'BPdots'; src: url(/fonts/bpdots.regular.otf) format('opentype')}", 1);
         loadFonts(['Kongtext', 'BPdots']);
       `);
       if (browser.browserType().name() === 'firefox') {
@@ -63,8 +63,8 @@ test.describe('WebFontsAddon', () => {
     test('FontFace hashing', async () => {
       // multiple calls of `loadFonts` with the same objects shall not bloat document.fonts
       await ctx.page.evaluate(`
-        const ff1 = new FontFace('Kongtext', "url(/kongtext.regular.ttf) format('truetype')");
-        const ff2 = new FontFace('BPdots', "url(/bpdots.regular.otf) format('opentype')");
+        const ff1 = new FontFace('Kongtext', "url(/fonts/kongtext.regular.ttf) format('truetype')");
+        const ff2 = new FontFace('BPdots', "url(/fonts/bpdots.regular.otf) format('opentype')");
         loadFonts([ff1, ff2]);
         loadFonts([ff1, ff2]);
         loadFonts([ff1, ff2]).then(() => loadFonts([ff1, ff2]));
@@ -76,7 +76,7 @@ test.describe('WebFontsAddon', () => {
       // to make this test work, we exclude the default measurement char W (x57) by restricting unicode-range
       // now the browser will postpone font loading until codepoint is hit --> wrong glyph metrics on first usage
       const data = await ctx.page.evaluate(`
-          document.styleSheets[0].insertRule("@font-face {font-family: Kongtext; src: url(/kongtext.regular.ttf) format('truetype'); unicode-range: U+00A0-00FF}", 0);
+          document.styleSheets[0].insertRule("@font-face {font-family: Kongtext; src: url(/fonts/kongtext.regular.ttf) format('truetype'); unicode-range: U+00A0-00FF}", 0);
         `);
       deepStrictEqual(await getDocumentFonts(), [{ family: 'Kongtext', status: 'unloaded' }]);
 
@@ -88,7 +88,11 @@ test.describe('WebFontsAddon', () => {
 
       // safari loads the font, firefox & chrome dont
       if (browser.browserType().name() === 'webkit') {
-        deepStrictEqual(await getDocumentFonts(), [{ family: 'Kongtext', status: 'loaded' }]);
+        try {
+          deepStrictEqual(await getDocumentFonts(), [{ family: 'Kongtext', status: 'loading' }]);
+        } catch (e) {
+          deepStrictEqual(await getDocumentFonts(), [{ family: 'Kongtext', status: 'loaded' }]);
+        }
       } else {
         deepStrictEqual(await getDocumentFonts(), [{ family: 'Kongtext', status: 'unloaded' }]);
       }
@@ -103,7 +107,10 @@ test.describe('WebFontsAddon', () => {
           window.helperTerm.open(term.element);
         `);
       await timeout(100);
-      deepStrictEqual(await getDocumentFonts(), [{ family: 'Kongtext', status: 'loaded' }]);
+      if (browser.browserType().name() !== 'webkit') {
+        // safari sometimes reports 'unloadeed'?
+        deepStrictEqual(await getDocumentFonts(), [{ family: 'Kongtext', status: 'loaded' }]);
+      }
 
       // cleanup this messy test case
       await ctx.page.evaluate(`

addons/addon-web-fonts/test/playwright.config.ts

@@ -5,10 +5,9 @@ const config: PlaywrightTestConfig = {
   timeout: 10000,
   projects: [
     {
-      name: 'ChromeStable',
+      name: 'Chromium',
       use: {
-        browserName: 'chromium',
-        channel: 'chrome'
+        browserName: 'chromium'
       }
     },
     {

addons/addon-web-fonts/test/tsconfig.json

@@ -10,13 +10,15 @@
     "outDir": "../out-test",
     "sourceMap": true,
     "removeComments": true,
-    "baseUrl": ".",
     "paths": {
       "common/*": [
         "../../../src/common/*"
       ],
       "browser/*": [
         "../../../src/browser/*"
+      ],
+      "*": [
+        "./*"
       ]
     },
     "strict": true,

addons/addon-web-links/package.json

@@ -16,7 +16,7 @@
     "xterm.js"
   ],
   "scripts": {
-    "build": "../../node_modules/.bin/tsc -p .",
+    "build": "../../node_modules/.bin/tsgo -p .",
     "prepackage": "npm run build",
     "package": "../../node_modules/.bin/webpack",
     "prepublishOnly": "npm run package",

addons/addon-web-links/src/WebLinksAddon.ts

@@ -35,7 +35,7 @@ function handleLink(event: MouseEvent, uri: string): void {
   }
 }
 
-export class WebLinksAddon implements ITerminalAddon , IWebLinksApi {
+export class WebLinksAddon implements ITerminalAddon, IWebLinksApi {
   private _terminal: Terminal | undefined;
   private _linkProvider: IDisposable | undefined;
 
@@ -48,7 +48,7 @@ export class WebLinksAddon implements ITerminalAddon , IWebLinksApi {
   public activate(terminal: Terminal): void {
     this._terminal = terminal;
     const options = this._options as ILinkProviderOptions;
-    const regex = options.urlRegex || strictUrlRegex;
+    const regex = options.urlRegex ?? strictUrlRegex;
     this._linkProvider = this._terminal.registerLinkProvider(new WebLinkProvider(this._terminal, regex, this._handler, options));
   }
 

addons/addon-web-links/test/playwright.config.ts

@@ -5,10 +5,9 @@ const config: PlaywrightTestConfig = {
   timeout: 10000,
   projects: [
     {
-      name: 'ChromeStable',
+      name: 'Chromium',
       use: {
-        browserName: 'chromium',
-        channel: 'chrome'
+        browserName: 'chromium'
       }
     },
     {

addons/addon-web-links/test/tsconfig.json

@@ -10,13 +10,15 @@
     "outDir": "../out-test",
     "sourceMap": true,
     "removeComments": true,
-    "baseUrl": ".",
     "paths": {
       "common/*": [
         "../../../src/common/*"
       ],
       "browser/*": [
         "../../../src/browser/*"
+      ],
+      "*": [
+        "./*"
       ]
     },
     "strict": true,

addons/addon-webgl/package.json

@@ -17,7 +17,7 @@
     "xterm.js"
   ],
   "scripts": {
-    "build": "../../node_modules/.bin/tsc -p .",
+    "build": "../../node_modules/.bin/tsgo -p .",
     "prepackage": "npm run build",
     "package": "../../node_modules/.bin/webpack",
     "prepublishOnly": "npm run package",

addons/addon-webgl/src/CellColorResolver.ts

@@ -7,6 +7,7 @@ import { ICellData } from 'common/Types';
 import { Terminal } from '@xterm/xterm';
 import { rgba } from 'common/Color';
 import { treatGlyphAsBackgroundColor } from 'browser/renderer/shared/RendererUtils';
+import { blockPatternCodepoints } from './customGlyphs/CustomGlyphDefinitions';
 
 // Work variables to avoid garbage collection
 let $fg = 0;
@@ -42,7 +43,7 @@ export class CellColorResolver {
    * Resolves colors for the cell, putting the result into the shared {@link result}. This resolves
    * overrides, inverse and selection for the cell which can then be used to feed into the renderer.
    */
-  public resolve(cell: ICellData, x: number, y: number, deviceCellWidth: number): void {
+  public resolve(cell: ICellData, x: number, y: number, deviceCellWidth: number, deviceCellHeight: number): void {
     this.result.bg = cell.bg;
     this.result.fg = cell.fg;
     this.result.ext = cell.bg & BgFlags.HAS_EXTENDED ? cell.extended.ext : 0;
@@ -63,7 +64,9 @@ export class CellColorResolver {
       const lineWidth = Math.max(1, Math.floor(this._optionService.rawOptions.fontSize * this._coreBrowserService.dpr / 15));
       $variantOffset = x * deviceCellWidth % (Math.round(lineWidth) * 2);
     }
-
+    if ($variantOffset === 0 && blockPatternCodepoints.has(code)) {
+      $variantOffset = ((x * deviceCellWidth) % 2) * 2 + ((y * deviceCellHeight) % 2);
+    }
     // Apply decorations on the bottom layer
     this._decorationService.forEachDecorationAtCell(x, y, 'bottom', d => {
       if (d.backgroundColorRGB) {

addons/addon-webgl/src/CharAtlasCache.ts

@@ -8,6 +8,7 @@ import { ITerminalOptions, Terminal } from '@xterm/xterm';
 import { ITerminal, ReadonlyColorSet } from 'browser/Types';
 import { ICharAtlasConfig, ITextureAtlas } from './Types';
 import { generateConfig, configEquals } from './CharAtlasUtils';
+import type { ILogService } from 'common/services/Services';
 
 interface ITextureAtlasCacheEntry {
   atlas: ITextureAtlas;
@@ -67,8 +68,9 @@ export function acquireTextureAtlas(
   }
 
   const core: ITerminal = (terminal as any)._core;
+  const logService = (core as any)._logService as ILogService;
   const newEntry: ITextureAtlasCacheEntry = {
-    atlas: new TextureAtlas(document, newConfig, core.unicodeService),
+    atlas: new TextureAtlas(document, newConfig, core.unicodeService, logService),
     config: newConfig,
     ownedBy: [terminal]
   };