@cplieger/web-terminal-ui 7.0.5 → 7.0.7

package/README.md

@@ -358,8 +358,19 @@ 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.
+error handling still sees the error.
+
+The panel is a native `<dialog>`. In `viewport` layout it opens with
+`showModal()`, so the rest of your document is inert while it is up; in
+`container` layout it opens non-modally, so the application around an embedded
+terminal keeps working and keeps its focusables. Escape does not dismiss it in
+either mode: the terminal is already gone, so there would be nothing behind it
+and no way back. Reload is the recovery.
+
+One visible consequence in `viewport` layout: a modal dialog is in the browser's
+top layer, above every `z-index` in the document, so the panel now paints over
+your loading overlay instead of under it. It appears at once and the overlay's
+fade-out finishes behind it.
 
 **This is why `target` takes a selector and `features` takes a function.** Both
 are resolved INSIDE that boundary. Written the other way round

package/css/10-primitives.css

@@ -133,13 +133,26 @@
    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. */
+   outside the terminal fully visible and interactive.
+
+   The surface is a native <dialog>: showModal() in wt-viewport, the bare `open`
+   attribute in wt-container. Modality is the only difference between them. */
 :where(.wt-root) .wt-fatal {
   position: absolute;
   inset: 0;
-  z-index: 100;
-  display: grid;
-  place-items: center;
+  /* The size resets are what let the insets stretch the panel: a <dialog> is
+     fit-content with the UA sheet's own `margin: auto`, and :modal additionally
+     caps both axes at calc(100% - 38px). margin, border-radius and box-shadow
+     answer an EMBEDDER's own `dialog { ... }` base rule rather than the UA sheet —
+     margin is the member that moves the box, the other two are cosmetic. */
+  margin: 0;
+  border: none;
+  border-radius: 0;
+  box-shadow: none;
+  inline-size: auto;
+  block-size: auto;
+  max-inline-size: none;
+  max-block-size: none;
   overflow: auto;
   padding: calc(var(--safe-top) + var(--sp-3)) var(--sp-3) calc(var(--safe-bottom) + var(--sp-3));
   background: var(--bg);
@@ -148,6 +161,39 @@
   text-align: center;
 }
 
+/* Scoped to [open]: an author `display` beats the UA's `dialog { display: none }`
+   at any specificity, so declared unconditionally a CLOSED panel would still
+   paint its full-surface background over the root. */
+:where(.wt-root) .wt-fatal[open] {
+  display: grid;
+  place-items: center;
+}
+
+/* The base rule's `position: absolute` serves the container half (it resolves
+   against .wt-root.wt-container, the embedder's box); this gives the viewport back
+   to the modal half. A top-layer absolute resolves against the initial containing
+   block — viewport-SIZED but canvas-anchored, so equivalent to fixed only at
+   scrollY 0 — and Blink does not lock document scrolling under a modal dialog.
+   Pinned by fatal-panel.test.ts's scrolled-document test. */
+:where(.wt-root) .wt-fatal:modal {
+  position: fixed;
+}
+
+/* The stacking order the top layer supplies for free, so it is declared only for
+   the half that is not in it. .wt-root.wt-container is the EMBEDDER's element and
+   forms no stacking context, so the panel competes in the host's. */
+:where(.wt-root) .wt-fatal:not(:modal) {
+  z-index: 100;
+}
+
+/* The panel IS the dim — it fills its whole surface in --bg — so the backdrop
+   agrees with it instead of adding a second, differently coloured layer. The UA's
+   rgba(0, 0, 0, 0.1) would show as a lighter seam if the panel were ever smaller
+   than the viewport. */
+:where(.wt-root) .wt-fatal::backdrop {
+  background: var(--bg);
+}
+
 :where(.wt-root) .wt-fatal-card {
   inline-size: min(100%, 28rem);
   padding: clamp(1.25rem, 5vi, 2rem);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-ui",
-  "version": "7.0.5",
+  "version": "7.0.7",
   "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": "MPL-2.0",
@@ -52,20 +52,20 @@
     "@stryker-mutator/vitest-runner": "10.0.0",
     "@types/node": "26.4.1",
     "@typescript/native": "npm:typescript@7.0.2",
-    "@vitest/browser": "4.1.11",
-    "@vitest/browser-playwright": "4.1.11",
-    "@vitest/coverage-v8": "4.1.11",
-    "eslint": "10.9.1",
+    "@vitest/browser": "5.0.0",
+    "@vitest/browser-playwright": "5.0.0",
+    "@vitest/coverage-v8": "5.0.0",
+    "eslint": "10.10.0",
     "fast-check": "4.9.0",
-    "html-validate": "11.12.0",
+    "html-validate": "11.14.0",
     "knip": "6.34.0",
-    "playwright": "1.62.1",
+    "playwright": "1.63.0",
     "prettier": "3.9.6",
-    "stylelint": "17.14.1",
+    "stylelint": "17.15.0",
     "stylelint-config-standard": "40.0.0",
     "typescript": "npm:@typescript/typescript6@6.0.2",
     "typescript-eslint": "8.69.0",
-    "vitest": "4.1.11"
+    "vitest": "5.0.0"
   },
   "publishConfig": {
     "access": "public"

package/src/composition.ts

@@ -39,30 +39,38 @@ let sendingComposition = false;
 let compositionStart = 0;
 let compositionSuffix = "";
 
-// A soft keyboard may announce its composition only at COMMIT time: the
-// per-character `input` events arrive with no composition in progress, the
-// kernel sends each keystroke as typed, and then the keyboard fires
-// compositionstart + compositionend back-to-back on the committing key while
-// writing the WHOLE accumulated word into the textarea. The deferred read below
-// then sends that word a second time — reported on Android Chrome with
-// SwiftKey, where typing "hello" and pressing space produced "hellohello  ".
+// A composition that never ENDS used to stop the terminal accepting input at
+// all. `composing` gates both the kernel's `input` and `keydown` listeners, and
+// nothing cleared it: no blur handler, no timer. So a keyboard that opened a
+// composition and never closed it left every subsequent keystroke, Enter
+// included, dropped on the floor — reported on Android Chrome with SwiftKey as
+// "typing does not work", recoverable only by tapping a word suggestion, which
+// is what finally fired compositionend.
 //
-// The terminal has already been given the literal keystrokes and cannot be
-// asked to retract them, so a commit that only repeats them is a no-op.
-// `noteDirectSend` records what the kernel sent with no composition running;
-// the finaliser drops a commit that matches it.
+// Not a SwiftKey quirk to special-case. Chromium has a filed defect for
+// compositionend going missing (crbug 446714223, in EditContext rather than a
+// textarea, so it is adjacent evidence and not proof of this exact path), and
+// CodeMirror synthesises the event outright for Safari dead keys, which is a
+// working implementation treating the same absence as real.
 //
-// Unreachable on a keyboard that announces its composition BEFORE the
-// keystrokes (every desktop IME, iOS, Android's own keyboard): there the
-// kernel's `input` listener returns early while composing, so nothing is
-// recorded and there is nothing for a commit to match.
-const ECHO_TAIL_MAX = 64;
-const ECHO_WINDOW_MS = 1500;
-const ECHO_MAX_COMPOSE_MS = 60;
+// The fix is a STALENESS READ rather than a timer. A composition the user is
+// typing into keeps firing compositionupdate, so its clock keeps refreshing; an
+// abandoned one stops and ages out, releasing the gate. UI Events promises one
+// or more compositionupdate events and one whenever the DOM is updated as part
+// of the composition, not strictly one per key, so this is a heuristic about
+// activity rather than a guaranteed per-keystroke signal. Deliberately NOT
+// refreshed by `input` events: in this failure the user IS typing and those
+// events ARE arriving, so refreshing there would defeat the mechanism.
+//
+// Five seconds is the number Slate's android-input-manager uses for its own
+// composition-gone-quiet bound (a DOM flush decision, not an input gate, so the
+// value is borrowed and the job is not the same). It is generous because the
+// residual risk runs the other way: a composition paused longer than this and
+// then resumed can duplicate its first character. That trade is deliberate —
+// the failure being replaced loses ALL input until an unrelated event fires.
+const COMPOSITION_IDLE_MS = 5000;
 
-let directTail = "";
-let directTailAt = 0;
-let compositionStartedAt: number | null = null;
+let lastCompositionActivity = 0;
 
 export function init(opts: {
   textarea: HTMLTextAreaElement;
@@ -85,61 +93,61 @@ export function init(opts: {
   textarea.addEventListener("paste", onPaste);
 }
 
-/** True while an IME composition is in progress. Caller's keydown
- *  listener must early-return on true to avoid sending raw key bytes
- *  during composition. */
+/** True while an IME composition is in progress, RECONCILED first: a composition
+ *  whose clock has not been refreshed for COMPOSITION_IDLE_MS is expired here,
+ *  clearing the latch, the clock and the overlay, so a keyboard that never fires
+ *  compositionend cannot strand the terminal or leave a stale panel on screen.
+ *  A late compositionend still delivers its text — `onEnd` snapshots what it
+ *  needs and does not require `composing` to have stayed true.
+ *
+ *  `sendingComposition` is exempt: that window is bounded by a setTimeout(0)
+ *  this module owns. */
 export function isComposing(): boolean {
-  return composing || sendingComposition;
-}
-
-/** Record text the kernel put on the wire with no composition running, so a
- *  keyboard that announces its composition only at commit time cannot have the
- *  same keystrokes delivered twice (see the ECHO_* note above). Typed text
- *  only — a paste is never re-committed by a keyboard. */
-export function noteDirectSend(text: string): void {
-  if (text === "") {
-    return;
+  if (sendingComposition) {
+    return true;
   }
-  const now = Date.now();
-  if (now - directTailAt > ECHO_WINDOW_MS) {
-    directTail = "";
-  }
-  directTail = (directTail + text).slice(-ECHO_TAIL_MAX);
-  directTailAt = now;
-}
-
-/** Whether this commit merely repeats keystrokes already delivered literally. */
-function repeatsDirectSends(composed: string, startedAt: number | null, endedAt: number): boolean {
-  if (directTail === "") {
+  if (!composing) {
     return false;
   }
-  // A composition the user typed INTO spans human time; a commit-time
-  // announcement starts and ends inside one keystroke.
-  if (startedAt !== null && endedAt - startedAt > ECHO_MAX_COMPOSE_MS) {
-    return false;
+  if (Date.now() - lastCompositionActivity <= COMPOSITION_IDLE_MS) {
+    return true;
   }
-  // Only the burst still being typed can be a re-commit of itself.
-  if (endedAt - directTailAt > ECHO_WINDOW_MS) {
-    return false;
-  }
-  // The committing key (space, tab) is delivered as its own `input` event, so
-  // what has to match is the WORD the keyboard is re-committing.
-  const word = composed.replace(/[ \t]+$/u, "");
-  return word !== "" && directTail.endsWith(word);
+  expireComposition();
+  return false;
+}
+
+/** The RAW latch: is a composition open at all, regardless of whether it has
+ *  gone quiet. Read before the reconciling `isComposing()` by the keydown guard,
+ *  because the keyCode 229 signal only means "an IME claimed this key" while a
+ *  composition is genuinely open — on Android it is the value for nearly every
+ *  soft-keyboard key. */
+export function isCompositionOpen(): boolean {
+  return composing || sendingComposition;
+}
+
+/** Drop a composition that has gone quiet: the latch, the clock and the visible
+ *  overlay together. Without the overlay half the gate would say no composition
+ *  while `.composition-view.active` still said there was one, leaving a stale
+ *  panel over the terminal for as long as the missing compositionend never
+ *  arrived. Does NOT touch the textarea: a late compositionend still reads it. */
+function expireComposition(): void {
+  composing = false;
+  lastCompositionActivity = 0;
+  compositionView.textContent = "";
+  compositionView.classList.remove("active");
 }
 
 /** Abort any in-flight composition without sending, and clear the textarea.
- *  The kernel calls this on a tab switch (detach): committing half-composed IME
- *  text to either the outgoing or the incoming session is wrong, so we discard
- *  it (design 5.1, "end any composition ... or cancel"). Clearing
- *  sendingComposition also neutralizes a just-fired compositionend whose
- *  deferred send is still pending on the microtask/timeout queue, so it cannot
- *  land on whoever is active after the switch. */
+ *  The kernel calls this on a tab switch (detach) and on blur: committing
+ *  half-composed IME text to either the outgoing or the incoming session is
+ *  wrong, so we discard it (design 5.1, "end any composition ... or cancel").
+ *  Clearing sendingComposition also neutralizes a just-fired compositionend
+ *  whose deferred send is still pending on the microtask/timeout queue, so it
+ *  cannot land on whoever is active after the switch. */
 export function cancelComposition(): void {
   composing = false;
   sendingComposition = false;
-  compositionStartedAt = null;
-  directTail = "";
+  lastCompositionActivity = 0;
   compositionView.textContent = "";
   compositionView.classList.remove("active");
   resetToPlaceholder(textarea);
@@ -167,7 +175,7 @@ export function teardown(): void {
 
 function onStart(): void {
   composing = true;
-  compositionStartedAt = Date.now();
+  lastCompositionActivity = Date.now();
   const start = textarea.selectionStart;
   const end = textarea.selectionEnd;
   compositionStart = Math.min(start, end);
@@ -179,6 +187,10 @@ function onStart(): void {
 }
 
 function onUpdate(ev: CompositionEvent): void {
+  // Every keystroke of a live composition lands here, which is what keeps its
+  // staleness clock fresh (see COMPOSITION_IDLE_MS). An abandoned composition
+  // stops firing this and ages out of the gate.
+  lastCompositionActivity = Date.now();
   // \u200E (LTR mark) wrappers + CSS direction:rtl on the view make
   // long compositions show their trailing edge instead of being
   // clipped at the start. Pattern from xterm.js.
@@ -189,15 +201,13 @@ function onUpdate(ev: CompositionEvent): void {
 function onEnd(): void {
   compositionView.classList.remove("active");
   composing = false;
+  lastCompositionActivity = 0;
   // The compositionend event fires before the textarea reflects the
   // final value on most browsers (Chromium especially). Defer one tick
   // and read the textarea then; xterm.js's pattern.
   sendingComposition = true;
   const startSnapshot = compositionStart;
   const suffixSnapshot = compositionSuffix;
-  const startedAt = compositionStartedAt;
-  const endedAt = Date.now();
-  compositionStartedAt = null;
   setTimeout(() => {
     if (!sendingComposition) {
       return;
@@ -211,10 +221,9 @@ function onEnd(): void {
     const composed = value
       .substring(startSnapshot, Math.max(startSnapshot, valueEnd))
       .replace(/\u00A0/g, " ");
-    if (composed.length > 0 && !repeatsDirectSends(composed, startedAt, endedAt)) {
+    if (composed.length > 0) {
       send(composed);
     }
-    directTail = "";
     resetToPlaceholder(textarea);
   }, 0);
 }

package/src/kernel/kernel.ts

@@ -120,6 +120,16 @@ function normalizeTypedText(text: string): string {
   return text.replace(/\u00A0/g, " ");
 }
 
+/** `KeyboardEvent.keyCode` for a key an IME has claimed. Windows' VK_PROCESS,
+ *  reported by Blink and WebKit for the key that commits a composition, and by
+ *  Android for essentially every soft-keyboard key — which is why every read of
+ *  it is gated on a composition being open.
+ *
+ *  Deprecated and nonetheless the only carrier of this fact: for that commit key
+ *  both engines report `key` as the ordinary `"Enter"`, and Safari reports
+ *  `isComposing` false, so neither the modern flag nor `key` distinguishes it. */
+const IME_COMMIT_KEYCODE = 229;
+
 function pick(root: ParentNode, selector: string): HTMLElement {
   const el = root.querySelector<HTMLElement>(selector);
   if (!el) {
@@ -158,17 +168,18 @@ function renderFatalStartupInto(
   layoutMode: "viewport" | "container",
   message: string = STARTUP_FAILURE_COPY.message,
 ): void {
-  const surface = document.createElement("section");
+  const surface = document.createElement("dialog");
   surface.className = "wt-fatal";
+  // alertdialog over the implicit `dialog` role: an urgent message to act on. No
+  // `aria-modal` — showModal() conveys modality; an authored value can contradict the UA.
   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");
-  }
+  // showModal() makes Escape a close request, and the kernel has already cleared
+  // the root: nothing is behind this panel, so reload is the only recovery.
+  surface.addEventListener("cancel", (ev) => {
+    ev.preventDefault();
+  });
 
   const card = document.createElement("div");
   card.className = "wt-fatal-card";
@@ -191,9 +202,19 @@ function renderFatalStartupInto(
   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.
+  // Viewport: the terminal IS the page, so the top layer and an inert document
+  // are both accurate; container gets the bare `open` attribute, which is neither
+  // and is what an embedded panel wants. `isConnected` is showModal()'s own
+  // precondition and a detached root arrives here from a typed call, where a
+  // throw would bury the real startup cause under a second error out of the catch.
+  if (layoutMode === "viewport" && surface.isConnected) {
+    surface.showModal();
+  } else {
+    surface.open = true;
+  }
+
+  // The terminal input held focus before setup failed; move it to the only
+  // recovery action. showModal() lands there itself, the non-modal half does not.
   reloadButton.focus();
 }
 
@@ -390,14 +411,6 @@ function buildTerminal(
   function sendText(text: string): void {
     sendBytes(encoder.encode(text));
   }
-  /** A keystroke the user typed with no composition running. Recorded so a
-   *  keyboard that announces its composition only at commit time cannot have
-   *  the same characters delivered twice (composition.ts, the ECHO_* note). */
-  function sendTyped(text: string): void {
-    const out = normalizeTypedText(text);
-    sendText(out);
-    composition.noteDirectSend(out);
-  }
   function paste(text: string): void {
     // The one bracketed-paste + newline-normalize funnel; every feature and the
     // kernel's own paste paths route through here (paste-jacking defense).
@@ -766,19 +779,43 @@ function buildTerminal(
       ) {
         resetToPlaceholder(input);
         return;
+      } else if (inputType === "insertReplacementText") {
+        // A spellcheck / autocorrect / autofill REWRITE of text already typed.
+        // The bytes it is correcting have already gone to the pty and a terminal
+        // cannot retract them: 0x7f means whatever the remote application decides
+        // it means, so a pager, vim, a y/n prompt and a no-echo password prompt
+        // each read it as their own input. Applying the rewrite forward instead
+        // duplicates — measured on xterm.js's value-diff, where `helo` corrected
+        // to `hello` puts `helohello` on the wire (its issue #3600). So drop it
+        // and leave the typed text standing, which is also what a shell wants:
+        // `cd /usr` silently becoming `cd /use` is worse than no autocorrect.
+        //
+        // The spec's own signal for this, so no length heuristic is needed: a
+        // max-one-character rule would break glide typing (a whole word in one
+        // event, and SwiftKey's flagship input method) while still admitting
+        // CJK's one-for-one in-place replacement. Cancelling is not an option
+        // either — preventDefault on beforeinput is a no-op in Chrome, per
+        // CodeMirror's own note — but declining to SEND is entirely ours.
+        //
+        // Reachable on more than Android: WebKit fires this type for a spelling
+        // suggestion and for a macOS system text substitution whatever
+        // autocorrect="off" says. Dropping is right wherever it fires, because
+        // what it carries is always a replacement for bytes the pty already has.
+        resetToPlaceholder(input);
+        return;
       } else if (typeof ev.data === "string" && ev.data.length > 0) {
         if (inputType === "insertFromPaste") {
           paste(ev.data);
         } else {
           // Normalize iOS's NBSP-for-space quirk, then send through the funnel.
-          sendTyped(ev.data);
+          sendText(normalizeTypedText(ev.data));
         }
       } else {
         const v = input.value;
         if (v.length > INPUT_PLACEHOLDER.length && v.startsWith(INPUT_PLACEHOLDER)) {
-          sendTyped(v.slice(INPUT_PLACEHOLDER.length));
+          sendText(normalizeTypedText(v.slice(INPUT_PLACEHOLDER.length)));
         } else if (v !== INPUT_PLACEHOLDER && v.length > 0) {
-          sendTyped(v);
+          sendText(normalizeTypedText(v));
         }
       }
       resetToPlaceholder(input);
@@ -796,7 +833,12 @@ function buildTerminal(
   input.addEventListener(
     "blur",
     () => {
-      resetToPlaceholder(input);
+      // cancelComposition, not just resetToPlaceholder: `composing` gates both
+      // input listeners, so a composition abandoned by losing focus would
+      // otherwise keep the gate shut and the terminal would take no input when
+      // focus came back. The staleness read covers a keyboard that strands us
+      // while still focused; this covers the case with a definite signal.
+      composition.cancelComposition();
       termWrap.classList.remove("focus");
     },
     { signal },
@@ -846,6 +888,33 @@ function buildTerminal(
   input.addEventListener(
     "keydown",
     (ev: KeyboardEvent) => {
+      // Three gates, and the order is the design. The spec signal first: UI
+      // Events requires a key event inside a composition session to carry
+      // isComposing, which covers every engine except one case.
+      //
+      // That case is the key which COMMITS a composition: Chrome and Safari both
+      // report keyCode 229 for it and Safari reports isComposing false (measured
+      // in quill PR #3445), so a second signal is needed. It is read against the
+      // RAW latch, before the reconciling isComposing() below, and both halves of
+      // that matter. Gated, because on Android 229 is the value for nearly every
+      // soft-keyboard key, so an unconditional check swallows ordinary Backspace
+      // and Enter — found in review after exactly that shipped here. Before the
+      // reconcile, because reconciling clears the latch, and a CJK user who left
+      // a candidate window open past the idle bound is still committing a real
+      // composition: taking this key as an ordinary Enter would send a carriage
+      // return before the composed phrase and execute a half-typed line.
+      //
+      // The consequence to know: in a stranded composition on Android, Enter and
+      // Backspace stay blocked until a character arrives (which reconciles the
+      // latch and releases them) or focus is lost. That is the deliberate side
+      // of the trade, because the alternative costs desktop and iOS correctness.
+      if (ev.isComposing) {
+        return;
+      }
+      // eslint-disable-next-line @typescript-eslint/no-deprecated -- see above
+      if (composition.isCompositionOpen() && ev.keyCode === IME_COMMIT_KEYCODE) {
+        return;
+      }
       if (composition.isComposing()) {
         return;
       }
@@ -1179,7 +1248,7 @@ function buildTerminal(
         // an uncanceled keydown's insertion target after a listener moved focus
         // mid-dispatch. Chromium does; no specification requires it.
         ev.preventDefault();
-        sendTyped(char);
+        sendText(normalizeTypedText(char));
         return;
       }
       applyMappedKey(ev, result);
@@ -1830,21 +1899,6 @@ function buildTerminal(
   };
 }
 
-/** 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. */
 /** 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
@@ -1901,6 +1955,10 @@ function createFallbackHost(): HTMLElement {
   return host;
 }
 
+/** Build the terminal UI inside `target`. Call exactly once. Wraps buildTerminal so
+ *  a SYNCHRONOUS startup failure gets the same recovery surface an async one does
+ *  and still propagates; that surface is modal in viewport layout, so
+ *  `onFatalError` returning `true` is the path that leaves the page interactive. */
 export function createTerminal(
   target: HTMLElement | string,
   opts: CreateTerminalOptions = {},