@xterm/addon-image 0.10.0-beta.25 → 0.10.0-beta.250

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xterm/addon-image",
-  "version": "0.10.0-beta.25",
+  "version": "0.10.0-beta.250",
   "author": {
     "name": "The xterm.js authors",
     "url": "https://xtermjs.org/"
@@ -18,17 +18,17 @@
     "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"
   },
-  "commit": "6fe5a124ca8a8e1643a7560aa13bc21005e59445",
+  "commit": "56564431633cc0e7b445292ad2e6b4c9cf0e66ba",
   "peerDependencies": {
-    "@xterm/xterm": "^6.1.0-beta.25"
+    "@xterm/xterm": "^6.1.0-beta.250"
   }
 }

package/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([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);

package/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);

package/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);
+  }
+}

package/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;
 }
 

package/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.