Merge branch 'master' into master

Author: Tyriar

README.md

@@ -94,7 +94,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
 
@@ -230,6 +230,7 @@ Xterm.js is used in many world-class applications to provide great terminal expe
 - [**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.
 - [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-image/src/ImageAddon.ts

@@ -5,6 +5,7 @@
 
 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';
@@ -62,6 +63,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);
@@ -74,6 +77,7 @@ export class ImageAddon implements ITerminalAddon, IImageApi {
     }
     this._disposables.length = 0;
     this._handlers.clear();
+    this._onImageAdded.dispose();
   }
 
   private _disposeLater(...args: IDisposable[]): void {
@@ -88,6 +92,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) {

addons/addon-image/src/ImageStorage.ts

@@ -124,6 +124,7 @@ 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(
@@ -336,6 +337,7 @@ export class ImageStorage implements IDisposable {
 
     // finally add the image
     this._images.set(imageId, imgSpec);
+    this.onImageAdded?.();
     return imageId;
   }
 

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

@@ -752,10 +752,10 @@ export class KittyGraphicsHandler implements IApcHandler, IResetHandler, IDispos
       const b1 = src32[srcOffset++];
       const b2 = src32[srcOffset++];
       // Little-endian: pixel bytes are [R,G,B] → uint32 ABGR layout
-      dst32[dstOffset++] = (b0 & 0x00FFFFFF) | 0xFF000000;
-      dst32[dstOffset++] = ((b0 >>> 24) | (b1 << 8)) & 0x00FFFFFF | 0xFF000000;
-      dst32[dstOffset++] = ((b1 >>> 16) | (b2 << 16)) & 0x00FFFFFF | 0xFF000000;
-      dst32[dstOffset++] = (b2 >>> 8) | 0xFF000000;
+      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

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

@@ -196,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);

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

@@ -2159,6 +2159,19 @@ test.describe('Kitty Graphics Protocol', () => {
       strictEqual(await ctx.page.evaluate(`window.imageAddon._storage._images.has(${oldStorageId})`), false);
     });
   });
+
+  test.describe('onImageAdded callback', () => {
+    test('onImageAdded fires for each kitty image', async () => {
+      await ctx.page.evaluate(`
+        window._imageAddedCount = 0;
+        window.imageAddon.onImageAdded(() => { window._imageAddedCount++; });
+      `);
+      await ctx.proxy.write(`\x1b_Ga=T,f=100;${KITTY_BLACK_1X1_BASE64}\x1b\\`);
+      await pollFor(ctx.page, 'window._imageAddedCount', 1);
+      await ctx.proxy.write(`\x1b_Ga=T,f=100;${KITTY_RGB_3X1_BASE64}\x1b\\`);
+      await pollFor(ctx.page, 'window._imageAddedCount', 2);
+    });
+  });
 });
 
 /**

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 {
@@ -116,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.
      */

headless/README.md

@@ -2,30 +2,30 @@
 
 ⚠ This package is experimental
 
-`xterm-headless` is a headless terminal that can be run in node.js. This is useful in combination with the frontend [`xterm`](https://www.npmjs.com/package/xterm) for example to keep track of a terminal's state on a remote server where the process is hosted.
+`@xterm/headless` is a headless terminal that can be run in node.js. This is useful in combination with the frontend [`xterm`](https://www.npmjs.com/package/@xterm/xterm) for example to keep track of a terminal's state on a remote server where the process is hosted.
 
 ## Getting Started
 
 First, you need to install the module, we ship exclusively through npm, so you need that installed and then add xterm.js as a dependency by running:
 
 ```sh
-npm install xterm-headless
+npm install @xterm/headless
 ```
 
-Then import as you would a regular node package. The recommended way to load `xterm-headless` is with TypeScript and the ES6 module syntax:
+Then import as you would a regular node package. The recommended way to load `@xterm/headless` is with TypeScript and the ES6 module syntax:
 
 ```javascript
 import { Terminal } from '@xterm/headless';
 ```
 
 ## API
 
-The full API for `xterm-headless` is contained within the [TypeScript declaration file](https://github.com/xtermjs/xterm.js/blob/master/typings/xterm-headless.d.ts), use the branch/tag picker in GitHub (`w`) to navigate to the correct version of the API.
+The full API for `@xterm/headless` is contained within the [TypeScript declaration file](https://github.com/xtermjs/xterm.js/blob/master/typings/xterm-headless.d.ts), use the branch/tag picker in GitHub (`w`) to navigate to the correct version of the API.
 
 Note that some APIs are marked *experimental*, these are added to enable experimentation with new ideas without committing to support it like a normal [semver](https://semver.org/) API. Note that these APIs can change radically between versions, so be sure to read release notes if you plan on using experimental APIs.
 
 ### Addons
 
-Addons in `xterm-headless` work the [same as in `xterm`](https://github.com/xtermjs/xterm.js/blob/master/README.md#addons) with the one caveat being that the addon needs to be packaged for node.js and not use any DOM APIs.
+Addons in `@xterm/headless` work the [same as in `xterm`](https://github.com/xtermjs/xterm.js/blob/master/README.md#addons) with the one caveat being that the addon needs to be packaged for node.js and not use any DOM APIs.
 
 Currently no official addons are packaged on npm.