Add support to ANSI OSC52

Add support to ANSI OSC52 sequence to manipulate selection and clipboard
data. The sequence specs supports multiple clipboard selections but we
only support the common ones, system and primary clipboard selections.

This adds a new event listener to the common terminal module
`onClipboard` to allow external implementations to hook into it.

The addon uses the browser Clipboard API to read/write from and to the
clipboard. The default `ClipboardProvider` uses the browser Clipboard
API. This means it only supports read/write to and from the system
clipboard.

Reference: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Operating-System-Commands
Fixes: xtermjs#3260
Signed-off-by: Ayman Bagabas <ayman.bagabas@gmail.com>

src/browser/Terminal.ts

@@ -46,7 +46,7 @@ import { CoreTerminal } from 'common/CoreTerminal';
 import { EventEmitter, IEvent, forwardEvent } from 'common/EventEmitter';
 import { MutableDisposable, toDisposable } from 'common/Lifecycle';
 import * as Browser from 'common/Platform';
-import { ColorRequestType, CoreMouseAction, CoreMouseButton, CoreMouseEventType, IColorEvent, ITerminalOptions, KeyboardResultType, ScrollSource, SpecialColorIndex } from 'common/Types';
+import { ColorRequestType, CoreMouseAction, CoreMouseButton, CoreMouseEventType, IClipboardEvent, IColorEvent, ITerminalOptions, KeyboardResultType, ScrollSource, SpecialColorIndex } from 'common/Types';
 import { DEFAULT_ATTR_DATA } from 'common/buffer/BufferLine';
 import { IBuffer } from 'common/buffer/Types';
 import { C0, C1_ESCAPED } from 'common/data/EscapeSequences';
@@ -54,7 +54,7 @@ import { evaluateKeyboardEvent } from 'common/input/Keyboard';
 import { toRgbString } from 'common/input/XParseColor';
 import { DecorationService } from 'common/services/DecorationService';
 import { IDecorationService } from 'common/services/Services';
-import { IDecoration, IDecorationOptions, IDisposable, ILinkProvider, IMarker } from 'xterm';
+import { IDecoration, IDecorationOptions, IDisposable, ILinkProvider, IMarker, IClipboardProvider } from 'xterm';
 import { WindowsOptionsReportType } from '../common/InputHandler';
 import { AccessibilityManager } from './AccessibilityManager';
 
@@ -119,6 +119,7 @@ export class Terminal extends CoreTerminal implements ITerminal {
   public viewport: IViewport | undefined;
   private _compositionHelper: ICompositionHelper | undefined;
   private _accessibilityManager: MutableDisposable<AccessibilityManager> = this.register(new MutableDisposable());
+  private _clipboardProvider: IClipboardProvider | undefined;
 
   private readonly _onCursorMove = this.register(new EventEmitter<void>());
   public readonly onCursorMove = this._onCursorMove.event;
@@ -163,6 +164,7 @@ export class Terminal extends CoreTerminal implements ITerminal {
     this.register(this._inputHandler.onRequestReset(() => this.reset()));
     this.register(this._inputHandler.onRequestWindowsOptionsReport(type => this._reportWindowsOptions(type)));
     this.register(this._inputHandler.onColor((event) => this._handleColorEvent(event)));
+    this.register(this._inputHandler.onClipboard((event) => this._handleClipboardEvent(event)));
     this.register(forwardEvent(this._inputHandler.onCursorMove, this._onCursorMove));
     this.register(forwardEvent(this._inputHandler.onTitleChange, this._onTitleChange));
     this.register(forwardEvent(this._inputHandler.onA11yChar, this._onA11yCharEmitter));
@@ -881,6 +883,14 @@ export class Terminal extends CoreTerminal implements ITerminal {
     return this.linkifier2.registerLinkProvider(linkProvider);
   }
 
+  public registerClipboardProvider(provider: IClipboardProvider): void {
+    this._clipboardProvider = provider;
+  }
+
+  public deregisterClipboardProvider(): void {
+    this._clipboardProvider = undefined;
+  }
+
   public registerCharacterJoiner(handler: CharacterJoinerHandler): number {
     if (!this._characterJoinerService) {
       throw new Error('Terminal must be opened first');
@@ -1281,6 +1291,18 @@ export class Terminal extends CoreTerminal implements ITerminal {
     }
   }
 
+  private _handleClipboardEvent(ev: IClipboardEvent): void {
+    if (!this._clipboardProvider) {
+      return;
+    }
+    if (ev.data === '?') {
+      this._clipboardProvider.readText(ev.selection).then(data =>
+        this.coreService.triggerDataEvent(data));
+      return;
+    }
+    this._clipboardProvider.writeText(ev.selection, ev.data);
+  }
+
   // TODO: Remove cancel function and cancelEvents option
   public cancel(ev: Event, force?: boolean): boolean | undefined {
     if (!this.options.cancelEvents && !force) {

src/browser/TestUtils.test.ts

@@ -3,7 +3,7 @@
  * @license MIT
  */
 
-import { IDisposable, IMarker, ILinkProvider, IDecorationOptions, IDecoration } from 'xterm';
+import { IDisposable, IMarker, ILinkProvider, IDecorationOptions, IDecoration, IClipboardProvider } from 'xterm';
 import { IEvent, EventEmitter } from 'common/EventEmitter';
 import { ICharacterJoinerService, ICharSizeService, ICoreBrowserService, IMouseService, IRenderService, ISelectionService, IThemeService } from 'browser/services/Services';
 import { IRenderDimensions, IRenderer, IRequestRedrawEvent } from 'browser/renderer/shared/Types';
@@ -104,6 +104,12 @@ export class MockTerminal implements ITerminal {
   public registerDecoration(decorationOptions: IDecorationOptions): IDecoration | undefined {
     throw new Error('Method not implemented.');
   }
+  public registerClipboardProvider(provider: IClipboardProvider): void {
+    throw new Error('Method not implemented.');
+  }
+  public deregisterClipboardProvider(): void {
+    throw new Error('Method not implemented.');
+  }
   public hasSelection(): boolean {
     throw new Error('Method not implemented.');
   }

src/browser/public/Terminal.ts

@@ -13,7 +13,7 @@ import { AddonManager } from 'common/public/AddonManager';
 import { BufferNamespaceApi } from 'common/public/BufferNamespaceApi';
 import { ParserApi } from 'common/public/ParserApi';
 import { UnicodeApi } from 'common/public/UnicodeApi';
-import { IBufferNamespace as IBufferNamespaceApi, IDecoration, IDecorationOptions, IDisposable, ILinkProvider, ILocalizableStrings, IMarker, IModes, IParser, ITerminalAddon, Terminal as ITerminalApi, ITerminalInitOnlyOptions, IUnicodeHandling } from 'xterm';
+import { IBufferNamespace as IBufferNamespaceApi, IClipboardProvider, IDecoration, IDecorationOptions, IDisposable, ILinkProvider, ILocalizableStrings, IMarker, IModes, IParser, ITerminalAddon, Terminal as ITerminalApi, ITerminalInitOnlyOptions, IUnicodeHandling } from 'xterm';
 
 /**
  * The set of options that only have an effect when set in the Terminal constructor.
@@ -168,6 +168,12 @@ export class Terminal extends Disposable implements ITerminalApi {
     this._verifyPositiveIntegers(decorationOptions.x ?? 0, decorationOptions.width ?? 0, decorationOptions.height ?? 0);
     return this._core.registerDecoration(decorationOptions);
   }
+  public registerClipboardProvider(provider: IClipboardProvider): void {
+    this._core.registerClipboardProvider(provider);
+  }
+  public deregisterClipboardProvider(): void {
+    this._core.deregisterClipboardProvider();
+  }
   public hasSelection(): boolean {
     return this._core.hasSelection();
   }

src/common/InputHandler.test.ts

@@ -5,7 +5,7 @@
 
 import { assert } from 'chai';
 import { InputHandler } from 'common/InputHandler';
-import { IBufferLine, IAttributeData, IColorEvent, ColorIndex, ColorRequestType, SpecialColorIndex } from 'common/Types';
+import { IBufferLine, IAttributeData, IColorEvent, ColorIndex, ColorRequestType, SpecialColorIndex, IClipboardEvent, ClipboardEventType } from 'common/Types';
 import { DEFAULT_ATTR_DATA } from 'common/buffer/BufferLine';
 import { CellData } from 'common/buffer/CellData';
 import { Attributes, BgFlags, UnderlineStyle } from 'common/buffer/Constants';
@@ -17,7 +17,7 @@ import { DEFAULT_OPTIONS } from 'common/services/OptionsService';
 import { clone } from 'common/Clone';
 import { BufferService } from 'common/services/BufferService';
 import { CoreService } from 'common/services/CoreService';
-
+import { ClipboardSelection } from 'xterm';
 
 function getCursor(bufferService: IBufferService): number[] {
   return [
@@ -1982,6 +1982,88 @@ describe('InputHandler', () => {
       assert.deepEqual(stack, [[{ type: ColorRequestType.SET, index: 0, color: [170, 187, 204] }, { type: ColorRequestType.SET, index: 123, color: [0, 17, 34] }]]);
       stack.length = 0;
     });
+    describe('52: manipulate selection data', async () => {
+      const testDataRaw = 'hello world';
+      const testDataB64 = 'aGVsbG8gd29ybGQ=';
+      optionsService.options.allowClipboardAccess = true;
+      const stack: IClipboardEvent[] = [];
+      inputHandler.onClipboard(ev => stack.push(ev));
+      await inputHandler.parseP(`\x1b]52;c;\x07`);
+      await inputHandler.parseP(`\x1b]52;c;${testDataRaw}\x07`);
+      await inputHandler.parseP(`\x1b]52;c;${testDataB64}\x07`);
+      await inputHandler.parseP(`\x1b]52;c;${testDataB64}invalid\x07`);
+      await inputHandler.parseP(`\x1b]52;c;!\x07`);
+      await inputHandler.parseP(`\x1b]52;c;?\x07`);
+      await inputHandler.parseP(`\x1b]52;p;\x07`);
+      await inputHandler.parseP(`\x1b]52;p;${testDataRaw}\x07`);
+      await inputHandler.parseP(`\x1b]52;p;${testDataB64}\x07`);
+      await inputHandler.parseP(`\x1b]52;p;${testDataB64}invalid\x07`);
+      await inputHandler.parseP(`\x1b]52;p;!\x07`);
+      await inputHandler.parseP(`\x1b]52;p;?\x07`);
+      assert.deepEqual(stack, [
+        {
+          type: ClipboardEventType.SET,
+          selection: ClipboardSelection.SYSTEM,
+          data: ''
+        },
+        {
+          type: ClipboardEventType.SET,
+          selection: ClipboardSelection.SYSTEM,
+          data: testDataRaw
+        },
+        {
+          type: ClipboardEventType.SET,
+          selection: ClipboardSelection.SYSTEM,
+          data: testDataB64
+        },
+        {
+          type: ClipboardEventType.SET,
+          selection: ClipboardSelection.SYSTEM,
+          data: testDataB64+'invalid'
+        },
+        {
+          type: ClipboardEventType.SET,
+          selection: ClipboardSelection.SYSTEM,
+          data: '!'
+        },
+        {
+          type: ClipboardEventType.REPORT,
+          selection: ClipboardSelection.SYSTEM,
+          data: '?'
+        },
+        {
+          type: ClipboardEventType.SET,
+          selection: ClipboardSelection.PRIMARY,
+          data: ''
+        },
+        {
+          type: ClipboardEventType.SET,
+          selection: ClipboardSelection.PRIMARY,
+          data: testDataRaw
+        },
+        {
+          type: ClipboardEventType.SET,
+          selection: ClipboardSelection.PRIMARY,
+          data: testDataB64
+        },
+        {
+          type: ClipboardEventType.SET,
+          selection: ClipboardSelection.PRIMARY,
+          data: testDataB64+'invalid'
+        },
+        {
+          type: ClipboardEventType.SET,
+          selection: ClipboardSelection.PRIMARY,
+          data: '!'
+        },
+        {
+          type: ClipboardEventType.REPORT,
+          selection: ClipboardSelection.PRIMARY,
+          data: '?'
+        }
+      ]);
+      stack.length = 0;
+    });
     it('104: restore events', async () => {
       const stack: IColorEvent[] = [];
       inputHandler.onColor(ev => stack.push(ev));
@@ -1994,7 +2076,7 @@ describe('InputHandler', () => {
       stack.length = 0;
       // full ANSI table restore
       await inputHandler.parseP('\x1b]104\x07');
-      assert.deepEqual(stack, [[{ type: ColorRequestType.RESTORE}]]);
+      assert.deepEqual(stack, [[{ type: ColorRequestType.RESTORE }]]);
     });
 
     it('10: FG set & query events', async () => {

src/common/InputHandler.ts

@@ -4,7 +4,7 @@
  * @license MIT
  */
 
-import { IInputHandler, IAttributeData, IDisposable, IWindowOptions, IColorEvent, IParseStack, ColorIndex, ColorRequestType, SpecialColorIndex } from 'common/Types';
+import { IInputHandler, IAttributeData, IDisposable, IWindowOptions, IColorEvent, IParseStack, ColorIndex, ColorRequestType, SpecialColorIndex, IClipboardEvent, ClipboardEventType } from 'common/Types';
 import { C0, C1 } from 'common/data/EscapeSequences';
 import { CHARSETS, DEFAULT_CHARSET } from 'common/data/Charsets';
 import { EscapeSequenceParser } from 'common/parser/EscapeSequenceParser';
@@ -22,6 +22,7 @@ import { OscHandler } from 'common/parser/OscParser';
 import { DcsHandler } from 'common/parser/DcsParser';
 import { IBuffer } from 'common/buffer/Types';
 import { parseColor } from 'common/input/XParseColor';
+import { ClipboardSelection } from 'xterm';
 
 /**
  * Map collect to glevel. Used in `selectCharset`.
@@ -159,6 +160,8 @@ export class InputHandler extends Disposable implements IInputHandler {
   public readonly onTitleChange = this._onTitleChange.event;
   private readonly _onColor = this.register(new EventEmitter<IColorEvent>());
   public readonly onColor = this._onColor.event;
+  private readonly _onClipboard = this.register(new EventEmitter<IClipboardEvent>());
+  public readonly onClipboard = this._onClipboard.event;
 
   private _parseStack: IParseStack = {
     paused: false,
@@ -320,6 +323,7 @@ export class InputHandler extends Disposable implements IInputHandler {
     //  50 - Set Font to Pt.
     //  51 - reserved for Emacs shell.
     //  52 - Manipulate Selection Data.
+    this._parser.registerOscHandler(52, new OscHandler(data => this.setOrReportClipboard(data)));
     // 104 ; c - Reset Color Number c.
     this._parser.registerOscHandler(104, new OscHandler(data => this.restoreIndexedColor(data)));
     // 105 ; c - Reset Special Color Number c.
@@ -3081,6 +3085,60 @@ export class InputHandler extends Disposable implements IInputHandler {
     return this._setOrReportSpecialColor(data, 2);
   }
 
+  private _setOrReportClipboard(data: string): boolean {
+    if (!this._optionsService.options.allowClipboardAccess) {
+      return true;
+    }
+    const args = data.split(';');
+    if (args.length < 2) {
+      return true;
+    }
+    const pc = args[0];
+    const pd = args[1];
+    if (pd.length === 0) {
+      return true;
+    }
+    switch (pc) {
+      case ClipboardSelection.SYSTEM:
+      case ClipboardSelection.PRIMARY:
+        this._onClipboard.fire({
+          type: pd === '?' ? ClipboardEventType.REPORT : ClipboardEventType.SET,
+          selection: pc,
+          data: pd
+        });
+        break;
+    }
+    return true;
+  }
+
+  /**
+   * OSC 52 ; <selection name> ; <base64 data>|<?> ST - set or query selection and clipboard data
+   *
+   * Test case:
+   *
+   * ```sh
+   * printf "\e]52;c;%s\a" "$(echo -n "Hello, World" | base64)"
+   * ```
+   *
+   * @vt: #Y    OSC    52    "Manipulate Selection Data"   "OSC 52 ; Pc ; Pd BEL" "Set or query selection and clipboard data."
+   * Pc is the selection name. Can be one of:
+   * - `c` - clipboard
+   * - `p` - primary
+   * - `q` - secondary
+   * - `s` - select
+   * - `0-7` - cut-buffers 0-7
+   *
+   * Only the `c` selection (clipboard) is supported by xterm.js. The browser
+   * Clipboard API only supports the clipboard selection.
+   *
+   * Pd is the base64 encoded data.
+   * If Pd is `?`, the terminal returns the current clipboard contents.
+   * If Pd is neither base64 encoded nor `?`, then the clipboard is cleared.
+   */
+  public setOrReportClipboard(data: string): boolean {
+    return this._setOrReportClipboard(data);
+  }
+
   /**
    * OSC 104 ; <num> ST - restore ANSI color <num>
    *

src/common/Types.d.ts

@@ -9,7 +9,7 @@ import { Attributes, UnderlineStyle } from 'common/buffer/Constants'; // eslint-
 import { IBufferSet } from 'common/buffer/Types';
 import { IParams } from 'common/parser/Types';
 import { ICoreMouseService, ICoreService, IOptionsService, IUnicodeService } from 'common/services/Services';
-import { IFunctionIdentifier, ITerminalOptions as IPublicTerminalOptions } from 'xterm';
+import { ClipboardSelection as ClipboardSelection, IFunctionIdentifier, ITerminalOptions as IPublicTerminalOptions } from 'xterm';
 
 export interface ICoreTerminal {
   coreMouseService: ICoreMouseService;
@@ -445,6 +445,16 @@ export interface IColorRestoreRequest {
 }
 export type IColorEvent = (IColorReportRequest | IColorSetRequest | IColorRestoreRequest)[];
 
+export const enum ClipboardEventType {
+  REPORT = 0,
+  SET = 1
+}
+
+export interface IClipboardEvent {
+  type: ClipboardEventType;
+  selection: ClipboardSelection;
+  data: string;
+}
 
 /**
  * Calls the parser and handles actions generated by the parser.
@@ -515,6 +525,7 @@ export interface IInputHandler {
   /** OSC 10 */ setOrReportFgColor(data: string): boolean;
   /** OSC 11 */ setOrReportBgColor(data: string): boolean;
   /** OSC 12 */ setOrReportCursorColor(data: string): boolean;
+  /** OSC 52 */ setOrReportClipboard(data: string): boolean;
   /** OSC 104 */ restoreIndexedColor(data: string): boolean;
   /** OSC 110 */ restoreFgColor(data: string): boolean;
   /** OSC 111 */ restoreBgColor(data: string): boolean;

src/common/services/OptionsService.ts

@@ -52,7 +52,8 @@ export const DEFAULT_OPTIONS: Readonly<Required<ITerminalOptions>> = {
   convertEol: false,
   termName: 'xterm',
   cancelEvents: false,
-  overviewRulerWidth: 0
+  overviewRulerWidth: 0,
+  allowClipboardAccess: false
 };
 
 const FONT_WEIGHT_OPTIONS: Extract<FontWeight, string>[] = ['normal', 'bold', '100', '200', '300', '400', '500', '600', '700', '800', '900'];
@@ -160,7 +161,7 @@ export class OptionsService extends Disposable implements IOptionsService {
         break;
       case 'cursorWidth':
         value = Math.floor(value);
-        // Fall through for bounds check
+      // Fall through for bounds check
       case 'lineHeight':
       case 'tabStopWidth':
         if (value < 1) {

src/common/services/Services.ts

@@ -206,6 +206,7 @@ export type FontWeight = 'normal' | 'bold' | '100' | '200' | '300' | '400' | '50
 export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'off';
 
 export interface ITerminalOptions {
+  allowClipboardAccess?: boolean;
   allowProposedApi?: boolean;
   allowTransparency?: boolean;
   altClickMovesCursor?: boolean;