Catch boot/chunk-load failures instead of leaving a blank page

The white-screen-on-login reports are boot-level failures that happen before
React renders the route tree, so the useLoginRequired spinner fix can't catch
them and the page goes fully blank with no recovery. Two gaps made any such
failure unrecoverable: use(bootstrapPromise) had no error boundary, and route
lazy() imports weren't wrapped for stale-bundle reload (so a chunk that 404s
after a deploy — "cacheless refresh fixes it" — blanked with no auto-reload).

- BootErrorBoundary wraps the app mount: on a caught boot/render error it reports
  to ErrorReporting, reloads onto the fresh bundle when the deployed entrypoint
  changed (reloadOnAppEntrypointHeadersMismatch, guarded by a sessionStorage
  timestamp so it can't loop), and otherwise renders a dependency-free
  "couldn't finish loading — reload" fallback instead of a blank page. The copy
  is hard-coded English on purpose: i18n may be exactly what failed to load.
- withEntrypointReloadOnLazy wraps every route's lazy import with
  checkAppEntrypointHeadersOnError, so a stale-deploy chunk 404 reloads onto the
  fresh bundle instead of surfacing as an unrecoverable blank.

This turns the whole class of login blanks — stale bundle, adblocker, odd state —
into a silent auto-reload or a visible, reportable error. It doesn't pinpoint
each trigger (the adblocker case still wants a HAR), but it makes them non-fatal.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: nbudin

app/javascript/BootErrorBoundary.tsx

@@ -0,0 +1,97 @@
+/* eslint-disable i18next/no-literal-string -- This boundary is the last line of
+   defense for a broken boot; it must not depend on i18n (which may be exactly
+   what failed to load), so its copy is intentionally hard-coded English. */
+import { Component, ErrorInfo, ReactNode, CSSProperties } from 'react';
+import { reloadOnAppEntrypointHeadersMismatch } from './checkAppEntrypointHeadersMatch';
+import errorReporting from 'ErrorReporting';
+
+// Guard against an auto-reload loop: if we reloaded very recently, show the
+// manual fallback instead of reloading again.
+const RELOAD_GUARD_KEY = 'intercode.bootErrorReloadAt';
+const RELOAD_GUARD_WINDOW_MS = 15_000;
+
+function reloadedWithinGuardWindow(): boolean {
+  try {
+    const last = Number(sessionStorage.getItem(RELOAD_GUARD_KEY));
+    return Number.isFinite(last) && last > 0 && Date.now() - last < RELOAD_GUARD_WINDOW_MS;
+  } catch {
+    return false;
+  }
+}
+
+function markReloadAttempt(): void {
+  try {
+    sessionStorage.setItem(RELOAD_GUARD_KEY, String(Date.now()));
+  } catch {
+    // sessionStorage may be unavailable (private mode / blocked); best effort.
+  }
+}
+
+const containerStyle: CSSProperties = {
+  maxWidth: '32rem',
+  margin: '4rem auto',
+  padding: '0 1rem',
+  fontFamily: 'system-ui, sans-serif',
+  textAlign: 'center',
+  lineHeight: 1.5,
+};
+
+const buttonStyle: CSSProperties = {
+  marginTop: '1rem',
+  padding: '0.5rem 1.25rem',
+  fontSize: '1rem',
+  cursor: 'pointer',
+};
+
+function BootErrorFallback() {
+  return (
+    <div style={containerStyle} role="alert">
+      <h1 style={{ fontSize: '1.25rem' }}>We couldn’t finish loading this page</h1>
+      <p>This is usually temporary and fixed by reloading. If it keeps happening, try again in a few minutes.</p>
+      <button type="button" style={buttonStyle} onClick={() => window.location.reload()}>
+        Reload the page
+      </button>
+    </div>
+  );
+}
+
+type Props = { children: ReactNode };
+type State = { hasError: boolean };
+
+// Catches failures during the SPA's initial boot/render — a rejected
+// bootstrapPromise, or an uncaught error rendering the route tree — that would
+// otherwise leave a blank white page with no recovery. A stale deploy (a chunk
+// hash that no longer exists) is the most common cause, so we try to reload
+// onto the fresh bundle; anything else gets a visible, reportable error instead
+// of a blank screen.
+export default class BootErrorBoundary extends Component<Props, State> {
+  state: State = { hasError: false };
+
+  static getDerivedStateFromError(): State {
+    return { hasError: true };
+  }
+
+  componentDidCatch(error: Error, info: ErrorInfo): void {
+    try {
+      errorReporting().error(error, { tags: { context: 'boot' }, componentStack: info.componentStack });
+    } catch {
+      // Error reporting itself may be unavailable (e.g. its SDK was the chunk
+      // that failed to load); don't let that mask the fallback UI.
+    }
+
+    // Very often a blank boot is a stale deploy. If the deployed entrypoint has
+    // changed under this tab, reload to pick up the fresh bundle — but only if
+    // we didn't just try, so we never get stuck in a reload loop.
+    if (!reloadedWithinGuardWindow()) {
+      markReloadAttempt();
+      void reloadOnAppEntrypointHeadersMismatch();
+    }
+  }
+
+  render(): ReactNode {
+    if (this.state.hasError) {
+      return <BootErrorFallback />;
+    }
+    return this.props.children;
+  }
+}

app/javascript/packs/application.tsx

@@ -3,7 +3,7 @@ import 'regenerator-runtime/runtime';
 import mountReactComponents from '../mountReactComponents';
 import { StrictMode, Suspense, use, useLayoutEffect, useMemo, useState } from 'react';
 import AuthenticityTokensManager, { getAuthenticityTokensURL } from 'AuthenticityTokensContext';
-import { createBrowserRouter, RouterContextProvider, RouterProvider } from 'react-router';
+import { createBrowserRouter, RouterContextProvider, RouterProvider, RouteObject } from 'react-router';
 import { buildBrowserApolloClient, GraphQLNotAuthenticatedErrorEvent } from 'useIntercodeApolloClient';
 import {
   apolloClientContext,
@@ -18,6 +18,8 @@ import { AuthenticationManager, AuthenticationManagerContext } from '../Authenti
 import { PageLoadingIndicator } from '@neinteractiveliterature/litform';
 import { ApolloClient } from '@apollo/client';
 import { initErrorReporting } from 'ErrorReporting';
+import { checkAppEntrypointHeadersOnError } from '../checkAppEntrypointHeadersMatch';
+import BootErrorBoundary from '../BootErrorBoundary';
 
 type Bootstrap = {
   clientConfiguration: ClientConfiguration;
@@ -118,19 +120,37 @@ function RouterLoadingOverlay({ router }: { router: BrowserRouter }) {
   );
 }
 
+// Wrap every route's lazy import so a failed chunk load — almost always a stale
+// deploy whose hashed chunk no longer exists — reloads onto the fresh bundle
+// instead of surfacing as an unrecoverable blank. Applied once to the whole tree.
+function withEntrypointReloadOnLazy(routes: RouteObject[]): RouteObject[] {
+  return routes.map((route) => {
+    let { lazy } = route;
+    if (typeof lazy === 'function') {
+      const load = lazy;
+      lazy = () => checkAppEntrypointHeadersOnError(load);
+    }
+    return {
+      ...route,
+      lazy,
+      children: route.children ? withEntrypointReloadOnLazy(route.children) : route.children,
+    } as RouteObject;
+  });
+}
+
 function DataModeApplicationEntry() {
   const bootstrap = use(bootstrapPromise);
 
   const router = useMemo(
     () =>
       createBrowserRouter(
-        [
+        withEntrypointReloadOnLazy([
           {
             id: 'root',
             lazy: () => import('root'),
             children: appRootRoutes,
           },
-        ],
+        ]),
         {
           getContext: () => {
             const context = new RouterContextProvider();
@@ -158,9 +178,11 @@ function DataModeApplicationEntry() {
 
 function DataModeApplicationEntrySuspenseWrapper() {
   return (
-    <Suspense fallback={<PageLoadingIndicator visible />}>
-      <DataModeApplicationEntry />
-    </Suspense>
+    <BootErrorBoundary>
+      <Suspense fallback={<PageLoadingIndicator visible />}>
+        <DataModeApplicationEntry />
+      </Suspense>
+    </BootErrorBoundary>
   );
 }
 

test/javascript/BootErrorBoundary.test.tsx

@@ -0,0 +1,36 @@
+import { vi } from 'vitest';
+import { render } from '@testing-library/react';
+import BootErrorBoundary from '../../app/javascript/BootErrorBoundary';
+
+function Boom(): never {
+  throw new Error('boom');
+}
+
+describe('BootErrorBoundary', () => {
+  it('renders its children when nothing throws', () => {
+    const { getByText } = render(
+      <BootErrorBoundary>
+        <div>app content</div>
+      </BootErrorBoundary>,
+    );
+
+    expect(getByText('app content')).toBeTruthy();
+  });
+
+  it('renders a reload fallback instead of a blank page when a child throws', () => {
+    // React logs caught boundary errors to console.error; silence it for this case.
+    const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {});
+    try {
+      const { getByRole, queryByText } = render(
+        <BootErrorBoundary>
+          <Boom />
+        </BootErrorBoundary>,
+      );
+
+      expect(getByRole('button', { name: /reload/i })).toBeTruthy();
+      expect(queryByText('app content')).toBeNull();
+    } finally {
+      consoleError.mockRestore();
+    }
+  });
+});