@cplieger/web-terminal-ui 4.8.1 → 5.0.1

package/README.md

@@ -12,7 +12,7 @@ The reference touch-first browser UI for
 It turns the engine's render/scroll/connection/keyboard modules into a usable
 terminal on a phone as well as a desktop.
 
-One `createTerminal(root, { features })` call builds the entire terminal UI
+One `createTerminal(target, { features })` call builds the entire terminal UI
 inside a single container element you provide. A small always-present kernel
 composes with opt-in feature modules that own everything above the raw
 terminal:
@@ -54,7 +54,7 @@ through its connection banner.
 
 Serve a CSS bundle matching how you embed the terminal, plus a minimal HTML
 page that has one empty container element, then call
-`createTerminal(root, { features })` from your entry module.
+`createTerminal(target, { features })` from your entry module.
 
 **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
@@ -88,17 +88,20 @@ entry modules beside it:
 <script type="module">
   import { createTerminal } from "@cplieger/web-terminal-ui";
   import { presetTabbed } from "@cplieger/web-terminal-ui/presets";
-  createTerminal(document.getElementById("terminal"), {
-    features: presetTabbed(),
+  createTerminal("#terminal", {
+    features: presetTabbed,
     loading: document.getElementById("loading"),
   });
   // or, for a server that exposes the WebSocket elsewhere / a custom font:
-  // createTerminal(root, { features: presetTabbed(), wsPath: "/api/shell/ws", fontReady: '14px "MyMono"' });
+  // createTerminal("#terminal", { features: presetTabbed, wsPath: "/api/shell/ws", fontReady: '14px "MyMono"' });
 </script>
 ```
 
-`createTerminal(root, opts?)` builds the entire terminal subtree (the kernel
-plus every feature's chrome) inside `root` itself. There is no element-id
+`createTerminal(target, opts?)` builds the entire terminal subtree (the kernel
+plus every feature's chrome) inside the target element itself. `target` is a CSS
+selector or an element: pass a **selector** from a page (`"#terminal"`) and pass
+an **element** only when you already hold one you created yourself. The
+difference matters — see "Startup failures" below. There is no element-id
 contract for the host page to reproduce, and every style and CSS custom
 property is scoped to the `wt-root` class it stamps on your element (removed
 again by `destroy()`). Call it exactly once; the engine's
@@ -138,7 +141,7 @@ are importable from `…/features/<name>` (`clipboard`, `context-menu`,
 
 | Option         | Default                    | Purpose                                                                                                                                                                                                                                                                                       |
 | -------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `features`     | _(none; bare kernel)_      | The feature list. Omitted or empty builds only the terminal (no chrome). Use a preset from `./presets` or a hand-picked array.                                                                                                                                                                |
+| `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.                                                                                                                                                   |
@@ -154,20 +157,49 @@ 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.
 
-Startup can fail in two phases, and both end at the same recovery surface. If a
-feature's setup throws or rejects (`phase: "feature-setup"`), the kernel stops the
-connection, tears down every completed feature and core listener, clears the
-broken subtree, and shows a reload surface. If `createTerminal` itself throws
-(`phase: "kernel-init"` — an invalid feature list, a DOM invariant), it shows the
-same surface, lowers your loading overlay so the surface is visible, and then
-rethrows, so a caller with its own error handling still sees the error. Either
-way the surface is modal when the terminal owns the viewport and non-modal when
-it fills an embedded container.
+### Startup failures
+
+You do not need your own startup-failure UI. Every way starting up can fail ends
+at one recovery surface this package owns — a "Terminal failed to start" panel
+with a Reload button — and your loading overlay is lowered so that panel is
+visible.
+
+Two phases can fail. If a feature's setup throws or rejects
+(`phase: "feature-setup"`), the kernel stops the connection, tears down every
+completed feature and core listener, clears the broken subtree, and shows the
+panel. If `createTerminal` itself throws (`phase: "kernel-init"` — an
+unresolvable mount selector, a preset that throws, an invalid feature list, a DOM
+invariant), it shows the same panel and then rethrows, so a caller with its own
+error handling still sees the error. Either way the panel is modal when the
+terminal owns the viewport and non-modal when it fills an embedded container.
+
+**This is why `target` takes a selector and `features` takes a function.** Both
+are resolved INSIDE that boundary. Written the other way round —
+`createTerminal(document.getElementById("terminal"), { features: presetTabbed() })`
+— the lookup and the preset call both happen at your call site, before
+`createTerminal` is entered, so a missing element or a throwing preset escapes
+the library entirely and leaves the page spinning under your overlay with nothing
+but a console error. Those were the two failures every consumer used to
+hand-build its own dialog for.
+
+One case has no panel by design: an embedded terminal (`layout: "container"`)
+whose mount target does not exist. It is one panel inside a host application that
+is otherwise working, so claiming the viewport to report its own failure would
+break a healthy page. The failure is still delivered to `onFatalError` and still
+rethrown, with `surface: undefined` to say there is nowhere to render.
 
 `onFatalError` receives the failure after cleanup. Discriminate on `phase`:
 `feature-setup` names the offending `feature`, `kernel-init` does not, because
-feature composition never began. Return `true` only when the host has rendered
-replacement recovery UI into the terminal root.
+feature composition never began. `surface` names the element the built-in panel
+would fill, and is the element to render into if you claim it. Return `true` only
+when you have rendered replacement recovery UI there.
+
+If your page also carries an inline bootstrap watchdog — a script that reports
+"the JS bundle never loaded at all", a rung below `import` — it cannot import
+anything by definition. Take its wording from `STARTUP_FAILURE_COPY` (exported at
+the package root and at `@cplieger/web-terminal-ui/startup-copy`, which imports
+nothing and touches no DOM so a build script can read it) and substitute the
+strings into your HTML at build time, rather than restating them by hand.
 
 ## What ships
 

package/css/00-tokens.css

@@ -58,10 +58,27 @@
      coincidence of taste, not a dependency.
 
      Working shares the accent's hue family, so on the ACTIVE tab it sits on an
-     accent-derived fill (--tab-active-bg): measured 5.2:1 against it, and 8.0:1
-     against the bar, both clear of the 3:1 non-text minimum. Hue still never
-     carries state on its own (the wave's motion, and the donut it becomes under
-     prefers-reduced-motion, are the non-hue cues per WCAG 1.4.1). */
+     accent-derived fill (--tab-active-bg) rather than on the bar. Measured
+     (sRGB, WCAG 1.4.3 formula, each layer composited over the page's #000):
+     8.0:1 against the bar, but only 2.6:1 against the active-tab fill -- under
+     the 3:1 non-text minimum. This comment previously claimed 5.2:1 for the
+     active-tab case, which was wrong by ~2x; a consumer's code review quoted the
+     figure back as its baseline and built a finding on it, so treat the number
+     here as load-bearing and re-measure rather than adjust it by eye.
+
+     Why it is nevertheless not a 1.4.1 failure, and why the fill is not simply
+     darkened: hue never carries state on its own here -- working is a travelling
+     wave, input a hard 2px ring, done a bare disc, and under
+     prefers-reduced-motion working becomes a donut -- so every state stays
+     distinguishable by shape and motion at any of these ratios. Reaching 3:1 on
+     the fill means dropping the accent fraction below ~25%, which visibly
+     de-themes the active tab; that is a design call for a future release, not a
+     silent token tweak. The dot's contrast against the fill does NOT vary with
+     terminal output: the tabs feature publishes --wt-reserve-bottom and
+     viewport.ts folds it into the terminal's bottom inset, so content stops
+     above the bar and #000 is what composites behind it. The one exception is
+     the mobile switcher tray while EXPANDED, which overlays the terminal by
+     design. */
   --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 */

package/css/30-tabs.css

@@ -75,6 +75,22 @@
   width: 300px;
   flex: 0 1 auto;
   min-width: 100px;
+  /* 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
+     the chrome already respects, including this chip's mobile counterpart
+     (.wt-switcher-current in 31-switcher.css, same declaration).
+
+     min-height, not height: the floor governs today (the tallest child is the
+     1.5rem close button, which fits with room to spare), and taller future
+     content grows the row rather than overflowing a fixed box. */
+  min-height: var(--touch-target);
   padding: var(--sp-2);
   /* A transparent border is reserved on every tab so toggling the inactive
      outline (below) never shifts the strip's layout. */
@@ -112,9 +128,8 @@
 
 /* Press (mousedown / touch-hold): one rung past the hover lift — same recipe,
    deeper mix — so hover -> press reads as a single dimension. After the hover
-   rule so it wins while both apply. Scoped like hover: clicking the active tab
-   selects nothing (it is already active), so it presses like the static surface
-   it is. */
+   rule so it wins while both apply. The active chip has its own pair (above),
+   mixed against the active fill instead of the inactive one. */
 :where(.wt-root) .wt-tab:not(.wt-tab-active):active {
   background: color-mix(in oklch, var(--tab-bg), var(--text) 25%);
   color: var(--tab-active-fg);
@@ -129,6 +144,34 @@
   color: var(--tab-active-fg);
 }
 
+/* The active tab answers a press too. Clicking it selects nothing, which is why
+   it was originally left inert — but selection is not the only thing a chip does:
+   it is a drag handle for reordering, a right-click target for the tab menu, a
+   double-tap target for rename, and it carries a close button. A control with
+   four affordances and no pointer feedback reads as decoration, and it was the
+   only chip in the strip that gave none (the same gap that got the keyboard
+   button its hover wash).
+
+   The lift is mixed with --tab-active-fg rather than --text: this is a lighter
+   press over an already-filled control (the .wt-switcher-current / .wt-tab-new
+   recipe), not a wash over a transparent one, so it follows the filled-surface
+   vocabulary and stays themeable through one token. It is a rung subtler than the
+   inactive chip's 15%/25% because it starts from an already-lifted fill.
+
+   Hover is gated to real hover pointers. Tapping an INACTIVE chip makes it
+   active, so a touchscreen's sticky :hover leaves with the class; tapping the
+   ACTIVE chip changes nothing, so an ungated hover would stay lit until the next
+   tap somewhere else. Touch feedback there is :active, which is correct. */
+@media (hover: hover) {
+  :where(.wt-root) .wt-tab-active:hover {
+    background: color-mix(in oklch, var(--tab-active-bg), var(--tab-active-fg) 12%);
+  }
+}
+
+:where(.wt-root) .wt-tab-active:active {
+  background: color-mix(in oklch, var(--tab-active-bg), var(--tab-active-fg) 22%);
+}
+
 /* 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). */
 :where(.wt-root) .wt-tab-label {
@@ -137,7 +180,9 @@
   overflow: hidden;
   white-space: nowrap;
   text-overflow: ellipsis;
-  /* Center the INK, not the line box: UI fonts carry far more ascent than
+}
+
+/* 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
@@ -159,15 +204,26 @@
      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
-     grown box (~20px) still sits inside the close button's 1.5rem, so the tab
-     height is unchanged. A browser without text-box support keeps the untrimmed
-     box, where the padding is harmless slack.
+     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). */
-  text-box: trim-both ex alphabetic;
-  padding-block: 0.5em;
+@supports (text-box: trim-both ex alphabetic) {
+  :where(.wt-root) .wt-tab-label {
+    text-box: trim-both ex alphabetic;
+    padding-block: 0.5em;
+  }
 }
 
 /* A little breathing room after the activity dot, before the label. */
@@ -241,12 +297,16 @@
   align-items: center;
   justify-content: center;
   flex: none;
-  /* Square box that matches the tab height (a stretched flex item ignores
-     aspect-ratio against its SVG's intrinsic width, so size it explicitly). The
-     tab height is the close-button (1.5rem) + vertical padding (2×sp-2) +
-     border. */
-  width: calc(1.5rem + 2 * var(--sp-2) + 2px);
-  height: calc(1.5rem + 2 * var(--sp-2) + 2px);
+  /* A SQUARE box of exactly the strip's control height, so it lines up with the
+     tab chips beside it and with the keyboard button after it (the .wt-btn
+     primitive's 44px box, same token). Sized explicitly on both axes rather
+     than by aspect-ratio: a stretched flex item ignores aspect-ratio against
+     its SVG's intrinsic width. It used to restate the chip's height arithmetic
+     (close button + padding + border) as a calc(), which is how it ended up
+     7px short of a chip whose content grew — see the min-height note on
+     .wt-tab. */
+  width: var(--touch-target);
+  height: var(--touch-target);
   padding: 0;
   background: transparent;
   border: none;

package/css/31-switcher.css

@@ -178,11 +178,16 @@
   text-overflow: ellipsis;
   white-space: nowrap;
   text-align: left;
-  /* Ink-centering trim + its mandatory descender allowance, same as
-     .wt-tab-label (see 30-tabs.css for why `ex` and why the padding is not
-     optional). */
-  text-box: trim-both ex alphabetic;
-  padding-block: 0.5em;
+}
+
+/* Ink-centering trim + its mandatory descender allowance, same as .wt-tab-label
+   (see 30-tabs.css for why `ex`, why the padding is not optional, and why the
+   pair is @supports-gated rather than left to fall back). */
+@supports (text-box: trim-both ex alphabetic) {
+  :where(.wt-root) .wt-switcher-label {
+    text-box: trim-both ex alphabetic;
+    padding-block: 0.5em;
+  }
 }
 
 /* Keyboard button: hidden until a keyboardToggle is wired; filled while the key
@@ -432,11 +437,16 @@
   overflow: hidden;
   text-overflow: ellipsis;
   white-space: nowrap;
-  /* Ink-centering trim + its mandatory descender allowance, same as
-     .wt-tab-label (see 30-tabs.css for why `ex` and why the padding is not
-     optional). */
-  text-box: trim-both ex alphabetic;
-  padding-block: 0.5em;
+}
+
+/* Ink-centering trim + its mandatory descender allowance, same as .wt-tab-label
+   (see 30-tabs.css for why `ex`, why the padding is not optional, and why the
+   pair is @supports-gated rather than left to fall back). */
+@supports (text-box: trim-both ex alphabetic) {
+  :where(.wt-root) .wt-switcher-row-label {
+    text-box: trim-both ex alphabetic;
+    padding-block: 0.5em;
+  }
 }
 
 /* The close sits flush at the row's right edge (no gap), vertically centered. */

package/css/page.css

@@ -39,6 +39,173 @@ body {
   touch-action: pan-x pan-y;
 }
 
+/* ===== The pre-JS loading overlay =====
+   ONE definition of the loading screen, owned here. Before this, the library
+   only PRESCRIBED it in scaffold/index.html and every full-page consumer carried
+   its own copy in an inline <style> — web-terminal-server's was byte-identical to
+   the scaffold's, web-terminal-kiro's had drifted (renamed keyframe, extra
+   states) — so the "one" loading screen existed three times and none of them
+   could be improved without editing three files.
+
+   Why it can live in a stylesheet at all, since the overlay's whole job is to be
+   on screen before the app is: a full-page host loads this bundle through a plain
+   render-blocking <link rel="stylesheet"> in <head>, so NOTHING paints until it
+   arrives. An inline copy buys no earlier paint. What an inline copy does buy is
+   the case where this stylesheet FAILS to load, which a consumer's own bootstrap
+   watchdog reports — so a consumer keeps a deliberately minimal inline fallback
+   for that failure surface only, not a second copy of everything below.
+
+   Consumer overrides work the same way the component tokens do, except simpler:
+   the overlay is the consumer's OWN element, so it sets the tokens on #loading in
+   its own CSS and needs no JS. web-terminal-kiro already did exactly this with
+   --accent before any of this was tokenised.
+
+   Selected by CLASS, never by the consumer's `id`: the library owns .wt-loading*
+   and must not reach into a host document's own identifiers (the same
+   no-element-id-contract rule the kernel follows for the terminal subtree), and
+   an unnamespaced `.bar` in a host page would collide with anything. */
+.wt-loading {
+  /* The overlay's accent: the bar and the status text derive from it, so one
+     override recolors the whole screen. Defaults to the component --accent
+     (00-tokens.css), restated as a literal because the component tokens are
+     scoped to .wt-root and the overlay is deliberately OUTSIDE it. */
+  --wt-loading-accent: oklch(72% 0.15 250deg);
+  --wt-loading-bg: #000;
+  --wt-loading-bar-inline-size: min(220px, 62vw);
+  --wt-loading-bar-block-size: 5px;
+  /* Symmetric ease-in-out-cubic, deliberately NOT one of the component easing
+     tokens: those are all asymmetric (they settle at one end), which reads as a
+     stutter on a looping indeterminate sweep. */
+  --wt-loading-sweep-easing: cubic-bezier(0.65, 0, 0.35, 1);
+  --wt-loading-sweep-duration: 1.5s;
+
+  position: fixed;
+  inset: 0;
+  z-index: 200;
+  display: flex;
+  /* Column, so the status line the kernel writes after a few seconds sits under
+     the bar instead of beside it. It is the only child that can appear, and it
+     is absent on a fast boot, so the column costs nothing when unused. */
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 1rem;
+  padding: max(1rem, env(safe-area-inset-top)) max(1rem, env(safe-area-inset-right))
+    max(1rem, env(safe-area-inset-bottom)) max(1rem, env(safe-area-inset-left));
+  background: var(--wt-loading-bg);
+  color: var(--wt-loading-accent);
+  font-family:
+    system-ui,
+    -apple-system,
+    sans-serif;
+  text-align: center;
+  transition: opacity 0.3s cubic-bezier(0.4, 0, 1, 1);
+}
+
+/* `fade` (not a wt- name) is the state class the kernel's fadeOutOverlay has always
+   added; it stays as-is so a consumer's own watchdog guards that read it keep
+   working. Compounding it with .wt-loading is what keeps a generic name safe. */
+.wt-loading.fade {
+  opacity: 0;
+  /* The kernel removes the node on transitionend (with a 1.5s fallback); until
+     then this invisible full-viewport box must not swallow the first
+     tap-to-focus on the freshly rendered terminal. */
+  pointer-events: none;
+}
+
+.wt-loading-bar {
+  position: relative;
+  inline-size: var(--wt-loading-bar-inline-size);
+  block-size: var(--wt-loading-bar-block-size);
+  overflow: hidden;
+  border-radius: 999px;
+  background: color-mix(in oklch, currentcolor 16%, transparent);
+  /* The bar is the fixed element of the screen; a status line appearing below it
+     must not shove it off centre, so it never shrinks. */
+  flex: none;
+}
+
+.wt-loading-bar::before {
+  content: "";
+  position: absolute;
+  inset-block: 0;
+  inline-size: 42%;
+  border-radius: inherit;
+  background: linear-gradient(
+    90deg,
+    transparent,
+    currentcolor 28%,
+    color-mix(in oklch, currentcolor, #fff 45%) 50%,
+    currentcolor 72%,
+    transparent
+  );
+  filter: drop-shadow(0 0 4px color-mix(in oklch, currentcolor 55%, transparent));
+  animation: wt-loading-slide var(--wt-loading-sweep-duration) var(--wt-loading-sweep-easing)
+    infinite;
+}
+
+/* The progressive status line (kernel/loading-status.ts writes it; see that
+   module for WHY it is delayed and why the rotating half is aria-hidden).
+   Hidden until it has something to say, so a fast boot shows the bar alone. */
+.wt-loading-text:empty {
+  display: none;
+}
+
+.wt-loading-text {
+  margin: 0;
+  max-inline-size: 34rem;
+  color: color-mix(in oklch, currentcolor, #fff 25%);
+  font-size: 0.9375rem;
+  line-height: 1.4;
+  /* Fade each message in rather than snapping it: the whole point of the delayed
+     and rotating text is to read as a system that is alive, and a hard swap reads
+     as a glitch. */
+  transition: opacity 0.4s cubic-bezier(0.4, 0, 1, 1);
+}
+
+.wt-loading-text.wt-loading-text-out {
+  opacity: 0;
+}
+
+@keyframes wt-loading-slide {
+  0% {
+    transform: translateX(-110%);
+  }
+  100% {
+    transform: translateX(250%);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .wt-loading {
+    transition-duration: 0.01s;
+  }
+
+  /* A travelling sweep is the motion a reduced-motion user asked not to see, but
+     the screen still has to read as busy — so the bar becomes a slow symmetric
+     pulse of the whole track instead of a moving highlight. */
+  .wt-loading-bar::before {
+    inline-size: 100%;
+    background: currentcolor;
+    filter: none;
+    animation: wt-loading-pulse 2s ease-in-out infinite;
+  }
+
+  .wt-loading-text {
+    transition-duration: 0.01s;
+  }
+}
+
+@keyframes wt-loading-pulse {
+  0%,
+  100% {
+    opacity: 0.35;
+  }
+  50% {
+    opacity: 1;
+  }
+}
+
 /* ===== Fonts =====
    The terminal web font, served by the full-page host at /vendor/fonts (both
    web-terminal-server and web-terminal-kiro ship these files there; see their

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@cplieger/web-terminal-ui",
-  "version": "4.8.1",
+  "version": "5.0.1",
   "type": "module",
   "description": "Reference touch-first browser UI for @cplieger/web-terminal-engine: a composable kernel + feature modules (tabs, activity monitor, mobile toolbar, context menu, IME, predictive echo, viewport handling) and CSS. One createTerminal() call.",
   "license": "GPL-3.0-or-later",
   "exports": {
     ".": "./src/index.ts",
+    "./startup-copy": "./src/kernel/startup-copy.ts",
     "./presets": "./src/presets.ts",
     "./presets/single": "./src/presets/single.ts",
     "./presets/touch": "./src/presets/touch.ts",

package/scaffold/index.html

@@ -12,26 +12,25 @@
      set). An embedder serves a per-preset manifest (css/MANIFEST.single/
      .touch/.tabbed) instead and passes layout: "container". -->
 <link rel="stylesheet" href="/style.css">
-<!-- [html-validate-disable-next no-style-tag -- critical CSS for instant loading indicator] -->
-<style>
-#loading{position:fixed;inset:0;z-index:200;display:flex;align-items:center;justify-content:center;background:#000;color:var(--accent,#6ea8ff);transition:opacity .3s ease}
-#loading.fade{opacity:0}
-#loading .bar{position:relative;inline-size:min(220px,62vw);block-size:5px;overflow:hidden;border-radius:999px;background:color-mix(in oklch,currentColor 16%,transparent)}
-#loading .bar::before{content:"";position:absolute;inset-block:0;inline-size:42%;border-radius:inherit;background:linear-gradient(90deg,transparent,currentColor 28%,color-mix(in oklch,currentColor,#fff 45%) 50%,currentColor 72%,transparent);filter:drop-shadow(0 0 4px color-mix(in oklch,currentColor 55%,transparent));animation:wt-loading-slide 1.5s cubic-bezier(.65,0,.35,1) infinite}
-@keyframes wt-loading-slide{0%{transform:translateX(-110%)}100%{transform:translateX(250%)}}
-@keyframes wt-loading-pulse{0%,100%{opacity:1}50%{opacity:.55}}
-/* Reduced motion: no translation sweep (the vestibular-trigger class). The bar
-   becomes a full-width solid fill whose only animation is a gentle opacity
-   pulse — liveness stays signaled, nothing moves. */
-@media (prefers-reduced-motion:reduce){#loading .bar::before{inline-size:100%;background:currentColor;filter:none;animation:wt-loading-pulse 2s ease-in-out infinite}}
-</style>
+<!-- No critical CSS for the loading overlay: css/page.css owns .wt-loading and
+     arrives with /style.css above, which is render-blocking, so nothing paints
+     before it either way. A consumer that also wants a failure surface for the
+     case where /style.css itself fails to load adds its own minimal inline block
+     for that (web-terminal-kiro does); a bare host does not need one. -->
 </head>
 <body>
 <!-- createTerminal() builds the entire terminal UI inside this single root
      element. The loading overlay is a sibling (not a child of the root) so it is
-     never cleared; it is faded out once the first frame renders. -->
+     never cleared; it is faded out once the first frame renders.
+     The overlay is styled by css/page.css through the wt-loading* CLASSES, not
+     by its id — recolor it by setting the tokens (--wt-loading-accent,
+     --wt-loading-bg, ...) on this element in your own CSS. role="status" is
+     load-bearing: the kernel writes a progressive status line into it if startup
+     drags on, and that is the channel a screen reader reads. -->
 <div id="terminal"></div>
-<div id="loading" role="status" aria-label="Loading"><div class="bar" aria-hidden="true"></div></div>
+<div id="loading" class="wt-loading" role="status" aria-label="Loading">
+  <div class="wt-loading-bar" aria-hidden="true"></div>
+</div>
 <!-- Deployment-specific: the importmap resolves the bare package specifiers to
      the compiled JS your build emits. Adjust the paths to your build layout. -->
 <script type="importmap">
@@ -46,7 +45,14 @@
 <script type="module">
   import { createTerminal } from "@cplieger/web-terminal-ui";
   import { presetTabbed } from "@cplieger/web-terminal-ui/presets";
-  createTerminal(document.getElementById("terminal"), { features: presetTabbed(), loading: document.getElementById("loading") });
+  // The root is passed as a SELECTOR and the preset as a FUNCTION, and both
+  // matter: createTerminal resolves the selector and calls the preset inside its
+  // own failure boundary, so a missing root element or a preset that throws
+  // renders the library's "Terminal failed to start" surface and lowers the
+  // overlay. Resolving the element here instead (and calling presetTabbed() as
+  // an argument) moves both failures OUTSIDE that boundary, where the only
+  // outcome is a page stuck on the spinner and an error in the console.
+  createTerminal("#terminal", { features: presetTabbed, loading: document.getElementById("loading") });
 </script>
 </body>
 </html>

package/src/features/tabs/index.ts

@@ -214,6 +214,14 @@ async function createSessionHonouringRetry(
         ctx.toast(`${waiting}; retrying`, 8000);
         ctx.announce(`${waiting}; retrying`);
       }
+      // Separate from the throttled pair above, and unthrottled: this writes the
+      // reason onto the loading OVERLAY, which is the only surface a user can
+      // actually see before the first frame -- the toast and the banner both live
+      // inside .wt-root and paint under it. It replaces text in place rather than
+      // stacking notifications, so there is no storm to throttle, and repeating
+      // the same string is idempotent. This is what turns the black screen of a
+      // twenty-minute tools install into a screen that says why it is waiting.
+      ctx.loadingReason(`${err.serverMessage ?? "Server is not ready yet"} — retrying…`);
       await new Promise((resolve) => {
         window.setTimeout(resolve, err.retryAfterMs ?? CREATE_RETRY_FALLBACK_MS);
       });
@@ -2437,8 +2445,8 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
           void close_(activeId);
         }
       });
-      // Dismiss the tab context menu on an outside click, on Escape, and on
-      // scroll (it is anchored to a viewport point, so a scroll would detach it).
+      // Dismiss the tab context menu on an outside click, on Escape, and on a
+      // scroll of the strip itself (which moves the chip the menu is anchored to).
       const onDocClickMenu = (): void => {
         // The trailing click of the long-press that just opened the menu is that
         // gesture's own release, not a click-away.
@@ -2458,8 +2466,23 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
         }
       };
       document.addEventListener("contextmenu", onDocContextMenu);
-      const onScrollMenu = (): void => {
-        hideTabMenu();
+      // Only a scroll that moves the menu's ANCHOR dismisses it, which is the
+      // strip's own horizontal scroller and nothing else: the menu is placed
+      // root-relative (menu-position.ts rebases onto the offsetParent), so any
+      // scroll that moves .wt-root moves the menu with it, and the terminal's
+      // scroller does not move the chip at all.
+      //
+      // The target check is load-bearing, not a micro-optimization. This listener
+      // is capture-phase on window, so it sees EVERY scroll in the document —
+      // including the terminal surface auto-scrolling to the bottom on each chunk
+      // of output. Without the check, an agent printing into the TUI closed the
+      // tab menu within a frame of it opening, which is unusable on exactly the
+      // screen the menu exists for (a busy multi-agent strip).
+      const onScrollMenu = (e: Event): void => {
+        const target = e.target;
+        if (target instanceof Element && target.closest(".wt-tab-scroll")) {
+          hideTabMenu();
+        }
       };
       window.addEventListener("scroll", onScrollMenu, true);
       const offMenuKey = ctx.registerKeydown((ev) => {

package/src/index.ts

@@ -12,6 +12,7 @@
 // their own DOM.
 
 export { createTerminal } from "./kernel/kernel.js";
+export { STARTUP_FAILURE_COPY } from "./kernel/startup-copy.js";
 export type {
   CreateTerminalOptions,
   TerminalStartupFailure,

package/src/kernel/kernel.ts

@@ -28,6 +28,8 @@ import { createBus } from "./bus.js";
 import { createRegions } from "./regions.js";
 import { createAnnouncer, createTablist } from "./a11y.js";
 import { createConnState } from "./conn-state.js";
+import { STARTUP_FAILURE_COPY } from "./startup-copy.js";
+import { attachLoadingStatus, DEFAULT_LOADING_MESSAGES } from "./loading-status.js";
 import type {
   CreateTerminalOptions,
   FeatureInstance,
@@ -111,7 +113,11 @@ function fadeOutOverlay(ld: HTMLElement | undefined): void {
  *  implementation of this surface, shared by the async `feature-setup` phase and
  *  the synchronous `kernel-init` phase, so the two can never drift apart. It
  *  depends on nothing but its two arguments. */
-function renderFatalStartupInto(root: HTMLElement, layoutMode: "viewport" | "container"): void {
+function renderFatalStartupInto(
+  root: HTMLElement,
+  layoutMode: "viewport" | "container",
+  message: string = STARTUP_FAILURE_COPY.message,
+): void {
   const surface = document.createElement("section");
   surface.className = "wt-fatal";
   surface.setAttribute("role", "alertdialog");
@@ -129,19 +135,19 @@ function renderFatalStartupInto(root: HTMLElement, layoutMode: "viewport" | "con
   const title = document.createElement("h2");
   title.id = "wt-fatal-title";
   title.className = "wt-fatal-title";
-  title.textContent = "Terminal failed to start";
-  const message = document.createElement("p");
-  message.id = "wt-fatal-message";
-  message.className = "wt-fatal-message";
-  message.textContent = "A required interface could not be loaded. Reload the page to try again.";
+  title.textContent = STARTUP_FAILURE_COPY.title;
+  const messageEl = document.createElement("p");
+  messageEl.id = "wt-fatal-message";
+  messageEl.className = "wt-fatal-message";
+  messageEl.textContent = message;
   const reloadButton = document.createElement("button");
   reloadButton.className = "wt-btn wt-fatal-reload";
   reloadButton.type = "button";
-  reloadButton.textContent = "Reload page";
+  reloadButton.textContent = STARTUP_FAILURE_COPY.reloadLabel;
   reloadButton.addEventListener("click", () => {
     window.location.reload();
   });
-  card.append(title, message, reloadButton);
+  card.append(title, messageEl, reloadButton);
   surface.appendChild(card);
   root.replaceChildren(surface);
 
@@ -153,10 +159,13 @@ function renderFatalStartupInto(root: HTMLElement, layoutMode: "viewport" | "con
 
 /** Build the terminal. See createTerminal, which wraps this to give a
  *  SYNCHRONOUS failure the same recovery surface an async one already gets. */
-function buildTerminal(root: HTMLElement, opts: CreateTerminalOptions = {}): TerminalHandle {
+function buildTerminal(
+  root: HTMLElement,
+  opts: CreateTerminalOptions,
+  featureList: readonly TerminalFeature<unknown>[],
+): TerminalHandle {
   const wsPath = opts.wsPath ?? DEFAULT_WS_PATH;
   const fontReady = opts.fontReady ?? DEFAULT_FONT_READY;
-  const featureList = opts.features ?? [];
   // At most one feature owns session selection (fail fast, before any DOM
   // work): the kernel drives the first connect through its registration.
   const owners = featureList.filter((f) => f.sessionOwner !== undefined);
@@ -325,7 +334,16 @@ function buildTerminal(root: HTMLElement, opts: CreateTerminalOptions = {}): Ter
   let fontsLoaded = false;
   let wsOpen = false;
   let overlayDismissed = false;
+  // Progressive status text on the consumer's overlay. Attached unconditionally
+  // (inert when no overlay was supplied) and torn down by the same function that
+  // lowers the overlay, so there is exactly one place where the loading screen's
+  // life ends and no timer can outlive the thing it was writing into.
+  const loadingStatus = attachLoadingStatus(opts.loading, {
+    ...DEFAULT_LOADING_MESSAGES,
+    ...opts.loadingMessages,
+  });
   function dismissLoadingOverlay(): void {
+    loadingStatus.stop();
     const ld = opts.loading;
     if (!ld || overlayDismissed) {
       return;
@@ -844,6 +862,13 @@ function buildTerminal(root: HTMLElement, opts: CreateTerminalOptions = {}): Ter
       announce: (message, politeness) => {
         announcer.announce(message, politeness);
       },
+      loadingReason: (message) => {
+        // No overlayDismissed guard needed: loadingStatus.stop() runs in
+        // dismissLoadingOverlay and every method is inert afterwards, so the
+        // "a late retry cannot resurrect the overlay" contract holds in ONE
+        // place rather than at each caller.
+        loadingStatus.reason(message);
+      },
       tablist: () => tablistController,
       layout: () => ({
         narrow: isNarrow(),
@@ -945,7 +970,8 @@ function buildTerminal(root: HTMLElement, opts: CreateTerminalOptions = {}): Ter
 
     let handled = false;
     try {
-      handled = opts.onFatalError?.({ phase: "feature-setup", feature, cause }) === true;
+      handled =
+        opts.onFatalError?.({ phase: "feature-setup", feature, cause, surface: root }) === true;
     } catch (handlerErr) {
       console.error("web-terminal-ui: onFatalError handler failed", handlerErr);
     }
@@ -1099,35 +1125,113 @@ function buildTerminal(root: HTMLElement, opts: CreateTerminalOptions = {}): Ter
  *  as before, only now against a page that is no longer stuck on a spinner. A
  *  handler returning `true` suppresses the built-in surface, same contract as the
  *  async phase. */
+/** Resolve the mount target. A selector is looked up here, INSIDE
+ *  createTerminal's try, which is the whole point: a consumer that passed
+ *  `document.getElementById("terminal")` had to null-check it first (tsc forces
+ *  that), and the only thing it could do in the null branch was hand-build a
+ *  startup-failure surface this library already owns. Taking the selector moves
+ *  that failure inside the boundary and deletes the consumer's branch.
+ *
+ *  An element is still accepted, because an embedder that CREATED the element
+ *  already holds a non-null reference and asking it to invent a selector for its
+ *  own div would be worse. The trap was never "passing an element", it was
+ *  "passing the result of a lookup". */
+function resolveRoot(target: HTMLElement | string): HTMLElement {
+  if (typeof target !== "string") {
+    return target;
+  }
+  const found = document.querySelector(target);
+  if (found === null) {
+    throw new Error(`web-terminal-ui: no element matches the mount selector ${target}`);
+  }
+  if (!(found instanceof HTMLElement)) {
+    // An SVG or MathML element can match a selector but cannot host the terminal
+    // (no style/classList contract this kernel relies on). Fail with the reason
+    // rather than crashing later on a missing property.
+    throw new Error(`web-terminal-ui: the mount selector ${target} matched a non-HTML element`);
+  }
+  return found;
+}
+
+/** Build the feature list. `features` is a FUNCTION so a preset that throws does
+ *  so inside createTerminal's try. As an eagerly-evaluated array argument
+ *  (`features: presetTabbed()`) the throw happened at the CALL SITE, before this
+ *  function's boundary existed, which is why a consumer had to wrap the preset
+ *  call in its own try/catch and render its own surface. One character of
+ *  laziness moves that failure inside. */
+function resolveFeatures(
+  features: CreateTerminalOptions["features"],
+): readonly TerminalFeature<unknown>[] {
+  return features === undefined ? [] : features();
+}
+
+/** Create the host element the recovery surface uses when the mount target could
+ *  not be resolved at all.
+ *
+ *  It is a NEW element appended to the body, never the body itself: .wt-root
+ *  carries the token defaults, box-sizing, color-scheme and scrollbar treatment,
+ *  and .wt-viewport carries `position: fixed; inset: 0` — stamping those on a
+ *  host application's own body would reformat a page that is otherwise perfectly
+ *  healthy. A dedicated element gets the styling boundary the surface needs
+ *  without touching anything the consumer owns. */
+function createFallbackHost(): HTMLElement {
+  const host = document.createElement("div");
+  host.className = "wt-root wt-viewport";
+  document.body.appendChild(host);
+  return host;
+}
+
 export function createTerminal(
-  root: HTMLElement,
+  target: HTMLElement | string,
   opts: CreateTerminalOptions = {},
 ): TerminalHandle {
+  const layoutMode = opts.layout ?? "viewport";
+  // Declared outside the try so the catch can tell "we never resolved a root"
+  // from "we had one and the build failed". The old code read the root straight
+  // from its parameter, so a caller who passed a null root (reachable from any
+  // untyped call site — an inline <script type="module"> never sees tsc) threw a
+  // SECOND error out of the catch itself, losing the real cause and rendering no
+  // surface at all. There is no null root to pass now, and the unresolved case
+  // has an explicit branch below.
+  let root: HTMLElement | undefined;
   try {
-    return buildTerminal(root, opts);
+    root = resolveRoot(target);
+    return buildTerminal(root, opts, resolveFeatures(opts.features));
   } catch (cause) {
-    const layoutMode = opts.layout ?? "viewport";
-    // Stamp the boundary classes before rendering. buildTerminal normally does
-    // this early, but a throw can precede it (the multiple-session-owner guard
-    // fires before any DOM work by design), and every .wt-fatal rule is scoped
-    // :where(.wt-root) -- so without this the recovery surface would render
-    // completely unstyled exactly when it matters most. Idempotent when
-    // buildTerminal already stamped them.
-    root.classList.add("wt-root", layoutMode === "container" ? "wt-container" : "wt-viewport");
+    // Container mode declines the fallback on purpose. An embedded terminal is
+    // one panel inside someone else's working application; if its mount target
+    // is missing, claiming the viewport to say so would break a page that is
+    // otherwise fine — strictly worse than the host app reporting the failure in
+    // the space it owns. The failure is still delivered and still rethrown, so an
+    // embedder is informed, just not overruled. A full-page consumer is the
+    // opposite case: the page IS the terminal, so a blank page with nothing but a
+    // console error is the worst outcome available.
+    const surface = root ?? (layoutMode === "viewport" ? createFallbackHost() : undefined);
+    if (surface !== undefined) {
+      // Stamp the boundary classes before rendering. buildTerminal normally does
+      // this early, but a throw can precede it (the multiple-session-owner guard
+      // fires before any DOM work by design), and every .wt-fatal rule is scoped
+      // :where(.wt-root) -- so without this the recovery surface would render
+      // completely unstyled exactly when it matters most. Idempotent when
+      // buildTerminal already stamped them, and when createFallbackHost did.
+      surface.classList.add("wt-root", layoutMode === "container" ? "wt-container" : "wt-viewport");
+    }
     // The overlay must come down even though nothing was built: it is the
     // consumer's pre-JS spinner, and leaving it up hides the surface below it.
+    // This runs even when no surface is rendered — a spinner over an embedder's
+    // broken panel is a lie either way.
     fadeOutOverlay(opts.loading);
 
     let handled = false;
     try {
-      handled = opts.onFatalError?.({ phase: "kernel-init", cause }) === true;
+      handled = opts.onFatalError?.({ phase: "kernel-init", cause, surface }) === true;
     } catch (handlerErr) {
       // Same posture as the async phase: a reporting failure must not leave the
       // page blank, so fall through to the built-in surface.
       console.error("web-terminal-ui: onFatalError handler failed", handlerErr);
     }
-    if (!handled) {
-      renderFatalStartupInto(root, layoutMode);
+    if (!handled && surface !== undefined) {
+      renderFatalStartupInto(surface, layoutMode);
     }
     throw cause;
   }

package/src/kernel/loading-status.ts

@@ -0,0 +1,236 @@
+// Progressive status text for the consumer's pre-JS loading overlay.
+//
+// The problem this solves: the overlay is an opaque full-viewport box the
+// consumer paints before any JS runs, and the kernel only lowers it once the
+// first terminal frame arrives. Every piece of terminal chrome the library could
+// speak through -- the toast layer, the connection banner -- lives inside
+// .wt-root and paints UNDER that overlay, so for as long as startup takes, the
+// library can say nothing a sighted user can see. On a fast boot that does not
+// matter; the overlay is gone in well under a second. On web-terminal-kiro's
+// first boot it matters a lot: the server answers session creation with 503
+// "tools installing" while its tool engine installs, the session owner retries
+// for up to twenty minutes, and the user watched a black screen with an
+// unlabelled sweep bar the whole time, unable to tell a server that is
+// deliberately waiting from an app that has hung.
+//
+// The design, in order of what a user experiences:
+//
+//   1. SILENCE FIRST. Nothing is written for the first few seconds. A message
+//      that flashes up and vanishes on a normal boot is worse than no message,
+//      and most boots never reach the first threshold at all.
+//   2. ONE calm line once the wait is real ("Loading terminal...").
+//   3. After a minute, ROTATING reassurance. A single sentence frozen on screen
+//      for nineteen more minutes reads exactly as hung as no sentence -- the
+//      whole point is to show the system is still alive, so the line changes.
+//   4. A LIVE REASON supersedes all of the above the moment one is known. The
+//      truthful wording for "tools installing" lives on the server, arrives in
+//      the 503 body, and is pushed in by the session owner; it is strictly more
+//      useful than anything this module could guess.
+//
+// Accessibility, and the trap that shapes the DOM here: the overlay is a
+// role="status" live region, so anything written into it is ANNOUNCED. Rotating
+// four messages every twenty seconds for twenty minutes would interrupt a screen
+// reader roughly sixty times to say nothing new. So the visible line is
+// aria-hidden and a separate off-screen live line carries only MEANINGFUL
+// changes -- the first threshold, and each new live reason. Sighted users get
+// motion; assistive tech gets information; neither gets the other's noise.
+
+/** Wording for the progressive loading status. Every field has a library
+ *  default; a consumer overrides only what it wants to reword. */
+export interface LoadingMessages {
+  /** Shown once the wait passes the first threshold. */
+  readonly initial: string;
+  /** Rotated, in order, once the wait passes the second threshold. Keep them
+   *  interchangeable: a user joins the rotation at an arbitrary point. */
+  readonly waiting: readonly string[];
+}
+
+export const DEFAULT_LOADING_MESSAGES: LoadingMessages = {
+  initial: "Loading terminal…",
+  waiting: [
+    "Still working — this can take a while on first start.",
+    "Still working — preparing the environment.",
+    "Still working — almost there.",
+    "Still working — thanks for your patience.",
+  ],
+};
+
+/** Delay before the first line appears. Long enough that a normal boot finishes
+ *  in silence (the overlay is typically gone inside a second), short enough that
+ *  a user who is about to start wondering gets an answer first. */
+const INITIAL_DELAY_MS = 5000;
+/** When the rotation takes over from the single initial line. */
+const WAITING_AFTER_MS = 60000;
+/** How often the rotation advances. Slow enough not to read as nervous chatter,
+ *  brisk enough that a glance a few seconds later shows something changed. */
+const ROTATE_EVERY_MS = 20000;
+/** The fade-out half of a message swap; must stay under ROTATE_EVERY_MS and
+ *  match the .wt-loading-text transition in css/page.css. */
+const SWAP_FADE_MS = 400;
+
+/** Controls the status line on one overlay. Every method is safe to call after
+ *  stop(), so the kernel never has to sequence teardown against a pending
+ *  timer. */
+export interface LoadingStatus {
+  /** Replace the wording with a known, specific reason and keep it until the
+   *  reason CHANGES. Cancels the rotation: a real reason outranks reassurance,
+   *  and alternating between them would be incoherent. Safe to call on every
+   *  tick of a retry loop -- an identical string is a no-op, so the announced
+   *  line is not re-read to a screen reader every few seconds. */
+  reason(text: string): void;
+  /** Cancel every timer and remove the text nodes. Idempotent. */
+  stop(): void;
+}
+
+/** Attach a progressive status line to `overlay`.
+ *
+ *  `overlay` is the consumer's element, so this only ever APPENDS two children
+ *  and removes them again on stop(); it never touches the overlay's own markup,
+ *  attributes or classes. A consumer that supplies no overlay gets an inert
+ *  controller, so callers need no null handling. */
+export function attachLoadingStatus(
+  overlay: HTMLElement | undefined,
+  messages: LoadingMessages = DEFAULT_LOADING_MESSAGES,
+  doc: Document = document,
+): LoadingStatus {
+  if (!overlay) {
+    return { reason: () => undefined, stop: () => undefined };
+  }
+
+  // The visible line. aria-hidden because the overlay is a live region and this
+  // element's whole job is to CHANGE often; the live line below is what speaks.
+  const visible = doc.createElement("p");
+  visible.className = "wt-loading-text";
+  visible.setAttribute("aria-hidden", "true");
+
+  // The announced line. Off-screen by the same clip technique the kernel
+  // announcer uses, and written only on meaningful transitions.
+  const live = doc.createElement("p");
+  live.className = "wt-loading-live";
+  Object.assign(live.style, {
+    position: "absolute",
+    inlineSize: "1px",
+    blockSize: "1px",
+    margin: "-1px",
+    padding: "0",
+    overflow: "hidden",
+    clipPath: "inset(50%)",
+    whiteSpace: "nowrap",
+    border: "0",
+  });
+
+  overlay.append(visible, live);
+
+  const timers: number[] = [];
+  let rotation: number | undefined;
+  let rotateIndex = 0;
+  let stopped = false;
+  let pinned = false; // a live reason has superseded the scripted wording
+  let current = ""; // last reason shown, so a repeat call is a no-op
+
+  const later = (fn: () => void, ms: number): void => {
+    timers.push(window.setTimeout(fn, ms));
+  };
+
+  // Swap the visible text through a fade so a change reads as deliberate rather
+  // than as a glitch. The first write skips the fade (there is nothing to fade
+  // out) so the line does not arrive half-transparent.
+  const show = (text: string): void => {
+    if (stopped) {
+      return;
+    }
+    // First write has nothing to fade out, so it must not arrive half-transparent.
+    if (visible.textContent === "") {
+      visible.textContent = text;
+      return;
+    }
+    visible.classList.add("wt-loading-text-out");
+    later(() => {
+      if (stopped) {
+        return;
+      }
+      visible.textContent = text;
+      visible.classList.remove("wt-loading-text-out");
+    }, SWAP_FADE_MS);
+  };
+
+  const announce = (text: string): void => {
+    if (!stopped) {
+      live.textContent = text;
+    }
+  };
+
+  later(() => {
+    if (pinned) {
+      return;
+    }
+    show(messages.initial);
+    announce(messages.initial);
+  }, INITIAL_DELAY_MS);
+
+  later(() => {
+    const waiting = messages.waiting;
+    if (pinned || stopped || waiting.length === 0) {
+      return;
+    }
+    // showAt reads through an undefined check rather than an index assertion:
+    // under noUncheckedIndexedAccess every element read is `string | undefined`,
+    // and the check is the only form both the assertion-style and
+    // no-non-null-assertion lint rules accept.
+    const showAt = (i: number): void => {
+      const text = waiting[i];
+      if (text !== undefined) {
+        show(text);
+      }
+    };
+    // Deliberately NOT announced, now or on any rotation: these carry no
+    // information a screen-reader user has not already been told once.
+    showAt(0);
+    rotation = window.setInterval(() => {
+      // No pinned/stopped guard here: both reason() and stop() clear this
+      // interval, so a tick cannot reach this line after either. The guard that
+      // matters is the `pinned` check on the ENCLOSING timer above, because the
+      // real production sequence puts reason() FIRST -- the server refuses
+      // session creation within a second or two, long before this 60s threshold
+      // -- and without it the rotation would start late and overwrite the
+      // server's own explanation with generic reassurance.
+      rotateIndex = (rotateIndex + 1) % waiting.length;
+      showAt(rotateIndex);
+    }, ROTATE_EVERY_MS);
+  }, WAITING_AFTER_MS);
+
+  return {
+    reason(text: string): void {
+      // Idempotent by text, and that is load-bearing rather than an
+      // optimisation: the natural caller is a retry loop that knows the reason
+      // on every tick, and re-writing the announced line would re-announce the
+      // same sentence to a screen reader every few seconds for the whole wait.
+      // Guarding here means a caller may call this as often as it likes.
+      if (stopped || text === "" || text === current) {
+        return;
+      }
+      current = text;
+      pinned = true;
+      if (rotation !== undefined) {
+        window.clearInterval(rotation);
+        rotation = undefined;
+      }
+      show(text);
+      announce(text);
+    },
+    stop(): void {
+      if (stopped) {
+        return;
+      }
+      stopped = true;
+      for (const t of timers) {
+        window.clearTimeout(t);
+      }
+      if (rotation !== undefined) {
+        window.clearInterval(rotation);
+      }
+      visible.remove();
+      live.remove();
+    },
+  };
+}

package/src/kernel/startup-copy.ts

@@ -0,0 +1,35 @@
+// The copy of the "terminal did not start" recovery surface, as DATA.
+//
+// Why this is a module of its own rather than string literals inside the
+// renderer: a full-page consumer needs the same words in a place no module can
+// reach. Its HTML carries an inline bootstrap watchdog whose entire job is to
+// report "the JS bundle never ran" -- a rung below `import`, by definition, or
+// it could not detect its own failure case. That watchdog cannot import these
+// strings at runtime, so a consumer's BUILD substitutes them into its HTML
+// instead, and the words survive as one declaration rather than three
+// hand-agreed copies (the pattern this replaced had web-terminal-kiro's app
+// code, its inline watchdog, and this library all restating them, kept in step
+// by comments asking the next reader to remember).
+//
+// This file therefore imports nothing and touches no DOM, so a Node build script
+// can read it without loading the kernel. It is exported at the package root and
+// at the "./startup-copy" subpath for exactly that use.
+
+/** The words the recovery surface shows, whichever startup rung failed.
+ *
+ *  A user cannot tell these failures apart and does not need to: the bundle not
+ *  loading, the mount target not existing, and a feature constructor throwing
+ *  all look like "I opened this and there is no terminal", and reloading is what
+ *  they will try. So the title and the action label are deliberately identical
+ *  across every rung; only the diagnostic detail differs, and that belongs in a
+ *  log or a consumer-supplied message, not in the headline.
+ *
+ *  `message` is the generic body the library uses when it has nothing more
+ *  specific. A consumer with a precise cause (its own bootstrap watchdog knows a
+ *  stylesheet failed) should say so instead -- it is strictly more useful than
+ *  this text -- while still taking `title` and `reloadLabel` from here. */
+export const STARTUP_FAILURE_COPY = {
+  title: "Terminal failed to start",
+  message: "A required interface could not be loaded. Reload the page to try again.",
+  reloadLabel: "Reload page",
+} as const;

package/src/kernel/types.ts

@@ -7,6 +7,7 @@
 // capability lookup) so a feature's public API is held by reference and a peer
 // reads it through a typed token.
 
+import type { LoadingMessages } from "./loading-status.js";
 import type { ScreenMessage, ModesMessage, LineStore } from "@cplieger/web-terminal-engine";
 
 /** Cancels a subscription or registration. Idempotent by convention. */
@@ -220,6 +221,19 @@ export interface TerminalContext {
   /** Announce a message on the single kernel-owned polite (or assertive) live
    *  region, so features do not spawn competing aria-live regions. */
   announce(message: string, politeness?: "polite" | "assertive"): void;
+  /** Report WHY startup is still waiting, onto the consumer's loading overlay.
+   *
+   *  For the window before the first frame, when the overlay covers every
+   *  surface a feature could otherwise speak through: the toast layer and the
+   *  connection banner both live inside .wt-root and paint UNDER it, so a
+   *  feature that retries for minutes has no visible channel without this.
+   *  Supersedes the kernel's own scripted wording (and stops its rotation),
+   *  because a reason the SERVER gave is always better than a guess -- pass the
+   *  server's own message where there is one. Safe to call on every tick of a
+   *  retry loop: an unchanged message is a no-op, so a screen reader is not
+   *  re-read the same sentence every few seconds. Also a no-op once the overlay
+   *  has been dismissed, so a late retry cannot resurrect it. */
+  loadingReason(message: string): void;
   /** The kernel's tablist/tabpanel ARIA controller (used by tabs). */
   tablist(): TablistController;
 
@@ -318,19 +332,26 @@ export interface FeatureInstance<Api = void> {
 /** A fatal failure while createTerminal is starting up.
  *
  *  Two phases can fail, and both are delivered here so a consumer never has to
- *  hand-build its own startup-failure surface:
+ *  hand-build its own startup-failure surface. That sentence used to be
+ *  aspirational: resolving the mount target and constructing the feature list
+ *  both happened at the CALL SITE, outside this boundary, so a consumer really
+ *  did need its own surface for those two — and every consumer that built one
+ *  restated this library's copy and re-decided its focus and ARIA behavior.
+ *  createTerminal now takes a selector and a feature THUNK, which pulls both
+ *  failures inside, and the promise holds literally.
  *
- *  - `kernel-init`: a SYNCHRONOUS throw out of createTerminal (an invalid
- *    feature list, a DOM invariant, a feature constructor). The kernel renders
- *    the recovery surface and then RETHROWS, so a caller with its own handling
- *    still sees the error.
+ *  - `kernel-init`: a SYNCHRONOUS throw out of createTerminal (an unresolvable
+ *    mount selector, a throwing preset or feature constructor, an invalid
+ *    feature list, a DOM invariant). The kernel renders the recovery surface and
+ *    then RETHROWS, so a caller with its own handling still sees the error.
  *  - `feature-setup`: an async feature-composition failure. The kernel has
  *    already stopped the connection, released every listener and singleton,
  *    torn down completed features, and cleared the terminal root when it
  *    delivers this value. Nothing is rethrown; the failure is asynchronous.
  *
  *  Discriminate on `phase`: `feature-setup` names the offending feature,
- *  `kernel-init` has no feature to name because composition never began. */
+ *  `kernel-init` has no feature to name because composition never began, and
+ *  only `kernel-init` can carry an undefined `surface`. */
 export type TerminalStartupFailure =
   | {
       readonly phase: "feature-setup";
@@ -338,19 +359,41 @@ export type TerminalStartupFailure =
       readonly feature: string;
       /** The original thrown or rejected value. */
       readonly cause: unknown;
+      /** The element the built-in surface would fill — always the terminal root
+       *  in this phase, since the terminal had already mounted. */
+      readonly surface: HTMLElement;
     }
   | {
       readonly phase: "kernel-init";
       /** The original thrown value, rethrown to the caller after this returns. */
       readonly cause: unknown;
+      /** The element the built-in surface would fill, and the element a handler
+       *  claiming the surface (returning true) must render into. Usually the
+       *  resolved root — but when the MOUNT TARGET itself could not be resolved
+       *  there is no root, so in `viewport` layout this is a fresh full-viewport
+       *  element the kernel appended to the body, and in `container` layout it is
+       *  `undefined`: an embedded terminal is one panel in a host application, so
+       *  a missing mount target is reported and rethrown but never answered by
+       *  seizing the host's page. A handler that renders its own UI must
+       *  therefore check for undefined. */
+      readonly surface: HTMLElement | undefined;
     };
 
 /** Options for createTerminal. */
 export interface CreateTerminalOptions {
-  /** The feature list; omitted or empty means the bare kernel (no chrome).
-   *  Heterogeneous feature APIs are held as unknown here; a consumer reads a
-   *  specific feature's api off the feature value it holds. */
-  features?: readonly TerminalFeature<unknown>[];
+  /** The feature list, as a FUNCTION that produces it; omitted means the bare
+   *  kernel (no chrome). Heterogeneous feature APIs are held as unknown here; a
+   *  consumer reads a specific feature's api off the feature value it holds.
+   *
+   *  It is a function, not an array, so that a preset or feature constructor
+   *  that throws does so INSIDE createTerminal's failure boundary. Passed as an
+   *  array (`features: presetTabbed()`) the call was evaluated as an argument —
+   *  before createTerminal was entered — so the throw escaped the library
+   *  entirely and every consumer had to wrap the preset call in its own
+   *  try/catch and hand-build a recovery surface. Write `features:
+   *  presetTabbed` when the preset takes no arguments, or `features: () =>
+   *  presetTabbed({...})` when it does. */
+  features?: () => readonly TerminalFeature<unknown>[];
   /** How the terminal claims space (default "viewport").
    *  "viewport": the root becomes a fixed full-viewport box — the full-page
    *  product (web-terminal-server, web-terminal-kiro, the scaffold page).
@@ -363,8 +406,17 @@ export interface CreateTerminalOptions {
   wsPath?: string;
   /** CSS font shorthand awaited before the first resize. */
   fontReady?: string;
-  /** Optional pre-JS loading overlay the kernel fades out on first paint. */
+  /** Optional pre-JS loading overlay the kernel fades out on first paint. Give
+   *  it the `wt-loading` class and a `wt-loading-bar` child and css/page.css
+   *  styles it; the kernel also writes a progressive status line into it while
+   *  startup drags on (see kernel/loading-status.ts). */
   loading?: HTMLElement;
+  /** Reword the loading overlay's progressive status text. Partial: anything
+   *  omitted keeps the library default. The wording only ever appears on a SLOW
+   *  start (nothing is written for the first few seconds), so this is about what
+   *  a waiting user reads, not about branding the normal case. A live reason
+   *  pushed by a feature via `ctx.loadingReason` supersedes all of it. */
+  loadingMessages?: Partial<LoadingMessages>;
   /** Observe or replace the kernel's fatal feature-setup surface. Called only
    *  after the live terminal has been completely torn down and its root
    *  cleared. Return true after rendering a replacement recovery surface into