@cplieger/web-terminal-ui 5.1.0 → 5.2.0

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/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
@@ -632,7 +642,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 +658,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-ui",
-  "version": "5.1.0",
+  "version": "5.2.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": "GPL-3.0-or-later",
@@ -56,7 +56,7 @@
     "eslint": "10.8.0",
     "fast-check": "4.9.0",
     "happy-dom": "20.11.1",
-    "html-validate": "11.5.6",
+    "html-validate": "11.6.0",
     "knip": "6.29.0",
     "prettier": "3.9.6",
     "stylelint": "17.14.1",

package/src/features/tabs/index.ts

@@ -34,7 +34,6 @@ import {
   orderedInsertIndex,
   parseCueSeen,
   parseTabOrder,
-  progressLabel,
   renderedProgress,
   sanitizePinnedName,
   serializeCueSeen,
@@ -760,12 +759,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 +777,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 +876,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 +904,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 +1306,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 +2574,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