From 41c62288f055a615302fa7fa95ee7f4b140496a4 Mon Sep 17 00:00:00 2001
From: Daniel Imms <2193314+Tyriar@users.noreply.github.com>
Date: Fri, 13 Oct 2023 13:41:53 -0700
Subject: [PATCH] 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               |  3 +++
 src/common/services/OptionsService.ts |  1 +
 src/common/services/Services.ts       |  1 +
 typings/xterm.d.ts                    | 11 +++++++++++
 4 files changed, 16 insertions(+)

diff --git a/src/browser/Terminal.ts b/src/browser/Terminal.ts
index 18af3e4e2a..621ee44c53 100644
--- a/src/browser/Terminal.ts
+++ b/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');
diff --git a/src/common/services/OptionsService.ts b/src/common/services/OptionsService.ts
index 3c572445ed..eb9dbfa8c2 100644
--- a/src/common/services/OptionsService.ts
+++ b/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',
diff --git a/src/common/services/Services.ts b/src/common/services/Services.ts
index 52c2a79fae..6ac73e37a9 100644
--- a/src/common/services/Services.ts
+++ b/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;
diff --git a/typings/xterm.d.ts b/typings/xterm.d.ts
index 3f603b9e19..b8028a181e 100644
--- a/typings/xterm.d.ts
+++ b/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.
      */