@xterm/addon-image 0.10.0-beta.3 → 0.10.0-beta.300

package/src/ImageStorage.ts

@@ -5,7 +5,11 @@
 
 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, IAddImageOpts
+} from './Types';
 
 
 // fallback default cell size
@@ -124,6 +128,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 +138,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 +195,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 +225,29 @@ 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 opts - Options for addImage:
+   *   - scrolling:  When true, cursor advances with the image.
+   *                 When false, image is placed at ORIGIN and cursor does not move.
+   *   - layer:      Which canvas layer to render on ('top' or 'bottom').
+   *   - zIndex:     Z-index for image layering within the same layer.
+   *   - cursorPos:  'vt340' for bottom-left, 'iip' for bottom.right.
+   * @returns The internal image ID assigned to the stored image.
    */
-  public addImage(img: HTMLCanvasElement | ImageBitmap): void {
+  public addImage(img: HTMLCanvasElement | ImageBitmap, opts: IAddImageOpts): number {
     // never allow storage to exceed memory limit
     this._evictOldest(img.width * img.height);
 
@@ -257,7 +269,7 @@ export class ImageStorage implements IDisposable {
     let offset = originX;
     let tileCount = 0;
 
-    if (!this._opts.sixelScrolling) {
+    if (!opts.scrolling) {
       buffer.x = 0;
       buffer.y = 0;
       offset = 0;
@@ -271,7 +283,7 @@ export class ImageStorage implements IDisposable {
         this._writeToCell(line as IBufferLineExt, offset + col, imageId, row * cols + col);
         tileCount++;
       }
-      if (this._opts.sixelScrolling) {
+      if (opts.scrolling) {
         if (row < rows - 1) this._terminal._core._inputHandler.lineFeed();
       } else {
         if (++buffer.y >= termRows) break;
@@ -281,8 +293,12 @@ export class ImageStorage implements IDisposable {
     this._terminal._core._inputHandler._dirtyRowTracker.markDirty(buffer.y);
 
     // cursor positioning modes
-    if (this._opts.sixelScrolling) {
-      buffer.x = offset;
+    if (opts.scrolling) {
+      if (opts.cursorPos === 'iip') {
+        buffer.x = Math.min(offset + cols, termCols);
+      } else {
+        buffer.x = offset;
+      }
     } else {
       buffer.x = originX;
       buffer.y = originY;
@@ -324,11 +340,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: opts.layer,
+      zIndex: opts.zIndex
     };
 
     // finally add the image
     this._images.set(imageId, imgSpec);
+    this.onImageAdded?.();
+    return imageId;
   }
 
 
@@ -338,16 +358,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 +389,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,13 +422,17 @@ 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
     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) {
         if (line.getBg(col) & BgFlags.HAS_EXTENDED) {
-          let e: IExtendedAttrsImage = line._extendedAttrs[col] || EMPTY_ATTRS;
+          let e: IExtendedAttrsImage = line._extendedAttrs[col] ?? EMPTY_ATTRS;
           const imageId = e.imageId;
           if (imageId === undefined || imageId === -1) {
             continue;
@@ -400,7 +451,7 @@ export class ImageStorage implements IDisposable {
             while (
               ++col < cols
               && (line.getBg(col) & BgFlags.HAS_EXTENDED)
-              && (e = line._extendedAttrs[col] || EMPTY_ATTRS)
+              && (e = line._extendedAttrs[col] ?? EMPTY_ATTRS)
               && (e.imageId === imageId)
               && (e.tileId === startTile + count)
             ) {
@@ -409,16 +460,29 @@ export class ImageStorage implements IDisposable {
             col--;
             if (imgSpec) {
               if (imgSpec.actual) {
-                this._renderer.draw(imgSpec, startTile, startCol, row, count);
+                drawCalls.push({ imgSpec, tileId: startTile, col: startCol, row, count });
               }
             } else if (this._opts.showPlaceholder) {
-              this._renderer.drawPlaceholder(startCol, row, count);
+              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) {

package/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);
       }
@@ -99,7 +99,7 @@ export class SixelHandler implements IDcsHandler, IResetHandler {
     }
 
     const canvas = ImageRenderer.createCanvas(undefined, width, height);
-    canvas.getContext('2d')?.putImageData(new ImageData(this._dec.data8, width, height), 0, 0);
+    canvas.getContext('2d')?.putImageData(new ImageData(this._dec.data8 as Uint8ClampedArray<ArrayBuffer>, width, height), 0, 0);
     if (this._dec.memoryUsage > MEM_PERMA_LIMIT) {
       this._dec.release();
     }

package/src/SixelImageStorage.ts

@@ -0,0 +1,52 @@
+/**
+ * Copyright (c) 2020 The xterm.js authors. All rights reserved.
+ * @license MIT
+ */
+
+import { ImageStorage, CELL_SIZE_DEFAULT } from './ImageStorage';
+import { IImageAddonOptions, ITerminalExt, IAddImageOpts } 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 {
+  private _addImageOpts: IAddImageOpts = { scrolling: true, layer: 'top', zIndex: 0, cursorPos: 'vt340' };
+  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._addImageOpts.scrolling = this._opts.sixelScrolling;
+    this._storage.addImage(img, this._addImageOpts);
+  }
+
+  /**
+   * 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();
+      }
+    }
+  }
+}

package/src/Types.ts

@@ -8,8 +8,9 @@ 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 { IParams, IDcsHandler, IOscHandler, IApcHandler, IEscapeSequenceParser } from 'common/parser/Types';
+import type { IInputHandler } from 'common/Types';
+import type { IBufferLine, IExtendedAttrs } from 'common/buffer/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';
@@ -22,7 +23,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 +39,8 @@ export interface IImageAddonOptions {
   sixelSizeLimit: number;
   iipSupport: boolean;
   iipSizeLimit: number;
+  kittySupport: boolean;
+  kittySizeLimit: number;
 }
 
 export interface IResetHandler {
@@ -97,6 +100,16 @@ export interface ICellSize {
   height: number;
 }
 
+export type ImageLayer = 'top' | 'bottom';
+export type CursorPos = 'vt340' | 'iip';
+
+export interface IAddImageOpts {
+  scrolling: boolean;
+  layer: ImageLayer;
+  zIndex: number;
+  cursorPos: CursorPos;
+}
+
 export interface IImageSpec {
   orig: HTMLCanvasElement | ImageBitmap | undefined;
   origCellSize: ICellSize;
@@ -105,4 +118,6 @@ export interface IImageSpec {
   marker: IMarker | undefined;
   tileCount: number;
   bufferType: 'alternate' | 'normal';
+  layer: ImageLayer;
+  zIndex: number;
 }