@cplieger/web-terminal-ui 7.0.1 → 7.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-ui",
-  "version": "7.0.1",
+  "version": "7.0.3",
   "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",
@@ -55,7 +55,7 @@
     "@vitest/coverage-v8": "4.1.11",
     "eslint": "10.8.1",
     "fast-check": "4.9.0",
-    "happy-dom": "20.11.2",
+    "happy-dom": "20.11.6",
     "html-validate": "11.8.0",
     "knip": "6.32.2",
     "prettier": "3.9.6",

package/src/features/tabs/index.ts

@@ -2873,13 +2873,20 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
       // still be), to the terminal otherwise. Recorded at entry because the exit
       // paths cannot tell them apart.
       let editFrom: "keyboard" | "pointer" = "pointer";
-      // Tab ids with a pinned-name request in flight. While an id is here, a status
-      // record carrying a DIFFERENT value is applied for display but does not
-      // supersede the request: SSE delivery order and REST mutation order are not
-      // one total order, so a record sampled BEFORE our PUT can arrive after it,
-      // and treating it as newer authority would suppress the request's own
-      // rollback and its failure toast.
-      const namesInFlight = new Set<string>();
+      // Tab ids with pinned-name requests in flight, COUNTED per id. While a count
+      // is held, a status record carrying a DIFFERENT value is applied for display
+      // but does not supersede the request: SSE delivery order and REST mutation
+      // order are not one total order, so a record sampled BEFORE our PUT can
+      // arrive after it, and treating it as newer authority would suppress the
+      // request's own rollback and its failure toast.
+      // Counted rather than a Set of ids, because two renames of one tab can be out
+      // at once and the invariant is "no request of OURS is in flight", not "no id
+      // is marked": a bare Set let the first request's completion clear the marker
+      // while the second's PUT was still open, and the second rename then failed
+      // silently. A per-request token would carry more information, but the only
+      // reader asks whether ANY request is out for this id, and the failure handler
+      // already distinguishes its own supersession by (born, nameSeq).
+      const namesInFlight = new Map<string, number>();
 
       /** restoreFocusAfterEdit sends focus where the entry path implies. The
        *  terminal branch is gated exactly like switchTo's focus-on-switch: on a
@@ -2949,8 +2956,11 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
           const { text, fallback } = baseLabel(t);
           ctx.announce(fallback ? "Custom name removed" : `Using automatic name: ${text}`);
         }
-        namesInFlight.add(id);
         const request = name === "" ? api.clearPinnedTitle(id) : api.setPinnedTitle(id, name);
+        // Counted only once the request exists: an api implementation that throws
+        // instead of rejecting would otherwise leave a count behind that no
+        // .finally ever releases, and the id would read as in flight forever.
+        namesInFlight.set(id, (namesInFlight.get(id) ?? 0) + 1);
         void request
           .catch(() => {
             const cur = tabList.find((x) => x.id === id);
@@ -2962,7 +2972,12 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
             ctx.toast("Couldn't save the terminal name");
           })
           .finally(() => {
-            namesInFlight.delete(id);
+            const left = (namesInFlight.get(id) ?? 0) - 1;
+            if (left > 0) {
+              namesInFlight.set(id, left);
+            } else {
+              namesInFlight.delete(id);
+            }
           });
         return true;
       }

package/src/kernel/kernel.ts

@@ -274,17 +274,21 @@ function buildTerminal(
   // Narrow = compact in EITHER dimension: skinny (a phone in portrait, a
   // narrow embedded panel) or short (a phone in landscape). The one
   // ResizeObserver below fires on both width and height changes.
+  //
+  // Constructed unconditionally: ResizeObserver is a hard requirement of this
+  // library, not an enhancement. viewport.init() and the tabs strip both
+  // construct one with no guard, and the same buildTerminal builds a WeakRef
+  // (whose browser floor is strictly higher), so a `typeof ResizeObserver ===
+  // "function"` guard here could only ever protect a browser that crashes
+  // moments later. It used to be here, and it was measured dead.
   const isNarrow = (): boolean =>
     root.clientWidth <= NARROW_MAX_PX || root.clientHeight <= SHORT_MAX_PX;
   function updateNarrow(): void {
     root.classList.toggle("wt-narrow", isNarrow());
   }
   updateNarrow();
-  let narrowObserver: ResizeObserver | null = null;
-  if (typeof ResizeObserver === "function") {
-    narrowObserver = new ResizeObserver(updateNarrow);
-    narrowObserver.observe(root);
-  }
+  let narrowObserver: ResizeObserver | null = new ResizeObserver(updateNarrow);
+  narrowObserver.observe(root);
 
   // --- Document title (kernel-owned, composed from two inputs) ---
   //

package/src/kernel/loading-status.ts

@@ -135,10 +135,10 @@ export function attachLoadingStatus(
   // Swap the visible text through a fade so a change reads as deliberate rather
   // than as a glitch. The first write skips the fade (there is nothing to fade
   // out) so the line does not arrive half-transparent.
+  //
+  // No `stopped` check, here or in the deferred half below, and that is
+  // deliberate rather than an omission: see stop(), which owns the invariant.
   const show = (text: string): void => {
-    if (stopped) {
-      return;
-    }
     // First write has nothing to fade out, so it must not arrive half-transparent.
     if (visible.textContent === "") {
       visible.textContent = text;
@@ -146,18 +146,13 @@ export function attachLoadingStatus(
     }
     visible.classList.add("wt-loading-text-out");
     later(() => {
-      if (stopped) {
-        return;
-      }
       visible.textContent = text;
       visible.classList.remove("wt-loading-text-out");
     }, SWAP_FADE_MS);
   };
 
   const announce = (text: string): void => {
-    if (!stopped) {
-      live.textContent = text;
-    }
+    live.textContent = text;
   };
 
   later(() => {
@@ -170,7 +165,13 @@ export function attachLoadingStatus(
 
   later(() => {
     const waiting = messages.waiting;
-    if (pinned || stopped || waiting.length === 0) {
+    // `pinned` only. Not `stopped`: this callback is held by `timers`, so stop()
+    // has cancelled it before it could read the flag. That disjunct was here and
+    // was as dead as the ones deleted above — and invisible to the mutation
+    // report, because a mutator works on binary-expression nodes and never
+    // isolates a bare identifier operand, so `pinned || stopped` is mutated as a
+    // pair and the pair is killable through `pinned`.
+    if (pinned || waiting.length === 0) {
       return;
     }
     // showAt reads through an undefined check rather than an index assertion:
@@ -219,6 +220,23 @@ export function attachLoadingStatus(
       announce(text);
     },
     stop(): void {
+      // THE OWNER of "nothing further happens", and the only one.
+      //
+      // It discharges that by cancelling every callback this controller armed:
+      // `later()` is the sole way to schedule here, everything it schedules is in
+      // `timers`, and the rotation interval is the one handle held separately.
+      // So the only call that can arrive after this line is one from OUTSIDE a
+      // cancellable callback — which is `reason()`, and `reason()` is where
+      // `stopped` is read.
+      //
+      // `show()` and `announce()` used to re-test it as well, and the mutation
+      // pass measured what that was worth: five permanently unkillable mutants,
+      // because no input could reach either function with `stopped` true. They
+      // were not even protecting anything if they had — the two nodes are
+      // detached three lines below, so a late write goes nowhere. The invariant
+      // is pinned by a test instead ("stop() leaves no timer armed"), which,
+      // unlike a guard, fails for the change that would actually break it: a
+      // future timer armed outside `later()`.
       if (stopped) {
         return;
       }

package/src/kernel/scrollback-storage.ts

@@ -28,7 +28,6 @@
 // caps rather than only writing.
 
 import type { ScrollbackPersistence } from "./types.js";
-import type { StoreSnapshot } from "@cplieger/web-terminal-engine";
 import { DEFAULT_MAX_AGE_MS } from "./scrollback.js";
 import { positiveIntOption } from "./options.js";
 
@@ -259,11 +258,16 @@ export function localScrollbackStorage(
         return null;
       }
       try {
-        // The snapshot is returned unvalidated on purpose: the kernel validates
-        // every field against the engine's snapshot contract, and duplicating that
-        // here would give two places to disagree about what a usable entry is. A
-        // parse failure is the one thing this layer must handle, since it throws.
-        return { savedAt, snapshot: JSON.parse(raw.slice(raw.indexOf("\n") + 1)) as StoreSnapshot };
+        // The snapshot is returned unparsed on purpose: the kernel parses every
+        // field against the engine's snapshot contract, and duplicating that here
+        // would give two places to disagree about what a usable entry is. Typed
+        // `unknown` rather than asserted `as StoreSnapshot`, which is what this
+        // line used to do — and that cast was laundering `JSON.parse`'s `any` past
+        // no-unsafe-assignment while telling the compiler the value was verified,
+        // leaving the keeper to verify it anyway. That is how the keeper's
+        // boundary came to check the same thing twice.
+        const snapshot: unknown = JSON.parse(raw.slice(raw.indexOf("\n") + 1));
+        return { savedAt, snapshot };
       } catch {
         remove(keyFor(sessionId));
         return null;

package/src/kernel/scrollback.ts

@@ -18,7 +18,7 @@
 
 import { LineStore, connection } from "@cplieger/web-terminal-engine";
 import { positiveIntOption } from "./options.js";
-import type { PersistedScrollback, ScrollbackPersistence } from "./types.js";
+import type { ScrollbackPersistence } from "./types.js";
 
 /**
  * Newest lines persisted per session when the consumer names no bound.
@@ -69,33 +69,72 @@ export interface ScrollbackKeeper {
   stop(): void;
 }
 
-/** Read a stored entry's timestamp defensively. The value has been outside this
- *  program's memory, so its type is an assumption until checked. */
-function savedAtOf(entry: unknown): number | null {
-  if (typeof entry !== "object" || entry === null) {
-    return null;
-  }
-  const at = (entry as Record<string, unknown>)["savedAt"];
-  return typeof at === "number" && Number.isFinite(at) ? at : null;
+/** A stored entry that has been read and proven: every field is what it says, so
+ *  nothing downstream re-checks it. `readStoredEntry` is the only constructor,
+ *  which is what makes that promise keepable. */
+interface StoredEntry {
+  /** `Date.now()` at the write. Finite. */
+  readonly savedAt: number;
+  /** The snapshot's server epoch, or null when the entry names no server
+   *  process.
+   *
+   *  Stricter than "a finite number", because this value is adopted as a
+   *  session's IDENTITY: the server reports a process-start timestamp in
+   *  nanoseconds, so a negative or fractional value cannot have come from one
+   *  and is a corrupt or hand-edited entry wearing the shape of a real one.
+   *
+   *  NOT 0-for-unknown. The engine spells "unknown" as 0 on its own surface and
+   *  that is its contract, but inheriting the spelling here put the rejection
+   *  value inside the range of accepted values, so `epoch > 0` and `epoch >= 0`
+   *  could not differ: at `epoch === 0` both yielded 0 and both were rejected
+   *  downstream. Out-of-band restores the distinction, and 0 goes back to being
+   *  a value the boundary refuses rather than the way it says no. */
+  readonly serverEpoch: number | null;
+  /** Still the engine's to parse. `LineStore.fromSnapshot` takes `unknown` and
+   *  is the authority on a snapshot's contents (engine store.ts:1584), so a
+   *  shape check here would be a second owner of one obligation. */
+  readonly snapshot: unknown;
 }
 
-/** Read a stored snapshot's server epoch defensively, or 0 for "unknown".
+/**
+ * Read a stored entry, or null when it cannot be used.
  *
- *  Stricter than "a finite number", because this value is adopted as a session's
- *  IDENTITY: the server reports a process-start timestamp in nanoseconds, so a
- *  negative or fractional value cannot have come from one and is a corrupt or
- *  hand-edited entry wearing the shape of a real one. 0 is the library's existing
- *  "unknown", and every rejection lands there. */
-function epochOf(entry: unknown): number {
-  if (typeof entry !== "object" || entry === null) {
-    return 0;
-  }
-  const snap = (entry as Record<string, unknown>)["snapshot"];
-  if (typeof snap !== "object" || snap === null) {
-    return 0;
+ * `unknown` in, because the value has been outside this program's memory and
+ * `ScrollbackPersistence.load`'s declared return type is an assumption about a
+ * consumer's storage rather than a fact about its contents — the library's own
+ * implementation produces one by `JSON.parse`. A `StoredEntry` out, so every
+ * later line reads fields instead of re-establishing them.
+ *
+ * The parameter type carries the caller's proof: `hydrate` must separate "no
+ * entry" from "bad entry" before calling, because those two have different
+ * handling, so non-nullishness is already established. That is why there is no
+ * object test here and why there must not be one — a property read on any other
+ * primitive yields undefined and the field checks below reject it, so a `typeof
+ * entry !== "object"` test would be a second statement of a thing the signature
+ * already guarantees. This function had two of them, one per field it read, and
+ * neither could be observed: 15 of the file's 19 surviving mutants were those
+ * two guards and their bodies.
+ */
+function readStoredEntry(entry: NonNullable<unknown>): StoredEntry | null {
+  const rec = entry as Record<string, unknown>;
+  const savedAt = rec["savedAt"];
+  // Finite, not merely a number: the age comparison below is a subtraction, and
+  // `Math.abs(Date.now() - NaN) > maxAgeMs` is false, so a NaN timestamp would
+  // read as freshly written forever.
+  if (typeof savedAt !== "number" || !Number.isFinite(savedAt)) {
+    return null;
   }
-  const epoch = (snap as Record<string, unknown>)["serverEpoch"];
-  return typeof epoch === "number" && Number.isSafeInteger(epoch) && epoch > 0 ? epoch : 0;
+  // Read through a nullable cast rather than a typeof test: `?.` is safe on a
+  // primitive as well as on null, so one operator covers every shape a stored
+  // value can have, and `fromSnapshot` owns what a usable snapshot contains.
+  const snapshot = rec["snapshot"] as Record<string, unknown> | null | undefined;
+  const epoch = snapshot?.["serverEpoch"];
+  return {
+    savedAt,
+    serverEpoch:
+      typeof epoch === "number" && Number.isSafeInteger(epoch) && epoch > 0 ? epoch : null,
+    snapshot,
+  };
 }
 
 export function createScrollbackKeeper(
@@ -143,22 +182,41 @@ export function createScrollbackKeeper(
    *  Every rejection below has that same correct handling, which is why none of
    *  them throws or reports: the worst outcome of starting empty is one slow
    *  restore, and the worst outcome of hydrating something unsound is a terminal
-   *  that shows content from a session that no longer exists. */
+   *  that shows content from a session that no longer exists.
+   *
+   *  This function owns exactly two decisions and delegates the rest, which is
+   *  the point of its shape. It decides whether there is an entry at all, and
+   *  whether an entry that parsed may be USED (age, and verifiability). What an
+   *  entry's envelope must look like is `readStoredEntry`'s; what a snapshot must
+   *  contain is `LineStore.fromSnapshot`'s. Three owners, three depths, no
+   *  overlap — the arrangement this module did not have when its two readers each
+   *  re-established that the entry was an object. */
   function hydrate(sessionId: string): LineStore | null {
-    let entry: PersistedScrollback | null | undefined;
+    let raw: unknown;
     try {
-      entry = cfg.load(sessionId);
+      raw = cfg.load(sessionId);
     } catch {
+      // Deliberately empty: a seam that threw has told us there is no entry, and
+      // `raw` is still undefined, which is exactly what the check below concludes.
+      // A `return null` here would be a second owner of "there is no entry".
+    }
+    // "No entry" is silent and is not a rejection: nothing is dropped, because
+    // there is nothing to drop. Every path below this line has an entry to
+    // account for. This is also what lets `readStoredEntry` take a non-nullish
+    // parameter and therefore need no object test.
+    if (raw === null || raw === undefined) {
       return null;
     }
-    if (entry === null || entry === undefined) {
+
+    const entry = readStoredEntry(raw);
+    if (entry === null) {
+      drop(sessionId);
       return null;
     }
 
-    const savedAt = savedAtOf(entry);
     // Distance in either direction: a clock that moved backwards would otherwise
     // leave an entry whose age never reaches the bound.
-    if (savedAt === null || Math.abs(Date.now() - savedAt) > maxAgeMs) {
+    if (Math.abs(Date.now() - entry.savedAt) > maxAgeMs) {
       drop(sessionId);
       return null;
     }
@@ -170,19 +228,22 @@ export function createScrollbackKeeper(
     }
 
     // Structure checked; now the one rejection that is a real decision rather
-    // than a validation. An entry with no server epoch cannot be verified
-    // against the server it is about to be shown next to, and absolute line
-    // indices only mean anything within one server process: a restarted server
-    // begins again near 0, so a hydrated store whose epoch cannot be compared
-    // would present old content as live AND then refuse the new session's
-    // output, because those low indices fall below what the hydrated store
-    // believes it evicted. A terminal that fills in slowly is a far better
-    // failure than one that is wrong and then permanently blank, so an
-    // unverifiable entry is discarded. In practice this never fires: an epoch is
-    // missing only from a server that reports none at all, in which case restart
-    // detection was never available to anyone.
-    const epoch = epochOf(entry);
-    if (epoch === 0) {
+    // than a validation, and the reason the epoch is read at the boundary but
+    // JUDGED here. An entry with no server epoch cannot be verified against the
+    // server it is about to be shown next to, and absolute line indices only
+    // mean anything within one server process: a restarted server begins again
+    // near 0, so a hydrated store whose epoch cannot be compared would present
+    // old content as live AND then refuse the new session's output, because
+    // those low indices fall below what the hydrated store believes it evicted.
+    // A terminal that fills in slowly is a far better failure than one that is
+    // wrong and then permanently blank, so an unverifiable entry is discarded.
+    // In practice this never fires: an epoch is missing only from a server that
+    // reports none at all, in which case restart detection was never available
+    // to anyone.
+    //
+    // AFTER fromSnapshot, deliberately: reading it earlier would fire the warning
+    // below for a snapshot the engine was going to reject anyway.
+    if (entry.serverEpoch === null) {
       if (!warnedNoEpoch) {
         warnedNoEpoch = true;
         console.warn(
@@ -196,7 +257,7 @@ export function createScrollbackKeeper(
     // The epoch must reach the connection layer BEFORE this session's resume, or
     // the first resumeAck records it with nothing to compare against and a
     // restart goes undetected for exactly the content that needed checking.
-    connection.adoptPersistedEpoch(sessionId, epoch);
+    connection.adoptPersistedEpoch(sessionId, entry.serverEpoch);
     return store;
   }
 

package/src/kernel/types.ts

@@ -498,9 +498,28 @@ export interface PersistedScrollback {
  *  treats any failure as "nothing was restored" and takes a full resume, exactly
  *  as if persistence were switched off. */
 export interface ScrollbackPersistence {
-  /** Return the stored entry for a session, or null/undefined when there is
-   *  none. Called once per session, before that session connects. */
-  load(sessionId: string): PersistedScrollback | null | undefined;
+  /** Return whatever was stored for a session, or null/undefined when there is
+   *  nothing. Called once per session, before that session connects.
+   *
+   *  `unknown`, not `PersistedScrollback`, and the asymmetry with `save` below is
+   *  the point: an entry going OUT was produced by the engine and is proven, while
+   *  an entry coming BACK has been outside this program's memory and is a claim.
+   *  Declaring the proven type on both sides told the compiler the returned value
+   *  was verified — which no implementation of this seam can promise, this
+   *  library's own `localScrollbackStorage` least of all, since it hands back a
+   *  `JSON.parse` result. The kernel parsed it anyway, and because the type said
+   *  otherwise it did so in helpers that each re-established the shape from
+   *  scratch: measured 2026-08, 15 of `scrollback.ts`'s 19 permanently unkillable
+   *  mutants were those duplicate checks.
+   *
+   *  Nothing is lost by an implementation: a `load` annotated
+   *  `PersistedScrollback | null` still satisfies this, so a consumer that holds
+   *  real entries in memory keeps its own type checking. What goes is only the
+   *  false guarantee at the boundary that cannot honour it.
+   *
+   *  `PersistedScrollback` remains the shape to store and the shape you get back
+   *  when storage is intact; see `save`. */
+  load(sessionId: string): unknown;
   /** Store an entry, replacing any previous one for the session.
    *
    *  THROW when nothing was persisted (over quota, storage revoked, an entry the