@cplieger/web-terminal-ui 3.4.4 → 3.5.0

package/README.md

@@ -3,6 +3,7 @@
 [![npm](https://img.shields.io/npm/v/@cplieger/web-terminal-ui)](https://www.npmjs.com/package/@cplieger/web-terminal-ui)
 [![JSR](https://jsr.io/badges/@cplieger/web-terminal-ui)](https://jsr.io/@cplieger/web-terminal-ui)
 [![Test coverage](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/cplieger/web-terminal-ui/badges/coverage.json)](https://github.com/cplieger/web-terminal-ui/actions/workflows/coverage.yml)
+[![Mutation (TS)](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/cplieger/web-terminal-ui/badges/mutation-ts.json)](https://github.com/cplieger/web-terminal-ui/issues?q=label%3Astryker-tracker)
 [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/13431/badge)](https://www.bestpractices.dev/projects/13431)
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/cplieger/web-terminal-ui/badge)](https://scorecard.dev/viewer/?uri=github.com/cplieger/web-terminal-ui)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-ui",
-  "version": "3.4.4",
+  "version": "3.5.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": "GPL-3.0-or-later",
@@ -25,10 +25,13 @@
     "verify": "bash scripts/verify.sh"
   },
   "peerDependencies": {
-    "@cplieger/web-terminal-engine": ">=2.2.0"
+    "@cplieger/web-terminal-engine": ">=2.4.0"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",
+    "@stryker-mutator/core": "9.6.1",
+    "@stryker-mutator/typescript-checker": "9.6.1",
+    "@stryker-mutator/vitest-runner": "9.6.1",
     "@types/node": "25.9.5",
     "@typescript/native": "npm:typescript@7.0.2",
     "@vitest/coverage-v8": "4.1.10",

package/src/features/connection-banner.ts

@@ -11,6 +11,9 @@ const TEXT: Partial<Record<ConnState, string>> = {
   reconnecting: "Reconnecting\u2026",
   offline: "Offline",
   restarted: "Server restarted; recent input may be lost",
+  // The session's process exited (definitive; nothing is retrying). The final
+  // screen stays rendered behind the banner; open a new tab to keep working.
+  ended: "Session ended",
 };
 
 export function connectionBanner(): TerminalFeature {

package/src/features/context-menu.ts

@@ -21,13 +21,20 @@
 // getSelection() read at a fixed delay races the native selection and caused the
 // reported flakiness (sometimes native, sometimes custom, sometimes both). So we
 // TRACK whether a selection is made during THIS press via a selectionchange
-// listener armed only while a touch is down: the moment one appears we cancel
-// the pending menu and, if it already opened, close it — native always wins over
-// text. The platforms deliver the long-press differently: iOS fires NO
-// contextmenu (a hold timer detects it), Android DOES (we handle it and
-// preventDefault it when showing our own, so Android's native menu doesn't also
-// appear — the "both menus" case). Both paths are gated by the same selection
-// check, so the outcome is consistent across platforms.
+// listener armed only while a touch is down (the moment one appears we cancel
+// the pending menu and, if it already opened, close it), AND we gate the menu on
+// PRESS POSITION: a long-press that landed on a glyph run belongs to the
+// platform's word-select even when no selection has registered yet (iOS 26's
+// native selection can land well past our 550ms timer, so timing alone misfires
+// over text). The platforms deliver the long-press differently: iPhone fires NO
+// contextmenu (a hold timer detects it); iPadOS DOES fire contextmenu mid-press
+// and WebKit treats preventDefault on it as "cancel every remaining default of
+// this gesture" — including a not-yet-registered selection — so on Apple touch
+// devices the contextmenu handler never preventDefaults (that asymmetry is what
+// once made iPad unable to select at all while iPhone worked); Android also
+// fires contextmenu, and there we DO preventDefault when showing our own menu so
+// Android's native menu doesn't also appear (the "both menus" case). All paths
+// share the same selection + position gates, so the outcome is consistent.
 
 import type { TerminalFeature } from "../kernel/types.js";
 import type { ClipboardApi } from "./clipboard.js";
@@ -116,6 +123,22 @@ export function contextMenu(opts: ContextMenuOptions = {}): TerminalFeature {
         }
       };
 
+      // True when the press landed on rendered text (a glyph run inside the
+      // output). The empty-space menu must not open there: a long-press on text
+      // belongs to the platform's word-selection, and opening ours first races
+      // it (on iOS 26 the native selection can register well after 550ms, so
+      // the old no-selection-yet check misfired over text). Hitting the row or
+      // container (the blank area beside/below content) still counts as empty
+      // space so Paste stays reachable.
+      const pressOverText = (x: number, y: number): boolean => {
+        const el = document.elementFromPoint(x, y);
+        if (!(el instanceof HTMLElement) || !el.closest(".term-output")) {
+          return false;
+        }
+        const run = el.closest("span, a");
+        return run !== null && run.textContent.trim().length > 0;
+      };
+
       // True when text is (or just got) selected, so the OS callout owns Copy and
       // our menu stays out of the way. pressSelectedText catches a native
       // selection the instant it happens (selectionchange), avoiding a race with
@@ -238,6 +261,20 @@ export function contextMenu(opts: ContextMenuOptions = {}): TerminalFeature {
           show(e.clientX, e.clientY, false);
           return;
         }
+        if (appleTouch) {
+          // NEVER preventDefault a touch contextmenu on iOS/iPadOS: WebKit then
+          // cancels every remaining default action of the gesture, including a
+          // native word-selection that registers AFTER this event (iPadOS fires
+          // contextmenu mid-long-press; on iOS 26 the selection can land well
+          // after it). iPhone fires no contextmenu at all, so suppressing here
+          // is exactly what made iPad behave differently from iPhone. If our
+          // empty-space menu opened first (the hold timer beat a slow native
+          // selection), stand down so the platform's selection wins.
+          if (menu.classList.contains("visible") && !hasNativeSelection()) {
+            hide(false);
+          }
+          return;
+        }
         if (menu.classList.contains("visible")) {
           e.preventDefault(); // the hold timer already opened it; just suppress native
           return;
@@ -245,12 +282,8 @@ export function contextMenu(opts: ContextMenuOptions = {}): TerminalFeature {
         if (hasNativeSelection()) {
           return; // native selection toolbar owns Copy over text
         }
-        if (appleTouch) {
-          // iOS/iPadOS fires contextmenu a beat before the native word-select
-          // registers, so hasNativeSelection() can still be false here. Defer
-          // anyway so the platform's own selection wins instead of our
-          // empty-space menu (which would preventDefault and suppress it).
-          return;
+        if (pressOverText(e.clientX, e.clientY)) {
+          return; // a long-press on text belongs to the platform's word-select
         }
         e.preventDefault();
         clearLongPress();
@@ -322,7 +355,7 @@ export function contextMenu(opts: ContextMenuOptions = {}): TerminalFeature {
         longPressOrigin = { x: t.clientX, y: t.clientY };
         longPressTimer = window.setTimeout(() => {
           longPressTimer = 0;
-          if (!hasNativeSelection()) {
+          if (!hasNativeSelection() && !pressOverText(longPressOrigin.x, longPressOrigin.y)) {
             show(longPressOrigin.x, longPressOrigin.y, true);
           }
         }, LONG_PRESS_MS);

package/src/features/tabs.ts

@@ -54,6 +54,11 @@ const ACTIVE_TAB_KEY = "wt-active-session";
 const SWITCHER_MEDIA = "(pointer: coarse) and (max-width: 600px)";
 // Default cadence for the no-activityMonitor polling fallback.
 const DEFAULT_POLL_MS = 4000;
+// The server-side status of a session whose process has exited (mirrors the
+// engine's terminal.StatusExited). Such a session is viewable history — its
+// final screen replays and the kernel shows "Session ended" — but it can never
+// produce output again, so session selection prefers live sessions everywhere.
+const STATUS_EXITED = "exited";
 // Tab context-menu viewport clamp (mirrors context-menu.ts): keep this margin
 // from every viewport edge, and this gap above the pointer when the menu has to
 // flip up (a right-click near the bottom edge) so it is neither clipped nor
@@ -1598,11 +1603,14 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
       // stream / poll adopt the existing sessions below; without this they would
       // render inert (blank, never connecting) until the user taps a tab. This
       // is the sibling of the '+'-retry recovery the bootstrap already handles.
+      // A live tab outranks an exited one (its dot status is fed by the same
+      // SSE/poll that adopted it); a corpse is only auto-activated when nothing
+      // else exists.
       function ensureActive(): void {
         if (activeId !== null) {
           return;
         }
-        const first = tabList[0];
+        const first = tabList.find((t) => t.dot.dataset["status"] !== STATUS_EXITED) ?? tabList[0];
         if (first) {
           switchTo(first.id);
         }
@@ -2471,18 +2479,24 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
       } catch {
         sessions = [];
       }
-      if (sessions.length === 0) {
+      // Spawn a fresh session unless a LIVE one is listed. An exited session is
+      // viewable history, not a working terminal — booting a page whose every
+      // session has died (the agent exited: a sign-in dead end, a crash) onto a
+      // corpse was the stuck-loading wedge. The exited ones are still adopted
+      // below (switch to them to read their final screen; close them by hand).
+      if (!sessions.some((s) => s.status !== STATUS_EXITED)) {
         try {
-          sessions = [await apiCreate()];
+          sessions = [...sessions, await apiCreate()];
         } catch {
           // Do not let the initial spawn propagate out of setup(): the kernel
           // would tear down every feature ("terminal has no chrome") and, since
           // managesSessions skipped the startup connect, connectionInitiated
           // stays false so the wake handlers (visibilitychange/pageshow/online)
           // all no-op -- a permanently dead terminal with no recovery. Match the
-          // runtime create() path: toast and leave the chrome up so "+" can retry.
+          // runtime create() path: toast and leave the chrome up so "+" can
+          // retry. Any exited sessions stay adopted (frozen screen + "Session
+          // ended" is still better than a blank page).
           ctx.toast("Couldn't open a terminal");
-          sessions = [];
         }
       }
       // Adopt (dedup) rather than blindly push. The status SSE pushes a snapshot
@@ -2499,17 +2513,25 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
       // Activate the previously-active session if it still exists, else the
       // first (oldest). Session ids are stable server-side, so a page reload
       // reconnects to the tab the user left on instead of always the oldest.
-      let startTab = tabList[0];
+      // Live sessions outrank exited ones: the saved id is honored only while
+      // its session is still live (a reload used to restore straight onto the
+      // corpse of a died-while-away session and wedge there), and the default
+      // is the oldest LIVE tab. Only when nothing is live (the fresh-spawn
+      // above failed too) does an exited tab start — a frozen final screen
+      // with the "Session ended" banner beats a blank page.
+      const liveIds = new Set(sessions.filter((s) => s.status !== STATUS_EXITED).map((s) => s.id));
+      const oldestLive = tabList.find((t) => liveIds.has(t.id));
+      let startTab = oldestLive ?? tabList[0];
       try {
         const savedId = localStorage.getItem(ACTIVE_TAB_KEY);
         if (savedId !== null && savedId !== "") {
           const saved = tabList.find((x) => x.id === savedId);
-          if (saved) {
+          if (saved && (liveIds.has(saved.id) || oldestLive === undefined)) {
             startTab = saved;
           }
         }
       } catch {
-        /* storage unavailable — fall back to the oldest tab */
+        /* storage unavailable — fall back to the oldest live tab */
       }
       if (startTab) {
         activeId = startTab.id;

package/src/kernel/conn-state.ts

@@ -33,6 +33,11 @@ export interface ConnStateMachine {
   closed(): void;
   /** Server restarted (epoch mismatch); recent input may be lost. */
   restarted(): void;
+  /** The active session's process exited (the engine's definitive 4001
+   *  close). Unlike closed(), this is not a failure to escalate or retry:
+   *  the state shows immediately and persists until open() (a switch to a
+   *  live session) replaces it. */
+  ended(): void;
   /** First screen frame rendered: the loading overlay is done, so the banner
    *  may show reconnect state from here on. */
   setLoaded(): void;
@@ -54,9 +59,14 @@ export function createConnState(opts: {
 
   function emit(): void {
     // Suppress transient states until the initial load is over (the loading
-    // overlay owns the screen), except "offline" once the initial-failure limit
-    // is reached. connectionBanner renders "open" as hidden.
-    if (!loaded && !(state === "offline" && consecutiveFailures >= INITIAL_FAILURE_LIMIT)) {
+    // overlay owns the screen), with two exceptions that must show through:
+    // "offline" once the initial-failure limit is reached, and "ended" (a
+    // definitive process exit — nothing further will ever fire, so suppressing
+    // it would hide the only explanation the page will get). connectionBanner
+    // renders "open" as hidden.
+    const passesLoadingGate =
+      state === "ended" || (state === "offline" && consecutiveFailures >= INITIAL_FAILURE_LIMIT);
+    if (!loaded && !passesLoadingGate) {
       opts.onState("open"); // nothing to show yet
       return;
     }
@@ -113,6 +123,13 @@ export function createConnState(opts: {
         }
       }, RESTARTED_CLEAR_MS);
     },
+    ended(): void {
+      // A definitive end, not a failure: reset the failure streak so a later
+      // reconnect to a LIVE session starts its escalation ladder from zero,
+      // and show the state immediately (no grace delay — nothing is retrying).
+      consecutiveFailures = 0;
+      setState("ended", 0);
+    },
     setLoaded(): void {
       loaded = true;
     },

package/src/kernel/kernel.ts

@@ -313,6 +313,19 @@ export function createTerminal(
     onOutboxFull() {
       connState.closed();
     },
+    onProcessExit() {
+      // The engine's definitive 4001 close: the session's process has exited
+      // and the engine will not reconnect it. Two jobs here. markReady()
+      // guarantees the page is usable even when the exit lands before any
+      // screen frame (attaching to an already-dead session on a server that
+      // races the replay) — without it the loading overlay would sit on top of
+      // the tabs chrome forever, which is exactly the reported stuck-loading
+      // wedge. Then surface the end state: "Session ended", not a flapping
+      // "Reconnecting…", since no reconnect is coming. The final screen (when
+      // the server delivered it) stays rendered behind the banner.
+      markReady();
+      connState.ended();
+    },
     onServerRestart() {
       render.resetScrollback();
       render.resetScreen();

package/src/kernel/types.ts

@@ -51,7 +51,16 @@ export interface SessionView {
 // --- Connection state (mirrors the kernel's connection-state machine) ---
 
 /** Connection state the kernel owns and broadcasts on `connection:state`. */
-export type ConnState = "open" | "connecting" | "reconnecting" | "offline" | "restarted";
+export type ConnState =
+  | "open"
+  | "connecting"
+  | "reconnecting"
+  | "offline"
+  | "restarted"
+  // The active session's process has EXITED (the engine's definitive 4001
+  // close): not a connectivity problem, so no reconnect is coming. Cleared
+  // only by connecting somewhere live (a tab switch / a new session).
+  | "ended";
 
 // --- Engine drive handles ---
 //