Enable OSC 8 hyperlink activation

Author: nedtwigg

docs/specs/terminal-escapes.md

@@ -20,14 +20,14 @@ Rule of thumb: CSI talks to the screen, OSC talks to the application hosting the
 
 OSC sequences are introduced by `ESC ]` and terminated by either `BEL` (`\x07`) or `ST` (`ESC \`). A `BEL` that terminates an OSC is part of that OSC sequence, not a standalone bell notification. Both terminators are accepted across all supported sequences, and the parser handles split chunks across PTY reads.
 
-Supported OSCs are parsed at the PTY data boundary in the platform adapter:
+State-driving and security-sensitive OSCs are parsed at the PTY data boundary in the platform adapter:
 
 - VS Code: in the extension host (`message-router.ts` / `pty-manager.ts`), before `pty:data` is forwarded to the webview.
 - Standalone and fake adapters: in the frontend adapter, before xterm.js sees the bytes.
 
-After parsing, supported sequences are consumed and not re-emitted. Known unsupported iTerm2/clipboard-capable OSCs listed in [Known-unimplemented iTerm2 and clipboard-capable sequences](#known-unimplemented-iterm2-and-clipboard-capable-sequences) are also consumed and ignored. The platform sends two streams to the webview:
+After parsing, state-driving supported sequences are consumed and not re-emitted. `OSC 8` hyperlinks are the exception: the parser leaves them in `pty:data` so xterm.js owns hyperlink regions and hover rendering, while MouseTerm supplies the activation handler. Known unsupported iTerm2/clipboard-capable OSCs listed in [Known-unimplemented iTerm2 and clipboard-capable sequences](#known-unimplemented-iterm2-and-clipboard-capable-sequences) are also consumed and ignored. The platform sends two streams to the webview:
 
-- `pty:data` — terminal output with supported OSCs already parsed/stripped. Feeds xterm.js.
+- `pty:data` — terminal output with state-driving supported OSCs already parsed/stripped and `OSC 8` hyperlinks preserved. Feeds xterm.js.
 - `terminal:semanticEvents` — normalized semantic events parsed in the platform (CWD, prompt/command boundaries, titles). Feeds `TerminalPaneState`; command boundaries also feed the command-exit alert track defined in `docs/specs/alert.md`.
 - Notification-derived state is delivered through `AlertManager` calls / `alert:state` messages, not through `pty:data`.
 
@@ -40,6 +40,10 @@ The parser also classifies each PTY data chunk for activity-monitor purposes:
 
 Unknown non-iTerm2 OSC families pass through to xterm.js unchanged so xterm.js can handle standard terminal behavior MouseTerm does not model. Security-sensitive or iTerm2-identity-triggered OSCs must not rely on xterm.js defaults: if they are not in [Supported OSCs](#supported-oscs), MouseTerm consumes and ignores them without visible terminal garbage, clipboard access, file access, focus changes, or other side effects.
 
+### OSC 8 hyperlinks
+
+`OSC 8 ; <params> ; <URI> ST` starts a hyperlink region and `OSC 8 ; ; ST` closes it. `params` may be empty or include `id=<group-id>` for multi-line/shared link regions. MouseTerm does not parse the `params` or URI at the PTY boundary; it passes the sequence through to xterm.js. `terminal-lifecycle.ts` sets xterm.js's `linkHandler` so activation normalizes the URI through `normalizeExternalUri()`, allowing only `http:`, `https:`, and `mailto:` before calling the platform adapter's external-open path. VS Code revalidates in the extension host before `vscode.env.openExternal`; standalone and fake adapters also revalidate before opening.
+
 ## Supported OSCs
 
 | Sequence | Purpose | Spec |
@@ -48,6 +52,7 @@ Unknown non-iTerm2 OSC families pass through to xterm.js unchanged so xterm.js c
 | `OSC 0 ; <title> ST` | Window/icon title | [terminal-state.md](terminal-state.md#supported-osc-inputs) |
 | `OSC 2 ; <title> ST` | Window title | [terminal-state.md](terminal-state.md#supported-osc-inputs) |
 | `OSC 7 ; file://host/path ST` | CWD (xterm-style URI) | [terminal-state.md](terminal-state.md#supported-osc-inputs) |
+| `OSC 8 ; <params> ; <URI> ST ... OSC 8 ; ; ST` | Explicit hyperlink region; passed through to xterm.js for rendering and opened through MouseTerm's external-link allowlist (`http:`, `https:`, `mailto:`). | This spec |
 | `OSC 9 ; <message> ST` | iTerm2 legacy notification | [alert.md](alert.md#osc-9) |
 | `OSC 9 ; 4 ; <state> [; <progress>] ST` | iTerm2 progress | [alert.md](alert.md#osc-94-progress) |
 | `OSC 9 ; 9 ; <cwd> ST` | CWD (Windows Terminal / ConEmu) | [terminal-state.md](terminal-state.md#supported-osc-inputs) |
@@ -135,6 +140,7 @@ This list is non-exhaustive. Any iTerm2-compatibility OSC family that MouseTerm
 - xterm control sequences (OSC 0 / 2 / 7): https://invisible-island.net/xterm/ctlseqs/ctlseqs.html
 - VS Code shell integration sequences (OSC 633): https://code.visualstudio.com/docs/terminal/shell-integration
 - Windows Terminal CWD OSC 9;9: https://learn.microsoft.com/en-us/windows/terminal/tutorials/new-tab-same-directory
+- xterm.js OSC 8 link handling: https://xtermjs.org/docs/guides/link-handling/
 - kitty desktop notifications (OSC 99): https://sw.kovidgoyal.net/kitty/desktop-notifications/
 - kitty keyboard protocol: https://sw.kovidgoyal.net/kitty/keyboard-protocol/
 - WezTerm escape sequences (OSC 777): https://wezterm.org/escape-sequences.html

docs/specs/transport.md

@@ -77,6 +77,7 @@ Message types live in `vscode-ext/src/message-types.ts` (the canonical schema; o
 | `pty:getCwd` | Query PTY working directory (request-response via requestId) |
 | `pty:getScrollback` | Query PTY scrollback buffer (request-response via requestId) |
 | `pty:getShells` | Query available shells (request-response via requestId) |
+| `mouseterm:openExternal` | Request the host to open an already-sanitized external URI from an OSC 8 hyperlink. Hosts must revalidate and only allow `http:`, `https:`, and `mailto:`. |
 | `mouseterm:init` | Trigger resume: get PTY list + replay data |
 | `mouseterm:saveState` | Frontend persisting session state |
 | `mouseterm:flushSessionSaveDone` | Ack for host-triggered flush (matched by requestId) |
@@ -96,7 +97,7 @@ Message types live in `vscode-ext/src/message-types.ts` (the canonical schema; o
 
 | Message | Purpose |
 |---------|---------|
-| `pty:data` | PTY output after supported OSC sequences have been parsed/stripped (routed only to owning router) |
+| `pty:data` | PTY output after state-driving supported OSC sequences have been parsed/stripped; `OSC 8` hyperlinks are preserved for xterm.js (routed only to owning router) |
 | `pty:exit` | PTY process exited (with exitCode) |
 | `terminal:semanticEvents` | Normalized CWD/title/prompt/command events parsed in the host from live PTY data |
 | `pty:list` | List of all resumable PTYs (response to `mouseterm:init`) |

lib/src/lib/external-links.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest';
+import { normalizeExternalUri } from './external-links';
+
+describe('normalizeExternalUri', () => {
+  it('allows http, https, and mailto URIs', () => {
+    expect(normalizeExternalUri('https://example.com/docs?q=mouse')).toBe('https://example.com/docs?q=mouse');
+    expect(normalizeExternalUri(' http://example.com/path ')).toBe('http://example.com/path');
+    expect(normalizeExternalUri('mailto:support@example.com')).toBe('mailto:support@example.com');
+  });
+
+  it('rejects non-external and scriptable URI schemes', () => {
+    expect(normalizeExternalUri('file:///etc/passwd')).toBeNull();
+    expect(normalizeExternalUri('javascript:alert(1)')).toBeNull();
+    expect(normalizeExternalUri('data:text/html,hello')).toBeNull();
+  });
+
+  it('rejects malformed or control-character-bearing input', () => {
+    expect(normalizeExternalUri('not a url')).toBeNull();
+    expect(normalizeExternalUri('https://example.com/\nnext')).toBeNull();
+    expect(normalizeExternalUri('')).toBeNull();
+  });
+});

lib/src/lib/external-links.ts

@@ -0,0 +1,13 @@
+const ALLOWED_EXTERNAL_URI_PROTOCOLS = new Set(['http:', 'https:', 'mailto:']);
+
+export function normalizeExternalUri(input: string): string | null {
+  const trimmed = input.trim();
+  if (!trimmed || /[\x00-\x1f\x7f-\x9f]/.test(trimmed)) return null;
+
+  try {
+    const uri = new URL(trimmed);
+    return ALLOWED_EXTERNAL_URI_PROTOCOLS.has(uri.protocol) ? uri.href : null;
+  } catch {
+    return null;
+  }
+}

lib/src/lib/platform/fake-adapter.ts

@@ -1,5 +1,6 @@
 import type { AlertStateDetail, PlatformAdapter, PtyInfo } from './types';
 import { AlertManager, type SessionStatus } from '../alert-manager';
+import { normalizeExternalUri } from '../external-links';
 import {
   applyTerminalProtocolEvents,
   collectTerminalSemanticEvents,
@@ -198,6 +199,11 @@ export class FakePtyAdapter implements PlatformAdapter {
 
   async readClipboardFilePaths(): Promise<string[] | null> { return null; }
   async readClipboardImageAsFilePath(): Promise<string | null> { return null; }
+  openExternal(uri: string): void {
+    const normalized = normalizeExternalUri(uri);
+    if (!normalized || typeof window === 'undefined') return;
+    window.open(normalized, '_blank', 'noopener,noreferrer');
+  }
 
   requestInit(): void {}
   onPtyList(_handler: (detail: { ptys: PtyInfo[] }) => void): void {}

lib/src/lib/platform/types.ts

@@ -36,6 +36,10 @@ export interface PlatformAdapter {
   // Only present on adapters with a native (non-DOM) drag-drop source. Currently inert in Tauri; see diffplug/mouseterm#38 and tauri-apps/tauri#14373.
   onFilesDropped?(handler: (paths: string[]) => void): () => void;
 
+  // Open a sanitized external URI. Implementations must revalidate because
+  // terminal output is untrusted.
+  openExternal?(uri: string): void;
+
   // PTY event listeners
   onPtyData(handler: (detail: { id: string; data: string }) => void): void;
   offPtyData(handler: (detail: { id: string; data: string }) => void): void;

lib/src/lib/platform/vscode-adapter.test.ts

@@ -69,6 +69,17 @@ describe('VSCodeAdapter PTY exit handling', () => {
     expect(postMessage).toHaveBeenCalledWith({ type: 'pty:kill', id: 'pane-1' });
   });
 
+  it('posts external hyperlink open requests to the extension host', () => {
+    const adapter = new VSCodeAdapter();
+
+    adapter.openExternal('https://example.com/docs');
+
+    expect(postMessage).toHaveBeenCalledWith({
+      type: 'mouseterm:openExternal',
+      uri: 'https://example.com/docs',
+    });
+  });
+
   it('parses replay buffers into semantic events and strips OSCs before forwarding', () => {
     const adapter = new VSCodeAdapter();
     const replays: Array<{ id: string; data: string }> = [];

lib/src/lib/platform/vscode-adapter.ts

@@ -177,6 +177,10 @@ export class VSCodeAdapter implements PlatformAdapter {
     );
   }
 
+  openExternal(uri: string): void {
+    this.vscode.postMessage({ type: 'mouseterm:openExternal', uri });
+  }
+
   onPtyData(handler: (detail: { id: string; data: string }) => void): void {
     this.dataHandlers.add(handler);
   }

lib/src/lib/terminal-lifecycle.ts

@@ -1,6 +1,7 @@
 import { Terminal } from '@xterm/xterm';
 import { FitAddon } from '@xterm/addon-fit';
 import { getPlatform } from './platform';
+import { normalizeExternalUri } from './external-links';
 import { attachMouseModeObserver } from './mouse-mode-observer';
 import {
   bumpRenderTick,
@@ -55,6 +56,15 @@ function createXtermHost(): { terminal: Terminal; fit: FitAddon; element: HTMLDi
     cursorBlink: true,
     theme,
     vtExtensions: { kittyKeyboard: true },
+    linkHandler: {
+      activate: (event, uri) => {
+        event.preventDefault();
+        const normalized = normalizeExternalUri(uri);
+        if (!normalized) return;
+        getPlatform().openExternal?.(normalized);
+      },
+      allowNonHttpProtocols: true,
+    },
   });
 
   const fit = new FitAddon();

lib/src/lib/terminal-protocol.test.ts

@@ -150,6 +150,15 @@ describe('TerminalProtocolParser', () => {
     expect(result.events).toEqual([]);
   });
 
+  it('passes OSC 8 hyperlinks through to xterm for rendering', () => {
+    const parser = new TerminalProtocolParser();
+    const hyperlink = '\x1b]8;id=docs;https://example.com/docs\x1b\\docs\x1b]8;;\x1b\\';
+    const result = parser.process(`see ${hyperlink} now`);
+
+    expect(result.visibleData).toBe(`see ${hyperlink} now`);
+    expect(result.events).toEqual([]);
+  });
+
   it('strips known unsupported iTerm2 and clipboard OSC sequences', () => {
     const parser = new TerminalProtocolParser();
     const result = parser.process('a\x1b]52;c;SGVsbG8=\x07b\x1b]50;Monaco\x07c');