@cplieger/web-terminal-ui 5.0.3 → 5.2.0

package/README.md

@@ -59,15 +59,19 @@ page that has one empty container element, then call
 **Full-page host** (the terminal IS the page, as in `web-terminal-server` and
 `web-terminal-kiro`): concatenate `css/MANIFEST` into the `style.css` your page
 links. That reference bundle is `css/page.css` (the page kit: `html/body`
-reset + the terminal web font's `@font-face`, expecting the font files at
-`/vendor/fonts/`) plus the complete component set.
+reset + the bundled web font's `@font-face`, expecting the font files at
+`/vendor/fonts/`) plus the complete component set. The bundled font backs both
+the terminal display and the chrome text, so serving those files is not
+optional for a full-page host.
 
 **Embedder** (the terminal lives inside your app's layout, as a panel or pane):
 concatenate the per-preset manifest matching your composition instead:
 `css/MANIFEST.single`, `css/MANIFEST.touch`, or `css/MANIFEST.tabbed`. These
 contain ONLY root-scoped component styles: no page reset, no fonts, no
-document-level rules, nothing to quarantine. Pass `layout: "container"` so the
-terminal fills (and positions its chrome against) your container element
+document-level rules, nothing to quarantine. Chrome text then falls back to your
+platform's monospace unless you declare the `@font-face` yourself; ship it if you
+want the terminal panel to match the full-page product. Pass `layout: "container"`
+so the terminal fills (and positions its chrome against) your container element
 instead of the viewport.
 
 Feature bundles (presets) live at the `./presets` sub-path, with per-preset
@@ -134,20 +138,37 @@ are importable from `…/features/<name>` (`clipboard`, `context-menu`,
   label follows the latest submitted line (persisted server-side and recovered
   on reload) and the program's OSC 0/2 title is ignored. With `presumeReports`,
   the idle activity dot shows from tab creation instead of waiting for the
-  session's first OSC 9;4 signal. Its status dots (idle / working / done /
-  needs-input) come from the same activity monitor.
+  session's first OSC 9;4 signal. Its status dots come from the same activity
+  monitor and cover eight states: the three animated OSC 9;4 progress states
+  (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,
+  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
 
-| Option         | Default                    | Purpose                                                                                                                                                                                                                                                                                       |
-| -------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `features`     | _(none; bare kernel)_      | A FUNCTION returning the feature list. Omitted builds only the terminal (no chrome). Pass a preset by name (`features: presetTabbed`) or a factory of your own; it is called inside the startup-failure boundary, so a preset that throws is handled rather than escaping.                    |
-| `layout`       | `"viewport"`               | How the terminal claims space. `"viewport"`: the root becomes a fixed full-viewport box (the full-page product). `"container"`: the root fills your container element, which becomes the styling and positioning boundary (the embedded case).                                                |
-| `wsPath`       | `"/ws"`                    | WebSocket endpoint path the engine connects to.                                                                                                                                                                                                                                               |
-| `fontReady`    | `'14px "MonaspiceNe NFM"'` | CSS font shorthand awaited before the first resize, so the server is sized against the real web font's cell metrics rather than a fallback.                                                                                                                                                   |
-| `loading`      | _(none)_                   | A pre-JS loading overlay element (kept in your served HTML so it paints before this module loads); it is faded out and removed once the first frame renders.                                                                                                                                  |
-| `onFatalError` | _(built-in recovery)_      | Called with a `TerminalStartupFailure` after a fatal startup failure, in either phase (`feature-setup` or `kernel-init`); behavior below.                                                                                                                                                     |
-| `theme`        | _(none)_                   | Theme overrides (CSS custom properties on the terminal root): `--accent`, `--tab-bg`, `--tab-hover-bg`, `--tab-active-bg`, `--tab-active-fg`, `--tab-active-border`, plus the activity-dot palette `--status-working`, `--status-done`, `--status-input`. The library ships neutral defaults. |
+| Option         | Default                    | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| -------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `features`     | _(none; bare kernel)_      | A FUNCTION returning the feature list. Omitted builds only the terminal (no chrome). Pass a preset by name (`features: presetTabbed`) or a factory of your own; it is called inside the startup-failure boundary, so a preset that throws is handled rather than escaping.                                                                                                                                                                                                                                                                                                                |
+| `layout`       | `"viewport"`               | How the terminal claims space. `"viewport"`: the root becomes a fixed full-viewport box (the full-page product). `"container"`: the root fills your container element, which becomes the styling and positioning boundary (the embedded case).                                                                                                                                                                                                                                                                                                                                            |
+| `wsPath`       | `"/ws"`                    | WebSocket endpoint path the engine connects to.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `fontReady`    | `'14px "MonaspiceNe NFM"'` | CSS font shorthand awaited before the first resize, so the server is sized against the real web font's cell metrics rather than a fallback.                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `loading`      | _(none)_                   | A pre-JS loading overlay element (kept in your served HTML so it paints before this module loads); it is faded out and removed once the first frame renders.                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `onFatalError` | _(built-in recovery)_      | Called with a `TerminalStartupFailure` after a fatal startup failure, in either phase (`feature-setup` or `kernel-init`); behavior below.                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `theme`        | _(none)_                   | Theme overrides (CSS custom properties on the terminal root): `--accent`, `--tab-bg`, `--tab-hover-bg`, `--tab-active-bg`, `--tab-active-fg`, `--tab-active-border`, plus the activity-dot palette `--status-working`, `--status-done`, `--status-input`, `--status-warning`, `--status-failed`. The library ships neutral defaults. If you retheme the animated trio (`--status-working` / `--status-warning` / `--status-failed`), keep their LIGHTNESS spread: they differ only in hue, so equal-lightness replacements collapse into one another in greyscale and under deuteranopia. |
 
 `createTerminal()` returns a handle: `focus()` re-focuses the terminal input
 (and opens the soft keyboard on touch); `send(bytes)` sends bytes to the active
@@ -157,6 +178,33 @@ screen without injecting keystrokes (send a redraw keystroke yourself if you
 want one, for example Ctrl+L); and `destroy()` tears every feature down and
 releases the kernel.
 
+### Themes that provably apply
+
+`theme` is an open `Record<string, string>` — the kernel sets every key on the
+terminal root verbatim — so a key this library renamed or retired becomes a live
+declaration nothing reads: no error, just the library's neutral defaults where
+your brand should be. The supported keys are therefore published as data:
+
+```ts
+import { PUBLIC_THEME_TOKENS } from "@cplieger/web-terminal-ui/style-contract";
+// or from the package root; the subpath imports nothing and touches no DOM,
+// so a Node script can read it too.
+
+for (const key of Object.keys(MY_THEME)) {
+  expect(PUBLIC_THEME_TOKENS).toContain(key); // your test, our list
+}
+```
+
+Every token on that list is guaranteed by this package's own suite to be both
+declared AND read by a shipped rule, so setting it changes what renders. The
+second half is the one you cannot check from outside: a token that is declared
+but that no rule reads accepts your override and applies it to nothing. Anything
+NOT on the list is internal and may be renamed without a release note.
+
+`LOADING_OVERLAY_CLASSES` is published from the same module for the same reason:
+your pre-JS overlay markup opts into `css/page.css`'s styling by class name, and
+that markup usually lives in a static HTML file no compiler reads.
+
 ### Startup failures
 
 You do not need your own startup-failure UI. Every way starting up can fail ends

package/css/00-tokens.css

@@ -82,6 +82,28 @@
   --status-working: #52a9fe; /* agent working (waves): the same blue as the default --accent */
   --status-done: #22c55e; /* turn finished: solid green */
   --status-input: #fb923c; /* action required: solid orange + ring */
+  /* OSC 9;4 progress states 4 (warning) and 2 (error). Both render as the SAME
+     object as working -- identical glow + travelling wave, one shared rule and
+     one shared pair of keyframes (30-tabs.css) -- differing ONLY in hue, because
+     the escape code models one progress indicator with several states rather
+     than three unrelated dots. Neither wears a ring: the frozen hard ring is
+     --status-input's exclusive meaning ("blocked, waiting on you"), and neither
+     warning nor error asks the user to act.
+     LIGHTNESS SEPARATION IS LOAD-BEARING, NOT DECORATIVE. Three states that
+     differ only by hue collapse into one under deuteranopia and in greyscale, so
+     the three hues are also spread across lightness. Measured OKLab L (and WCAG
+     relative luminance Y, the greyscale read):
+       warning #facc15  L 86.1%  Y 63.6%
+       working #52a9fe  L 71.9%  Y 37.3%
+       failed  #dc2626  L 57.7%  Y 16.7%
+     ~14 L points and a wide Y gap between each neighbour, monotonic in both, so
+     the three stay ordered and distinguishable with hue discarded entirely. A
+     retheme MUST keep that spread: two animated states at the same lightness are
+     indistinguishable to a colour-blind user, whatever their hues. warning is
+     YELLOW, deliberately not amber -- amber would collide with --status-input's
+     orange (L 75.8%), which sits between working and warning. */
+  --status-warning: #facc15; /* OSC 9;4 state 4: yellow disc, working's wave */
+  --status-failed: #dc2626; /* OSC 9;4 state 2: red disc, working's wave; crashed reuses it solid and static */
   --radius: 0.75rem;
   --radius-inner: 0.5rem;
   /* Small square icon buttons (e.g. the 24px tab-close x): at that size the
@@ -102,8 +124,38 @@
   --sp-1: 0.25rem;
   --sp-2: 0.5rem;
   --sp-3: 0.75rem;
-  --font-ui: -apple-system, blinkmacsystemfont, "SF Pro Text", system-ui, sans-serif;
+  /* Chrome text uses the SAME bundled web font as the terminal, deliberately.
+     A system-font stack made the tab-title alignment unfixable: every entry of
+     the old stack (-apple-system, BlinkMacSystemFont, "SF Pro Text") resolves
+     only on Apple platforms, so everywhere else it fell through to system-ui —
+     which Chromium resolves through fontconfig and Firefox from the desktop UI
+     font setting. Two different typefaces, with two different vertical metrics,
+     on ONE machine. Optically centring text needs the font's ascent/descent
+     asymmetry as a known constant (--label-ink-shift below), and an unknown
+     font has no constant, so no value could ever be right on both.
+
+     MonaspiceNe NFM is already served at /vendor/fonts by every full-page host
+     (page.css declares the faces, the Dockerfiles ship the files), so this adds
+     no download. A consumer serving a component-only manifest has no face for
+     this family and falls back to the platform monospace — and also ships no tab
+     strip (MANIFEST.touch excludes 30-tabs.css), so nothing metric-dependent
+     rides on that fallback. */
+  --font-ui: "MonaspiceNe NFM", ui-monospace, monospace;
   --font-mono: "MonaspiceNe NFM", monospace;
+  /* How far a chip label's INK sits below its line box's centre, so flex
+     centring can be corrected by exactly that much (see .wt-tab-label in
+     30-tabs.css). Derived from MonaspiceNe NFM's own tables and outlines:
+
+       (ascent - descent) / 2      = (0.995 - 0.250) / 2   = 0.3725em
+       (cap ink - descender ink)/2 = (0.7344 - 0.2188) / 2 = 0.2578em
+       difference                                          = 0.1147em
+
+     A constant is safe here only because the bundled font leaves engines
+     nothing to disagree about: hhea, OS/2 typo and usWin all declare the same
+     0.995 / 0.250 with lineGap 0, and fsSelection sets USE_TYPO_METRICS, so
+     Chromium, Gecko and WebKit all compute the same line box. Re-derive this
+     number if the bundled font ever changes; do not nudge it by eye. */
+  --label-ink-shift: 0.1147em;
   --dur-micro: 0.1s;
   --dur-standard: 0.2s;
   --dur-enter: 0.25s;

package/css/30-tabs.css

@@ -75,15 +75,34 @@
   width: 300px;
   flex: 0 1 auto;
   min-width: 100px;
+  /* Positioning context for the chip's own overlay: the OSC 9;4 determinate
+     progress bar sits on its bottom edge (see .wt-progress-bar). Nothing else
+     inside a chip is absolutely positioned, and the strip's two root-level
+     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
      whatever its tallest child happened to be, and the "+" hard-coded a COPY of
      that arithmetic (close button + padding + border) — two sources of truth
-     for one row, which drifted the moment a child's box grew: a browser without
-     text-box support kept the label's untrimmed line box (31px, past the 24px
-     close button), so the chip rendered 49px tall next to a 42px "+" and a 44px
-     keyboard button. --touch-target is also the tap-target floor the rest of
+     for one row, which drifted the moment a child's box grew: the label's own
+     box once reached 31px, past the 24px close button, and the chip rendered
+     49px tall next to a 42px "+" and a 44px keyboard button. (That growth came
+     from a text-box trim's descender padding being applied on the untrimmed
+     code path, which no longer exists -- the label's geometry is now one
+     unconditional rule; see .wt-tab-label. The two-sources-of-truth lesson is
+     what survives.) --touch-target is also the tap-target floor the rest of
      the chrome already respects, including this chip's mobile counterpart
      (.wt-switcher-current in 31-switcher.css, same declaration).
 
@@ -174,57 +193,58 @@
 }
 
 /* The label flexes to fill the fixed-width tab and truncates with an ellipsis
-   (min-width: 0 lets a flex item shrink below its content width). */
+   (min-width: 0 lets a flex item shrink below its content width), and it owns the
+   ink-centring geometry the two switcher labels in 31-switcher.css share verbatim.
+
+   Centre the INK, not the line box. A font's metrics box reaches far higher above
+   the baseline than below it (the bundled font: 0.995em over, 0.250em under),
+   while the ink of a mixed-case title runs 0.7344em over (cap height) to 0.2188em
+   under (descender). Flex centring centres the BOX, which leaves the visible text
+   --label-ink-shift low — 0.1147em, 1.5px at this size — reading as
+   baseline-aligned with the activity dot's bottom edge instead of level with its
+   centre. Two declarations, one job, and a third that must NOT be added:
+
+   - padding-block is the ink allowance, not spacing. `overflow: hidden` (which
+     the ellipsis requires) clips at the padding box, and the line box clears the
+     tallest ink by only 0.6px, so an unpadded label shaves the top off every
+     acute accent and caron. 0.125em per side buys 2.2px of clearance at 13px, and
+     being symmetric it does not move the centred text.
+   - margin-block hangs TWICE the shift below the box. Flex centring centres the
+     MARGIN box, so a bottom-heavy margin lifts the border box by half of it --
+     exactly one shift -- and unlike padding it does not enlarge the clipping box.
+   - line-height stays at `normal`, deliberately. Setting it looks like the
+     responsible thing to do and it is the trap: `normal` is the ONE value whose
+     half-leading is zero by definition, which is what makes the baseline sit at
+     exactly the engine's ascent below the box top. Any other value leaves
+     (line-height - font box) / 2 to be halved and rounded, and Chromium floors
+     it -- measured with an explicit 1.25 the 14px switcher labels came out a
+     FULL pixel high (line box 17.5 under an 18px font box, so half-leading
+     -0.25 floored to -1) while the 13px strip label was fine, which is exactly
+     the kind of works-where-I-looked bug this rule exists to end.
+
+   What this deliberately does NOT use is `text-box: trim-both`, which all three
+   previous attempts were built on. It ships in Blink and WebKit only (Firefox has
+   it in Nightly behind layout.css.text-box.enabled), so it can only be applied
+   behind an @supports gate, and a gate means two engines render two different
+   geometries of which only the one the author is looking at ever gets tuned.
+   Measured on the gated version: Chromium centred to 0.02px while Firefox sat
+   1.50px low with its baseline half a pixel BELOW the dot. The keyword vocabulary
+   is too coarse for this text besides -- `cap alphabetic` centres the cap band and
+   reads 1.14px low on lowercase, `ex alphabetic` centres the x-band and reads high
+   on capitals, and a mixed-case tab title wants neither edge.
+
+   The residual error is engines rounding ascent and descent to whole pixels, which
+   makes the ideal shift 0.127em at 13px and 0.099em at 14px; the one authored
+   0.1147em is the unrounded truth and lands within 0.22px at both sizes, in every
+   engine, with no fork. */
 :where(.wt-root) .wt-tab-label {
   flex: 1 1 auto;
   min-width: 0;
   overflow: hidden;
   white-space: nowrap;
   text-overflow: ellipsis;
-}
-
-/* Center the INK, not the line box: UI fonts carry far more ascent than
-     descent (the -apple-system/Noto Sans stack at 13px: 14px over / 4px under
-     the baseline), so the flex-centered line box leaves the visible text ~1.5px
-     low — reading as baseline-aligned with the activity dot's bottom instead of
-     its center. Trimming the box makes flexbox center the glyph band instead of
-     the font's metrics box.
-
-     `ex`, not `cap`, is the over edge, because a tab title is sentence case and
-     lowercase-dominant ("workspace", "refactor the auth module"). Centering the
-     x-height/baseline band centers the total ink of such a string, since a
-     Latin font's ascender overshoot above x-height is about its descender depth
-     below the baseline (measured on this stack at 13px: 3.0px over vs 3.0px
-     under, ink center 0.02px off the chip's center). `cap alphabetic` — the
-     right choice for an ALL-CAPS label — leaves lowercase text 1.14px low,
-     which is the original complaint barely moved.
-
-     padding-block is LOAD-BEARING, not spacing: trimming puts the box's under
-     edge ON the baseline, and `overflow: hidden` clips at the padding edge, so
-     with no padding every descender and every tall diacritic is cut off (
-     measured: 3.3px of p/y/g/j tail and 2.3px of an acute accent, i.e. "pygmy
-     jaguar Ápple" rendered as "pyqmy iaquar Apple"). 0.5em restores the ink
-     overhang the trim removes from the box; being symmetric it does not move
-     the centered band, and being em-relative it tracks the font size.
-
-     The pair is @supports-GATED because the padding is the trim's allowance and
-     nothing else: an untrimmed line box already contains that overhang, so
-     adding the padding there is not "harmless slack" (this comment used to
-     claim it was) — it grew the label's box to 31px, past the 24px close button,
-     and a browser without text-box support rendered 49px tab chips beside a
-     42px "+" and a 44px keyboard button. The chip's own --touch-target floor
-     pins the row height either way; the gate is what keeps the label from
-     pushing PAST it. Gating the shorthand (not the longhands) is deliberate: an
-     engine that ships text-box-trim without the shorthand does not apply the
-     declaration we actually write, so it must take the untrimmed branch too.
-
-     Shared by all three chip labels (this one + the two switcher labels in
-     31-switcher.css). */
-@supports (text-box: trim-both ex alphabetic) {
-  :where(.wt-root) .wt-tab-label {
-    text-box: trim-both ex alphabetic;
-    padding-block: 0.5em;
-  }
+  padding-block: 0.125em;
+  margin-block: 0 calc(2 * var(--label-ink-shift));
 }
 
 /* A little breathing room after the activity dot, before the label. */
@@ -569,9 +589,13 @@
 }
 
 /* ===== Activity dots (activityMonitor via tabs) =====
-   Four-state, distinguishable without color (shape + motion, not hue alone),
-   per section 12 / WCAG 1.4.1. The one .wt-status-dot vocabulary is shared by
-   the desktop strip, the mobile switcher, and the overview sheet rows.
+   Eight-state, distinguishable without color (shape + motion, not hue alone),
+   per section 12 / WCAG 1.4.1: three ANIMATED progress states (working /
+   warning / failed — one object, three hues, spread across lightness so they
+   survive greyscale and deuteranopia), a frozen ringed disc (input), two static
+   discs (green done, red crashed), and two hollow ones (idle, dim exited).
+   The one .wt-status-dot vocabulary is shared by the desktop strip, the mobile
+   switcher, and the overview sheet rows.
 
    Revealed PER TAB: the dot is hidden until its own session reports activity
    (OSC 9;4 progress, or a classified OSC 9 notification), at which point the
@@ -595,6 +619,7 @@
      from the filled done/working/input states (WCAG 1.4.1). */
   background: transparent;
   border: 1.5px solid color-mix(in oklch, var(--text) 45%, transparent);
+
   /* Reset every transient visual owned by a status. In particular, a dot that
      leaves working must stop its pulse, and a dot that enters working must not
      carry the input ring or an exited opacity into the animated paint layer. */
@@ -603,6 +628,39 @@
   animation: none;
 }
 
+/* ===== Determinate progress bar (OSC 9;4 percentage) =====
+   The second display mode the specs name for a progress report (iTerm2 calls it
+   a progress bar; ConEmu also puts the value on the taskbar, which is the
+   document-title prefix's job). One 2px line on the chip's bottom edge, shared
+   by all three chip sites (desktop strip chip, mobile active row, expanded list
+   row) because it ships in the one chipContent builder.
+
+   The ACCENT colour, not a per-state tint: the bar answers "how far", the dot
+   answers "in what state", and tinting the bar per state would say the same
+   thing twice while making a 2px line carry hue it cannot carry legibly.
+
+   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.
+
+   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;
+  bottom: 0;
+  height: 2px;
+  max-width: 100%;
+  background: var(--accent);
+  pointer-events: none;
+}
+
 /* Reveal a dot only once its session has reported activity (the tabs feature
    adds .wt-reports per dot; see paintStatusDot). Without it the dot — and the
    whole activity vocabulary for that tab — stays invisible. */
@@ -629,14 +687,44 @@
    opacity always multiplies onto its pseudos, so true independence requires
    animating disc COLORS, not element opacity. Server-side this is driven by the
    OSC 9;4 progress signal, so it tracks agent activity, not the user typing at
-   the prompt. */
-:where(.wt-root) .wt-status-dot[data-status="working"] {
+   the prompt.
+
+   WORKING, WARNING AND FAILED SHARE THIS RULE, AND BOTH KEYFRAMES, VERBATIM.
+   OSC 9;4 models ONE progress indicator with several states (1/3 active,
+   4 warning, 2 error), so it renders as one visual object whose HUE carries the
+   state — not three unrelated dots. Each state therefore sets --dot-color and
+   changes nothing else: same disc, same glow beat, same travelling wave, same
+   period. Do NOT give warning or failed a ring — the frozen hard ring is
+   input's exclusive meaning ("blocked, waiting on you"), and neither of these
+   asks the user to act (see the input rule). Hue alone would not be enough on
+   its own, which is why the three tokens are also spread across lightness
+   (measured OKLab L: warning 86.1%, working 71.9%, failed 57.7% — see the
+   load-bearing note in 00-tokens.css). */
+:where(.wt-root) .wt-status-dot[data-status="working"],
+:where(.wt-root) .wt-status-dot[data-status="warning"],
+:where(.wt-root) .wt-status-dot[data-status="failed"] {
   position: relative;
-  background: var(--status-working);
-  border-color: var(--status-working);
+  background: var(--dot-color);
+  border-color: var(--dot-color);
   animation: wt-working-glow 1.2s ease-in-out infinite;
 }
 
+/* The one difference between the three animated states. Kept as three
+   single-declaration rules so the shared paint above reads as literally shared:
+   a future change to the disc, the glow or the wave cannot land on one hue and
+   miss the other two. */
+:where(.wt-root) .wt-status-dot[data-status="working"] {
+  --dot-color: var(--status-working);
+}
+
+:where(.wt-root) .wt-status-dot[data-status="warning"] {
+  --dot-color: var(--status-warning);
+}
+
+:where(.wt-root) .wt-status-dot[data-status="failed"] {
+  --dot-color: var(--status-failed);
+}
+
 /* The ripple layer: a feathered radial BAND (not a hairline border) that starts
    hugging the disc's edge (inset -2px, the 9->13px box) and then travels
    outward, dissolving. The band is painted as a radial-gradient — soft on both
@@ -645,16 +733,18 @@
    which is what makes the wave visibly dissipate as it grows. transform +
    opacity only, so it composites without repaints (a gradient background is
    rasterized once, unlike an animated box-shadow spread, which repaints every
-   frame). It exists only in the working state — no stale layer to pin when a
-   dot changes status. (The switcher notification dot never shows working —
-   input/done only — so its position: absolute placement never meets this
-   rule's position: relative.)
+   frame). It exists only in the three animated states — no stale layer to pin
+   when a dot changes status. (The switcher notification dot never shows any of
+   them — input/done/crashed only — so its position: absolute placement never
+   meets this rule's position: relative.)
 
    The final scale is deliberately capped at today's 27px footprint: the mobile
    overview row (.wt-switcher-row-select) clips at overflow: hidden 12.5px from
    the dot's center, and a wave wider than ~25px picks up a visible straight
    edge there. Visibility comes from the band's weight and timing, not size. */
-:where(.wt-root) .wt-status-dot[data-status="working"]::after {
+:where(.wt-root) .wt-status-dot[data-status="working"]::after,
+:where(.wt-root) .wt-status-dot[data-status="warning"]::after,
+:where(.wt-root) .wt-status-dot[data-status="failed"]::after {
   content: "";
   position: absolute;
   inset: -2px;
@@ -662,7 +752,7 @@
   background: radial-gradient(
     closest-side,
     transparent 44%,
-    var(--status-working) 76%,
+    var(--dot-color) 76%,
     transparent 100%
   );
   animation: wt-working-ripple 1.2s linear infinite;
@@ -702,23 +792,46 @@
   opacity: 0.5;
 }
 
+/* Crashed (a non-zero exit status, or a signal the program was not asked for;
+   a server-initiated end is "exited", so a routine restart never paints red):
+   a SOLID dot in the failed red, static.
+
+   Solid, not hollow. There is no "hollow means no process" invariant to honour —
+   idle is hollow with a perfectly live process — so hollowness would only say
+   "unremarkable", and a crash is the least unremarkable thing this vocabulary
+   reports. It uses the SAME token as failed, because "the program reported an
+   error" and "the program died badly" are one family, and it separates from
+   failed by MOTION: failed pulses and emits the travelling wave, crashed is
+   completely still (no glow, no wave, no ring — nothing clears it, so any
+   animation would nag forever). That is the same axis that already separates
+   working from done. Under prefers-reduced-motion the separation survives as
+   SHAPE: failed degrades to a ringed donut (see the reduced-motion block), while
+   crashed stays a bare solid disc. */
+:where(.wt-root) .wt-status-dot[data-status="crashed"] {
+  background: var(--status-failed);
+  border-color: var(--status-failed);
+}
+
 /* The disc's glow beat: base -> brighter -> base, then a rest until the next
    cycle. Colors are set at EVERY frame, which both drives the glow and pins
    the paint — a dot entering working in the same frame input/done ends can
    never re-pulse the previously rasterized paint (the hazard the old
    opacity-only pulse had to pin box-shadow against). Element opacity stays 1
-   throughout; see the layer-independence note on the working rule. */
+   throughout; see the layer-independence note on the working rule.
+
+   --dot-color, not --status-working: this beat is shared verbatim by working,
+   warning and failed, each of which supplies its own hue. */
 @keyframes wt-working-glow {
   0%,
   70%,
   100% {
-    background-color: var(--status-working);
-    border-color: var(--status-working);
+    background-color: var(--dot-color);
+    border-color: var(--dot-color);
   }
 
   35% {
-    background-color: color-mix(in oklch, var(--status-working) 78%, #fff);
-    border-color: color-mix(in oklch, var(--status-working) 78%, #fff);
+    background-color: color-mix(in oklch, var(--dot-color) 78%, #fff);
+    border-color: color-mix(in oklch, var(--dot-color) 78%, #fff);
   }
 }
 
@@ -758,22 +871,27 @@
   }
 }
 
-/* Reduced-motion: drop the working motion (glow + ripple), keep color. */
+/* Reduced-motion: drop the animated states' motion (glow + ripple), keep color.
+   All three degrade the same way, since they are one object with three hues. */
 @media (prefers-reduced-motion: reduce) {
-  :where(.wt-root) .wt-status-dot[data-status="working"] {
+  :where(.wt-root) .wt-status-dot[data-status="working"],
+  :where(.wt-root) .wt-status-dot[data-status="warning"],
+  :where(.wt-root) .wt-status-dot[data-status="failed"] {
     animation: none;
-    /* Motion is what separates working from input's frozen ping; with it
-       removed, punch an inner hole (dot -> donut) and add a static ring so
-       working differs from input (solid ringed disc) and done (bare disc) by
-       shape, not hue alone (WCAG 1.4.1). The ring carries the same 30%
-       weight as input's. */
+    /* Motion is what separates the animated states from input's frozen ping;
+       with it removed, punch an inner hole (dot -> donut) and add a static ring
+       so they differ from input (solid ringed disc) and done (bare disc) by
+       shape, not hue alone (WCAG 1.4.1). The ring carries the same 30% weight as
+       input's, from whichever hue the state supplied. */
     box-shadow:
       inset 0 0 0 2px var(--bg),
-      0 0 0 2px color-mix(in srgb, var(--status-working) 30%, transparent);
+      0 0 0 2px color-mix(in srgb, var(--dot-color) 30%, transparent);
   }
 
   /* The ripple layer disappears entirely (not just paused mid-wave). */
-  :where(.wt-root) .wt-status-dot[data-status="working"]::after {
+  :where(.wt-root) .wt-status-dot[data-status="working"]::after,
+  :where(.wt-root) .wt-status-dot[data-status="warning"]::after,
+  :where(.wt-root) .wt-status-dot[data-status="failed"]::after {
     content: none;
   }
 }