@hex1b/web-terminal 0.1.0 → 0.166.0

package/README.md

@@ -1,6 +1,6 @@
 # @hex1b/web-terminal
 
-The first-party WebGPU browser terminal for Hex1b. It renders server-authoritative
+The first-party GPU-rendered browser terminal for Hex1b. It renders server-authoritative
 cells and graphics in a module worker, with local input routing, producer-backed
 history and selection, clipboard actions, and primary/secondary view sizing.
 There are no runtime package dependencies.
@@ -51,12 +51,89 @@ terminal.focus();
 or disposes a mounted view. Disposal removes only the appended element and its
 connection, not the container or server-side shared terminal.
 
+### Connection closure and workload completion
+
+Use `onClose(details)` to observe the browser's actual WebSocket close event.
+`TerminalCloseDetails` contains readonly `code`, `reason`, and `wasClean` fields.
+The callback runs once with the view already disconnected, **even if the socket
+closes before the first HWT frame or authoritative HMP peer state**. A pending
+mount rejects after the callback, so capture any host state before calling mount.
+The details object is frozen. Reasons are untrusted text; do not render them as HTML.
+
+```ts
+import { WebTerminal, type TerminalCloseDetails } from "@hex1b/web-terminal";
+
+const container = document.getElementById("terminal");
+if (!container) throw new Error("Missing terminal container");
+let closed: TerminalCloseDetails | undefined;
+try {
+  const terminal = await WebTerminal.mount(container, {
+    url: "/ws/terminal",
+    onClose(details) {
+      closed = details;
+      console.log("View closed", details.code, details.reason, details.wasClean);
+    }
+  });
+  terminal.focus();
+} catch (error) {
+  // closed is set for a transport close, but not for local initialization failure.
+  console.error("Mount failed", closed, error);
+}
+```
+
+Transport loss is **not workload completion**. Code 1006 means the browser did not
+receive a close frame; even code 1000 and `wasClean: true` only describe transport
+closure, not successful process exit. Hosts can define an application close-code
+contract and send it when their authoritative producer reports completion,
+including before any HWT frame exists. Hex1b does not assign workload meaning to
+close codes or reason strings. HTTP upgrade failures generally surface as 1006;
+browsers do not expose the rejected HTTP response body or status through this API.
+
+The client never retries automatically. The host decides whether to mount a new
+view after transport loss or leave an ended tab/dialog visible. Abort, explicit
+disposal, mount timeout, and local initialization/renderer failures do not
+synthesize `onClose`; no callback runs after disposal. Callback exceptions are
+reported to the host, not swallowed or retried, and do not leave mounting pending.
+The API does not retain the producer after exit or promise a final rendered frame.
+
 ### Browser and deployment requirements
 
-Use HTTPS or localhost and a browser with WebGPU, module workers, transferable
-OffscreenCanvas, worker animation frames, ResizeObserver, and CSS Font Loading.
-Clipboard access also requires browser permission and, for relevant actions, a
-user gesture. There is no Canvas2D terminal-rendering fallback.
+Use a browser with WebGPU or WebGL2, module workers, transferable OffscreenCanvas,
+worker animation frames, ResizeObserver, and CSS Font Loading. WebGPU requires
+HTTPS or localhost; WebGL2 rendering also works on ordinary HTTP origins.
+Clipboard API access still requires a secure context, browser permission and,
+for relevant actions, a user gesture. There is no Canvas2D terminal-rendering fallback.
+Renderer selection does not change transport security: use HTTPS/WSS to protect
+terminal input and output.
+
+### Renderer selection
+
+Set the mount-time `renderer` option to `"auto"` (the default), `"webgpu"`, or
+`"webgl2"`. Auto prefers WebGPU and uses WebGL2 if the secure context, API,
+adapter, device acquisition, or presentation context is unavailable. Explicit
+modes require that backend and report an error rather than falling back.
+Shader, font, validation, and unexpected initialization errors are not
+compatibility fallbacks. Runtime GPU/context loss terminates the view with an
+error; it does not switch backends behind the caller's back.
+
+```ts
+const terminal = await WebTerminal.mount(container, {
+  url: "/ws/terminal",
+  renderer: "webgl2", // Use WebGL2 even if WebGPU is available.
+  onStats(stats) {
+    console.log(stats.renderer, stats.rendererFallbackReason);
+  }
+});
+```
+
+`stats.renderer` identifies the active backend after initialization.
+`stats.rendererFallbackReason` explains an automatic fallback and is absent
+for explicit selections and successful WebGPU initialization. Both backends
+share glyph rasterization, frame preparation, clipping, and image ordering.
+WebGPU preference is not a performance guarantee; compare representative
+workloads on your target browsers and devices.
+
+### Module and worker deployment
 
 The package contains browser ES modules, not a single bundle. For bare static
 hosting, copy **all of `dist/`**, preserving its directory structure, and import
@@ -100,10 +177,14 @@ workers, fonts, and the intended WebSocket endpoint.
 | --- | --- |
 | `workerUrl` | Optional module-worker entry; useful when worker assets are deployed separately. |
 | `scale` | GPU backing scale `0.5`–`3`, or `"auto"` (default, bounded device pixel ratio). |
+| `renderer` | `"auto"` (prefer WebGPU), `"webgpu"`, or `"webgl2"`; selected once per mount. |
 | `font` | One family and optional downloadable font faces; see below. |
 | `sizing` | `{ mode: "auto", fontSize?: number }` or `{ mode: "fixed", columns, rows, fontSize?: number }`. |
-| `readOnly` | Disable application input while retaining history inspection and selection. |
+| `readOnly` | Initial per-view input policy; change it later with `setReadOnly(boolean)`. |
 | `label` | Accessible label for the terminal's hidden keyboard input. |
+| `onTitleChange` | Initial authoritative workload title, then distinct presented changes; see below. |
+| `onClose` | Native WebSocket close details, including pre-mount transport failure; not workload completion. |
+| `onProgressChange`, `onShellIntegrationChange` | Initial authoritative activity, then distinct presented changes for host-owned chrome. |
 | `inputBindings`, `onInput`, `actions` | Per-view input policy and custom actions. |
 | `onSelectionUI` | Synchronous, cancelable UI notification hook. |
 
@@ -114,7 +195,7 @@ Font size is an integer from 8–32, defaulting to 16. Import `MIN_FONT_SIZE` an
 ownership. `requestPrimary()` explicitly requests ownership; inspect `peer` or
 `onRoleChange` to observe the result.
 
-The handle exposes `geometry`, `peer`, `connected`, `stats`, `screenText`,
+The handle exposes `geometry`, `peer`, `connected`, `readOnly`, `title`, `progress`, `shellIntegration`, `stats`, `screenText`,
 `sizing`, `viewport`, `selection`, `inputBindings`, and `inputContext`.
 Metrics start empty; check optional fields before using them. History may be
 unavailable, and selection can be unavailable, none, pending, valid, or
@@ -122,8 +203,215 @@ invalidated. Narrow `viewport.available` and `selection.status` before using
 their state-specific values. `screenText` reflects the presented viewport, not
 an independently reconstructed ANSI buffer.
 
-Callbacks include `onGeometry`, `onRoleChange`, `onSizingChange`, `onStats`,
-`onViewportChange`, `onSelectionChange`, `onStatus`, and `onInputError`.
+Callbacks include `onGeometry`, `onRoleChange`, `onTitleChange`, `onSizingChange`, `onStats`,
+`onProgressChange`, `onShellIntegrationChange`, `onViewportChange`, `onSelectionChange`, `onStatus`, and `onInputError`.
+
+### Live read-only views
+
+Call `terminal.setReadOnly(true)` to disable application input on an already
+mounted view. `terminal.readOnly`, `inputContext.readOnly`, and selection UI
+notifications reflect the new policy. Use `setReadOnly(false)` to re-enable input;
+neither call remounts, reconnects, releases the peer's primary role, or changes
+the server's current grid. A writable primary resumes automatic sizing requests.
+Mutating the original `options.readOnly` after mount has no effect.
+
+Read-only blocks keyboard/text/IME input, application mouse reports, direct
+`paste()`/`pasteClipboard()`, the paste paths of `runAction()`, `resize()`,
+`setSizing()`, `requestPrimary()`, and automatic resize requests. Explicit input
+methods throw when disabled; DOM application input is not forwarded. Routing
+overrides cannot bypass this policy. Custom actions can still run local operations,
+but any terminal input method they call remains gated.
+
+Active pointer capture and queued mouse movement, pending composition, queued
+resize, and pending clipboard pastes are cancelled on policy change. Quickly
+re-enabling input does not revive a previously pending paste. Commands already
+dispatched cannot be recalled. Output, local selection gestures, history
+navigation, resync, and copying remain available, including a copy already in
+progress. UI notifications follow their usual coalescing rules.
+
+```ts
+import { WebTerminal } from "@hex1b/web-terminal";
+
+const container = document.getElementById("terminal");
+const inputEnabled = document.querySelector<HTMLInputElement>("#input-enabled");
+if (!container || !inputEnabled) throw new Error("Missing terminal controls");
+
+const terminal = await WebTerminal.mount(container, {
+  url: "/ws/terminal",
+  readOnly: !inputEnabled.checked
+});
+inputEnabled.addEventListener("change", () => terminal.setReadOnly(!inputEnabled.checked));
+```
+
+**Client policy is not authorization.** Enforce it independently on each server
+view with `Hwt1PresentationAdapter.IsReadOnly`, initially or at runtime. For
+example, in the host's existing connection setup (C# snippet):
+
+```csharp
+var presentation = new Hwt1PresentationAdapter { IsReadOnly = true };
+// Attach this presentation to the view's terminal and drive its existing transport loops.
+// Only trusted host policy should grant writes:
+presentation.IsReadOnly = false;
+```
+
+The adapter ignores producer-mutating browser input, resize, and primary requests
+while read-only, but still processes acknowledgements, resync, history, selection,
+and copy. This is **per presentation**, not a producer-wide input lock: direct
+terminal automation and other authorized viewers continue. A policy change does
+not retract a command the adapter already accepted. The host must update both its
+server policy and browser UX; client changes do not authorize themselves, and the
+server property does not automatically change client UI.
+
+### Workload titles
+
+The read-only `terminal.title` is the current presented workload title. An empty
+string means unset or explicitly cleared; choose your own fallback. The optional
+`onTitleChange(title)` callback runs once with the first authoritative presented
+value, **including `""`, before mount resolves**. The getter is updated before
+the callback. Later notifications report only distinct presented values. Identical
+updates, same-title resyncs, cursor blinking, and statistics do not notify again.
+Intermediate workload changes can coalesce; this is not an event for every OSC
+sequence.
+
+```ts
+import { WebTerminal } from "@hex1b/web-terminal";
+
+const container = document.getElementById("terminal");
+const header = document.getElementById("terminal-header");
+if (!container || !header) throw new Error("Missing terminal elements");
+const resourceName = "Build service";
+
+const terminal = await WebTerminal.mount(container, {
+  url: "/ws/terminal",
+  onTitleChange(title) {
+    header.textContent = title || resourceName;
+  }
+});
+console.log(terminal.title);
+```
+
+The callback uses elements and fallback text captured **before** mounting, not
+the still-pending `terminal` result. The component does not change `document.title`,
+your header, or the input's accessible `label` automatically. There is no title
+subscription method or DOM title event.
+
+Titles are normalized by the core to at most 4,096 UTF-16 code units, with C0,
+DEL, and C1 controls removed, malformed surrogates replaced with U+FFFD, and
+truncation at a Unicode scalar boundary. They remain **untrusted text**: markup
+and bidi characters are preserved. Use `textContent`, not `innerHTML`; apply your
+own presentation and bidi policies.
+
+OSC 0 and OSC 2 set or explicitly clear the window title; OSC 1 is icon-only.
+Use `ESC ] 0 ; text BEL` or `ESC ] 2 ; text BEL`; `ESC \` (ST) may replace BEL.
+The UTF-8 input path also accepts Unicode C1 OSC (`U+009D`) and ST (`U+009C`).
+Semicolons within `text` are literal. Existing OSC 22/23 saved-title extensions
+update the same state, including after a late HMP1 attachment.
+RIS, soft reset, screen clearing, and buffer switching preserve the title and
+existing saved-title behavior. History inspection retains the current workload
+title rather than a title associated with an old row.
+
+Disconnect and disposal retain the last known title without a synthetic clear.
+Disposal (including abort) stops title callbacks. Attach a new view to reconnect;
+it receives its own initial current title. Preliminary disconnected relay frames
+do not trigger the initial notification. Callbacks run directly like the other
+state callbacks; thrown host errors are not swallowed or retried.
+
+The required title field needs the matching server build. Missing or malformed
+title metadata fails the connection; an older server is not silently treated as
+an empty title.
+The per-title bound is not a limit on all parser buffering or saved-stack depth.
+An HMP1 snapshot with too much saved title state fails its 16 MiB replay limit
+rather than silently discarding saved titles.
+
+### Application progress and shell activity
+
+`terminal.progress` exposes OSC 9;4 state as `{ state, percentage }`.
+The states are `"none"`, `"normal"`, `"error"`, `"indeterminate"`, and `"warning"`.
+Normal/error/warning percentages are integers from 0 through 100. None and
+indeterminate have `percentage: null`; none means the host should hide its indicator.
+This is application-reported progress, not inferred from output or CPU activity.
+It is independent of `ProgressWidget`, which draws inside terminal cells.
+
+`terminal.shellIntegration` exposes OSC 133 as `{ phase, lastExitCode }`.
+The phases are `"unknown"`, `"prompt"` (A), `"commandLine"` (B),
+`"executing"` (C), and `"finished"` (D). B means input after the prompt, **not**
+command execution. Unknown does not mean idle. `lastExitCode` is a signed
+32-bit integer, or null when no status was reported; null is not success.
+A/B/C preserve the last reported result, and D replaces it, including clearing
+it to null when the shell omits its status. No command text, history, or output
+locations are retained by these APIs.
+
+Both getters return defensive copies. Their callbacks receive the first
+authoritative presented state before mount resolves, then distinct presented
+changes. Both getters are updated before either activity callback. Callbacks
+use the same direct, synchronous host-callback convention as title changes;
+host exceptions are not swallowed or retried.
+
+Frames coalesce: the browser might see only Finished for a fast command, or
+miss an entire command whose final state is unchanged. These callbacks are
+**current-state notifications, not a lossless start/finish event stream**.
+Resync/replay never invent commands, unchanged state does not notify again,
+and a new mount receives its own baseline.
+
+This example creates optional chrome outside the terminal:
+
+```ts
+import { WebTerminal } from "@hex1b/web-terminal";
+
+const status = document.createElement("span");
+const progress = document.createElement("progress");
+progress.max = 100;
+progress.hidden = true;
+const container = document.createElement("div");
+container.style.cssText = "width:800px;height:480px";
+document.body.append(status, progress, container);
+
+const terminal = await WebTerminal.mount(container, {
+  url: "/ws/terminal",
+  onProgressChange(value) {
+    progress.hidden = value.state === "none";
+    progress.dataset.state = value.state; // Host CSS can distinguish error/warning.
+    if (value.percentage === null) progress.removeAttribute("value");
+    else progress.value = value.percentage;
+  },
+  onShellIntegrationChange(value) {
+    status.textContent = value.phase +
+      (value.lastExitCode === null ? "" : ` (last exit ${value.lastExitCode})`);
+  },
+  onStats(stats) {
+    if (!stats.connected) {
+      progress.hidden = true;
+      status.textContent = "Disconnected";
+    }
+  }
+});
+console.log(terminal.progress, terminal.shellIntegration);
+```
+
+No title, document chrome, or progress UI is changed automatically by the
+component. The sample endpoint must be supplied by your application.
+Callbacks can run before the `terminal` variable is assigned; use their
+arguments during initial mounting.
+
+RIS resets progress to None and shell integration to Unknown. Soft reset,
+screen clearing, resize, and buffer switches preserve them. OSC 9;4 state 0
+clears only progress; a shell completion does not implicitly clear it.
+Disconnect, process exit, and disposal retain the last reported values
+without inventing a completion or progress clear. Check `connected` before
+showing active chrome, and remount to reconnect. Disposal stops callbacks.
+Snapshots and historical viewports carry current activity, not activity at
+the time a particular row was printed.
+
+The core accepts BEL, ESC-backslash ST, and decoded Unicode C1 terminators
+through its UTF-8 input path. Determinate progress requires unsigned decimal
+0-100; clear/indeterminate allow an omitted percentage and ignore its optional
+value. OSC 133 supports the basic A/B/C forms and D with an optional signed
+decimal exit status (an empty field also means no status). Missing required,
+malformed, overflowed, excess, or unsupported arguments do not change state.
+The raw-output presentation path still forwards the original sequences to
+supporting outer terminals. Required activity metadata needs the matching
+server build; invalid/missing wire fields fail the connection, not silently
+fall back to default state.
 
 ## Input and clipboard
 
@@ -172,6 +460,20 @@ actions reject if selection/input/focus changes before their asynchronous work
 can be applied safely. Errors are surfaced rather than silently reported as
 successful copies or pastes.
 
+### Hyperlinks
+
+Hold Ctrl or Cmd and click an OSC 8 hyperlink to open its destination in a new
+tab. Hovering shows the destination and activation hint; holding the modifier
+also shows a pointer cursor. Links work in live output, scrollback, and read-only
+views. Plain clicks and drags retain their existing selection/application
+behavior, and explicit input-policy routes or actions take precedence.
+Shift and Alt/Option continue to reserve selection gestures.
+
+Only absolute `http:`, `https:`, and `mailto:` destinations are activated
+(`mailto:` handling depends on the browser). New tabs use `noopener,noreferrer`.
+Script, data, file, relative, and custom-scheme URLs are not activated.
+Plain URL text is not automatically detected; the workload must emit OSC 8.
+
 ## Selection UI hooks
 
 `onSelectionUI` receives a typed `SelectionUIEvent`, also dispatched as the
@@ -239,5 +541,6 @@ Only `dist/`, this README, the MIT license, and package metadata are shipped.
 A prepared tarball is self-contained and can be published with
 `npm publish ./hex1b-web-terminal-<version>.tgz --ignore-scripts`; it does not
 need development sources or build scripts. The package name is always
-`@hex1b/web-terminal`, including GitHub Packages. Registry selection is left to
-the caller; no registry is pinned in `package.json`.
+`@hex1b/web-terminal`. CI publishes main/release builds to npmjs; PR builds
+provide the tarball as the `npm-web-terminal` workflow artifact and do not
+publish it to a registry. No registry is pinned in `package.json`.

package/dist/backend-selection.d.ts

@@ -0,0 +1,7 @@
+import type { RenderBackend } from "./render-backend.js";
+import type { TerminalRendererPreference } from "./types.js";
+export declare function createRenderBackend(canvas: OffscreenCanvas, onFatal: (error: Error) => void, preference?: TerminalRendererPreference): Promise<{
+    backend: RenderBackend;
+    fallbackReason?: string;
+}>;
+//# sourceMappingURL=backend-selection.d.ts.map

package/dist/backend-selection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend-selection.d.ts","sourceRoot":"","sources":["../src/backend-selection.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAIzD,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AAE7D,wBAAsB,mBAAmB,CAAC,MAAM,EAAE,eAAe,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,EAChG,UAAU,GAAE,0BAAmC,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,aAAa,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAe/G"}

package/dist/backend-selection.js

@@ -0,0 +1,23 @@
+import { RendererUnavailableError } from "./render-backend.js";
+import { normalizeRenderer } from "./renderer-options.js";
+import { WebGpuBackend } from "./webgpu-backend.js";
+import { WebGl2Backend } from "./webgl2-backend.js";
+export async function createRenderBackend(canvas, onFatal, preference = "auto") {
+    const requested = normalizeRenderer(preference);
+    if (requested === "webgl2")
+        return { backend: await WebGl2Backend.create(canvas, onFatal) };
+    try {
+        return { backend: await WebGpuBackend.create(canvas, onFatal) };
+    }
+    catch (error) {
+        if (requested !== "auto" || !(error instanceof RendererUnavailableError))
+            throw error;
+        try {
+            return { backend: await WebGl2Backend.create(canvas, onFatal), fallbackReason: error.message };
+        }
+        catch (fallbackError) {
+            throw new AggregateError([error, fallbackError], `WebGPU unavailable (${error.message}); WebGL2 initialization failed: ${fallbackError instanceof Error ? fallbackError.message : String(fallbackError)}`);
+        }
+    }
+}
+//# sourceMappingURL=backend-selection.js.map

package/dist/backend-selection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend-selection.js","sourceRoot":"","sources":["../src/backend-selection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAE/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGpD,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,MAAuB,EAAE,OAA+B,EAChG,aAAyC,MAAM;IAC/C,MAAM,SAAS,GAAG,iBAAiB,CAAC,UAAU,CAAC,CAAC;IAChD,IAAI,SAAS,KAAK,QAAQ;QAAE,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IAC5F,IAAI,CAAC;QACH,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IAClE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,SAAS,KAAK,MAAM,IAAI,CAAC,CAAC,KAAK,YAAY,wBAAwB,CAAC;YAAE,MAAM,KAAK,CAAC;QACtF,IAAI,CAAC;YACH,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC;QACjG,CAAC;QAAC,OAAO,aAAa,EAAE,CAAC;YACvB,MAAM,IAAI,cAAc,CAAC,CAAC,KAAK,EAAE,aAAa,CAAC,EAC7C,uBAAuB,KAAK,CAAC,OAAO,oCAClC,aAAa,YAAY,KAAK,CAAC,CAAC,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC;QACxF,CAAC;IACH,CAAC;AACH,CAAC","sourcesContent":["import { RendererUnavailableError } from \"./render-backend.js\";\nimport type { RenderBackend } from \"./render-backend.js\";\nimport { normalizeRenderer } from \"./renderer-options.js\";\nimport { WebGpuBackend } from \"./webgpu-backend.js\";\nimport { WebGl2Backend } from \"./webgl2-backend.js\";\nimport type { TerminalRendererPreference } from \"./types.js\";\n\nexport async function createRenderBackend(canvas: OffscreenCanvas, onFatal: (error: Error) => void,\n  preference: TerminalRendererPreference = \"auto\"): Promise<{ backend: RenderBackend; fallbackReason?: string }> {\n  const requested = normalizeRenderer(preference);\n  if (requested === \"webgl2\") return { backend: await WebGl2Backend.create(canvas, onFatal) };\n  try {\n    return { backend: await WebGpuBackend.create(canvas, onFatal) };\n  } catch (error) {\n    if (requested !== \"auto\" || !(error instanceof RendererUnavailableError)) throw error;\n    try {\n      return { backend: await WebGl2Backend.create(canvas, onFatal), fallbackReason: error.message };\n    } catch (fallbackError) {\n      throw new AggregateError([error, fallbackError],\n        `WebGPU unavailable (${error.message}); WebGL2 initialization failed: ${\n          fallbackError instanceof Error ? fallbackError.message : String(fallbackError)}`);\n    }\n  }\n}\n"]}

package/dist/hyperlinks.d.ts

@@ -0,0 +1,10 @@
+import type { TerminalPoint } from "./types.js";
+import type { HyperlinkRange } from "./wire-types.js";
+/** OSC 8 destinations are untrusted output, not page-relative navigation. */
+export declare function hyperlinkUri(uri: string): string | null;
+export declare class Hyperlinks {
+    #private;
+    update(ranges: readonly HyperlinkRange[]): void;
+    at(point: TerminalPoint): string | null;
+}
+//# sourceMappingURL=hyperlinks.d.ts.map

package/dist/hyperlinks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hyperlinks.d.ts","sourceRoot":"","sources":["../src/hyperlinks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtD,6EAA6E;AAC7E,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAIvD;AAED,qBAAa,UAAU;;IAGrB,MAAM,CAAC,MAAM,EAAE,SAAS,cAAc,EAAE,GAAG,IAAI;IAa/C,EAAE,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,GAAG,IAAI;CAIxC"}

package/dist/hyperlinks.js

@@ -0,0 +1,28 @@
+/** OSC 8 destinations are untrusted output, not page-relative navigation. */
+export function hyperlinkUri(uri) {
+    if (/[\u0000-\u0020\u007f]/u.test(uri) || !URL.canParse(uri))
+        return null;
+    const url = new URL(uri);
+    return ["https:", "http:", "mailto:"].includes(url.protocol) ? url.href : null;
+}
+export class Hyperlinks {
+    #rows = new Map();
+    update(ranges) {
+        this.#rows.clear();
+        const destinations = new Map();
+        for (const range of ranges) {
+            if (!destinations.has(range.uri))
+                destinations.set(range.uri, hyperlinkUri(range.uri));
+            const uri = destinations.get(range.uri);
+            if (!uri)
+                continue;
+            const row = this.#rows.get(range.row) ?? [];
+            row.push({ ...range, uri });
+            this.#rows.set(range.row, row);
+        }
+    }
+    at(point) {
+        return this.#rows.get(point.y)?.find(range => point.x >= range.startColumn && point.x < range.endColumn)?.uri ?? null;
+    }
+}
+//# sourceMappingURL=hyperlinks.js.map

package/dist/hyperlinks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hyperlinks.js","sourceRoot":"","sources":["../src/hyperlinks.ts"],"names":[],"mappings":"AAGA,6EAA6E;AAC7E,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,IAAI,wBAAwB,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1E,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACzB,OAAO,CAAC,QAAQ,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;AACjF,CAAC;AAED,MAAM,OAAO,UAAU;IACrB,KAAK,GAAG,IAAI,GAAG,EAA4B,CAAC;IAE5C,MAAM,CAAC,MAAiC;QACtC,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QACnB,MAAM,YAAY,GAAG,IAAI,GAAG,EAAyB,CAAC;QACtD,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC;gBAAE,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,EAAE,YAAY,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;YACvF,MAAM,GAAG,GAAG,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YACxC,IAAI,CAAC,GAAG;gBAAE,SAAS;YACnB,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;YAC5C,GAAG,CAAC,IAAI,CAAC,EAAE,GAAG,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;YAC5B,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QACjC,CAAC;IACH,CAAC;IAED,EAAE,CAAC,KAAoB;QACrB,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,EAAE,CAC3C,KAAK,CAAC,CAAC,IAAI,KAAK,CAAC,WAAW,IAAI,KAAK,CAAC,CAAC,GAAG,KAAK,CAAC,SAAS,CAAC,EAAE,GAAG,IAAI,IAAI,CAAC;IAC5E,CAAC;CACF","sourcesContent":["import type { TerminalPoint } from \"./types.js\";\nimport type { HyperlinkRange } from \"./wire-types.js\";\n\n/** OSC 8 destinations are untrusted output, not page-relative navigation. */\nexport function hyperlinkUri(uri: string): string | null {\n  if (/[\\u0000-\\u0020\\u007f]/u.test(uri) || !URL.canParse(uri)) return null;\n  const url = new URL(uri);\n  return [\"https:\", \"http:\", \"mailto:\"].includes(url.protocol) ? url.href : null;\n}\n\nexport class Hyperlinks {\n  #rows = new Map<number, HyperlinkRange[]>();\n\n  update(ranges: readonly HyperlinkRange[]): void {\n    this.#rows.clear();\n    const destinations = new Map<string, string | null>();\n    for (const range of ranges) {\n      if (!destinations.has(range.uri)) destinations.set(range.uri, hyperlinkUri(range.uri));\n      const uri = destinations.get(range.uri);\n      if (!uri) continue;\n      const row = this.#rows.get(range.row) ?? [];\n      row.push({ ...range, uri });\n      this.#rows.set(range.row, row);\n    }\n  }\n\n  at(point: TerminalPoint): string | null {\n    return this.#rows.get(point.y)?.find(range =>\n      point.x >= range.startColumn && point.x < range.endColumn)?.uri ?? null;\n  }\n}\n"]}

package/dist/mouse-input.d.ts

@@ -14,9 +14,12 @@ interface MouseInspection {
     execute?: (decision: Extract<InputDecision, {
         action: unknown;
     }>, input: TerminalInput) => void;
+    hyperlink?: (point: TerminalPoint) => string | null;
+    openHyperlink?: (uri: string) => void;
 }
 export interface MouseCapture {
     update(columns: number, rows: number, tracking: MouseTrackingMode): void;
+    refresh(): void;
     cancel(): void;
     dispose(): void;
 }

package/dist/mouse-input.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mouse-input.d.ts","sourceRoot":"","sources":["../src/mouse-input.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAmB,iBAAiB,EAAiB,aAAa,EAC3F,aAAa,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,KAAK,EAA6B,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAK/E,UAAU,eAAe;IACvB,KAAK,CAAC,EAAE,MAAM,IAAI,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;IAC7C,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE;QAAE,IAAI,EAAE,aAAa,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAC;IAC5F,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;IACxC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,aAAa,KAAK,IAAI,CAAC;IAC3D,GAAG,CAAC,EAAE,CAAC,SAAS,EAAE,OAAO,KAAK,IAAI,CAAC;IACnC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,aAAa,CAAC;IAClD,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,CAAC,aAAa,EAAE;QAAE,MAAM,EAAE,OAAO,CAAA;KAAE,CAAC,EAAE,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;CACjG;AACD,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACzE,MAAM,IAAI,IAAI,CAAC;IACf,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,oFAAoF;AACpF,wBAAgB,YAAY,CAAC,MAAM,EAAE,iBAAiB,EAAE,IAAI,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK,IAAI,EAC3F,KAAK,EAAE,MAAM,IAAI,EAAE,UAAU,GAAE,eAAoB,GAAG,YAAY,CA+SnE"}
+{"version":3,"file":"mouse-input.d.ts","sourceRoot":"","sources":["../src/mouse-input.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAmB,iBAAiB,EAAiB,aAAa,EAC3F,aAAa,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,KAAK,EAA6B,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAM/E,UAAU,eAAe;IACvB,KAAK,CAAC,EAAE,MAAM,IAAI,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;IAC7C,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE;QAAE,IAAI,EAAE,aAAa,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAC;IAC5F,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;IACxC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,aAAa,KAAK,IAAI,CAAC;IAC3D,GAAG,CAAC,EAAE,CAAC,SAAS,EAAE,OAAO,KAAK,IAAI,CAAC;IACnC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,aAAa,CAAC;IAClD,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,CAAC,aAAa,EAAE;QAAE,MAAM,EAAE,OAAO,CAAA;KAAE,CAAC,EAAE,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;IAChG,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,MAAM,GAAG,IAAI,CAAC;IACpD,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CACvC;AACD,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACzE,OAAO,IAAI,IAAI,CAAC;IAChB,MAAM,IAAI,IAAI,CAAC;IACf,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,oFAAoF;AACpF,wBAAgB,YAAY,CAAC,MAAM,EAAE,iBAAiB,EAAE,IAAI,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK,IAAI,EAC3F,KAAK,EAAE,MAAM,IAAI,EAAE,UAAU,GAAE,eAAoB,GAAG,YAAY,CA2WnE"}

package/dist/mouse-input.js

@@ -24,10 +24,27 @@ export function captureMouse(canvas, send, focus, inspection = {}) {
     let completedClick;
     let routedGesture;
     let contextMenuRoute;
+    let hyperlinkClick;
+    let hoverEvent;
+    let hoverModifiers;
+    const originalTitle = canvas.title;
+    const originalCursor = canvas.style.cursor;
     const state = () => ({ tracking, ...inspection.state?.() });
     function point(event, clamp = false) {
         return cellPoint(event, canvas.getBoundingClientRect(), columns, rows, clamp);
     }
+    function refreshHover(modifiers = hoverModifiers) {
+        if (!inspection.hyperlink)
+            return;
+        hoverModifiers = modifiers;
+        const position = hoverEvent && point(hoverEvent);
+        const uri = position ? inspection.hyperlink(position) : null;
+        canvas.title = uri ? `${uri}\nCtrl/Cmd+click to open link` : originalTitle;
+        canvas.style.cursor = uri && modifiers && (modifiers.ctrlKey || modifiers.metaKey) &&
+            !modifiers.altKey && !modifiers.shiftKey ? "pointer" : originalCursor;
+        if (hyperlinkClick && hyperlinkClick.uri !== uri)
+            hyperlinkClick.dragged = true;
+    }
     function updateAutoScroll() {
         clearTimeout(autoScroll);
         autoScroll = undefined;
@@ -83,6 +100,7 @@ export function captureMouse(canvas, send, focus, inspection = {}) {
         pointerEvent = undefined;
         selectionClick = undefined;
         completedClick = undefined;
+        hyperlinkClick = undefined;
         gesture.end();
         routedGesture = undefined;
         if (report)
@@ -115,6 +133,8 @@ export function captureMouse(canvas, send, focus, inspection = {}) {
         if (!position)
             return;
         if (pointerId !== null) {
+            if (hyperlinkClick)
+                hyperlinkClick.dragged = true;
             if (routedGesture !== InputRoute.Browser)
                 event.preventDefault();
             if ((gesture.owner === "app" || routedGesture === InputRoute.Application) && pointerId === event.pointerId)
@@ -125,8 +145,20 @@ export function captureMouse(canvas, send, focus, inspection = {}) {
         const input = { type: "pointer", button: pointerButtons[event.button],
             point: Object.freeze({ ...position }), ...inputModifiers(event) };
         const decision = inspection.resolve?.(input) ?? { route: InputRoute.Continue };
-        const route = decision.action !== undefined ? InputRoute.Consume : decision.route;
+        let route = decision.action !== undefined ? InputRoute.Consume : decision.route;
+        if (route === InputRoute.Continue && event.button === 0 && (event.ctrlKey || event.metaKey) &&
+            !event.altKey && !event.shiftKey) {
+            const uri = inspection.hyperlink?.(position);
+            if (uri) {
+                hyperlinkClick = { uri, x: event.clientX, y: event.clientY, dragged: false };
+                route = InputRoute.Consume;
+            }
+        }
         contextMenuRoute = event.button === 2 ? route : undefined;
+        if (hyperlinkClick)
+            contextMenuRoute = InputRoute.Consume;
+        hoverEvent = event;
+        refreshHover(event);
         if (route !== InputRoute.Continue) {
             completedClick = selectionClick = undefined;
             click.count = 0;
@@ -186,6 +218,10 @@ export function captureMouse(canvas, send, focus, inspection = {}) {
             return;
         if (pointerId !== null && pointerId !== event.pointerId)
             return;
+        hoverEvent = event;
+        refreshHover(event);
+        if (hyperlinkClick && Math.hypot(event.clientX - hyperlinkClick.x, event.clientY - hyperlinkClick.y) >= 4)
+            hyperlinkClick.dragged = true;
         const position = point(event, pointerId !== null);
         if (!position)
             return;
@@ -224,6 +260,21 @@ export function captureMouse(canvas, send, focus, inspection = {}) {
     canvas.addEventListener("pointerup", event => {
         if (pointerId !== event.pointerId)
             return;
+        if (hyperlinkClick) {
+            event.preventDefault();
+            const link = hyperlinkClick;
+            const position = point(event);
+            const activate = event.button === 0 && event.buttons === 0 && !link.dragged &&
+                Math.hypot(event.clientX - link.x, event.clientY - link.y) < 4 &&
+                position && inspection.hyperlink?.(position) === link.uri;
+            if (event.buttons === 0)
+                cancel(false, false);
+            else
+                link.dragged = true;
+            if (activate)
+                inspection.openHyperlink?.(link.uri);
+            return;
+        }
         const position = point(event, true) ?? lastPoint;
         if (routedGesture) {
             if (routedGesture === InputRoute.Application && position)
@@ -262,11 +313,21 @@ export function captureMouse(canvas, send, focus, inspection = {}) {
             inspection.begin?.(completed.point, { mode, extend: false });
     }, options);
     canvas.addEventListener("pointercancel", () => cancel(), options);
+    canvas.addEventListener("pointerleave", () => {
+        hoverEvent = undefined;
+        refreshHover();
+    }, options);
     canvas.addEventListener("lostpointercapture", () => {
         if (pointerId !== null)
             cancel();
     }, options);
-    window.addEventListener("blur", () => cancel(), options);
+    window.addEventListener("blur", () => {
+        cancel();
+        hoverEvent = undefined;
+        refreshHover();
+    }, options);
+    window.addEventListener("keydown", event => refreshHover(event), { ...options, capture: true });
+    window.addEventListener("keyup", event => refreshHover(event), { ...options, capture: true });
     canvas.addEventListener("contextmenu", event => {
         if (contextMenuRoute !== undefined && contextMenuRoute !== InputRoute.Continue) {
             const route = contextMenuRoute;
@@ -279,6 +340,8 @@ export function captureMouse(canvas, send, focus, inspection = {}) {
             event.preventDefault();
     }, options);
     canvas.addEventListener("wheel", event => {
+        if (hyperlinkClick)
+            hyperlinkClick.dragged = true;
         const input = { type: "wheel", deltaX: event.deltaX, deltaY: event.deltaY,
             deltaMode: event.deltaMode, point: point(event), ...inputModifiers(event) };
         const decision = pointerId === null
@@ -345,11 +408,15 @@ export function captureMouse(canvas, send, focus, inspection = {}) {
                 rows = nextRows;
                 tracking = nextTracking;
             }
+            refreshHover();
         },
+        refresh() { refreshHover(); },
         cancel() { cancel(); },
         dispose() {
             cancel(false);
             listeners.abort();
+            canvas.title = originalTitle;
+            canvas.style.cursor = originalCursor;
         }
     };
 }