feat: add focusOnOpen option to Terminal (#2)

Add a focusOnOpen boolean option (default: true) that controls whether
the terminal automatically focuses itself when open() is called.
Setting it to false lets embedders open a terminal in the background
without stealing keyboard focus from another element.

Resolves coder#100.


Inspired-by: coder#149

Co-authored-by: Sauyon Lee <git@sjle.co>

Author: diegosouzapw

lib/interfaces.ts

@@ -19,6 +19,9 @@ export interface ITerminalOptions {
   convertEol?: boolean; // Convert \n to \r\n (default: false)
   disableStdin?: boolean; // Disable keyboard input (default: false)
 
+  // Focus options
+  focusOnOpen?: boolean; // Auto-focus terminal on open (default: true)
+
   // Scrolling options
   smoothScrollDuration?: number; // Duration in ms for smooth scroll animation (default: 100, 0 = instant)
 

lib/terminal.test.ts

@@ -2989,4 +2989,35 @@ describe('Synchronous open()', () => {
 
     term.dispose();
   });
+
+  test('focusOnOpen: false prevents auto-focus on open', async () => {
+    if (!container) return;
+
+    // Focus a different element first
+    const other = document.createElement('input');
+    document.body.appendChild(other);
+    other.focus();
+    expect(document.activeElement).toBe(other);
+
+    const term = await createIsolatedTerminal({ focusOnOpen: false });
+    term.open(container);
+
+    // The terminal should NOT have stolen focus
+    expect(document.activeElement).toBe(other);
+
+    other.remove();
+    term.dispose();
+  });
+
+  test('focusOnOpen defaults to true', async () => {
+    if (!container) return;
+
+    const term = await createIsolatedTerminal();
+    term.open(container);
+
+    // The terminal should have taken focus
+    expect(document.activeElement).toBe(container);
+
+    term.dispose();
+  });
 });

lib/terminal.ts

@@ -151,6 +151,7 @@ export class Terminal implements ITerminalCore {
       convertEol: options.convertEol ?? false,
       disableStdin: options.disableStdin ?? false,
       smoothScrollDuration: options.smoothScrollDuration ?? 100, // Default: 100ms smooth scroll
+      focusOnOpen: options.focusOnOpen ?? true,
     };
 
     // Wrap in Proxy to intercept runtime changes (xterm.js compatibility)
@@ -526,7 +527,9 @@ export class Terminal implements ITerminalCore {
       this.startRenderLoop();
 
       // Focus input (auto-focus so user can start typing immediately)
-      this.focus();
+      if (this.options.focusOnOpen !== false) {
+        this.focus();
+      }
     } catch (error) {
       // Clean up on error
       this.isOpen = false;