@cplieger/web-terminal-ui 7.0.6 → 7.1.0

package/README.md

@@ -186,7 +186,27 @@ want one, for example Ctrl+L); `reattach()` attaches again to whatever the serve
 serves now, for a session that has ended (see "When a session ends"); and
 `destroy()` tears every feature down and releases the kernel.
 
-### Persisting scrollback across a discard
+### Mouse and focus
+
+A terminal application that turns mouse tracking on receives the clicks, drags
+and wheel gestures a user makes in the browser, as SGR reports. The pointer says
+so while that is happening: at rest the grid carries a text cursor, and while an
+application holds the mouse the grid and any links in it carry an arrow instead,
+because a click is reported to that application rather than selecting text or
+opening the link. Shift-drag still selects and shift-click still opens a link,
+which is the convention xterm set, so nothing becomes unreachable.
+
+Mouse input is best-effort, as it is in every terminal: a report says where the
+pointer is at that moment and carries nothing a receiver could use to notice it
+had gone stale, so a report made while the socket is down is dropped rather than
+delivered late against a screen that has since been repainted. Typed input keeps
+its delivery guarantee and is unaffected.
+
+Focus reporting is the server's answer rather than this UI's. The kernel tells
+the server whether its own terminal widget holds focus and the server decides
+what the application is told, so several devices attached to one session cannot
+contradict each other. A blur that a press causes and that the same gesture's
+click undoes is not reported, because the terminal did not lose focus.
 
 `persistScrollback` takes the storage, not a switch, because storage is a
 decision this library should not make for you. Chrome's page-lifecycle guidance
@@ -358,8 +378,19 @@ completed feature and core listener, clears the broken subtree, and shows the
 panel. If `createTerminal` itself throws (`phase: "kernel-init"`: an
 unresolvable mount selector, a preset that throws, an invalid feature list, a DOM
 invariant), it shows the same panel and then rethrows, so a caller with its own
-error handling still sees the error. Either way the panel is modal when the
-terminal owns the viewport and non-modal when it fills an embedded container.
+error handling still sees the error.
+
+The panel is a native `<dialog>`. In `viewport` layout it opens with
+`showModal()`, so the rest of your document is inert while it is up; in
+`container` layout it opens non-modally, so the application around an embedded
+terminal keeps working and keeps its focusables. Escape does not dismiss it in
+either mode: the terminal is already gone, so there would be nothing behind it
+and no way back. Reload is the recovery.
+
+One visible consequence in `viewport` layout: a modal dialog is in the browser's
+top layer, above every `z-index` in the document, so the panel now paints over
+your loading overlay instead of under it. It appears at once and the overlay's
+fade-out finishes behind it.
 
 **This is why `target` takes a selector and `features` takes a function.** Both
 are resolved INSIDE that boundary. Written the other way round

package/css/02-terminal.css

@@ -149,6 +149,11 @@
      kernel focus handling + contextMenu feature). */
   user-select: text;
   -webkit-touch-callout: default;
+
+  /* Stated rather than inherited: the UA default over text is already an I-beam,
+     but the tracking rule below has to have something deterministic to override
+     (and to hand back to). */
+  cursor: text;
 }
 
 /* IME composition view: floating overlay positioned at the cursor
@@ -327,6 +332,18 @@
   --bg: var(--text-default);
 }
 
+/* An application holds the mouse (DEC 1000/1002/1003) and the kernel toggles
+   .wt-mouse-app on the scroll container. A plain click is reported to that
+   application, so neither the I-beam nor the link's pointer is true any longer:
+   both promise something the click no longer does. Deliberately no
+   `user-select: none` here, because the engine hands a shifted gesture to the
+   browser, so shift+drag selecting and shift+click opening a link are the only
+   ways left to reach either and blanketing selection off would remove them. */
+:where(.wt-root) .term.wt-mouse-app .term-output,
+:where(.wt-root) .term.wt-mouse-app .term-link {
+  cursor: default;
+}
+
 :where(.wt-root) .term-blink {
   animation: wt-blink-anim 1s step-end infinite;
 }

package/css/10-primitives.css

@@ -133,13 +133,26 @@
    Feature setup is part of the kernel composition contract. If it fails, the
    kernel removes the half-live terminal and fills only its own layout boundary
    with this recovery surface. In container mode that leaves the host app
-   outside the terminal fully visible and interactive. */
+   outside the terminal fully visible and interactive.
+
+   The surface is a native <dialog>: showModal() in wt-viewport, the bare `open`
+   attribute in wt-container. Modality is the only difference between them. */
 :where(.wt-root) .wt-fatal {
   position: absolute;
   inset: 0;
-  z-index: 100;
-  display: grid;
-  place-items: center;
+  /* The size resets are what let the insets stretch the panel: a <dialog> is
+     fit-content with the UA sheet's own `margin: auto`, and :modal additionally
+     caps both axes at calc(100% - 38px). margin, border-radius and box-shadow
+     answer an EMBEDDER's own `dialog { ... }` base rule rather than the UA sheet —
+     margin is the member that moves the box, the other two are cosmetic. */
+  margin: 0;
+  border: none;
+  border-radius: 0;
+  box-shadow: none;
+  inline-size: auto;
+  block-size: auto;
+  max-inline-size: none;
+  max-block-size: none;
   overflow: auto;
   padding: calc(var(--safe-top) + var(--sp-3)) var(--sp-3) calc(var(--safe-bottom) + var(--sp-3));
   background: var(--bg);
@@ -148,6 +161,39 @@
   text-align: center;
 }
 
+/* Scoped to [open]: an author `display` beats the UA's `dialog { display: none }`
+   at any specificity, so declared unconditionally a CLOSED panel would still
+   paint its full-surface background over the root. */
+:where(.wt-root) .wt-fatal[open] {
+  display: grid;
+  place-items: center;
+}
+
+/* The base rule's `position: absolute` serves the container half (it resolves
+   against .wt-root.wt-container, the embedder's box); this gives the viewport back
+   to the modal half. A top-layer absolute resolves against the initial containing
+   block — viewport-SIZED but canvas-anchored, so equivalent to fixed only at
+   scrollY 0 — and Blink does not lock document scrolling under a modal dialog.
+   Pinned by fatal-panel.test.ts's scrolled-document test. */
+:where(.wt-root) .wt-fatal:modal {
+  position: fixed;
+}
+
+/* The stacking order the top layer supplies for free, so it is declared only for
+   the half that is not in it. .wt-root.wt-container is the EMBEDDER's element and
+   forms no stacking context, so the panel competes in the host's. */
+:where(.wt-root) .wt-fatal:not(:modal) {
+  z-index: 100;
+}
+
+/* The panel IS the dim — it fills its whole surface in --bg — so the backdrop
+   agrees with it instead of adding a second, differently coloured layer. The UA's
+   rgba(0, 0, 0, 0.1) would show as a lighter seam if the panel were ever smaller
+   than the viewport. */
+:where(.wt-root) .wt-fatal::backdrop {
+  background: var(--bg);
+}
+
 :where(.wt-root) .wt-fatal-card {
   inline-size: min(100%, 28rem);
   padding: clamp(1.25rem, 5vi, 2rem);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-ui",
-  "version": "7.0.6",
+  "version": "7.1.0",
   "type": "module",
   "description": "Reference touch-first browser UI for @cplieger/web-terminal-engine: a composable kernel + feature modules (tabs, activity monitor, mobile toolbar, context menu, IME, predictive echo, viewport handling) and CSS. One createTerminal() call.",
   "license": "MPL-2.0",
@@ -40,7 +40,7 @@
     "verify": "bash scripts/verify.sh"
   },
   "peerDependencies": {
-    "@cplieger/web-terminal-engine": "^5.0.3"
+    "@cplieger/web-terminal-engine": "^5.1.0"
   },
   "overrides": {
     "qs": "^6.15.2"
@@ -50,18 +50,18 @@
     "@stryker-mutator/core": "10.0.0",
     "@stryker-mutator/typescript-checker": "10.0.0",
     "@stryker-mutator/vitest-runner": "10.0.0",
-    "@types/node": "26.4.1",
+    "@types/node": "26.5.0",
     "@typescript/native": "npm:typescript@7.0.2",
     "@vitest/browser": "5.0.0",
     "@vitest/browser-playwright": "5.0.0",
     "@vitest/coverage-v8": "5.0.0",
-    "eslint": "10.9.1",
+    "eslint": "10.10.0",
     "fast-check": "4.9.0",
-    "html-validate": "11.14.0",
-    "knip": "6.34.0",
-    "playwright": "1.62.1",
+    "html-validate": "11.15.0",
+    "knip": "6.35.1",
+    "playwright": "1.63.0",
     "prettier": "3.9.6",
-    "stylelint": "17.14.1",
+    "stylelint": "17.15.0",
     "stylelint-config-standard": "40.0.0",
     "typescript": "npm:@typescript/typescript6@6.0.2",
     "typescript-eslint": "8.69.0",

package/src/kernel/kernel.ts

@@ -13,12 +13,11 @@
 // still single-instance, so createTerminal is called once per page (tabs
 // multiplex sessions over the one kernel, section 22.5).
 //
-// Mouse tracking (engine `mouse` module) is intentionally NOT wired here yet:
-// the design adds it (section 22.3), but wiring it also brings DEC 1004 focus
-// emission, which must be suppressed under the keep-unfocused model (section
-// 7.2). Not wiring it keeps the client emitting no focus bytes (the safe
-// default the previous UI already had); adding mouse tracking with focus
-// suppression is a tracked follow-up.
+// The kernel owns the terminal widget's DOM, so it owns the widget's focus: it
+// REPORTS focus and blur to the transport (`connection.setClientFocus`) and
+// never writes DEC 1004 bytes itself. The server derives the answer for the
+// session from every attached client's report plus its own hold, which is the
+// only place the question can be answered once a second device attaches.
 
 import {
   render,
@@ -26,6 +25,7 @@ import {
   connection,
   keyboard,
   modes,
+  mouse,
   LineStore,
 } from "@cplieger/web-terminal-engine";
 import * as composition from "../composition.js";
@@ -168,17 +168,18 @@ function renderFatalStartupInto(
   layoutMode: "viewport" | "container",
   message: string = STARTUP_FAILURE_COPY.message,
 ): void {
-  const surface = document.createElement("section");
+  const surface = document.createElement("dialog");
   surface.className = "wt-fatal";
+  // alertdialog over the implicit `dialog` role: an urgent message to act on. No
+  // `aria-modal` — showModal() conveys modality; an authored value can contradict the UA.
   surface.setAttribute("role", "alertdialog");
   surface.setAttribute("aria-labelledby", "wt-fatal-title");
   surface.setAttribute("aria-describedby", "wt-fatal-message");
-  if (layoutMode === "viewport") {
-    // A full-page terminal has no usable host UI behind it, so this is the
-    // page's modal recovery state. An embedded terminal is only one panel in
-    // a larger app and must not claim that the rest of the app is inert.
-    surface.setAttribute("aria-modal", "true");
-  }
+  // showModal() makes Escape a close request, and the kernel has already cleared
+  // the root: nothing is behind this panel, so reload is the only recovery.
+  surface.addEventListener("cancel", (ev) => {
+    ev.preventDefault();
+  });
 
   const card = document.createElement("div");
   card.className = "wt-fatal-card";
@@ -201,9 +202,19 @@ function renderFatalStartupInto(
   surface.appendChild(card);
   root.replaceChildren(surface);
 
-  // The terminal input held focus before setup failed. Move that focus to the
-  // only recovery action; container mode remains non-modal because no trap or
-  // aria-modal claim prevents the user from leaving the terminal panel.
+  // Viewport: the terminal IS the page, so the top layer and an inert document
+  // are both accurate; container gets the bare `open` attribute, which is neither
+  // and is what an embedded panel wants. `isConnected` is showModal()'s own
+  // precondition and a detached root arrives here from a typed call, where a
+  // throw would bury the real startup cause under a second error out of the catch.
+  if (layoutMode === "viewport" && surface.isConnected) {
+    surface.showModal();
+  } else {
+    surface.open = true;
+  }
+
+  // The terminal input held focus before setup failed; move it to the only
+  // recovery action. showModal() lands there itself, the non-modal half does not.
   reloadButton.focus();
 }
 
@@ -389,9 +400,9 @@ function buildTerminal(
     // output never does (the scroll controller's follow/hold job is unchanged),
     // so scrolling up to read while output streams is preserved. A no-op on the
     // alt screen (no scrollback) and when already following. NOTE: every caller
-    // of sendBytes today is genuine user input (typed keys, paste, mobile
-    // toolbar); if mouse tracking is ever wired through ctx.send, its motion
-    // bytes must NOT come through here or the view would snap on every move.
+    // of sendBytes is genuine user input (typed keys, paste, mobile toolbar);
+    // mouse reports deliberately bypass this funnel and go out as ephemeral
+    // input, or the view would snap on every motion report.
     scroll.scrollToBottom();
     for (const obs of inputObservers) {
       obs(out);
@@ -564,6 +575,100 @@ function buildTerminal(
   });
   render.updateFontMetrics();
 
+  // A mouse report is BEST-EFFORT and never enters the reliable outbox: it
+  // carries no sequence number, so one retransmitted after a resume describes a
+  // screen since repainted, and `sendEphemeral` refuses rather than queues. Not
+  // sendBytes either: that funnel snaps the view to the bottom on every accepted
+  // byte, so a motion report would jump the viewport. The listeners belong on the
+  // scroll container (a click in its padding or over the reserved scrollbar
+  // gutter never reaches a row, and the wheel has to be cancellable there); the
+  // coordinate frame is the row container, whose box IS the grid.
+  const disposeMouse = mouse.init({
+    sendReport: (data) => connection.sendEphemeral(data),
+    cellSize: render.cellSize,
+    termElement: () => termWrap,
+    gridElement: () => outputEl,
+    // The RENDERED grid, not computeSize(): the row hit test anchors on its
+    // height, and this client's own measurement disagrees with the negotiated
+    // screen whenever a second device is attached or a local resize has not been
+    // answered yet, which would shift every reported row.
+    gridSize: render.gridSize,
+  });
+
+  // A press over the display-only output takes focus off the hidden textarea and
+  // the click handler below puts it back, so that blur/focus pair is an artifact
+  // of this input model, not a focus change the application should be told about.
+  // xterm.js never emits one because its textarea keeps focus through a click on
+  // the terminal. So a blur raised inside a press is withheld and the gesture's
+  // REAL end state is reported once it resolves: nothing when focus came back,
+  // one report when it did not (a live selection, a link and a bare touch tap all
+  // decline to restore it). Measured before this: 3600 focus reports in 90s of
+  // clicking, which reaches an application as FocusLost/FocusGained per click.
+  let pressHoldsFocus = false;
+  let focusResolve: ReturnType<typeof setTimeout> | null = null;
+
+  function reportFocusNow(): void {
+    connection.setClientFocus(
+      document.activeElement !== null && termWrap.contains(document.activeElement),
+    );
+  }
+
+  // Scheduled rather than read at pointerup: the focus restore happens in the
+  // `click` handler, which the browser dispatches after pointerup within the same
+  // task, so a task boundary is the first point where the end state is settled.
+  function endPressFocusGesture(): void {
+    if (focusResolve !== null) {
+      clearTimeout(focusResolve);
+    }
+    focusResolve = setTimeout(() => {
+      focusResolve = null;
+      pressHoldsFocus = false;
+      reportFocusNow();
+    }, 0);
+  }
+
+  // The keyboard target is the hidden textarea INSIDE termWrap, so the widget's
+  // own focus events bubble to here. What goes out is the widget's STATE, not
+  // DEC 1004 bytes: the server derives the answer from this report plus every
+  // other attached client's plus its own hold.
+  termWrap.addEventListener(
+    "focusin",
+    () => {
+      connection.setClientFocus(true);
+    },
+    { signal },
+  );
+  termWrap.addEventListener(
+    "focusout",
+    (ev) => {
+      if (ev.relatedTarget instanceof Node && termWrap.contains(ev.relatedTarget)) {
+        return; // focus moving WITHIN the terminal is not a blur
+      }
+      if (pressHoldsFocus) {
+        return; // this gesture's own doing; endPressFocusGesture reports the truth
+      }
+      connection.setClientFocus(false);
+    },
+    { signal },
+  );
+  // Seeded once, so a terminal mounted with its textarea already focused does not
+  // report blurred until the first real focusin.
+  reportFocusNow();
+
+  // The kernel is the toggler, and the class goes on the scroll container rather
+  // than on the rows: `.term-output` is replaced wholesale by the renderer, and
+  // `.term` is the element that survives every rebuild. What the shape MEANS is
+  // at the CSS rule it drives (css/02-terminal.css).
+  function updateMousePointer(): void {
+    termWrap.classList.toggle("wt-mouse-app", modes.getMouseMode() !== 0);
+  }
+
+  // Derived once here as well as from the two triggers below: the modes module is
+  // a singleton that outlives a terminal, so a re-created terminal on a page
+  // whose mirror already holds a tracking mode would otherwise show the resting
+  // pointer until the next frame.
+  updateMousePointer();
+
   composition.init({
     textarea: input,
     compositionView: compositionViewEl,
@@ -687,6 +792,7 @@ function buildTerminal(
         bus.emit("wire:title", { session: activeSession?.id ?? "", title: msg.title });
       } else if (msg.type === "modes") {
         render.updateReverseVideo();
+        updateMousePointer();
         bus.emit("wire:modes", msg);
       } else if (msg.type === "clipboard") {
         // Inbound OSC 52. With no clipboard feature subscribed this is a no-op
@@ -958,9 +1064,13 @@ function buildTerminal(
       pointerDownX = e.clientX;
       pointerDownY = e.clientY;
       pointerDownTime = e.timeStamp;
+      pressHoldsFocus = true;
     },
     { passive: true, signal },
   );
+  for (const end of ["pointerup", "pointercancel", "lostpointercapture"] as const) {
+    termWrap.addEventListener(end, endPressFocusGesture, { passive: true, signal });
+  }
   termWrap.addEventListener(
     "pointerup",
     (e) => {
@@ -1465,6 +1575,11 @@ function buildTerminal(
     // detach here and the onSwitch attach below.
     composition.cancelComposition();
     resetToPlaceholder(input);
+    // A held mouse gesture is latched input too, and the mouse module is per
+    // TERMINAL while sessions multiplex over it: a record kept across the switch
+    // would let the incoming session's first open synthesize a release for a
+    // press its application never saw.
+    mouse.disarmGesture();
     for (const { instance } of instances) {
       instance.onDetach?.();
     }
@@ -1472,6 +1587,9 @@ function buildTerminal(
     // Reconnect the terminal WS to this session using its per-tab resume
     // state; the renderer was already pointed at its store by the owner.
     connection.setSession(session.id);
+    // setSession restores the incoming session's mode mirror synchronously and
+    // delivers no modes frame, so nothing else re-derives the pointer here.
+    updateMousePointer();
     // The owned first connect has happened (session id is now on the WS URL);
     // wake-reconnect handlers may fire from here on.
     connectionInitiated = true;
@@ -1660,12 +1778,17 @@ function buildTerminal(
     // Reset the composition singleton: a failure during an IME cycle must not
     // leave module state or a deferred send alive for a later terminal mount.
     composition.teardown();
+    disposeMouse();
     connection.disconnect();
     connState.destroy();
     if (toastTimer !== null) {
       clearTimeout(toastTimer);
       toastTimer = null;
     }
+    if (focusResolve !== null) {
+      clearTimeout(focusResolve);
+      focusResolve = null;
+    }
     for (const off of subscriptions) {
       off();
     }
@@ -1888,21 +2011,6 @@ function buildTerminal(
   };
 }
 
-/** Build the terminal UI inside `root`. Call exactly once.
- *
- *  Wraps buildTerminal so that a SYNCHRONOUS startup failure gets the same
- *  treatment an asynchronous one already got. Before this, the two halves of
- *  "the terminal did not start" were handled inconsistently: an async
- *  feature-setup rejection ran enterFatalStartup (overlay dismissed,
- *  onFatalError delivered, recovery surface rendered), while a synchronous throw
- *  propagated bare, leaving the consumer's loading overlay spinning forever over
- *  a page with no terminal and no explanation. Consumers were left hand-building
- *  their own surface to cover the gap, diverging from this one in shape and copy.
- *
- *  The error still propagates: a consumer with its own handling sees it exactly
- *  as before, only now against a page that is no longer stuck on a spinner. A
- *  handler returning `true` suppresses the built-in surface, same contract as the
- *  async phase. */
 /** Resolve the mount target. A selector is looked up here, INSIDE
  *  createTerminal's try, which is the whole point: a consumer that passed
  *  `document.getElementById("terminal")` had to null-check it first (tsc forces
@@ -1959,6 +2067,10 @@ function createFallbackHost(): HTMLElement {
   return host;
 }
 
+/** Build the terminal UI inside `target`. Call exactly once. Wraps buildTerminal so
+ *  a SYNCHRONOUS startup failure gets the same recovery surface an async one does
+ *  and still propagates; that surface is modal in viewport layout, so
+ *  `onFatalError` returning `true` is the path that leaves the page interactive. */
 export function createTerminal(
   target: HTMLElement | string,
   opts: CreateTerminalOptions = {},