@cplieger/web-terminal-ui 5.1.0 → 5.2.1

package/README.md

@@ -143,12 +143,20 @@ are importable from `…/features/<name>` (`clipboard`, `context-menu`,
   (working, warning, error), the frozen ringed needs-input dot, two static discs
   (a green finished turn, a red crashed process), and two hollow ones (idle and a
   dim ended session). A
-  reported percentage additionally renders a 2px determinate bar on the chip and
-  a `78% ·` prefix on the tab label; it is deliberately never written to the
-  browser document title, since one page title cannot represent several
-  sessions. An OSC 9 notification is posted as a browser
+  reported percentage additionally renders a 2px determinate bar on the chip,
+  shown only while one of those three progress states is the session's current
+  status. The number itself is announced in the tab's accessible name and drawn
+  nowhere: no terminal emulator puts a percentage next to a tab label, and a chip
+  that shrinks toward a 100px floor has no width to spare. It is likewise never
+  written to the browser document title, since one page title cannot represent
+  several sessions. An OSC 9 notification is posted as a browser
   notification when the user is not already looking at that terminal (permission
   is requested on a user gesture; a denial degrades silently to the tab dots).
+  Clicking one switches to the session that raised it: the Notifications API's
+  own click default already focuses the page, and the handler supplies the
+  in-page half. These are non-persistent notifications, so per the API the
+  constructor throws on most mobile browsers, where the notification degrades to
+  the tab dots.
 
 ### Options
 

package/css/10-primitives.css

@@ -38,7 +38,11 @@
   user-select: none;
 }
 
-:where(.wt-root) .wt-btn:active {
+/* Press. The pointerdown-cancelling bar buttons (holdFocusOnPress in
+   features/dom.ts) never enter :active in Firefox, so they paint .wt-pressed on
+   themselves and every press rule in this package matches either. */
+:where(.wt-root) .wt-btn:active,
+:where(.wt-root) .wt-btn.wt-pressed {
   background: var(--text-active);
 }
 

package/css/21-scroll-to-bottom.css

@@ -38,7 +38,11 @@
   border-color: color-mix(in oklch, var(--text) 35%, transparent);
 }
 
-:where(.wt-root) .wt-scroll-bottom:active {
+/* Press fills the background. .wt-pressed rides along: this button cancels its
+   pointerdown default and so never enters :active in Firefox (holdFocusOnPress
+   in features/dom.ts). */
+:where(.wt-root) .wt-scroll-bottom:active,
+:where(.wt-root) .wt-scroll-bottom.wt-pressed {
   background: var(--text-active);
 }
 

package/css/30-tabs.css

@@ -81,6 +81,16 @@
      overlays (.wt-tab-ghost, .wt-tab-menu) are children of .wt-root, not of a
      chip, so this cannot capture them. */
   position: relative;
+  /* ...and the clip that keeps that bar inside the chip. A 2px line at
+     `left: 0; bottom: 0` has square ends, so without this it pokes out through
+     both rounded bottom corners and reads as running edge to edge. The clip is
+     applied to the PADDING box with the chip's inner radius (--radius-inner less
+     the 1px border), which is exactly the shape the bar must follow, and it is
+     what the other two chip sites already do (.wt-switcher-current,
+     .wt-switcher-row-select). Nothing else in the chip needs to escape: the
+     dot's ripple stays within the --sp-2 padding at its visible amplitude, and
+     the rename field's 2px/1px-offset focus ring sits well inside it. */
+  overflow: hidden;
   /* ONE height for every control in the strip: the chip, the "+" and the
      keyboard button all resolve to --touch-target, so a chip and a button can
      never disagree about how tall the row is. Before this the chip's height was
@@ -337,8 +347,11 @@
 
 /* Press: brighten the hover fill with the active-tab fg (the
    .wt-switcher-current press recipe — a lighter press over an already-filled
-   control), keeping the accent glyph. */
-:where(.wt-root) .wt-tab-new:active {
+   control), keeping the accent glyph. .wt-pressed rides along because this
+   button cancels its pointerdown default and so never enters :active in Firefox
+   (holdFocusOnPress in features/dom.ts). */
+:where(.wt-root) .wt-tab-new:active,
+:where(.wt-root) .wt-tab-new.wt-pressed {
   background: color-mix(in oklch, var(--tab-active-bg), var(--tab-active-fg) 12%);
 }
 
@@ -632,7 +645,15 @@
    Painted only while a percentage actually exists: the element carries the
    `hidden` attribute otherwise (paintProgress), so an absent value (-1) renders
    NO bar rather than a zero-width or empty one. Its width is the only inline
-   style — the percentage is data, not styling. */
+   style — the percentage is data, not styling.
+
+   The rounded ENDS are the chip's job, not this rule's: each chip site clips its
+   own overflow (.wt-tab here, .wt-switcher-current and .wt-switcher-row-select in
+   31-switcher.css), so the bar is cut to the chip's inner corner radius at both
+   ends. A radius on the bar itself cannot do that job — a 2px-tall box scales
+   every radius down to 2px under the CSS overlap rule, so it would trace a 2px
+   curve against the chip's --radius-inner one and still square off wherever the
+   percentage stops short of the edge. */
 :where(.wt-root) .wt-progress-bar {
   position: absolute;
   left: 0;
@@ -640,8 +661,6 @@
   height: 2px;
   max-width: 100%;
   background: var(--accent);
-  /* Follow the chip's rounded bottom-left corner instead of poking out of it. */
-  border-bottom-left-radius: inherit;
   pointer-events: none;
 }
 

package/css/31-switcher.css

@@ -339,7 +339,10 @@
   }
 }
 
-:where(.wt-root) .wt-switcher-new:active {
+/* Press. .wt-pressed rides along: this button cancels its pointerdown default
+   and so never enters :active in Firefox (holdFocusOnPress in features/dom.ts). */
+:where(.wt-root) .wt-switcher-new:active,
+:where(.wt-root) .wt-switcher-new.wt-pressed {
   background: var(--tab-hover-bg);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-ui",
-  "version": "5.1.0",
+  "version": "5.2.1",
   "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",
@@ -56,8 +56,8 @@
     "eslint": "10.8.0",
     "fast-check": "4.9.0",
     "happy-dom": "20.11.1",
-    "html-validate": "11.5.6",
-    "knip": "6.29.0",
+    "html-validate": "11.6.0",
+    "knip": "6.30.0",
     "prettier": "3.9.6",
     "stylelint": "17.14.1",
     "stylelint-config-standard": "40.0.0",

package/src/features/dom.ts

@@ -1,7 +1,8 @@
-// Small shared helper for features: build a chrome element from a static,
+// Small shared helpers for features: building a chrome element from a static,
 // trusted HTML string (icons, buttons) via a <template> clone, the same pattern
-// the kernel uses for its core subtree. No interpolation ever passes through
-// here, so it carries no injection surface.
+// the kernel uses for its core subtree, and the press wiring the bar buttons
+// share. No interpolation ever passes through here, so it carries no injection
+// surface.
 
 /** Parse a static HTML string and return its first element. */
 export function fromHTML(html: string): HTMLElement {
@@ -13,3 +14,62 @@ export function fromHTML(html: string): HTMLElement {
   }
   return el;
 }
+
+/** The press class the chrome buttons wired by holdFocusOnPress paint on
+ *  themselves. Every `:active` press rule for such a button pairs with it (see
+ *  the CSS contract test), because those buttons never enter `:active` in
+ *  Firefox. */
+export const PRESSED_CLASS = "wt-pressed";
+
+/** holdFocusOnPress wires a chrome button that must NOT take the keyboard off
+ *  the terminal, and paints its own press state because of it.
+ *
+ *  Focus: the hidden terminal textarea stays focused. A bar button needs no
+ *  focus of its own, and letting the press shift focus makes iOS/iPadOS consume
+ *  the FIRST tap to blur the input (so "+" only fired on the second tap — the
+ *  reported double-tap), while on a desktop it parks the keyboard on the button,
+ *  where the strip's own keydown handling eats arrows as "switch tab" and Delete
+ *  as "close tab". Cancelling pointerdown's default prevents both.
+ *
+ *  Press feedback: cancelling that default is also what suppresses the browser's
+ *  OWN activation state — Firefox ties `:active` to the mousedown default action,
+ *  and preventDefault on pointerdown suppresses the compatibility mousedown
+ *  entirely (measured on Firefox 140: no mousedown event, `matches(":active")`
+ *  false, background unchanged for as long as the button is held; Chromium and
+ *  WebKit still apply it). So these buttons — and ONLY these — carry the press
+ *  class, and their CSS press rules match either. That is why the two jobs live
+ *  in one helper: a caller that cancels the default without painting the class
+ *  ships a control with no press feedback in one engine, which is exactly the
+ *  defect this replaced.
+ *
+ *  The class is dropped on release, on cancel, and when the pointer leaves while
+ *  held (a press dragged off the button is not an activation), mirroring what
+ *  `:active` does on its own. A non-primary button press paints nothing, also
+ *  matching it. The release listeners live on `window` for the life of the press
+ *  (an `AbortController`, the pattern the switcher gesture uses) rather than on
+ *  the button: `.wt-scroll-bottom` acts on the press and hides itself, so by the
+ *  time the release lands the button is `display: none` and receives no
+ *  `pointerup` at all — bound to the button, the class would stay painted and the
+ *  control would come back already lit. */
+export function holdFocusOnPress(btn: HTMLElement): void {
+  let release: (() => void) | null = null;
+  btn.addEventListener("pointerdown", (e) => {
+    e.preventDefault();
+    if (e.button !== 0 || release !== null) {
+      return;
+    }
+    btn.classList.add(PRESSED_CLASS);
+    const held = new AbortController();
+    release = () => {
+      held.abort();
+      release = null;
+      btn.classList.remove(PRESSED_CLASS);
+    };
+    const end = (): void => {
+      release?.();
+    };
+    window.addEventListener("pointerup", end, { signal: held.signal });
+    window.addEventListener("pointercancel", end, { signal: held.signal });
+    btn.addEventListener("pointerleave", end, { signal: held.signal });
+  });
+}

package/src/features/scroll-to-bottom.ts

@@ -5,7 +5,7 @@
 // scroll.scrollToBottom.
 
 import type { TerminalFeature } from "../kernel/types.js";
-import { fromHTML } from "./dom.js";
+import { fromHTML, holdFocusOnPress } from "./dom.js";
 
 const BUTTON_HTML = `
 <button type="button" class="wt-btn wt-scroll-bottom" aria-label="Scroll to bottom">
@@ -39,14 +39,13 @@ export function scrollToBottom(): TerminalFeature {
         surface.scrollTo({ top: surface.scrollHeight, behavior: "smooth" });
       };
 
-      // pointerdown (like the toolbar keys) so touch devices show press
-      // feedback; preventDefault keeps focus on the terminal. click is kept for
-      // keyboard activation. jump is idempotent, so the pair is safe.
-      const onDown = (e: PointerEvent): void => {
-        e.preventDefault();
-        jump();
-      };
-      btn.addEventListener("pointerdown", onDown);
+      // pointerdown (like the toolbar keys) so touch devices get the jump on the
+      // press rather than the release; click is kept for keyboard activation.
+      // jump is idempotent, so the pair is safe. holdFocusOnPress keeps the
+      // keyboard on the terminal across the press and paints the press class the
+      // cancelled default costs this button.
+      holdFocusOnPress(btn);
+      btn.addEventListener("pointerdown", jump);
       btn.addEventListener("click", jump);
 
       // Visible only while scrolled up; the region reflects it via a class.

package/src/features/tabs/index.ts

@@ -12,7 +12,7 @@ import { LineStore, modes } from "@cplieger/web-terminal-engine";
 import type { SessionRef, TerminalContext, TerminalFeature } from "../../kernel/types.js";
 import type { ActivityMonitorApi } from "../activity-monitor.js";
 import type { MobileToolbarApi } from "../mobile-toolbar.js";
-import { fromHTML } from "../dom.js";
+import { fromHTML, holdFocusOnPress } from "../dom.js";
 import { createClickSwallow, placeMenuAt } from "../menu-position.js";
 import type { CueStatus, SessionInfo, StatusRecord, Tab } from "./model.js";
 import {
@@ -34,7 +34,6 @@ import {
   orderedInsertIndex,
   parseCueSeen,
   parseTabOrder,
-  progressLabel,
   renderedProgress,
   sanitizePinnedName,
   serializeCueSeen,
@@ -337,16 +336,11 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
       // and reflects its open state on every keyboard button.
       function makeNewButton(cls: string): HTMLElement {
         const btn = fromHTML(newButtonHTML(cls));
-        // Keep the hidden terminal textarea focused: a bar button needs no focus
-        // of its own, and letting the tap shift focus makes iOS/iPadOS consume
-        // the FIRST tap to blur the input (so "+" only fired create on the second
-        // tap — the reported double-tap). preventDefault on pointerdown fires the
-        // action on the first tap; switchTo then re-focuses the input for the new
-        // tab (see focusAfterSwitch). It does NOT make one press one activation —
-        // that is create()'s in-flight coalescing, for the opposite failure.
-        btn.addEventListener("pointerdown", (e) => {
-          e.preventDefault();
-        });
+        // Keeps the keyboard on the terminal and paints its own press state;
+        // holdFocusOnPress explains why those two are one job. It does NOT make
+        // one press one activation — that is create()'s in-flight coalescing,
+        // for the opposite failure.
+        holdFocusOnPress(btn);
         btn.addEventListener("click", () => {
           void create();
         });
@@ -354,11 +348,7 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
       }
       function makeKbButton(cls: string): HTMLElement {
         const btn = fromHTML(kbButtonHTML(cls));
-        // First-tap focus retention (see makeNewButton): keep the terminal
-        // textarea focused so the toggle fires on the first tap on iOS/iPadOS.
-        btn.addEventListener("pointerdown", (e) => {
-          e.preventDefault();
-        });
+        holdFocusOnPress(btn);
         btn.addEventListener("click", () => {
           const kb = opts.keyboardToggle ? ctx.use(opts.keyboardToggle) : undefined;
           if (!kb) {
@@ -376,15 +366,11 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
       }
       // makeSwitchButton builds the mobile switcher's dedicated open/close
       // button (its notification dot is painted by paintSwitchDot). Like the
-      // other bar buttons it preventDefaults pointerdown for first-tap focus
-      // retention (keeps the terminal textarea focused so it fires on the first
-      // tap on iOS/iPadOS); its click toggles the list (toggleSwitcher opens when
-      // collapsed, closes when expanded).
+      // other bar buttons it goes through holdFocusOnPress; its click toggles the
+      // list (toggleSwitcher opens when collapsed, closes when expanded).
       function makeSwitchButton(): HTMLElement {
         const btn = fromHTML(switchButtonHTML("wt-switcher-switch wt-btn"));
-        btn.addEventListener("pointerdown", (e) => {
-          e.preventDefault();
-        });
+        holdFocusOnPress(btn);
         btn.addEventListener("click", () => {
           toggleSwitcher();
         });
@@ -760,12 +746,13 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
             }
           }
           t.display = display;
-          const rendered = progressLabel(display, shownProgress(t));
-          t.label.textContent = rendered;
-          // The accessible name carries the state as well as the label: the dots
-          // are aria-hidden decoration, so without this a screen-reader user
-          // cannot tell a working tab from a crashed one.
-          t.aria.setLabel(tabAccessibleName(rendered, statusOf(t)));
+          t.label.textContent = display;
+          // The accessible name carries the state and the percentage as well as
+          // the label: the dots are aria-hidden decoration and the progress bar
+          // is a 2px line with no text, so without this a screen-reader user
+          // cannot tell a working tab from a crashed one, or hear how far along
+          // a determinate one is.
+          t.aria.setLabel(tabAccessibleName(display, statusOf(t), shownProgress(t)));
         }
       }
 
@@ -777,10 +764,10 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
       }
 
       /** shownProgress is a tab's percentage as it may currently be DISPLAYED:
-       *  the last value the server reported, dropped once the process is gone.
-       *  Those are the only two ways a percentage stops showing — the program's
-       *  own OSC 9;4;0 (an explicit -1) and the process ending; see
-       *  renderedProgress for why there is no third. */
+       *  the last value the server reported, dropped unless the current status is
+       *  one the progress channel owns. Those are the only two ways a percentage
+       *  stops showing — the program's own OSC 9;4;0 (an explicit -1) and a status
+       *  from another channel; see renderedProgress for why there is no third. */
       function shownProgress(t: Tab): number {
         return renderedProgress(statusOf(t), t.progress);
       }
@@ -876,7 +863,7 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
       function syncMobile(): void {
         const idx = tabList.findIndex((t) => t.id === activeId);
         const active = idx >= 0 ? tabList[idx] : undefined;
-        swLabel.textContent = active ? progressLabel(active.display, shownProgress(active)) : "";
+        swLabel.textContent = active ? active.display : "";
         paintStatusDot(swDot, active ? statusOf(active) : "idle", active?.reports ?? false);
         paintProgress(swProgress, active ? shownProgress(active) : PROGRESS_ABSENT);
         // The aggregate background-notification cue rides the dedicated switch
@@ -904,10 +891,7 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
       function updateRow(row: HTMLElement, t: Tab): void {
         paintStatusDot(pick(row, ".wt-switcher-row-dot"), statusOf(t), t.reports);
         paintProgress(pick(row, ".wt-progress-bar"), shownProgress(t));
-        pick(row, ".wt-switcher-row-label").textContent = progressLabel(
-          t.display,
-          shownProgress(t),
-        );
+        pick(row, ".wt-switcher-row-label").textContent = t.display;
       }
       // renderSwitcherList reconciles the expanded list to a row per OTHER tab
       // (the active tab lives in the bar row), REUSING existing row elements
@@ -1309,8 +1293,10 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
         // Set an initial label immediately (relabelAll refines it with de-dup
         // once the tab is in tabList and syncChrome runs).
         tab.display = baseLabel(tab).text;
-        label.textContent = progressLabel(tab.display, renderedProgress(info.status, tab.progress));
-        aria.setLabel(tabAccessibleName(label.textContent, info.status));
+        label.textContent = tab.display;
+        aria.setLabel(
+          tabAccessibleName(tab.display, info.status, renderedProgress(info.status, tab.progress)),
+        );
         el.addEventListener("click", (e) => {
           if ((e.target as HTMLElement).closest(".wt-tab-close")) {
             return; // handled by the close button
@@ -2575,6 +2561,15 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
           notifier.deliver(s, {
             sessionIsActive: s.id === activeId,
             label: tabList.find((t) => t.id === s.id)?.display ?? s.title,
+            // What clicking the notification does. The platform's own click
+            // default focuses the page; this supplies the other half, landing the
+            // user on the session that raised the notification rather than on
+            // whichever tab they last left active. switchTo already no-ops on an
+            // id that is gone, which is the case that matters here: the prompt may
+            // have been answered, or the tab closed, between post and click.
+            activate: () => {
+              switchTo(s.id);
+            },
           });
         });
         offStreamOpen = monitor.onStreamOpen?.(() => {

package/src/features/tabs/model.ts

@@ -117,53 +117,71 @@ export function normalizeProgress(value: unknown): number {
   return Math.min(100, Math.round(value));
 }
 
+/** statusOwnsProgress reports whether a status is one the program's OSC 9;4
+ *  progress channel is currently speaking through. Only these may show a bar.
+ *
+ *  The tab keeps the last percentage the server reported, and the server keeps
+ *  sending it (correctly — a progress state persists until the program changes
+ *  it), so this predicate is what stops that value from being painted underneath a
+ *  status that came from somewhere else entirely. `input` and `done` come from the
+ *  NOTIFICATION channel; `idle` is the absence of a progress state; `exited` and
+ *  `crashed` are process facts. A percentage under any of those is a claim about
+ *  a different channel than the one the reader is looking at. */
+export function statusOwnsProgress(status: string): boolean {
+  return status === "working" || status === STATUS_FAILED || status === STATUS_WARNING;
+}
+
 /** renderedProgress is the percentage a status may actually SHOW. The tab keeps
  *  the last value the server reported; this is the one place that decides whether
  *  it is still meaningful, so the clearing rule has a single home.
  *
- *  There are exactly TWO clears, and both are honest — neither invents a state
- *  change the program never made:
+ *  Two things clear it, and both are honest — neither invents a state change the
+ *  program never made:
  *
  *   1. The program's own clear: OSC 9;4;0, or the abbreviated OSC 9;4, which the
  *      engine reports as percentage -1. That is the spec path, and the value
  *      arriving as PROGRESS_ABSENT is all it takes.
- *   2. The process is GONE (exited or crashed) — checked here. A dead process's
- *      progress is meaningless, and nothing will ever clear it, so the bar and
- *      the title prefix drop with the process.
+ *   2. The status is not one the progress channel owns (statusOwnsProgress) —
+ *      checked here. That covers a dead process, whose progress is meaningless
+ *      and which nothing will ever clear, and equally a `done` or `input` latch,
+ *      which is the notification channel talking. Measured: kiro-cli parks
+ *      progress state 4 at its context-usage percentage when idle, so a finished
+ *      turn used to paint a green done dot beside a 72% bar — a number about the
+ *      context window, rendered as how far along the work was.
  *
  *  There is deliberately NO third clear. 100% is not special: state 1 at 100 is a
- *  STATE that persists, and the progress channel carries no "done" signal at all
- *  (our `done` comes from the notification channel, a separate mechanism), so a
- *  program that pins 100 and goes quiet keeps its bar — the same "persists until
- *  the program says otherwise" property the indeterminate state already has.
+ *  STATE that persists, and the progress channel carries no "done" signal at all,
+ *  so a program that pins 100 and goes quiet keeps its bar — the same "persists
+ *  until the program says otherwise" property the indeterminate state already has.
  *  There is also no TIMEOUT: a timer would assert a change the program never
- *  reported. And a `done`/`input` latch does not clear it either, because a latch
- *  says something about the notification channel, not about the progress the
- *  program last reported. (In practice this is not a stale-bar risk for the one
- *  agent that drives it: kiro-cli never sends state 1, and sends state 0 when it
- *  goes idle.) */
+ *  reported (Ghostty's ~15s one does, which is why it also asks emitters to
+ *  refresh once a second; nothing here requires a keep-alive). */
 export function renderedProgress(status: string, progress: number): number {
-  return isEndedStatus(status) ? PROGRESS_ABSENT : progress;
-}
-
-/** progressLabel prefixes a rendered label with its percentage ("78% · one").
- *
- *  Applied at RENDER time and never stored: `Tab.title`, `Tab.pinnedTitle` and
- *  `Tab.display` stay the plain name, so a manual rename round-trips unprefixed,
- *  an automatic title is untouched, de-duplication still compares real labels,
- *  and clearing the progress needs no cleanup — the next paint simply stops
- *  adding the prefix. */
-export function progressLabel(display: string, progress: number): string {
-  return progress < 0 ? display : `${String(progress)}% · ${display}`;
+  return statusOwnsProgress(status) ? progress : PROGRESS_ABSENT;
 }
 
 /** tabAccessibleName is a tab's announced name: its rendered label plus the
- *  session's state. The dots are aria-hidden="true" (they are decoration with no
- *  text), so before this the status was invisible to a screen reader — a fact a
- *  red crashed state makes worse. This deliberately changes the announced text
- *  for the existing states too. */
-export function tabAccessibleName(renderedLabel: string, status: string): string {
-  return `${renderedLabel} — ${statusPhrase(status)}`;
+ *  session's state, and the percentage when one is showing.
+ *
+ *  The percentage is announced but never DRAWN as text. No terminal emulator puts
+ *  a number next to a tab label — Windows Terminal draws a ring over the tab icon,
+ *  Ghostty and kitty a bar on a window edge, ConEmu a percentage in the WINDOW
+ *  title — and the visible number cost label width in a chip that already shrinks
+ *  to a 100px floor. The bar answers "how far" for the eye; this answers it for a
+ *  screen reader, which cannot see the bar at all (it is decoration with no text).
+ *
+ *  Pass PROGRESS_ABSENT for progress to announce the state alone. Callers hand in
+ *  renderedProgress's output, so a percentage the tab is not showing is not
+ *  announced either. */
+export function tabAccessibleName(
+  renderedLabel: string,
+  status: string,
+  progress: number = PROGRESS_ABSENT,
+): string {
+  const state = statusPhrase(status);
+  return progress < 0
+    ? `${renderedLabel} — ${state}`
+    : `${renderedLabel} — ${state}, ${String(progress)}%`;
 }
 
 // localStorage key for the last active session id, so a page reload reopens the

package/src/features/tabs/notify.ts

@@ -2,7 +2,19 @@
 // BROWSER notifications. The spec names the display mode ("post a
 // notification"), which is why this one signal is not tab-only chrome: a
 // finished turn or a permission prompt has to be able to reach a user who is
-// looking at another app.
+// looking at another app. Clicking one takes the user to the session that raised
+// it (see deliver).
+//
+// NON-PERSISTENT notifications (the `new Notification()` constructor), which is
+// the standard surface available to a page with no service worker. Their lifetime
+// is tied to the page's, which suits this app exactly: the notification is about
+// a live PTY the page is attached to, and there is nothing useful to click once
+// the page is gone. Per the Notifications API the constructor throws on most
+// mobile browsers, where persistent (service-worker) notifications are the only
+// route; that throw is caught below and degrades to tab-only chrome. Registering
+// a service worker for an app that is otherwise entirely live is a cost this does
+// not pay — mobile support for the standard constructor is the platforms' side of
+// the contract.
 //
 // A notification is an EVENT, not a state (that is the structural difference
 // from OSC 9;4 progress, which is a state and drives the status dot): the engine
@@ -15,13 +27,20 @@
 // browserNotifierEnv() below. The notification text NEVER enters the DOM — see
 // the note on deliver().
 
-/** The slice of `window.Notification` used here. Constructed and dropped: the
- *  browser owns the notification's life, and we keep no handle (nothing in this
- *  UI closes or replaces one programmatically). */
+/** The slice of a non-persistent `Notification` instance this feature uses: the
+ *  `click` handler and `close()`. The instance is no longer discarded — attaching
+ *  a click handler is what lets a notification finish its job (see deliver).
+ *  Module-private: it is the ctor type's return shape, not a consumer surface. */
+interface NotificationLike {
+  onclick: ((event: Event) => void) | null;
+  close: () => void;
+}
+
+/** The slice of `window.Notification` used here. */
 export type NotificationCtorLike = new (
   title: string,
   options?: { body?: string; tag?: string },
-) => unknown;
+) => NotificationLike;
 
 /** The capabilities a notifier needs, all injected. `permission` and `request`
  *  are read as plain strings rather than the DOM's NotificationPermission union:
@@ -71,8 +90,15 @@ export interface Notifier {
   /** Deliver one status event's notification, if it carries a new one. Returns
    *  true when a browser notification was actually posted (false covers every
    *  degraded path: no notification in the event, a repeat, suppression, no API,
-   *  no permission, a throwing constructor). */
-  deliver(ev: NotificationEvent, view: { sessionIsActive: boolean; label: string }): boolean;
+   *  no permission, a throwing constructor).
+   *
+   *  `view.activate` is what the notification's click performs in the page. The
+   *  caller supplies it, so this module still knows nothing about sessions, tabs
+   *  or the DOM. */
+  deliver(
+    ev: NotificationEvent,
+    view: { sessionIsActive: boolean; label: string; activate: () => void },
+  ): boolean;
   /** Note that this page has a session capable of notifying, which is what makes
    *  a permission prompt worth raising at all. */
   arm(): void;
@@ -135,7 +161,30 @@ export function createNotifier(env: NotifierEnv): Notifier {
         // label. The engine already strips control/bidi runes and clamps the
         // length; that is not widened here. If this ever needs an in-page
         // surface, it must use textContent.
-        new Ctor(view.label, { body: text, tag: ev.id });
+        const posted = new Ctor(view.label, { body: text, tag: ev.id });
+        // A notification the user clicks should land them on the terminal that
+        // raised it. Half of that is the click event's OWN default behaviour —
+        // per the Notifications API, activating a non-persistent notification
+        // moves focus to the viewport of its browsing context — so this handler
+        // deliberately does NOT preventDefault() and does NOT call
+        // window.focus(): the platform already brings the page forward, and the
+        // only missing half is switching to the right session inside it. That
+        // asymmetry is the whole bug this fixes: the page came forward and then
+        // showed whichever tab the user happened to leave active.
+        //
+        // NOT the `navigate` option, which is the declarative alternative and
+        // bypasses the click event entirely: it NAVIGATES, which for a live
+        // terminal means dropping every WebSocket and replaying scrollback to
+        // arrive somewhere the page already was. A same-page switch is both
+        // cheaper and correct. Do not "modernise" this into `navigate`.
+        posted.onclick = (): void => {
+          view.activate();
+          // The user has just acted on it, so it is no longer relevant — the
+          // documented reason to close one. (Closing is only wrong when used as
+          // a display timer, which also strips it from the notification tray
+          // before the user can interact.)
+          posted.close();
+        };
         return true;
       } catch {
         // Safari throws on `new Notification` outside an installed PWA even when