@cplieger/web-terminal-ui 8.6.0-dev.4 → 8.6.0-dev.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-ui",
-  "version": "8.6.0-dev.4",
+  "version": "8.6.0-dev.5",
   "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",
@@ -64,7 +64,7 @@
     "html-validate": "11.16.2",
     "knip": "6.41.0",
     "playwright": "1.64.0",
-    "prettier": "3.9.9",
+    "prettier": "3.9.10",
     "stylelint": "17.16.0",
     "stylelint-config-standard": "40.0.0",
     "typescript": "npm:@typescript/typescript6@6.0.2",

package/src/features/tabs/index.ts

@@ -28,7 +28,6 @@ import {
 } from "./route.js";
 import type { CueStatus, PaneLayout, SessionInfo, StatusRecord, Tab } from "./model.js";
 import {
-  CUE_SEEN_KEY,
   MAX_PERSISTED_CUE_SEEN,
   MAX_PINNED_NAME,
   PROGRESS_ABSENT,
@@ -39,6 +38,8 @@ import {
   createSessionAPI,
   createTombstones,
   cueIconName,
+  cueSeenID,
+  cueSeenKey,
   foldedCueStatus,
   hasPinnedName,
   isCueStatus,
@@ -51,7 +52,6 @@ import {
   parseCueSeen,
   renderedProgress,
   sanitizePinnedName,
-  serializeCueSeen,
   statusPhrase,
   summarizeCues,
   tabAccessibleName,
@@ -196,26 +196,47 @@ const CATCHUP_SETTLE_MS = 250;
  *  multiple frames; ordinary streaming must never arm the cue. */
 const CATCHUP_MIN_BACKLOG = 400;
 
+function* storedCueSeen(win: Pick<Window, "localStorage">): Generator<readonly [string, string]> {
+  try {
+    const store = win.localStorage;
+    for (let i = 0; i < store.length; i++) {
+      const key = store.key(i);
+      const id = key === null ? null : cueSeenID(key);
+      if (key !== null && id !== null) {
+        yield [id, store.getItem(key) ?? ""];
+      }
+    }
+  } catch {
+    /* storage unavailable */
+  }
+}
+
 /** The acknowledged background-tab cues, or an empty map when storage throws or
  *  holds nothing trustworthy: the dot simply lights again. */
 function readCueSeen(win: Pick<Window, "localStorage">): Map<string, CueStatus> {
+  return parseCueSeen(storedCueSeen(win));
+}
+
+/** Best-effort: a full quota must not break the dismissal the user just
+ *  performed on screen. */
+function writeCueSeen(win: Pick<Window, "localStorage">, id: string, status: CueStatus): void {
   try {
-    return parseCueSeen(win.localStorage.getItem(CUE_SEEN_KEY));
+    win.localStorage.setItem(cueSeenKey(id), status);
   } catch {
-    return new Map<string, CueStatus>();
+    /* storage unavailable or full: the dismissal still holds for this page */
   }
 }
 
-/** writeCueSeen persists acknowledgements, best-effort: a full quota must not
- *  break the dismissal the user just performed on screen. */
-function writeCueSeen(
-  win: Pick<Window, "localStorage">,
-  seen: ReadonlyMap<string, CueStatus>,
-): void {
+/** Remove `id`'s stored acknowledgement only while it still holds `status`:
+ *  another window may since have acknowledged the session's next cue. */
+function dropCueSeen(win: Pick<Window, "localStorage">, id: string, status: CueStatus): void {
   try {
-    win.localStorage.setItem(CUE_SEEN_KEY, serializeCueSeen(seen));
+    const key = cueSeenKey(id);
+    if (win.localStorage.getItem(key) === status) {
+      win.localStorage.removeItem(key);
+    }
   } catch {
-    /* storage unavailable or full — the dismissal still holds for this page */
+    /* storage unavailable: nothing stored to remove */
   }
 }
 
@@ -682,36 +703,40 @@ 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).
+      // Cues this viewer has already SEEN, per session (see CUE_SEEN_PREFIX).
       // 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(win);
+      // The out-of-page surfaces render the SAME unseen-cue set the switch dot
+      // shows, fed only through paintAttention below.
+      const attention = ctx.shell.attention({ icons: opts.attentionIcons === true });
       // 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.
+      // every tab's dot was opened. Every read re-asserts the badge, which may
+      // still show a write the platform dropped though the count is unchanged,
+      // and closes the session's banner; a non-cue status stores nothing.
       function markCueSeen(id: string, status: string): void {
+        attention.resync();
+        ctx.shell.notifications.retract(id);
         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.
+        writeCueSeen(win, id, status);
+        // Evict the oldest so storage obeys the parser's cap: 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.
         while (cueSeen.size > MAX_PERSISTED_CUE_SEEN) {
-          const oldest = cueSeen.keys().next().value;
-          if (oldest === undefined) {
+          const [oldest, held] = cueSeen.entries().next().value ?? [];
+          if (oldest === undefined || held === undefined) {
             break;
           }
           cueSeen.delete(oldest);
+          dropCueSeen(win, oldest, held);
         }
-        writeCueSeen(win, cueSeen);
         // An acknowledgement can change the unseen count without touching the tab
         // list, so syncChrome's sweep is not enough on its own: opening the tray
         // and arriving on a tab both land here and neither adds or removes a chip.
@@ -722,13 +747,13 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
       // (a new working phase, an exit) and when the session goes away. Every
       // caller ends in syncChrome, which repaints the out-of-page surfaces.
       function forgetCueSeen(id: string): void {
-        if (cueSeen.delete(id)) {
-          writeCueSeen(win, cueSeen);
+        const known = cueSeen.get(id);
+        if (known === undefined) {
+          return;
         }
+        cueSeen.delete(id);
+        dropCueSeen(win, id, known);
       }
-      // The out-of-page surfaces render the SAME unseen-cue set the switch dot
-      // shows, fed only through paintAttention below.
-      const attention = ctx.shell.attention({ icons: opts.attentionIcons === true });
       // visibilityState, not document.hasFocus(), which is false for a
       // visible-but-unfocused window where the terminal IS on screen.
       function pageVisible(): boolean {
@@ -753,6 +778,36 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
       ctx.defer(() => {
         doc.removeEventListener("visibilitychange", onPageVisible);
       });
+      // Every page writes the one app badge, so each mirrors the shared map;
+      // otherwise a hidden page keeps counting a cue the reader saw elsewhere.
+      // A null key is another page's localStorage.clear().
+      function onCueSeenStored(e: StorageEvent): void {
+        if (e.key !== null && cueSeenID(e.key) === null) {
+          return;
+        }
+        const stored = readCueSeen(win);
+        for (const id of [...cueSeen.keys()]) {
+          if (!stored.has(id)) {
+            cueSeen.delete(id);
+          }
+        }
+        for (const [id, status] of stored) {
+          if (cueSeen.get(id) !== status) {
+            cueSeen.set(id, status);
+            // Read elsewhere, but only this page can close the banners it posted.
+            ctx.shell.notifications.retract(id);
+          }
+        }
+        if (switchNotifyId !== null && cueSeen.get(switchNotifyId) === switchNotify) {
+          clearSwitchNotify();
+        }
+        attention.resync();
+        paintAttention();
+      }
+      win.addEventListener("storage", onCueSeenStored);
+      ctx.defer(() => {
+        win.removeEventListener("storage", onCueSeenStored);
+      });
 
       // A FOLD over the tab list rather than incremental bookkeeping: no state of
       // its own can go stale, and the shell no-ops when nothing changed.
@@ -3738,11 +3793,13 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
         let streamOpens = 0;
         const offStreamOpen = monitor.onStreamOpen?.(() => {
           streamOpens++;
-          if (streamOpens === 1) {
-            void reconcileOnce();
-          } else {
-            void withPlacementHold(() => inReconcileSlot(reconcileNow));
-          }
+          const settled =
+            streamOpens === 1
+              ? reconcileOnce()
+              : withPlacementHold(() => inReconcileSlot(reconcileNow));
+          void settled.then(() => {
+            attention.resync();
+          });
         });
         if (offStreamOpen) {
           ctx.defer(offStreamOpen);

package/src/features/tabs/model.ts

@@ -282,54 +282,49 @@ export function summarizeCues(
   return { count, worst };
 }
 
-/** localStorage key for the cues this viewer has SEEN: session id -> the
- *  acknowledged status. Remembered because `input` and `done` are latched on the
- *  server and re-delivered in every snapshot, so a dismissed dot came back on
- *  every reload; client-side because "seen" is the VIEWER's, not the session's;
- *  per session because several background tabs can hold a latch at once. */
-export const CUE_SEEN_KEY = "wt-cue-seen";
-
-/** Bound on the acknowledgement map, so a corrupted or hostile stored value
+/** localStorage key prefix for the cues this viewer has SEEN: one key per
+ *  session, `cueSeenKey(id)`, holding the acknowledged status. Remembered because
+ *  `input` and `done` are latched on the server and re-delivered in every
+ *  snapshot, so a dismissed dot came back on every reload; client-side because
+ *  "seen" is the VIEWER's, not the session's. One key per session because every
+ *  window of the app writes here: two windows acknowledging different sessions
+ *  write different keys, where one shared map lets the later write drop the
+ *  other's acknowledgement. */
+const CUE_SEEN_PREFIX = "wt-cue-seen/";
+
+/** The storage key holding `id`'s acknowledgement. */
+export function cueSeenKey(id: string): string {
+  return CUE_SEEN_PREFIX + id;
+}
+
+/** The session id a storage key acknowledges, or null for any other key. */
+export function cueSeenID(key: string): string | null {
+  return key.startsWith(CUE_SEEN_PREFIX) && key.length > CUE_SEEN_PREFIX.length
+    ? key.slice(CUE_SEEN_PREFIX.length)
+    : null;
+}
+
+/** Bound on the acknowledgements read back, so a corrupted or hostile store
  *  cannot make the restore path do unbounded work. */
 export const MAX_PERSISTED_CUE_SEEN = 200;
 
-/** Read stored acknowledgements into a clean map, dropping anything untrusted: a
- *  lost acknowledgement only re-lights a dot the user can dismiss again. */
-export function parseCueSeen(raw: string | null): Map<string, CueStatus> {
+/** Read stored [session id, raw status] entries into a clean map, dropping
+ *  anything untrusted (a lost acknowledgement only re-lights a dot the user can
+ *  dismiss again), and stop reading at the cap. */
+export function parseCueSeen(entries: Iterable<readonly [string, string]>): Map<string, CueStatus> {
   const out = new Map<string, CueStatus>();
-  if (raw === null) {
-    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);
+  for (const [id, status] of entries) {
     if (out.size >= MAX_PERSISTED_CUE_SEEN) {
       break;
     }
+    if (id === "" || !isCueStatus(status)) {
+      continue;
+    }
+    out.set(id, status);
   }
   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));
-}
-
 /** TabOrderKey is what the strip's order is decided by: the server's shared
  *  position for the session, its creation timestamp, and its id. Both `Tab` and
  *  the wire `SessionInfo` carry these three fields, so either can be passed

package/src/kernel/attention.ts

@@ -40,17 +40,18 @@ export function iconVariantHref(href: string, variant: string): string | null {
   return `${href.slice(0, at)}-${variant}${href.slice(at)}`;
 }
 
-/** Render reports onto `sinks`, change-gated on the last rendered value: the
- *  title doubles as the browser-tab label and the bookmark name, and
- *  re-assigning an icon href makes some browsers re-fetch it. `pagehide` restores
- *  the surfaces (a browser remembers ONE icon per URL for the bookmark and the
- *  history row, so a tab closed on a lit cue would leave a status variant standing
- *  in for the app), `pageshow` repaints the last report for a page that came back
- *  from the back-forward cache, and `freeze` changes nothing because a frozen tab
- *  is still in the strip rendering its icon. */
+/** Render reports onto `sinks`. The title and icon are change-gated: the title is
+ *  also the tab label and bookmark name, and re-assigning an icon href makes some
+ *  browsers re-fetch it. The badge is OS state a platform may drop a write to
+ *  without rejecting, so it is also re-asserted on `resync`, a return to visible,
+ *  window focus and `pageshow`. `pagehide` restores the title and icon (a browser
+ *  remembers ONE icon per URL) but leaves the badge, which means "unread" for the
+ *  whole app rather than for this page. */
 export function createAttention(sinks: AttentionSinks, win: Window): AttentionSurface {
-  let reported: AttentionState = NO_ATTENTION;
+  let reported: AttentionState | null = null;
   let rendered: AttentionState | null = null;
+  let badged: number | null = null;
+  let pendingResync: number | null = null;
 
   function render(next: AttentionState): void {
     const countChanged = next.count !== rendered?.count;
@@ -58,24 +59,58 @@ export function createAttention(sinks: AttentionSinks, win: Window): AttentionSu
     rendered = next;
     if (countChanged) {
       sinks.setTitleMark(titleMarkFor(next.count));
-      sinks.setBadge?.(next.count);
     }
     if (iconChanged) {
       sinks.setIcon?.(next.icon);
     }
   }
+  function cancelResync(): void {
+    if (pendingResync !== null) {
+      win.clearTimeout(pendingResync);
+      pendingResync = null;
+    }
+  }
+  function writeBadge(count: number): void {
+    cancelResync();
+    badged = count;
+    sinks.setBadge?.(count);
+  }
+  const listeners = new AbortController();
+  const { signal } = listeners;
+  // Deferred a task so this surface's listener and the caller's report on one
+  // event write once. Before the first report, a write would wipe the badge
+  // another page or a previous run set; after dispose, it would raise a cleared one.
+  function resync(): void {
+    if (reported === null || signal.aborted || pendingResync !== null) {
+      return;
+    }
+    pendingResync = win.setTimeout(() => {
+      pendingResync = null;
+      if (reported !== null && !signal.aborted) {
+        writeBadge(reported.count);
+      }
+    }, 0);
+  }
 
   function onPageGone(): void {
     render(NO_ATTENTION);
   }
   function onPageBack(): void {
-    render(reported);
+    if (reported !== null) {
+      render(reported);
+    }
+    resync();
+  }
+  function onVisibility(): void {
+    if (win.document.visibilityState !== "hidden") {
+      resync();
+    }
   }
-  const listeners = new AbortController();
-  const { signal } = listeners;
   try {
     win.addEventListener("pagehide", onPageGone, { signal });
     win.addEventListener("pageshow", onPageBack, { signal });
+    win.addEventListener("focus", resync, { signal });
+    win.document.addEventListener("visibilitychange", onVisibility, { signal });
   } catch (err) {
     listeners.abort();
     throw err;
@@ -85,10 +120,15 @@ export function createAttention(sinks: AttentionSinks, win: Window): AttentionSu
     report(state) {
       reported = state;
       render(state);
+      if (state.count !== badged) {
+        writeBadge(state.count);
+      }
     },
+    resync,
     dispose() {
       listeners.abort();
       render(NO_ATTENTION);
+      writeBadge(0);
     },
   };
 }

package/src/kernel/notify.ts

@@ -38,24 +38,41 @@ export function shouldNotify(sessionIsActive: boolean, pageVisible: boolean): bo
   return !(sessionIsActive && pageVisible);
 }
 
-/** Bound on the per-session dedupe map: each key is a live session server-side,
- *  so a real page is nowhere near this and a hostile stream cannot grow it. */
+/** Bound on each per-session map: each key is a live session server-side, so a
+ *  real page is nowhere near this and a hostile stream cannot grow it. */
 const MAX_TRACKED_SESSIONS = 200;
 
 export function createNotifier(env: NotifierEnv): Notifier {
   // Highest sequence delivered per session. The engine never replays a
   // notification; this makes a doubled frame unable to notify twice for one event.
   const lastSeq = new Map<string, number>();
+  // The banner on screen per session. A page notification is invisible to
+  // ServiceWorkerRegistration.getNotifications(), so only this reference can
+  // close it once its session is read.
+  const shown = new Map<string, NotificationLike>();
   let armed = false;
   let requested = false;
 
-  function evict(): void {
-    while (lastSeq.size > MAX_TRACKED_SESSIONS) {
-      const oldest = lastSeq.keys().next().value;
+  // `drop` must remove the key, or this never ends.
+  function evict(map: Map<string, unknown>, drop: (id: string) => void): void {
+    while (map.size > MAX_TRACKED_SESSIONS) {
+      const oldest = map.keys().next().value;
       if (oldest === undefined) {
         return;
       }
-      lastSeq.delete(oldest);
+      drop(oldest);
+    }
+  }
+  function retract(id: string): void {
+    const posted = shown.get(id);
+    if (posted === undefined) {
+      return;
+    }
+    shown.delete(id);
+    try {
+      posted.close();
+    } catch {
+      /* a banner the platform already took down */
     }
   }
 
@@ -71,7 +88,7 @@ export function createNotifier(env: NotifierEnv): Notifier {
           return false;
         }
         lastSeq.set(ev.id, seq);
-        evict();
+        evict(lastSeq, (id) => lastSeq.delete(id));
       }
       if (!shouldNotify(view.sessionIsActive, env.pageVisible())) {
         return false;
@@ -90,7 +107,16 @@ export function createNotifier(env: NotifierEnv): Notifier {
         posted.onclick = (): void => {
           view.activate();
           posted.close();
+          if (shown.get(ev.id) === posted) {
+            shown.delete(ev.id);
+          }
         };
+        // Re-inserted so map order is banner age, and the banner evicted is
+        // closed: a dropped reference would leave it (and Android's launcher
+        // dot) up with nothing able to retract it.
+        shown.delete(ev.id);
+        shown.set(ev.id, posted);
+        evict(shown, retract);
         return true;
       } catch {
         // Safari throws on `new Notification` outside an installed PWA.
@@ -117,8 +143,10 @@ export function createNotifier(env: NotifierEnv): Notifier {
         /* a browser that refuses to be asked is a tab-only browser */
       }
     },
+    retract,
     forget(id): void {
       lastSeq.delete(id);
+      retract(id);
     },
   };
 }

package/src/kernel/shell.ts

@@ -438,7 +438,7 @@ function createShellInto(
   function attention(options: AttentionOptions): AttentionReporter {
     // A setup still running past destroy() gets a reporter that writes nothing.
     if (destroyed) {
-      return { report: () => undefined };
+      return { report: () => undefined, resync: () => undefined };
     }
     const surface = createAttention(
       browserAttentionSinks(

package/src/kernel/types.ts

@@ -240,6 +240,12 @@ export interface AttentionReporter {
   /** Render `state`. Idempotent: a state equal to the last one reported touches
    *  nothing, so a status sweep may call it every tick. */
   report(state: AttentionState): void;
+  /** Write the latest reported count to the app badge again on the next task,
+   *  changed or not; a `report` that writes the badge before then satisfies it.
+   *  The page cannot read the badge back and a platform may drop a write
+   *  silently, so a caller resyncs wherever the two may have diverged, ahead of
+   *  the report that follows. A no-op before the first report. */
+  resync(): void;
 }
 
 /** The notification a session status event carries (OSC 9 `<message>`). Both
@@ -276,7 +282,10 @@ export interface Notifier {
   arm(): void;
   /** Note a user gesture: the ONLY moment a permission prompt may be raised. */
   gesture(): void;
-  /** Drop a closed session's dedupe state. */
+  /** Close the notification delivered for `id`, if one is still up: the user has
+   *  seen that session, so the banner no longer reports anything unread. */
+  retract(id: string): void;
+  /** Drop a closed session's dedupe state and retract its notification. */
   forget(id: string): void;
 }