@hex1b/web-terminal 0.1.0 → 0.166.0

package/dist/web-terminal.js

@@ -1,11 +1,13 @@
 import { captureMouse } from "./mouse-input.js";
 import { normalizeFont } from "./terminal-font.js";
+import { normalizeRenderer } from "./renderer-options.js";
 import { dimensions, normalizeSizing, requestedGrid, fittedScale } from "./terminal-sizing.js";
 import { HistoryState } from "./history-state.js";
 import { terminalThemeCss } from "./terminal-theme.js";
 import { InputPolicy, InputRoute, TerminalAction, inputModifiers } from "./input-policy.js";
 import { assertCommandSize } from "./protocol.js";
 import { SelectionUI } from "./selection-ui.js";
+import { Hyperlinks } from "./hyperlinks.js";
 import { errorMessage, isRecord } from "./validation.js";
 export { InputRoute, TerminalAction, defaultInputBindings } from "./input-policy.js";
 function requiredElement(root, selector, type) {
@@ -21,6 +23,7 @@ function requiredElement(root, selector, type) {
 export class WebTerminal {
     element;
     #options;
+    #renderer;
     // DOM and worker fields are initialized by mount before a handle is returned.
     #worker;
     #surface;
@@ -34,15 +37,23 @@ export class WebTerminal {
     #geometry = { columns: 80, rows: 24, cellWidth: 10, cellHeight: 20, mouseTracking: 0 };
     #peer = { id: null, primaryId: null, isPrimary: false };
     #connected = false;
+    #closed = false;
+    #readOnly;
     #disposed = false;
     #hasGeometry = false;
     #resizeTimer;
     #lastRequested;
     #compositionTimer;
+    #resetComposition;
     #ready = Promise.withResolvers();
     #readyTimer;
     #stats = {};
     #screenText = "";
+    #title = "";
+    #hasTitle = false;
+    #progress = { state: "none", percentage: null };
+    #shellIntegration = { phase: "unknown", lastExitCode: null };
+    #hasActivity = false;
     #history;
     #highlights;
     #inspection;
@@ -57,6 +68,7 @@ export class WebTerminal {
     #selectionOverlay;
     #selectionUIError = "";
     #canvasSize = { width: 0, height: 0 };
+    #hyperlinks = new Hyperlinks();
     /** Resolves after a connected terminal frame is presented. Supply signal to cancel mounting. */
     static async mount(container, options) {
         if (!(container instanceof HTMLElement))
@@ -65,8 +77,9 @@ export class WebTerminal {
             throw new TypeError("A terminal WebSocket URL is required");
         if (options.signal?.aborted)
             throw options.signal.reason;
-        if (!window.isSecureContext || !navigator.gpu)
-            throw new Error("WebTerminal requires WebGPU over HTTPS or localhost");
+        if (normalizeRenderer(options.renderer) === "webgpu" && (!window.isSecureContext || !navigator.gpu)) {
+            throw new Error("The requested WebGPU renderer requires WebGPU over HTTPS or localhost");
+        }
         if (!window.Worker || !window.ResizeObserver || !window.OffscreenCanvas ||
             !HTMLCanvasElement.prototype.transferControlToOffscreen) {
             throw new Error("WebTerminal requires module workers, ResizeObserver, and a transferable OffscreenCanvas");
@@ -83,6 +96,10 @@ export class WebTerminal {
     }
     constructor(options) {
         this.#options = options;
+        if (options.readOnly !== undefined && typeof options.readOnly !== "boolean")
+            throw new TypeError("readOnly must be a boolean");
+        this.#readOnly = options.readOnly ?? false;
+        this.#renderer = normalizeRenderer(options.renderer);
         if (options.workerUrl !== undefined && !(options.workerUrl instanceof URL) &&
             (typeof options.workerUrl !== "string" || !options.workerUrl.trim()))
             throw new TypeError("workerUrl must be a nonempty URL string or URL");
@@ -100,6 +117,11 @@ export class WebTerminal {
     get geometry() { return { ...this.#geometry }; }
     get peer() { return { ...this.#peer }; }
     get connected() { return this.#connected; }
+    get readOnly() { return this.#readOnly; }
+    /** Current presented workload title; retained on disconnect/dispose. Treat as untrusted text. */
+    get title() { return this.#title; }
+    get progress() { return { ...this.#progress }; }
+    get shellIntegration() { return { ...this.#shellIntegration }; }
     get stats() { return { ...this.#stats }; }
     get screenText() { return this.#screenText; }
     get sizing() { return { ...this.#sizing }; }
@@ -176,7 +198,7 @@ export class WebTerminal {
             element: this.element, overlay: this.#selectionOverlay,
             button: requiredElement(this.#inspection, ".copy-selection", HTMLButtonElement), signal: this.#listeners.signal,
             getState: () => ({ selection: this.selection, viewport: this.viewport, geometry: this.geometry,
-                canvasSize: this.#canvasSize, connected: this.#connected, readOnly: !!this.#options.readOnly }),
+                canvasSize: this.#canvasSize, connected: this.#connected, readOnly: this.#readOnly }),
             runAction: this.runAction.bind(this),
             onSelectionUI: this.#options.onSelectionUI,
             reportError: error => {
@@ -202,14 +224,23 @@ export class WebTerminal {
             }
         };
         this.#mouse = captureMouse(this.#canvas, command => this.#inputCommand(command), () => this.focus(), {
-            state: () => ({ historical: !this.viewport.following || this.viewport.pending, readOnly: !!this.#options.readOnly,
+            state: () => ({ historical: !this.viewport.following || this.viewport.pending, readOnly: this.#readOnly,
                 selection: this.selection }),
             begin: (point, selection) => inspect(() => this.#history.begin(point, selection)),
             extend: point => inspect(() => this.#history.extend(point)),
             scroll: (delta, endpoint) => inspect(() => this.#history.scroll(delta, endpoint)),
             end: cancelled => this.#history.endGesture(cancelled),
             resolve: input => this.#resolveInput(input),
-            execute: (decision, input) => this.#executeInputAction(decision, input)
+            execute: (decision, input) => this.#executeInputAction(decision, input),
+            hyperlink: point => this.#connected && !this.viewport.pending ? this.#hyperlinks.at(point) : null,
+            openHyperlink: uri => {
+                try {
+                    window.open(uri, "_blank", "noopener,noreferrer");
+                }
+                catch (error) {
+                    this.#actionFailed(error);
+                }
+            }
         });
         this.#bindKeyboard();
         requiredElement(this.#inspection, ".return-live", HTMLButtonElement).addEventListener("click", () => {
@@ -250,7 +281,8 @@ export class WebTerminal {
         });
         this.#worker.addEventListener("messageerror", () => this.#fail(new Error("Terminal worker message could not be decoded")));
         const canvas = this.#canvas.transferControlToOffscreen();
-        this.#post({ type: "init", canvas, url: url.href, scale, font }, [canvas]);
+        this.#post({ type: "init", canvas, url: url.href, scale, font,
+            renderer: this.#renderer }, [canvas]);
     }
     #message(message) {
         if (this.#disposed)
@@ -259,8 +291,19 @@ export class WebTerminal {
             this.#connected = true;
             this.#input.disabled = !this.#canInput();
         }
-        else if (message.type === "disconnected") {
-            this.#disconnect();
+        else if (message.type === "closed") {
+            if (this.#closed)
+                return;
+            this.#closed = true;
+            clearTimeout(this.#readyTimer);
+            try {
+                this.#disconnect();
+                if (!this.#disposed)
+                    this.#options.onClose?.(Object.freeze({ ...message.details }));
+            }
+            finally {
+                this.#ready.reject(new Error(`Terminal WebSocket closed (${message.details.code}${message.details.reason ? `: ${message.details.reason}` : ""}) before mounting completed`));
+            }
         }
         else if (message.type === "status") {
             if (message.level === "error") {
@@ -283,7 +326,7 @@ export class WebTerminal {
             this.#input.disabled = !this.#canInput();
             if (this.#canInput() && document.activeElement === this.element && !this.element.shadowRoot?.activeElement)
                 this.focus();
-            this.#mouse?.update(message.columns, message.rows, message.mouseTracking);
+            this.#hyperlinks.update(message.hyperlinks);
             if (geometryChanged || oldPeer.isPrimary !== this.#peer.isPrimary)
                 this.#fit();
             if (!this.#peer.isPrimary) {
@@ -299,6 +342,7 @@ export class WebTerminal {
                 this.#screenText = message.text;
                 this.#history.accept(message.history, message.revision);
             }
+            this.#mouse?.update(message.columns, message.rows, message.mouseTracking);
             if (geometryChanged)
                 this.#options.onGeometry?.(this.geometry);
             if (first)
@@ -306,6 +350,24 @@ export class WebTerminal {
             if (oldPeer.id !== this.#peer.id || oldPeer.primaryId !== this.#peer.primaryId || oldPeer.isPrimary !== this.#peer.isPrimary) {
                 this.#options.onRoleChange?.(this.peer);
             }
+            if (!this.#disposed && this.#connected && (this.#peer.id !== null || this.#peer.isPrimary)) {
+                const titleChanged = !this.#hasTitle || this.#title !== message.title;
+                const progressChanged = !this.#hasActivity || this.#progress.state !== message.progress.state ||
+                    this.#progress.percentage !== message.progress.percentage;
+                const shellChanged = !this.#hasActivity || this.#shellIntegration.phase !== message.shellIntegration.phase ||
+                    this.#shellIntegration.lastExitCode !== message.shellIntegration.lastExitCode;
+                this.#title = message.title;
+                this.#hasTitle = true;
+                this.#progress = { ...message.progress };
+                this.#shellIntegration = { ...message.shellIntegration };
+                this.#hasActivity = true;
+                if (titleChanged)
+                    this.#options.onTitleChange?.(this.#title);
+                if (!this.#disposed && progressChanged)
+                    this.#options.onProgressChange?.(this.progress);
+                if (!this.#disposed && shellChanged)
+                    this.#options.onShellIntegrationChange?.(this.shellIntegration);
+            }
         }
         else if (message.type === "history") {
             this.#screenText = message.text;
@@ -315,7 +377,8 @@ export class WebTerminal {
             this.#stats = message.stats;
             if (message.text !== undefined)
                 this.#screenText = message.text;
-            if (message.stats.revision > 0 && this.#connected && (this.#peer.id !== null || this.#peer.isPrimary)) {
+            if (message.stats.revision > 0 && this.#hasTitle && this.#hasActivity && this.#connected &&
+                (this.#peer.id !== null || this.#peer.isPrimary)) {
                 clearTimeout(this.#readyTimer);
                 this.#ready.resolve(this);
             }
@@ -341,13 +404,13 @@ export class WebTerminal {
     #queueResize(includeFixed = false) {
         if (this.#sizing.mode === "fixed" && !includeFixed)
             return;
-        if (!this.#hasGeometry || !this.#peer.isPrimary || this.#resizeTimer !== undefined || this.#disposed)
+        if (!this.#canInput() || !this.#peer.isPrimary || this.#resizeTimer !== undefined || this.#disposed)
             return;
         // Throttle (rather than debounce) so dragging a primary view updates peers live.
         this.#resizeTimer = setTimeout(() => {
             this.#resizeTimer = undefined;
             const grid = this.#fittedGrid();
-            if (!grid || !this.#peer.isPrimary || !this.#connected)
+            if (!grid || !this.#peer.isPrimary || !this.#canInput())
                 return;
             const key = `${grid.columns}x${grid.rows}`;
             if ((grid.columns === this.#geometry.columns && grid.rows === this.#geometry.rows) || key === this.#lastRequested)
@@ -361,6 +424,8 @@ export class WebTerminal {
     #send(command) {
         if (!this.#connected || this.#disposed)
             throw new Error("Terminal view is not connected");
+        if (this.#readOnly && ["input", "paste", "key", "mouse", "resize", "requestPrimary"].includes(command.type))
+            throw new Error("Terminal view does not accept input");
         this.#post({ type: "command", command });
     }
     #inputCommand(command) {
@@ -380,6 +445,7 @@ export class WebTerminal {
     #inspectionChanged() {
         const viewport = this.viewport;
         const selection = this.selection;
+        this.#mouse?.refresh();
         if (selection.status === "invalidated")
             this.#mouse?.cancel();
         if (this.#highlights) {
@@ -466,20 +532,23 @@ export class WebTerminal {
         }
     }
     #canInput() {
-        return this.#connected && this.#hasGeometry && !this.#options.readOnly &&
+        return this.#connected && this.#hasGeometry && !this.#readOnly &&
             (this.#peer.id !== null || this.#peer.isPrimary);
     }
     get inputContext() {
         return Object.freeze({
             terminal: this, selection: this.selection, viewport: this.viewport,
-            buffer: this.viewport.buffer ?? null, mouseCaptured: this.#geometry.mouseTracking !== 0,
+            buffer: this.viewport.buffer ?? null, mouseCaptured: !this.#readOnly && this.#geometry.mouseTracking !== 0,
             historical: !this.viewport.following || this.viewport.pending,
-            readOnly: !!this.#options.readOnly, connected: this.#connected, peer: this.peer
+            readOnly: this.#readOnly, connected: this.#connected, peer: this.peer
         });
     }
     #resolveInput(input) {
         try {
-            return this.#policy.resolve(Object.freeze(input), this.inputContext);
+            const decision = this.#policy.resolve(Object.freeze(input), this.inputContext);
+            if (this.#readOnly && decision.route === InputRoute.Application)
+                return { route: input.type === "pointer" || input.type === "wheel" ? InputRoute.Continue : InputRoute.Consume };
+            return decision;
         }
         catch (error) {
             this.#actionFailed(error);
@@ -524,7 +593,7 @@ export class WebTerminal {
                 try {
                     if (this.selection.active || (this.selection.pending && this.selection.canExtend))
                         return await this.copySelection({ clear: true });
-                    if (!this.#options.readOnly)
+                    if (!this.#readOnly)
                         return await this.pasteClipboard();
                     return;
                 }
@@ -559,6 +628,34 @@ export class WebTerminal {
         this.paste(text);
         return text;
     }
+    /** Changes per-view input policy without reconnecting; server authorization remains host-owned. */
+    setReadOnly(readOnly) {
+        if (typeof readOnly !== "boolean")
+            throw new TypeError("readOnly must be a boolean");
+        if (this.#disposed)
+            throw new Error("Terminal view is disposed");
+        if (this.#readOnly === readOnly)
+            return;
+        const inputFocused = document.activeElement === this.element &&
+            (!this.element.shadowRoot?.activeElement || this.element.shadowRoot.activeElement === this.#input);
+        this.#readOnly = readOnly;
+        this.#inputSerial++;
+        this.#resetComposition?.();
+        if (this.#input) {
+            this.#input.value = "";
+            this.#input.disabled = !this.#canInput();
+        }
+        // Set the policy before cancelling so pending moves and button releases cannot leak.
+        this.#mouse?.cancel();
+        this.#mouse?.refresh();
+        clearTimeout(this.#resizeTimer);
+        this.#resizeTimer = undefined;
+        this.#lastRequested = undefined;
+        this.#queueResize(true);
+        if (inputFocused)
+            this.focus();
+        this.#selectionUI?.refresh();
+    }
     #forwardInput(input) {
         if (input.type === "key") {
             if (input.meta)
@@ -599,6 +696,11 @@ export class WebTerminal {
         const options = { signal: this.#listeners.signal };
         let composing = false;
         let compositionCommit = null;
+        this.#resetComposition = () => {
+            composing = false;
+            compositionCommit = null;
+            clearTimeout(this.#compositionTimer);
+        };
         this.element.addEventListener("keydown", event => {
             if (event.defaultPrevented)
                 return;
@@ -619,11 +721,15 @@ export class WebTerminal {
             input.value = "";
         }, options);
         input.addEventListener("compositionstart", () => {
+            if (!this.#canInput())
+                return;
             composing = true;
             compositionCommit = null;
             clearTimeout(this.#compositionTimer);
         }, options);
         input.addEventListener("compositionend", event => {
+            if (!composing)
+                return;
             composing = false;
             // Accommodate browsers placing the final input before or after compositionend.
             compositionCommit = typeof event.data === "string" ? event.data : input.value;
@@ -654,6 +760,8 @@ export class WebTerminal {
     }
     /** Request HMP1 primary explicitly; peer notifications confirm the result. */
     requestPrimary() {
+        if (!this.#canInput())
+            throw new Error("Terminal view does not accept input");
         if (this.#size.width <= 0 || this.#size.height <= 0)
             throw new Error("Show the terminal container before taking primary");
         const grid = this.#fittedGrid();
@@ -670,6 +778,8 @@ export class WebTerminal {
     /** Request a grid; never reflow locally before the authoritative response. */
     resize(columns, rows) {
         const grid = dimensions(columns, rows);
+        if (!this.#canInput())
+            throw new Error("Terminal view does not accept input");
         if (!this.#peer.isPrimary)
             throw new Error("Only the primary view can request a terminal resize");
         this.#send({ type: "resize", ...grid });
@@ -680,6 +790,8 @@ export class WebTerminal {
         const next = normalizeSizing(sizing, this.#sizing.fontSize);
         if (!this.#connected || this.#disposed)
             throw new Error("Terminal view is not connected");
+        if (this.#readOnly)
+            throw new Error("Terminal view does not accept input");
         if (!this.#peer.isPrimary)
             throw new Error("Only the primary view can change terminal sizing");
         this.#sizing = next;
@@ -694,6 +806,7 @@ export class WebTerminal {
     #disconnect() {
         this.#inputSerial++;
         this.#connected = false;
+        this.#hyperlinks.update([]);
         if (this.#input)
             this.#input.disabled = true;
         this.#mouse?.update(1, 1, 0);