@xterm/headless 6.1.0-beta.3 → 6.1.0-beta.300

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xterm/headless",
   "description": "A headless terminal component that runs in Node.js",
-  "version": "6.1.0-beta.3",
+  "version": "6.1.0-beta.300",
   "main": "lib-headless/xterm-headless.js",
   "module": "lib/xterm.mjs",
   "types": "typings/xterm-headless.d.ts",
@@ -10,6 +10,9 @@
   "workspaces": [
     "addons/*"
   ],
+  "overrides": {
+    "serialize-javascript": "^7.0.3"
+  },
   "keywords": [
     "cli",
     "command-line",
@@ -25,5 +28,5 @@
     "webgl",
     "xterm"
   ],
-  "commit": "8308ede3f5a74b24e1a7aaed89be68404951e5bc"
+  "commit": "6ccafd97791ed8c6bf05662708a0745b1d085023"
 }

package/typings/xterm-headless.d.ts

@@ -49,10 +49,19 @@ declare module '@xterm/headless' {
     convertEol?: boolean;
 
     /**
-     * Whether the cursor blinks.
+     * Whether the cursor blinks. The blinking will stop after 5 minutes of idle
+     * time (refreshed by clicking, focusing or the cursor moving). The default
+     * is false.
      */
     cursorBlink?: boolean;
 
+    /**
+     * The interval in milliseconds for the blink attribute. This is the amount
+     * of time text remains visible or hidden before toggling. Set to 0 to
+     * disable blinking. The default is 0.
+     */
+    blinkIntervalDuration?: number;
+
     /**
      * The style of the cursor.
      */
@@ -63,14 +72,6 @@ declare module '@xterm/headless' {
      */
     cursorWidth?: number;
 
-    /**
-     * Whether to draw custom glyphs for block element and box drawing
-     * characters instead of using the font. This should typically result in
-     * better rendering with continuous lines, even when line height and letter
-     * spacing is used. Note that this doesn't work with the DOM renderer which
-     * renders all characters using the font. The default is true.
-     */
-    customGlyphs?: boolean;
     /**
      * Whether input should be disabled.
      */
@@ -81,13 +82,6 @@ declare module '@xterm/headless' {
      */
     drawBoldTextInBrightColors?: boolean;
 
-    /**
-     * The modifier key hold to multiply scroll speed.
-     * @deprecated This option is no longer available and will always use alt.
-     * Setting this will be ignored.
-     */
-    fastScrollModifier?: 'none' | 'alt' | 'ctrl' | 'shift';
-
     /**
      * The spacing in whole pixels between characters.
      */
@@ -142,10 +136,22 @@ declare module '@xterm/headless' {
      */
     minimumContrastRatio?: number;
 
+    /**
+     * When enabled and the terminal is in mouse events mode, mouse click, drag,
+     * and move events are only sent to the underlying application when the alt
+     * key is held. The alt key is not included in the mouse reports sent to the
+     * application. Wheel events are not affected. This allows normal text
+     * selection by default while still supporting application mouse interaction
+     * and scrolling when holding alt. When enabled, this takes precedence over
+     * `macOptionClickForcesSelection`.
+     */
+    mouseEventsRequireAlt?: boolean;
+
     /**
      * Whether to reflow the line containing the cursor when the terminal is
      * resized. Defaults to false, because shells usually handle this
-     * themselves.
+     * themselves. Note that this will not move the cursor position, only the
+     * line contents.
      */
     reflowCursorLine?: boolean;
 
@@ -214,25 +220,6 @@ declare module '@xterm/headless' {
      */
     theme?: ITheme;
 
-    /**
-     * Whether "Windows mode" is enabled. Because Windows backends winpty and
-     * conpty operate by doing line wrapping on their side, xterm.js does not
-     * have access to wrapped lines. When Windows mode is enabled the following
-     * changes will be in effect:
-     *
-     * - Reflow is disabled.
-     * - Lines are assumed to be wrapped if the last character of the line is
-     *   not whitespace.
-     *
-     * When using conpty on Windows 11 version >= 21376, it is recommended to
-     * disable this because native text wrapping sequences are output correctly
-     * thanks to https://github.com/microsoft/terminal/issues/405
-     *
-     * @deprecated Use {@link windowsPty}. This value will be ignored if
-     * windowsPty is set.
-     */
-    windowsMode?: boolean;
-
     /**
      * Compatibility information when the pty is known to be hosted on Windows.
      * Setting this will turn on certain heuristics/workarounds depending on the
@@ -262,6 +249,11 @@ declare module '@xterm/headless' {
      * All features are disabled by default for security reasons.
      */
     windowOptions?: IWindowOptions;
+
+    /**
+     * Enable various VT extensions.
+     */
+    vtExtensions?: IVtExtensions;
   }
 
   /**
@@ -278,6 +270,13 @@ declare module '@xterm/headless' {
      * The number of rows in the terminal.
      */
     rows?: number;
+
+    /**
+     * Whether to show the cursor immediately when the terminal is created.
+     * When false (default), the cursor will not be visible until the terminal
+     * is focused for the first time.
+     */
+    showCursorImmediately?: boolean;
   }
 
   /**
@@ -344,6 +343,51 @@ declare module '@xterm/headless' {
     buildNumber?: number;
   }
 
+  /**
+   * Enable VT extensions that are not part of the core VT specification.
+   */
+  export interface IVtExtensions {
+    /**
+     * Whether the [kitty keyboard protocol][0] (`CSI =|?|>|< u`) is enabled.
+     * When enabled, the terminal will respond to keyboard protocol queries and
+     * allow programs to enable enhanced keyboard reporting. The default is
+     * false.
+     *
+     * [0]: https://sw.kovidgoyal.net/kitty/keyboard-protocol/
+     */
+    kittyKeyboard?: boolean;
+
+    /**
+     * Whether [SGR 221 (not bold) and SGR 222 (not faint) are enabled][0].
+     * These are kitty extensions that allow resetting bold and faint
+     * independently. The default is true.
+     *
+     * [0]: https://sw.kovidgoyal.net/kitty/misc-protocol/
+     */
+    kittySgrBoldFaintControl?: boolean;
+
+    /**
+     * Whether [win32-input-mode][0] (`DECSET 9001`) is enabled. When enabled,
+     * the terminal will allow programs to enable win32 INPUT_RECORD  keyboard
+     * reporting via `CSI ? 9001 h`. The default is false.
+     *
+     * [0]: https://github.com/microsoft/terminal/blob/main/doc/specs/%234999%20-%20Improved%20keyboard%20handling%20in%20Conpty.md
+     */
+    win32InputMode?: boolean;
+
+    /**
+     * Whether [color scheme query and notification][0] (`CSI ? 996 n` and
+     * `DECSET 2031`) is enabled. When enabled, the terminal will respond to
+     * color scheme queries with `CSI ? 997 ; 1 n` (dark) or `CSI ? 997 ; 2 n`
+     * (light) based on the relative luminance of the background and foreground
+     * theme colors. Programs can enable unsolicited notifications via
+     * `CSI ? 2031 h`. The default is true.
+     *
+     * [0]: https://contour-terminal.org/vt-extensions/color-palette-update-notifications/
+     */
+    colorSchemeQuery?: boolean;
+  }
+
   /**
    * A replacement logger for `console`.
    */
@@ -615,21 +659,18 @@ declare module '@xterm/headless' {
     readonly cols: number;
 
     /**
-     * (EXPERIMENTAL) The terminal's current buffer, this might be either the
-     * normal buffer or the alt buffer depending on what's running in the
-     * terminal.
+     * Access to the terminal's normal and alt buffer.
      */
     readonly buffer: IBufferNamespace;
 
     /**
-     * (EXPERIMENTAL) Get all markers registered against the buffer. If the alt
-     * buffer is active this will always return [].
+     * Get all markers registered against the buffer. If the alt buffer is
+     * active this will always return [].
      */
     readonly markers: ReadonlyArray<IMarker>;
 
     /**
-     * (EXPERIMENTAL) Get the parser interface to register
-     * custom escape sequence handlers.
+     * Get the parser interface to register custom escape sequence handlers.
      */
     readonly parser: IParser;
 
@@ -730,6 +771,17 @@ declare module '@xterm/headless' {
      */
     onLineFeed: IEvent<void>;
 
+    /**
+     * Adds an event listener for when rows are _requested_ to be rendered. The
+     * event value contains the start row and end rows of the rendered area
+     * (ranges from `0` to `Terminal.rows - 1`). This differs from the regular
+     * xterm.js in that it doesn't actually do any rendering but requests
+     * rendering from the outside. This is useful for implementing a custom
+     * renderer on top of xterm-headless.
+     * @returns an `IDisposable` to stop listening.
+     */
+    onRender: IEvent<{ start: number, end: number }>;
+
     /**
      * Adds an event listener for when data has been parsed by the terminal,
      * after {@link write} is called. This event is useful to listen for any
@@ -784,12 +836,11 @@ declare module '@xterm/headless' {
     resize(columns: number, rows: number): void;
 
     /**
-     * Adds a marker to the normal buffer and returns it. If the alt buffer is
-     * active, undefined is returned.
+     * Adds a marker to the normal buffer and returns it.
      * @param cursorYOffset The y position offset of the marker from the cursor.
      * @returns The new marker or undefined.
      */
-    registerMarker(cursorYOffset?: number): IMarker | undefined;
+    registerMarker(cursorYOffset?: number): IMarker;
 
     /*
      * Disposes of the terminal, detaching it from the DOM and removing any
@@ -1177,6 +1228,26 @@ declare module '@xterm/headless' {
 
     /** Whether the cell has the default attribute (no color or style). */
     isAttributeDefault(): boolean;
+
+    /** Gets the underline style. */
+    getUnderlineStyle(): number;
+    /** Gets the underline color number. */
+    getUnderlineColor(): number;
+    /** Gets the underline color mode. */
+    getUnderlineColorMode(): number;
+    /** Whether the cell is using the RGB underline color mode. */
+    isUnderlineColorRGB(): boolean;
+    /** Whether the cell is using the palette underline color mode. */
+    isUnderlineColorPalette(): boolean;
+    /** Whether the cell is using the default underline color mode. */
+    isUnderlineColorDefault(): boolean;
+
+    /**
+     * Compares the cell's attributes (colors and styles) with another cell.
+     * This does not compare the cell's content and excludes URL ids and
+     * underline variant offsets.
+     */
+    attributesEquals(other: IBufferCell): boolean;
   }
 
   /**
@@ -1213,12 +1284,12 @@ declare module '@xterm/headless' {
     prefix?: string;
     /**
      * Optional intermediate bytes, must be in range \x20 .. \x2f.
-     * Usable in CSI, DCS and ESC.
+     * Usable in CSI, DCS, ESC and APC.
      */
     intermediates?: string;
     /**
      * Final byte, must be in range \x40 .. \x7e for CSI and DCS,
-     * \x30 .. \x7e for ESC.
+     * \x30 .. \x7e for ESC and APC.
      */
     final: string;
   }
@@ -1265,7 +1336,7 @@ declare module '@xterm/headless' {
      * @param id Specifies the function identifier under which the callback
      * gets registered, e.g. {intermediates: '%' final: 'G'} for
      * default charset selection.
-     * @param callback The function to handle the sequence.
+     * @param handler The function to handle the sequence.
      * Return true if the sequence was handled; false if we should try
      * a previous handler (set by addEscHandler or setEscHandler).
      * The most recently added handler is tried first.
@@ -1290,6 +1361,24 @@ declare module '@xterm/headless' {
      * @returns An IDisposable you can call to remove this handler.
      */
     registerOscHandler(ident: number, callback: (data: string) => boolean): IDisposable;
+
+    /**
+     * Adds a handler for APC escape sequences.
+     * @param id Specifies the function identifier under which the callback
+     * gets registered, e.g. {final: 'G'} for Kitty graphics protocol.
+     * @param callback The function to handle the sequence. Note that the
+     * function will only be called once if the sequence finished successfully.
+     * There is currently no way to intercept smaller data chunks, data chunks
+     * will be stored up until the sequence is finished. Since APC sequences are
+     * not limited by the amount of data this might impose a problem for big
+     * payloads. Currently xterm.js limits APC payload to 10 MB which should
+     * give enough room for most use cases. The callback is called with APC data
+     * string (excluding the identifier character). Return true if the sequence
+     * was handled; false if we should try a previous handler. The most recently
+     * added handler is tried first.
+     * @returns An IDisposable you can call to remove this handler.
+     */
+    registerApcHandler(id: IFunctionIdentifier, callback: (data: string) => boolean): IDisposable;
   }
 
   /**
@@ -1370,6 +1459,10 @@ declare module '@xterm/headless' {
      * Send FocusIn/FocusOut events: `CSI ? 1 0 0 4 h`
      */
     readonly sendFocusMode: boolean;
+    /**
+     * Show Cursor (DECTCEM): `CSI ? 2 5 h`
+     */
+    readonly showCursor: boolean;
     /**
      * Synchronized Output Mode: `CSI ? 2 0 2 6 h`
      *
@@ -1377,6 +1470,13 @@ declare module '@xterm/headless' {
      * disabled, allowing for atomic screen updates without tearing.
      */
     readonly synchronizedOutputMode: boolean;
+    /**
+     * Win32 Input Mode: `CSI ? 9 0 0 1 h`
+     *
+     * When enabled, keyboard input is sent as Win32 INPUT_RECORD format:
+     * `CSI Vk ; Sc ; Uc ; Kd ; Cs ; Rc _`
+     */
+    readonly win32InputMode: boolean;
     /**
      * Auto-Wrap Mode (DECAWM): `CSI ? 7 h`
      */