@cplieger/web-terminal-ui 5.0.3 → 5.2.0

package/src/features/tabs/model.ts

@@ -14,11 +14,175 @@ import type { TabHandle } from "../../kernel/types.js";
 // contract has one home. Type-only import: erases at compile, no runtime dep.
 export type { SessionInfo };
 
+/** A status record as the tabs feature consumes it: the session's REST wire
+ *  shape plus the percentage that exists only on the status STREAM
+ *  (SessionStatus.progressValue). Both status sources flow through one code path
+ *  this way, and the optionality is meaningful: the polling fallback lists
+ *  SessionInfo with no percentage at all, which means "no information" and must
+ *  not be read as "the percentage was cleared". */
+export type StatusRecord = SessionInfo & { readonly progressValue?: number };
+
+// The status vocabulary, module-private on purpose: every consumer asks one of
+// the predicates below (isEndedStatus / statusRevealsDot / isCueStatus /
+// statusPhrase) instead of comparing strings itself, so a status's
+// MEANING has exactly one home. Adding a status means adding it to the
+// predicates that should include it, not to a comparison at each call site.
+//
 // The server-side status of a session whose process has exited (mirrors the
 // engine's terminal.StatusExited). Such a session is viewable history — its
 // final screen replays and the kernel shows "Session ended" — but it can never
 // produce output again, so session selection prefers live sessions everywhere.
-export const STATUS_EXITED = "exited";
+const STATUS_EXITED = "exited";
+
+/** The other end-of-process status (engine terminal.StatusCrashed): a non-zero
+ *  exit status, or a terminating signal the program was not asked for. A
+ *  server-initiated end (a closed tab, the idle reaper, a server shutdown) is
+ *  reported as "exited", so a routine restart never paints as a failure. Like
+ *  "exited" it is terminal: nothing clears it, and it outranks every progress
+ *  state. */
+const STATUS_CRASHED = "crashed";
+
+/** OSC 9;4 progress state 2, the error state (iTerm2 semantics). A STATE, not an
+ *  event: it persists until the program reports another progress state, or the
+ *  process dies (which outranks it). */
+const STATUS_FAILED = "failed";
+
+/** OSC 9;4 progress state 4, the warning state (iTerm2 semantics; ConEmu calls
+ *  the same state paused). Same persistence rules as STATUS_FAILED. */
+const STATUS_WARNING = "warning";
+
+/** isEndedStatus reports whether a status means the session's process is GONE,
+ *  whichever way it went. Session selection asks this — not `=== "exited"` —
+ *  because a crashed session is exactly as dead as an exited one: reloading onto
+ *  either is the stuck-loading wedge the bootstrap's live-session preference
+ *  exists to avoid. */
+export function isEndedStatus(status: string): boolean {
+  return status === STATUS_EXITED || status === STATUS_CRASHED;
+}
+
+/** The statuses whose dot must be visible even if the server never set the
+ *  session's sticky reportsActivity flag. `warning` and `failed` are OSC 9;4
+ *  states, so the flag is set for them in practice and this only floors it;
+ *  `crashed` is the case that needs it — a plain shell that dies badly has
+ *  reported no activity in its life, and its red dot is the one thing the user
+ *  most needs to see. An ordinary `exited` deliberately stays gated: a clean end
+ *  is not news. */
+export function statusRevealsDot(status: string): boolean {
+  return status === STATUS_WARNING || status === STATUS_FAILED || status === STATUS_CRASHED;
+}
+
+/** statusPhrase is the human wording for a status, used for BOTH the dot's hover
+ *  tooltip and the suffix in a tab's accessible name — one definition, so what a
+ *  sighted user reads on hover and what a screen reader announces cannot
+ *  disagree. An unknown status (a newer server: the wire is parsed, not
+ *  validated) falls back to the raw value rather than being hidden. */
+export function statusPhrase(status: string): string {
+  switch (status) {
+    case "working":
+      return "working";
+    case STATUS_WARNING:
+      return "warning reported";
+    case STATUS_FAILED:
+      return "error reported";
+    case "input":
+      return "waiting for you";
+    case "done":
+      return "turn finished";
+    case STATUS_EXITED:
+      return "session ended";
+    case STATUS_CRASHED:
+      return "process crashed";
+    case "idle":
+    case "":
+      return "idle";
+    default:
+      return status;
+  }
+}
+
+/** PROGRESS_ABSENT is "no percentage" (the engine's own marker). Absence is -1,
+ *  never 0: a session that reported nothing is not a session at 0%, and the two
+ *  must render differently (no bar at all vs an empty bar). */
+export const PROGRESS_ABSENT = -1;
+
+/** normalizeProgress cleans a percentage off the wire into PROGRESS_ABSENT or
+ *  0-100. The engine already clamps, so this is the untrusted-JSON guard: a
+ *  string, a NaN, an Infinity or a negative all mean "absent" rather than
+ *  throwing or rendering a nonsense bar, and an out-of-range high value clamps
+ *  rather than overflowing the chip. */
+export function normalizeProgress(value: unknown): number {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+    return PROGRESS_ABSENT;
+  }
+  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.
+ *
+ *  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 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,
+ *  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 (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 statusOwnsProgress(status) ? progress : PROGRESS_ABSENT;
+}
+
+/** tabAccessibleName is a tab's announced name: its rendered label plus the
+ *  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
 // tab the user left on rather than always defaulting to the oldest one.
@@ -87,15 +251,20 @@ export function serializeTabOrder(ids: readonly string[]): string {
   return JSON.stringify(ids.slice(0, MAX_PERSISTED_TAB_ORDER));
 }
 
-/** The two session statuses that raise the mobile switcher's aggregate attention
- *  cue: a background terminal blocked on the user ("input") or one whose turn
- *  finished ("done"). Declared once here so the raise test and the
- *  acknowledgement store cannot disagree about which statuses are cue-worthy. */
-export type CueStatus = "input" | "done";
+/** 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";
 
 /** isCueStatus narrows a raw server status to a cue-worthy one. */
 export function isCueStatus(status: string): status is CueStatus {
-  return status === "input" || status === "done";
+  return status === "input" || status === "done" || status === STATUS_CRASHED;
 }
 
 /** localStorage key for the cues this viewer has already SEEN: session id -> the
@@ -221,6 +390,14 @@ export interface Tab {
   el: HTMLElement;
   label: HTMLElement;
   dot: HTMLElement;
+  /** The chip's determinate progress bar (the 2px line on its bottom edge).
+   *  Present on every chip, hidden until a percentage exists. */
+  progressEl: HTMLElement;
+  /** The last OSC 9;4 percentage the server reported for this session, or
+   *  PROGRESS_ABSENT. Held raw: whether it is currently SHOWN is a render-time
+   *  question (renderedProgress), and the prefix it produces is never stored on
+   *  any title field. */
+  progress: number;
   aria: TabHandle;
   scrollTop: number;
   following: boolean;

package/src/features/tabs/notify.ts

@@ -0,0 +1,265 @@
+// tabs/notify.ts — OSC 9 Form B notifications (`OSC 9 ; <message> ST`) as
+// 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. 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
+// latches nothing for it and never replays it, so it is delivered once, on the
+// sweep that first observes it.
+//
+// DOM-free and global-free by construction: every capability comes in through
+// NotifierEnv, so the decisions here are unit-testable without a browser
+// permission model, and the one place that touches globals is
+// browserNotifierEnv() below. The notification text NEVER enters the DOM — see
+// the note on deliver().
+
+/** 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 },
+) => NotificationLike;
+
+/** The capabilities a notifier needs, all injected. `permission` and `request`
+ *  are read as plain strings rather than the DOM's NotificationPermission union:
+ *  they come from a browser that may report something newer, and a value we do
+ *  not recognise must degrade rather than be asserted. */
+export interface NotifierEnv {
+  /** The Notification constructor, or undefined where the API does not exist
+   *  (iOS Safari outside an installed PWA, a non-secure context, happy-dom). */
+  ctor: NotificationCtorLike | undefined;
+  /** Current permission: "default" | "granted" | "denied" (or anything else). */
+  permission: () => string;
+  /** Ask for permission. Must be called from a user gesture. */
+  request: () => void;
+  /** Is the page currently visible to the user? */
+  pageVisible: () => boolean;
+}
+
+/** One status event's notification payload (the fields SessionStatus carries for
+ *  it). Both are optional: an older server, or any event that carries no
+ *  notification, simply omits them. */
+interface NotificationEvent {
+  readonly id: string;
+  readonly notification?: string | undefined;
+  readonly notificationSeq?: number | undefined;
+}
+
+/** shouldNotify is the suppression rule, alone and testable.
+ *
+ *  Skip a notification ONLY when the user is already looking at the terminal that
+ *  produced it: its tab is the active one AND the page is visible. Both halves
+ *  are required, and the second is the one that matters most — when the page is
+ *  HIDDEN (another browser tab, a locked phone, a minimised window) the
+ *  notification fires even for the active session, because that is exactly the
+ *  situation where the user cannot see the terminal at all. A rule that keyed
+ *  only on "is this the active tab" would silently swallow the notification of
+ *  the very session the user left running. */
+export function shouldNotify(sessionIsActive: boolean, pageVisible: boolean): boolean {
+  return !(sessionIsActive && pageVisible);
+}
+
+/** Bound on the per-session dedupe map, same reasoning as the model's other
+ *  bounded stores: each key is a live session server-side, so a real one is
+ *  nowhere near this, and a hostile or buggy stream cannot grow it without end. */
+const MAX_TRACKED_SESSIONS = 200;
+
+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).
+   *
+   *  `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;
+  /** Note a user gesture: the ONLY moment a permission prompt may be raised. */
+  gesture(): void;
+  /** Drop a closed session's dedupe state. */
+  forget(id: string): void;
+}
+
+export function createNotifier(env: NotifierEnv): Notifier {
+  // Highest notification sequence delivered per session. The engine never
+  // replays a notification, so this is a belt-and-braces guard rather than the
+  // mechanism that makes re-delivery safe: it costs one map and it means a
+  // duplicated frame (a doubled subscriber, a consumer re-emitting a snapshot)
+  // cannot notify twice for one event.
+  const lastSeq = new Map<string, number>();
+  let armed = false;
+  let requested = false;
+
+  function evict(): void {
+    while (lastSeq.size > MAX_TRACKED_SESSIONS) {
+      const oldest = lastSeq.keys().next().value;
+      if (oldest === undefined) {
+        return;
+      }
+      lastSeq.delete(oldest);
+    }
+  }
+
+  return {
+    deliver(ev, view): boolean {
+      const text = ev.notification ?? "";
+      if (text === "") {
+        return false;
+      }
+      const seq = ev.notificationSeq ?? 0;
+      if (seq !== 0) {
+        if (seq <= (lastSeq.get(ev.id) ?? 0)) {
+          return false; // already delivered this event
+        }
+        lastSeq.set(ev.id, seq);
+        evict();
+      }
+      if (!shouldNotify(view.sessionIsActive, env.pageVisible())) {
+        return false;
+      }
+      const Ctor = env.ctor;
+      if (!Ctor || env.permission() !== "granted") {
+        // Degrade silently to tab-only: the session's dot and the switcher's
+        // aggregate cue already carry that something happened. No throw, no
+        // console noise — an unpermitted notification is a normal state of the
+        // world, not an error.
+        return false;
+      }
+      try {
+        // The message is UNTRUSTED program output. It is passed as DATA to the
+        // Notification API (a string option, rendered by the browser's own
+        // notification surface) and is never written into the DOM — not as
+        // innerHTML, not as a template string that becomes markup, not into a
+        // 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.
+        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
+        // the constructor exists. Tab-only, silently.
+        return false;
+      }
+    },
+    arm(): void {
+      armed = true;
+    },
+    gesture(): void {
+      // Permission is requested from a USER GESTURE, never at load: Safari
+      // rejects (and Chrome penalises) a prompt with no gesture behind it, and a
+      // prompt on page load is the pattern browsers added those rules for.
+      //
+      // Gated on `armed` as well, so only a page that actually has a
+      // notification-capable session ever prompts: a plain shell emits no OSC 9,
+      // and asking its user for notification permission is a prompt they can
+      // only answer wrongly. The cost of that gate is that the FIRST
+      // notification of a session cannot be shown (the prompt has not been
+      // answered yet) — unavoidable in any case, since permission cannot be
+      // obtained without a gesture, and a first signal rarely coincides with one.
+      if (!armed || requested) {
+        return;
+      }
+      const Ctor = env.ctor;
+      if (!Ctor || env.permission() !== "default") {
+        return; // absent API, or already granted/denied: nothing to ask
+      }
+      requested = true; // once per page, whatever the answer
+      try {
+        env.request();
+      } catch {
+        /* a browser that refuses to be asked is a tab-only browser */
+      }
+    },
+    forget(id): void {
+      lastSeq.delete(id);
+    },
+  };
+}
+
+/** browserNotifierEnv binds a notifier to the real browser APIs. The single
+ *  place in this feature that touches globals, and it reads them through
+ *  `unknown` on purpose: `Notification` is absent (not merely denied) on iOS
+ *  Safari and in test DOMs, so nothing here may assume the declared global
+ *  exists. Both `requestPermission` shapes are tolerated — modern browsers
+ *  return a promise, older Safari takes a callback and returns undefined — since
+ *  the result is not awaited: the answer is read from `permission()` at the next
+ *  notification. */
+export function browserNotifierEnv(): NotifierEnv {
+  const api = (): { permission?: unknown; requestPermission?: unknown } | undefined => {
+    const value: unknown = (globalThis as { Notification?: unknown }).Notification;
+    return typeof value === "function"
+      ? (value as unknown as { permission?: unknown; requestPermission?: unknown })
+      : undefined;
+  };
+  return {
+    get ctor(): NotificationCtorLike | undefined {
+      const value: unknown = (globalThis as { Notification?: unknown }).Notification;
+      return typeof value === "function" ? (value as NotificationCtorLike) : undefined;
+    },
+    permission: (): string => {
+      const value = api()?.permission;
+      return typeof value === "string" ? value : "denied";
+    },
+    request: (): void => {
+      const fn = api()?.requestPermission;
+      if (typeof fn === "function") {
+        (fn as () => unknown).call(api());
+      }
+    },
+    // document.visibilityState is the only reliable "can the user see this page"
+    // signal; document.hasFocus() is false for a visible-but-unfocused window,
+    // where the terminal IS on screen and a notification would be redundant.
+    pageVisible: (): boolean => document.visibilityState !== "hidden",
+  };
+}

package/src/features/tabs/strip.ts

@@ -6,6 +6,11 @@
 // (it closes over the feature state). The mobile chrome templates live in
 // switcher.ts; the session model in model.ts.
 
+// The status vocabulary itself (which statuses reveal a dot, and how each one is
+// worded for a human) lives in the DOM-free model, so the painters here and the
+// accessible names index.ts builds read one definition.
+import { statusPhrase, statusRevealsDot } from "./model.js";
+
 // The +/x/keyboard glyphs are inline SVG (not font glyphs) so they center
 // exactly in their flex-centered buttons and stay symmetric regardless of the UI
 // font's metrics. Each is defined ONCE here and shared by every chip site and
@@ -21,15 +26,22 @@ const KB_SVG = `<svg viewBox="0 0 24 24" aria-hidden="true"><rect x="4" y="4" wi
 const SWITCH_SVG = `<svg viewBox="0 0 24 24" aria-hidden="true"><rect x="3" y="8" width="13" height="13" rx="2"/><path d="M8 8V6a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v9a2 2 0 0 1-2 2h-3"/></svg>`;
 
 // chipContent is the ONE builder for a tab chip's content — a status dot, a
-// label, and a close (x) — shared by all three chip sites: the desktop strip
-// (.wt-tab), the mobile active row (.wt-switcher-current), and each expanded
-// mobile list row (.wt-switcher-row). Each site passes its OWN class set (never
-// renamed) so every existing selector — and thus all CSS and all tests — still
-// matches. The one structural difference is WHERE the close sits: the desktop
+// label, a determinate progress bar, and a close (x) — shared by all three chip
+// sites: the desktop strip (.wt-tab), the mobile active row
+// (.wt-switcher-current), and each expanded mobile list row (.wt-switcher-row).
+// Each site passes its OWN class set (never renamed) so every existing selector
+// — and thus all CSS and all tests — still matches. The one structural
+// difference is WHERE the close sits: the desktop
 // chip nests it flat inside .wt-tab, while the two mobile chips place it as a
 // sibling of the select/swipe button (a button can't nest in a button). So the
 // builder returns two fragments — the dot+label pair and the close — that each
 // site drops into its own structure.
+//
+// The progress bar rides in the dotLabel fragment rather than taking a per-site
+// class: it is positioned against the chip, not laid out in its flex row, so one
+// class (.wt-progress-bar) styles it everywhere and every chip site gets it for
+// free. It starts `hidden` — a session with no percentage must render NO bar
+// (paintProgress).
 export function chipContent(v: { dot: string; label: string; close: string; closeAttr?: string }): {
   dotLabel: string;
   close: string;
@@ -37,7 +49,8 @@ export function chipContent(v: { dot: string; label: string; close: string; clos
   return {
     dotLabel:
       `<span class="${v.dot} wt-status-dot" aria-hidden="true"></span>` +
-      `<span class="${v.label}"></span>`,
+      `<span class="${v.label}"></span>` +
+      `<span class="wt-progress-bar" aria-hidden="true" hidden></span>`,
     close: `<button type="button" class="${v.close}" aria-label="Close terminal"${v.closeAttr ?? ""}>${CLOSE_SVG}</button>`,
   };
 }
@@ -80,15 +93,44 @@ export const TAB_HTML = `
   ${TAB_CHIP.close}
 </div>`;
 
-/** paintStatusDot applies a status dot's two orthogonal bits: data-status drives
- *  its appearance (idle / working / done / input / exited via CSS), and the
- *  .wt-reports class controls its visibility — the dot is hidden by default and
- *  shown only once the session has reported activity (OSC 9;4 progress or a
- *  classified OSC 9 notification), so a plain shell's tabs stay clean and
- *  label-only while an agent's light up. */
+/** paintStatusDot applies a status dot's three orthogonal bits: data-status
+ *  drives its appearance (idle / working / warning / failed / done / input /
+ *  exited / crashed via CSS), the .wt-reports class controls its visibility, and
+ *  `title` gives it a hover tooltip naming the state — the dots are decoration
+ *  (aria-hidden), and a colour vocabulary that grew to eight states needs a way
+ *  to be read rather than memorised. The tooltip wording is statusPhrase, the
+ *  same source the tab's accessible name uses, so hover text and announced text
+ *  cannot drift.
+ *
+ *  Visibility: the dot is hidden by default and shown once the session has
+ *  reported activity (OSC 9;4 progress or a classified OSC 9 notification), so a
+ *  plain shell's tabs stay clean and label-only while an agent's light up. The
+ *  reveal is FLOORED by the status itself (statusRevealsDot) for the states that
+ *  are self-evidently news — a plain shell that crashes never reported activity
+ *  in its life, and hiding its red dot would hide the only signal it ever
+ *  produced. */
 export function paintStatusDot(el: HTMLElement, status: string, reports: boolean): void {
-  el.dataset["status"] = status || "idle";
-  el.classList.toggle("wt-reports", reports);
+  const value = status || "idle";
+  el.dataset["status"] = value;
+  el.classList.toggle("wt-reports", reports || statusRevealsDot(value));
+  el.title = statusPhrase(value);
+}
+
+/** paintProgress renders one chip's determinate progress bar from a percentage.
+ *
+ *  An absent percentage (PROGRESS_ABSENT / any negative) renders NO bar: the
+ *  element is `hidden` and its width is cleared, rather than left as a
+ *  zero-width or empty bar that would read as "0%, stalled". The width is the
+ *  only inline style — the percentage is data, and everything about how the bar
+ *  looks stays in .wt-progress-bar. */
+export function paintProgress(el: HTMLElement, progress: number): void {
+  if (progress < 0) {
+    el.hidden = true;
+    el.style.removeProperty("width");
+    return;
+  }
+  el.hidden = false;
+  el.style.width = `${String(progress)}%`;
 }
 
 /** pick returns a required descendant element or throws (static chrome only). */

package/src/index.ts

@@ -13,6 +13,8 @@
 
 export { createTerminal } from "./kernel/kernel.js";
 export { STARTUP_FAILURE_COPY } from "./kernel/startup-copy.js";
+export { LOADING_OVERLAY_CLASSES, PUBLIC_THEME_TOKENS } from "./kernel/style-contract.js";
+export type { PublicThemeToken } from "./kernel/style-contract.js";
 export type {
   CreateTerminalOptions,
   TerminalStartupFailure,