X11

.gitignore

@@ -1,7 +1,13 @@
+output/
 ssh.wasm
 tests.wasm
+tests.x11.wasm
 wasm_exec.js
 node_modules
 xterm.css
 xterm.js
 xterm.mjs
+js_tests/.npm-cache
+.gemini/
+/testserver
+tests/x11-standalone/*.png

.goversion

@@ -1 +1 @@
-1.26.2
+1.26.3

X11.md

@@ -0,0 +1,98 @@
+# X11 Forwarding Implementation in SSHTERM
+
+This document provides a comprehensive overview of the X11 server implementation in `sshterm`. It enables running graphical X11 applications on a remote server and displaying their interfaces directly within the web browser.
+
+## Architecture
+
+The system follows a distributed server-client model where the browser itself acts as the X11 server.
+
+### 1. X11 Server (Go/WASM)
+The core logic is implemented in Go and compiled to WebAssembly (WASM).
+*   **Protocol Handling:** Manages the X11 wire protocol, parsing incoming requests from clients and serializing replies, events, and errors.
+*   **State Management:** Maintains the authoritative state of windows, graphics contexts (GCs), properties, atoms, and resource allocations.
+*   **Event Routing:** Distributes input events (mouse, keyboard) to the correct clients and windows based on focus and grabs.
+*   **Abstraction:** Communicates with the rendering layer via the `X11FrontendAPI` interface, ensuring the core logic remains platform-independent.
+
+### 2. Frontend Renderer (HTML5 Canvas)
+The rendering layer is implemented as a Go-WASM bridge to the browser's DOM.
+*   **Canvas Windows:** Each top-level X11 window is represented by an HTML5 `<canvas>` element.
+*   **WASM-JS Bridge:** Uses `syscall/js` to translate Go drawing commands into high-performance JavaScript Canvas API calls.
+*   **Window Manager:** A lightweight internal window manager handles decorations (title bars, close buttons), dragging, and resizing for top-level windows.
+
+### 3. SSH Integration
+X11 traffic is forwarded over standard SSH channels.
+*   **Forwarding:** When the `-X` flag is used, `sshterm` requests X11 forwarding from the remote server (`x11-req`).
+*   **Channel Management:** The application listens for incoming X11 channels and pipes them directly into the internal X11 server instance.
+
+---
+
+## Core Components
+
+### `x11Server` (`go/internal/x11/x11.go`)
+The central engine that coordinates client connections and resource management. It handles the initial handshake (supporting both Big and Little Endian) and dispatches opcodes to their respective handlers.
+
+### `wire` Package (`go/internal/x11/wire/`)
+An exhaustive definition of the X11 protocol. It contains structs and serialization logic for over 100 requests, replies, events, and errors. It ensures strict protocol compliance and robust input validation.
+
+### `X11FrontendAPI`
+A decoupled interface defining all visual and interactive operations:
+*   **Drawing:** `PolyLine`, `PolyFillRectangle`, `FillPoly`, `PolyArc`, `PutImage`, `ImageText8/16`, etc.
+*   **Windowing:** `CreateWindow`, `MapWindow`, `ConfigureWindow`, `SetWindowCursor`.
+*   **Resources:** `CreatePixmap`, `CreateGC`, `OpenFont`.
+*   **Interaction:** `GrabPointer`, `GrabKeyboard`, `AllowEvents`.
+
+---
+
+## Rendering Engine
+
+### Logical Operations
+X11 defines 16 logical functions for drawing (`GXcopy`, `GXxor`, `GXand`, etc.). `sshterm` uses a dual-path approach:
+*   **Native Path:** Common operations like `GXcopy` and `GXxor` are mapped to Canvas `globalCompositeOperation` (e.g., `source-over`, `difference`) for hardware-accelerated performance.
+*   **Software Path:** For complex operations not supported by Canvas, an optimized software renderer performs bitwise manipulation on `Uint32Array` views of the pixel data.
+
+### Optimizations
+*   **Dirty Region Tracking:** The server tracks modified areas of windows to minimize redrawing and data transfer.
+*   **Bulk Memory Copy:** `PutImage` avoids per-pixel Go-to-JS calls by passing raw byte slices and using `Uint8ClampedArray.set()` for high-speed transfers.
+*   **Throttling:** High-frequency events like `mousemove` are throttled to 60FPS to prevent flooding the WASM bridge.
+
+---
+
+## Input & Interaction
+
+### Grabs and Synchronization
+*   **Active Grabs:** Implements `GrabPointer` and `GrabKeyboard` using the browser's `setPointerCapture` API. This ensures that menus and popups correctly capture interaction even outside their window boundaries.
+*   **Event Queuing:** To support `AllowEvents` and synchronous grabs, the server maintains internal event queues. During a synchronous grab, events are buffered and only released when the client explicitly requests them, preventing race conditions in modal dialogs.
+
+### Fonts
+X11 Logical Font Descriptions (XLFD) are mapped to modern CSS web fonts. The server generates accurate font metrics (ascent, descent, character widths) to ensure clients can correctly calculate their layout.
+
+### Clipboard
+X11 selections (`CLIPBOARD`, `PRIMARY`) are integrated with the browser's `navigator.clipboard` API. This allows seamless copy-paste between remote graphical applications and local browser/OS applications.
+
+---
+
+## Extensions Support
+
+*   **BigRequests:** Fully supported, allowing for requests larger than 256KB.
+*   **XInput / XInput2:** Implements device state queries, extended event masks, and raw motion events.
+*   **MIT-SHM:** Reported as unsupported, forcing clients to fall back to standard `PutImage`/`GetImage` paths which are optimized within the WASM environment.
+
+---
+
+## Security
+
+*   **MIT-MAGIC-COOKIE-1:** Standard X11 authentication is implemented to verify connections.
+*   **Isolation:** The X11 server runs entirely within the browser's security sandbox. It has no access to the local filesystem or network beyond what the SSH session and browser APIs allow.
+
+---
+
+## Testing Strategy
+
+### 1. Unit Tests
+Located in `go/internal/x11/`, these tests verify protocol parsing, resource state, and logic. They use a mock frontend to assert that X11 requests result in the expected internal state changes.
+
+### 2. Visual Tests
+Automated WASM-based tests (`visual_test.go`) that render primitives to a canvas and verify the result by comparing pixel data against expected values. This ensures high-fidelity rendering for all GC functions and drawing modes.
+
+### 3. Integration Tests
+Headless browser tests (`tests/run-headless-tests.sh`) use `chromedp` to drive the full application. They connect to a mock SSH server, launch real X11 applications (like `xterm` or `xeyes`), and verify that windows appear and respond to injected input correctly.

build.sh

@@ -1,12 +1,16 @@
 #!/bin/bash -e
 
 cd $(dirname $0)
+
+mkdir -p output
+exec &> >(tee output/build.log)
+
 if [[ ! -f docroot/xterm.mjs ]]; then
   echo "Updating xtermjs..."
   ./xterm/update.sh
 fi
 echo "Updating ssh.wasm..."
-./go/build.sh
+./go/build.sh "$@"
 echo "Files in ./docroot/"
 ls ./docroot/
 echo "Done"

docroot/main.mjs

@@ -25,6 +25,4 @@
 
 import { TabManager } from './ssh.mjs';
 
-window.addEventListener('load', () => {
-  new TabManager(document.getElementById('terminal'));
-});
+new TabManager(document.getElementById('terminal'));

docroot/ssh.mjs

@@ -29,6 +29,9 @@ import { Terminal, FitAddon } from './xterm.mjs';
 function isTest() {
   return window.location.pathname.indexOf('tests.html') !== -1;
 }
+function isX11Test() {
+  return window.location.pathname.indexOf('tests.html') !== -1 && window.location.search.indexOf('x11') !== -1;
+}
 
 class TerminalManager {
   constructor(elem, setTitle, onBell) {
@@ -183,18 +186,22 @@ export class TabManager {
     this.selectScreen(b.id);
 
     const term = terminalManager.getTerm();
-    const cfg = await fetch('config.json')
+    const configFile = isX11Test() ? 'tests.x11.config.json' : 'config.json';
+    const cfg = await fetch(configFile)
       .then(r => {
         if (r.ok) return r.json();
         return {};
       })
       .catch(e => {
-        term.writeln('\x1b[31mError reading config.json:\x1b[0m');
+        term.writeln('\x1b[31mError reading ' + configFile + ':\x1b[0m');
         term.writeln('\x1b[31m' + e.message + '\x1b[0m');
         term.writeln('');
         return {};
       });
     cfg.term = term;
+    if (isX11Test()) {
+      cfg.forwardX11 = true;
+    }
 
     const app = await window.sshApp.start(cfg);
     this.screens[b.id].close = app.close;
@@ -240,6 +247,6 @@ window.sshApp.ready = new Promise(resolve => {
 });
 
 const go = new Go();
-const wasmFile = isTest() ? 'tests.wasm' : 'ssh.wasm';
+const wasmFile = isTest() && !isX11Test() ? 'tests.wasm' : 'ssh.wasm';
 WebAssembly.instantiateStreaming(fetch(wasmFile), go.importObject)
   .then(r => go.run(r.instance));

docroot/tests.x11.config.json

@@ -0,0 +1,25 @@
+{
+	"persist": false,
+	"theme": "dark",
+	"endpoints": [{
+		"name": "test-server",
+		"url": "./websocket?cert=true"
+        }],
+	"certificateAuthorities": [{
+	        "name": "test-ca",
+		"publicKey": "===CAKEY===",
+		"hostnames": [ "test-server" ]
+	 }],
+	"generateKeys": [{
+		"name": "default",
+		"type": "ed25519",
+		"identityProvider": "/cert",
+		"addToAgent": true
+	}],
+	"autoConnect": {
+		"username": "testuser",
+		"hostname": "test-server",
+		"identity": "default",
+		"forwardX11": true
+	}
+}

docroot/tests.x11.html

@@ -0,0 +1,50 @@
+<!doctype html>
+<!--
+https://github.com/c2FmZQ/sshterm
+
+MIT License
+
+Copyright (c) 2025 TTBT Enterprises LLC
+Copyright (c) 2025 Robin Thellend <rthellend@rthellend.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+-->
+<html>
+<head>
+<title>SSH Terminal X11 Tests</title>
+<meta http-equiv="content-type" content="text/html; charset=utf-8" />
+<meta http-equiv="content-security-policy" content="default-src 'self'; style-src 'unsafe-inline' 'self'; script-src 'unsafe-eval' 'self';" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<link rel="icon" type="image/png" href="ssh.png" />
+<script type="module" src="tests.x11.mjs"></script>
+<style>
+html, body {
+  height: 100%;
+  margin: 0;
+  background-color: black;
+}
+#terminal {
+  height: 100%;
+}
+</style>
+</head>
+<body>
+<div id="terminal"></div>
+</body>
+</html>

docroot/tests.x11.mjs

@@ -0,0 +1,51 @@
+/*
+ * MIT License
+ *
+ * Copyright (c) 2025 TTBT Enterprises LLC
+ * Copyright (c) 2025 Robin Thellend <rthellend@rthellend.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import './wasm_exec.js';
+
+window.sshApp = {};
+window.sshApp.exited = null;
+window.sshApp.ready = new Promise(resolve => {
+  window.sshApp.sshIsReady = () => {
+    console.log('SSH WASM is ready');
+    resolve();
+  };
+});
+
+const go = new Go();
+const wasmFile = 'tests.x11.wasm';
+WebAssembly.instantiateStreaming(fetch(wasmFile), go.importObject)
+  .then(r => go.run(r.instance));
+
+window.sshApp.ready
+  .then(() => window.sshApp.start())
+  .then(res => {
+    console.log(`Exit status ${res}`);
+    let div = document.createElement('div');
+    div.id = 'x11-wasm-tests-done';
+    div.textContent = 'X11 WASM TESTS DONE';
+    div.style = 'position: absolute; top: 0; left: 0; color: white; background-color: black;';
+    document.body.appendChild(div);
+  });