Merge pull request #5840 from xtermjs/fix_apc

changes in APC handling

Author: Tyriar

addons/addon-image/src/ImageAddon.ts

@@ -16,6 +16,47 @@ 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,
@@ -166,7 +207,7 @@ export class ImageAddon implements ITerminalAddon, IImageApi {
       this._disposeLater(
         kittyStorage,
         kittyHandler,
-        terminal._core._inputHandler._parser.registerApcHandler(0x47, kittyHandler)
+        terminal._core._inputHandler._parser.registerApcHandler({ final: 'G' }, kittyHandler)
       );
     }
   }

bin/extract_vtfeatures.js

@@ -57,6 +57,9 @@ xterm.js version: {{version}}
 {{#CSI.length}}
 - [CSI](#csi)
 {{/CSI.length}}
+{{#APC.length}}
+- [APC](#apc)
+{{/APC.length}}
 {{#DCS.length}}
 - [DCS](#dcs)
 {{/DCS.length}}
@@ -80,8 +83,9 @@ This document lists xterm.js' support of terminal sequences. The sequences are g
 - CSI - Control Sequence Introducer: sequence starting with \`ESC [\` (7bit) or CSI (\`\\x9B\`, 8bit)
 - DCS - Device Control String: sequence starting with \`ESC P\` (7bit) or DCS (\`\\x90\`, 8bit)
 - OSC - Operating System Command: sequence starting with \`ESC ]\` (7bit) or OSC (\`\\x9D\`, 8bit)
+- APC - Application Program Command: sequence starting with \`ESC _\` (7bit) or OSC (\`\\x9F\`, 8bit)
 
-Application Program Command (APC), Privacy Message (PM) and Start of String (SOS) are recognized but not supported,
+Privacy Message (PM) and Start of String (SOS) are recognized but not supported,
 any sequence of these types will be silently ignored. They are also not hookable by the API.
 
 Note that the list only marks sequences implemented in xterm.js' core codebase as supported. Missing sequences are either
@@ -178,6 +182,33 @@ To denote the sequences the tables use the same abbreviations as xterm does:
 {{/CSI.length}}
 
 
+{{#APC.length}}
+## APC
+
+| Mnemonic | Name | Sequence | Short Description | Support |
+| -------- | ---- | -------- | ----------------- | ------- |
+{{#APC}}
+| {{mnemonic}} | {{name}} | \`{{sequence}}\` | {{{shortDescription}}} {{#longDescription.length}}_[more](#{{longTarget}}){: .link-details}_{{/longDescription.length}} | {{{status}}} |
+{{/APC}}
+
+{{#APC.hasLongDescriptions}}
+{{#APC}}
+{{#longDescription.length}}
+<section class="sequence-details">
+
+### {{name}}
+{{#longDescription}}
+{{{.}}}
+{{/longDescription}}
+
+</section>
+{{/longDescription.length}}
+{{/APC}}
+{{/APC.hasLongDescriptions}}
+
+{{/APC.length}}
+
+
 {{#DCS.length}}
 ## DCS
 

package-lock.json

@@ -66,7 +66,7 @@
     "benchmark-baseline": "NODE_PATH=./out xterm-benchmark -r 5 -c test/benchmark/benchmark.json --baseline out-test/benchmark/*benchmark.js",
     "benchmark-eval": "NODE_PATH=./out xterm-benchmark -r 5 -c test/benchmark/benchmark.json --eval out-test/benchmark/*benchmark.js",
     "clean": "rm -rf lib out addons/*/lib addons/*/out",
-    "vtfeatures": "node bin/extract_vtfeatures.js src/**/*.ts src/*.ts",
+    "vtfeatures": "node bin/extract_vtfeatures.js src/*/*.ts src/*/*/*.ts src/*.ts addons/**/src/*.ts",
     "prepackage": "npm run build",
     "package": "webpack",
     "postpackage": "npm run esbuild-package",

package.json

@@ -107,7 +107,7 @@ export class MockTerminal implements ITerminal {
   public registerOscHandler(ident: number, callback: (data: string) => boolean | Promise<boolean>): IDisposable {
     throw new Error('Method not implemented.');
   }
-  public registerApcHandler(ident: number, callback: (data: string) => boolean | Promise<boolean>): IDisposable {
+  public registerApcHandler(id: IFunctionIdentifier, callback: (data: string) => boolean | Promise<boolean>): IDisposable {
     throw new Error('Method not implemented.');
   }
   public registerLinkProvider(linkProvider: ILinkProvider): IDisposable {

src/browser/TestUtils.test.ts

@@ -243,8 +243,8 @@ export abstract class CoreTerminal extends Disposable implements ICoreTerminal {
   }
 
   /** Add handler for APC escape sequence. See xterm.d.ts for details. */
-  public registerApcHandler(ident: number, callback: (data: string) => boolean | Promise<boolean>): IDisposable {
-    return this._inputHandler.registerApcHandler(ident, callback);
+  public registerApcHandler(id: IFunctionIdentifier, callback: (data: string) => boolean | Promise<boolean>): IDisposable {
+    return this._inputHandler.registerApcHandler(id, callback);
   }
 
   protected _setup(): void {

src/common/CoreTerminal.ts

@@ -30,28 +30,9 @@ import { XTERM_VERSION } from 'common/Version';
  */
 const GLEVEL: { [key: string]: number } = { '(': 0, ')': 1, '*': 2, '+': 3, '-': 1, '.': 2 };
 
-/**
- * VT commands done by the parser - FIXME: move this to the parser?
- */
-// @vt: #Y   ESC   CSI   "Control Sequence Introducer"   "ESC ["   "Start of a CSI sequence."
-// @vt: #Y   ESC   OSC   "Operating System Command"      "ESC ]"   "Start of an OSC sequence."
-// @vt: #Y   ESC   DCS   "Device Control String"         "ESC P"   "Start of a DCS sequence."
-// @vt: #Y   ESC   ST    "String Terminator"             "ESC \"   "Terminator used for string type sequences."
-// @vt: #Y   ESC   PM    "Privacy Message"               "ESC ^"   "Start of a privacy message."
-// @vt: #Y   ESC   APC   "Application Program Command"   "ESC _"   "Start of an APC sequence."
-// @vt: #Y   C1    CSI   "Control Sequence Introducer"   "\x9B"    "Start of a CSI sequence."
-// @vt: #Y   C1    OSC   "Operating System Command"      "\x9D"    "Start of an OSC sequence."
-// @vt: #Y   C1    DCS   "Device Control String"         "\x90"    "Start of a DCS sequence."
-// @vt: #Y   C1    ST    "String Terminator"             "\x9C"    "Terminator used for string type sequences."
-// @vt: #Y   C1    PM    "Privacy Message"               "\x9E"    "Start of a privacy message."
-// @vt: #Y   C1    APC   "Application Program Command"   "\x9F"    "Start of an APC sequence."
-// @vt: #Y   C0    NUL   "Null"                          "\0, \x00"  "NUL is ignored."
-// @vt: #Y   C0    ESC   "Escape"                        "\e, \x1B"  "Start of a sequence. Cancels any other sequence."
-
 /**
  * Document xterm VT features here that are currently unsupported
  */
-// @vt: #E[Supported via @xterm/addon-image.]  DCS   SIXEL       "SIXEL Graphics"          "DCS Ps ; Ps ; Ps ; q 	Pt ST"  "Draw SIXEL image."
 // @vt: #N  DCS   DECUDK      "User Defined Keys"       "DCS Ps ; Ps \| Pt ST"           "Definitions for user-defined keys."
 // @vt: #N  DCS   XTGETTCAP   "Request Terminfo String" "DCS + q Pt ST"                 "Request Terminfo String."
 // @vt: #N  DCS   XTSETTCAP   "Set Terminfo Data"       "DCS + p Pt ST"                 "Set Terminfo Data."
@@ -211,6 +192,9 @@ export class InputHandler extends Disposable implements IInputHandler {
       }
       this._logService.debug('Unknown DCS code: ', { identifier: this._parser.identToString(ident), action, payload });
     });
+    this._parser.setApcHandlerFallback((ident, action, payload) => {
+      this._logService.debug('Unknown APC code: ', { identifier: this._parser.identToString(ident), action, payload });
+    });
 
     /**
      * print handler
@@ -729,8 +713,8 @@ export class InputHandler extends Disposable implements IInputHandler {
   /**
    * Forward registerApcHandler from parser.
    */
-  public registerApcHandler(ident: number, callback: (data: string) => boolean | Promise<boolean>): IDisposable {
-    return this._parser.registerApcHandler(ident, new ApcHandler(callback));
+  public registerApcHandler(id: IFunctionIdentifier, callback: (data: string) => boolean | Promise<boolean>): IDisposable {
+    return this._parser.registerApcHandler(id, new ApcHandler(callback));
   }
 
   /**

src/common/InputHandler.ts

@@ -22,7 +22,7 @@ export interface ICoreTerminal {
   registerDcsHandler(id: IFunctionIdentifier, callback: (data: string, param: IParams) => boolean | Promise<boolean>): IDisposable;
   registerEscHandler(id: IFunctionIdentifier, callback: () => boolean | Promise<boolean>): IDisposable;
   registerOscHandler(ident: number, callback: (data: string) => boolean | Promise<boolean>): IDisposable;
-  registerApcHandler(ident: number, callback: (data: string) => boolean | Promise<boolean>): IDisposable;
+  registerApcHandler(id: IFunctionIdentifier, callback: (data: string) => boolean | Promise<boolean>): IDisposable;
 }
 
 export interface IDisposable {
@@ -476,7 +476,7 @@ export interface IInputHandler {
   registerDcsHandler(id: IFunctionIdentifier, callback: (data: string, param: IParams) => boolean | Promise<boolean>): IDisposable;
   registerEscHandler(id: IFunctionIdentifier, callback: () => boolean | Promise<boolean>): IDisposable;
   registerOscHandler(ident: number, callback: (data: string) => boolean | Promise<boolean>): IDisposable;
-  registerApcHandler(ident: number, callback: (data: string) => boolean | Promise<boolean>): IDisposable;
+  registerApcHandler(id: IFunctionIdentifier, callback: (data: string) => boolean | Promise<boolean>): IDisposable;
 
   /** C0 BEL */ bell(): boolean;
   /** C0 LF */ lineFeed(): boolean;