From 7fbbb6f0f66a597a797b127a095a64091b48f3a0 Mon Sep 17 00:00:00 2001
From: Yevheniia Sorokina <yevheniia.sorokina@scandit.com>
Date: Mon, 12 Oct 2026 12:14:07 +0100
Subject: [PATCH] Report page crashes, recover from stale chunks, and survive
 page translation

- Errors caught by the error boundaries never reach window.onerror, so
  exception autocapture missed them. Both fallbacks now report the crash
  to PostHog, waiting up to 15 s for it to load and respecting an opt-out.
- A first page load that asks for chunks a deploy removed fails before
  hydration, as an unhandled rejection, and leaves the page inert. It now
  reloads, at most once per page per tab in 10 minutes; a failure the
  guard blocks is reported. After the app has started, failed chunks
  (link preloads on hover) are left to Docusaurus.
- Browser translation moves text nodes React owns, and React's next
  removeChild or insertBefore throws. A guard tolerates the moved node and
  logs a warning (the workaround from facebook/react#11538).
  translate="no" on the copyable commands, the agent picker and both
  framework pickers.
- capturePostHogEvent and the crash reporter share one helper for calling
  PostHog (callPostHog), so the availability, opt-out and error rules live
  in one place.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 docusaurus.config.ts                          |  2 +
 src/clientModules/chunkLoadRecovery.ts        | 33 +++++++
 src/clientModules/translationGuard.ts         | 40 +++++++++
 .../HomePage/Frameworks/Frameworks.tsx        |  4 +-
 .../HomePage/Frameworks/FrameworksMobile.tsx  |  4 +-
 src/components/SkillsCallout/CommandBlock.tsx |  3 +
 .../SkillsCallout/ManualInstall.tsx           |  2 +
 src/components/SkillsCallout/analytics.ts     | 30 ++-----
 src/theme/Error/index.js                      | 10 +++
 src/theme/ErrorPageContent/index.js           |  9 ++
 src/utils/crashReporting.ts                   | 87 +++++++++++++++++++
 src/utils/posthog.ts                          | 37 ++++++++
 12 files changed, 235 insertions(+), 26 deletions(-)
 create mode 100644 src/clientModules/chunkLoadRecovery.ts
 create mode 100644 src/clientModules/translationGuard.ts
 create mode 100644 src/theme/Error/index.js
 create mode 100644 src/theme/ErrorPageContent/index.js
 create mode 100644 src/utils/crashReporting.ts
 create mode 100644 src/utils/posthog.ts

diff --git a/docusaurus.config.ts b/docusaurus.config.ts
index e3c379db9b..d6ed88022c 100644
--- a/docusaurus.config.ts
+++ b/docusaurus.config.ts
@@ -955,6 +955,8 @@ const config: Config = {
   },
   clientModules: [
     require.resolve('./src/clientModules/agentSkillsNavLink.ts'),
+    require.resolve('./src/clientModules/translationGuard.ts'),
+    require.resolve('./src/clientModules/chunkLoadRecovery.ts'),
   ],
   plugins: [
     [
diff --git a/src/clientModules/chunkLoadRecovery.ts b/src/clientModules/chunkLoadRecovery.ts
new file mode 100644
index 0000000000..5c6e9edbdd
--- /dev/null
+++ b/src/clientModules/chunkLoadRecovery.ts
@@ -0,0 +1,33 @@
+import {
+  isChunkLoadError,
+  reloadOnceForChunkError,
+  reportCrash,
+} from '@site/src/utils/crashReporting';
+
+/**
+ * Recover a first page load that asks for chunks a deploy has removed.
+ *
+ * A cached or long-open HTML page from the previous build references chunk
+ * hashes that no longer exist. Docusaurus already reloads when that happens
+ * during in-app navigation, but on the first load the route's chunks are
+ * fetched before hydration, and the failure is an unhandled rejection: the
+ * page stays as inert server-rendered HTML. Reload instead (see
+ * reloadOnceForChunkError for the loop guard). When the guard declines, the
+ * page will not start, so report it.
+ *
+ * Only until the app has started: after that, a failed chunk is a link
+ * preload on hover, and reloading the page the reader is on would be wrong.
+ */
+let started = false;
+
+if (typeof window !== 'undefined') {
+  window.addEventListener('unhandledrejection', (event) => {
+    if (started || !isChunkLoadError(event.reason)) return;
+    if (!reloadOnceForChunkError(event.reason)) reportCrash(event.reason, 'first-load');
+  });
+}
+
+// Runs on the first render after hydration too, not only on navigation.
+export function onRouteDidUpdate(): void {
+  started = true;
+}
diff --git a/src/clientModules/translationGuard.ts b/src/clientModules/translationGuard.ts
new file mode 100644
index 0000000000..531cf36a14
--- /dev/null
+++ b/src/clientModules/translationGuard.ts
@@ -0,0 +1,40 @@
+/**
+ * Keep React working when the browser translates the page.
+ *
+ * Chrome and Edge translation replace text nodes with their own <font>
+ * wrappers. When React later removes or inserts next to a node it believes it
+ * owns, the node is no longer where React left it, and the DOM throws
+ * "Failed to execute 'removeChild' on 'Node'", which takes the whole page
+ * down.
+ *
+ * The guard makes the two operations tolerate a node the translator moved:
+ * removing a node that is no longer a child does nothing, and inserting before
+ * one appends instead. Neither path runs unless the DOM would have thrown, and
+ * both log a warning so a real bug stays visible. This is the workaround from
+ * facebook/react#11538.
+ */
+if (typeof window !== 'undefined' && typeof Node === 'function' && Node.prototype) {
+  const originalRemoveChild = Node.prototype.removeChild;
+  Node.prototype.removeChild = function removeChild<T extends Node>(this: Node, child: T): T {
+    if (child.parentNode !== this) {
+      console.warn('Cannot remove a child from a different parent', child, this);
+      return child;
+    }
+    return originalRemoveChild.call(this, child) as T;
+  };
+
+  const originalInsertBefore = Node.prototype.insertBefore;
+  Node.prototype.insertBefore = function insertBefore<T extends Node>(
+    this: Node,
+    newNode: T,
+    referenceNode: Node | null,
+  ): T {
+    if (referenceNode && referenceNode.parentNode !== this) {
+      console.warn('Cannot insert before a reference node from a different parent', referenceNode, this);
+      return originalInsertBefore.call(this, newNode, null) as T;
+    }
+    return originalInsertBefore.call(this, newNode, referenceNode) as T;
+  };
+}
+
+export {};
diff --git a/src/components/HomePage/Frameworks/Frameworks.tsx b/src/components/HomePage/Frameworks/Frameworks.tsx
index d2f12fb73f..64b1056064 100644
--- a/src/components/HomePage/Frameworks/Frameworks.tsx
+++ b/src/components/HomePage/Frameworks/Frameworks.tsx
@@ -64,7 +64,9 @@ export default function Frameworks({ handleFrameworkClick }: FrameworksProps) {
       <h4 className={style.text}>
         Select Your Framework to View Supported Products and Features
       </h4>
-      <form className={style.iconList}>
+      {/* Framework names are product names, and the labels change as the
+          selection does: left to a page translator they can crash React. */}
+      <form className={style.iconList} translate="no">
         {frameworkCards.map((item) => {
           return (
             <div
diff --git a/src/components/HomePage/Frameworks/FrameworksMobile.tsx b/src/components/HomePage/Frameworks/FrameworksMobile.tsx
index b87e6acd71..f8b95a5b68 100644
--- a/src/components/HomePage/Frameworks/FrameworksMobile.tsx
+++ b/src/components/HomePage/Frameworks/FrameworksMobile.tsx
@@ -68,7 +68,9 @@ export default function FrameworksMobile({
       </h4>
       <BrowserOnly>
         {() => (
-          <div className={style.frameworksMobile}>
+          // Framework names are product names, and the labels change as the
+          // selection does: left to a page translator they can crash React.
+          <div className={style.frameworksMobile} translate="no">
             <div
               className={style.field}
               onClick={() => setOpenSelector(!openSelector)}
diff --git a/src/components/SkillsCallout/CommandBlock.tsx b/src/components/SkillsCallout/CommandBlock.tsx
index 9ec3459818..71303f5973 100644
--- a/src/components/SkillsCallout/CommandBlock.tsx
+++ b/src/components/SkillsCallout/CommandBlock.tsx
@@ -87,6 +87,9 @@ const CommandBlock: React.FC<CommandBlockProps> = ({
     <div className={styles.commandBlock}>
       <pre
         className={`${styles.command} ${prose ? styles.commandProse : ''}`}
+        // A translated command no longer runs, and translation of a node React
+        // owns can crash the page (see clientModules/translationGuard).
+        translate="no"
         onCopy={handleTextCopy}
       ><code>{command}</code></pre>
       <button
diff --git a/src/components/SkillsCallout/ManualInstall.tsx b/src/components/SkillsCallout/ManualInstall.tsx
index d5ec0ff8df..b8f2955286 100644
--- a/src/components/SkillsCallout/ManualInstall.tsx
+++ b/src/components/SkillsCallout/ManualInstall.tsx
@@ -57,6 +57,8 @@ const ManualInstall: React.FC<ManualInstallProps> = ({ framework }) => {
         <select
           id="skills-agent-picker"
           className={styles.manualSelect}
+          // Agent and platform names are product names.
+          translate="no"
           value={agent.key}
           onChange={handleChange}
         >
diff --git a/src/components/SkillsCallout/analytics.ts b/src/components/SkillsCallout/analytics.ts
index df05b08759..7e708d5ce3 100644
--- a/src/components/SkillsCallout/analytics.ts
+++ b/src/components/SkillsCallout/analytics.ts
@@ -1,18 +1,12 @@
-type PostHogCapture = (event: string, props?: Record<string, unknown>) => void;
-
-type PostHogLike = {
-  capture?: PostHogCapture;
-  has_opted_out_capturing?: () => boolean;
-};
+import { callPostHog } from '@site/src/utils/posthog';
 
 /**
  * Send an event to PostHog, and report whether it was accepted.
  *
- * PostHog is loaded by GTM behind the cookie banner, so `window.posthog` is
- * simply absent until a reader consents - and on a first page view it usually
- * is. The previous version swallowed that (`ph?.capture?.()`), which is fine
- * for a fire-and-forget signal but not for anything that then tells the reader
- * their input was delivered. Callers that don't care can ignore the result.
+ * PostHog is often not loaded yet (see callPostHog). The previous version
+ * swallowed that (`ph?.capture?.()`), which is fine for a fire-and-forget
+ * signal but not for anything that then tells the reader their input was
+ * delivered. Callers that don't care can ignore the result.
  *
  * `true` means PostHog accepted the event, NOT that it reached the server. Two
  * cases it cannot see: the loader stub queues `capture` before the library
@@ -20,19 +14,7 @@ type PostHogLike = {
  * accepted; and a network failure after that is invisible here. An explicit
  * opt-out IS detected, since that is the case a reader can create themselves
  * and would be most surprised to see reported as sent.
- *
- * A throwing capture is caught rather than propagated: this runs inside click
- * handlers, and an exception escaping one leaves the UI inert.
  */
 export function capturePostHogEvent(event: string, props?: Record<string, unknown>): boolean {
-  if (typeof window === 'undefined') return false;
-  const ph = (window as unknown as { posthog?: PostHogLike }).posthog;
-  if (typeof ph?.capture !== 'function') return false;
-  try {
-    if (ph.has_opted_out_capturing?.() === true) return false;
-    ph.capture(event, props);
-    return true;
-  } catch {
-    return false;
-  }
+  return callPostHog('capture', (ph) => ph.capture(event, props)) === 'sent';
 }
diff --git a/src/theme/Error/index.js b/src/theme/Error/index.js
new file mode 100644
index 0000000000..58294b473a
--- /dev/null
+++ b/src/theme/Error/index.js
@@ -0,0 +1,10 @@
+import React from "react";
+import OriginalError from "@theme-original/Error";
+import { useCrashHandling } from "@site/src/utils/crashReporting";
+
+// The site-wide error boundary's fallback, for a crash outside a page's
+// content (the layout, navbar or footer). See ErrorPageContent for the rest.
+export default function Error(props) {
+  useCrashHandling(props.error, "site");
+  return <OriginalError {...props} />;
+}
diff --git a/src/theme/ErrorPageContent/index.js b/src/theme/ErrorPageContent/index.js
new file mode 100644
index 0000000000..27efedecd6
--- /dev/null
+++ b/src/theme/ErrorPageContent/index.js
@@ -0,0 +1,9 @@
+import React from "react";
+import OriginalErrorPageContent from "@theme-original/ErrorPageContent";
+import { useCrashHandling } from "@site/src/utils/crashReporting";
+
+// The fallback of the error boundary around every page's content.
+export default function ErrorPageContent(props) {
+  useCrashHandling(props.error, "page");
+  return <OriginalErrorPageContent {...props} />;
+}
diff --git a/src/utils/crashReporting.ts b/src/utils/crashReporting.ts
new file mode 100644
index 0000000000..bb069d74ca
--- /dev/null
+++ b/src/utils/crashReporting.ts
@@ -0,0 +1,87 @@
+import { useEffect } from 'react';
+import { callPostHog } from '@site/src/utils/posthog';
+
+const reported = new WeakSet<object>();
+
+// PostHog loads after the app starts, so a crash during or soon after
+// hydration finds it missing. Wait for it this long before giving up.
+const POSTHOG_WAIT_MS = 1000;
+const POSTHOG_WAIT_ATTEMPTS = 15;
+
+/**
+ * Send a crash caught by a React error boundary to PostHog.
+ *
+ * Exception autocapture only sees errors that reach window.onerror, and an
+ * error a boundary catches never does, so report it explicitly.
+ *
+ * Nothing is sent after an explicit opt-out, or when PostHog has not loaded
+ * within the wait. Each error is reported once: a boundary's fallback can
+ * render more than once for the same error.
+ */
+export function reportCrash(error: unknown, source: string, attempt = 0): void {
+  if (typeof window === 'undefined') return;
+  if (attempt === 0 && error && typeof error === 'object') {
+    if (reported.has(error)) return;
+    reported.add(error);
+  }
+  const result = callPostHog('captureException', (ph) =>
+    ph.captureException(error, { crash_source: source }),
+  );
+  if (result === 'unavailable' && attempt < POSTHOG_WAIT_ATTEMPTS) {
+    window.setTimeout(() => reportCrash(error, source, attempt + 1), POSTHOG_WAIT_MS);
+  }
+}
+
+/**
+ * A failed load of one of the build's JavaScript or CSS chunks.
+ *
+ * After a deploy, a page opened on the previous build asks for chunk hashes
+ * that no longer exist. webpack names the error ChunkLoadError; the CSS loader
+ * only says so in the message.
+ */
+export function isChunkLoadError(error: unknown): boolean {
+  if (!error || typeof error !== 'object') return false;
+  const { name, message } = error as { name?: unknown; message?: unknown };
+  return (
+    name === 'ChunkLoadError' ||
+    (typeof message === 'string' && /Loading (?:CSS )?chunk \S+ failed/.test(message))
+  );
+}
+
+const RELOAD_KEY_PREFIX = 'chunk-reload:';
+// Long enough to stop a chunk that is really missing from reloading in a loop,
+// short enough that the next deploy can be recovered in the same tab.
+const RELOAD_COOLDOWN_MS = 10 * 60 * 1000;
+
+/**
+ * Reload the page when a chunk failed to load, so the reader gets the current
+ * build instead of an error. Returns whether it reloaded.
+ *
+ * At most once per page per tab within the cooldown, recorded in
+ * sessionStorage. If sessionStorage is unavailable (blocked storage, some
+ * private modes) it does not reload at all, since nothing would stop a loop.
+ */
+export function reloadOnceForChunkError(error: unknown): boolean {
+  if (typeof window === 'undefined' || !isChunkLoadError(error)) return false;
+  const key = RELOAD_KEY_PREFIX + window.location.pathname;
+  try {
+    const last = Number(window.sessionStorage.getItem(key));
+    if (last && Date.now() - last < RELOAD_COOLDOWN_MS) return false;
+    window.sessionStorage.setItem(key, String(Date.now()));
+  } catch {
+    return false;
+  }
+  window.location.reload();
+  return true;
+}
+
+/**
+ * For an error boundary's fallback: reload for a chunk left behind by a
+ * deploy, and report anything else (or a chunk error the reload could not
+ * fix) as a crash.
+ */
+export function useCrashHandling(error: unknown, source: string): void {
+  useEffect(() => {
+    if (!reloadOnceForChunkError(error)) reportCrash(error, source);
+  }, [error, source]);
+}
diff --git a/src/utils/posthog.ts b/src/utils/posthog.ts
new file mode 100644
index 0000000000..f3e309d069
--- /dev/null
+++ b/src/utils/posthog.ts
@@ -0,0 +1,37 @@
+export type PostHogLike = {
+  capture?: (event: string, props?: Record<string, unknown>) => void;
+  captureException?: (error: unknown, props?: Record<string, unknown>) => void;
+  has_opted_out_capturing?: () => boolean;
+};
+
+/**
+ * What became of a call: `unavailable` when PostHog (or the method) is not
+ * loaded, `opted-out` after the reader opted out, `failed` when the call threw.
+ * `sent` means PostHog accepted it, NOT that it reached the server.
+ */
+export type PostHogCallResult = 'sent' | 'unavailable' | 'opted-out' | 'failed';
+
+/**
+ * Call one PostHog method under the rules every capture on the site follows.
+ *
+ * PostHog is loaded by GTM behind the cookie banner, so `window.posthog` is
+ * absent until it loads, and on a first page view it usually is. An explicit
+ * opt-out is respected. A throwing call is caught rather than propagated:
+ * these run inside click handlers and error fallbacks, and an exception
+ * escaping one leaves the UI inert.
+ */
+export function callPostHog(
+  method: 'capture' | 'captureException',
+  call: (ph: Required<PostHogLike>) => void,
+): PostHogCallResult {
+  if (typeof window === 'undefined') return 'unavailable';
+  const ph = (window as unknown as { posthog?: PostHogLike }).posthog;
+  if (typeof ph?.[method] !== 'function') return 'unavailable';
+  try {
+    if (ph.has_opted_out_capturing?.() === true) return 'opted-out';
+    call(ph as Required<PostHogLike>);
+    return 'sent';
+  } catch {
+    return 'failed';
+  }
+}