Expose React 19 root error callbacks (rootErrorHandlers) + hydration-mismatch debugging guide

.bundle-size-skip-branch

@@ -1,7 +1,5 @@
-# This file allows skipping the bundle size CI check for a specific branch.
-# When a branch name in this file matches the PR branch, the size check is skipped.
-#
-# Usage: Run `bin/skip-bundle-size-check` to set the current branch, then commit and push.
-#
-# This is useful when you have an intentional size increase that exceeds the 0.5KB threshold.
-jg-conductor/3209-fix
+# Audited intentional growth for PR #3933 (rootErrorHandlers feature, +0.75KB gzip client):
+# 91% of the module-level delta is the new feature module; no accidental imports.
+# Audit evidence: https://github.com/shakacode/react_on_rails/pull/3933#issuecomment-4688270487
+# Clear this file in a follow-up after the PR merges.
+jg/3892-react19-root-error-callbacks

.lychee.toml

@@ -85,6 +85,7 @@ exclude = [
   '^https://reactonrails\.com/docs/reference/error-reference(#.*)?$',  # New generated docs page - live after docs deploy
   '^https://reactonrails\.com/docs/pro/react-server-components/rsc-payload-route-data/?$',  # #3783 docs page - live after docs deploy
   '^https://www\.reactonrails\.com/llms(-full(-pro)?)?\.txt$',  # Machine-readable docs endpoints; serving tracked in reactonrails.com#126
+  '^https://reactonrails\.com/docs/building-features/debugging-hydration-mismatches/?$',  # #3892 docs page - live after docs deploy
 
   # ============================================================================
   # SITES FROM PROJECTS.MD THAT BLOCK BOTS OR ARE UNRELIABLE
@@ -120,7 +121,9 @@ exclude = [
   # auto-generated by changelog tooling. GitHub PR pages also intermittently
   # return 5xx responses to lychee in CI, even when the pages are live.
   '^https://github\.com/shakacode/react_on_rails/compare/',
-  '^https://github\.com/shakacode/react_on_rails/pull/[0-9]+$',  # Intermittent 5xx from GitHub PR pages in CI
+  # PR pages intermittently return 5xx from CI; XXXX is the changelog placeholder used by
+  # in-flight batch PRs until the coordinator substitutes the real PR number.
+  '^https://github\.com/shakacode/react_on_rails/pull/([0-9]+|XXXX)$',
   '^https://github\.com/shakacode/react_on_rails/actions/workflows/pro-test-package-and-gem\.yml$',  # Intermittent 502 from GitHub Actions workflow pages in CI
   '^https://github\.com/shakacode/react_on_rails/issues/2766$',  # Intermittent 502 from GitHub issue pages in CI
   '^https://github\.com/rack/rack/blob/main/SPEC\.rdoc$',  # Intermittent 502 from GitHub blob pages in CI

CHANGELOG.md

@@ -24,6 +24,10 @@ After a release, run `/update-changelog` in Claude Code to analyze commits, writ
 
 ### [Unreleased]
 
+#### Added
+
+- **React 19 root error callbacks**: `ReactOnRails.setOptions({ rootErrorHandlers: { onRecoverableError, onCaughtError, onUncaughtError } })` registers React's root error callbacks globally; React on Rails applies them to every `hydrateRoot`/`createRoot` call it makes and invokes them with an extra context argument whose `componentName` and `domNodeId` fields are optional. In development, recoverable hydration errors now log an actionable React on Rails message (component name, dom id, component stack, and a link to the new [Debugging Hydration Mismatches guide](https://reactonrails.com/docs/building-features/debugging-hydration-mismatches)) alongside React's default error reporting, which stays intact so window-'error'-based tooling keeps working. Partial `rootErrorHandlers` updates merge per key, so registering one callback later does not drop the others. On React <19 (and <18 for `onRecoverableError`), React on Rails retains registrations for future upgrades, but the current runtime cannot invoke unsupported callbacks and logs a one-time console warning. On React on Rails Pro RSC/streaming hydration paths, user callbacks chain with (never replace) Pro's internal recoverable-error handler. Addresses [Issue 3892](https://github.com/shakacode/react_on_rails/issues/3892). [PR 3933](https://github.com/shakacode/react_on_rails/pull/3933) by [justin808](https://github.com/justin808).
+
 #### Changed
 
 - **[Pro]** **RSC peer compatibility accepts the coordinated React 19.2 floor**: The Pro node renderer now allows React and React DOM `19.2.x` starting at `19.2.7`, matching the floor required by the `react-on-rails-rsc` 19.2 package line while preserving the existing React `19.0.x` support window. Refs [Issue 3865](https://github.com/shakacode/react_on_rails/issues/3865).

docs/oss/api-reference/javascript-api.md

@@ -78,7 +78,18 @@ reactHydrateOrRender(domNode, reactElement, hydrate);
 /**
  * Set options for ReactOnRails, typically before you call ReactOnRails.register
  * Available Options:
- * `traceTurbolinks: true|false Gives you debugging messages on Turbolinks events
+ * `traceTurbolinks: true|false` Gives you debugging messages on Turbolinks events
+ * `rootErrorHandlers: { onRecoverableError, onCaughtError, onUncaughtError }` React root error
+ *   callbacks applied to every React root created by React on Rails. Each callback receives
+ *   React's (error, errorInfo) plus a context object whose componentName and domNodeId fields
+ *   are optional.
+ *   Partial updates merge per key (setting one callback later keeps the others).
+ *   onRecoverableError requires React 18+; onCaughtError/onUncaughtError require React 19.
+ *   Unsupported React versions retain registrations for future upgrades, but the current runtime
+ *   cannot invoke unsupported callbacks and logs a one-time warning.
+ *   On React on Rails Pro RSC hydration roots, onRecoverableError is chained after Pro's
+ *   internal default reporting instead of replacing it; do not report the same error again there.
+ *   See https://reactonrails.com/docs/building-features/debugging-hydration-mismatches
  */
 setOptions(options);