@cplieger/web-terminal-ui 7.0.6 → 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.6",
+  "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",
@@ -55,13 +55,13 @@
     "@vitest/browser": "5.0.0",
     "@vitest/browser-playwright": "5.0.0",
     "@vitest/coverage-v8": "5.0.0",
-    "eslint": "10.9.1",
+    "eslint": "10.10.0",
     "fast-check": "4.9.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",

package/src/kernel/kernel.ts

@@ -168,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";
@@ -201,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();
 }
 
@@ -1888,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
@@ -1959,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 = {},