From 7d68ff00e2873306e8f4e722243fa39a205d7987 Mon Sep 17 00:00:00 2001
From: "@permadeath.com" <did:plc:nlzmjyfv6loqtxyzvdcznwgf>
Date: Wed, 12 Aug 2026 17:41:01 -0400
Subject: [PATCH] fix(web): keep the front page up when the control plane is
 not
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The router read the session before putting Home up, and a failed read went
to the error screen. Everything on Home but the sign-in panel — the
headline, the pitch, the three facts, the footer — is in the bundle that
was just served off S3 and asks the API for nothing, so an API outage was
telling strangers the site was broken instead of what the site is.

Home now takes a panel rather than a session, and the third state fills the
sign-in form's place with the message and a Try again. Not the form with an
error over it: whatever stopped /api/session will stop /api/login too,
which was the error screen's reason and is the half worth keeping. Matches
still gets the error screen, having nothing to show without the API.
---
 TODO.md                             |  13 +++
 web/scripts/outage-panel.fixture.ts |   7 ++
 web/scripts/outage-panel.test.mjs   | 132 ++++++++++++++++++++++++++++
 web/src/outage-panel.ts             |  46 ++++++++++
 web/src/router.ts                   |  45 +++++++---
 web/src/screens/home.ts             |  44 ++++++++--
 web/src/styles.css                  |   9 +-
 7 files changed, 272 insertions(+), 24 deletions(-)
 create mode 100644 web/scripts/outage-panel.fixture.ts
 create mode 100644 web/scripts/outage-panel.test.mjs
 create mode 100644 web/src/outage-panel.ts

diff --git a/TODO.md b/TODO.md
index 906d2d5..26cab8f 100644
--- a/TODO.md
+++ b/TODO.md
@@ -232,6 +232,19 @@ rediscovering them:
       `web/src/signin-form.ts`, and what it says about the grant is already
       true. The waiting screen's lines are off the list too: they rotate real
       trivia from `web/src/content/trivia.csv` now.
+- [x] **An unreachable API used to take the front page down with it.** The
+      router read the session before putting Home up, and a failed read went to
+      the error screen — so a stranger arriving while headquarters-api was down
+      was told the site was broken rather than what the site is, even though
+      the headline, the pitch, the three facts and the footer had all just been
+      served off S3 and asked the API for nothing.
+
+      Home now keeps all of that and replaces one panel: the sign-in form's
+      place holds the message and a Try again, from `web/src/outage-panel.ts`.
+      Not the form with an error over it — whatever stopped `/api/session` will
+      stop `/api/login` too, which was the original reason for the error
+      screen and is the half worth keeping. Matches still gets the error
+      screen, because that screen is nothing but what the API answers.
 - [ ] **The hero's host list goes stale on its own.** The pitch ends on a name
       that rotates through account hosts — `HOSTS` in `web/src/host-cycle.ts`,
       checked against the community PDS list on
diff --git a/web/scripts/outage-panel.fixture.ts b/web/scripts/outage-panel.fixture.ts
new file mode 100644
index 0000000..922449f
--- /dev/null
+++ b/web/scripts/outage-panel.fixture.ts
@@ -0,0 +1,7 @@
+/**
+ * The panel the hero shows when the control plane cannot be reached.
+ *
+ * Bundled by outage-panel.test.mjs, the way profile.fixture.ts is, because the
+ * module under test is TypeScript with extensionless imports.
+ */
+export { outagePanel } from "../src/outage-panel";
diff --git a/web/scripts/outage-panel.test.mjs b/web/scripts/outage-panel.test.mjs
new file mode 100644
index 0000000..f6502c7
--- /dev/null
+++ b/web/scripts/outage-panel.test.mjs
@@ -0,0 +1,132 @@
+/**
+ * The panel that stands in for the sign-in form when the API is down must not
+ * be a sign-in form.
+ *
+ * The whole reason the front page used to throw itself away during an outage
+ * was the reasoning in router.ts: a form that cannot submit is worse than no
+ * form, so rather than show one the router showed the error screen instead —
+ * and took the headline, the pitch and the three facts down with it, none of
+ * which ever asked the API for anything.
+ *
+ * Keeping the page therefore only works while the panel keeps the other half
+ * of that bargain. A field added here later would collect a handle and fail
+ * with it, silently and on the front page, so this asserts the absence: no
+ * form, no input, and an alert a screen reader is actually told about.
+ *
+ * A real test rather than a source read, which outage-panel.ts is written to
+ * allow: it imports ./dom and nothing else, so the fake below is enough. Its
+ * neighbours in the hero cannot be tested this way — chrome.ts asks the API
+ * for its version at import time, which is right in a browser and wrong here.
+ *
+ * The module under test is TypeScript with extensionless imports, so this
+ * bundles it the way profile.test.mjs does. Run with `npm test`.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+// The same shape dom.test.mjs uses, plus the listener el() never touches and
+// this panel's button does.
+class FakeElement {
+  constructor(tag) {
+    this.tagName = tag.toUpperCase();
+    this.attributes = {};
+    this.children = [];
+    this.listeners = {};
+  }
+  setAttribute(name, value) {
+    this.attributes[name] = value;
+  }
+  append(...nodes) {
+    this.children.push(...nodes);
+  }
+  addEventListener(type, handler) {
+    this.listeners[type] = handler;
+  }
+  /** Every element in the tree, this one included. */
+  *walk() {
+    yield this;
+    for (const child of this.children) if (child.walk) yield* child.walk();
+  }
+}
+
+globalThis.document = { createElement: (tag) => new FakeElement(tag) };
+
+const run = promisify(execFile);
+const web = join(new URL(".", import.meta.url).pathname, "..");
+
+const dir = await mkdtemp(join(tmpdir(), "outage-panel-"));
+const bundle = join(dir, "fixture.mjs");
+await run(
+  join(web, "node_modules/.bin/rolldown"),
+  [
+    join(web, "scripts/outage-panel.fixture.ts"),
+    "--format",
+    "esm",
+    "--platform",
+    "node",
+    "--file",
+    bundle,
+  ],
+  { cwd: web },
+);
+
+const { outagePanel } = await import(bundle);
+
+/** The message api.ts writes when fetch itself could not reach the API. */
+const MESSAGE = "Cannot reach the control plane.";
+
+test("the panel asks for nothing", () => {
+  const panel = outagePanel(MESSAGE, () => {});
+  const tags = [...panel.walk()].map((node) => node.tagName);
+
+  for (const asking of ["FORM", "INPUT", "SELECT", "TEXTAREA"]) {
+    assert.ok(
+      !tags.includes(asking),
+      `the outage panel grew a <${asking.toLowerCase()}> — whatever stopped ` +
+        `/api/session will stop the submit too`,
+    );
+  }
+});
+
+test("the message is announced, not just printed", () => {
+  const panel = outagePanel(MESSAGE, () => {});
+  // A property and not an attribute, because `role` has no hyphen and el()
+  // splits on that — which is a real assignment in a browser, where role is
+  // reflected. See dom.test.mjs for why that split exists at all.
+  const alert = [...panel.walk()].find((node) => node.role === "alert");
+
+  assert.ok(
+    alert,
+    "nothing on the panel is an alert — a player who pressed Sign in and got " +
+      "this panel back is told nothing",
+  );
+  assert.equal(alert.textContent, MESSAGE);
+});
+
+test("try again runs the retry, once per press", () => {
+  let asked = 0;
+  const panel = outagePanel(MESSAGE, () => {
+    asked += 1;
+  });
+  const button = [...panel.walk()].find((node) => node.tagName === "BUTTON");
+
+  assert.ok(button, "the panel has no way out of the outage");
+  // type="button" and not a submit: there is no form, and a bare <button>
+  // inside one would submit it.
+  assert.equal(button.type, "button");
+
+  button.listeners.click();
+
+  assert.equal(asked, 1);
+  // Disabled rather than left live, so a player pressing it three times does
+  // not queue three session reads against an API that is already not
+  // answering. start() re-renders the panel, which is what re-enables it.
+  assert.equal(button.disabled, true);
+});
+
+test.after(() => rm(dir, { recursive: true, force: true }));
diff --git a/web/src/outage-panel.ts b/web/src/outage-panel.ts
new file mode 100644
index 0000000..1bfae5c
--- /dev/null
+++ b/web/src/outage-panel.ts
@@ -0,0 +1,46 @@
+/**
+ * What the hero's panel says when the control plane cannot be reached.
+ *
+ * The front page is static and knows it: the headline, the pitch and the three
+ * facts are in this bundle and ask the API for nothing. The one thing on it
+ * that does need the API is signing in — so an unreachable control plane costs
+ * the panel, and must not cost the page.
+ *
+ * Not the sign-in form with an error over it. Whatever stopped `/api/session`
+ * will stop `/api/login` too, so a handle field here would take a handle and
+ * fail with it. The panel says the site cannot be signed into and offers the
+ * one thing that ever helps, which is asking again.
+ *
+ * No prose of its own, deliberately: the message is the one api.ts already
+ * writes for an unreachable API, and the button says what it does. The card
+ * has no heading for the same reason the error screen's card has none — the
+ * page it sits on already has its h1. Nothing here is a placeholder waiting on
+ * a human, because nothing here is copy.
+ *
+ * `card` is the class the sign-in form shares its base look with, so the panel
+ * this stands in for and this one are the same object in the same place; only
+ * the hero's own translucency rule has to name it as well.
+ */
+
+import { el } from "./dom";
+
+/**
+ * The panel, and the button that re-runs whatever the caller passes.
+ *
+ * `retry` is the router's own start(), so pressing this reads the session
+ * again and puts up whichever screen it should have been all along — the
+ * signed-in home included, if the outage was over by then.
+ */
+export function outagePanel(message: string, retry: () => void): HTMLElement {
+  const again = el("button", { type: "button", textContent: "Try again" });
+  again.addEventListener("click", () => {
+    again.disabled = true;
+    again.textContent = "Retrying…";
+    retry();
+  });
+
+  return el("section", { className: "card hero-outage" }, [
+    el("p", { className: "error", role: "alert", textContent: message }),
+    el("div", { className: "row" }, [again]),
+  ]);
+}
diff --git a/web/src/router.ts b/web/src/router.ts
index a62a6fc..e6ff836 100644
--- a/web/src/router.ts
+++ b/web/src/router.ts
@@ -154,23 +154,42 @@ export async function start(): Promise<void> {
       );
     }
 
-    render(...homeScreen(session, error));
+    render(
+      ...homeScreen(
+        session ? { kind: "signedIn", session } : { kind: "signedOut", error },
+      ),
+    );
   } catch (err) {
     // The screen only ever shows the message. Keep the error itself where a
     // bug report can find it.
     console.error("start: the session could not be read", err);
-    // The sign-in form would be a lie here: whatever stopped /api/session will
-    // stop /api/login too.
-    render(
-      ...errorScreen(
-        err instanceof ApiError
-          ? err.message
-          : "The control plane did not answer as expected.",
-        () => {
-          void start();
-        },
-      ),
-    );
+    const message =
+      err instanceof ApiError
+        ? err.message
+        : "The control plane did not answer as expected.";
+    const retry = () => {
+      void start();
+    };
+
+    // Matches is nothing but what the API answers — the list, the scenarios,
+    // the opponents — so there is no page underneath to keep, and the error
+    // screen is the page. It is the only route that gets here and is not Home:
+    // camo, faq and about returned above without ever reading a session.
+    if (route === "matches") {
+      render(...errorScreen(message, retry));
+      return;
+    }
+
+    // Home is the opposite. Its headline, its pitch and its three facts are in
+    // this bundle and came off the same static host that served the page, so
+    // an unreachable API costs exactly one panel. Throwing the front page away
+    // over it meant a stranger arriving during an outage was told the site was
+    // broken instead of what the site is.
+    //
+    // The sign-in form would still be a lie — whatever stopped /api/session
+    // will stop /api/login too — so the panel is not the form with an error
+    // over it. See outage-panel.ts.
+    render(...homeScreen({ kind: "unreachable", message, retry }));
   }
 }
 
diff --git a/web/src/screens/home.ts b/web/src/screens/home.ts
index 9f05219..be142e2 100644
--- a/web/src/screens/home.ts
+++ b/web/src/screens/home.ts
@@ -1,10 +1,17 @@
 /**
  * Home: the front of the site, whoever is looking at it.
  *
- * One composition, in two states that differ by one panel. The framed hero with
- * the insignia cropped by its own right edge, the pitch, and the three facts
- * under it are the site's front page and stay the front page after signing in —
- * what changes is that the sign-in form is replaced by the player's pilot card.
+ * One composition, in three states that differ by one panel. The framed hero
+ * with the insignia cropped by its own right edge, the pitch, and the three
+ * facts under it are the site's front page and stay the front page after
+ * signing in — what changes is that the sign-in form is replaced by the
+ * player's pilot card, or, when the control plane cannot be reached, by the
+ * one line that says so.
+ *
+ * That third state is why the panel is a parameter rather than a session. This
+ * page is served from S3 and holds its own copy of everything on it, so it is
+ * up whenever the bucket is; the API being down costs signing in and nothing
+ * else, and the page has to keep saying what the site is either way.
  *
  * The signed-in home used to be a different page: an account card, and the
  * match list beside it. The matches moved to a screen of their own, which is
@@ -20,21 +27,40 @@ import { footer } from "../chrome";
 import { el } from "../dom";
 import { hostCycle } from "../host-cycle";
 import { insignia } from "../insignia";
+import { outagePanel } from "../outage-panel";
 import { signInForm } from "../signin-form";
 import { pilotCard } from "./pilot";
 
 /**
- * The home screen.
+ * Who the hero's panel is for.
  *
- * `error` is the one the OAuth callback came back with, and only a signed-out
- * reader can be shown it — there is no form to put it above otherwise.
+ * A union rather than a session plus flags, because the three cases exclude
+ * each other and two of them carry something the others have no use for: a
+ * signed-out reader can be shown the error a failed OAuth callback came back
+ * with, and there is no form to put that above otherwise.
  */
-export function homeScreen(session: Session | null, error?: string): Node[] {
+export type HomePanel =
+  | { readonly kind: "signedIn"; readonly session: Session }
+  | { readonly kind: "signedOut"; readonly error?: string }
+  /** The control plane did not answer. `retry` reads the session again. */
+  | {
+      readonly kind: "unreachable";
+      readonly message: string;
+      readonly retry: () => void;
+    };
+
+/** The home screen. Everything but the panel is the same in all three states. */
+export function homeScreen(state: HomePanel): Node[] {
   // Signed out, the site's one sign-in form (signin-form.ts) — the same one the
   // masthead's Login button and the camo editor put up in a dialog. Nothing
   // about the request differs here, so nothing about the form does either: the
   // hero supplies the panel it sits in, and that is all it supplies.
-  const panel = session ? pilotCard(session) : signInForm({ error }).form;
+  const panel =
+    state.kind === "signedIn"
+      ? pilotCard(state.session)
+      : state.kind === "signedOut"
+        ? signInForm({ error: state.error }).form
+        : outagePanel(state.message, state.retry);
 
   return [
     el("section", { className: "hero" }, [
diff --git a/web/src/styles.css b/web/src/styles.css
index b940a67..57f946a 100644
--- a/web/src/styles.css
+++ b/web/src/styles.css
@@ -837,8 +837,13 @@ body:has(.hero) {
 }
 
 /* The form is a panel on a panel, so it is slightly translucent and lifted
-   rather than another flat card the same colour as its surroundings. */
-.hero .signin {
+   rather than another flat card the same colour as its surroundings.
+
+   .hero-outage is what stands in the same place when the control plane cannot
+   be reached, so it is the same panel — named here rather than given a look of
+   its own, because a second set of numbers is a second thing to keep in step. */
+.hero .signin,
+.hero .hero-outage {
   width: 100%;
   max-width: 27rem;
   margin-top: 0.15rem;
-- 
2.51.2