@cplieger/web-terminal-ui 5.4.6 → 5.5.0

package/css/30-tabs.css

@@ -875,9 +875,10 @@
    opacity only, so it composites without repaints (a gradient background is
    rasterized once, unlike an animated box-shadow spread, which repaints every
    frame). It exists only in the three animated states — no stale layer to pin
-   when a dot changes status. (The switcher notification dot never shows any of
-   them — input/done/crashed only — so its position: absolute placement never
-   meets this rule's position: relative.)
+   when a dot changes status. (The switcher notification dot can now show one of
+   them, `failed`, since that status became cue-worthy; 31-switcher.css neutralises
+   this rule and the position: relative above for that surface, so its
+   position: absolute badge placement still holds.)
 
    The final scale is deliberately capped at today's 27px footprint: the mobile
    overview row (.wt-switcher-row-select) clips at overflow: hidden 12.5px from

package/css/31-switcher.css

@@ -326,22 +326,51 @@
 /* Latest-wins background-tab notification dot on the switch button — the moved
    attention cue: the input colour when a background terminal needs input, the
    done colour when a background turn finished, the failed red when a background
-   process crashed. Those three only — the rule the user set is "only states that
-   want the user, like a notification", so the ongoing progress states (working /
-   warning / failed) never raise it. Reuses the exact .wt-status-dot rules
-   (30-tabs.css, --status-* tokens) so it matches the per-tab dots. Hidden until
-   the tabs feature sets data-status; cleared when the list opens
-   (expandSwitcher). */
+   process crashed or reported an error. Those four only (CueStatus) — the rule
+   the user set is "only states that want the user, like a notification", so the
+   ongoing progress states (working / warning) never raise it. `failed` DOES,
+   because OSC 9;4 state 2 is a result the program parked rather than a phase in
+   progress; the override below is what keeps it looking like a notification here.
+   Reuses the exact .wt-status-dot rules (30-tabs.css, --status-* tokens) so it
+   matches the per-tab dots. Hidden until the tabs feature sets data-status;
+   cleared when the list opens (expandSwitcher). */
 :where(.wt-root) .wt-switcher-switch-dot {
   position: absolute;
   top: 6px;
   right: 6px;
 }
 
+/* `failed` is one of 30-tabs.css's three ANIMATED states, and on this surface it
+   must not be. That rule set is why this override exists at all rather than the
+   dot simply inheriting:
+
+   - `.wt-status-dot[data-status="failed"]` is specificity (0,2,0) and sets
+     `position: relative`, which BEATS the (0,1,0) `position: absolute` above
+     (`:where()` contributes nothing), so the dot would leave its badge corner and
+     land in the button's normal flow, displacing the icon.
+   - It also attaches the glow ::before and the travelling-wave ::after, pinning a
+     perpetual animation to the switch button for a state that persists until the
+     program's next status change.
+
+   So `failed` renders here the way `crashed` already does: static solid red in the
+   badge corner. Colour needs no restating — background/border-color resolve
+   through --dot-color to the same --status-failed either way. */
+:where(.wt-root) .wt-switcher-switch-dot[data-status="failed"] {
+  position: absolute;
+  animation: none;
+  transform: none;
+}
+
+:where(.wt-root) .wt-switcher-switch-dot[data-status="failed"]::before,
+:where(.wt-root) .wt-switcher-switch-dot[data-status="failed"]::after {
+  content: none;
+}
+
 /* The dot carries the .wt-status-dot class, so its size, shape, and colour come
-   straight from the shared .wt-status-dot[data-status="input"|"done"|"crashed"]
-   rules (30-tabs.css) — the SAME dot colours every tab already uses, defined
-   once. None of the three animates, so nothing here can pin a wave layer.
+   straight from the shared .wt-status-dot[data-status="input"|"done"|"crashed"|
+   "failed"] rules (30-tabs.css) — the SAME dot colours every tab already uses,
+   defined once. Three of the four animate nothing; `failed` is neutralised
+   directly above, so nothing here can pin a wave layer.
    .wt-status-dot is display:none by default; force it visible only while a
    notification is set (data-status present). */
 :where(.wt-root) .wt-switcher-switch-dot[data-status] {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-ui",
-  "version": "5.4.6",
+  "version": "5.5.0",
   "type": "module",
   "description": "Reference touch-first browser UI for @cplieger/web-terminal-engine: a composable kernel + feature modules (tabs, activity monitor, mobile toolbar, context menu, IME, predictive echo, viewport handling) and CSS. One createTerminal() call.",
   "license": "MPL-2.0",

package/src/features/tabs/attention.ts

@@ -0,0 +1,234 @@
+// tabs/attention.ts — the unseen-cue set, rendered onto the surfaces that exist
+// OUTSIDE this page's chrome: the browser tab title, the installed app's icon
+// badge, and the tab icon.
+//
+// Why these are needed at all: a tab holding a latched status paints a dot on its
+// chip, and that dot is not reliably on screen. The desktop strip scrolls
+// horizontally once it is full, a narrow coarse-pointer device hides the strip
+// entirely (only the active row plus the switcher's aggregate dot remain), and a
+// hidden page shows no chrome at all. notify.ts already covers the last case with
+// a browser Notification, but that API is absent on iOS Safari outside an
+// installed web app, which is exactly where this UI spends its time.
+//
+// STATE, not events. A notification fires once per occurrence and is deduped on a
+// sequence number; everything here is a pure render of what is currently true, so
+// it is safe to recompute on every status sweep and each sink no-ops when nothing
+// changed. That split is why this module and notify.ts stay separate.
+//
+// The set is CueStatus and nothing else, so these surfaces cannot disagree with
+// 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.
+
+import { type CueStatus, cueIconName, isUnseenCue, worseCue } from "./model.js";
+
+/** What the fold reads per tab. A structural type, so the caller passes its own
+ *  tab objects without this module knowing what else they carry. */
+export interface CueCandidate {
+  readonly id: string;
+  readonly status: string;
+}
+
+/** The whole attention state, and the only thing the sinks are allowed to see. */
+export interface Attention {
+  /** How many sessions hold an unacknowledged cue. */
+  readonly count: number;
+  /** The most severe of them, or "" when there is none. */
+  readonly worst: CueStatus | "";
+}
+
+export const NO_ATTENTION: Attention = { count: 0, worst: "" };
+
+/** summarize folds the tab list and this viewer's acknowledgements into the one
+ *  value every surface renders.
+ *
+ *  A COUNT for the title and the badge, a single WORST for the icon. That split
+ *  is deliberate: a count is set-valued, so it needs no rule for choosing among
+ *  sessions, and severity is a total order, so the icon's choice is not arbitrary
+ *  either. Neither surface can name a session, which is the standing constraint
+ *  on anything written to a page-wide surface here (see the decision against
+ *  per-session progress in the document title, index.ts). */
+export function summarize(
+  tabs: readonly CueCandidate[],
+  seen: ReadonlyMap<string, CueStatus>,
+): Attention {
+  let count = 0;
+  let worst: CueStatus | "" = "";
+  for (const tab of tabs) {
+    if (!isUnseenCue(tab.status, tab.id, seen)) {
+      continue;
+    }
+    count += 1;
+    worst = worseCue(worst, tab.status);
+  }
+  return { count, worst };
+}
+
+/** The capabilities the sinks need, all injected, all optional except the title.
+ *
+ *  An absent capability is an absent sink and therefore a silent no-op, the same
+ *  contract notify.ts uses for a missing Notification constructor: an unsupported
+ *  surface is a normal state of the world, not an error to report.
+ *
+ *  Two of these can also fail INVISIBLY, and that is accepted rather than
+ *  handled. `setBadge` resolves on Linux where the desktop paints no badge at
+ *  all, and `setIcon` assigns an href that Safari ignores because it caches the
+ *  first icon it fetched. Neither is detectable, and neither costs anything when
+ *  it fails, because the title is not gated on any capability and so is the
+ *  floor: every platform that renders a title at all gets the count. Do not
+ *  arrange these into a fallback ladder where the title only appears if the
+ *  others are missing — on those two platforms the detection would report
+ *  success and the user would be left with nothing. */
+export interface AttentionEnv {
+  /** Set (or clear, with "") the document-title prefix. The kernel's composing
+   *  writer, so this cannot be erased by a program's OSC 0/2 window title. */
+  titlePrefix: (text: string) => void;
+  /** Set the installed app's icon badge to a count, or clear it at zero. */
+  setBadge?: ((count: number) => void) | undefined;
+  /** Point the page's icon links at a variant, or restore them with null. */
+  setIcon?: ((variant: "input" | "done" | "alert" | null) => void) | undefined;
+}
+
+export interface AttentionSurfaces {
+  /** Render an attention state. Idempotent: a value equal to the last one
+   *  applied touches nothing. */
+  apply(next: Attention): void;
+}
+
+/** titlePrefixFor is the title text for a count, and the format is load-bearing
+ *  enough to name: the count goes FIRST, because a browser tab strip truncates a
+ *  title to its first few characters and a suffix would be the part that is cut.
+ *  Parenthesised digits are also the convention every mail and chat client uses,
+ *  so it needs no legend. */
+export function titlePrefixFor(count: number): string {
+  return count > 0 ? `(${String(count)}) ` : "";
+}
+
+export function createAttention(env: AttentionEnv): AttentionSurfaces {
+  // Last applied, so each sink is called only on a real change. This matters
+  // beyond cost: the document title doubles as the browser-tab label and the
+  // bookmark name, and re-assigning an icon href makes some browsers re-fetch it.
+  let applied: Attention = NO_ATTENTION;
+  let first = true;
+
+  return {
+    apply(next: Attention): void {
+      const countChanged = first || next.count !== applied.count;
+      const worstChanged = first || next.worst !== applied.worst;
+      first = false;
+      applied = next;
+
+      if (countChanged) {
+        env.titlePrefix(titlePrefixFor(next.count));
+        // The badge takes the SAME number as the title, which is the whole
+        // reason both read one fold: two surfaces disagreeing about how many
+        // things want you is worse than either being absent.
+        env.setBadge?.(next.count);
+      }
+      if (worstChanged) {
+        env.setIcon?.(next.worst === "" ? null : cueIconName(next.worst));
+      }
+    },
+  };
+}
+
+/** iconVariantHref rewrites an icon URL to its variant, by the convention the
+ *  asset generator writes (scripts/gen-attention-icons.py): the `favicon` token
+ *  of the filename gains `-<variant>`, so `/favicon.svg` becomes
+ *  `/favicon-input.svg` and `/favicon-32x32.png` becomes
+ *  `/favicon-input-32x32.png`. The extension is preserved, so each link keeps
+ *  pointing at its own format and no `type` attribute has to change.
+ *
+ *  A URL whose filename does not start with `favicon` is returned unchanged,
+ *  which leaves that link alone rather than pointing it at a 404. Exported for
+ *  the test that pins this against the generator's own naming. */
+export function iconVariantHref(href: string, variant: string): string | null {
+  const match = /(^|\/)favicon(?=[-.])/.exec(href);
+  if (!match) {
+    return null;
+  }
+  const at = match.index + match[0].length;
+  return `${href.slice(0, at)}-${variant}${href.slice(at)}`;
+}
+
+/** browserAttentionEnv binds the sinks to the real browser, given the kernel's
+ *  title setter. Everything optional is decided HERE, once, so the core never
+ *  probes for a capability.
+ *
+ *  `icons` opts the icon sink in. It is off unless the consumer asks for it,
+ *  because it needs asset files the library cannot ship: the dot's colour comes
+ *  from the app's own `--status-*` theme, so the variants are per-app artifacts.
+ */
+export function browserAttentionEnv(
+  titlePrefix: (text: string) => void,
+  icons: boolean,
+): AttentionEnv {
+  const env: AttentionEnv = { titlePrefix };
+
+  // The Badging API, read through `unknown` for the same reason notify.ts reads
+  // Notification that way: it is absent on most browsers and must degrade rather
+  // than be asserted. Installed apps only — a badge lives on an app icon, which
+  // exists only after the app is installed.
+  const nav: unknown = globalThis.navigator;
+  const setAppBadge = (nav as { setAppBadge?: unknown } | undefined)?.setAppBadge;
+  const clearAppBadge = (nav as { clearAppBadge?: unknown } | undefined)?.clearAppBadge;
+  if (typeof setAppBadge === "function") {
+    env.setBadge = (count: number): void => {
+      // Always a NUMBER, never the spec's bare flag form: iOS renders nothing at
+      // all for `setAppBadge()` with no argument. Zero clears, via clearAppBadge
+      // where it exists (the documented way) and setAppBadge(0) otherwise.
+      //
+      // Both return promises that reject on an unsupported platform, so the
+      // rejection is swallowed: a badge the OS declines to paint is not an error
+      // this page can do anything about, and an unhandled rejection in a status
+      // sweep would be reported as a page fault.
+      try {
+        const call =
+          count > 0
+            ? (setAppBadge as (n: number) => unknown).call(nav, count)
+            : typeof clearAppBadge === "function"
+              ? (clearAppBadge as () => unknown).call(nav)
+              : (setAppBadge as (n: number) => unknown).call(nav, 0);
+        void Promise.resolve(call).catch(() => {
+          /* an OS that will not paint a badge is a title-only OS */
+        });
+      } catch {
+        /* a synchronous throw is the same non-event */
+      }
+    };
+  }
+
+  if (icons) {
+    // Every icon link, not one of them: which link a browser picks differs
+    // between browsers (Chrome prefers the SVG), so mutating a single element is
+    // unreliable. apple-touch-icon is deliberately NOT matched — `rel~="icon"`
+    // does not select it — because that icon and the manifest's are cached by the
+    // OS when the app is installed and a swap cannot reach them.
+    const links = [...document.querySelectorAll<HTMLLinkElement>('link[rel~="icon"]')];
+    const originals = new Map<HTMLLinkElement, string>();
+    for (const link of links) {
+      originals.set(link, link.getAttribute("href") ?? "");
+    }
+    if (links.length > 0) {
+      env.setIcon = (variant): void => {
+        for (const link of links) {
+          const original = originals.get(link) ?? "";
+          if (variant === null) {
+            link.setAttribute("href", original);
+            continue;
+          }
+          const next = iconVariantHref(original, variant);
+          if (next !== null) {
+            link.setAttribute("href", next);
+          }
+        }
+      };
+    }
+  }
+
+  return env;
+}

package/src/features/tabs/index.ts

@@ -32,6 +32,7 @@ import {
   hasPinnedName,
   isCueStatus,
   isEndedStatus,
+  isUnseenCue,
   normalizeProgress,
   orderedInsertIndex,
   parseCueSeen,
@@ -41,6 +42,7 @@ import {
   statusPhrase,
   tabAccessibleName,
 } from "./model.js";
+import { NO_ATTENTION, browserAttentionEnv, createAttention, summarize } from "./attention.js";
 import { browserNotifierEnv, createNotifier } from "./notify.js";
 import {
   REORDER_MOVE_EPS_PX,
@@ -133,6 +135,25 @@ export interface TabsOptions {
    *  then merely confirms. Default false (evidence-driven reveal: a plain
    *  shell keeps clean, label-only tabs). presetAgentTabbed enables this. */
   presumeReports?: boolean;
+  /** Swap the page's icon links to a status variant while a background session
+   *  holds an unacknowledged cue, so the browser tab icon carries the same colour
+   *  its chip's dot does. Default false, because it needs asset files the library
+   *  cannot ship: the dot's colour comes from the app's own `--status-*` theme, so
+   *  the variants are per-app artifacts.
+   *
+   *  Enabling it is a promise that those files exist. For every
+   *  `link[rel=icon]` whose filename starts with `favicon`, three variants must
+   *  be served alongside it with `-input`, `-done` and `-alert` inserted after
+   *  that token (`/favicon.svg` needs `/favicon-input.svg`; `/favicon-32x32.png`
+   *  needs `/favicon-input-32x32.png`). Generate them with
+   *  `scripts/gen-attention-icons.py`, which writes exactly those names, and
+   *  assert their presence in the APP's own tests — the library cannot check a
+   *  file it does not ship, and a missing variant is a blank tab icon.
+   *
+   *  Not every platform honours it: Safari caches the first icon it fetched and
+   *  ignores later changes, and an installed app has no tab icon at all. The
+   *  title count is not gated on this, so those cases lose nothing. */
+  attentionIcons?: boolean;
 }
 
 // looksLikeHardwareKey reports whether a keydown could only have come from a
@@ -486,8 +507,8 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
       // by each qualifying background-tab event (applyStatus) and cleared when
       // the list opens (expandSwitcher) or the raising tab is visited or closed
       // (acknowledgeSwitchNotify). "" = no pending cue; the dot is hidden. The
-      // cue-worthy set is CueStatus (input / done / crashed — the states that
-      // want the user), declared once in model.ts beside isCueStatus.
+      // cue-worthy set is CueStatus (input / done / crashed / failed — the states
+      // that want the user), declared once in model.ts beside isCueStatus.
       let switchNotify: "" | CueStatus = "";
       // The session that raised the pending cue, so arriving on that tab (a
       // swipe or any switch) acknowledges it without opening the list.
@@ -522,6 +543,10 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
           cueSeen.delete(oldest);
         }
         writeCueSeen(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.
+        paintAttention();
       }
       // forgetCueSeen drops an acknowledgement, so the session's NEXT input/done
       // is a fresh cue: called when its status moves off the acknowledged value
@@ -529,6 +554,7 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
       function forgetCueSeen(id: string): void {
         if (cueSeen.delete(id)) {
           writeCueSeen(cueSeen);
+          paintAttention();
         }
       }
       // OSC 9 Form B notifications: the one signal the specs say to surface
@@ -538,6 +564,60 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
       // degradation — lives in notify.ts; this feature only feeds it events and
       // gestures.
       const notifier = createNotifier(browserNotifierEnv());
+      // The out-of-page surfaces for the SAME unseen-cue set the switch dot
+      // shows: the document-title count, the installed app's icon badge, and the
+      // tab icon. Constructed here so every capability decision is made once,
+      // and fed only through paintAttention below.
+      const attention = createAttention(
+        browserAttentionEnv((text) => {
+          ctx.titlePrefix(text);
+        }, opts.attentionIcons === true),
+      );
+      // pageVisible is the "can the user see this page at all" test, and
+      // visibilityState is the only reliable one: document.hasFocus() is false for
+      // a visible-but-unfocused window, where the terminal IS on screen. Same
+      // signal notify.ts reads, for the same decision.
+      function pageVisible(): boolean {
+        return document.visibilityState !== "hidden";
+      }
+
+      // onPageVisible is the DEFERRED half of the active-tab acknowledgement in
+      // applyStatus: a cue that latched while the page was hidden was deliberately
+      // not acknowledged then, so it could raise the out-of-page surfaces, and this
+      // acknowledges it the moment the user can actually see the terminal.
+      //
+      // Scoped to the ACTIVE tab only. A wholesale clear on becoming visible is the
+      // obvious shortcut and it is wrong: the tab the user returns to is not
+      // necessarily the one that was waiting, and blanking a background tab's cue
+      // it never saw is how a viewer loses the thing it came back for.
+      function onPageVisible(): void {
+        if (!pageVisible() || activeId === null) {
+          return;
+        }
+        const active = tabList.find((t) => t.id === activeId);
+        if (active) {
+          markCueSeen(active.id, statusOf(active));
+        }
+      }
+      document.addEventListener("visibilitychange", onPageVisible);
+
+      // paintAttention re-derives the whole attention state from the tab list and
+      // this viewer's acknowledgements, and hands it to the surfaces.
+      //
+      // A FOLD rather than incremental bookkeeping, for the reason applyServerOrder
+      // is one: there is no state of its own to get out of step, so no path can
+      // leave it stale, and it is cheap enough to run on every tick (a loop over a
+      // handful of tabs, then sinks that no-op when nothing changed). The dot is
+      // the store — statusOf reads each tab's status back off it — so this reads
+      // exactly what the user is looking at.
+      function paintAttention(): void {
+        attention.apply(
+          summarize(
+            tabList.map((t) => ({ id: t.id, status: statusOf(t) })),
+            cueSeen,
+          ),
+        );
+      }
       function paintSwitchDot(): void {
         // Reuse the per-tab status-dot colours (single source, css/05-tabs.css
         // .wt-status-dot[data-status="input"|"done"|"crashed"]) instead of
@@ -552,6 +632,9 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
           swSwitchDot.dataset["status"] = switchNotify;
           swSwitchDot.title = statusPhrase(switchNotify);
         }
+        // The out-of-page surfaces answer to the same set, so they repaint
+        // wherever this does: a raise, and every clear through clearSwitchNotify.
+        paintAttention();
       }
       function clearSwitchNotify(): void {
         switchNotify = "";
@@ -1154,6 +1237,12 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
         }
         maybeSwipeHint();
         applyServerOrder();
+        // Hung off syncChrome for the reason applyServerOrder is: it is the one
+        // function every list mutation already ends with (reorder, create, adopt,
+        // close, reconcile), so no path can forget the out-of-page surfaces. The
+        // fold is idempotent and the sinks no-op when unchanged, so running it
+        // this often costs a comparison.
+        paintAttention();
       }
 
       // The percentage is deliberately NOT written into the browser document
@@ -1165,6 +1254,12 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
       // the bookmark name, and it invites reading one session's progress as the
       // window's. The per-chip prefix carries the same information without the
       // conflict, because each chip shows its own session. Do not add it back.
+      //
+      // What DOES go there is the unseen-cue COUNT (see paintAttention), and it
+      // is not a softening of this rule: a count names no session, so it needs no
+      // arbitrary choice, and it changes only when a cue is raised or acknowledged
+      // rather than on every progress tick. A per-session value in that prefix
+      // would be this same mistake in a new place.
 
       // applyServerOrder re-sorts the strip into the order the SERVER holds, and
       // is the read half of tab-order sync: a drag on another device arrives as a
@@ -3162,11 +3257,19 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
         // acknowledgement so the next latch is a fresh cue.
         if (!isCueStatus(rec.status)) {
           forgetCueSeen(rec.id);
-        } else if (rec.id === activeId) {
+        } else if (rec.id === activeId && pageVisible()) {
           // 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.
+          //
+          // BOTH halves are required, for the reason notify.ts states for its own
+          // suppression rule: keyed on "is this the active tab" alone, this
+          // swallowed the cue of the very session the user left running. That is
+          // the single-session case — one tab is necessarily the active one — and
+          // it is precisely the case the out-of-page surfaces exist for, so a
+          // latch arriving on a HIDDEN page now raises them and is acknowledged
+          // when the user comes back (see onPageVisible).
           markCueSeen(rec.id, rec.status);
-        } else if (cueSeen.get(rec.id) !== rec.status) {
+        } else if (isUnseenCue(rec.status, rec.id, cueSeen)) {
           switchNotify = rec.status;
           switchNotifyId = rec.id;
           paintSwitchDot();
@@ -3977,6 +4080,14 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
             tabList.map((t) => ({ id: t.id, title: t.display, active: t.id === activeId })),
         },
         teardown() {
+          // Restore the out-of-page surfaces first, while the sinks still exist.
+          // The kernel clears the title prefix on its own teardown, but the app
+          // badge and the icon links are OUR state and nothing else will clear
+          // them: the badge is OS-level and outlives the page entirely, and a
+          // destroyed terminal in an embedded panel leaves the document's icon
+          // pointed at a status variant for a tab that no longer exists.
+          // Change-gated, so this is a no-op when nothing was lit.
+          attention.apply(NO_ATTENTION);
           tornDown = true;
           resolveImpl = null;
           offStatus?.();
@@ -3985,6 +4096,7 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
           offArmed?.();
           offMenuKey();
           document.removeEventListener("click", onDocClickMenu);
+          document.removeEventListener("visibilitychange", onPageVisible);
           document.removeEventListener("contextmenu", onDocContextMenu);
           document.removeEventListener("pointerup", onDocTapDismiss, true);
           document.removeEventListener("dragover", onDocTabDrop);

package/src/features/tabs/model.ts

@@ -192,20 +192,79 @@ export const ACTIVE_TAB_KEY = "wt-active-session";
 // One-time "swipe to switch" hint, remembered across loads.
 export const SWIPE_HINT_KEY = "wt-swipe-hint-seen";
 
-/** The session statuses that raise the mobile switcher's aggregate attention
- *  cue. The rule is "only states that want the user — it's like a notification":
- *  a background terminal blocked on the user ("input"), one whose turn finished
- *  ("done"), and one whose process died badly ("crashed"). The three animated
- *  progress states are deliberately excluded — working / warning / failed are
- *  ongoing and informational, and an animated dot pinned to the switch button
- *  would nag with nothing to act on. Declared once here so the raise test and
- *  the acknowledgement store cannot disagree about which statuses are
- *  cue-worthy. */
-export type CueStatus = "input" | "done" | "crashed";
+/** The session statuses that raise an attention cue: the mobile switcher's
+ *  aggregate dot, and the three out-of-page surfaces derived from the same set
+ *  (see attention.ts). The rule is "only states that want the user — it's like a
+ *  notification": a background terminal blocked on the user ("input"), one whose
+ *  turn finished ("done"), one whose process died badly ("crashed"), and one that
+ *  reported an error ("failed").
+ *
+ *  `working` and `warning` are excluded because they are ONGOING and
+ *  informational: an animated dot pinned to the switch button would nag with
+ *  nothing to act on. `failed` was excluded on the same reasoning and that was
+ *  wrong — OSC 9;4 state 2 is not ongoing, it is a result the program parked and
+ *  does not revisit until its next state change, which is exactly the shape of a
+ *  thing to tell the user about. It is also the half of "red" a viewer cares most
+ *  about: `crashed` was already here, so an errored turn raised nothing while a
+ *  dead process raised everything.
+ *
+ *  Declared once here so the raise test, the acknowledgement store and every
+ *  attention sink cannot disagree about which statuses are cue-worthy. */
+export type CueStatus = "input" | "done" | "crashed" | "failed";
+
+/** Severity order over CueStatus, most severe first, AND the complete set: this
+ *  array is what isCueStatus tests against, so the type and the runtime list
+ *  cannot drift the way two hand-maintained four-way checks could.
+ *
+ *  The order is read by the one surface that can show a single state (the browser
+ *  tab icon), which paints the most severe unseen cue. That is a total order and
+ *  so a defensible rule, unlike picking a session.
+ *
+ *  A dead process outranks a reported error (the session is gone, not merely
+ *  unhappy), an error outranks a request for input, and a finished turn is the
+ *  mildest thing worth a cue at all. */
+export const CUE_SEVERITY: readonly CueStatus[] = [STATUS_CRASHED, STATUS_FAILED, "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" || status === STATUS_CRASHED;
+  return (CUE_SEVERITY as readonly string[]).includes(status);
+}
+
+/** worseCue returns whichever of two cues is more severe; "" means no cue. */
+export function worseCue(a: CueStatus | "", b: CueStatus | ""): CueStatus | "" {
+  if (a === "") {
+    return b;
+  }
+  if (b === "") {
+    return a;
+  }
+  return CUE_SEVERITY.indexOf(a) <= CUE_SEVERITY.indexOf(b) ? a : b;
+}
+
+/** The icon variant a cue paints, which is NOT one per status: `crashed` and
+ *  `failed` both render --status-failed, so they share one asset. An app ships
+ *  one icon per name returned here (see scripts/gen-attention-icons.py). */
+export function cueIconName(status: CueStatus): "input" | "done" | "alert" {
+  if (status === "input" || status === "done") {
+    return status;
+  }
+  return "alert";
+}
+
+/** isUnseenCue reports whether a session's CURRENT status is a cue this viewer
+ *  has not acknowledged. The single predicate behind both the raise and the
+ *  attention count, so a dot can never light for a session the count omits.
+ *
+ *  Note what it does NOT consider: whether the session is the active tab. A
+ *  latch arriving on the active tab is acknowledged at arrival (applyStatus), so
+ *  it is already absent from the unseen set by the time anything folds over it,
+ *  and no caller needs a special case. */
+export function isUnseenCue(
+  status: string,
+  id: string,
+  seen: ReadonlyMap<string, CueStatus>,
+): status is CueStatus {
+  return isCueStatus(status) && seen.get(id) !== status;
 }
 
 /** localStorage key for the cues this viewer has already SEEN: session id -> the

package/src/kernel/kernel.ts

@@ -258,6 +258,31 @@ function buildTerminal(
     narrowObserver.observe(root);
   }
 
+  // --- Document title (kernel-owned, composed from two inputs) ---
+  //
+  // The page has ONE title and two things want to write it: a program's OSC 0/2
+  // window title, and a feature's attention prefix (tabs' unseen-cue count). So
+  // the kernel holds both and is the only assigner. Two direct writers was the
+  // alternative and it cannot work: whichever ran last won, so a shell or an
+  // editor emitting OSC 2 silently erased the prefix, and there is no ordering
+  // that fixes it because both inputs change on their own schedule.
+  //
+  // The base starts as whatever the served document declared, so a consumer that
+  // never receives an OSC title (web-terminal-kiro sets kiro-cli's
+  // chat.terminalTitle=false) keeps its own <title> as the base rather than
+  // needing to declare it twice.
+  let baseTitle = document.title;
+  let titlePrefixText = "";
+  function paintTitle(): void {
+    const next = titlePrefixText + baseTitle;
+    // Idempotent: the title doubles as the browser-tab label and the bookmark
+    // name, and this runs on every status sweep, so an unchanged assignment must
+    // not churn it.
+    if (document.title !== next) {
+      document.title = next;
+    }
+  }
+
   // Toast surface (kernel-owned shared primitive, section 22.3).
   const toastEl = document.createElement("div");
   toastEl.className = "wt-toast";
@@ -607,7 +632,8 @@ function buildTerminal(
         // when it redraws its prompt after idling, so hold the last-good browser
         // title instead of flickering blank.
         if (msg.title.trim() !== "") {
-          document.title = msg.title;
+          baseTitle = msg.title;
+          paintTitle();
         }
         bus.emit("wire:title", { session: activeSession?.id ?? "", title: msg.title });
       } else if (msg.type === "modes") {
@@ -1216,6 +1242,10 @@ function buildTerminal(
         // place rather than at each caller.
         loadingStatus.reason(message);
       },
+      titlePrefix: (text) => {
+        titlePrefixText = text;
+        paintTitle();
+      },
       tablist: () => tablistController,
       newLineStore: (sessionId) => {
         // Registered on EVERY path, because this factory is the only way a store
@@ -1307,6 +1337,12 @@ function buildTerminal(
     scrollbackKeeper?.flush();
     scrollbackKeeper?.stop();
     teardownFeatures();
+    // A destroyed terminal must not leave its attention prefix on the page: the
+    // tab it counted is gone, and the title outlives this runtime (an embedded
+    // panel closing, a reload path). The base is left alone -- it belongs to the
+    // document, not to us.
+    titlePrefixText = "";
+    paintTitle();
     kernelAbort.abort();
     narrowObserver?.disconnect();
     narrowObserver = null;

package/src/kernel/types.ts

@@ -274,6 +274,21 @@ export interface TerminalContext {
    *  re-read the same sentence every few seconds. Also a no-op once the overlay
    *  has been dismissed, so a late retry cannot resurrect it. */
   loadingReason(message: string): void;
+  /** Set the prefix the kernel composes onto the document title, or "" to clear
+   *  it. The kernel is the only writer of `document.title`: it holds the base
+   *  (the served `<title>`, replaced by a program's OSC 0/2 window title) and
+   *  this prefix, and re-composes on either change. A feature that assigned
+   *  `document.title` directly would be erased by the next OSC 2 from any shell
+   *  or editor running in a session, with no ordering that avoids it.
+   *
+   *  Idempotent and safe on every status tick: an unchanged result is not
+   *  re-assigned, because the title doubles as the browser-tab label and the
+   *  bookmark name. Cleared automatically when the terminal is destroyed.
+   *
+   *  Keep it an AGGREGATE. A page has one title while this UI multiplexes many
+   *  sessions, so any per-session value has to pick a session arbitrarily (see
+   *  the standing decision against writing progress here in features/tabs). */
+  titlePrefix(text: string): void;
   /** The kernel's tablist/tabpanel ARIA controller (used by tabs). */
   tablist(): TablistController;
 

package/src/presets/agent-tabbed.ts

@@ -1,7 +1,7 @@
 // presetAgentTabbed: the tabbed composition tuned for an agent shell.
 
 import type { TerminalFeature } from "../kernel/types.js";
-import { buildTabbed } from "./tabbed.js";
+import { type TabbedPresetOptions, buildTabbed } from "./tabbed.js";
 
 /** Tabbed UI for an agent shell (web-terminal-kiro). Same features as
  *  presetTabbed, tuned for sessions that ARE agents:
@@ -15,6 +15,6 @@ import { buildTabbed } from "./tabbed.js";
  *  status classifier that maps OSC 9 notifications to done/needs-input, and the
  *  input-derived session name (terminal.WithInputTitle), which the agent host
  *  enables because its program's own window title is not worth showing. */
-export function presetAgentTabbed(): TerminalFeature<unknown>[] {
-  return buildTabbed(true);
+export function presetAgentTabbed(opts: TabbedPresetOptions = {}): TerminalFeature<unknown>[] {
+  return buildTabbed(true, opts);
 }

package/src/presets/tabbed.ts

@@ -27,7 +27,22 @@ 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. */
-export function buildTabbed(agentShell: boolean): TerminalFeature<unknown>[] {
+/** 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 scripts/gen-attention-icons.py, which writes them. */
+  attentionIcons?: boolean;
+}
+
+export function buildTabbed(
+  agentShell: boolean,
+  opts: TabbedPresetOptions = {},
+): TerminalFeature<unknown>[] {
   const kb = mobileToolbar({ externalToggle: true });
   const monitor = activityMonitor();
   return [
@@ -38,6 +53,7 @@ export function buildTabbed(agentShell: boolean): TerminalFeature<unknown>[] {
       keyboardToggle: kb,
       activityMonitor: monitor,
       presumeReports: agentShell,
+      attentionIcons: opts.attentionIcons === true,
     }),
     animations(),
   ];
@@ -49,6 +65,6 @@ export function buildTabbed(agentShell: boolean): TerminalFeature<unknown>[] {
  *  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. */
-export function presetTabbed(): TerminalFeature<unknown>[] {
-  return buildTabbed(false);
+export function presetTabbed(opts: TabbedPresetOptions = {}): TerminalFeature<unknown>[] {
+  return buildTabbed(false, opts);
 }

package/src/presets.ts

@@ -19,4 +19,5 @@
 export { presetSingle } from "./presets/single.js";
 export { presetTouch } from "./presets/touch.js";
 export { presetTabbed } from "./presets/tabbed.js";
+export type { TabbedPresetOptions } from "./presets/tabbed.js";
 export { presetAgentTabbed } from "./presets/agent-tabbed.js";