From c53086b06d2a005a1d78b73652b409338277e91b Mon Sep 17 00:00:00 2001
From: Thales <>
Date: Sat, 12 Sep 2026 02:47:18 +0100
Subject: [PATCH] Say why the app did not start, instead of showing a dead one

main.js wires the UI in a synchronous run of fifteen wireX() calls and only
registers its own error handlers at the end of the module. A throw anywhere in
that run does two things at once: every listener after it never attaches, and
the handlers that would have reported it never register either.

What the user gets is an app that hovers and lets them type, because the engine
does that itself, but whose buttons and file drop do nothing because nothing is
listening. Nothing is written anywhere. There was no earlier error capture in
the frontend, and CSP script-src 'self' forbids adding an inline one to the
HTML.

boot-diagnostics.js is loaded before main.js and shows the failure in the page.
It follows three rules so it still works when main.js does not: it imports
nothing, since an import is a second thing that can fail in exactly these
circumstances; it styles itself inline, since it cannot assume a stylesheet
loaded; and it listens in the capture phase, because a module that 404s fires
its error on the element and never bubbles to window.

Its strings are English and do not go through i18n. That is deliberate and is
the one place in the UI where it is correct: i18n.js is itself a module that can
fail to load, and a banner that renders nothing when translation is broken
defeats the point of having it.

One honest limit, asserted in the tests rather than papered over: when a
dependency 404s, the banner names main.js and not the missing file. The module
loader fetches dependencies itself, so no per-file error event exists to catch.
Which file is missing is a uvicorn access line in backend.log, which is why the
banner points at /api/logs/backend rather than pretending to know.

Four browser tests cover a module that fails to load, a throw during wiring,
that the detail is selectable and the banner dismissable, and that a healthy
page shows nothing. The first three fail without the script tag; verified by
removing it.

Refs #618, and the investigation behind #617.
---
 static/index.html               |   3 +
 static/js/boot-diagnostics.js   | 130 ++++++++++++++++++++++++++++++++
 tests/e2e/boot-failure.spec.mjs |  83 ++++++++++++++++++++
 3 files changed, 216 insertions(+)
 create mode 100644 static/js/boot-diagnostics.js
 create mode 100644 tests/e2e/boot-failure.spec.mjs

diff --git a/static/index.html b/static/index.html
index d7862198..5db0a9ab 100644
--- a/static/index.html
+++ b/static/index.html
@@ -1087,6 +1087,9 @@ <h2 id="failureTitle" data-i18n="failure.title">Something failed</h2>
       </div>
     </div>
 
+    <!-- First, so its handlers are installed before main.js is evaluated and
+         can report a failure to parse, resolve an import, or wire the UI. -->
+    <script type="module" src="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/js/boot-diagnostics.js"></script>
     <script type="module" src="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/js/main.js"></script>
     <script type="module" src="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/js/ui-chrome.js"></script>
   </body>
diff --git a/static/js/boot-diagnostics.js b/static/js/boot-diagnostics.js
new file mode 100644
index 00000000..8a3e885e
--- /dev/null
+++ b/static/js/boot-diagnostics.js
@@ -0,0 +1,130 @@
+// Catch and show a failure that happens while the app is wiring itself up.
+//
+// main.js wires the UI in a long synchronous run of wireX() calls and only
+// registers its own error handlers near the end of the module. A throw anywhere
+// in that run therefore does two things at once: every listener after it never
+// attaches, and the handlers that would have reported it never register either.
+// What the user gets is an app that hovers and lets them type, because that is
+// the engine's own behaviour, but whose buttons and file drop do nothing,
+// because nothing is listening. Nothing is written anywhere (#618, found via
+// #617).
+//
+// This module exists to be the thing that still works when that happens, so it
+// follows three rules:
+//
+//   1. It is loaded BEFORE main.js in index.html. Module scripts execute in
+//      document order, so its handlers are installed before main.js is
+//      evaluated and are in place for anything main.js does, including a
+//      failure to parse or to resolve an import.
+//   2. It imports nothing. An import is a second thing that can fail, and it
+//      would fail in exactly the circumstances this module needs to survive.
+//   3. It styles itself inline. It cannot rely on a stylesheet having loaded,
+//      and CSP allows inline style (`style-src 'self' 'unsafe-inline'`) while
+//      forbidding inline script, which is also why this is a file rather than a
+//      <script> block in the HTML.
+//
+// The strings here are deliberately English and do not go through i18n, which
+// is the one place in the UI where that is correct: i18n.js is itself a module
+// that can fail to load, and a banner that renders nothing when translation is
+// broken defeats the entire point. An untranslated explanation beats a silent
+// dead app.
+
+(function () {
+  const BANNER_ID = "boot-failure";
+  let reported = false;
+
+  function detailFrom(event) {
+    if (event.type === "unhandledrejection") {
+      const reason = event.reason;
+      if (reason instanceof Error) return `${reason.message}\n${reason.stack || ""}`;
+      return String(reason);
+    }
+    // A resource that failed to load (a module that 404s, say) fires an error
+    // event on the element itself with no message, rather than a script error.
+    const target = event.target;
+    if (target && target !== window && (target.src || target.href)) {
+      return `Failed to load: ${target.src || target.href}`;
+    }
+    const where = event.filename ? `\n${event.filename}:${event.lineno}:${event.colno}` : "";
+    const stack = event.error && event.error.stack ? `\n${event.error.stack}` : "";
+    return `${event.message || "Unknown error"}${where}${stack}`;
+  }
+
+  function show(detail) {
+    // Only the first failure is shown. A broken wiring run usually produces
+    // several, and the first is the one that caused the rest.
+    if (reported) return;
+    reported = true;
+
+    const build = () => {
+      if (document.getElementById(BANNER_ID)) return;
+
+      const bar = document.createElement("div");
+      bar.id = BANNER_ID;
+      bar.setAttribute("role", "alert");
+      bar.style.cssText = [
+        "position:fixed", "inset:0 0 auto 0", "z-index:2147483647",
+        "background:#3b1111", "color:#f6e9e9", "border-bottom:1px solid #d65a4a",
+        "padding:14px 16px", "font:13px/1.5 system-ui,sans-serif",
+        "max-height:50vh", "overflow:auto", "box-shadow:0 4px 24px rgba(0,0,0,0.4)",
+      ].join(";");
+
+      const title = document.createElement("strong");
+      title.textContent = "StemDeck did not finish starting up.";
+      title.style.cssText = "display:block;font-size:14px;margin-bottom:6px";
+
+      const lead = document.createElement("div");
+      lead.textContent =
+        "Part of the interface never loaded, so buttons and file drop will not "
+        + "respond. Hovering and typing still work because the browser handles "
+        + "those itself. The cause is below. Please include it if you report this.";
+      lead.style.cssText = "margin-bottom:10px;max-width:80ch";
+
+      const pre = document.createElement("pre");
+      pre.textContent = detail;
+      // user-select is explicit because the app sets it to none in places, and
+      // this text is the whole reason the banner exists.
+      pre.style.cssText = [
+        "margin:0 0 10px", "padding:8px 10px", "background:#2a0d0d",
+        "border:1px solid #5c2222", "border-radius:6px", "white-space:pre-wrap",
+        "word-break:break-word", "user-select:text", "-webkit-user-select:text",
+        "font:12px/1.45 ui-monospace,Consolas,monospace",
+      ].join(";");
+
+      const hint = document.createElement("div");
+      hint.textContent =
+        "The full backend log is at /api/logs.zip, and the raw backend output at "
+        + "/api/logs/backend. Both help identify whether a file failed to load.";
+      hint.style.cssText = "opacity:0.85;margin-bottom:10px";
+
+      const dismiss = document.createElement("button");
+      dismiss.type = "button";
+      dismiss.textContent = "Dismiss";
+      dismiss.style.cssText = [
+        "background:#5c2222", "color:#f6e9e9", "border:1px solid #d65a4a",
+        "border-radius:6px", "padding:5px 12px", "cursor:pointer", "font:inherit",
+      ].join(";");
+      dismiss.addEventListener("click", () => bar.remove());
+
+      bar.append(title, lead, pre, hint, dismiss);
+      document.body.prepend(bar);
+    };
+
+    if (document.body) build();
+    else document.addEventListener("DOMContentLoaded", build, { once: true });
+  }
+
+  function handle(event) {
+    const detail = detailFrom(event);
+    // Still log it. In a browser the console is the faster route, and this runs
+    // before main.js installs its own logging.
+    console.error("[boot]", detail);
+    show(detail);
+  }
+
+  // Capture phase, because a resource load failure fires on the element and
+  // does not bubble. A bubbling-phase listener on window never sees a module
+  // that 404s, which is one of the two causes this needs to tell apart.
+  window.addEventListener("error", handle, true);
+  window.addEventListener("unhandledrejection", handle);
+})();
diff --git a/tests/e2e/boot-failure.spec.mjs b/tests/e2e/boot-failure.spec.mjs
new file mode 100644
index 00000000..dfd4a173
--- /dev/null
+++ b/tests/e2e/boot-failure.spec.mjs
@@ -0,0 +1,83 @@
+// A failure while the app wires itself up must be visible and quotable.
+//
+// Before boot-diagnostics.js existed, both cases below produced an app that
+// hovered and accepted typing but whose buttons did nothing, with nothing
+// logged anywhere, because main.js registers its own error handlers only after
+// the wiring run that failed (#618, reported as #617).
+//
+// Both tests fail without static/js/boot-diagnostics.js loaded first.
+
+import { test, expect } from "@playwright/test";
+
+const BANNER = "#boot-failure";
+
+test("a module that fails to load is reported in the UI", async ({ page }) => {
+  // The missing-file case: a JS file quarantined by antivirus or lost in a
+  // partial unzip. main.js cannot resolve the import and never evaluates, so
+  // nothing it would have registered exists.
+  await page.route("**/js/catalog.js", (route) => route.fulfill({ status: 404, body: "" }));
+
+  await page.goto("/");
+
+  const banner = page.locator(BANNER);
+  await expect(banner).toBeVisible();
+  await expect(banner).toContainText("StemDeck did not finish starting up");
+
+  // The banner names main.js, not catalog.js, and that is the honest limit of
+  // what the page can know: the module loader fetches dependencies itself, so a
+  // dependency that 404s produces no per-file error event. What surfaces is the
+  // entry module whose graph failed to resolve.
+  //
+  // Which file is missing is answerable, just not from here: the 404 is a
+  // uvicorn access line in backend.log. That is why the banner points at
+  // /api/logs/backend rather than pretending to know.
+  await expect(banner).toContainText("Failed to load");
+  await expect(banner).toContainText("main.js");
+  await expect(banner).toContainText("/api/logs/backend");
+});
+
+test("a throw during wiring is reported in the UI", async ({ page }) => {
+  // The other cause with the same symptom: every file loads, and one of the
+  // wireX() calls throws.
+  await page.route("**/js/main.js", (route) =>
+    route.fulfill({
+      status: 200,
+      contentType: "application/javascript",
+      body: 'throw new Error("wiring blew up");',
+    }),
+  );
+
+  await page.goto("/");
+
+  const banner = page.locator(BANNER);
+  await expect(banner).toBeVisible();
+  await expect(banner).toContainText("wiring blew up");
+});
+
+test("the detail can be selected, and the banner can be dismissed", async ({ page }) => {
+  // The text exists to be copied into a bug report, and the app sets
+  // user-select: none in places, so the banner sets it back explicitly.
+  await page.route("**/js/main.js", (route) =>
+    route.fulfill({
+      status: 200,
+      contentType: "application/javascript",
+      body: 'throw new Error("selectable please");',
+    }),
+  );
+
+  await page.goto("/");
+
+  const pre = page.locator(`${BANNER} pre`);
+  await expect(pre).toHaveCSS("user-select", "text");
+
+  await page.locator(`${BANNER} button`).click();
+  await expect(page.locator(BANNER)).toHaveCount(0);
+});
+
+test("a healthy page shows no banner", async ({ page }) => {
+  // Guards the obvious regression: a banner that appears when nothing is wrong
+  // would be worse than no banner at all.
+  await page.goto("/");
+  await expect(page.locator("#url")).toBeVisible();
+  await expect(page.locator(BANNER)).toHaveCount(0);
+});