react-on-rails 17.0.0-rc.5 → 17.0.0-rc.6

package/lib/ClientRenderer.js

@@ -8,6 +8,7 @@ import { onPageUnloaded } from "./pageLifecycle.js";
 import { supportsRootApi, unmountComponentAtNode } from "./reactApis.cjs";
 import { isRendererTeardownResult } from "./rendererTeardown.js";
 import { buildRootErrorCallbackOptions } from "./rootErrorHandlers.js";
+import { convertToError } from "./errorUtils.js";
 import { isThenable } from "./isThenable.js";
 const REACT_ON_RAILS_STORE_ATTRIBUTE = 'data-js-react-on-rails-store';
 // Track all rendered roots for cleanup
@@ -39,6 +40,10 @@ function invokeRendererTeardown(teardown, domNodeId) {
  * abort cleanup of the remaining entries.
  */
 function teardownEntry(entry, domNodeId) {
+    if (entry.kind === 'scheduled') {
+        entry.cancel();
+        return;
+    }
     if (entry.kind === 'renderer') {
         invokeRendererTeardown(entry.teardown, domNodeId);
         return;
@@ -52,6 +57,15 @@ function teardownEntry(entry, domNodeId) {
         unmountComponentAtNode(entry.domNode);
     }
 }
+function teardownErrorLabel(entry, domNodeId) {
+    if (entry.kind === 'renderer') {
+        return `Error in renderer teardown for dom node "${domNodeId}":`;
+    }
+    if (entry.kind === 'scheduled') {
+        return `Error canceling scheduled render for dom node "${domNodeId}":`;
+    }
+    return `Error unmounting component for dom node "${domNodeId}":`;
+}
 function initializeStore(el, railsContext) {
     const name = el.getAttribute(REACT_ON_RAILS_STORE_ATTRIBUTE) || '';
     const props = el.textContent !== null ? JSON.parse(el.textContent) : {};
@@ -68,6 +82,102 @@ function forEachStore(railsContext) {
 function domNodeIdForEl(el) {
     return el.getAttribute('data-dom-id') || '';
 }
+function hydrateOnForEl(el) {
+    const hydrateOn = el.getAttribute('data-hydrate-on');
+    if (!hydrateOn || hydrateOn === 'immediate' || hydrateOn === 'visible' || hydrateOn === 'idle') {
+        return (hydrateOn || 'immediate');
+    }
+    console.warn(`[react-on-rails] Unsupported hydrate_on: ${hydrateOn}.`);
+    return 'immediate';
+}
+function hasObservableArea(element) {
+    const rects = element.getClientRects();
+    for (let index = 0; index < rects.length; index += 1) {
+        const rect = rects[index];
+        if (rect.width > 0 && rect.height > 0)
+            return true;
+    }
+    const boundingRect = element.getBoundingClientRect();
+    return boundingRect.width > 0 && boundingRect.height > 0;
+}
+function scheduleTimeout(callback, delay) {
+    const timeoutId = window.setTimeout(callback, delay);
+    return () => window.clearTimeout(timeoutId);
+}
+function scheduleWhenVisible(domNode, callback) {
+    if (typeof IntersectionObserver === 'undefined') {
+        console.warn('[react-on-rails] No IntersectionObserver.');
+        return scheduleTimeout(callback, 0);
+    }
+    if (!domNode.hasChildNodes() && !hasObservableArea(domNode)) {
+        return scheduleTimeout(callback, 0);
+    }
+    const observer = new IntersectionObserver((entries) => {
+        // Disconnect early if the target was removed outside Turbo navigation to avoid a
+        // leaked observer holding a live reference to a detached node.
+        const target = entries[0]?.target;
+        if (target && !target.isConnected) {
+            observer.disconnect();
+            return;
+        }
+        const isVisible = entries.some((entry) => entry.isIntersecting || entry.intersectionRatio > 0);
+        if (!isVisible)
+            return;
+        observer.disconnect();
+        callback();
+    }, { rootMargin: '200px 0px' });
+    observer.observe(domNode);
+    return () => {
+        observer.disconnect();
+    };
+}
+function scheduleWhenIdle(callback) {
+    const idleWindow = window;
+    if (typeof idleWindow.requestIdleCallback === 'function') {
+        const idleCallbackId = idleWindow.requestIdleCallback(callback, { timeout: 2000 });
+        return () => {
+            if (typeof idleWindow.cancelIdleCallback === 'function') {
+                idleWindow.cancelIdleCallback(idleCallbackId);
+            }
+        };
+    }
+    // Safari lacks requestIdleCallback; 50 ms defers past the current frame without a layout-blocking
+    // setTimeout(0) but still far enough before most long-idle periods (matching common polyfill defaults).
+    return scheduleTimeout(callback, 50);
+}
+function scheduleHydration(hydrateOn, domNode, callback) {
+    if (hydrateOn === 'visible') {
+        return scheduleWhenVisible(domNode, callback);
+    }
+    if (hydrateOn === 'idle') {
+        return scheduleWhenIdle(callback);
+    }
+    // Defensive: `renderElement` short-circuits for `immediate` before calling `scheduleHydration`, so
+    // this branch is normally unreachable; it acts as a safe fallback guard for future callers.
+    callback();
+    return () => { };
+}
+// Logs a normalized copy of the original thrown value, then returns a fresh ReactOnRails-prefixed
+// error for callers to throw/report. This must not mutate the original value: user code can throw
+// strings, null, cross-realm errors, or frozen Error instances, and delayed hydration catches run
+// inside scheduler callbacks where an error reporter that throws would escape the callback.
+function prepareRenderError(componentName, error) {
+    const originalError = convertToError(error);
+    console.error(originalError);
+    const renderError = new Error(`ReactOnRails encountered an error while rendering component: ${componentName}. See above error message.`);
+    renderError.cause = originalError;
+    if (typeof originalError.stack === 'string') {
+        renderError.stack = originalError.stack;
+    }
+    return renderError;
+}
+function raiseRenderError(componentName, error) {
+    throw prepareRenderError(componentName, error);
+}
+function reportRenderError(componentName, error) {
+    // prepareRenderError already logged the original error; do not log again (avoids the double-log).
+    prepareRenderError(componentName, error);
+}
 function delegateToRenderer(componentObj, props, railsContext, domNodeId, trace) {
     const { name, component, isRenderer } = componentObj;
     if (isRenderer) {
@@ -173,10 +283,14 @@ function renderElement(el, railsContext) {
             // (e.g., for asynchronously loaded content)
             const existing = renderedRoots.get(domNodeId);
             if (existing) {
-                // Only skip if it's the exact same DOM node and it's still connected to the document.
-                // If the node was replaced (e.g., via innerHTML or Turbo), we need to unmount the old
-                // root and re-render to the new node to prevent memory leaks and ensure rendering works.
-                const sameNode = existing.domNode === domNode && existing.domNode.isConnected;
+                // Only skip if it's the exact same DOM node, it's still connected to the document, AND it has
+                // actually mounted. A `scheduled` entry has not mounted yet: if its node was detached and later
+                // reattached (e.g. Turbo cache restore or a DOM move), its IntersectionObserver was disconnected
+                // and will never re-observe, so we must fall through to cancel the stale schedule and re-schedule
+                // fresh rather than skip (which would leave the island permanently non-interactive).
+                // If the node was replaced (e.g., via innerHTML or Turbo), we likewise need to unmount/cancel the
+                // old entry and re-render to the new node to prevent memory leaks and ensure rendering works.
+                const sameNode = existing.kind !== 'scheduled' && existing.domNode === domNode && existing.domNode.isConnected;
                 if (sameNode) {
                     if (trace) {
                         console.log(`Skipping already rendered component: ${name} (dom id: ${domNodeId})`);
@@ -192,10 +306,7 @@ function renderElement(el, railsContext) {
                     // Surface the failure unconditionally (matching unmountAllComponents) so a teardown/unmount
                     // error on node replacement is as visible as one on page unload, using the same greppable
                     // labels. We still continue: the old mount may leak, but the new node must be rendered.
-                    const label = existing.kind === 'renderer'
-                        ? `Error in renderer teardown for dom node "${domNodeId}":`
-                        : `Error unmounting component for dom node "${domNodeId}":`;
-                    console.error(label, unmountError);
+                    console.error(teardownErrorLabel(existing, domNodeId), unmountError);
                 }
                 renderedRoots.delete(domNodeId);
             }
@@ -207,38 +318,62 @@ function renderElement(el, railsContext) {
                 trackRendererMount(domNodeId, domNode, delegation.result);
                 return;
             }
-            // Hydrate if the DOM node has content (server-rendered HTML)
-            // Since we skip already-rendered components above, this check now correctly
-            // identifies only server-rendered content, not previously client-rendered content
-            const shouldHydrate = !!domNode.innerHTML;
-            const reactElementOrRouterResult = createReactOutput({
-                componentObj,
-                props,
-                domNodeId,
-                trace,
-                railsContext,
-                shouldHydrate,
-            });
-            if (isServerRenderHash(reactElementOrRouterResult)) {
-                throw new Error(`\
+            const mountReactRoot = () => {
+                // Hydrate if the DOM node has content (server-rendered HTML)
+                // Since we skip already-rendered components above, this check now correctly
+                // identifies only server-rendered content, not previously client-rendered content
+                const shouldHydrate = !!domNode.innerHTML;
+                const reactElementOrRouterResult = createReactOutput({
+                    componentObj,
+                    props,
+                    domNodeId,
+                    trace,
+                    railsContext,
+                    shouldHydrate,
+                });
+                if (isServerRenderHash(reactElementOrRouterResult)) {
+                    throw new Error(`\
 You returned a server side type of react-router error: ${JSON.stringify(reactElementOrRouterResult)}
 You should return a React.Component always for the client side entry point.`);
-            }
-            else {
+                }
                 const root = reactHydrateOrRender(domNode, reactElementOrRouterResult, shouldHydrate, 
                 // Attach user-registered root error callbacks (and the dev-mode hydration-mismatch
                 // logger) to every root, enriched with this mount's component name and dom id.
                 buildRootErrorCallbackOptions({ componentName: name || undefined, domNodeId: domNodeId || undefined }, shouldHydrate));
                 // Track the root for cleanup
                 renderedRoots.set(domNodeId, { kind: 'react', root, domNode });
+            };
+            const hydrateOn = hydrateOnForEl(el);
+            if (hydrateOn === 'immediate') {
+                mountReactRoot();
+                return;
             }
+            let scheduledEntry;
+            const runScheduledRender = () => {
+                if (renderedRoots.get(domNodeId) !== scheduledEntry)
+                    return;
+                if (!domNode.isConnected) {
+                    renderedRoots.delete(domNodeId);
+                    return;
+                }
+                try {
+                    mountReactRoot();
+                }
+                catch (scheduledError) {
+                    renderedRoots.delete(domNodeId);
+                    reportRenderError(name, scheduledError);
+                }
+            };
+            scheduledEntry = {
+                kind: 'scheduled',
+                domNode,
+                cancel: scheduleHydration(hydrateOn, domNode, runScheduledRender),
+            };
+            renderedRoots.set(domNodeId, scheduledEntry);
         }
     }
     catch (e) {
-        const error = e;
-        console.error(error.message);
-        error.message = `ReactOnRails encountered an error while rendering component: ${name}. See above error message.`;
-        throw error;
+        raiseRenderError(name, e);
     }
 }
 /**
@@ -295,12 +430,7 @@ function unmountAllComponents() {
             teardownEntry(entry, domNodeId);
         }
         catch (error) {
-            // Use the same label as the async-rejection path so renderer-teardown failures are greppable
-            // whether the teardown threw synchronously (here) or rejected (invokeRendererTeardown).
-            const label = entry.kind === 'renderer'
-                ? `Error in renderer teardown for dom node "${domNodeId}":`
-                : `Error unmounting component for dom node "${domNodeId}":`;
-            console.error(label, error);
+            console.error(teardownErrorLabel(entry, domNodeId), error);
         }
     });
     renderedRoots.clear();

package/lib/captureReactOwnerStack.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Whether React's dev-only `captureOwnerStack` API exists in the current build — i.e. React >= 19.1
+ * running its **development** build. Used to gate dev-mode owner-stack logging so that on older
+ * React (or any production build), where the API is absent, React's own default error reporting is
+ * left untouched (issue #3887).
+ */
+export declare function isOwnerStackSupported(): boolean;
+export default function captureReactOwnerStack(): string | undefined;
+//# sourceMappingURL=captureReactOwnerStack.d.ts.map

package/lib/captureReactOwnerStack.js

@@ -0,0 +1,64 @@
+import * as React from 'react';
+/**
+ * React's `captureOwnerStack` (added in React 19.1) returns the "owner stack" for the component
+ * currently rendering or erroring — the chain of components that created the failing element, e.g.
+ *
+ *   at Avatar
+ *   at PostCard
+ *   at PostList
+ *
+ * This is dramatically more useful for debugging than a minified JS stack because it names the
+ * components a developer actually wrote.
+ *
+ * IMPORTANT dev-build-on-server / production constraints (verified against React 19.0.x and 19.2.x):
+ *
+ * 1. `captureOwnerStack` is exported **only from React's development build**. In a production build
+ *    the export does not exist (`typeof React.captureOwnerStack !== 'function'`), so the guard below
+ *    makes this a strict no-op in production — there is no capture, no call, and no behavioral change.
+ *    This is asserted by tests.
+ * 2. It is exported only from React **>= 19.1**. On React 19.0 and earlier the export is `undefined`
+ *    even in dev builds, so the same guard covers the version requirement without needing to parse
+ *    `React.version`.
+ * 3. It returns a meaningful string **only when called synchronously while React is rendering or
+ *    handling an error** (e.g. inside an `onError`/`onCaughtError`/`onUncaughtError`/`onShellError`
+ *    callback). Called outside that window it returns `null`. Post-hoc formatting (for example the
+ *    Ruby layer, or a `try/catch` around `renderToString` after it has already thrown) cannot
+ *    capture it — which is why capture must happen JS-side inside the error callback.
+ *
+ * On the server this only yields output when React's **development** build runs in the SSR bundle.
+ * Production SSR bundles run React's production build and therefore get the no-op behavior above;
+ * that is the documented, intended outcome for production.
+ *
+ * @returns React's owner stack string verbatim (it typically begins with a newline and indented
+ *   `at <Component>` frames) when a non-empty one is available, otherwise `undefined`. The
+ *   whitespace is preserved intentionally so callers can embed it directly under a label. Never
+ *   throws.
+ */
+// `captureOwnerStack` is only present on React's dev build for React >= 19.1. Accessing it through a
+// typed-as-optional view keeps this compiling against the broad `react >= 16` peer range.
+const reactWithOwnerStack = React;
+/**
+ * Whether React's dev-only `captureOwnerStack` API exists in the current build — i.e. React >= 19.1
+ * running its **development** build. Used to gate dev-mode owner-stack logging so that on older
+ * React (or any production build), where the API is absent, React's own default error reporting is
+ * left untouched (issue #3887).
+ */
+export function isOwnerStackSupported() {
+    return typeof reactWithOwnerStack.captureOwnerStack === 'function';
+}
+export default function captureReactOwnerStack() {
+    if (typeof reactWithOwnerStack.captureOwnerStack !== 'function') {
+        return undefined;
+    }
+    try {
+        const ownerStack = reactWithOwnerStack.captureOwnerStack();
+        if (typeof ownerStack === 'string' && ownerStack.trim().length > 0) {
+            return ownerStack;
+        }
+    }
+    catch {
+        // captureOwnerStack must never break error reporting; swallow any unexpected failure.
+    }
+    return undefined;
+}
+//# sourceMappingURL=captureReactOwnerStack.js.map

package/lib/createReactOutput.js

@@ -70,9 +70,12 @@ export default function createReactOutput({ componentObj, props, railsContext, d
         if (typeof component !== 'function') {
             throw new Error(`Registered render function "${name}" must be a function.`);
         }
+        // The cast only narrows the broad RegisteredComponentValue union (which isn't structurally
+        // callable) to a concrete render-function role; it does not widen what may be returned.
         const renderFunctionResult = component(props, railsContext);
-        // Defense-in-depth: a 2-argument render function isn't expected to return a teardown wrapper, but
-        // the public RenderFunction return type can't structurally exclude it, so reject that at runtime too.
+        // Defense-in-depth: RenderFunction (= ServerRenderFunction) returns RenderFunctionResult, which
+        // already excludes RendererTeardownResult at the type level, so a teardown can't arrive here from
+        // a typed caller. Reject it at runtime anyway for untyped JS callers that ignore the contract.
         if (isRendererTeardownResult(renderFunctionResult)) {
             throw new Error(unsupportedManualRendererMessage(name));
         }

package/lib/errorUtils.d.ts

@@ -0,0 +1,4 @@
+import type { RenderingError } from './types/index.ts';
+export declare function remapSourceMappedStack(stack: RenderingError['stack']): string | undefined;
+export declare function convertToError(e: unknown): Error;
+//# sourceMappingURL=errorUtils.d.ts.map

package/lib/errorUtils.js

@@ -0,0 +1,50 @@
+// Must match SOURCE_MAP_STACK_REMAPPER_CONTEXT_KEY in
+// packages/react-on-rails-pro-node-renderer/src/worker/vmSourceMapSupport.ts.
+const SOURCE_MAPPED_STACK_REMAPPER_KEY = '__reactOnRailsProRemapStackTrace';
+export function remapSourceMappedStack(stack) {
+    const remapper = globalThis[SOURCE_MAPPED_STACK_REMAPPER_KEY];
+    if (typeof remapper !== 'function') {
+        return stack;
+    }
+    try {
+        const remappedStack = remapper(stack);
+        return typeof remappedStack === 'string' ? remappedStack : stack;
+    }
+    catch {
+        return stack;
+    }
+}
+function isCrossRealmError(e) {
+    return typeof e === 'object' && e !== null && Object.prototype.toString.call(e) === '[object Error]';
+}
+function stringifyThrownValue(e) {
+    if (isCrossRealmError(e)) {
+        return typeof e.message === 'string' ? e.message : Object.prototype.toString.call(e);
+    }
+    if (typeof e === 'object' && e !== null) {
+        try {
+            // JSON.stringify can return undefined without throwing, for example when toJSON returns undefined.
+            return JSON.stringify(e) ?? Object.prototype.toString.call(e);
+        }
+        catch {
+            return Object.prototype.toString.call(e);
+        }
+    }
+    return String(e);
+}
+export function convertToError(e) {
+    if (e instanceof Error) {
+        return e;
+    }
+    const message = stringifyThrownValue(e);
+    // tsconfig uses es2020 libs, which do not type Error.cause even though supported runtimes provide it.
+    const error = new Error(message);
+    error.cause = e;
+    if (isCrossRealmError(e) && typeof e.stack === 'string') {
+        // Prefer the cross-realm bundle stack over the host wrapping call site; the
+        // original thrown value remains available through `cause`.
+        error.stack = remapSourceMappedStack(e.stack);
+    }
+    return error;
+}
+//# sourceMappingURL=errorUtils.js.map

package/lib/rootErrorHandlers.js

@@ -1,6 +1,7 @@
 import { supportsRootApi, supportsReact19RootErrorCallbacks } from "./reactApis.cjs";
 import { getRailsContext } from "./context.js";
 import { isThenable } from "./isThenable.js";
+import captureReactOwnerStack, { isOwnerStackSupported } from "./captureReactOwnerStack.js";
 /**
  * Guide linked from the development-mode hydration-mismatch message.
  * TODO(#3894): swap to the stable error-reference URL once error codes and reference pages land.
@@ -143,18 +144,61 @@ function extractComponentStack(errorInfo) {
     const componentStack = errorInfo?.componentStack;
     return typeof componentStack === 'string' && componentStack.length > 0 ? componentStack : undefined;
 }
+/**
+ * React 19.2+ includes the owner stack on the `errorInfo` passed to `onCaughtError`/`onUncaughtError`
+ * (and to `onRecoverableError` for hydration mismatches) via `errorInfo.ownerStack`. Prefer it when
+ * present; callers fall back to a live `captureReactOwnerStack()` call for React 19.1, which exposes
+ * the API but not the `errorInfo` field.
+ */
+function extractOwnerStack(errorInfo) {
+    const ownerStack = errorInfo?.ownerStack;
+    return typeof ownerStack === 'string' && ownerStack.trim().length > 0 ? ownerStack : undefined;
+}
+/**
+ * Builds the supplemental "Owner stack" suffix for dev-mode error logs (issue #3887).
+ *
+ * MUST be called synchronously from inside React's error callback. `precomputedOwnerStack` is the
+ * owner stack React already captured for this error (e.g. `errorInfo.ownerStack` on React 19.2+),
+ * when available; otherwise we fall back to a live `captureReactOwnerStack()` call, which only
+ * returns a value while React is still handling the error. Returns an empty string when no owner
+ * stack is available — in particular on React < 19.1 and in production builds, where
+ * `captureReactOwnerStack` is a strict no-op.
+ */
+function ownerStackSuffix(precomputedOwnerStack) {
+    const ownerStack = (typeof precomputedOwnerStack === 'string' && precomputedOwnerStack.trim().length > 0
+        ? precomputedOwnerStack
+        : undefined) ?? captureReactOwnerStack();
+    return ownerStack ? `\nOwner stack (the components that rendered this one):${ownerStack}` : '';
+}
 /**
  * Branded, supplemental development-mode line: component name, dom id, component stack (when
- * React provides one), and the debugging-guide link. Deliberately does NOT dump the error object
- * itself — the error is default-reported exactly once elsewhere (by `defaultReportRecoverableError`
- * on core paths, or by Pro's internal recoverable-error handler on chained paths).
+ * React provides one), the owner stack (React >= 19.1 dev builds, issue #3887), and the
+ * debugging-guide link. Deliberately does NOT dump the error object itself — the error is
+ * default-reported exactly once elsewhere (by `defaultReportRecoverableError` on core paths, or by
+ * Pro's internal recoverable-error handler on chained paths).
  */
 function logDevHydrationError(context, errorInfo) {
     const componentName = context.componentName ?? 'unknown';
     const domNodeId = context.domNodeId ?? 'unknown';
     const componentStack = extractComponentStack(errorInfo);
     const componentStackSuffix = componentStack ? `\nComponent stack:${componentStack}` : '';
-    console.error(`[ReactOnRails] Recoverable hydration error in component "${componentName}" (dom id: "${domNodeId}"). The server-rendered HTML did not match what React rendered on the client, so React threw away the server HTML and re-rendered on the client. Common Rails-specific causes and fixes: ${HYDRATION_MISMATCH_GUIDE_URL}${componentStackSuffix}`);
+    console.error(`[ReactOnRails] Recoverable hydration error in component "${componentName}" (dom id: "${domNodeId}"). The server-rendered HTML did not match what React rendered on the client, so React threw away the server HTML and re-rendered on the client. Common Rails-specific causes and fixes: ${HYDRATION_MISMATCH_GUIDE_URL}${componentStackSuffix}${ownerStackSuffix(extractOwnerStack(errorInfo))}`);
+}
+/**
+ * Development-only supplemental line for render-path errors React reports through an app-registered
+ * `onCaughtError`/`onUncaughtError` handler (issue #3887). Names the failing component/dom id and
+ * appends the owner stack when React provides one. The error itself is reported by the app's own
+ * handler (which we forward to), so this line is purely additive context.
+ */
+function logDevRenderError(kind, context, errorInfo) {
+    const suffix = ownerStackSuffix(extractOwnerStack(errorInfo));
+    if (!suffix) {
+        return;
+    }
+    const componentName = context.componentName ?? 'unknown';
+    const domNodeId = context.domNodeId ?? 'unknown';
+    const caughtNote = kind === 'onCaughtError' ? ' (caught by an error boundary)' : '';
+    console.error(`[ReactOnRails] Render error in component "${componentName}" (dom id: "${domNodeId}")${caughtNote}.${suffix}`);
 }
 /**
  * Builds the `hydrateRoot`/`createRoot` error callback options for one React root, wrapping the
@@ -197,11 +241,33 @@ export function buildRootErrorCallbackOptions(context, hydrating, { defaultRepor
         };
     }
     if (supportsReact19RootErrorCallbacks) {
+        // Owner-stack enrichment for client render errors (issue #3887). We only enrich when the app has
+        // registered its own onCaughtError/onUncaughtError handler: providing one already replaces
+        // React's default reporting for that callback, so prepending our supplemental dev owner-stack
+        // line is purely additive. We deliberately do NOT auto-attach a wrapper when the app registered
+        // no handler — that would displace React's built-in dev diagnostics (component stack,
+        // error-boundary hints) that we cannot faithfully reproduce, a net loss. Owner stacks still reach
+        // users automatically on the two paths React on Rails already owns: SSR errors (the Pro streaming
+        // onError path) and hydration mismatches (the onRecoverableError path above).
+        //
+        // The owner-stack line is only emitted on React >= 19.1 dev builds (`isOwnerStackSupported()`);
+        // otherwise the wrapper just forwards to the app handler unchanged.
+        const enrichDevOwnerStack = inDevelopmentEnv() && isOwnerStackSupported();
         if (onCaughtError) {
-            options.onCaughtError = (error, errorInfo) => safeInvoke(onCaughtError, 'onCaughtError', error, errorInfo, context);
+            options.onCaughtError = (error, errorInfo) => {
+                if (enrichDevOwnerStack) {
+                    logDevRenderError('onCaughtError', context, errorInfo);
+                }
+                safeInvoke(onCaughtError, 'onCaughtError', error, errorInfo, context);
+            };
         }
         if (onUncaughtError) {
-            options.onUncaughtError = (error, errorInfo) => safeInvoke(onUncaughtError, 'onUncaughtError', error, errorInfo, context);
+            options.onUncaughtError = (error, errorInfo) => {
+                if (enrichDevOwnerStack) {
+                    logDevRenderError('onUncaughtError', context, errorInfo);
+                }
+                safeInvoke(onUncaughtError, 'onUncaughtError', error, errorInfo, context);
+            };
         }
     }
     return options;

package/lib/serverRenderUtils.d.ts

@@ -1,4 +1,5 @@
 import type { RegisteredComponent, RegisteredComponentValue, RenderingError, FinalHtmlResult } from './types/index.ts';
+export { convertToError } from './errorUtils.ts';
 /**
  * Builds the metadata object for the length-prefixed streaming protocol.
  * This is the shared metadata builder used by both streaming and non-streaming paths.
@@ -19,7 +20,5 @@ export declare function buildRenderMetadata(consoleReplayScript: string, renderS
  * buildRenderMetadata directly with Buffer operations for efficiency.
  */
 export declare function buildLengthPrefixedResult(html: FinalHtmlResult | null, consoleReplayScript: string, renderState: RenderMetadataSource): string;
-export declare function convertToError(e: unknown): Error;
 export declare function validateComponent(componentObj: RegisteredComponent<RegisteredComponentValue>, componentName: string): void;
-export {};
 //# sourceMappingURL=serverRenderUtils.d.ts.map

package/lib/serverRenderUtils.js

@@ -1,19 +1,5 @@
-// Must match SOURCE_MAP_STACK_REMAPPER_CONTEXT_KEY in
-// packages/react-on-rails-pro-node-renderer/src/worker/vmSourceMapSupport.ts.
-const SOURCE_MAPPED_STACK_REMAPPER_KEY = '__reactOnRailsProRemapStackTrace';
-function remapSourceMappedStack(stack) {
-    const remapper = globalThis[SOURCE_MAPPED_STACK_REMAPPER_KEY];
-    if (typeof remapper !== 'function') {
-        return stack;
-    }
-    try {
-        const remappedStack = remapper(stack);
-        return typeof remappedStack === 'string' ? remappedStack : stack;
-    }
-    catch {
-        return stack;
-    }
-}
+import { remapSourceMappedStack } from "./errorUtils.js";
+export { convertToError } from "./errorUtils.js";
 export function buildRenderMetadata(consoleReplayScript, renderState) {
     return {
         consoleReplayScript,
@@ -26,24 +12,6 @@ export function buildRenderMetadata(consoleReplayScript, renderState) {
         isShellReady: 'isShellReady' in renderState ? renderState.isShellReady : undefined,
     };
 }
-function isCrossRealmError(e) {
-    return typeof e === 'object' && e !== null && Object.prototype.toString.call(e) === '[object Error]';
-}
-function stringifyThrownValue(e) {
-    if (isCrossRealmError(e)) {
-        return typeof e.message === 'string' ? e.message : Object.prototype.toString.call(e);
-    }
-    if (typeof e === 'object' && e !== null) {
-        try {
-            // JSON.stringify can return undefined without throwing, for example when toJSON returns undefined.
-            return JSON.stringify(e) ?? Object.prototype.toString.call(e);
-        }
-        catch {
-            return Object.prototype.toString.call(e);
-        }
-    }
-    return String(e);
-}
 /**
  * Returns the UTF-8 byte length of a string.
  * Uses native Buffer.byteLength when available (Node.js, Pro node renderer).
@@ -105,21 +73,6 @@ export function buildLengthPrefixedResult(html, consoleReplayScript, renderState
     const byteLength = utf8ByteLength(htmlStr);
     return `${metadata}\t${byteLength.toString(16).padStart(8, '0')}\n${htmlStr}`;
 }
-export function convertToError(e) {
-    if (e instanceof Error) {
-        return e;
-    }
-    const message = stringifyThrownValue(e);
-    // tsconfig uses es2020 libs, which do not type Error.cause even though supported runtimes provide it.
-    const error = new Error(message);
-    error.cause = e;
-    if (isCrossRealmError(e) && typeof e.stack === 'string') {
-        // Prefer the cross-realm bundle stack over the host wrapping call site; the
-        // original thrown value remains available through `cause`.
-        error.stack = remapSourceMappedStack(e.stack);
-    }
-    return error;
-}
 export function validateComponent(componentObj, componentName) {
     if (componentObj.isRenderer) {
         throw new Error(`Detected a renderer while server rendering component '${componentName}'. See https://github.com/shakacode/react_on_rails#renderer-functions`);

package/lib/types/index.d.ts

@@ -48,6 +48,7 @@ export type RailsContextWithServerComponentMetadata = RailsContext & {
 export type RailsContextWithServerStreamingCapabilities = RailsContextWithServerComponentMetadata & {
     getRSCPayloadStream: (componentName: string, props: unknown) => Promise<NodeJS.ReadableStream>;
     addPostSSRHook: (hook: () => void) => void;
+    recordRSCDiagnostic?: (componentName: string, diagnosticError: Error) => void;
 };
 export declare const assertRailsContextWithServerComponentMetadata: (context: RailsContext | undefined) => asserts context is RailsContextWithServerComponentMetadata;
 export declare const assertRailsContextWithServerStreamingCapabilities: (context: RailsContext | undefined) => asserts context is RailsContextWithServerStreamingCapabilities;
@@ -169,23 +170,32 @@ type AsyncPropsManager = {
  * anotherRenderFunction.renderFunction = true;
  *
  * @remarks
- * The 3-argument "renderer" form `(props, railsContext, domNodeId)` owns its own DOM
- * rendering/hydration. Use {@link RendererFunction} for renderers that return nothing or an optional
- * `{ teardown }` wrapper for cleanup. `RenderFunction` still accepts legacy 3-argument renderers
- * that returned a component/server result only to satisfy the old type; React on Rails ignores those
- * return values on the client renderer path.
+ * `RenderFunction` is exactly this 2-argument server/client render-function form. The 3-argument
+ * "renderer" form `(props, railsContext, domNodeId)` owns its own DOM rendering/hydration and is a
+ * distinct role: type those functions {@link RendererFunction} (they return nothing or an optional
+ * `{ teardown }` wrapper for cleanup). For `RenderFunction`, this makes the illegal combination —
+ * a server render-function "returning" a teardown — unrepresentable instead of merely discouraged.
+ * (`RendererFunction` still accepts legacy {@link RenderFunctionResult} return shapes for backward
+ * compatibility with old 3-argument renderers; those values are ignored at runtime.)
+ *
+ * The doc block above describes {@link RenderFunction}, the public alias for this interface. Prefer
+ * `RenderFunction` in public-facing annotations; `ServerRenderFunction` is the concrete interface
+ * behind it (exported mainly so call sites can narrow to the precise role after runtime guards).
  */
 interface ServerRenderFunction extends RenderFunctionMarker {
     (props?: any, railsContext?: RailsContext): RenderFunctionResult;
 }
-interface LegacyRendererRenderFunction extends RenderFunctionMarker {
-    (props?: any, railsContext?: RailsContext, domNodeId?: string): RenderFunctionResult;
-}
-type RenderFunction = ServerRenderFunction | LegacyRendererRenderFunction;
+/**
+ * The public name for the 2-argument server/client render-function form
+ * `(props, railsContext) => RenderFunctionResult`. Alias of {@link ServerRenderFunction}; prefer
+ * `RenderFunction` in public-facing annotations. See {@link ServerRenderFunction} for the full
+ * render-function vs. renderer role explanation.
+ */
+type RenderFunction = ServerRenderFunction;
 type ReactComponentOrRenderFunction = ReactComponent | RenderFunction | RendererFunction;
 type RegisteredComponentValue = ReactComponentOrRenderFunction | Record<string, unknown>;
 type PipeableOrReadableStream = PipeableStream | NodeJS.ReadableStream;
-export type { ReactComponentOrRenderFunction, RegisteredComponentValue, ReactComponent, ReactComponentRenderFunction, AuthenticityHeaders, RenderFunction, RendererTeardown, RendererTeardownResult, RendererFunction, RenderFunctionResult, Store, StoreGenerator, CreateReactOutputResult, ServerRenderResult, ServerRenderHashRenderedHtml, CreateReactOutputSyncResult, CreateReactOutputAsyncResult, RenderFunctionSyncResult, RenderFunctionAsyncResult, ReactComponentRenderFunctionResult, StreamableComponentResult, PipeableOrReadableStream, };
+export type { ReactComponentOrRenderFunction, RegisteredComponentValue, ReactComponent, ReactComponentRenderFunction, AuthenticityHeaders, RenderFunction, ServerRenderFunction, RendererTeardown, RendererTeardownResult, RendererFunction, RenderFunctionResult, RendererFunctionResult, Store, StoreGenerator, CreateReactOutputResult, ServerRenderResult, ServerRenderHashRenderedHtml, CreateReactOutputSyncResult, CreateReactOutputAsyncResult, RenderFunctionSyncResult, RenderFunctionAsyncResult, ReactComponentRenderFunctionResult, StreamableComponentResult, PipeableOrReadableStream, };
 /**
  * The generic defaults to the pre-object-registration component type so existing consumers that
  * read `registeredComponent.component` stay source-compatible. Use

package/lib/types/index.js

@@ -16,7 +16,19 @@ export const assertRailsContextWithServerComponentMetadata = (context) => {
 };
 export const assertRailsContextWithServerStreamingCapabilities = (context) => {
     assertRailsContextWithServerComponentMetadata(context);
-    if (!('getRSCPayloadStream' in context) || !('addPostSSRHook' in context)) {
+    // Verify the capabilities are callable, not merely present, so a misconfigured context fails here
+    // with the intended diagnostic instead of crashing later at a call site.
+    //
+    // `recordRSCDiagnostic` is intentionally NOT required here. It is an additive field (#3475); an
+    // external consumer constructing this context against an older Pro version may not supply it.
+    // Hard-throwing on its absence would be a compat regression for those consumers even though their
+    // type-check passes (the field is optional). Callers degrade gracefully when it is missing, so the
+    // assertion only guards the two pre-existing required capabilities.
+    // Cast to a Partial of the target type (rather than Record<string, unknown>) so the known
+    // capability keys stay typed while we runtime-check that each is actually a function.
+    const capabilities = context;
+    if (typeof capabilities.getRSCPayloadStream !== 'function' ||
+        typeof capabilities.addPostSSRHook !== 'function') {
         throwRailsContextMissingEntries('getRSCPayloadStream and addPostSSRHook functions');
     }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-on-rails",
-  "version": "17.0.0-rc.5",
+  "version": "17.0.0-rc.6",
   "description": "react-on-rails JavaScript for react_on_rails Ruby gem",
   "main": "lib/ReactOnRails.full.js",
   "type": "module",
@@ -39,6 +39,7 @@
     "./ReactOnRails.full": "./lib/ReactOnRails.full.js",
     "./handleError": "./lib/handleError.js",
     "./generateRenderingErrorMessage": "./lib/generateRenderingErrorMessage.js",
+    "./captureReactOwnerStack": "./lib/captureReactOwnerStack.js",
     "./serverRenderUtils": "./lib/serverRenderUtils.js",
     "./buildConsoleReplay": "./lib/buildConsoleReplay.js",
     "./ReactDOMServer": "./lib/ReactDOMServer.cjs",