Resilience: 404/500/503 pages, dynamic web app manifest, X-Redirect-By

[alexpricedev]

Implements the Resilience section of specification.website, the next section in the ongoing spec audit (Foundations, SEO, Accessibility, Security, Performance, Privacy already done).

What's in here

Custom error pages — 404 / 500 (Required)

• New ErrorLayout — same header/nav/footer chrome as the site, but ships zero client JS (no importmap, Lottie, or main bundle) so error pages render instantly even when the app is degraded, and always noindex. Extracted a shared SiteFooter so the repo-specific links live in one place.
• templates/error.tsx + utils/errors.tsx render render404() / render500() / render503().
• 404: fallback.ts now returns the styled, navigable page instead of plain-text "Not found" (correct status, homepage link, no leaks).
• 500: a new handleGuarded() wraps both the routed handlers and the fallback — it catches any uncaught error, logs it server-side, and returns the styled 500 with no stack-trace / path leak. A Bun.serve error() backstop also suppresses Bun's dev error page (which does leak).

503 maintenance (Recommended)

• MAINTENANCE_MODE=true serves a 503 with a Retry-After header (default 3600s, override via MAINTENANCE_RETRY_AFTER) for every request except /health (so the platform doesn't cycle the instance). Documented in .env.example.

Web app manifest (Recommended)

• Made dynamic so the name is never stuck as "Billet": deleted the static file, added buildWebManifest() driven by SITE_NAME (+ start_url, scope, display: standalone, theme/bg colours, 192/512 icons, and a maskable icon), served at /site.webmanifest with application/manifest+json.
• START_PROMPT.md notes that the manifest and X-Redirect-By both follow SITE_NAME — renaming that one constant renames both.

X-Redirect-By (Recommended)

• Stamped centrally in withSecurityHeaders: any response with a Location header gets X-Redirect-By: <SITE_NAME>. One line covers every redirect — the redirect() helper, the 308 trailing-slash, and the inline 303s in the auth/admin middleware.

Graceful degradation (Recommended)

• Already passed (full SSR, real <a>/<form action>, the single projects-search island degrades to the server-rendered list). Reinforced by making the new error/maintenance pages zero-JS.

Deferred (Optional / infra)

Service worker / offline (skipped by request); Deprecation/Sunset headers (no versioned endpoints yet); external synthetic monitoring, separate-host status page, and RUM/web-vitals (ops/infra — the /health liveness endpoint already exists).

Testing

• bun run check clean; 321 tests pass (added errors.test.tsx, webmanifest.test.ts, plus X-Redirect-By and handleGuarded cases; updated fallback.test.ts).
• Verified live in-browser: 404 (status + nav + CTA navigates home), 500, 503 (correctly drops nav/home button), and the manifest (application/manifest+json, name/short_name/start_url/maskable).

How to test the error pages locally

• 404: visit any nonexistent URL, e.g. /nope.
• 503: set MAINTENANCE_MODE=true in .env, restart — every page 503s except /health; unset to lift.
• 500: temporarily throw new Error("preview 500") in a controller (e.g. home.index()), hit the page, remove it. The real error logs to the terminal, never to the user.

🤖 Generated with Claude Code