Address PR #3933 review: dev-default reporting, merge semantics, shared isThenable

Review fixes from the Claude Code review pass and Cursor Bugbot on PR #3933:

1. Dev-mode hydration logger no longer swallows React's default
   reporting or the component stack. The error is default-reported
   exactly once (reportError, falling back to console.error — mirroring
   React's own default) so window-'error' tooling keeps working, and the
   branded line now includes errorInfo.componentStack.
2. New buildRootErrorCallbackOptions option
   defaultReportingHandledInternally: Pro's RSC-wrapped hydrate paths
   pass it so the chained internal handler remains the single default
   reporter and the dev logger emits only its supplemental branded line
   (no second full error dump in development). Added a Pro test covering
   the chained dev path with railsEnv development.
3. getRootErrorHandlers now returns a snapshot copy so callers cannot
   mutate the internal registration and bypass validation.
4. Extracted the three byte-identical isThenable copies into
   packages/react-on-rails/src/isThenable.ts (exported as
   react-on-rails/@internal/isThenable) and removed the MUST-SYNC
   thenable-guard duplication note from the Pro renderer.
5. Partial rootErrorHandlers updates now merge per key (consistent with
   the other setOptions keys): setting only one callback keeps the
   others; an explicit undefined clears just that key; resetOptions
   still clears all. setOptions stores the merged result so
   option('rootErrorHandlers') reflects the effective registration.

Docs (guide, JS API reference, type JSDoc) and the changelog entry
updated to describe the preserved default reporting, component stack,
and merge semantics.

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

Author: justin808

CHANGELOG.md

@@ -26,7 +26,7 @@ After a release, run `/update-changelog` in Claude Code to analyze commits, writ
 
 #### 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 containing the component name and DOM id. In development, recoverable hydration errors now log an actionable React on Rails message (component name, dom id, and a link to the new [Debugging Hydration Mismatches guide](https://reactonrails.com/docs/building-features/debugging-hydration-mismatches)) instead of React's bare console line. On React <19 (and <18 for `onRecoverableError`), registration is a graceful no-op with a 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).
+- **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 containing the component name and DOM id. 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`), registration is a graceful no-op with a 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).
 
 ### [17.0.0.rc.2] - 2026-06-09
 

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

@@ -82,6 +82,7 @@ reactHydrateOrRender(domNode, reactElement, hydrate);
  * `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 with the componentName and domNodeId.
+ *   Partial updates merge per key (setting one callback later keeps the others).
  *   onRecoverableError requires React 18+; onCaughtError/onUncaughtError require React 19.
  *   See https://reactonrails.com/docs/building-features/debugging-hydration-mismatches
  */

docs/oss/building-features/debugging-hydration-mismatches.md

@@ -8,12 +8,16 @@ Rails apps hit a set of systematic causes that JavaScript-only frameworks rarely
 
 ### Development default
 
-When `Rails.env.development?`, React on Rails automatically logs every recoverable hydration error with the component name, the DOM id, and a link to this guide — replacing React's bare console line:
+When `Rails.env.development?`, React on Rails automatically logs every recoverable hydration error with the component name, the DOM id, the component stack (when React provides one), and a link to this guide:
 
 ```text
 [ReactOnRails] Recoverable hydration error in component "MyComponent" (dom id: "MyComponent-react-component-0"). ...
+Component stack:
+    at MyComponent
 ```
 
+React's default error reporting is preserved: the error itself is still reported once via `reportError` (falling back to `console.error`), so dev overlays and other window-`'error'`-based tooling keep working. The branded line is supplemental context. On React on Rails Pro RSC hydration paths, Pro's internal handler already reports the error, so only the supplemental line is added — each error is reported exactly once either way.
+
 No setup is required. The default logger runs in addition to any callback you register.
 
 ### Registering root error callbacks (React 19)
@@ -51,7 +55,8 @@ Each callback receives React's original `(error, errorInfo)` arguments plus a `c
 
 Notes:
 
-- **Register before rendering.** Callbacks apply to roots created after registration; register them in the same pack file where you call `ReactOnRails.register`.
+- **Register before rendering.** Each root captures the callbacks registered at the moment it is created; register them in the same pack file where you call `ReactOnRails.register`.
+- **Partial updates merge per key.** A later `setOptions({ rootErrorHandlers: { onCaughtError } })` keeps a previously registered `onRecoverableError`/`onUncaughtError`. Pass an explicit `undefined` for a key to clear just that callback; `ReactOnRails.resetOptions()` clears all of them.
 - **React version support:** `onRecoverableError` requires React 18+; `onCaughtError`/`onUncaughtError` require React 19. On older React versions, registration is a graceful no-op and React on Rails logs a one-time `console.warn`.
 - **React on Rails Pro:** on RSC/streaming hydration paths, Pro installs an internal `onRecoverableError` for its own bookkeeping. Your callback is chained after it — both always run, and Pro's internal control-flow signals (such as the `RSCRoute` `ssr: false` bailout) are filtered out of both so they never reach your error reporter.
 - **Per-component overrides** are not currently supported; the global registration above is the blessed route.

packages/react-on-rails-pro/src/ClientSideRenderer.ts

@@ -33,6 +33,7 @@ import { supportsHydrate, supportsRootApi, unmountComponentAtNode } from 'react-
 import reactHydrateOrRender from 'react-on-rails/reactHydrateOrRender';
 import { debugTurbolinks } from 'react-on-rails/turbolinksUtils';
 import { buildRootErrorCallbackOptions } from 'react-on-rails/@internal/rootErrorHandlers';
+import { isThenable } from 'react-on-rails/@internal/isThenable';
 import { maybeWrapWithDefaultRSCProviderWithStatus } from './defaultRSCProviderRegistry.ts';
 import { chainRecoverableErrorHandlers } from './handleRecoverableError.client.ts';
 
@@ -41,24 +42,14 @@ import * as ComponentRegistry from './ComponentRegistry.ts';
 
 const REACT_ON_RAILS_STORE_ATTRIBUTE = 'data-js-react-on-rails-store';
 
-/** Narrows an unknown value to a thenable (has a callable `.then`) without assuming a native Promise. */
-function isThenable(value: unknown): value is PromiseLike<unknown> {
-  return (
-    value != null &&
-    (typeof value === 'object' || typeof value === 'function') &&
-    typeof (value as { then?: unknown }).then === 'function'
-  );
-}
-
 /**
  * Invokes a renderer teardown, swallowing async rejections so a failing teardown cannot produce an
  * unhandled promise rejection. Synchronous throws propagate to the caller's try/catch.
  *
  * Intentionally re-implemented (not imported) from the OSS `react-on-rails` `invokeRendererTeardown`:
  * the OSS module does not export it, so re-implementing keeps the Pro client renderer decoupled from
  * OSS internals (no reliance on a non-public export) instead of widening the OSS public API just to
- * share it. Keep the local thenable guard in sync with the OSS helper so non-native thenables are
- * handled the same way in both packages. The shared `RendererFunction`/`RendererTeardown`/
+ * share it. The thenable guard (`isThenable`) and the shared `RendererFunction`/`RendererTeardown`/
  * `RendererTeardownResult` *types* are imported, so only this small runtime helper is duplicated.
  * MUST SYNC: A sibling helper exists in packages/react-on-rails/src/ClientRenderer.ts. If you
  * change the error-handling logic or log format here, update that copy too.
@@ -259,10 +250,12 @@ You should return a React.Component always for the client side entry point.`);
           // component name and dom id. Applied to every root; on the RSC-wrapped hydrate path the
           // user onRecoverableError is CHAINED after Pro's internal recoverable-error handler so
           // both run (the internal handler must never be clobbered, and the user callback must
-          // never be dropped).
+          // never be dropped). On that chained path the internal handler already default-reports
+          // the error, so the dev-mode logger must emit only its supplemental branded line.
           const userErrorCallbackOptions = buildRootErrorCallbackOptions(
             { componentName: name, domNodeId },
             shouldHydrate,
+            { defaultReportingHandledInternally: wrappedByDefaultRSCProvider && shouldHydrate },
           );
           let renderOptions: Parameters<typeof reactHydrateOrRender>[3] = userErrorCallbackOptions;
           if (wrappedByDefaultRSCProvider) {

packages/react-on-rails-pro/src/wrapServerComponentRenderer/client.tsx

@@ -124,11 +124,16 @@ const wrapServerComponentRenderer = (
 
     // User-registered root error callbacks (rootErrorHandlers), wrapped with this mount's
     // component name and dom id. On the hydrate path the user onRecoverableError is CHAINED after
-    // Pro's internal recoverable-error handler so both run.
+    // Pro's internal recoverable-error handler so both run; the internal handler already
+    // default-reports the error there, so the dev-mode logger emits only its supplemental branded
+    // line (the flag is moot on the createRoot path, where the dev logger is not attached).
     const shouldHydrate = !!domNode.innerHTML;
     const userErrorCallbackOptions = buildRootErrorCallbackOptions(
       { componentName, domNodeId },
       shouldHydrate,
+      {
+        defaultReportingHandledInternally: shouldHydrate,
+      },
     );
     const reactRoot = shouldHydrate
       ? ReactDOMClient.hydrateRoot(domNode, rootElement, {

packages/react-on-rails-pro/tests/ClientSideRenderer.test.ts

@@ -396,6 +396,58 @@ describe('ClientSideRenderer', () => {
     }
   });
 
+  it('emits one internal report plus the supplemental branded dev line on the chained dev hydrate path', async () => {
+    // railsEnv 'development' + RSC-wrapped hydrate: the chained handler must default-report the
+    // error exactly once (Pro's internal handler), with the dev logger adding only its branded
+    // supplemental line — never a second full error dump.
+    const TestComponent = ({ greeting }: { greeting: string }) => React.createElement('div', null, greeting);
+    const defaultProviderFactory = jest.fn(({ reactElement }: DefaultRSCProviderFactoryArgs) => reactElement);
+    const globalWithReportError = globalThis as typeof globalThis & {
+      reportError?: (error: unknown) => void;
+    };
+    const originalReportError = globalWithReportError.reportError;
+    const reportErrorSpy = jest.fn();
+    globalWithReportError.reportError = reportErrorSpy;
+    const userOnRecoverableError = jest.fn();
+    setRootErrorHandlers({ onRecoverableError: userOnRecoverableError });
+    ComponentRegistry.register({ TestComponent });
+    const componentSpec = setupTestComponentDom('dom-id-dev', '<div>Server fallback</div>');
+    addRailsContext({ railsEnv: 'development', rscPayloadGenerationUrlPath: '/rsc_payload' });
+    setDefaultRSCProviderFactory(defaultProviderFactory);
+
+    try {
+      await renderOrHydrateComponent(componentSpec);
+
+      const recoverableError = new Error('dev chained recoverable error');
+      const errorInfo = { componentStack: '\n    at TestComponent' };
+      const onRecoverableError = expectRecoverableHandlerFromLastRender();
+      (onRecoverableError as (error: unknown, errorInfo: unknown) => void)(recoverableError, errorInfo);
+
+      // Exactly one default report — Pro's internal handler.
+      expect(reportErrorSpy).toHaveBeenCalledTimes(1);
+      expect(reportErrorSpy).toHaveBeenCalledWith(recoverableError);
+
+      // Exactly one console.error: the branded supplemental line (context + stack + guide link),
+      // not a second full error dump.
+      const consoleErrorCalls = (console.error as jest.Mock).mock.calls;
+      expect(consoleErrorCalls).toHaveLength(1);
+      const [message] = consoleErrorCalls[0] as [unknown];
+      expect(message).toEqual(expect.stringContaining('[ReactOnRails] Recoverable hydration error'));
+      expect(message).toEqual(expect.stringContaining('"TestComponent"'));
+      expect(message).toEqual(expect.stringContaining('dom-id-dev'));
+      expect(message).toEqual(expect.stringContaining('Component stack:'));
+      expect(consoleErrorCalls[0]).toHaveLength(1);
+
+      // The user callback still runs with the enriched context.
+      expect(userOnRecoverableError).toHaveBeenCalledWith(recoverableError, errorInfo, {
+        componentName: 'TestComponent',
+        domNodeId: 'dom-id-dev',
+      });
+    } finally {
+      globalWithReportError.reportError = originalReportError;
+    }
+  });
+
   it('passes user root error callbacks on non-RSC-wrapped hydrate paths without the internal handler', async () => {
     const TestComponent = ({ greeting }: { greeting: string }) => React.createElement('div', null, greeting);
     const globalWithReportError = globalThis as typeof globalThis & {

packages/react-on-rails/package.json

@@ -54,6 +54,7 @@
     "./@internal/sanitizeNonce": "./lib/sanitizeNonce.js",
     "./@internal/rendererTeardown": "./lib/rendererTeardown.js",
     "./@internal/rootErrorHandlers": "./lib/rootErrorHandlers.js",
+    "./@internal/isThenable": "./lib/isThenable.js",
     "./@internal/base/client": "./lib/base/client.js",
     "./@internal/base/full": {
       "react-server": "./lib/base/full.rsc.js",

packages/react-on-rails/src/ClientRenderer.ts

@@ -17,6 +17,7 @@ import { onPageUnloaded } from './pageLifecycle.ts';
 import { supportsRootApi, unmountComponentAtNode } from './reactApis.cts';
 import { isRendererTeardownResult } from './rendererTeardown.ts';
 import { buildRootErrorCallbackOptions } from './rootErrorHandlers.ts';
+import { isThenable } from './isThenable.ts';
 
 const REACT_ON_RAILS_STORE_ATTRIBUTE = 'data-js-react-on-rails-store';
 
@@ -35,15 +36,6 @@ type RenderedEntry =
   | { kind: 'react'; root: RenderReturnType; domNode: Element }
   | { kind: 'renderer'; teardown?: RendererTeardown; domNode: Element };
 
-/** Narrows an unknown value to a thenable (has a callable `.then`) without assuming a native Promise. */
-function isThenable(value: unknown): value is PromiseLike<unknown> {
-  return (
-    value != null &&
-    (typeof value === 'object' || typeof value === 'function') &&
-    typeof (value as { then?: unknown }).then === 'function'
-  );
-}
-
 // Track all rendered roots for cleanup
 const renderedRoots = new Map<string, RenderedEntry>();
 

packages/react-on-rails/src/base/client.ts

@@ -21,6 +21,7 @@ import createReactOutput from '../createReactOutput.ts';
 import componentRegistrationMetric from '../componentRegistrationMetric.ts';
 import {
   buildRootErrorCallbackOptions,
+  getRootErrorHandlers,
   resetRootErrorHandlers,
   setRootErrorHandlers,
 } from '../rootErrorHandlers.ts';
@@ -180,9 +181,11 @@ Fix: Use only react-on-rails OR react-on-rails-pro, not both.`);
       }
 
       if (typeof newOptions.rootErrorHandlers !== 'undefined') {
-        // Validates and stores the handlers; warns when the React runtime cannot support them.
+        // Validates and merges the handlers per key (partial updates keep previously registered
+        // callbacks); warns when the React runtime cannot support them. Store the merged result so
+        // `option('rootErrorHandlers')` reflects the effective registration.
         setRootErrorHandlers(newOptions.rootErrorHandlers);
-        this.options.rootErrorHandlers = newOptions.rootErrorHandlers;
+        this.options.rootErrorHandlers = getRootErrorHandlers();
         // eslint-disable-next-line no-param-reassign
         delete newOptions.rootErrorHandlers;
       }

packages/react-on-rails/src/capabilities/core.ts

@@ -15,6 +15,7 @@ import createReactOutput from '../createReactOutput.ts';
 import componentRegistrationMetric from '../componentRegistrationMetric.ts';
 import {
   buildRootErrorCallbackOptions,
+  getRootErrorHandlers,
   resetRootErrorHandlers,
   setRootErrorHandlers,
 } from '../rootErrorHandlers.ts';
@@ -101,9 +102,11 @@ export function createCoreCapability(registries: Registries) {
       }
 
       if (typeof rootErrorHandlers !== 'undefined') {
-        // Validates and stores the handlers; warns when the React runtime cannot support them.
+        // Validates and merges the handlers per key (partial updates keep previously registered
+        // callbacks); warns when the React runtime cannot support them. Store the merged result so
+        // `option('rootErrorHandlers')` reflects the effective registration.
         setRootErrorHandlers(rootErrorHandlers);
-        this.options.rootErrorHandlers = rootErrorHandlers;
+        this.options.rootErrorHandlers = getRootErrorHandlers();
       }
 
       if (Object.keys(rest).length > 0) {