@cplieger/web-terminal-ui 7.0.2 → 7.0.4

package/css/30-tabs.css

@@ -355,27 +355,6 @@
   color: var(--text);
 }
 
-/* On an inactive tab the close appears only on hover, kept in the layout via
-   visibility so the tab width never jumps; on the active tab it is always shown. */
-:where(.wt-root) .wt-tab:not(.wt-tab-active) .wt-tab-close {
-  visibility: hidden;
-}
-
-:where(.wt-root) .wt-tab:not(.wt-tab-active):hover .wt-tab-close {
-  visibility: visible;
-}
-
-/* Coarse pointer (an iPad using the strip): no hover fires, so an inactive tab's close
-   would be unreachable without first activating the tab. Reveal every tab's close there,
-   matching the always-visible mobile switcher closes. No narrow gate needed: on the
-   narrow-coarse phone the whole strip is display:none (31-switcher.css), so this rule
-   is moot there. */
-@media (pointer: coarse) {
-  :where(.wt-root) .wt-tab:not(.wt-tab-active) .wt-tab-close {
-    visibility: visible;
-  }
-}
-
 /* The add-tab (+) button: a fixed bar item OUTSIDE the tab scroller (it never
    scrolls away with an overflowing list; the shrink-wrapped scroller keeps it
    visually trailing the last tab while the tabs fit — see .wt-tab-scroll). Its

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-ui",
-  "version": "7.0.2",
+  "version": "7.0.4",
   "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",
@@ -50,19 +50,21 @@
     "@stryker-mutator/core": "10.0.0",
     "@stryker-mutator/typescript-checker": "10.0.0",
     "@stryker-mutator/vitest-runner": "10.0.0",
-    "@types/node": "26.2.0",
+    "@types/node": "26.4.0",
     "@typescript/native": "npm:typescript@7.0.2",
+    "@vitest/browser": "4.1.11",
+    "@vitest/browser-playwright": "4.1.11",
     "@vitest/coverage-v8": "4.1.11",
-    "eslint": "10.8.1",
+    "eslint": "10.9.1",
     "fast-check": "4.9.0",
-    "happy-dom": "20.11.6",
-    "html-validate": "11.8.0",
-    "knip": "6.32.2",
+    "html-validate": "11.10.0",
+    "knip": "6.33.0",
+    "playwright": "1.62.1",
     "prettier": "3.9.6",
     "stylelint": "17.14.1",
     "stylelint-config-standard": "40.0.0",
     "typescript": "npm:@typescript/typescript6@6.0.2",
-    "typescript-eslint": "8.67.0",
+    "typescript-eslint": "8.68.0",
     "vitest": "4.1.11"
   },
   "publishConfig": {

package/src/features/context-menu.ts

@@ -75,6 +75,16 @@ export interface ContextMenuOptions {
  *  opens, so a wrong answer here costs at most a duplicated menu on an unusual
  *  device, never a broken selection and never a lost paste. */
 function isAppleTouchDevice(): boolean {
+  // Dead in every runtime that reaches this, and left in place deliberately.
+  // Measured on this repo's Node (v24.18.0, the version ts-ci pins): `typeof
+  // navigator` is "object", with userAgent "Node.js/24", platform
+  // "Linux x86_64" and maxTouchPoints undefined — so the fall-through already
+  // answers false there, by the same route a browser on a non-Apple device
+  // takes. A Web Worker has a WorkerNavigator, so it does not reach this
+  // either. What the guard still buys is totality: without it the bare
+  // `navigator` reads below would throw a ReferenceError in a runtime that has
+  // no navigator at all. It answers the same `false` the fall-through would, so
+  // nothing depends on reaching it, and no test can reach it without stubbing.
   if (typeof navigator === "undefined") {
     return false;
   }

package/src/features/tabs/attention.ts

@@ -19,10 +19,25 @@
 // the switcher's aggregate dot about what wants the user; the fold and the raise
 // share isUnseenCue (model.ts).
 //
-// DOM-free and global-free by construction, like notify.ts: every capability
-// arrives through AttentionEnv, so the decisions are unit-testable with no
-// document, no navigator and no icon assets, and browserAttentionEnv() below is
-// the one place that touches globals.
+// DOM-free by construction, like notify.ts: every capability arrives through
+// AttentionEnv, so the fold, the idempotence and the degradation paths are driven
+// in the tests by plain recorder functions, and browserAttentionEnv() below is the
+// only function here that reads a global (globalThis.navigator, document).
+//
+// That last clause is a reading of the source, and nothing enforces it — on
+// purpose, not by omission. An ambient-absence test would assert the RUNTIME
+// rather than this module: the only importer is tabs/index.ts, the node project
+// holds one file and it reads stylesheets off disk, so nothing here loads this
+// module outside a browser and no test can observe an absent `document` without
+// passing for a third wrong reason (.kiro/steering/testing-ts.md,
+// "Capability-absence is NOT a project selection"). The half that does ship IS
+// enforced, and at the site: attention.test.ts shadows the whole `navigator`
+// object and drives the real browserAttentionEnv through it. The mechanism that
+// could enforce the load-time half is an AST scan of this file's top-level
+// statements — vibekit carries one for its ported copy, where a node-project test
+// statically imports the module and a module-scope global read really does break
+// something. Copy it here the day anything needs this module to load without a
+// document.
 
 import { type CueStatus, cueIconName, isUnseenCue, worseCue } from "./model.js";
 

package/src/features/tabs/index.ts

@@ -1007,8 +1007,7 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
       // sync, so a user browsing a scrolled strip is never yanked back by an
       // unrelated repaint), the newly active chip is brought into view in the
       // overflowed scroller; inline: "nearest" is a no-op when it is already
-      // visible. The typeof guard covers happy-dom, which lacks
-      // scrollIntoView.
+      // visible. The typeof guard covers an environment without scrollIntoView.
       let lastRevealedActive = "";
       function paintActive(): void {
         for (const t of tabList) {
@@ -2247,7 +2246,7 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
           }
         }
         if (invert.size === 0) {
-          return; // nothing moved on screen (a zero-rect DOM: happy-dom)
+          return; // nothing moved on screen (every box measured zero)
         }
         applyShift(invert, "none");
         // The read forces the reflow that COMMITS the from-state. Without it the
@@ -2537,8 +2536,8 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
         // Reordering re-appends every chip, and reparenting the focused field blurs
         // it — so an open edit would be committed as a side effect of moving some
         // OTHER tab, via a blur the user never performed. Resolve it here instead,
-        // so the outcome is chosen and testable rather than emergent (happy-dom
-        // does not reproduce the reparent-blur, so no test could catch it).
+        // so the outcome is chosen rather than emergent: a blur that arrives as a
+        // side effect of reparenting is not a decision anyone made.
         resolveEdit("blur", false);
         const from = tabList.findIndex((t) => t.id === id);
         const to = from + delta;

package/src/features/tabs/ink-centre.ts

@@ -249,9 +249,9 @@ export function centreChipLabels(
   };
 
   remeasure(false);
-  // The DOM lib types document.fonts as always present; happy-dom ships no
-  // FontFaceSet at all, and neither does any engine without the CSS Font
-  // Loading API, so the honest type is the optional one.
+  // The DOM lib types document.fonts as always present; an engine without the CSS
+  // Font Loading API ships no FontFaceSet at all, so the honest type is the
+  // optional one.
   const fonts = document.fonts as FontFaceSet | undefined;
   // `ready` settles the initial load (including a failed one); `loadingdone`
   // covers a face the host page adds afterwards, which `ready` never reports.

package/src/features/tabs/notify.ts

@@ -48,7 +48,7 @@ export type NotificationCtorLike = new (
  *  not recognise must degrade rather than be asserted. */
 export interface NotifierEnv {
   /** The Notification constructor, or undefined where the API does not exist
-   *  (iOS Safari outside an installed PWA, a non-secure context, happy-dom). */
+   *  (iOS Safari outside an installed PWA, a non-secure context). */
   ctor: NotificationCtorLike | undefined;
   /** Current permission: "default" | "granted" | "denied" (or anything else). */
   permission: () => string;

package/src/features/tabs/switch-anim.ts

@@ -10,7 +10,7 @@
 // on the 360 ms fallback timer instead of the animation's own end, and every test
 // still passes because the tests dispatch the JS constant.
 //
-// Living here rather than inside the feature is what lets `css-contract.test.ts`
+// Living here rather than inside the feature is what lets `css-contract.node.test.ts`
 // import it and assert the CSS agrees. Same reason `input-placeholder.ts` and
 // `kernel/gesture.ts` exist: a constant two places must keep in lockstep gets its
 // own module. NOT part of the package's `exports` map, so it is internal and can

package/src/kernel/kernel.ts

@@ -40,6 +40,7 @@ import { createConnState } from "./conn-state.js";
 import { createScrollbackKeeper } from "./scrollback.js";
 import { STARTUP_FAILURE_COPY } from "./startup-copy.js";
 import { attachLoadingStatus, DEFAULT_LOADING_MESSAGES } from "./loading-status.js";
+import { reloadPage } from "./navigation.js";
 import type {
   CreateTerminalOptions,
   FeatureInstance,
@@ -184,7 +185,7 @@ function renderFatalStartupInto(
   reloadButton.type = "button";
   reloadButton.textContent = STARTUP_FAILURE_COPY.reloadLabel;
   reloadButton.addEventListener("click", () => {
-    window.location.reload();
+    reloadPage();
   });
   card.append(title, messageEl, reloadButton);
   surface.appendChild(card);

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/navigation.ts

@@ -0,0 +1,19 @@
+// navigation.ts — the library's one page-navigation call, behind its own module.
+//
+// `window.location.reload` cannot be substituted in a real browser: `reload` is
+// an own, sealed property of the location instance (`configurable: false`,
+// `writable: false`), `Location.prototype` carries no `reload` to spy on, and
+// `window`, `globalThis.window` and `globalThis.location` are all
+// non-configurable. So a test cannot redefine it, assign over it, or stub the
+// global, and letting the real call run navigates the test runner's own frame
+// and takes the whole run down with it.
+//
+// A separate module is the seam that works: a caller's import is a live binding
+// the test framework can replace, which an intra-module call is not. Keeping the
+// call here also means there is exactly one place in the library that navigates,
+// so the next one has to be added deliberately.
+
+/** Reload the current page. The only navigation this library performs. */
+export function reloadPage(): void {
+  window.location.reload();
+}

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/style-contract.ts

@@ -25,7 +25,7 @@
 // These lists are HAND-WRITTEN on purpose. They are the public contract — a
 // decision about what this library promises to support — not a fact derived
 // from the stylesheets. What IS derived from the stylesheets is the
-// verification that the promise holds: `src/css-contract.test.ts` generates the
+// verification that the promise holds: `src/css-contract.node.test.ts` generates the
 // declared/referenced token inventory from the CSS itself and fails if any
 // token named here is not both DECLARED and READ by a rule. A token that is
 // declared but never read is the silent-no-op case above, reached from the

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

package/src/presets/tabbed.ts

@@ -10,6 +10,18 @@ import { activityMonitor } from "../features/activity-monitor.js";
 import { animations } from "../features/animations.js";
 import { presetSingle } from "./single.js";
 
+/** Options shared by the two tabbed presets, passed through to the tabs feature.
+ *  A preset that takes arguments is called as `features: () =>
+ *  presetTabbed({...})`, which keeps the call inside createTerminal's failure
+ *  boundary (see CreateTerminalOptions.features). */
+export interface TabbedPresetOptions {
+  /** Swap the page's icon links to a status variant while a background session
+   *  wants the user. Off by default, and enabling it is a promise that the
+   *  variant assets are served — see TabsOptions.attentionIcons for the naming
+   *  contract and .kiro/scripts/gen-attention-icons.py, which writes them. */
+  attentionIcons?: boolean;
+}
+
 /** buildTabbed composes the tabbed UI: the single-pane touch features, an
  *  externally-driven mobile toolbar (its grid is opened from a keyboard button
  *  in the tab bar, not its own toggle), the activity monitor (the status-SSE
@@ -27,18 +39,6 @@ import { presetSingle } from "./single.js";
  *  foreground-process/cwd inference — and both presets render what it reports. A
  *  browser that re-derived any of that could only disagree with the server and
  *  with every other client attached to the same session. */
-/** Options shared by the two tabbed presets, passed through to the tabs feature.
- *  A preset that takes arguments is called as `features: () =>
- *  presetTabbed({...})`, which keeps the call inside createTerminal's failure
- *  boundary (see CreateTerminalOptions.features). */
-export interface TabbedPresetOptions {
-  /** Swap the page's icon links to a status variant while a background session
-   *  wants the user. Off by default, and enabling it is a promise that the
-   *  variant assets are served — see TabsOptions.attentionIcons for the naming
-   *  contract and .kiro/scripts/gen-attention-icons.py, which writes them. */
-  attentionIcons?: boolean;
-}
-
 export function buildTabbed(
   agentShell: boolean,
   opts: TabbedPresetOptions = {},
@@ -59,12 +59,8 @@ export function buildTabbed(
   ];
 }
 
-/** Tabbed UI: the touch features, tabs, the mobile keyboard bar, the activity
- *  monitor, and animations. Each tab's title follows the process OSC 0/2 window
- *  title when the program sets one, else the last submitted line; each tab's
- *  activity dot stays hidden until its session reports activity via OSC 9;4
- *  progress (kiro-cli, Claude Code, …), so a plain bash/sh keeps clean,
- *  label-only tabs. */
+/** Tabbed UI: buildTabbed with agent activity presumed off (see buildTabbed for
+ *  title and activity-dot sourcing). */
 export function presetTabbed(opts: TabbedPresetOptions = {}): TerminalFeature<unknown>[] {
   return buildTabbed(false, opts);
 }