@cplieger/web-terminal-ui 5.0.3 → 5.1.0

package/src/features/tabs/notify.ts

@@ -0,0 +1,216 @@
+// 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.
+//
+// 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 `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). */
+export type NotificationCtorLike = new (
+  title: string,
+  options?: { body?: string; tag?: string },
+) => unknown;
+
+/** 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). */
+  deliver(ev: NotificationEvent, view: { sessionIsActive: boolean; label: string }): 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.
+        new Ctor(view.label, { body: text, tag: ev.id });
+        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,

package/src/kernel/style-contract.ts

@@ -0,0 +1,96 @@
+// The names that cross this package's boundary as STRINGS, published as data.
+//
+// Two surfaces of this library are addressed by name rather than by type, so no
+// compiler on either side of the boundary checks them:
+//
+//   - `theme` is `Readonly<Record<string, string>>`. The kernel copies every key
+//     onto the terminal root verbatim, so a consumer that names a token this
+//     library renamed or retired gets a live declaration nothing reads: no
+//     error, no warning, just the library's own defaults where the consumer's
+//     brand was meant to be.
+//   - The loading overlay is the CONSUMER's element (it must paint before this
+//     module loads), styled by `css/page.css` purely because the markup opts in
+//     by class. Those classes are usually hardcoded in a static HTML file no
+//     compiler reads at all.
+//
+// Both were previously prose — a doc comment on the option, a sentence in the
+// README — which a consumer could only agree with by remembering. Published as
+// data they can be ASSERTED against instead: web-terminal-kiro's app.test.ts
+// checks its theme keys and its overlay markup against these exports the same
+// way it already checks its bootstrap watchdog's wording against
+// STARTUP_FAILURE_COPY. Same reason, same shape: this file imports nothing and
+// touches no DOM, so a test or a Node build script can read it without loading
+// the kernel.
+//
+// These lists are HAND-WRITTEN on purpose. They are the public contract — a
+// decision about what this library promises to support — not a fact derived
+// from the stylesheets. What IS derived from the stylesheets is the
+// verification that the promise holds: `src/css-contract.test.ts` generates the
+// declared/referenced token inventory from the CSS itself and fails if any
+// token named here is not both DECLARED and READ by a rule. A token that is
+// declared but never read is the silent-no-op case above, reached from the
+// library's side instead of the consumer's, and no hand-maintained list can
+// catch it.
+
+/** CSS custom properties a consumer may set through `CreateTerminalOptions.theme`.
+ *
+ *  Every entry is guaranteed to be both declared and read by the shipped
+ *  stylesheets (see the inventory test), so setting any of them changes what the
+ *  terminal renders. Anything NOT listed here is unsupported: it may be an
+ *  internal token that is renamed without a release note, or it may not exist.
+ *
+ *  Two families, and one rule about the second:
+ *
+ *  - `--accent` and the `--tab-*` family recolor the chrome. `--accent` is the
+ *    widest lever — the "+" glyphs, and the active-tab border via a `color-mix`
+ *    derivation — so a single override themes several surfaces.
+ *  - The `--status-*` family is the activity-dot palette. The three ANIMATED
+ *    states (`working` / `warning` / `failed`) differ from one another only in
+ *    HUE, so replacements must keep their LIGHTNESS spread: equal-lightness
+ *    substitutes collapse into one indistinguishable state in greyscale and
+ *    under deuteranopia. `crashed` deliberately has no token of its own — it
+ *    reuses `--status-failed`, solid and static, separating from `failed` by
+ *    motion rather than color.
+ *
+ *  Values are arbitrary CSS, including `var()` references. A value that reaches
+ *  through `var()` to an INTERNAL token couples the consumer to a name this
+ *  list does not cover — assert on those separately if you write one. */
+export const PUBLIC_THEME_TOKENS = [
+  "--accent",
+  "--tab-bg",
+  "--tab-hover-bg",
+  "--tab-active-bg",
+  "--tab-active-fg",
+  "--tab-active-border",
+  "--status-working",
+  "--status-done",
+  "--status-input",
+  "--status-warning",
+  "--status-failed",
+] as const;
+
+/** A CSS custom property `CreateTerminalOptions.theme` supports.
+ *
+ *  `theme` itself stays an open `Record<string, string>` — narrowing it would
+ *  break every consumer that builds its theme object dynamically — so this type
+ *  is offered for a consumer that wants its OWN theme constant typed closed,
+ *  which is where the mistake is actually made. */
+export type PublicThemeToken = (typeof PUBLIC_THEME_TOKENS)[number];
+
+/** The class names `css/page.css` styles the pre-JS loading overlay by.
+ *
+ *  Selected by CLASS, never by the consumer's element id: the same
+ *  no-element-id-contract rule the kernel follows, and an unnamespaced name
+ *  would collide in a host document. Markup contract: one element carrying
+ *  `overlay` plus `role="status"`, with one `bar` child. Recolor it by setting
+ *  the `--wt-loading-*` custom properties on that element — it is the
+ *  consumer's element, so no JS option is involved.
+ *
+ *  The kernel writes its progressive startup status line into a region it
+ *  CREATES inside the overlay (`kernel/loading-status.ts`), so those class
+ *  names are the kernel's own and are not part of the markup a consumer
+ *  writes. */
+export const LOADING_OVERLAY_CLASSES = {
+  overlay: "wt-loading",
+  bar: "wt-loading-bar",
+} as const;

package/src/kernel/types.ts

@@ -426,12 +426,19 @@ export interface CreateTerminalOptions {
   // eslint-disable-next-line @typescript-eslint/no-invalid-void-type -- an observing handler returns nothing; only a literal `true` claims the recovery surface, so forcing `return undefined` on every observer is worse than the union
   onFatalError?: (failure: TerminalStartupFailure) => boolean | void;
   /** Theme overrides: CSS custom properties set on the terminal root so a
-   *  consumer recolors the UI (accent, tab hover/active) without shipping CSS.
-   *  Keys must be CSS custom-property names (start with "--"); values are any
-   *  CSS value. The library ships the defaults (css/00-tokens.css) — the
-   *  "template"; these are the consumer's "settings" and override them for this
-   *  instance. Known tokens: --accent, --tab-bg, --tab-hover-bg,
-   *  --tab-active-bg, --tab-active-fg, --tab-active-border. */
+   *  consumer recolors the UI (accent, tab hover/active, the activity-dot
+   *  palette) without shipping CSS. Keys must be CSS custom-property names
+   *  (start with "--"); values are any CSS value. The library ships the defaults
+   *  (css/00-tokens.css) — the "template"; these are the consumer's "settings"
+   *  and override them for this instance.
+   *
+   *  The supported keys are published as DATA, not prose: `PUBLIC_THEME_TOKENS`
+   *  (exported at the package root and at "@cplieger/web-terminal-ui/style-contract").
+   *  This type stays an open Record so a consumer may build its theme
+   *  dynamically, which means nothing here rejects a key the library renamed or
+   *  retired — the override would simply apply to nothing. Assert your keys
+   *  against that list rather than trusting a comment; the library's own suite
+   *  guarantees every token on it is both declared and read by a rule. */
   theme?: Readonly<Record<string, string>>;
 }