Expose a documentOverride setting

This lets the embedder choose which Document object to use for creating
elements, adding event listeners, etc. The reason this exists is because
when working with multiple windows it can be convenient to create all
elements under the primary window to make instanceof usage consistent.

See microsoft/vscode#195595

src/browser/Terminal.ts

@@ -398,6 +398,9 @@ export class Terminal extends CoreTerminal implements ITerminal {
     }
 
     this._document = parent.ownerDocument!;
+    if (this.options.documentOverride && this.options.documentOverride instanceof Document) {
+      this._document = this.optionsService.rawOptions.documentOverride as Document;
+    }
 
     // Create main element container
     this.element = this._document.createElement('div');

src/common/services/OptionsService.ts

@@ -18,6 +18,7 @@ export const DEFAULT_OPTIONS: Readonly<Required<ITerminalOptions>> = {
   cursorInactiveStyle: 'outline',
   customGlyphs: true,
   drawBoldTextInBrightColors: true,
+  documentOverride: null,
   fastScrollModifier: 'alt',
   fastScrollSensitivity: 5,
   fontFamily: 'courier-new, courier, monospace',

src/common/services/Services.ts

@@ -217,6 +217,7 @@ export interface ITerminalOptions {
   cursorInactiveStyle?: CursorInactiveStyle;
   customGlyphs?: boolean;
   disableStdin?: boolean;
+  documentOverride?: any | null;
   drawBoldTextInBrightColors?: boolean;
   fastScrollModifier?: 'none' | 'alt' | 'ctrl' | 'shift';
   fastScrollSensitivity?: number;

typings/xterm.d.ts

@@ -89,6 +89,17 @@ declare module 'xterm' {
      */
     disableStdin?: boolean;
 
+    /**
+     * A {@link Document} to use instead of the one that xterm.js was attached
+     * to. The purpose of this is to improve support in multi-window
+     * applications where HTML elements may be references across multiple
+     * windows which can cause problems with `instanceof`.
+     *
+     * The type is `any` because using `Document` can cause TS to have
+     * performance/compiler problems.
+     */
+    documentOverride?: any | null;
+
     /**
      * Whether to draw bold text in bright colors. The default is true.
      */