@xterm/addon-image 0.7.0-beta.1

package/src/SixelHandler.ts

@@ -0,0 +1,151 @@
+/**
+ * Copyright (c) 2020, 2023 The xterm.js authors. All rights reserved.
+ * @license MIT
+ */
+
+import { ImageStorage } from './ImageStorage';
+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';
+import { ImageRenderer } from './ImageRenderer';
+
+import { DecoderAsync, Decoder } from 'sixel/lib/Decoder';
+
+// always free decoder ressources after decoding if it exceeds this limit
+const MEM_PERMA_LIMIT = 4194304; // 1024 pixels * 1024 pixels * 4 channels = 4MB
+
+// custom default palette: VT340 (lower 16 colors) + ANSI256 (up to 256) + zeroed (up to 4096)
+const DEFAULT_PALETTE = PALETTE_ANSI_256;
+DEFAULT_PALETTE.set(PALETTE_VT340_COLOR);
+
+
+export class SixelHandler implements IDcsHandler, IResetHandler {
+  private _size = 0;
+  private _aborted = false;
+  private _dec: Decoder | undefined;
+
+  constructor(
+    private readonly _opts: IImageAddonOptions,
+    private readonly _storage: ImageStorage,
+    private readonly _coreTerminal: ITerminalExt
+  ) {
+    DecoderAsync({
+      memoryLimit: this._opts.pixelLimit * 4,
+      palette: DEFAULT_PALETTE,
+      paletteLimit: this._opts.sixelPaletteLimit
+    }).then(d => this._dec = d);
+  }
+
+  public reset(): void {
+    /**
+     * reset sixel decoder to defaults:
+     * - release all memory
+     * - nullify palette (4096)
+     * - apply default palette (256)
+     */
+    if (this._dec) {
+      this._dec.release();
+      // FIXME: missing interface on decoder to nullify full palette
+      (this._dec as any)._palette.fill(0);
+      this._dec.init(0, DEFAULT_PALETTE, this._opts.sixelPaletteLimit);
+    }
+  }
+
+  public hook(params: IParams): void {
+    this._size = 0;
+    this._aborted = false;
+    if (this._dec) {
+      const fillColor = params.params[1] === 1 ? 0 : extractActiveBg(
+        this._coreTerminal._core._inputHandler._curAttrData,
+        this._coreTerminal._core._themeService?.colors);
+      this._dec.init(fillColor, null, this._opts.sixelPaletteLimit);
+    }
+  }
+
+  public put(data: Uint32Array, start: number, end: number): void {
+    if (this._aborted || !this._dec) {
+      return;
+    }
+    this._size += end - start;
+    if (this._size > this._opts.sixelSizeLimit) {
+      console.warn(`SIXEL: too much data, aborting`);
+      this._aborted = true;
+      this._dec.release();
+      return;
+    }
+    try {
+      this._dec.decode(data, start, end);
+    } catch (e) {
+      console.warn(`SIXEL: error while decoding image - ${e}`);
+      this._aborted = true;
+      this._dec.release();
+    }
+  }
+
+  public unhook(success: boolean): boolean | Promise<boolean> {
+    if (this._aborted || !success || !this._dec) {
+      return true;
+    }
+
+    const width = this._dec.width;
+    const height = this._dec.height;
+
+    // partial fix for https://github.com/jerch/xterm-addon-image/issues/37
+    if (!width || ! height) {
+      if (height) {
+        this._storage.advanceCursor(height);
+      }
+      return true;
+    }
+
+    const canvas = ImageRenderer.createCanvas(undefined, width, height);
+    canvas.getContext('2d')?.putImageData(new ImageData(this._dec.data8, width, height), 0, 0);
+    if (this._dec.memoryUsage > MEM_PERMA_LIMIT) {
+      this._dec.release();
+    }
+    this._storage.addImage(canvas);
+    return true;
+  }
+}
+
+
+/**
+ * Some helpers to extract current terminal colors.
+ */
+
+// get currently active background color from terminal
+// also respect INVERSE setting
+function extractActiveBg(attr: AttributeData, colors: ReadonlyColorSet | undefined): RGBA8888 {
+  let bg = 0;
+  if (!colors) {
+    // FIXME: theme service is prolly not available yet,
+    // happens if .open() was not called yet (bug in core?)
+    return bg;
+  }
+  if (attr.isInverse()) {
+    if (attr.isFgDefault()) {
+      bg = convertLe(colors.foreground.rgba);
+    } else if (attr.isFgRGB()) {
+      const t = (attr.constructor as typeof AttributeData).toColorRGB(attr.getFgColor());
+      bg = toRGBA8888(...t);
+    } else {
+      bg = convertLe(colors.ansi[attr.getFgColor()].rgba);
+    }
+  } else {
+    if (attr.isBgDefault()) {
+      bg = convertLe(colors.background.rgba);
+    } else if (attr.isBgRGB()) {
+      const t = (attr.constructor as typeof AttributeData).toColorRGB(attr.getBgColor());
+      bg = toRGBA8888(...t);
+    } else {
+      bg = convertLe(colors.ansi[attr.getBgColor()].rgba);
+    }
+  }
+  return bg;
+}
+
+// rgba values on the color managers are always in BE, thus convert to LE
+function convertLe(color: number): RGBA8888 {
+  if (BIG_ENDIAN) return color;
+  return (color & 0xFF) << 24 | (color >>> 8 & 0xFF) << 16 | (color >>> 16 & 0xFF) << 8 | color >>> 24 & 0xFF;
+}

package/src/Types.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Copyright (c) 2020 The xterm.js authors. All rights reserved.
+ * @license MIT
+ */
+
+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 { IBufferLine, IExtendedAttrs, IInputHandler } from 'common/Types';
+import type { ITerminal, ReadonlyColorSet } from 'browser/Types';
+import type { IRenderDimensions } from 'browser/renderer/shared/Types';
+import type { ICoreBrowserService, IRenderService, IThemeService } from 'browser/services/Services';
+
+export const enum Cell {
+  CONTENT = 0,  // codepoint and wcwidth information (enum Content)
+  FG = 1,       // foreground color in lower 3 bytes (rgb), attrs in 4th byte (enum FgFlags)
+  BG = 2,       // background color in lower 3 bytes (rgb), attrs in 4th byte (enum BgFlags)
+  SIZE = 3      // size of single cell on buffer array
+}
+
+// export some privates for local usage
+export { AttributeData, IParams, IDcsHandler, IOscHandler, BgFlags, IRenderDimensions, IRenderService, Content, ExtFlags, Attributes, UnderlineStyle, ReadonlyColorSet };
+
+/**
+ * Plugin ctor options.
+ */
+export interface IImageAddonOptions {
+  enableSizeReports: boolean;
+  pixelLimit: number;
+  storageLimit: number;
+  showPlaceholder: boolean;
+  sixelSupport: boolean;
+  sixelScrolling: boolean;
+  sixelPaletteLimit: number;
+  sixelSizeLimit: number;
+  iipSupport: boolean;
+  iipSizeLimit: number;
+}
+
+export interface IResetHandler {
+  // attached to RIS and DECSTR
+  reset(): void;
+}
+
+/**
+ * Stub into private interfaces.
+ * This should be kept in line with common libs.
+ * Any change made here should be replayed in the accessors test case to
+ * have a somewhat reliable testing against code changes in the core repo.
+ */
+
+// overloaded IExtendedAttrs to hold image refs
+export interface IExtendedAttrsImage extends IExtendedAttrs {
+  imageId: number;
+  tileId: number;
+  clone(): IExtendedAttrsImage;
+}
+
+/* eslint-disable */
+export interface IBufferLineExt extends IBufferLine {
+  _extendedAttrs: {[index: number]: IExtendedAttrsImage | undefined};
+  _data: Uint32Array;
+}
+
+interface IInputHandlerExt extends IInputHandler {
+  _parser: IEscapeSequenceParser;
+  _curAttrData: AttributeData;
+  _dirtyRowTracker: {
+    markRangeDirty(y1: number, y2: number): void;
+    markAllDirty(): void;
+    markDirty(y: number): void;
+  };
+  onRequestReset(handler: () => void): IDisposable;
+}
+
+export interface ICoreTerminalExt extends ITerminal {
+  _themeService: IThemeService | undefined;
+  _inputHandler: IInputHandlerExt;
+  _renderService: IRenderService;
+  _coreBrowserService: ICoreBrowserService | undefined;
+}
+
+export interface ITerminalExt extends Terminal {
+  _core: ICoreTerminalExt;
+}
+/* eslint-enable */
+
+
+/**
+ * Some storage definitions.
+ */
+export interface ICellSize {
+  width: number;
+  height: number;
+}
+
+export interface IImageSpec {
+  orig: HTMLCanvasElement | ImageBitmap | undefined;
+  origCellSize: ICellSize;
+  actual: HTMLCanvasElement | ImageBitmap | undefined;
+  actualCellSize: ICellSize;
+  marker: IMarker | undefined;
+  tileCount: number;
+  bufferType: 'alternate' | 'normal';
+}

package/typings/addon-image.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Copyright (c) 2022 The xterm.js authors. All rights reserved.
+ * @license MIT
+ */
+
+import { Terminal, ITerminalAddon } from '@xterm/xterm';
+
+declare module '@xterm/addon-image' {
+  export interface IImageAddonOptions {
+    /**
+     * Enable size reports in windowOptions:
+     * - getWinSizePixels (CSI 14 t)
+     * - getCellSizePixels (CSI 16 t)
+     * - getWinSizeChars (CSI 18 t)
+     *
+     * If `true` (default), the reports will be activated during addon loading.
+     * If `false`, no settings will be touched. Use `false`, if you have high
+     * security constraints and/or deal with windowOptions by other means.
+     * On addon disposal, the settings will not change.
+     */
+    enableSizeReports?: boolean;
+
+    /**
+     * Maximum pixels a single image may hold. Images exceeding this number will
+     * be discarded during processing with no changes to the terminal buffer
+     * (no cursor advance, no placeholder).
+     * This setting is mainly used to restrict images sizes during initial decoding
+     * including the final canvas creation.
+     *
+     * Note: The image worker decoder may hold additional memory up to
+     * `pixelLimit` * 4 bytes permanently, plus the same amount on top temporarily
+     * for pixel transfers, which should be taken into account under memory pressure conditions.
+     *
+     * Note: Browsers restrict allowed canvas dimensions further. We dont reflect those
+     * limits here, thus the construction of an oddly shaped image having most pixels
+     * in one dimension still can fail.
+     *
+     * Note: `storageLimit` bytes are calculated from images by multiplying the pixels with 4
+     * (4 channels with one byte, images are stored as RGBA8888).
+     *
+     * Default is 2^16 (4096 x 4096 pixels).
+     */
+    pixelLimit?: number;
+
+    /**
+     * Storage limit in MB.
+     * The storage implements a FIFO cache removing old images, when the limit gets hit.
+     * Also exposed as addon property for runtime adjustments.
+     * Default is 128 MB.
+     */
+    storageLimit?: number;
+
+    /**
+     * Whether to show a placeholder for images removed from cache, default is true.
+     */
+    showPlaceholder?: boolean;
+
+    /**
+     * SIXEL settings
+     */
+
+    /** Whether SIXEL is enabled (default is true). */
+    sixelSupport?: boolean;
+    /** Whether SIXEL scrolling is enabled (default is true). Same as DECSET 80. */
+    sixelScrolling?: boolean;
+    /** Palette color limit (default 256). */
+    sixelPaletteLimit?: number;
+    /** SIXEL image size limit in bytes (default 25000000 bytes). */
+    sixelSizeLimit?: number;
+
+    /**
+     * IIP settings (iTerm image protocol)
+     */
+
+    /** Whether iTerm image protocol style is enabled (default is true). */
+    iipSupport?: boolean;
+    /** IIP sequence size limit (default 20000000 bytes). */
+    iipSizeLimit?: number;
+  }
+
+  export class ImageAddon implements ITerminalAddon {
+    constructor(options?: IImageAddonOptions);
+    public activate(terminal: Terminal): void;
+    public dispose(): void;
+
+    /**
+     * Reset the image addon.
+     *
+     * This resets all runtime options to default values (as given to the ctor)
+     * and resets the image storage.
+     */
+    public reset(): void;
+
+    /**
+     * Getter/Setter for the storageLimit in MB.
+     * Synchronously deletes images if the stored data exceeds the new value.
+     */
+    public storageLimit: number;
+
+    /**
+     * Current memory usage of the stored images in MB.
+     */
+    public readonly storageUsage: number;
+
+    /**
+     * Getter/Setter whether the placeholder should be shown.
+     */
+    public showPlaceholder: boolean;
+
+    /**
+     * Get original image canvas at buffer position.
+     */
+    public getImageAtBufferCell(x: number, y: number): HTMLCanvasElement | undefined;
+
+    /**
+     * Extract single tile canvas at buffer position.
+     */
+    public extractTileAtBufferCell(x: number, y: number): HTMLCanvasElement | undefined;
+  }
+}