ruact 0.0.19 → 0.0.21

data/lib/ruact.rb

@@ -10,12 +10,19 @@ require_relative "ruact/string_distance"
 require_relative "ruact/layout_source"
 require_relative "ruact/component_contract"
 require_relative "ruact/component_attributes"
+require_relative "ruact/markers"
+require_relative "ruact/request_kind"
+require_relative "ruact/inline_script"
 require_relative "ruact/erb_preprocessor"
 require_relative "ruact/render_context"
 require_relative "ruact/html_converter"
 require_relative "ruact/client_manifest"
 require_relative "ruact/manifest_resolver"
 require_relative "ruact/render_pipeline"
+require_relative "ruact/deferred_render"
+require_relative "ruact/cached_blocks"
+require_relative "ruact/query_watch"
+require_relative "ruact/declared_content"
 require_relative "ruact/view_helper"
 require_relative "ruact/erb_preprocessor_hook"
 require_relative "ruact/server_functions"

data/vendor/javascript/vite-plugin-ruact/bootstrap.test.mjs

@@ -56,15 +56,28 @@ describe("virtual:ruact/bootstrap — load (Story 14.2)", () => {
 
   it("imports the runtime modules via ABSOLUTE fs specifiers, not relative", () => {
     expect(src).toMatch(/from '\/.*\/runtime\/flight-modules\.js'/);
-    expect(src).toMatch(/import '\/.*\/runtime\/suspense-boundary\.js'/);
+    expect(src).toMatch(/from '\/.*\/runtime\/suspense-boundary\.js'/);
     expect(src).toMatch(/from '\/.*\/runtime\/ruact-router\.js'/);
-    // Story 18-1 — React's Flight client, through the plugin's virtual id.
-    expect(src).toContain("from 'virtual:ruact/flight-client'");
+    // The page is opened through page-stream.js, which reads React's Flight
+    // client through the plugin's virtual id (Story 18-1).
+    expect(src).toMatch(/from '\/.*\/runtime\/page-stream\.js'/);
     // No `\0virtual:`-unresolvable relative import survives.
     expect(src).not.toMatch(/(from|import)\s+['"]\.\/[\w.-]+\.js['"]/);
     expect(src).not.toMatch(/from\s+['"]\.\/ruact-router\.js['"]/);
   });
 
+  // Story 19-1 — the boundary handler is in place before the first render: a
+  // row that is already an error when the page mounts is caught during that
+  // first commit, before the router's effect runs.
+  it("installs the boundary error handler before it mounts, and mounts into the root once it exists", () => {
+    expect(src).toMatch(/from '\/.*\/runtime\/dev-overlay\.js'/);
+    expect(src.indexOf("setBoundaryErrorHandler((error)")).toBeGreaterThan(-1);
+    expect(src.indexOf("setBoundaryErrorHandler((error)")).toBeLessThan(src.indexOf("createRoot(container"));
+    expect(src).toContain("Promise.all([initialTree, whenRoot()])");
+    expect(src).toContain("openPage(documentRows(flightData))");
+    expect(src).toContain("setupRouter({ onNavigate: setCurrent, onBoundaryError })");
+  });
+
   it("contains no JSX syntax (loads via the default loader like the registry)", () => {
     expect(src).not.toContain("<App");
     expect(src).toContain("createElement(App)");

data/vendor/javascript/vite-plugin-ruact/page-mount.test.mjs

@@ -0,0 +1,75 @@
+// @vitest-environment jsdom
+//
+// Story 19-1 — the entry is `async`: it can run before the parser reaches the
+// page's `<div id="root">`, and a <Suspense> that failed on the server is shown
+// over the page in development.
+import { describe, it, expect } from "vitest";
+import { whenRoot } from "./runtime/page-stream.js";
+import { showDevOverlay } from "./runtime/dev-overlay.js";
+
+function loadingDocument() {
+  const doc = document.implementation.createHTMLDocument("page");
+  Object.defineProperty(doc, "readyState", { value: "loading", configurable: true });
+  return doc;
+}
+
+describe("whenRoot", () => {
+  it("gives the root at once when it is there", async () => {
+    const doc = document.implementation.createHTMLDocument("page");
+    doc.body.innerHTML = '<div id="root"></div>';
+    await expect(whenRoot(doc)).resolves.toBe(doc.getElementById("root"));
+  });
+
+  it("waits for a root the parser has not reached yet", async () => {
+    const doc = loadingDocument();
+    let found = null;
+    const waiting = whenRoot(doc).then((root) => { found = root; });
+    await new Promise((resolve) => setTimeout(resolve, 5));
+    expect(found).toBeNull();
+
+    const root = doc.createElement("div");
+    root.id = "root";
+    doc.body.appendChild(root);
+    await waiting;
+    expect(found).toBe(root);
+  });
+
+  it("gives up with null when the document ends without one", async () => {
+    const doc = loadingDocument();
+    const waiting = whenRoot(doc);
+    doc.dispatchEvent(new Event("DOMContentLoaded"));
+    await expect(waiting).resolves.toBeNull();
+  });
+});
+
+describe("showDevOverlay", () => {
+  it("shows the server's error over the page, and closes on a click", () => {
+    const cause = new Error("ArgumentError: boom in a block");
+    cause.stack = "ArgumentError: boom in a block\n    at app/views/posts/show.html.erb:4";
+    showDevOverlay(new Error("[ruact] Server error: ArgumentError: boom in a block", { cause }));
+
+    const overlay = document.getElementById("ruact-dev-overlay");
+    expect(overlay.querySelector("[data-overlay-message]").textContent).toBe("ArgumentError: boom in a block");
+    expect(overlay.querySelector("[data-overlay-stack]").textContent).toContain("show.html.erb:4");
+
+    overlay.click();
+    expect(document.getElementById("ruact-dev-overlay")).toBeNull();
+  });
+
+  // Story 19-2 (AC7) — every failure, in the one overlay.
+  it("shows each failure in the one overlay, and opens again after it was closed", () => {
+    showDevOverlay(new Error("first"));
+    showDevOverlay(new Error("second"));
+    const overlays = document.querySelectorAll("#ruact-dev-overlay");
+    expect(overlays).toHaveLength(1);
+    const messages = [...overlays[0].querySelectorAll("[data-overlay-message]")].map((el) => el.textContent);
+    expect(messages).toEqual(["first", "second"]);
+    expect(overlays[0].querySelector("[data-overlay-title]").textContent).toBe("[ruact] 2 <Suspense> failed on the server");
+    overlays[0].click();
+
+    showDevOverlay(new Error("third"));
+    const reopened = document.getElementById("ruact-dev-overlay");
+    expect([...reopened.querySelectorAll("[data-overlay-message]")].map((el) => el.textContent)).toEqual(["third"]);
+    reopened.click();
+  });
+});

data/vendor/javascript/vite-plugin-ruact/page-stream.test.mjs

@@ -0,0 +1,132 @@
+// The two ways a page is opened read the same way: the rows a document inlined
+// in `__FLIGHT_DATA`, and a fetch body that may end early.
+import { describe, it, expect } from "vitest";
+import { LEAVE_EVENT, documentRows, openPage } from "./runtime/page-stream.js";
+
+const encoder = new TextEncoder();
+
+function bodyOf(chunks, { error } = {}) {
+  return new ReadableStream({
+    start(controller) {
+      for (const chunk of chunks) controller.enqueue(encoder.encode(chunk));
+      if (error) controller.error(error);
+      else controller.close();
+    },
+  });
+}
+
+describe("openPage", () => {
+  it("opens the rows a document inlined, joined in the order they were pushed", async () => {
+    const page = openPage(documentRows(['1:"wor', 'ld"\n0:["hello","$1"]\n'], { readyState: "complete" }));
+    expect(await page.root).toEqual(["hello", "world"]);
+    await expect(page.end).resolves.toBeUndefined();
+  });
+
+  it("resolves the root at row 0, before a deferred row has arrived", async () => {
+    let push;
+    const body = new ReadableStream({
+      start(controller) {
+        controller.enqueue(encoder.encode('0:{"later":"$@1"}\n'));
+        push = (row) => {
+          controller.enqueue(encoder.encode(row));
+          controller.close();
+        };
+      },
+    });
+    const page = openPage(body);
+    const root = await page.root;
+    expect(root.later).toBeInstanceOf(Promise);
+
+    push('1:"arrived"\n');
+    await expect(root.later).resolves.toBe("arrived");
+    await expect(page.end).resolves.toBeUndefined();
+  });
+
+  it("labels a body that ends before the root as the transport's failure, and rejects the end", async () => {
+    const page = openPage(bodyOf([], { error: new TypeError("network down") }));
+    await expect(page.root).rejects.toMatchObject({ digest: "ruact:connection-closed" });
+    await expect(page.end).rejects.toThrow("network down");
+  });
+});
+
+// Story 19-1 — a page that streams: the document is still open when the
+// bootstrap runs, and pushes each <Suspense>'s rows as they are ready.
+describe("documentRows", () => {
+  function openDocument() {
+    const listeners = {};
+    return {
+      readyState: "loading",
+      addEventListener(type, listener) { listeners[type] = listener; },
+      removeEventListener(type) { delete listeners[type]; },
+      finish(state = "interactive") {
+        this.readyState = state;
+        listeners.readystatechange?.();
+      },
+      leave() {
+        listeners[LEAVE_EVENT]?.();
+        this.finish("complete");
+      },
+    };
+  }
+
+  it("reads what the queue holds, then each row pushed later, until the document ends", async () => {
+    const doc = openDocument();
+    const queue = ['0:{"later":"$@1"}\n'];
+    const page = openPage(documentRows(queue, doc));
+    const root = await page.root;
+    expect(root.later).toBeInstanceOf(Promise);
+
+    queue.push('1:"arrived"\n');
+    await expect(root.later).resolves.toBe("arrived");
+    expect(queue).toHaveLength(0);
+
+    doc.finish();
+    await expect(page.end).resolves.toBeUndefined();
+  });
+
+  it("keeps the stream open while the document loads, and closes it when the document ends", async () => {
+    const doc = openDocument();
+    const stream = documentRows(['0:"shell"\n'], doc);
+    const reader = stream.getReader();
+    await reader.read();
+    let closed = false;
+    const next = reader.read().then((result) => { closed = result.done; });
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    expect(closed).toBe(false);
+    doc.finish();
+    await next;
+    expect(closed).toBe(true);
+  });
+
+  // Story 19-2 — the router stops a document it leaves while it still loads.
+  it("closes when the document is stopped while loading", async () => {
+    const doc = openDocument();
+    const reader = documentRows(['0:"x"\n'], doc).getReader();
+    await reader.read();
+    doc.finish("complete");
+    await expect(reader.read()).resolves.toMatchObject({ done: true });
+  });
+
+  // Story 19-2 — the router leaving it: the page being left reports nothing,
+  // as for a superseded navigation.
+  it("ends as an aborted navigation when the router leaves the document", async () => {
+    const doc = openDocument();
+    const page = openPage(documentRows(['0:{"later":"$@1"}\n'], doc));
+    const root = await page.root;
+    doc.leave();
+    await expect(root.later).rejects.toMatchObject({ name: "AbortError" });
+    await expect(page.end).rejects.toMatchObject({ name: "AbortError" });
+  });
+
+  it("closes at once when the document has already ended", async () => {
+    const reader = documentRows(['0:"x"\n'], { readyState: "complete" }).getReader();
+    await reader.read();
+    await expect(reader.read()).resolves.toMatchObject({ done: true });
+  });
+
+  it("ignores a row pushed after the document ended instead of throwing", () => {
+    const queue = [];
+    documentRows(queue, { readyState: "complete" });
+    expect(() => queue.push('9:"late"\n')).not.toThrow();
+  });
+});

data/vendor/javascript/vite-plugin-ruact/ruact-router.test.mjs

@@ -14,6 +14,7 @@ import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
 import fs from "node:fs";
 import path from "node:path";
 import { setupRouter, teardownRouter } from "./runtime/ruact-router.js";
+import { LEAVE_EVENT } from "./runtime/page-stream.js";
 
 const ORIGIN = "http://localhost:3000";
 
@@ -568,3 +569,187 @@ describe("ruact-router — dates and big integers in a navigation (Story 17-0c)"
   });
 });
 
+
+// Story 19-2 — leaving a page whose document is still arriving (a page that
+// streams) stops loading it, so the server starts no further block for it.
+describe("leaving a document that is still loading", () => {
+  let dom;
+
+  beforeEach(() => {
+    dom = installDom();
+    globalThis.fetch = vi.fn().mockResolvedValue(respond({ body: '0:"next"\n' }));
+    globalThis.window.stop = vi.fn();
+    globalThis.__FLIGHT_DATA = Object.assign([], { streaming: true });
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    setupRouter({ onNavigate: vi.fn(), moduleRegistry: {}, onError: vi.fn() });
+  });
+
+  afterEach(() => {
+    teardownRouter();
+    delete globalThis.__FLIGHT_DATA;
+    vi.restoreAllMocks();
+  });
+
+  // A slow network, a long layout: the rest of the document after `#root`
+  // (which a navigation does not replace) still has to arrive.
+  it("leaves a loading document alone when it does not stream, or its rows are all in", async () => {
+    globalThis.document.readyState = "loading";
+    globalThis.__FLIGHT_DATA = [];
+    click(dom.listeners, "/products/2");
+    await settle();
+    globalThis.__FLIGHT_DATA = Object.assign([], { streaming: false });
+    click(dom.listeners, "/products/3");
+    await settle();
+    expect(window.stop).not.toHaveBeenCalled();
+    expect(fetch).toHaveBeenCalledTimes(2);
+  });
+
+  it("stops the document before it fetches the next page", async () => {
+    globalThis.document.readyState = "loading";
+    let stoppedBeforeFetch = null;
+    globalThis.fetch.mockImplementation(async () => {
+      stoppedBeforeFetch = window.stop.mock.calls.length === 1;
+      return respond({ body: '0:"next"\n' });
+    });
+    click(dom.listeners, "/products/2");
+    await settle();
+    expect(stoppedBeforeFetch).toBe(true);
+  });
+
+  it("leaves a document that has finished alone", async () => {
+    globalThis.document.readyState = "complete";
+    click(dom.listeners, "/products/2");
+    await settle();
+    expect(window.stop).not.toHaveBeenCalled();
+    expect(fetch).toHaveBeenCalled();
+  });
+
+  it("stops it for a form the router submits", async () => {
+    globalThis.document.readyState = "loading";
+    let stoppedBeforeFetch = null;
+    globalThis.fetch.mockImplementation(async () => {
+      stoppedBeforeFetch = window.stop.mock.calls.length === 1;
+      return respond({ body: '0:"next"\n' });
+    });
+    submit(dom.listeners, new dom.FakeForm({ action: "/people", method: "post" }));
+    await settle();
+    expect(stoppedBeforeFetch).toBe(true);
+  });
+
+  // Review 19-2a R3/R4 — a `#anchor` on the page on screen: the browser
+  // scrolls; nothing is fetched, and the document is not left.
+  it("leaves a popstate that only changes the hash to the browser", async () => {
+    globalThis.document.readyState = "loading";
+    location._set("/products/1#reviews");
+    dom.listeners.window.popstate.forEach((fn) => fn({}));
+    await settle();
+    expect(window.stop).not.toHaveBeenCalled();
+    expect(fetch).not.toHaveBeenCalled();
+  });
+
+  it("leaves a link to this page's #anchor to the browser", async () => {
+    globalThis.document.readyState = "loading";
+    const event = click(dom.listeners, "/products/1#reviews");
+    await settle();
+    expect(event.defaultPrevented).toBe(false);
+    expect(window.stop).not.toHaveBeenCalled();
+    expect(fetch).not.toHaveBeenCalled();
+  });
+
+  // Review 19-2a R4 — as a browser does: once stopped, the document no longer
+  // loads, so a later navigation does not stop it again.
+  function stopForReal() {
+    globalThis.document.readyState = "loading";
+    window.stop.mockImplementation(() => { globalThis.document.readyState = "complete"; });
+  }
+
+  it("fetches the page again when the navigation that superseded the one that stopped it fails", async () => {
+    stopForReal();
+    const html500 = respond({ status: 500, contentType: "text/html", body: "<p>boom</p>" });
+    globalThis.fetch
+      .mockImplementationOnce((_url, { signal }) => new Promise((_resolve, reject) => {
+        signal.addEventListener("abort", () => reject(new DOMException("aborted", "AbortError")));
+      }))
+      .mockResolvedValueOnce(html500)
+      .mockResolvedValue(respond({ body: '0:"again"\n' }));
+    const form = new dom.FakeForm({ action: "/people", method: "post" });
+    submit(dom.listeners, form);
+    submit(dom.listeners, form);
+    await settle();
+    await settle();
+    expect(window.stop).toHaveBeenCalledTimes(1);
+    expect(fetch.mock.calls.map((call) => call[0])).toEqual(["/people", "/people", "/products/1"]);
+  });
+
+  it("fetches the page again when the redirect a form was answered with fails", async () => {
+    stopForReal();
+    globalThis.fetch
+      .mockResolvedValueOnce(respond({ body: '0:{"redirectUrl":"/people/9","redirectType":"push"}\n' }))
+      .mockRejectedValueOnce(new TypeError("Failed to fetch"))
+      .mockResolvedValue(respond({ body: '0:"again"\n' }));
+    submit(dom.listeners, new dom.FakeForm({ action: "/people", method: "post" }));
+    await settle();
+    await settle();
+    expect(fetch.mock.calls.map((call) => call[0])).toEqual(["/people", "/people/9", "/products/1"]);
+  });
+
+  it("does not fetch the page again once a navigation replaced it", async () => {
+    stopForReal();
+    globalThis.fetch.mockResolvedValue(respond({ body: '0:"next"\n' }));
+    click(dom.listeners, "/products/2");
+    await settle();
+    globalThis.fetch.mockRejectedValue(new TypeError("Failed to fetch"));
+    click(dom.listeners, "/products/3");
+    await settle();
+    await settle();
+    expect(fetch.mock.calls.map((call) => call[0])).toEqual(["/products/2", "/products/3"]);
+  });
+
+  // Review 19-2a R3 — the navigation that stopped the document failed: the user
+  // is still on that page, whose boundaries would keep their fallback.
+  it("fetches the page again when the navigation that stopped it fails", async () => {
+    globalThis.document.readyState = "loading";
+    globalThis.fetch
+      .mockRejectedValueOnce(new TypeError("Failed to fetch"))
+      .mockResolvedValue(respond({ body: '0:"again"\n' }));
+    submit(dom.listeners, new dom.FakeForm({ action: "/people", method: "post" }));
+    await settle();
+    await settle();
+    expect(window.stop).toHaveBeenCalledTimes(1);
+    expect(fetch).toHaveBeenCalledTimes(2);
+    expect(fetch.mock.calls[1][0]).toBe("/products/1");
+  });
+
+  it("does not fetch the page again after a failure when nothing was stopped", async () => {
+    globalThis.document.readyState = "complete";
+    globalThis.fetch.mockRejectedValue(new TypeError("Failed to fetch"));
+    submit(dom.listeners, new dom.FakeForm({ action: "/people", method: "post" }));
+    await settle();
+    await settle();
+    expect(fetch).toHaveBeenCalledTimes(1);
+  });
+
+  // revalidate() stays on the page: stopping the document would also fail the
+  // page's other requests in flight (a server function, a useQuery).
+  it("leaves the document loading for revalidate()", async () => {
+    globalThis.document.readyState = "loading";
+    await globalThis.__ruact_revalidate();
+    expect(window.stop).not.toHaveBeenCalled();
+    expect(fetch).toHaveBeenCalledTimes(1);
+  });
+
+  // Stopped, the document's rows would read as a response cut short, which
+  // the page being left reports: they are told first.
+  it("tells the document's rows it is left before it stops it", async () => {
+    globalThis.document.readyState = "loading";
+    const told = [];
+    globalThis.document.dispatchEvent = vi.fn((event) => {
+      told.push([event.type, window.stop.mock.calls.length]);
+      return true;
+    });
+    click(dom.listeners, "/products/2");
+    await settle();
+    expect(told).toEqual([[LEAVE_EVENT, 0]]);
+    expect(window.stop).toHaveBeenCalledTimes(1);
+  });
+});

data/vendor/javascript/vite-plugin-ruact/runtime/bootstrap.jsx

@@ -18,15 +18,16 @@
 //     transforming a `\0virtual:` id.
 import { createRoot } from 'react-dom/client';
 import { createElement, useState, useEffect } from 'react';
-// Story 18-1 — React's own Flight client: the copy vendored in the gem, or the
-// app's `react-server-dom-webpack` when installed (the plugin decides).
-import { createFromReadableStream } from 'virtual:ruact/flight-client';
 import { setModuleRegistry } from './flight-modules.js';
 // Registers the boundary the server wraps each Suspense child in.
-import './suspense-boundary.js';
+import { setBoundaryErrorHandler } from './suspense-boundary.js';
 import { RootBoundary, onCaughtError } from './root-boundary.js';
-import { labelledStream } from './transport.js';
+// The page, opened from its Flight bytes with React's own Flight client (the
+// copy vendored in the gem, or the app's `react-server-dom-webpack` when it
+// declares one: the plugin decides).
+import { documentRows, openPage, whenRoot } from './page-stream.js';
 import { setupRouter, teardownRouter } from './ruact-router.js';
+import { showDevOverlay } from './dev-overlay.js';
 
 // MODULE_REGISTRY maps react-client-manifest "id" values to component exports.
 // It is auto-derived by vite-plugin-ruact from the SAME scan that emits
@@ -56,31 +57,35 @@ if (!flightData || flightData.length === 0) {
     root.textContent = '[ruact] No Flight data found — is the Rails server running?';
   }
 } else {
-  // The inline payload, as the stream the client reads. The root is mounted
-  // once the tree resolves, so the first paint is the page, not a fallback.
-  const bytes = new TextEncoder().encode(flightData.join(''));
-  const stream = new ReadableStream({
-    start(controller) {
-      controller.enqueue(bytes);
-      controller.close();
-    },
+  // Story 19-1 — in development a <Suspense> that failed on the server is shown
+  // over the page. The handler is in place before anything renders: a row that
+  // is already an error when the page mounts is caught during that first
+  // commit, before the router's effect would install one.
+  const onBoundaryError = import.meta.env?.DEV ? (error) => showDevOverlay(error) : null;
+  setBoundaryErrorHandler((error) => {
+    console.error(error.message);
+    onBoundaryError?.(error);
   });
 
+  // The document's rows, as the stream the client reads — open while the
+  // document is: a page that streams pushes each <Suspense>'s rows as they are
+  // ready. The root is mounted once the tree resolves, so the first paint is
+  // the page with its fallbacks.
   let initialTree;
   try {
-    initialTree = createFromReadableStream(labelledStream(stream));
+    initialTree = openPage(documentRows(flightData)).root;
   } catch (err) {
     showBootError(err);
     throw err;
   }
 
-  initialTree.then(
-    (tree) => {
+  Promise.all([initialTree, whenRoot()]).then(
+    ([tree, container]) => {
       function App() {
         const [current, setCurrent] = useState(() => tree);
 
         useEffect(() => {
-          setupRouter({ onNavigate: setCurrent });
+          setupRouter({ onNavigate: setCurrent, onBoundaryError });
           return () => teardownRouter();
         }, []);
 
@@ -88,7 +93,7 @@ if (!flightData || flightData.length === 0) {
         return createElement(RootBoundary, { tree: current }, current);
       }
 
-      createRoot(document.getElementById('root'), { onCaughtError }).render(createElement(App));
+      createRoot(container, { onCaughtError }).render(createElement(App));
     },
     (err) => {
       showBootError(err);

data/vendor/javascript/vite-plugin-ruact/runtime/dev-overlay.js

@@ -0,0 +1,53 @@
+// Story 19-1 (ADR D5) — in development, a `<Suspense>` whose content failed on
+// the server is shown over the page: what failed, and where in the templates.
+// Production shows nothing of the error; the boundary keeps its fallback.
+//
+// The boundary hands the error to the handler ./suspense-boundary.js was given
+// (the bootstrap installs one before the first render, the router keeps it).
+// React's development client rebuilds the server's backtrace into the error's
+// `stack`.
+
+const OVERLAY_ID = "ruact-dev-overlay";
+
+/**
+ * Shows +error+ over the page, under the ones already shown (Story 19-2: one
+ * entry per failed <Suspense>); a click closes the overlay, and the next
+ * failure opens it again.
+ */
+export function showDevOverlay(error, doc = globalThis.document) {
+  const cause = error?.cause ?? error;
+  let overlay = doc.getElementById(OVERLAY_ID);
+  if (!overlay) {
+    overlay = doc.createElement("div");
+    overlay.id = OVERLAY_ID;
+    overlay.setAttribute("role", "alertdialog");
+    overlay.setAttribute("aria-label", "A <Suspense> failed on the server");
+    overlay.style.cssText =
+      "position:fixed;inset:0;z-index:2147483647;background:rgba(24,6,6,.94);color:#fff;" +
+      "font:14px/1.5 ui-monospace,SFMono-Regular,Menlo,monospace;padding:32px;overflow:auto;" +
+      "white-space:pre-wrap;cursor:pointer";
+    overlay.addEventListener("click", () => overlay.remove());
+    const title = doc.createElement("h2");
+    title.dataset.overlayTitle = "";
+    const hint = doc.createElement("p");
+    hint.dataset.overlayHint = "";
+    hint.textContent = "Development only. Click to close.";
+    overlay.append(title, hint);
+    (doc.body ?? doc.documentElement).appendChild(overlay);
+  }
+
+  const entry = doc.createElement("section");
+  entry.dataset.overlayEntry = "";
+  const message = doc.createElement("p");
+  message.dataset.overlayMessage = "";
+  message.textContent = cause?.message ?? String(cause);
+  const stack = doc.createElement("pre");
+  stack.dataset.overlayStack = "";
+  stack.textContent = cause?.stack ?? "";
+  entry.append(message, stack);
+  overlay.insertBefore(entry, overlay.querySelector("[data-overlay-hint]"));
+
+  const count = overlay.querySelectorAll("[data-overlay-entry]").length;
+  overlay.querySelector("[data-overlay-title]").textContent =
+    count === 1 ? "[ruact] A <Suspense> failed on the server" : `[ruact] ${count} <Suspense> failed on the server`;
+}