@cplieger/web-terminal-ui 4.5.2 → 4.7.0

package/src/kernel/kernel.ts

@@ -86,10 +86,74 @@ function pick(root: ParentNode, selector: string): HTMLElement {
   return el;
 }
 
-export function createTerminal(
-  root: HTMLElement,
-  opts: CreateTerminalOptions = {},
-): TerminalHandle {
+/** Fade out and remove a consumer-supplied loading overlay.
+ *
+ *  Module scope because BOTH startup-failure phases need it and they live on
+ *  opposite sides of createTerminal's closure: the async `feature-setup` path
+ *  reaches it through dismissLoadingOverlay (which adds the once-only guard),
+ *  the synchronous `kernel-init` path calls it directly from the catch, where
+ *  no kernel state exists yet. */
+function fadeOutOverlay(ld: HTMLElement | undefined): void {
+  if (!ld) {
+    return;
+  }
+  ld.classList.add("fade");
+  const removeOverlay = (): void => {
+    ld.remove();
+  };
+  ld.addEventListener("transitionend", removeOverlay, { once: true });
+  window.setTimeout(removeOverlay, 1500);
+}
+
+/** Render the kernel-owned "Terminal failed to start" recovery surface into root.
+ *
+ *  Module scope for the same reason as fadeOutOverlay: it is the ONE
+ *  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 {
+  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();
+}
+
+/** 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 {
   const wsPath = opts.wsPath ?? DEFAULT_WS_PATH;
   const fontReady = opts.fontReady ?? DEFAULT_FONT_READY;
   const featureList = opts.features ?? [];
@@ -267,12 +331,7 @@ export function createTerminal(
       return;
     }
     overlayDismissed = true;
-    ld.classList.add("fade");
-    const removeOverlay = (): void => {
-      ld.remove();
-    };
-    ld.addEventListener("transitionend", removeOverlay, { once: true });
-    window.setTimeout(removeOverlay, 1500);
+    fadeOutOverlay(ld);
   }
   function markReady(): void {
     if (ready) {
@@ -873,43 +932,7 @@ export function createTerminal(
   }
 
   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();
+    renderFatalStartupInto(root, layoutMode);
   }
 
   function enterFatalStartup(feature: string, cause: unknown): void {
@@ -1060,3 +1083,52 @@ export function createTerminal(
     },
   };
 }
+
+/** Build the terminal UI inside `root`. Call exactly once.
+ *
+ *  Wraps buildTerminal so that a SYNCHRONOUS startup failure gets the same
+ *  treatment an asynchronous one already got. Before this, the two halves of
+ *  "the terminal did not start" were handled inconsistently: an async
+ *  feature-setup rejection ran enterFatalStartup (overlay dismissed,
+ *  onFatalError delivered, recovery surface rendered), while a synchronous throw
+ *  propagated bare, leaving the consumer's loading overlay spinning forever over
+ *  a page with no terminal and no explanation. Consumers were left hand-building
+ *  their own surface to cover the gap, diverging from this one in shape and copy.
+ *
+ *  The error still propagates: a consumer with its own handling sees it exactly
+ *  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. */
+export function createTerminal(
+  root: HTMLElement,
+  opts: CreateTerminalOptions = {},
+): TerminalHandle {
+  try {
+    return buildTerminal(root, opts);
+  } 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");
+    // 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.
+    fadeOutOverlay(opts.loading);
+
+    let handled = false;
+    try {
+      handled = opts.onFatalError?.({ phase: "kernel-init", cause }) === 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);
+    }
+    throw cause;
+  }
+}

package/src/kernel/types.ts

@@ -147,6 +147,18 @@ export interface TabHandle {
   setSelected(selected: boolean): void;
   /** Set the accessible label (used for aria-labelledby on the panel). */
   setLabel(text: string): void;
+  /** Enter or leave inline-edit mode. A textbox is not valid content for
+   *  `role="tab"` (ARIA marks a tab's children presentational, so a focusable
+   *  descendant may get no accessibility-tree node at all), so a feature that
+   *  puts an input inside its chip drops the tab semantics for the duration.
+   *
+   *  One atomic transition each way. On: `role` and `aria-selected` are removed
+   *  and the chip leaves the roving sequence while the field owns focus. Off: the
+   *  role is restored along with `aria-selected` and the roving tabindex derived
+   *  from `selected` AS OF NOW — the active tab can change while an edit is open
+   *  on a different chip, so the caller passes the current state rather than the
+   *  handle replaying the state it saw at entry. */
+  setEditing(editing: boolean, selected: boolean): void;
   /** Deregister this tab. */
   remove(): void;
 }
@@ -303,17 +315,35 @@ 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;
-}
+/** 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:
+ *
+ *  - `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.
+ *  - `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. */
+export type 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;
+    }
+  | {
+      readonly phase: "kernel-init";
+      /** The original thrown value, rethrown to the caller after this returns. */
+      readonly cause: unknown;
+    };
 
 /** Options for createTerminal. */
 export interface CreateTerminalOptions {

package/src/presets/agent-tabbed.ts

@@ -5,18 +5,16 @@ import { buildTabbed } from "./tabbed.js";
 
 /** Tabbed UI for an agent shell (web-terminal-kiro). Same features as
  *  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). */
+ *  Two agent-vs-generic distinctions live SERVER-side rather than here: the
+ *  status classifier that maps OSC 9 notifications to done/needs-input, and the
+ *  input-derived session name (terminal.WithInputTitle), which the agent host
+ *  enables because its program's own window title is not worth showing. */
 export function presetAgentTabbed(): TerminalFeature<unknown>[] {
   return buildTabbed(true);
 }

package/src/presets/tabbed.ts

@@ -19,8 +19,14 @@ import { presetSingle } from "./single.js";
  *  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 agent-shell tuning: input-derived titles
- *  (preferInputTitle) + presumed activity reporting (presumeReports). */
+ *  which now differ only in presumed activity reporting (presumeReports).
+ *
+ *  Titles are no longer a preset concern. The ENGINE resolves a session's name —
+ *  its pinned name, an input-derived name when the host asked for one
+ *  (terminal.WithInputTitle), the program's OSC window title, or its own
+ *  foreground-process/cwd inference — and both presets render what it reports. A
+ *  browser that re-derived any of that could only disagree with the server and
+ *  with every other client attached to the same session. */
 export function buildTabbed(agentShell: boolean): TerminalFeature<unknown>[] {
   const kb = mobileToolbar({ externalToggle: true });
   const monitor = activityMonitor();
@@ -31,7 +37,6 @@ export function buildTabbed(agentShell: boolean): TerminalFeature<unknown>[] {
     tabs({
       keyboardToggle: kb,
       activityMonitor: monitor,
-      preferInputTitle: agentShell,
       presumeReports: agentShell,
     }),
     animations(),