@cplieger/web-terminal-ui 3.4.5 → 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.5",
+  "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/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 ---
 //