@cplieger/web-terminal-ui 4.3.1 → 4.5.0

package/README.md

@@ -128,31 +128,42 @@ are importable from `…/features/<name>` (`clipboard`, `context-menu`,
   keeps clean, label-only tabs. Requires a server that speaks the session API
   (`/api/sessions` and `/ws?session=`), such as `web-terminal-server`.
 - `presetAgentTabbed()` — the same feature set as `presetTabbed()` (activity
-  monitor included), but with `preferInputTitle`: each tab's label follows the
-  latest submitted line (persisted server-side and recovered on reload) and the
-  program's OSC 0/2 title is ignored — for an agent shell such as `web-terminal-kiro`
-  whose program emits a non-empty but useless OSC title. Its status dots
-  (idle / working / done / needs-input) come from the same activity monitor,
-  driven by the server's status SSE and its OSC-9 classifier.
+  monitor included), tuned for an agent shell such as `web-terminal-kiro`: with
+  `preferInputTitle`, each tab's label follows the latest submitted line
+  (persisted server-side and recovered on reload) and the program's non-empty
+  but useless OSC 0/2 title is ignored; and with `presumeReports`, the idle
+  activity dot shows from tab creation instead of waiting for the session's
+  first OSC 9;4 signal — every session is an agent, so there is nothing to
+  prove. Its status dots (idle / working / done / needs-input) come from the
+  same activity monitor, driven by the server's status SSE and its OSC-9
+  classifier.
 
 ### Options
 
-| 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.                                                                                                                                                                                                                           |
-| `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.                                                                                                                                                                                             |
-| `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 working and input rings derive from their own tokens). The library ships neutral defaults. |
+| 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.                                                                                                                                                                                                                           |
+| `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 after a fatal feature setup failure has stopped the connection, released the terminal runtime, and cleared the root. It receives `{ phase, feature, cause }`. Return `true` only after rendering replacement recovery UI into the root; otherwise the kernel shows its Reload page surface.                                                       |
+| `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 working and input rings derive from their own tokens). The library ships neutral defaults. |
 
 `createTerminal()` returns a handle: `focus()` re-focuses the terminal input
 (and opens the soft keyboard on touch); `send(bytes)` sends bytes to the active
 session through the kernel's sanitizing input funnel (the supported host path
 for a "type this command" affordance); `reset()` drops the local scrollback and
 screen without injecting keystrokes (send a redraw keystroke yourself if you
-want one — e.g. Ctrl+L); and `destroy()` tears every feature down and releases
-the kernel.
+want one, for example Ctrl+L); and `destroy()` tears every feature down and
+releases the kernel.
+
+If a feature's setup throws or rejects, the kernel stops the connection, tears
+down every completed feature and core listener, clears the broken subtree, and
+shows a reload surface. The surface is modal when the terminal owns the
+viewport and non-modal when it fills an embedded container. `onFatalError`
+receives the failure after cleanup; return `true` only when the host has rendered
+replacement recovery UI into the terminal root.
 
 ## What ships
 
@@ -183,7 +194,7 @@ Consumers that ship this UI:
 
 This project is built with care and follows security best practices, but it is intended for personal / self-hosted use. No guarantees of fitness for production environments. Use at your own risk.
 
-This project was built with AI-assisted tooling using [Claude Opus](https://www.anthropic.com/claude) and [Kiro](https://kiro.dev). The human maintainer defines architecture, supervises implementation, and makes all final decisions.
+This project was built with AI-assisted tooling using [Claude](https://claude.com), [GPT](https://openai.com), and [Kiro](https://kiro.dev). The human maintainer defines architecture, supervises implementation, and makes all final decisions.
 
 ## License
 

package/css/10-primitives.css

@@ -13,7 +13,8 @@
    motion is opt-in from one place). Cascade order is the manifest file order.
 
    Primitives are the building blocks every feature reuses: the transparent
-   layout regions, the 44px touch button, and the toast surface. */
+   layout regions, the 44px touch button, the toast surface, and the kernel's
+   fatal-startup recovery surface. */
 
 :where(.wt-root) .wt-region,
 :where(.wt-root) .wt-slot {
@@ -96,3 +97,63 @@
   display: block;
   opacity: 1;
 }
+
+/* ===== Fatal startup recovery =====
+   Feature setup is part of the kernel composition contract. If it fails, the
+   kernel removes the half-live terminal and fills only its own layout boundary
+   with this recovery surface. In container mode that leaves the host app
+   outside the terminal fully visible and interactive. */
+:where(.wt-root) .wt-fatal {
+  position: absolute;
+  inset: 0;
+  z-index: 100;
+  display: grid;
+  place-items: center;
+  overflow: auto;
+  padding: calc(var(--safe-top) + var(--sp-3)) var(--sp-3) calc(var(--safe-bottom) + var(--sp-3));
+  background: var(--bg);
+  color: var(--text);
+  font-family: var(--font-ui);
+  text-align: center;
+}
+
+:where(.wt-root) .wt-fatal-card {
+  inline-size: min(100%, 28rem);
+  padding: clamp(1.25rem, 5vi, 2rem);
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+}
+
+:where(.wt-root) .wt-fatal-title {
+  margin: 0;
+  color: var(--text);
+  font-size: clamp(1.25rem, 5vi, 1.5rem);
+  line-height: 1.2;
+}
+
+:where(.wt-root) .wt-fatal-message {
+  margin: var(--sp-3) 0 1.25rem;
+  color: color-mix(in oklch, var(--text), transparent 20%);
+  font-size: 0.9375rem;
+  line-height: 1.5;
+}
+
+:where(.wt-root) .wt-fatal-reload {
+  inline-size: fit-content;
+  padding-inline: 1rem;
+  background: var(--accent);
+  color: var(--bg);
+  font-weight: 600;
+}
+
+@media (hover: hover) {
+  :where(.wt-root) .wt-fatal-reload:hover {
+    background: color-mix(in oklch, var(--accent), var(--text) 12%);
+  }
+}
+
+:where(.wt-root) .wt-fatal-reload:active {
+  background: color-mix(in oklch, var(--accent), var(--bg) 12%);
+  transform: translateY(1px);
+}

package/css/30-tabs.css

@@ -357,8 +357,11 @@
    tabs feature adds .wt-reports to that dot (paintStatusDot). A program that
    emits no OSC 9 signal (a plain bash/sh) has no activity concept, so its tabs
    stay clean, label-only; a progress-reporting agent (kiro-cli, Claude Code)
-   lights up. The element stays in the DOM either way (JS sets data-status
-   regardless), so revealing it is a pure CSS switch. */
+   lights up. An agent-shell consumer can PRESUME the report instead (tabs'
+   presumeReports option, on in presetAgentTabbed): .wt-reports is then set
+   from tab creation, so the idle dot shows immediately rather than popping in
+   after the agent's first signal. The element stays in the DOM either way (JS
+   sets data-status regardless), so revealing it is a pure CSS switch. */
 :where(.wt-root) .wt-status-dot {
   display: none;
   width: 9px;
@@ -391,19 +394,43 @@
   border: 1.5px solid color-mix(in oklch, var(--text) 45%, transparent);
 }
 
-/* Agent working: solid pulsing dot (--status-working; pale lime by default —
-   its high lightness keeps it clear on every tab state) wearing the same 2px
-   ring as input, so the two agent-turn states share one silhouette: a live
-   turn pulses (dot + ring together), a turn blocked on the user is that same
-   silhouette frozen and recolored (input, below). Motion separates working
-   from input; the ring separates both from done's bare disc. Server-side this
-   is driven by the OSC 9;4 progress signal, so it tracks agent activity, not
-   the user typing at the prompt. */
+/* Agent working: two INDEPENDENTLY animated layers on one element make the
+   "alive" read (the status-badge "processing" idiom — Ant Design's processing
+   badge, the classic CSS live-indicator ripple): the solid disc keeps full
+   opacity and gently GLOWS (its colors brighten mid-beat), while a ::after
+   ring — born exactly on the static 2px ring — RIPPLES outward and dissolves,
+   re-emitted each cycle. The static ring itself never moves, so working keeps
+   input's exact rest silhouette (a live turn ripples; a turn blocked on the
+   user is that same silhouette frozen — see input below). Motion separates
+   working from input; the ring separates both from done's bare disc. The old
+   single-layer pulse faded disc + ring together (opacity on the element),
+   which read as a blink and coupled the layers — an element's 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"] {
+  position: relative;
   background: var(--status-working);
   border-color: var(--status-working);
   box-shadow: 0 0 0 2px color-mix(in srgb, var(--status-working) 40%, transparent);
-  animation: wt-pulse 1.2s ease-in-out infinite;
+  animation: wt-working-glow 1.2s ease-in-out infinite;
+}
+
+/* The ripple layer: at scale(1) its 2px border overlays the static ring's
+   9->13px band exactly (inset -2px), then the wave detaches, expanding and
+   fading. transform + opacity only, so it composites without repaints. 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.) */
+:where(.wt-root) .wt-status-dot[data-status="working"]::after {
+  content: "";
+  position: absolute;
+  inset: -2px;
+  border: 2px solid var(--status-working);
+  border-radius: 50%;
+  animation: wt-working-ripple 1.2s ease-in-out infinite;
 }
 
 /* Agent done / ready: solid disc (--status-done), no motion. The default green
@@ -436,39 +463,58 @@
   opacity: 0.5;
 }
 
-@keyframes wt-pulse {
+/* 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. */
+@keyframes wt-working-glow {
   0%,
+  70%,
   100% {
-    /* Pin the animated layer's paint as well as its opacity. When working begins
-       in the same frame that input/done ends, an opacity-only animation can
-       pulse the previously rasterized input/done paint (the input ring
-       included, hence the box-shadow pin). */
     background-color: var(--status-working);
     border-color: var(--status-working);
-    box-shadow: 0 0 0 2px color-mix(in srgb, var(--status-working) 40%, transparent);
-    opacity: 1;
   }
 
-  50% {
-    background-color: var(--status-working);
-    border-color: var(--status-working);
-    box-shadow: 0 0 0 2px color-mix(in srgb, var(--status-working) 40%, transparent);
+  35% {
+    background-color: color-mix(in oklch, var(--status-working) 78%, #fff);
+    border-color: color-mix(in oklch, var(--status-working) 78%, #fff);
+  }
+}
+
+/* The ripple wave: one emission per cycle, launching off the static ring and
+   dissolving by ~2.1x. Opacity starts at the static ring's own 40% weight so
+   the wave reads as the ring letting go of a copy, not a new brighter object. */
+@keyframes wt-working-ripple {
+  0% {
+    transform: scale(1);
     opacity: 0.4;
   }
+
+  100% {
+    transform: scale(2.1);
+    opacity: 0;
+  }
 }
 
-/* Reduced-motion (or the animations feature off): drop the pulse, keep color. */
+/* Reduced-motion: drop the working motion (glow + ripple), keep color. */
 @media (prefers-reduced-motion: reduce) {
   :where(.wt-root) .wt-status-dot[data-status="working"] {
     animation: none;
-    /* The pulse is what separates working from input's frozen silhouette; with
-       motion removed, punch an inner hole (dot -> donut) so working differs
-       from input (solid ringed disc) and done (bare disc) by shape, not hue
-       alone (WCAG 1.4.1). The outer ring stays. */
+    /* Motion is what separates working from input's frozen silhouette; with
+       it removed, punch an inner hole (dot -> donut) so working differs from
+       input (solid ringed disc) and done (bare disc) by shape, not hue alone
+       (WCAG 1.4.1). The outer ring stays. */
     box-shadow:
       inset 0 0 0 2px var(--bg),
       0 0 0 2px color-mix(in srgb, var(--status-working) 40%, transparent);
   }
+
+  /* The ripple layer disappears entirely (not just paused mid-wave). */
+  :where(.wt-root) .wt-status-dot[data-status="working"]::after {
+    content: none;
+  }
 }
 
 /* ===== Catching-up cue (tabs feature, sections 12/13) =====

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-ui",
-  "version": "4.3.1",
+  "version": "4.5.0",
   "type": "module",
   "description": "Reference touch-first browser UI for @cplieger/web-terminal-engine: a composable kernel + feature modules (tabs, activity monitor, mobile toolbar, context menu, IME, predictive echo, viewport handling) and CSS. One createTerminal() call.",
   "license": "GPL-3.0-or-later",
@@ -54,10 +54,10 @@
     "html-validate": "11.5.6",
     "knip": "6.27.0",
     "prettier": "3.9.5",
-    "stylelint": "17.14.0",
+    "stylelint": "17.14.1",
     "stylelint-config-standard": "40.0.0",
     "typescript": "npm:@typescript/typescript6@6.0.2",
-    "typescript-eslint": "8.64.0",
+    "typescript-eslint": "8.65.0",
     "vitest": "4.1.10"
   },
   "publishConfig": {

package/scaffold/index.html

@@ -19,7 +19,11 @@
 #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%)}}
-@media (prefers-reduced-motion:reduce){#loading .bar::before{animation-duration:3s}}
+@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>
 </head>
 <body>

package/src/features/tabs/index.ts

@@ -100,6 +100,13 @@ export interface TabsOptions {
    *  reload), and the unreliable OSC title is ignored entirely. presetAgentTabbed
    *  enables this. */
   preferInputTitle?: boolean;
+  /** Presume every session reports activity (an agent shell, where the program
+   *  always emits OSC 9;4 progress): each tab's dot is visible as idle from
+   *  creation instead of popping in seconds later when the agent has booted
+   *  far enough to first report — the server's sticky reportsActivity flag
+   *  then merely confirms. Default false (evidence-driven reveal: a plain
+   *  shell keeps clean, label-only tabs). presetAgentTabbed enables this. */
+  presumeReports?: boolean;
 }
 
 // looksLikeHardwareKey reports whether a keydown could only have come from a
@@ -135,6 +142,12 @@ function looksLikeHardwareKey(ev: KeyboardEvent): boolean {
 export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
   const apiBase = opts.apiBase ?? DEFAULT_API_BASE;
   const preferInputTitle = opts.preferInputTitle ?? false;
+  const presumeReports = opts.presumeReports ?? false;
+  // reportsOf floors the server's per-session reportsActivity flag with the
+  // consumer's presumption (see TabsOptions.presumeReports): an agent shell
+  // shows the idle dot from tab creation instead of waiting out the agent's
+  // boot-to-first-OSC-9;4 window.
+  const reportsOf = (reports?: boolean): boolean => presumeReports || (reports ?? false);
   // The session REST client (model.ts): every call timeout-bounded, list
   // shape-guarded, title persistence fire-and-forget.
   const api = createSessionAPI(apiBase);
@@ -912,7 +925,7 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
         if (!label || !dot || !close) {
           throw new Error("web-terminal-ui: tab chrome missing parts");
         }
-        paintStatusDot(dot, info.status, info.reportsActivity ?? false);
+        paintStatusDot(dot, info.status, reportsOf(info.reportsActivity));
         const aria = tablist.registerTab(el);
         // Append to the scroller's end: the tab list is ALL the scroller holds
         // (the "+" and keyboard button are fixed bar items outside it).
@@ -941,7 +954,7 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
           aria,
           scrollTop: 0,
           following: true,
-          reports: info.reportsActivity ?? false,
+          reports: reportsOf(info.reportsActivity),
         };
         // Set an initial label immediately (relabelAll refines it with de-dup
         // once the tab is in tabList and syncChrome runs).
@@ -1669,7 +1682,7 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
               info.status,
               info.title,
               info.clientTitle,
-              info.reportsActivity ?? false,
+              reportsOf(info.reportsActivity),
             );
           }
           // A tab the server no longer lists was reaped/closed elsewhere (or
@@ -1703,7 +1716,7 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
           // SSE-adopted tab without its persisted title — in preferInputTitle
           // mode the label then fell back to "New tab" on reload.
           adoptSession(s);
-          applyStatus(s.id, s.status, s.title, s.clientTitle, s.reportsActivity ?? false);
+          applyStatus(s.id, s.status, s.title, s.clientTitle, reportsOf(s.reportsActivity));
           ensureActive();
           syncChrome();
         });

package/src/index.ts

@@ -14,6 +14,7 @@
 export { createTerminal } from "./kernel/kernel.js";
 export type {
   CreateTerminalOptions,
+  TerminalStartupFailure,
   TerminalHandle,
   TerminalFeature,
   FeatureInstance,

package/src/kernel/kernel.ts

@@ -186,7 +186,13 @@ export function createTerminal(
       return;
     }
     for (const fn of [...errorHandlers]) {
-      fn(feature, err);
+      try {
+        fn(feature, err);
+      } catch (handlerErr) {
+        // Error reporting must never turn the original feature failure into an
+        // unhandled rejection or prevent fatal-startup cleanup from running.
+        console.error("web-terminal-ui: feature error handler failed", handlerErr);
+      }
     }
   }
 
@@ -508,6 +514,11 @@ export function createTerminal(
   let pointerDownY = 0;
   let pointerDownTime = 0;
   function focusTerminal(): void {
+    // The public handle can outlive a fatal startup or explicit destroy. Never
+    // focus the detached textarea after the runtime has been released.
+    if (destroyed) {
+      return;
+    }
     input.focus({ preventScroll: true });
   }
   termWrap.addEventListener(
@@ -794,13 +805,19 @@ export function createTerminal(
   }
 
   // --- Feature lifecycle ---
+  // `destroyed` means the terminal runtime is no longer usable, whether that
+  // happened through the public destroy() handle or a fatal startup rollback.
+  // `rootReleased` is narrower: destroy() has also removed the recovery surface
+  // and boundary classes. Keeping the two facts separate lets a fatal terminal
+  // remain visible and still be explicitly destroyed later.
   let destroyed = false;
-  // Live read of `destroyed` for the post-await re-check in setupFeatures():
-  // a plain `if (destroyed)` there is narrowed to always-false by TS CFA
-  // (it cannot model destroy() firing during the await), tripping
-  // @typescript-eslint/no-unnecessary-condition. A call defeats the stale
-  // narrowing with identical runtime behavior.
+  let rootReleased = false;
+  let runtimeCleaned = false;
+  // Live read of `destroyed` for post-await re-checks: a plain variable read is
+  // narrowed to always-false by TS CFA because it cannot model destroy() firing
+  // while feature setup or session resolution is awaiting.
   const isDestroyed = (): boolean => destroyed;
+
   function teardownFeatures(): void {
     for (let i = instances.length - 1; i >= 0; i--) {
       const entry = instances[i];
@@ -816,49 +833,157 @@ export function createTerminal(
     instances.length = 0;
   }
 
-  // Resolves true when every feature set up; false when setup was aborted (a
-  // feature threw and everything rolled back, or destroy() ran mid-setup). The
-  // session-owner first connect below runs only on true — a resolver must never
-  // run against torn-down chrome.
-  async function setupFeatures(): Promise<boolean> {
+  // Release the complete live runtime while leaving the root boundary classes
+  // intact. Fatal startup uses the root for its recovery surface; destroy()
+  // follows this cleanup by removing the classes and any recovery UI.
+  function cleanupRuntime(): void {
+    if (runtimeCleaned) {
+      return;
+    }
+    runtimeCleaned = true;
+    teardownFeatures();
+    kernelAbort.abort();
+    narrowObserver?.disconnect();
+    narrowObserver = null;
+    viewport.teardown();
+    // Reset the composition singleton: a failure during an IME cycle must not
+    // leave module state or a deferred send alive for a later terminal mount.
+    composition.teardown();
+    connection.disconnect();
+    connState.destroy();
+    if (toastTimer !== null) {
+      clearTimeout(toastTimer);
+      toastTimer = null;
+    }
+    for (const off of subscriptions) {
+      off();
+    }
+    subscriptions.length = 0;
+    inputTransforms.length = 0;
+    inputObservers.length = 0;
+    keydownHandlers.length = 0;
+    errorHandlers.clear();
+    apiMap.clear();
+    activeSession = null;
+    bus.clear();
+    announcer.destroy();
+    regions.destroy();
+    root.classList.remove("wt-narrow");
+    root.replaceChildren();
+  }
+
+  function renderFatalStartup(): void {
+    const surface = document.createElement("section");
+    surface.className = "wt-fatal";
+    surface.setAttribute("role", "alertdialog");
+    surface.setAttribute("aria-labelledby", "wt-fatal-title");
+    surface.setAttribute("aria-describedby", "wt-fatal-message");
+    if (layoutMode === "viewport") {
+      // A full-page terminal has no usable host UI behind it, so this is the
+      // page's modal recovery state. An embedded terminal is only one panel in
+      // a larger app and must not claim that the rest of the app is inert.
+      surface.setAttribute("aria-modal", "true");
+    }
+
+    const card = document.createElement("div");
+    card.className = "wt-fatal-card";
+    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.";
+    const reloadButton = document.createElement("button");
+    reloadButton.className = "wt-btn wt-fatal-reload";
+    reloadButton.type = "button";
+    reloadButton.textContent = "Reload page";
+    reloadButton.addEventListener("click", () => {
+      window.location.reload();
+    });
+    card.append(title, message, reloadButton);
+    surface.appendChild(card);
+    root.replaceChildren(surface);
+
+    // The terminal input held focus before setup failed. Move that focus to the
+    // only recovery action; container mode remains non-modal because no trap or
+    // aria-modal claim prevents the user from leaving the terminal panel.
+    reloadButton.focus();
+  }
+
+  function enterFatalStartup(feature: string, cause: unknown): void {
+    if (destroyed) {
+      return;
+    }
+    destroyed = true;
+    cleanupRuntime();
+    dismissLoadingOverlay();
+
+    let handled = false;
+    try {
+      handled = opts.onFatalError?.({ phase: "feature-setup", feature, cause }) === true;
+    } catch (handlerErr) {
+      console.error("web-terminal-ui: onFatalError handler failed", handlerErr);
+    }
+    // A handler may call destroy() while taking over, so do not recreate the
+    // default surface after the root has explicitly been released.
+    if (!handled && !rootReleased) {
+      renderFatalStartup();
+    }
+  }
+
+  type FeatureSetupOutcome =
+    | { readonly status: "ready" }
+    | { readonly status: "aborted" }
+    | {
+        readonly status: "failed";
+        readonly feature: string;
+        readonly cause: unknown;
+      };
+
+  // Distinguish intentional cancellation from a fatal feature failure. A
+  // boolean collapsed both into the same "not ready" outcome, which is why a
+  // failed setup previously left a half-live terminal and only wrote a log.
+  async function setupFeatures(): Promise<FeatureSetupOutcome> {
     for (const feature of featureList) {
       if (destroyed) {
-        return false;
+        return { status: "aborted" };
       }
       try {
         const instance = await feature.setup(makeContext(feature.name));
-        // destroy() may have run during the await above; teardownFeatures() has already
-        // swept `instances`, and destroy() is one-shot, so a straight push here would
-        // leave this instance's listeners/timers/observers (tabs' SSE + poll + window/
-        // document listeners + ResizeObservers) alive forever. Tear it down instead of
-        // registering it.
+        // destroy() may have run during the await above; cleanupRuntime() has
+        // already swept `instances`, and destroy() is one-shot, so a straight
+        // push here would leave this instance's listeners/timers/observers alive
+        // forever. Tear it down instead of registering it.
         if (isDestroyed()) {
           try {
             instance.teardown();
           } catch (err) {
             reportError(feature.name, err);
           }
-          return false;
+          return { status: "aborted" };
         }
         instances.push({ feature, instance });
         // Populate the feature value's readonly api (consumer pattern:
         // tabs.api?.create()) via a narrow cast, and the ctx.use lookup map.
         (feature as { api?: unknown }).api = instance.api;
         apiMap.set(feature, instance.api);
-      } catch (err) {
-        // Fail fast: roll back the already-set-up features in reverse and
-        // surface a composed, named error (section 22.4).
-        reportError(feature.name, err);
-        teardownFeatures();
-        console.error(
-          `web-terminal-ui: feature "${feature.name}" setup failed; terminal has no chrome`,
-          err,
-        );
-        return false;
+      } catch (cause) {
+        if (isDestroyed()) {
+          return { status: "aborted" };
+        }
+        reportError(feature.name, cause);
+        console.error(`web-terminal-ui: feature "${feature.name}" setup failed`, cause);
+        if (isDestroyed()) {
+          return { status: "aborted" };
+        }
+        return { status: "failed", feature: feature.name, cause };
       }
     }
-    return true;
+    return { status: "ready" };
   }
+
   // Features set up in the background; first paint is never gated on them.
   // Under a session owner the kernel then drives the first connect itself:
   // await the owner's resolveInitialSession() and switch to the session it
@@ -870,14 +995,12 @@ export function createTerminal(
   // alive, and the kernel — which now SEES the failure instead of inferring it
   // from a missing side effect — dismisses the loading overlay so that chrome
   // is visible instead of an eternal spinner.
-  void setupFeatures().then(async (ok) => {
-    if (!ok) {
-      // Setup aborted (rolled back or destroyed). Under a session owner no
-      // connect will ever be attempted, so nothing else can lower the loading
-      // overlay — dismiss it so the page shows its real state.
-      if (!connectionInitiated && !destroyed) {
-        dismissLoadingOverlay();
-      }
+  void setupFeatures().then(async (outcome) => {
+    if (outcome.status === "failed") {
+      enterFatalStartup(outcome.feature, outcome.cause);
+      return;
+    }
+    if (outcome.status === "aborted") {
       return;
     }
     if (!sessionOwner || isDestroyed()) {
@@ -924,32 +1047,15 @@ export function createTerminal(
       render.resetScreen();
     },
     destroy() {
-      if (destroyed) {
+      if (rootReleased) {
         return;
       }
+      rootReleased = true;
       destroyed = true;
-      teardownFeatures();
-      kernelAbort.abort();
-      narrowObserver?.disconnect();
-      viewport.teardown();
-      // Reset the composition singleton (kernel-driven, no feature teardown): a
-      // destroy() mid-IME-composition otherwise leaves module-level `composing`
-      // stuck true, so a remounted terminal swallows every keydown until an IME
-      // cycle resets it; also neutralizes a pending compositionend setTimeout.
-      composition.teardown();
-      connection.disconnect();
-      connState.destroy();
-      if (toastTimer !== null) {
-        clearTimeout(toastTimer);
-      }
-      for (const off of subscriptions) {
-        off();
-      }
-      subscriptions.length = 0;
-      bus.clear();
-      announcer.destroy();
-      regions.destroy();
+      cleanupRuntime();
       root.classList.remove("wt-root", "wt-viewport", "wt-container", "wt-narrow");
+      // cleanupRuntime() removed the live subtree. A fatal handler may have
+      // rendered replacement UI afterward, so destroy() clears once more.
       root.replaceChildren();
     },
   };

package/src/kernel/types.ts

@@ -303,6 +303,18 @@ export interface FeatureInstance<Api = void> {
 
 // --- Entry point ---
 
+/** A fatal failure while createTerminal is starting its feature composition.
+ *  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 to `onFatalError`. */
+export interface TerminalStartupFailure {
+  readonly phase: "feature-setup";
+  /** Name of the feature whose setup threw or rejected. */
+  readonly feature: string;
+  /** The original thrown or rejected value. */
+  readonly cause: unknown;
+}
+
 /** Options for createTerminal. */
 export interface CreateTerminalOptions {
   /** The feature list; omitted or empty means the bare kernel (no chrome).
@@ -323,6 +335,14 @@ export interface CreateTerminalOptions {
   fontReady?: string;
   /** Optional pre-JS loading overlay the kernel fades out on first paint. */
   loading?: HTMLElement;
+  /** 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
+   *  that root; false or undefined keeps the built-in Reload page surface. If
+   *  this callback throws, the kernel logs that error and shows the built-in
+   *  surface, so a reporting failure cannot leave the page blank. */
+  // eslint-disable-next-line @typescript-eslint/no-invalid-void-type -- an observing handler returns nothing; only a literal `true` claims the recovery surface, so forcing `return undefined` on every observer is worse than the union
+  onFatalError?: (failure: TerminalStartupFailure) => boolean | void;
   /** Theme overrides: CSS custom properties set on the terminal root so a
    *  consumer recolors the UI (accent, tab hover/active) without shipping CSS.
    *  Keys must be CSS custom-property names (start with "--"); values are any

package/src/presets/agent-tabbed.ts

@@ -4,12 +4,19 @@ import type { TerminalFeature } from "../kernel/types.js";
 import { buildTabbed } from "./tabbed.js";
 
 /** Tabbed UI for an agent shell (web-terminal-kiro). Same features as
- *  presetTabbed, but with `preferInputTitle`: the agent's program (kiro-cli)
- *  emits a non-empty but useless OSC 0/2 title, so each tab's label follows the
- *  latest submitted line (persisted server-side and recovered on reload) and
- *  the OSC title is ignored. The agent-vs-generic status distinction remains
- *  server-side (a status classifier mapping OSC 9 notifications to
- *  done/needs-input). */
+ *  presetTabbed, tuned for sessions that ARE agents:
+ *  - `preferInputTitle`: the agent's program (kiro-cli) emits a non-empty but
+ *    useless OSC 0/2 title, so each tab's label follows the latest submitted
+ *    line (persisted server-side and recovered on reload) and the OSC title
+ *    is ignored.
+ *  - `presumeReports`: every session's program is an agent that WILL report
+ *    OSC 9;4 progress, so the idle activity dot shows from tab creation
+ *    instead of popping in seconds later when the agent has booted far enough
+ *    to first report; the server's sticky reportsActivity flag then merely
+ *    confirms. (presetTabbed keeps the evidence-driven reveal instead: a
+ *    plain shell never grows a meaningless dot.)
+ *  The agent-vs-generic status distinction remains server-side (a status
+ *  classifier mapping OSC 9 notifications to done/needs-input). */
 export function presetAgentTabbed(): TerminalFeature<unknown>[] {
   return buildTabbed(true);
 }

package/src/presets/tabbed.ts

@@ -14,19 +14,26 @@ import { presetSingle } from "./single.js";
  *  externally-driven mobile toolbar (its grid is opened from a keyboard button
  *  in the tab bar, not its own toggle), the activity monitor (the status-SSE
  *  data source), tabs wired to both, and animations. The activity dot reveals
- *  itself per tab only when a session reports activity (OSC 9;4), so the
- *  monitor is always included — a plain shell just never shows a dot. The
+ *  itself per tab only when a session reports activity (OSC 9;4) — or from tab
+ *  creation when the agent composition presumes it — so the monitor is always
+ *  included; a plain shell under presetTabbed just never shows a dot. The
  *  toolbar and monitor are ordered before tabs because tabs reads their APIs
  *  via ctx.use. Shared by presetTabbed and presetAgentTabbed (agent-tabbed.ts),
- *  which differ only in the title source. */
-export function buildTabbed(preferInputTitle: boolean): TerminalFeature<unknown>[] {
+ *  which differ only in the agent-shell tuning: input-derived titles
+ *  (preferInputTitle) + presumed activity reporting (presumeReports). */
+export function buildTabbed(agentShell: boolean): TerminalFeature<unknown>[] {
   const kb = mobileToolbar({ externalToggle: true });
   const monitor = activityMonitor();
   return [
     ...presetSingle(),
     kb,
     monitor,
-    tabs({ keyboardToggle: kb, activityMonitor: monitor, preferInputTitle }),
+    tabs({
+      keyboardToggle: kb,
+      activityMonitor: monitor,
+      preferInputTitle: agentShell,
+      presumeReports: agentShell,
+    }),
     animations(),
   ];
 }