@akinon/next 1.126.13-v1-rc.9 → 1.126.13

package/CHANGELOG.md

@@ -1,11 +1,10 @@
 # @akinon/next
 
-## 1.126.13-v1-rc.9
+## 1.126.13
 
 ### Patch Changes
 
-- d480941: ZERO-4399: add card rewards to pz-masterpass-rest
-- 182a639b: ZERO-4483: Verify v1-rc maintenance pipeline (no-op patch to confirm v1-rc dist-tag flow)
+- 5b17eef: ZERO-5129, ZERO-5130: Report the error the [pz] error boundary caught instead of a synthetic fatal one, so Sentry groups by what broke and drops stale chunks; reload once, instead of showing the error page, after a ChunkLoadError (also one no boundary catches) or a removeChild/insertBefore DOM mutation race
 
 ## 1.126.12
 

package/__tests__/uncaught-error.test.ts

@@ -0,0 +1,489 @@
+/**
+ * ZERO-5129 / ZERO-5130: what the storefront does with an error nothing else
+ * caught — which kind it is, whether it recovers on its own, and what reaches
+ * Sentry.
+ */
+import {
+  buildUncaughtErrorReport,
+  canAttemptRecovery,
+  claimRecoveryAttempt,
+  classifyUncaughtError,
+  copyError,
+  decideUncaughtError,
+  RECOVERY_WINDOW_MS,
+  runUncaughtErrorRecovery
+} from '../utils/uncaught-error';
+
+const sentryInit = jest.fn();
+const scopes: Array<Record<string, jest.Mock>> = [];
+const captureException = jest.fn();
+
+jest.mock('@sentry/nextjs', () => ({
+  init: (options: unknown) => sentryInit(options),
+  isInitialized: () => false,
+  withScope: (callback: (scope: unknown) => void) => {
+    const scope = {
+      setLevel: jest.fn(),
+      setTags: jest.fn(),
+      setExtra: jest.fn()
+    };
+    scopes.push(scope);
+    callback(scope);
+  },
+  captureException: (...args: unknown[]) => captureException(...args)
+}));
+
+// Effects and memos run as soon as the hook is called; no renderer is needed to
+// see what they do.
+jest.mock('react', () => ({
+  ...jest.requireActual('react'),
+  useEffect: (effect: () => void) => effect(),
+  useMemo: (compute: () => unknown) => compute()
+}));
+
+const named = (name: string, message: string, stack?: string) => {
+  const error = new Error(message);
+  error.name = name;
+  if (stack !== undefined) error.stack = stack;
+  return error;
+};
+
+const memoryStorage = () => {
+  const values = new Map<string, string>();
+  return {
+    getItem: (key: string) => values.get(key) ?? null,
+    setItem: (key: string, value: string) => void values.set(key, value)
+  };
+};
+
+describe('classifying what the error boundary caught', () => {
+  it.each([
+    [
+      'webpack ChunkLoadError',
+      named(
+        'ChunkLoadError',
+        'Loading chunk 2390 failed.\n(error: https://www.lacoste.com.tr/_next/static/chunks/app/category/page-94a025687cec4f55.js)'
+      )
+    ],
+    [
+      'a CSS chunk',
+      named(
+        'Error',
+        'Loading CSS chunk 8104 failed.\n(/_next/static/css/a.css)'
+      )
+    ],
+    [
+      "Turbopack's wording",
+      named(
+        'Error',
+        'Failed to load chunk /_next/static/chunks/0f2b.js from module 4411'
+      )
+    ]
+  ])('%s is a stale chunk', (_label, error) => {
+    expect(classifyUncaughtError(error)).toBe('chunk-load');
+  });
+
+  it.each([
+    [
+      'Chrome removeChild',
+      named(
+        'NotFoundError',
+        "Failed to execute 'removeChild' on 'Node': The node to be removed is not a child of this node."
+      )
+    ],
+    [
+      'Chrome insertBefore',
+      named(
+        'NotFoundError',
+        "Failed to execute 'insertBefore' on 'Node': The node before which the new node is to be inserted is not a child of this node."
+      )
+    ],
+    [
+      'Firefox removeChild',
+      named(
+        'NotFoundError',
+        'Node.removeChild: The node to be removed is not a child of this node'
+      )
+    ],
+    [
+      'Safari, which names the method only in the stack',
+      named(
+        'NotFoundError',
+        'The object can not be found here.',
+        'insertBefore@[native code]\naZ@https://tr.uspoloassn.com/_next/static/chunks/fd9d1056.js:1:76229'
+      )
+    ]
+  ])('%s is a DOM mutation race', (_label, error) => {
+    expect(classifyUncaughtError(error)).toBe('dom-mutation');
+  });
+
+  it.each([
+    [
+      'a TypeError',
+      new TypeError("Cannot read properties of undefined (reading 'id')")
+    ],
+    [
+      'a NotFoundError from another API',
+      named('NotFoundError', 'Requested device not found')
+    ],
+    [
+      "Safari's wording without a DOM method in the stack",
+      named(
+        'NotFoundError',
+        'The object can not be found here.',
+        'transaction@[native code]'
+      )
+    ],
+    ['a thrown string', 'boom'],
+    ['nothing at all', undefined]
+  ])('%s is an uncaught error', (_label, error) => {
+    expect(classifyUncaughtError(error)).toBe('uncaught');
+  });
+});
+
+describe('the one recovery attempt per window', () => {
+  const now = 1_000_000;
+
+  it('is granted once, then again after the window', () => {
+    const storage = memoryStorage();
+
+    expect(claimRecoveryAttempt('chunk-load', storage, now)).toBe(true);
+    expect(claimRecoveryAttempt('chunk-load', storage, now + 1000)).toBe(false);
+    expect(
+      claimRecoveryAttempt('chunk-load', storage, now + RECOVERY_WINDOW_MS)
+    ).toBe(true);
+  });
+
+  it('is counted per kind', () => {
+    const storage = memoryStorage();
+
+    expect(claimRecoveryAttempt('chunk-load', storage, now)).toBe(true);
+    expect(claimRecoveryAttempt('dom-mutation', storage, now)).toBe(true);
+  });
+
+  it('is never granted to an uncaught error, or without storage', () => {
+    expect(claimRecoveryAttempt('uncaught', memoryStorage(), now)).toBe(false);
+    expect(claimRecoveryAttempt('chunk-load', null, now)).toBe(false);
+  });
+
+  it('is not granted when storage refuses access, rather than looping', () => {
+    const refusing = {
+      getItem: () => {
+        throw new Error('SecurityError');
+      },
+      setItem: () => undefined
+    };
+    const readOnly = {
+      getItem: () => null,
+      setItem: () => {
+        throw new Error('QuotaExceededError');
+      }
+    };
+
+    expect(claimRecoveryAttempt('chunk-load', refusing, now)).toBe(false);
+    expect(claimRecoveryAttempt('chunk-load', readOnly, now)).toBe(false);
+  });
+
+  it('can be looked at without being taken', () => {
+    const storage = memoryStorage();
+
+    expect(canAttemptRecovery('dom-mutation', storage, now)).toBe(true);
+    expect(canAttemptRecovery('dom-mutation', storage, now)).toBe(true);
+    expect(claimRecoveryAttempt('dom-mutation', storage, now)).toBe(true);
+  });
+});
+
+describe('the decision about one error', () => {
+  it('is taken once, and every caller hears the same answer', () => {
+    const storage = memoryStorage();
+    const error = named('ChunkLoadError', 'Loading chunk 1 failed.');
+
+    const first = decideUncaughtError(error, storage, 1000);
+    const second = decideUncaughtError(error, storage, 1000);
+
+    expect(first).toEqual({ kind: 'chunk-load', recovering: true });
+    expect(second).toBe(first);
+    // A second failure inside the window does not get another attempt.
+    expect(
+      decideUncaughtError(
+        named('ChunkLoadError', 'Loading chunk 1 failed.'),
+        storage,
+        2000
+      )
+    ).toEqual({ kind: 'chunk-load', recovering: false });
+  });
+});
+
+describe('carrying out a recovery', () => {
+  it('reloads the page once, however many callers ask', () => {
+    const reload = jest.fn();
+
+    for (const [error, kind] of [
+      [named('ChunkLoadError', 'Loading chunk 7 failed.'), 'chunk-load'],
+      [named('NotFoundError', 'x'), 'dom-mutation']
+    ] as const) {
+      const decision = { kind, recovering: true };
+      runUncaughtErrorRecovery(error, decision, reload);
+      runUncaughtErrorRecovery(error, decision, reload);
+    }
+
+    expect(reload).toHaveBeenCalledTimes(2);
+  });
+
+  it('does nothing when the attempt was not granted', () => {
+    const reload = jest.fn();
+
+    runUncaughtErrorRecovery(
+      named('ChunkLoadError', 'x'),
+      { kind: 'chunk-load', recovering: false },
+      reload
+    );
+
+    expect(reload).not.toHaveBeenCalled();
+  });
+});
+
+describe('what the report says', () => {
+  it('reports a crash as fatal, grouped by the error itself', () => {
+    const error = new TypeError('x is undefined');
+    const report = buildUncaughtErrorReport(error, {
+      kind: 'uncaught',
+      recovering: false
+    });
+
+    expect(report.level).toBe('fatal');
+    expect(report.fingerprint).toEqual([
+      'UNCAUGHT_ERROR_PAGE',
+      '{{ default }}'
+    ]);
+    expect(report.tags).toEqual({
+      UNCAUGHT_ERROR_KIND: 'uncaught',
+      RECOVERY: 'none'
+    });
+  });
+
+  it('keeps grouping a server error by its digest', () => {
+    const error = Object.assign(
+      new Error('An error occurred in the Server Components render.'),
+      {
+        digest: '3141592653'
+      }
+    );
+
+    expect(
+      buildUncaughtErrorReport(error, { kind: 'uncaught', recovering: false })
+        .fingerprint
+    ).toEqual(['UNCAUGHT_ERROR_PAGE', '3141592653']);
+  });
+
+  it('reports a DOM mutation race as a warning, under one issue', () => {
+    const report = buildUncaughtErrorReport(named('NotFoundError', 'x'), {
+      kind: 'dom-mutation',
+      recovering: true
+    });
+
+    expect(report.level).toBe('warning');
+    expect(report.fingerprint).toEqual(['UNCAUGHT_ERROR_PAGE', 'dom-mutation']);
+    expect(report.tags.RECOVERY).toBe('attempted');
+  });
+
+  it('sends a copy of the error, name, message and stack intact', () => {
+    const error = named(
+      'NotFoundError',
+      'gone',
+      'NotFoundError: gone\n    at a2 (x.js:1:1)'
+    );
+    const copy = copyError(error);
+
+    expect(copy).not.toBe(error);
+    expect([copy.name, copy.message, copy.stack]).toEqual([
+      error.name,
+      error.message,
+      error.stack
+    ]);
+    expect(copyError('boom').message).toBe('boom');
+  });
+});
+
+describe('the client filter, with the real error in hand', () => {
+  const beforeSend = () => {
+    sentryInit.mockClear();
+    const { initSentry } = require('../sentry');
+    initSentry('Client', { dsn: 'https://key@sentry.invalid/1' });
+    return sentryInit.mock.calls[0][0].beforeSend as (
+      event: unknown,
+      hint: unknown
+    ) => unknown;
+  };
+  const errorPageEvent = { tags: { LOG_TYPE: 'UNCAUGHT_ERROR_PAGE' } };
+
+  it('drops a stale chunk the error page reports', () => {
+    const send = beforeSend();
+
+    for (const message of [
+      'Loading chunk 2390 failed.',
+      'Loading CSS chunk 12 failed.',
+      'Failed to load chunk /_next/static/chunks/a.js'
+    ]) {
+      expect(
+        send(errorPageEvent, {
+          originalException: copyError(named('ChunkLoadError', message))
+        })
+      ).toBeNull();
+    }
+  });
+
+  it('lets a DOM mutation race and a crash through', () => {
+    const send = beforeSend();
+
+    expect(
+      send(errorPageEvent, {
+        originalException: copyError(
+          named(
+            'NotFoundError',
+            "Failed to execute 'removeChild' on 'Node': The node to be removed is not a child of this node."
+          )
+        )
+      })
+    ).toBe(errorPageEvent);
+    expect(
+      send(errorPageEvent, {
+        originalException: new TypeError('x is undefined')
+      })
+    ).toBe(errorPageEvent);
+  });
+
+  it('still drops what the error page did not report', () => {
+    expect(
+      beforeSend()({ tags: {} }, { originalException: new TypeError('x') })
+    ).toBeNull();
+  });
+});
+
+describe('the error boundary hook', () => {
+  const load = () => {
+    return require('../hooks/use-sentry-uncaught-errors')
+      .useSentryUncaughtErrors as (error: Error) => void;
+  };
+
+  beforeEach(() => {
+    captureException.mockClear();
+    scopes.length = 0;
+  });
+
+  it('reports the error itself, not a stand-in, once', () => {
+    const error = named(
+      'NotFoundError',
+      "Failed to execute 'insertBefore' on 'Node': The node before which the new node is to be inserted is not a child of this node."
+    );
+    const useSentryUncaughtErrors = load();
+
+    useSentryUncaughtErrors(error);
+    useSentryUncaughtErrors(error);
+
+    expect(captureException).toHaveBeenCalledTimes(1);
+    const [sent, hint] = captureException.mock.calls[0];
+    expect([sent.name, sent.message]).toEqual([error.name, error.message]);
+    expect(hint).toEqual({
+      fingerprint: ['UNCAUGHT_ERROR_PAGE', 'dom-mutation']
+    });
+    expect(scopes[0].setLevel).toHaveBeenCalledWith('warning');
+    expect(scopes[0].setTags).toHaveBeenCalledWith(
+      expect.objectContaining({
+        LOG_TYPE: 'UNCAUGHT_ERROR_PAGE',
+        UNCAUGHT_ERROR_KIND: 'dom-mutation'
+      })
+    );
+  });
+
+  it('keeps a crash fatal', () => {
+    const useSentryUncaughtErrors = load();
+
+    useSentryUncaughtErrors(
+      new TypeError("Cannot read properties of null (reading 'map')")
+    );
+
+    expect(scopes[0].setLevel).toHaveBeenCalledWith('fatal');
+  });
+
+  it('reloads a tab that asked for a chunk of the previous build, once per window', () => {
+    const reload = jest.fn();
+    const storage = memoryStorage();
+    (globalThis as unknown as { window: unknown }).window = {
+      sessionStorage: storage,
+      location: { reload }
+    };
+    const useSentryUncaughtErrors = load();
+
+    try {
+      useSentryUncaughtErrors(
+        named('ChunkLoadError', 'Loading chunk 9393 failed.')
+      );
+      useSentryUncaughtErrors(
+        named('ChunkLoadError', 'Loading chunk 9393 failed.')
+      );
+    } finally {
+      delete (globalThis as unknown as { window?: unknown }).window;
+    }
+
+    expect(reload).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('the error page hook', () => {
+  const load = () =>
+    require('../hooks/use-uncaught-error-recovery')
+      .useUncaughtErrorRecovery as (error: Error) => boolean;
+
+  const withWindow = (run: (reload: jest.Mock) => void) => {
+    const reload = jest.fn();
+    (globalThis as unknown as { window: unknown }).window = {
+      sessionStorage: memoryStorage(),
+      location: { reload }
+    };
+    try {
+      run(reload);
+    } finally {
+      delete (globalThis as unknown as { window?: unknown }).window;
+    }
+  };
+
+  const domMutation = () =>
+    named(
+      'NotFoundError',
+      "Failed to execute 'removeChild' on 'Node': The node to be removed is not a child of this node."
+    );
+
+  it('draws nothing while a DOM mutation race reloads the page, once', () => {
+    withWindow((reload) => {
+      const useUncaughtErrorRecovery = load();
+
+      expect(useUncaughtErrorRecovery(domMutation())).toBe(true);
+      expect(reload).toHaveBeenCalledTimes(1);
+
+      // The same race again inside the window shows the error page.
+      expect(useUncaughtErrorRecovery(domMutation())).toBe(false);
+      expect(reload).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  it('draws nothing while a stale chunk reloads the page', () => {
+    withWindow((reload) => {
+      expect(load()(named('ChunkLoadError', 'Loading chunk 4 failed.'))).toBe(
+        true
+      );
+      expect(reload).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  it('shows the error page for a crash', () => {
+    withWindow((reload) => {
+      expect(load()(new TypeError('x is undefined'))).toBe(false);
+      expect(reload).not.toHaveBeenCalled();
+    });
+  });
+
+  it('shows the error page on the server, where no attempt can be recorded', () => {
+    expect(load()(domMutation())).toBe(false);
+  });
+});

package/components/client-root.tsx

@@ -1,7 +1,7 @@
 'use client';
 
 import React from 'react';
-import { useMobileIframeHandler } from '../hooks';
+import { useChunkLoadRecovery, useMobileIframeHandler } from '../hooks';
 import { LoggerPopup } from './logger-popup';
 import { LoggerProvider } from '../hooks/use-logger-context';
 import * as Sentry from '@sentry/nextjs';
@@ -19,6 +19,8 @@ export default function ClientRoot({
     sessionId: sessionId || ''
   });
 
+  useChunkLoadRecovery();
+
   const initializeSentry = async () => {
     const response = await fetch('/api/sentry', { next: { revalidate: 0 } });
     const data = await response.json();

package/hooks/index.ts

@@ -13,4 +13,6 @@ export * from './use-message-listener';
 export * from './use-logger';
 export * from './use-logger-context';
 export * from './use-sentry-uncaught-errors';
+export * from './use-uncaught-error-recovery';
+export * from './use-chunk-load-recovery';
 export * from './use-pz-params';

package/hooks/use-chunk-load-recovery.ts

@@ -0,0 +1,38 @@
+import { useEffect } from 'react';
+import {
+  classifyUncaughtError,
+  decideUncaughtError,
+  runUncaughtErrorRecovery
+} from '../utils/uncaught-error';
+
+/**
+ * Reloads once when a chunk of the previous build fails to load and no error
+ * boundary catches it.
+ *
+ * A client-side navigation that needs a route chunk after a deploy can throw
+ * its ChunkLoadError outside every boundary — Next.js then shows its own
+ * "This page couldn't load" screen, and the `[pz]` error page never learns of
+ * it. The same once-per-window attempt the error page uses applies here, so
+ * the two never reload twice for one failure, and a build that really lost
+ * the chunk is not reloaded forever.
+ */
+export const useChunkLoadRecovery = () => {
+  useEffect(() => {
+    const recover = (error: unknown) => {
+      if (classifyUncaughtError(error) !== 'chunk-load') return;
+
+      runUncaughtErrorRecovery(error, decideUncaughtError(error));
+    };
+
+    const onError = (event: ErrorEvent) => recover(event.error);
+    const onRejection = (event: PromiseRejectionEvent) => recover(event.reason);
+
+    window.addEventListener('error', onError);
+    window.addEventListener('unhandledrejection', onRejection);
+
+    return () => {
+      window.removeEventListener('error', onError);
+      window.removeEventListener('unhandledrejection', onRejection);
+    };
+  }, []);
+};

package/hooks/use-sentry-uncaught-errors.ts

@@ -1,24 +1,54 @@
 import { useEffect } from 'react';
 import * as Sentry from '@sentry/nextjs';
 import { ClientLogType } from '@akinon/next/sentry';
+import {
+  buildUncaughtErrorReport,
+  decideUncaughtError,
+  runUncaughtErrorRecovery,
+  UncaughtErrorDecision
+} from '../utils/uncaught-error';
 
-export const useSentryUncaughtErrors = (error: Error & { digest?: string }) => {
-  useEffect(() => {
-    Sentry.withScope(function (scope) {
-      scope.setLevel('fatal');
-      scope.setTags({
-        APP_TYPE: 'ProjectZeroNext',
-        TYPE: 'Client',
-        LOG_TYPE: ClientLogType.UNCAUGHT_ERROR_PAGE
-      });
-      scope.setExtra('error', error);
+const reported = new WeakSet<object>();
+
+const reportUncaughtError = (
+  error: Error & { digest?: string },
+  decision: UncaughtErrorDecision
+) => {
+  // Once per error object: a re-render or a strict-mode effect re-run is not a
+  // second occurrence.
+  if (reported.has(error)) return;
+  reported.add(error);
 
-      const error_ = new Error('FATAL: Uncaught client error');
-      error_.name = 'UNCAUGHT_ERROR_PAGE';
+  const report = buildUncaughtErrorReport(error, decision);
+
+  Sentry.withScope(function (scope) {
+    scope.setLevel(report.level);
+    scope.setTags({
+      APP_TYPE: 'ProjectZeroNext',
+      TYPE: 'Client',
+      LOG_TYPE: ClientLogType.UNCAUGHT_ERROR_PAGE,
+      ...report.tags
+    });
+    scope.setExtra('error', error);
 
-      Sentry.captureException(error_, {
-        fingerprint: ['UNCAUGHT_ERROR_PAGE', error.digest]
-      });
+    // The error itself, not a stand-in: Sentry groups by what actually broke,
+    // and the client filter (`isNetworkError`) can recognise a stale chunk.
+    Sentry.captureException(report.error, {
+      fingerprint: report.fingerprint
     });
+  });
+};
+
+/**
+ * Reports an error the `[pz]` error boundary caught, and reloads the page for
+ * the kinds that recover on their own — a stale chunk, a DOM mutation race
+ * (see `utils/uncaught-error`).
+ */
+export const useSentryUncaughtErrors = (error: Error & { digest?: string }) => {
+  useEffect(() => {
+    const decision = decideUncaughtError(error);
+
+    reportUncaughtError(error, decision);
+    runUncaughtErrorRecovery(error, decision);
   }, [error]);
 };

package/hooks/use-uncaught-error-recovery.ts

@@ -0,0 +1,28 @@
+import { useEffect, useMemo } from 'react';
+import {
+  decideUncaughtError,
+  runUncaughtErrorRecovery
+} from '../utils/uncaught-error';
+
+/**
+ * Whether the page is reloading to recover from `error` — a stale chunk or a
+ * DOM mutation race (see `utils/uncaught-error`). While it does, the error page
+ * should draw nothing: the 500 page would only flash before the reload. When
+ * the recovery attempt is spent, this is false and the page shows.
+ *
+ * The decision is taken while rendering, so the first render already knows.
+ * Taking it twice is safe: it is made once per error object and every later
+ * call returns the same answer. On the server there is no storage to record
+ * an attempt in, so it is always false there.
+ */
+export const useUncaughtErrorRecovery = (
+  error: Error & { digest?: string }
+): boolean => {
+  const decision = useMemo(() => decideUncaughtError(error), [error]);
+
+  useEffect(() => {
+    runUncaughtErrorRecovery(error, decision);
+  }, [error, decision]);
+
+  return decision.recovering;
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@akinon/next",
   "description": "Core package for Project Zero Next",
-  "version": "1.126.13-v1-rc.9",
+  "version": "1.126.13",
   "private": false,
   "license": "MIT",
   "bin": {
@@ -35,7 +35,7 @@
     "set-cookie-parser": "2.6.0"
   },
   "devDependencies": {
-    "@akinon/eslint-plugin-projectzero": "1.126.13-v1-rc.9",
+    "@akinon/eslint-plugin-projectzero": "1.126.13",
     "@babel/core": "7.26.10",
     "@babel/preset-env": "7.26.9",
     "@babel/preset-typescript": "7.27.0",

package/sentry/index.ts

@@ -1,4 +1,5 @@
 import * as Sentry from '@sentry/nextjs';
+import { classifyUncaughtError } from '../utils/uncaught-error';
 
 const SENTRY_DSN: string | undefined =
   process.env.SENTRY_DSN || process.env.NEXT_PUBLIC_SENTRY_DSN;
@@ -27,6 +28,10 @@ const isNetworkError = (exception: unknown): boolean => {
 
   if (exception.name === 'NetworkError') return true;
 
+  // A stale build's chunk — including a CSS chunk, and Turbopack's wording —
+  // the same way the error boundary recognises it.
+  if (classifyUncaughtError(exception) === 'chunk-load') return true;
+
   if (exception.name === 'TypeError') {
     return networkErrorPatterns.some((pattern) =>
       exception.message.toLowerCase().includes(pattern)

package/utils/uncaught-error.ts

@@ -0,0 +1,228 @@
+/**
+ * What the storefront does with an error nothing else caught.
+ *
+ * The `[pz]` error boundary used to treat every error the same way: report a
+ * synthetic `FATAL: Uncaught client error` to Sentry and show the 500 page. Two
+ * kinds of error are neither fatal nor the page's fault, and both recover on
+ * their own:
+ *
+ * - `chunk-load`: a tab still running the previous build asked for one of its
+ *   chunks after a deploy removed it. Nothing is broken; a reload fetches the
+ *   new build. It is not reported: the Sentry filter drops it by design.
+ * - `dom-mutation`: React found a node it manages moved or removed behind its
+ *   back — Chrome's page translation, an extension, a third-party script — and
+ *   `removeChild`/`insertBefore` threw while it committed. A fresh document
+ *   gets past it. Reported as a warning, under one issue.
+ *
+ * Both recover by reloading the page. For a DOM mutation, re-rendering just
+ * the segment (the boundary's `reset`) would be lighter, but it does not hold:
+ * a commit that failed half way leaves the App Router's own state behind it
+ * inconsistent, and on a Next.js 16 production build its next render throws
+ * React #310 ("Rendered more hooks than during the previous render") at the
+ * root — Next.js's "This page couldn't load" instead of the page. The URL
+ * already points where the user was going, so the reload lands there.
+ *
+ * Everything else is `uncaught`: a real crash, reported as fatal and grouped by
+ * the error itself.
+ *
+ * Recovery is tried once per kind per window, so an error that survives it —
+ * a deploy that really lost its chunks, a page that keeps being rewritten —
+ * shows the error page instead of reloading in a loop.
+ */
+
+export type UncaughtErrorKind = 'chunk-load' | 'dom-mutation' | 'uncaught';
+
+export interface UncaughtErrorDecision {
+  kind: UncaughtErrorKind;
+  /** Whether this error gets its one recovery attempt. */
+  recovering: boolean;
+}
+
+type RecoveryStorage = Pick<Storage, 'getItem' | 'setItem'>;
+
+export const RECOVERY_WINDOW_MS = 30_000;
+
+const RECOVERY_KEY_PREFIX = 'pz-uncaught-error-recovery:';
+
+// webpack: "Loading chunk 2390 failed." / "Loading CSS chunk 12 failed.";
+// Turbopack: "Failed to load chunk static/chunks/…".
+const CHUNK_LOAD_PATTERNS = [
+  /loading (css )?chunk \S+ failed/i,
+  /failed to load chunk/i
+];
+
+const DOM_MUTATION_METHODS = /\b(removeChild|insertBefore)\b/;
+// Chrome and Firefox name the method in the message; Safari only says "The
+// object can not be found here." and names it in the stack.
+const DOM_MUTATION_MESSAGES = [
+  /not a child of this node/i,
+  /the object can not be found here/i
+];
+
+const readText = (value: unknown): string =>
+  typeof value === 'string' ? value : '';
+
+export const classifyUncaughtError = (error: unknown): UncaughtErrorKind => {
+  if (!error || typeof error !== 'object') return 'uncaught';
+
+  const { name, message, stack } = error as Record<string, unknown>;
+  const errorName = readText(name);
+  const errorMessage = readText(message);
+
+  if (
+    errorName === 'ChunkLoadError' ||
+    CHUNK_LOAD_PATTERNS.some((pattern) => pattern.test(errorMessage))
+  ) {
+    return 'chunk-load';
+  }
+
+  if (
+    errorName === 'NotFoundError' &&
+    (DOM_MUTATION_METHODS.test(errorMessage) ||
+      DOM_MUTATION_METHODS.test(readText(stack))) &&
+    DOM_MUTATION_MESSAGES.some((pattern) => pattern.test(errorMessage))
+  ) {
+    return 'dom-mutation';
+  }
+
+  return 'uncaught';
+};
+
+/** sessionStorage, or null where it is missing or refuses access. */
+export const readSessionStorage = (): RecoveryStorage | null => {
+  try {
+    return typeof window !== 'undefined' && window.sessionStorage
+      ? window.sessionStorage
+      : null;
+  } catch {
+    return null;
+  }
+};
+
+/** Whether a recovery of this kind would be allowed now. Reads only. */
+export const canAttemptRecovery = (
+  kind: UncaughtErrorKind,
+  storage: RecoveryStorage | null,
+  now: number = Date.now()
+): boolean => {
+  if (kind === 'uncaught' || !storage) return false;
+
+  try {
+    const last = storage.getItem(`${RECOVERY_KEY_PREFIX}${kind}`);
+    return !last || now - Number(last) >= RECOVERY_WINDOW_MS;
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * Takes this kind's recovery attempt for the window, if it is free. Without
+ * storage there is no way to know a reload already happened, so nothing is
+ * attempted rather than risking a loop.
+ */
+export const claimRecoveryAttempt = (
+  kind: UncaughtErrorKind,
+  storage: RecoveryStorage | null,
+  now: number = Date.now()
+): boolean => {
+  if (!canAttemptRecovery(kind, storage, now)) return false;
+
+  try {
+    (storage as RecoveryStorage).setItem(
+      `${RECOVERY_KEY_PREFIX}${kind}`,
+      String(now)
+    );
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+// One decision per error object. The boundary's hook and the error page both
+// ask about the same error; the first to ask takes the attempt, the other
+// hears the same answer.
+const decisions = new WeakMap<object, UncaughtErrorDecision>();
+
+export const decideUncaughtError = (
+  error: unknown,
+  storage: RecoveryStorage | null = readSessionStorage(),
+  now: number = Date.now()
+): UncaughtErrorDecision => {
+  const cacheable = !!error && typeof error === 'object';
+  const cached = cacheable ? decisions.get(error as object) : undefined;
+  if (cached) return cached;
+
+  const kind = classifyUncaughtError(error);
+  const decision = {
+    kind,
+    recovering: claimRecoveryAttempt(kind, storage, now)
+  };
+
+  if (cacheable) decisions.set(error as object, decision);
+  return decision;
+};
+
+const recovered = new WeakSet<object>();
+
+/**
+ * Carries out a recovery the decision granted: reloads the page, once per
+ * error however many callers ask.
+ */
+export const runUncaughtErrorRecovery = (
+  error: unknown,
+  decision: UncaughtErrorDecision,
+  reload: () => void = () => window.location.reload()
+): void => {
+  if (!decision.recovering || !error || typeof error !== 'object') return;
+  if (recovered.has(error as object)) return;
+
+  recovered.add(error as object);
+  reload();
+};
+
+export interface UncaughtErrorReport {
+  /** A copy of the error, so Sentry sees it as new; see `copyError`. */
+  error: Error;
+  level: 'fatal' | 'warning';
+  fingerprint: string[];
+  tags: Record<string, string>;
+}
+
+/**
+ * A fresh error with the same name, message and stack. Sentry skips an error
+ * object it has captured before, and the global handlers may have captured
+ * this one on its way to the boundary — only for `beforeSend` to drop it,
+ * since it lets through the error page's reports alone.
+ */
+export const copyError = (error: unknown): Error => {
+  if (!(error instanceof Error)) return new Error(String(error));
+
+  const copy = new Error(error.message);
+  copy.name = error.name;
+  copy.stack = error.stack;
+  return copy;
+};
+
+export const buildUncaughtErrorReport = (
+  error: Error & { digest?: string },
+  decision: UncaughtErrorDecision
+): UncaughtErrorReport => {
+  const fingerprint =
+    decision.kind !== 'uncaught'
+      ? ['UNCAUGHT_ERROR_PAGE', decision.kind]
+      : error.digest
+      ? // A server error reaches the client with a generic message; its
+        // digest is what tells one apart from another.
+        ['UNCAUGHT_ERROR_PAGE', error.digest]
+      : ['UNCAUGHT_ERROR_PAGE', '{{ default }}'];
+
+  return {
+    error: copyError(error),
+    level: decision.kind === 'uncaught' ? 'fatal' : 'warning',
+    fingerprint,
+    tags: {
+      UNCAUGHT_ERROR_KIND: decision.kind,
+      RECOVERY: decision.recovering ? 'attempted' : 'none'
+    }
+  };
+};

package/views/error-page.tsx

@@ -1,5 +1,5 @@
 import { useEffect, useState } from 'react';
-import { useLocalization } from '../hooks';
+import { useLocalization, useUncaughtErrorRecovery } from '../hooks';
 import { Button, Link } from '../components';
 import { ROUTES } from 'routes';
 
@@ -36,6 +36,11 @@ function ClientErrorUI({
   reset: () => void;
 }) {
   const { t } = useLocalization();
+  // A stale chunk or a DOM mutation race reloads the page; the 500 page would
+  // only flash before it.
+  const recovering = useUncaughtErrorRecovery(error);
+
+  if (recovering) return null;
 
   const errorMessage = error?.message || 'Unknown error';