@cplieger/web-terminal-ui 5.0.1 → 5.0.3

package/css/10-primitives.css

@@ -42,6 +42,33 @@
   background: var(--text-active);
 }
 
+/* ===== Hover gating: any-hover, never hover =====
+   Every gated hover rule in this package uses @media (any-hover: hover). Do not
+   write @media (hover: hover) here.
+
+   What the gate is for: a bare touchscreen fires no pointer-leave, so a tapped
+   control keeps its :hover wash until the next tap somewhere else. What went
+   wrong: `hover` and `pointer` describe only the PRIMARY input, and iPadOS
+   reports hover: none / pointer: coarse whether or not a Magic Keyboard trackpad
+   is attached. So (hover: hover) is false on every touch-primary device,
+   INCLUDING the ones driving a real pointer.
+
+   For the coarse-only controls that made the gate not a tradeoff but a deletion,
+   and it shipped that way: .wt-tab-kb renders only under @media (pointer: coarse)
+   (30-tabs.css) and the whole .wt-switcher subtree only under (pointer: coarse)
+   plus .wt-narrow (31-switcher.css). Pairing either with (hover: hover) makes the
+   two conditions complementary, so the hover rule was unreachable on every device
+   that exists. Measured against the deployed bundle at iPad width: the keyboard
+   button is a visible 44x44 while a forced :hover leaves its background at
+   rgba(0, 0, 0, 0), where the ungated .wt-tab-new beside it resolves to
+   --tab-active-bg.
+
+   `any-hover` asks the question the gate meant to ask — can ANY attached device
+   hover — so a bare iPhone/iPad still answers none (no wash, nothing to stick)
+   while a trackpad or Pencil answers hover and brings a real pointer-leave with
+   it. Same defect class as Tailwind's hoverOnlyWhenSupported
+   (tailwindlabs/tailwindcss#11109). */
+
 /* Keyboard-focus ring for every chrome control (all interactive chrome is a
    real <button>: tabs, +, keyboard, switcher rows, menu items, the FAB).
    :focus-visible only — a tap/click never shows the ring (the UA heuristic),
@@ -147,7 +174,7 @@
   font-weight: 600;
 }
 
-@media (hover: hover) {
+@media (any-hover: hover) {
   :where(.wt-root) .wt-fatal-reload:hover {
     background: color-mix(in oklch, var(--accent), var(--text) 12%);
   }

package/css/30-tabs.css

@@ -158,11 +158,12 @@
    vocabulary and stays themeable through one token. It is a rung subtler than the
    inactive chip's 15%/25% because it starts from an already-lifted fill.
 
-   Hover is gated to real hover pointers. Tapping an INACTIVE chip makes it
-   active, so a touchscreen's sticky :hover leaves with the class; tapping the
-   ACTIVE chip changes nothing, so an ungated hover would stay lit until the next
-   tap somewhere else. Touch feedback there is :active, which is correct. */
-@media (hover: hover) {
+   Hover is gated (see the any-hover note in 10-primitives.css). Tapping an
+   INACTIVE chip makes it active, so a touchscreen's sticky :hover leaves with the
+   class; tapping the ACTIVE chip changes nothing, so an ungated hover would stay
+   lit until the next tap somewhere else. Touch feedback there is :active, which is
+   correct. */
+@media (any-hover: hover) {
   :where(.wt-root) .wt-tab-active:hover {
     background: color-mix(in oklch, var(--tab-active-bg), var(--tab-active-fg) 12%);
   }
@@ -382,13 +383,15 @@
 
 /* Hover wash, matching every other bar control (.wt-tab-new, the switcher's
    buttons) — without it this was the one control in the chrome that gave no
-   pointer feedback at all. Gated to real hover pointers because the button only
-   SHOWS on a coarse pointer (the iPad strip): a plain touchscreen has no
-   pointer-leave, so :hover would stick after a tap and the wash would linger;
-   the feedback there is :active, from .wt-btn. Before .wt-active / .wt-armed so
-   those toggled fills win on a hovered button (equal specificity, source order
-   decides). */
-@media (hover: hover) {
+   pointer feedback at all. Gated on any-hover, NOT hover: this button renders only
+   under (pointer: coarse) below, and a touch-primary device reports hover: none
+   even with a trackpad attached, so a (hover: hover) gate here made the wash
+   unreachable on every device rather than restricting it to hovering ones (the
+   note in 10-primitives.css has the measurement). On a bare touchscreen any-hover
+   is none, so the feedback there is still :active, from .wt-btn. Before
+   .wt-active / .wt-armed so those toggled fills win on a hovered button (equal
+   specificity, source order decides). */
+@media (any-hover: hover) {
   :where(.wt-root) .wt-tab-kb:hover {
     background: var(--tab-hover-bg);
   }

package/css/31-switcher.css

@@ -148,7 +148,7 @@
   color: color-mix(in oklch, var(--text) 55%, transparent);
 }
 
-@media (hover: hover) {
+@media (any-hover: hover) {
   :where(.wt-root) .wt-switcher-current-close:hover {
     color: var(--text);
   }
@@ -216,10 +216,11 @@
   overflow: hidden;
 }
 
-/* Hover wash like the switch and "+" buttons beside it; gated to real hover
-   pointers for the same reason they are (a sticky :hover after a tap). Before
-   .wt-active / .wt-armed so those fills win on a hovered button. */
-@media (hover: hover) {
+/* Hover wash like the switch and "+" buttons beside it; gated on any-hover for
+   the same reason they are (see the note in 10-primitives.css — this whole
+   subtree renders only on a coarse pointer, where hover: hover is always false).
+   Before .wt-active / .wt-armed so those fills win on a hovered button. */
+@media (any-hover: hover) {
   :where(.wt-root) .wt-switcher-kb:hover {
     background: var(--tab-hover-bg);
   }
@@ -292,7 +293,7 @@
   pointer-events: none;
 }
 
-@media (hover: hover) {
+@media (any-hover: hover) {
   :where(.wt-root) .wt-switcher-switch:hover {
     background: var(--tab-hover-bg);
   }
@@ -320,15 +321,17 @@
 }
 
 /* Mobile "+": the primary action, carried in the accent colour so it reads as
-   permanent and prominent. Hover fill is gated to real hover pointers: on touch,
-   :hover sticks after a tap (no pointer-leave), so the purple would linger — the
-   press feedback there comes from :active, which clears on release. */
+   permanent and prominent. Hover fill is gated on any-hover (see the note in
+   10-primitives.css): on a bare touchscreen any-hover is none, so the purple
+   cannot linger after a tap and the press feedback comes from :active; a trackpad
+   or Pencil reports hover and gets the wash, which a (hover: hover) gate denied it.
+   */
 :where(.wt-root) .wt-switcher-new {
   flex: none;
   color: var(--accent);
 }
 
-@media (hover: hover) {
+@media (any-hover: hover) {
   :where(.wt-root) .wt-switcher-new:hover {
     background: var(--tab-hover-bg);
   }
@@ -418,7 +421,7 @@
   overflow: hidden;
 }
 
-@media (hover: hover) {
+@media (any-hover: hover) {
   :where(.wt-root) .wt-switcher-row-select:hover {
     background: color-mix(in oklch, var(--tab-bg), var(--text) 15%);
   }
@@ -458,10 +461,13 @@
   color: color-mix(in oklch, var(--text) 55%, transparent);
 }
 
-/* Hover only on real hover pointers: on touch, :hover sticks after a tap, so
-   when closing a tab shifts the list under the finger the newly-under close
-   would latch white. Touch feedback comes from the surrounding row's :active. */
-@media (hover: hover) {
+/* Hover gated on any-hover (see the note in 10-primitives.css): on a bare
+   touchscreen any-hover is none, so when closing a tab shifts the list under the
+   finger the newly-under close cannot latch white, and the feedback comes from the
+   surrounding row's :active. A trackpad or Pencil reports hover and gets the
+   brighten, which a (hover: hover) gate denied it — this subtree only ever renders
+   on a coarse-primary device. */
+@media (any-hover: hover) {
   :where(.wt-root) .wt-switcher-row-close:hover {
     color: var(--text);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-ui",
-  "version": "5.0.1",
+  "version": "5.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": "GPL-3.0-or-later",
@@ -52,7 +52,7 @@
     "@types/node": "25.9.5",
     "@typescript/native": "npm:typescript@7.0.2",
     "@vitest/coverage-v8": "4.1.10",
-    "eslint": "10.7.0",
+    "eslint": "10.8.0",
     "fast-check": "4.9.0",
     "happy-dom": "20.11.1",
     "html-validate": "11.5.6",

package/src/features/tabs/index.ts

@@ -14,9 +14,11 @@ import type { ActivityMonitorApi } from "../activity-monitor.js";
 import type { MobileToolbarApi } from "../mobile-toolbar.js";
 import { fromHTML } from "../dom.js";
 import { createClickSwallow, placeMenuAt } from "../menu-position.js";
-import type { SessionInfo, Tab } from "./model.js";
+import type { CueStatus, SessionInfo, Tab } from "./model.js";
 import {
   ACTIVE_TAB_KEY,
+  CUE_SEEN_KEY,
+  MAX_PERSISTED_CUE_SEEN,
   MAX_PINNED_NAME,
   STATUS_EXITED,
   SWIPE_HINT_KEY,
@@ -26,9 +28,12 @@ import {
   createSessionAPI,
   createTombstones,
   hasPinnedName,
+  isCueStatus,
   orderedInsertIndex,
+  parseCueSeen,
   parseTabOrder,
   sanitizePinnedName,
+  serializeCueSeen,
   serializeTabOrder,
 } from "./model.js";
 import {
@@ -186,6 +191,29 @@ function writeSavedOrder(ids: readonly string[]): void {
   }
 }
 
+/** readCueSeen loads the acknowledged background-tab cues, or an empty map when
+ *  there is none to trust. Storage itself can throw (Safari private mode, a
+ *  disabled third-party context, an embedder's iframe) and an unreadable map is
+ *  never fatal: the dot simply lights again, exactly as it behaved before
+ *  acknowledgements were remembered. */
+function readCueSeen(): Map<string, CueStatus> {
+  try {
+    return parseCueSeen(localStorage.getItem(CUE_SEEN_KEY));
+  } catch {
+    return new Map<string, CueStatus>();
+  }
+}
+
+/** writeCueSeen persists acknowledgements, best-effort: a full quota must not
+ *  break the dismissal the user just performed on screen. */
+function writeCueSeen(seen: ReadonlyMap<string, CueStatus>): void {
+  try {
+    localStorage.setItem(CUE_SEEN_KEY, serializeCueSeen(seen));
+  } catch {
+    /* storage unavailable or full — the dismissal still holds for this page */
+  }
+}
+
 async function createSessionHonouringRetry(
   api: { create: () => Promise<SessionInfo> },
   ctx: TerminalContext,
@@ -468,6 +496,45 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
       // The session that raised the pending cue, so arriving on that tab (a
       // swipe or any switch) acknowledges it without opening the list.
       let switchNotifyId: string | null = null;
+      // Cues this viewer has already SEEN, per session (see CUE_SEEN_KEY).
+      // Loaded here so a reload starts from what the user already dismissed:
+      // input/done stay LATCHED server-side, and the status stream re-pushes the
+      // latch in the snapshot it sends on every open, so without this a
+      // dismissed dot came back on the next load — and on every SSE reconnect,
+      // which on a phone is just returning to a backgrounded page.
+      const cueSeen = readCueSeen();
+      // markCueSeen records that this viewer has seen `id` holding `status`:
+      // either because that tab is the one on screen, or because the tray listing
+      // every tab's dot was opened. A non-cue status is not an acknowledgeable
+      // event, so it is ignored rather than stored.
+      function markCueSeen(id: string, status: string): void {
+        if (!isCueStatus(status) || cueSeen.get(id) === status) {
+          return;
+        }
+        cueSeen.set(id, status);
+        // Evict the oldest entries so the live map obeys the same cap the parser
+        // does. dropTab prunes a session closed while this page was open, but one
+        // that vanished while the page was CLOSED leaves an entry nothing else
+        // collects; unbounded, that would eventually push the map past the cap and
+        // make the parser discard whatever it read last — dropping fresh
+        // acknowledgements to keep dead ones.
+        while (cueSeen.size > MAX_PERSISTED_CUE_SEEN) {
+          const oldest = cueSeen.keys().next().value;
+          if (oldest === undefined) {
+            break;
+          }
+          cueSeen.delete(oldest);
+        }
+        writeCueSeen(cueSeen);
+      }
+      // forgetCueSeen drops an acknowledgement, so the session's NEXT input/done
+      // is a fresh cue: called when its status moves off the acknowledged value
+      // (a new working phase, an exit) and when the session goes away.
+      function forgetCueSeen(id: string): void {
+        if (cueSeen.delete(id)) {
+          writeCueSeen(cueSeen);
+        }
+      }
       function paintSwitchDot(): void {
         // Reuse the per-tab status-dot colours (single source, css/05-tabs.css
         // .wt-status-dot[data-status="input"|"done"]) instead of re-declaring
@@ -1100,6 +1167,13 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
         }
         // Opening the list acknowledges any pending background-tab notification:
         // the user is now looking at the tabs, so clear the switch button's dot.
+        // The tray lists EVERY tab with its own status dot, so every latched tab
+        // is acknowledged here, not just the cue's latest subject — several tabs
+        // can be latched at once while the dot only ever showed the newest, and an
+        // unacknowledged sibling would re-raise it on the next load.
+        for (const t of tabList) {
+          markCueSeen(t.id, t.dot.dataset["status"] ?? "");
+        }
         clearSwitchNotify();
         renderSwitcherList();
         setExpandedState(true);
@@ -1371,8 +1445,11 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
         activeId = next.id;
         // Arriving on the tab that raised the switch-button cue resolves it
         // (a swipe through the tabs must dismiss the dot, not only opening the
-        // list).
+        // list). Its current latch is acknowledged whether or not it was the
+        // cue's subject: the terminal is now on screen, so a reload must not
+        // notify about a state the user just looked at.
         acknowledgeSwitchNotify(next.id);
+        markCueSeen(next.id, next.dot.dataset["status"] ?? "");
         try {
           localStorage.setItem(ACTIVE_TAB_KEY, next.id);
         } catch {
@@ -1749,8 +1826,11 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
         // the server reaping it cannot re-adopt the just-closed tab.
         tombstones.add(id);
         // A pending switch-button cue whose subject just closed is moot: clear
-        // it rather than leaving a dot no tab visit can ever resolve.
+        // it rather than leaving a dot no tab visit can ever resolve. Its stored
+        // acknowledgement goes too — the session is gone, so the entry would only
+        // sit in storage forever.
         acknowledgeSwitchNotify(id);
+        forgetCueSeen(id);
         tab.aria.remove();
         // Remove immediately (no exit animation): a lingering element made the
         // "+" teleport after a delay, and made a last-tab replacement appear in
@@ -2263,7 +2343,20 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
         // list opens. The active surface keeps its own needs-input cue (see
         // syncMobile); this is the moved + upgraded, glanceable version on the
         // dedicated button.
-        if (rec.id !== activeId && (rec.status === "input" || rec.status === "done")) {
+        //
+        // Both statuses are LATCHED server-side, so this runs on re-delivered
+        // state as well as on genuine transitions: every SSE (re)open pushes a
+        // snapshot and the poll fallback re-lists every few seconds. What makes a
+        // dismissal stick across those is cueSeen — a latch this viewer already
+        // acknowledged raises nothing, while a status that moved on drops the
+        // acknowledgement so the next latch is a fresh cue.
+        if (!isCueStatus(rec.status)) {
+          forgetCueSeen(rec.id);
+        } else if (rec.id === activeId) {
+          // The user is looking at this terminal as it latches, so there is
+          // nothing to notify — and nothing to re-raise once they move away.
+          markCueSeen(rec.id, rec.status);
+        } else if (cueSeen.get(rec.id) !== rec.status) {
           switchNotify = rec.status;
           switchNotifyId = rec.id;
           paintSwitchDot();

package/src/features/tabs/model.ts

@@ -87,6 +87,85 @@ export function serializeTabOrder(ids: readonly string[]): string {
   return JSON.stringify(ids.slice(0, MAX_PERSISTED_TAB_ORDER));
 }
 
+/** The two session statuses that raise the mobile switcher's aggregate attention
+ *  cue: a background terminal blocked on the user ("input") or one whose turn
+ *  finished ("done"). Declared once here so the raise test and the
+ *  acknowledgement store cannot disagree about which statuses are cue-worthy. */
+export type CueStatus = "input" | "done";
+
+/** isCueStatus narrows a raw server status to a cue-worthy one. */
+export function isCueStatus(status: string): status is CueStatus {
+  return status === "input" || status === "done";
+}
+
+/** localStorage key for the cues this viewer has already SEEN: session id -> the
+ *  latched status that was acknowledged.
+ *
+ *  It has to be remembered, because dismissing the cue does not change the
+ *  session: `input` and `done` are LATCHED server-side (the engine clears them
+ *  only on the session's next working phase) and the status stream re-delivers
+ *  the latch in the snapshot it pushes on every open. So a dismissed dot came
+ *  back on the next page load — and, since the snapshot is re-pushed on every
+ *  SSE reconnect, on a phone simply returning to a backgrounded page.
+ *
+ *  Client-side for the same reason as ACTIVE_TAB_KEY and TAB_ORDER_KEY: "I have
+ *  seen this" is a property of the VIEWER, not of the session. A phone
+ *  acknowledging a finished turn must not blank the dot on the desktop watching
+ *  the same server, so this needs no engine API and the session REST surface
+ *  stays the fixed four routes.
+ *
+ *  Keyed per session rather than as one latest-wins slot: several background tabs
+ *  can hold a latched status at once while the cue only ever shows the newest, so
+ *  a single-slot acknowledgement would let every other one re-raise the dot on
+ *  the next load. */
+export const CUE_SEEN_KEY = "wt-cue-seen";
+
+/** Bound on the acknowledgement map, same reasoning as MAX_PERSISTED_TAB_ORDER:
+ *  every key is a live session server-side, so a real one is nowhere near this,
+ *  and a corrupted or hostile stored value cannot make the restore path do
+ *  unbounded work. */
+export const MAX_PERSISTED_CUE_SEEN = 200;
+
+/** parseCueSeen reads stored acknowledgements into a clean map. Anything it
+ *  cannot trust is dropped (or, for a broken document, all of it): a lost
+ *  acknowledgement only re-lights a dot the user can dismiss again, so degrading
+ *  to "nothing acknowledged" is always safe. Pure, so it is testable without a
+ *  storage backend; the caller owns the localStorage read and its try/catch. */
+export function parseCueSeen(raw: string | null): Map<string, CueStatus> {
+  const out = new Map<string, CueStatus>();
+  if (raw === null || raw === "") {
+    return out;
+  }
+  let data: unknown;
+  try {
+    data = JSON.parse(raw);
+  } catch {
+    return out;
+  }
+  // Arrays and null are typeof "object" too, and neither is a cue map.
+  if (typeof data !== "object" || data === null || Array.isArray(data)) {
+    return out;
+  }
+  for (const [id, status] of Object.entries(data)) {
+    if (id === "" || typeof status !== "string" || !isCueStatus(status)) {
+      continue;
+    }
+    out.set(id, status);
+    if (out.size >= MAX_PERSISTED_CUE_SEEN) {
+      break;
+    }
+  }
+  return out;
+}
+
+/** serializeCueSeen encodes acknowledgements for storage. The caller keeps the
+ *  live map within the cap (see markCueSeen), so this does not truncate: a silent
+ *  truncation here would drop whichever entries the parser happened to read last,
+ *  which is the opposite of what an eviction should discard. */
+export function serializeCueSeen(seen: ReadonlyMap<string, CueStatus>): string {
+  return JSON.stringify(Object.fromEntries(seen));
+}
+
 /** orderedInsertIndex returns where `id` belongs in `current` (a list of tab ids
  *  in display order) to honour the stored arrangement `saved`.
  *