react-on-rails 17.0.0-rc.3 → 17.0.0-rc.4

package/lib/ClientRenderer.js

@@ -7,13 +7,9 @@ import { isServerRenderHash } from "./isServerRenderResult.js";
 import { onPageUnloaded } from "./pageLifecycle.js";
 import { supportsRootApi, unmountComponentAtNode } from "./reactApis.cjs";
 import { isRendererTeardownResult } from "./rendererTeardown.js";
+import { buildRootErrorCallbackOptions } from "./rootErrorHandlers.js";
+import { isThenable } from "./isThenable.js";
 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) {
-    return (value != null &&
-        (typeof value === 'object' || typeof value === 'function') &&
-        typeof value.then === 'function');
-}
 // Track all rendered roots for cleanup
 const renderedRoots = new Map();
 /**
@@ -229,7 +225,10 @@ You returned a server side type of react-router error: ${JSON.stringify(reactEle
 You should return a React.Component always for the client side entry point.`);
             }
             else {
-                const root = reactHydrateOrRender(domNode, reactElementOrRouterResult, shouldHydrate);
+                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 });
             }

package/lib/base/client.js

@@ -7,6 +7,7 @@ import buildConsoleReplay, { consoleReplay } from "../buildConsoleReplay.js";
 import reactHydrateOrRender from "../reactHydrateOrRender.js";
 import createReactOutput from "../createReactOutput.js";
 import componentRegistrationMetric from "../componentRegistrationMetric.js";
+import { buildRootErrorCallbackOptions, getRootErrorHandlers, resetRootErrorHandlers, setRootErrorHandlers, } from "../rootErrorHandlers.js";
 const DEFAULT_OPTIONS = {
     traceTurbolinks: false,
     turbo: false,
@@ -73,37 +74,46 @@ Fix: Use only react-on-rails OR react-on-rails-pro, not both.`);
             return Authenticity.authenticityHeaders(otherHeaders);
         },
         reactHydrateOrRender(domNode, reactElement, hydrate) {
-            return reactHydrateOrRender(domNode, reactElement, hydrate);
+            // The component name is unknown on this low-level path; the dom id still ties errors to a mount.
+            const rootErrorCallbackOptions = buildRootErrorCallbackOptions({ domNodeId: domNode.id || undefined }, hydrate);
+            return reactHydrateOrRender(domNode, reactElement, hydrate, rootErrorCallbackOptions);
         },
         setOptions(newOptions) {
-            if (typeof newOptions.traceTurbolinks !== 'undefined') {
-                this.options.traceTurbolinks = newOptions.traceTurbolinks;
-                // eslint-disable-next-line no-param-reassign
-                delete newOptions.traceTurbolinks;
+            const { traceTurbolinks, turbo, debugMode, logComponentRegistration, rootErrorHandlers, ...rest } = newOptions;
+            if (typeof traceTurbolinks !== 'undefined') {
+                this.options.traceTurbolinks = traceTurbolinks;
             }
-            if (typeof newOptions.turbo !== 'undefined') {
-                this.options.turbo = newOptions.turbo;
-                // eslint-disable-next-line no-param-reassign
-                delete newOptions.turbo;
+            if (typeof turbo !== 'undefined') {
+                this.options.turbo = turbo;
             }
-            if (typeof newOptions.debugMode !== 'undefined') {
-                this.options.debugMode = newOptions.debugMode;
-                if (newOptions.debugMode) {
+            if (typeof debugMode !== 'undefined') {
+                this.options.debugMode = debugMode;
+                if (debugMode) {
                     console.log('[ReactOnRails] Debug mode enabled');
                 }
-                // eslint-disable-next-line no-param-reassign
-                delete newOptions.debugMode;
             }
-            if (typeof newOptions.logComponentRegistration !== 'undefined') {
-                this.options.logComponentRegistration = newOptions.logComponentRegistration;
-                if (newOptions.logComponentRegistration) {
+            if (typeof logComponentRegistration !== 'undefined') {
+                this.options.logComponentRegistration = logComponentRegistration;
+                if (logComponentRegistration) {
                     console.log('[ReactOnRails] Component registration logging enabled');
                 }
-                // eslint-disable-next-line no-param-reassign
-                delete newOptions.logComponentRegistration;
             }
-            if (Object.keys(newOptions).length > 0) {
-                throw new Error(`Invalid options passed to ReactOnRails.options: ${JSON.stringify(newOptions)}`);
+            if (Object.prototype.hasOwnProperty.call(newOptions, 'rootErrorHandlers')) {
+                // MUST SYNC: sibling implementation exists in packages/react-on-rails/src/capabilities/core.ts.
+                // 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.
+                if (typeof rootErrorHandlers === 'undefined') {
+                    resetRootErrorHandlers();
+                    this.options.rootErrorHandlers = undefined;
+                }
+                else {
+                    setRootErrorHandlers(rootErrorHandlers);
+                    this.options.rootErrorHandlers = getRootErrorHandlers();
+                }
+            }
+            if (Object.keys(rest).length > 0) {
+                throw new Error(`Invalid options passed to ReactOnRails.options: ${JSON.stringify(rest)}`);
             }
         },
         option(key) {
@@ -117,6 +127,7 @@ Fix: Use only react-on-rails OR react-on-rails-pro, not both.`);
         },
         resetOptions() {
             this.options = { ...DEFAULT_OPTIONS };
+            resetRootErrorHandlers();
         },
         // ===================================================================
         // REGISTRY METHOD IMPLEMENTATIONS - Using provided registries
@@ -181,7 +192,7 @@ Fix: Use only react-on-rails OR react-on-rails-pro, not both.`);
         render(name, props, domNodeId, hydrate) {
             const componentObj = ComponentRegistry.get(name);
             const reactElement = createReactOutput({ componentObj, props, domNodeId });
-            return this.reactHydrateOrRender(document.getElementById(domNodeId), reactElement, hydrate);
+            return reactHydrateOrRender(document.getElementById(domNodeId), reactElement, hydrate, buildRootErrorCallbackOptions({ componentName: name || undefined, domNodeId: domNodeId || undefined }, hydrate));
         },
         // ===================================================================
         // CLIENT-SIDE RENDERING STUBS - To be overridden by createReactOnRails

package/lib/capabilities/core.js

@@ -3,6 +3,7 @@ import buildConsoleReplay, { consoleReplay } from "../buildConsoleReplay.js";
 import reactHydrateOrRender from "../reactHydrateOrRender.js";
 import createReactOutput from "../createReactOutput.js";
 import componentRegistrationMetric from "../componentRegistrationMetric.js";
+import { buildRootErrorCallbackOptions, getRootErrorHandlers, resetRootErrorHandlers, setRootErrorHandlers, } from "../rootErrorHandlers.js";
 const DEFAULT_OPTIONS = {
     traceTurbolinks: false,
     turbo: false,
@@ -28,10 +29,12 @@ export function createCoreCapability(registries) {
             return Authenticity.authenticityHeaders(otherHeaders);
         },
         reactHydrateOrRender(domNode, reactElement, hydrate) {
-            return reactHydrateOrRender(domNode, reactElement, hydrate);
+            // The component name is unknown on this low-level path; the dom id still ties errors to a mount.
+            const rootErrorCallbackOptions = buildRootErrorCallbackOptions({ domNodeId: domNode.id || undefined }, hydrate);
+            return reactHydrateOrRender(domNode, reactElement, hydrate, rootErrorCallbackOptions);
         },
         setOptions(newOptions) {
-            const { traceTurbolinks, turbo, debugMode, logComponentRegistration, ...rest } = newOptions;
+            const { traceTurbolinks, turbo, debugMode, logComponentRegistration, rootErrorHandlers, ...rest } = newOptions;
             if (typeof traceTurbolinks !== 'undefined') {
                 this.options.traceTurbolinks = traceTurbolinks;
             }
@@ -50,6 +53,20 @@ export function createCoreCapability(registries) {
                     console.log('[ReactOnRails] Component registration logging enabled');
                 }
             }
+            if (Object.prototype.hasOwnProperty.call(newOptions, 'rootErrorHandlers')) {
+                // MUST SYNC: sibling implementation exists in packages/react-on-rails/src/base/client.ts.
+                // 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.
+                if (typeof rootErrorHandlers === 'undefined') {
+                    resetRootErrorHandlers();
+                    this.options.rootErrorHandlers = undefined;
+                }
+                else {
+                    setRootErrorHandlers(rootErrorHandlers);
+                    this.options.rootErrorHandlers = getRootErrorHandlers();
+                }
+            }
             if (Object.keys(rest).length > 0) {
                 throw new Error(`Invalid options passed to ReactOnRails.options: ${JSON.stringify(rest)}`);
             }
@@ -65,6 +82,7 @@ export function createCoreCapability(registries) {
         },
         resetOptions() {
             this.options = { ...DEFAULT_OPTIONS };
+            resetRootErrorHandlers();
         },
         // ===================================================================
         // REGISTRY METHOD IMPLEMENTATIONS - Using provided registries
@@ -129,7 +147,7 @@ export function createCoreCapability(registries) {
         render(name, props, domNodeId, hydrate) {
             const componentObj = ComponentRegistry.get(name);
             const reactElement = createReactOutput({ componentObj, props, domNodeId });
-            return this.reactHydrateOrRender(document.getElementById(domNodeId), reactElement, hydrate);
+            return reactHydrateOrRender(document.getElementById(domNodeId), reactElement, hydrate, buildRootErrorCallbackOptions({ componentName: name || undefined, domNodeId: domNodeId || undefined }, hydrate));
         },
         // ===================================================================
         // SSR STUBS — overridden by createSSRCapability() in full/node bundles

package/lib/isThenable.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Narrows an unknown value to a thenable (has a callable `.then`) without assuming a native
+ * Promise. Shared by the core ClientRenderer, rootErrorHandlers, and the Pro ClientSideRenderer
+ * (via `react-on-rails/@internal/isThenable`) so non-native thenables are handled identically
+ * everywhere.
+ */
+export declare function isThenable(value: unknown): value is PromiseLike<unknown>;
+//# sourceMappingURL=isThenable.d.ts.map

package/lib/isThenable.js

@@ -0,0 +1,13 @@
+/* eslint-disable import/prefer-default-export -- named export for grep-ability and consistency with other @internal helpers */
+/**
+ * Narrows an unknown value to a thenable (has a callable `.then`) without assuming a native
+ * Promise. Shared by the core ClientRenderer, rootErrorHandlers, and the Pro ClientSideRenderer
+ * (via `react-on-rails/@internal/isThenable`) so non-native thenables are handled identically
+ * everywhere.
+ */
+export function isThenable(value) {
+    return (value != null &&
+        (typeof value === 'object' || typeof value === 'function') &&
+        typeof value.then === 'function');
+}
+//# sourceMappingURL=isThenable.js.map

package/lib/reactApis.cjs

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ensureReactUseAvailable = exports.unmountComponentAtNode = exports.reactHydrate = exports.supportsHydrate = exports.supportsRootApi = void 0;
+exports.ensureReactUseAvailable = exports.unmountComponentAtNode = exports.reactHydrate = exports.supportsReact19RootErrorCallbacks = exports.supportsHydrate = exports.supportsRootApi = void 0;
 exports.reactRender = reactRender;
 /* eslint-disable global-require,@typescript-eslint/no-require-imports */
 const React = require("react");
@@ -9,6 +9,9 @@ const reactMajorVersion = Number(ReactDOM.version?.split('.')[0]) || 16;
 // TODO: once we require React 18, we can remove this and inline everything guarded by it.
 exports.supportsRootApi = reactMajorVersion >= 18;
 exports.supportsHydrate = exports.supportsRootApi || 'hydrate' in ReactDOM;
+// React 19 added the `onCaughtError`/`onUncaughtError` root options. React 18's root API only
+// supports `identifierPrefix` and `onRecoverableError`.
+exports.supportsReact19RootErrorCallbacks = reactMajorVersion >= 19;
 // TODO: once React dependency is updated to >= 18, we can remove this and just
 // import ReactDOM from 'react-dom/client';
 let reactDomClient;

package/lib/reactApis.d.cts

@@ -2,6 +2,7 @@ import type { ReactElement } from 'react';
 import type { RenderReturnType } from './types/index.ts' with { 'resolution-mode': 'import' };
 export declare const supportsRootApi: boolean;
 export declare const supportsHydrate: boolean;
+export declare const supportsReact19RootErrorCallbacks: boolean;
 export type ReactHydrateOptions = {
     identifierPrefix?: string;
     onCaughtError?: (error: unknown, errorInfo: unknown) => void;

package/lib/rootErrorHandlers.d.ts

@@ -0,0 +1,82 @@
+import type { RootErrorContext, RootErrorHandlers } from './types/index.ts';
+import type { ReactHydrateOptions } from './reactApis.cts';
+/**
+ * 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.
+ * @internal
+ */
+export declare const HYDRATION_MISMATCH_GUIDE_URL = "https://reactonrails.com/docs/building-features/debugging-hydration-mismatches";
+/**
+ * Validates and stores the user's root error callbacks. Called by `ReactOnRails.setOptions`.
+ *
+ * Updates MERGE per key (matching how the other `setOptions` keys update independently): passing
+ * only `onCaughtError` keeps a previously registered `onRecoverableError`/`onUncaughtError`.
+ * Passing an explicit `undefined` for a key clears that key; `resetRootErrorHandlers` (via
+ * `ReactOnRails.resetOptions`) clears all of them. Combined with the capture-at-root-creation
+ * semantics in `buildRootErrorCallbackOptions`, changes only affect roots created afterwards.
+ *
+ * On React runtimes without root error callback support this still stores the handlers (so a
+ * later React upgrade picks them up) but warns that they will never be called.
+ */
+export declare function setRootErrorHandlers(handlers: RootErrorHandlers): void;
+/** Clears the registered root error callbacks. Called by `ReactOnRails.resetOptions`. */
+export declare function resetRootErrorHandlers(): void;
+/**
+ * Returns a snapshot copy of the currently registered root error callbacks. A copy is returned so
+ * callers cannot mutate the internal registration and bypass `setRootErrorHandlers` validation.
+ */
+export declare function getRootErrorHandlers(): RootErrorHandlers;
+/**
+ * Mirrors React's own default `onRecoverableError` (`reportError` where available, else
+ * `console.error`). Attaching a root callback replaces React's default reporting, so the
+ * dev-mode logger must re-emit it itself — otherwise window-'error'-based tooling (dev overlays,
+ * error trackers) goes silent in development.
+ */
+export declare function defaultReportRecoverableError(error: unknown): void;
+type RootErrorCallbackOptions = Pick<ReactHydrateOptions, 'onRecoverableError' | 'onCaughtError' | 'onUncaughtError'>;
+/** @internal Used by Pro via the `@internal/rootErrorHandlers` alias; not part of the public API. */
+export interface BuildRootErrorCallbackOptionsExtras {
+    /**
+     * Set by Pro callers that chain their own default reporting around the returned
+     * `onRecoverableError` via `chainRecoverableErrorHandlers` (see
+     * `handleRecoverableError.client.ts`). When true, the dev-mode logger emits only its branded
+     * supplemental line and skips `defaultReportRecoverableError`, so each recoverable error is
+     * default-reported exactly once.
+     *
+     * New Pro hydrate paths that call `chainRecoverableErrorHandlers` should use
+     * `buildRootErrorCallbackOptionsWithInternalRecoverableErrorReporting` instead of setting this
+     * low-level flag directly; omitting it causes double-reporting in development.
+     */
+    defaultReportingHandledInternally?: boolean;
+}
+/**
+ * Builds the `hydrateRoot`/`createRoot` error callback options for one React root, wrapping the
+ * user's registered handlers so they also receive `context` (component name and dom id).
+ *
+ * The handlers registered at root-creation time are CAPTURED into the returned wrappers (not
+ * re-read on every error): attaching a root callback permanently replaces React's default
+ * reporting for that callback on that root, so a wrapper that later re-read cleared handlers
+ * would silently swallow errors. Roots therefore keep the handlers they were created with;
+ * re-registering affects only roots created afterwards.
+ *
+ * When hydrating in Rails development mode, a React on Rails-branded hydration-mismatch line
+ * (component name, dom id, component stack, guide link) is attached in addition to (and before)
+ * any user `onRecoverableError`. React's default reporting is preserved: the error itself is
+ * still default-reported once — via `defaultReportRecoverableError` here, or by the caller's own
+ * reporting when `defaultReportingHandledInternally` is set.
+ *
+ * Returns `{}` when nothing needs to be attached so React's default error reporting stays
+ * untouched, and on React <18 (the legacy `hydrate`/`render` APIs have no such options).
+ */
+export declare function buildRootErrorCallbackOptions(context: RootErrorContext, hydrating: boolean, { defaultReportingHandledInternally }?: BuildRootErrorCallbackOptionsExtras): RootErrorCallbackOptions;
+/**
+ * Pro RSC hydration wraps the returned `onRecoverableError` with an internal handler that has already
+ * performed React's default recoverable-error reporting. Keep that invariant in one named helper so
+ * Pro call sites do not need to remember the lower-level `defaultReportingHandledInternally` flag.
+ *
+ * On non-hydrate (`createRoot`) paths, `defaultReportingHandledInternally` is false, so this
+ * degrades to `buildRootErrorCallbackOptions` with no reporting-behavior change.
+ */
+export declare function buildRootErrorCallbackOptionsWithInternalRecoverableErrorReporting(context: RootErrorContext, hydrating: boolean): RootErrorCallbackOptions;
+export {};
+//# sourceMappingURL=rootErrorHandlers.d.ts.map

package/lib/rootErrorHandlers.js

@@ -0,0 +1,222 @@
+import { supportsRootApi, supportsReact19RootErrorCallbacks } from "./reactApis.cjs";
+import { getRailsContext } from "./context.js";
+import { isThenable } from "./isThenable.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.
+ * @internal
+ */
+export const HYDRATION_MISMATCH_GUIDE_URL = 'https://reactonrails.com/docs/building-features/debugging-hydration-mismatches';
+const HANDLER_KEYS = [
+    'onRecoverableError',
+    'onCaughtError',
+    'onUncaughtError',
+];
+const REACT_19_ONLY_HANDLER_KEYS = [
+    'onCaughtError',
+    'onUncaughtError',
+];
+// Registered through `ReactOnRails.setOptions({ rootErrorHandlers })`; module-level so both the
+// core ClientRenderer and the Pro ClientSideRenderer (which imports this module from the same
+// `react-on-rails` package instance) read the same registration.
+let registeredHandlers = {};
+let warnedMissingRootApi = false;
+// One-shot per reset cycle: the warning body names all React-19-only keys so split
+// registrations in the same cycle do not need repeated warnings.
+let warnedMissingReact19Callbacks = false;
+/**
+ * Validates and stores the user's root error callbacks. Called by `ReactOnRails.setOptions`.
+ *
+ * Updates MERGE per key (matching how the other `setOptions` keys update independently): passing
+ * only `onCaughtError` keeps a previously registered `onRecoverableError`/`onUncaughtError`.
+ * Passing an explicit `undefined` for a key clears that key; `resetRootErrorHandlers` (via
+ * `ReactOnRails.resetOptions`) clears all of them. Combined with the capture-at-root-creation
+ * semantics in `buildRootErrorCallbackOptions`, changes only affect roots created afterwards.
+ *
+ * On React runtimes without root error callback support this still stores the handlers (so a
+ * later React upgrade picks them up) but warns that they will never be called.
+ */
+export function setRootErrorHandlers(handlers) {
+    if (handlers == null) {
+        throw new Error(`Invalid ReactOnRails rootErrorHandlers option: expected an object, got ${handlers}. ` +
+            'Use undefined (or omit the key) to clear all handlers.');
+    }
+    const unknownKeys = Object.keys(handlers).filter((key) => !HANDLER_KEYS.includes(key));
+    if (unknownKeys.length > 0) {
+        throw new Error(`Invalid ReactOnRails rootErrorHandlers option: unknown key(s) ${unknownKeys.join(', ')}. ` +
+            `Valid keys are: ${HANDLER_KEYS.join(', ')}.`);
+    }
+    HANDLER_KEYS.forEach((key) => {
+        const value = handlers[key];
+        if (typeof value !== 'undefined' && typeof value !== 'function') {
+            throw new Error(`Invalid ReactOnRails rootErrorHandlers option: ${key} must be a function, got ${value === null ? 'null' : typeof value}.`);
+        }
+    });
+    const providedKeys = HANDLER_KEYS.filter((key) => typeof handlers[key] === 'function');
+    if (providedKeys.length > 0 && !supportsRootApi) {
+        if (!warnedMissingRootApi) {
+            console.warn(`[ReactOnRails] rootErrorHandlers (${providedKeys.join(', ')}) require the React 18+ root APIs ` +
+                '(hydrateRoot/createRoot). The registered callbacks will never be called with the current React version.');
+            warnedMissingRootApi = true;
+        }
+    }
+    else if (!supportsReact19RootErrorCallbacks) {
+        const react19OnlyKeys = providedKeys.filter((key) => REACT_19_ONLY_HANDLER_KEYS.includes(key));
+        if (react19OnlyKeys.length > 0 && !warnedMissingReact19Callbacks) {
+            console.warn(`[ReactOnRails] rootErrorHandlers (${react19OnlyKeys.join(', ')}) require React 19. ` +
+                'Only onRecoverableError is supported on React 18; React 19-only callbacks ' +
+                `(${REACT_19_ONLY_HANDLER_KEYS.join(', ')}) will never be called with the current React version.`);
+            warnedMissingReact19Callbacks = true;
+        }
+    }
+    // Per-key merge: keys absent from `handlers` keep their previous registration; keys explicitly
+    // set to `undefined` are cleared.
+    const merged = {};
+    HANDLER_KEYS.forEach((key) => {
+        const next = Object.prototype.hasOwnProperty.call(handlers, key)
+            ? handlers[key]
+            : registeredHandlers[key];
+        if (typeof next === 'function') {
+            merged[key] = next;
+        }
+    });
+    registeredHandlers = merged;
+}
+/** Clears the registered root error callbacks. Called by `ReactOnRails.resetOptions`. */
+export function resetRootErrorHandlers() {
+    registeredHandlers = {};
+    warnedMissingRootApi = false;
+    warnedMissingReact19Callbacks = false;
+}
+/**
+ * Returns a snapshot copy of the currently registered root error callbacks. A copy is returned so
+ * callers cannot mutate the internal registration and bypass `setRootErrorHandlers` validation.
+ */
+export function getRootErrorHandlers() {
+    return { ...registeredHandlers };
+}
+// A failing user callback must not break React's own error recovery, so failures are logged
+// rather than propagated. Handlers are typed to return void, but an `async` handler (or one
+// returning a rejecting thenable) is still assignable to that type, so adopt any returned
+// thenable and swallow its rejection too — otherwise a root error could surface as an unhandled
+// promise rejection from the very callback meant to report it.
+function safeInvoke(handler, key, error, errorInfo, context) {
+    const logHandlerFailure = (handlerError) => {
+        console.error(`[ReactOnRails] The registered rootErrorHandlers.${key} callback threw while handling a root error:`, handlerError, 'Original root error:', error);
+    };
+    // Re-type the void-returning handler so an async handler's returned promise can be inspected.
+    const invoke = handler;
+    try {
+        const result = invoke(error, errorInfo, context);
+        if (isThenable(result)) {
+            // `Promise.resolve(...)` adopts non-native thenables that may lack `.catch`.
+            Promise.resolve(result).catch(logHandlerFailure);
+        }
+    }
+    catch (handlerError) {
+        logHandlerFailure(handlerError);
+    }
+}
+function inDevelopmentEnv() {
+    // Called from client render paths after #js-react-on-rails-context is in the DOM; keep this
+    // development-only so test suites opt into reporter assertions instead of getting noisy logs.
+    if (typeof document === 'undefined') {
+        return false;
+    }
+    return getRailsContext()?.railsEnv === 'development';
+}
+/**
+ * Mirrors React's own default `onRecoverableError` (`reportError` where available, else
+ * `console.error`). Attaching a root callback replaces React's default reporting, so the
+ * dev-mode logger must re-emit it itself — otherwise window-'error'-based tooling (dev overlays,
+ * error trackers) goes silent in development.
+ */
+export function defaultReportRecoverableError(error) {
+    if (typeof globalThis.reportError === 'function') {
+        globalThis.reportError(error);
+    }
+    else {
+        console.error(error);
+    }
+}
+function extractComponentStack(errorInfo) {
+    const componentStack = errorInfo?.componentStack;
+    return typeof componentStack === 'string' && componentStack.length > 0 ? componentStack : undefined;
+}
+/**
+ * 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).
+ */
+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}`);
+}
+/**
+ * Builds the `hydrateRoot`/`createRoot` error callback options for one React root, wrapping the
+ * user's registered handlers so they also receive `context` (component name and dom id).
+ *
+ * The handlers registered at root-creation time are CAPTURED into the returned wrappers (not
+ * re-read on every error): attaching a root callback permanently replaces React's default
+ * reporting for that callback on that root, so a wrapper that later re-read cleared handlers
+ * would silently swallow errors. Roots therefore keep the handlers they were created with;
+ * re-registering affects only roots created afterwards.
+ *
+ * When hydrating in Rails development mode, a React on Rails-branded hydration-mismatch line
+ * (component name, dom id, component stack, guide link) is attached in addition to (and before)
+ * any user `onRecoverableError`. React's default reporting is preserved: the error itself is
+ * still default-reported once — via `defaultReportRecoverableError` here, or by the caller's own
+ * reporting when `defaultReportingHandledInternally` is set.
+ *
+ * Returns `{}` when nothing needs to be attached so React's default error reporting stays
+ * untouched, and on React <18 (the legacy `hydrate`/`render` APIs have no such options).
+ */
+export function buildRootErrorCallbackOptions(context, hydrating, { defaultReportingHandledInternally = false } = {}) {
+    if (!supportsRootApi) {
+        return {};
+    }
+    const options = {};
+    const { onRecoverableError, onCaughtError, onUncaughtError } = registeredHandlers;
+    // Capture once at root creation; the callback does not re-check the Rails env per error.
+    const logDevDefault = hydrating && inDevelopmentEnv();
+    if (logDevDefault || onRecoverableError) {
+        options.onRecoverableError = (error, errorInfo) => {
+            if (logDevDefault) {
+                if (!defaultReportingHandledInternally) {
+                    defaultReportRecoverableError(error);
+                }
+                logDevHydrationError(context, errorInfo);
+            }
+            if (onRecoverableError) {
+                safeInvoke(onRecoverableError, 'onRecoverableError', error, errorInfo, context);
+            }
+        };
+    }
+    if (supportsReact19RootErrorCallbacks) {
+        if (onCaughtError) {
+            options.onCaughtError = (error, errorInfo) => safeInvoke(onCaughtError, 'onCaughtError', error, errorInfo, context);
+        }
+        if (onUncaughtError) {
+            options.onUncaughtError = (error, errorInfo) => safeInvoke(onUncaughtError, 'onUncaughtError', error, errorInfo, context);
+        }
+    }
+    return options;
+}
+/**
+ * Pro RSC hydration wraps the returned `onRecoverableError` with an internal handler that has already
+ * performed React's default recoverable-error reporting. Keep that invariant in one named helper so
+ * Pro call sites do not need to remember the lower-level `defaultReportingHandledInternally` flag.
+ *
+ * On non-hydrate (`createRoot`) paths, `defaultReportingHandledInternally` is false, so this
+ * degrades to `buildRootErrorCallbackOptions` with no reporting-behavior change.
+ */
+export function buildRootErrorCallbackOptionsWithInternalRecoverableErrorReporting(context, hydrating) {
+    return buildRootErrorCallbackOptions(context, hydrating, {
+        defaultReportingHandledInternally: hydrating,
+    });
+}
+//# sourceMappingURL=rootErrorHandlers.js.map

package/lib/serverRenderUtils.js

@@ -1,3 +1,19 @@
+// 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;
+    }
+}
 export function buildRenderMetadata(consoleReplayScript, renderState) {
     return {
         consoleReplayScript,
@@ -5,7 +21,7 @@ export function buildRenderMetadata(consoleReplayScript, renderState) {
         hasErrors: renderState.hasErrors,
         renderingError: renderState.error && {
             message: renderState.error.message,
-            stack: renderState.error.stack,
+            stack: remapSourceMappedStack(renderState.error.stack),
         },
         isShellReady: 'isShellReady' in renderState ? renderState.isShellReady : undefined,
     };
@@ -97,6 +113,11 @@ export function convertToError(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) {

package/lib/types/index.d.ts

@@ -250,6 +250,40 @@ export interface Root {
     unmount(): void;
 }
 export type RenderReturnType = void | Element | Component | Root;
+/** Extra context React on Rails adds when invoking registered root error callbacks. */
+export interface RootErrorContext {
+    /** Name of the registered component rendered into the affected React root, when known. */
+    componentName?: string;
+    /** DOM id of the element the affected React root was mounted in, when known. */
+    domNodeId?: string;
+}
+/**
+ * A root error callback registered through `ReactOnRails.setOptions({ rootErrorHandlers })`.
+ * Receives React's original `(error, errorInfo)` arguments plus React on Rails context about the
+ * affected root. `errorInfo` typically contains `componentStack` (see the `react-dom/client`
+ * `createRoot`/`hydrateRoot` option docs for the exact per-callback shape).
+ */
+export type RootErrorHandler = (error: unknown, errorInfo: unknown, context: RootErrorContext) => void;
+/**
+ * User-registered React root error callbacks, applied to every React root that React on Rails
+ * creates via `hydrateRoot`/`createRoot`. Register them before your components render (typically
+ * in the same pack file where you call `ReactOnRails.register`); each root captures the callbacks
+ * registered at the moment it is created. Partial updates merge per key: a later
+ * `setOptions({ rootErrorHandlers })` call that sets only one callback keeps the others; pass an
+ * explicit `undefined` for a key to clear just that callback. Passing `null` is invalid and
+ * throws at runtime; use `undefined` to deregister.
+ */
+export interface RootErrorHandlers {
+    /**
+     * Called when React automatically recovers from an error, e.g. a hydration mismatch.
+     * Requires React 18+.
+     */
+    onRecoverableError?: RootErrorHandler;
+    /** Called for errors caught by an error boundary. Requires React 19+. */
+    onCaughtError?: RootErrorHandler;
+    /** Called for errors not caught by any error boundary. Requires React 19+. */
+    onUncaughtError?: RootErrorHandler;
+}
 export interface ReactOnRailsOptions {
     /** Gives you debugging messages on Turbolinks events. */
     traceTurbolinks?: boolean;
@@ -259,6 +293,12 @@ export interface ReactOnRailsOptions {
     debugMode?: boolean;
     /** Log component registration details including timing and size information. */
     logComponentRegistration?: boolean;
+    /**
+     * React root error callbacks (`onRecoverableError`, `onCaughtError`, `onUncaughtError`)
+     * applied to every React root created by React on Rails.
+     * @see {RootErrorHandlers}
+     */
+    rootErrorHandlers?: RootErrorHandlers;
 }
 export interface ReactOnRails {
     /**

package/lib/useRailsForm.d.ts

@@ -0,0 +1,137 @@
+/**
+ * useRailsForm — a small, Inertia `useForm`-style hook for submitting React
+ * forms to plain Rails controller actions.
+ *
+ * The hook keeps Rails as the mutation layer: it wires up `fetch`, attaches the
+ * CSRF token from the standard Rails `<meta name="csrf-token">` tag (via the
+ * existing `authenticityToken` utility), sends/receives JSON, and maps the
+ * blessed 422 validation-error shape — `{ errors: { field: ["message"] } }` —
+ * onto per-field client state. The matching server side is the opt-in
+ * `ReactOnRails::Controller::FormResponders#render_model_errors` concern in the
+ * react_on_rails gem, but the hook works against any endpoint that returns the
+ * documented shape.
+ *
+ * v1 scope (https://github.com/shakacode/react_on_rails/issues/3872):
+ * submit verbs, `data`/`setData`, `errors`, `processing`, CSRF auto-attach, and
+ * 422 error mapping. Deferred to a follow-up: `transform`,
+ * `recentlySuccessful`, and file-upload `progress` (which requires an
+ * XMLHttpRequest or duplex-stream transport; v1 is fetch-only).
+ *
+ * Success/redirect handling is intentionally minimal and forward-compatible
+ * with the client-routing work in issue #3873: the hook never navigates on its
+ * own. It surfaces safe JSON `redirect_to` hints through `onSuccess` / the
+ * resolved submit result so the app — or a future router integration — decides
+ * what to do.
+ */
+/** Per-field validation errors: `{ field: ["message", ...] }`. */
+export type RailsFormErrors = Record<string, string[]>;
+export type RailsFormMethod = 'post' | 'put' | 'patch' | 'delete';
+export interface RailsFormSuccessResult {
+    ok: true;
+    /** Parsed JSON response body, or `null` when the body was empty or not JSON. */
+    responseData: unknown;
+    /**
+     * Redirect target when the server replied with a safe JSON
+     * `redirect_to`/`redirectTo` hint. Browser redirect following is disabled for
+     * CSRF-bearing submissions; a defensively filtered redirected Response URL is
+     * still accepted if a custom fetch implementation returns one.
+     * Hints are accepted only when they resolve to the current origin over HTTP(S);
+     * non-HTTP schemes such as `javascript:` are ignored.
+     * The hook never navigates — pass this to your router or `window.location`.
+     * Designed to compose with the client-routing integration in issue #3873.
+     */
+    redirectTo: string | null;
+    response: Response;
+}
+export interface RailsFormValidationErrorResult {
+    ok: false;
+    /** Per-field errors mapped from the 422 response body. */
+    errors: RailsFormErrors;
+    response: Response;
+}
+export interface RailsFormStaleResult {
+    ok: false;
+    /**
+     * True when this submit was superseded by a newer submit before it settled.
+     * Stale submissions do not update form state, run submit callbacks, or reject
+     * stale caller `.catch()` handlers after the newer submit has won.
+     */
+    stale: true;
+    response?: Response;
+    error?: unknown;
+}
+export type RailsFormSubmitResult = RailsFormSuccessResult | RailsFormValidationErrorResult | RailsFormStaleResult;
+/** Thrown (as a promise rejection) for non-2xx responses other than a mappable 422. */
+export declare class RailsFormRequestError extends Error {
+    /** The response, with its body stream unread — `.json()`/`.text()` work. */
+    readonly response: Response;
+    /**
+     * Parsed JSON body when the hook already read it (a 422 whose body didn't
+     * match the documented errors shape); `undefined` otherwise.
+     */
+    readonly responseBody: unknown;
+    constructor(response: Response, responseBody?: unknown);
+}
+export interface RailsFormSubmitOptions {
+    /** Extra request headers. JSON and CSRF headers are always applied on top. */
+    headers?: Record<string, string>;
+    /**
+     * Called after a 2xx response. If this callback throws, the exception
+     * propagates as the submit promise rejection after form state has settled.
+     */
+    onSuccess?: (result: RailsFormSuccessResult) => void;
+    /** Called after a 422 response whose body matched the documented errors shape. */
+    onError?: (errors: RailsFormErrors) => void;
+}
+export interface UseRailsForm<TData extends object> {
+    /** Current form data. */
+    data: TData;
+    /** Set a single field, merge a partial object, or apply an updater function. */
+    setData: {
+        <K extends keyof TData>(key: K, value: TData[K]): void;
+        (valuesOrUpdater: Partial<TData> | ((previousData: TData) => TData)): void;
+    };
+    /** Per-field validation errors from the last 422 response (or `setError`). */
+    errors: RailsFormErrors;
+    hasErrors: boolean;
+    /** True while a submission is in flight. */
+    processing: boolean;
+    /** True once the most recent submission succeeded. Reset when a new one starts. */
+    wasSuccessful: boolean;
+    /** Submit with an explicit HTTP method. */
+    submit: (method: RailsFormMethod, url: string, options?: RailsFormSubmitOptions) => Promise<RailsFormSubmitResult>;
+    post: (url: string, options?: RailsFormSubmitOptions) => Promise<RailsFormSubmitResult>;
+    put: (url: string, options?: RailsFormSubmitOptions) => Promise<RailsFormSubmitResult>;
+    patch: (url: string, options?: RailsFormSubmitOptions) => Promise<RailsFormSubmitResult>;
+    /** Named `delete` on the hook object; `delete` is reserved in some contexts. */
+    delete: (url: string, options?: RailsFormSubmitOptions) => Promise<RailsFormSubmitResult>;
+    /**
+     * Reset all data (no args) or the given fields to their initial values.
+     * Clears matching errors and `wasSuccessful`. "Initial values" are the
+     * `initialData` captured on first render (Inertia `useForm` semantics) —
+     * later prop changes are not tracked; remount the component to re-seed.
+     */
+    reset: (...fields: Extract<keyof TData, string>[]) => void;
+    /** Clear all errors (no args) or the errors for the given fields. */
+    clearErrors: (...fields: string[]) => void;
+    /** Manually set the errors for one field (e.g. client-side pre-checks). */
+    setError: (field: string, messages: string | string[]) => void;
+}
+/**
+ * React hook for submitting form data to a Rails controller action.
+ *
+ * ```tsx
+ * const form = useRailsForm({ name: '', email: '' });
+ * // <input value={form.data.name} onChange={(e) => form.setData('name', e.target.value)} />
+ * // {form.errors.name?.[0]}
+ * // <form onSubmit={(e) => { e.preventDefault(); void form.post('/contacts'); }}>
+ * ```
+ *
+ * Submissions send `Content-Type: application/json` / `Accept: application/json`
+ * with the CSRF token from the Rails csrf-token meta tag. A 422 response with a
+ * `{ errors: { field: ["message"] } }` body (the shape rendered by the
+ * `render_model_errors` controller concern) populates `errors`; other non-2xx
+ * responses reject with `RailsFormRequestError`.
+ */
+export declare function useRailsForm<TData extends object>(initialData: TData): UseRailsForm<TData>;
+//# sourceMappingURL=useRailsForm.d.ts.map

package/lib/useRailsForm.js

@@ -0,0 +1,430 @@
+/**
+ * useRailsForm — a small, Inertia `useForm`-style hook for submitting React
+ * forms to plain Rails controller actions.
+ *
+ * The hook keeps Rails as the mutation layer: it wires up `fetch`, attaches the
+ * CSRF token from the standard Rails `<meta name="csrf-token">` tag (via the
+ * existing `authenticityToken` utility), sends/receives JSON, and maps the
+ * blessed 422 validation-error shape — `{ errors: { field: ["message"] } }` —
+ * onto per-field client state. The matching server side is the opt-in
+ * `ReactOnRails::Controller::FormResponders#render_model_errors` concern in the
+ * react_on_rails gem, but the hook works against any endpoint that returns the
+ * documented shape.
+ *
+ * v1 scope (https://github.com/shakacode/react_on_rails/issues/3872):
+ * submit verbs, `data`/`setData`, `errors`, `processing`, CSRF auto-attach, and
+ * 422 error mapping. Deferred to a follow-up: `transform`,
+ * `recentlySuccessful`, and file-upload `progress` (which requires an
+ * XMLHttpRequest or duplex-stream transport; v1 is fetch-only).
+ *
+ * Success/redirect handling is intentionally minimal and forward-compatible
+ * with the client-routing work in issue #3873: the hook never navigates on its
+ * own. It surfaces safe JSON `redirect_to` hints through `onSuccess` / the
+ * resolved submit result so the app — or a future router integration — decides
+ * what to do.
+ */
+import * as React from 'react';
+import { authenticityToken } from "./Authenticity.js";
+/** Thrown (as a promise rejection) for non-2xx responses other than a mappable 422. */
+export class RailsFormRequestError extends Error {
+    constructor(response, responseBody = undefined) {
+        super(`useRailsForm request failed with status ${response.status}`);
+        this.name = 'RailsFormRequestError';
+        this.response = response;
+        this.responseBody = responseBody;
+    }
+}
+const PINNED_RAILS_FORM_HEADER_NAMES = new Set([
+    'accept',
+    'content-type',
+    'x-csrf-token',
+    'x-requested-with',
+]);
+const REQUIRED_REACT_HOOK_NAMES = ['useCallback', 'useEffect', 'useRef', 'useState'];
+const assertReactHooksAvailable = () => {
+    const missingHooks = REQUIRED_REACT_HOOK_NAMES.filter((hookName) => typeof React[hookName] !== 'function');
+    if (missingHooks.length > 0) {
+        throw new Error(`useRailsForm requires React 16.8 or newer because it uses React hooks. Missing React exports: ${missingHooks.join(', ')}.`);
+    }
+};
+assertReactHooksAvailable();
+const railsFormJsonHeaders = (customHeaders = {}) => {
+    const filteredCustomHeaders = Object.fromEntries(Object.entries(customHeaders).filter(([headerName]) => !PINNED_RAILS_FORM_HEADER_NAMES.has(headerName.toLowerCase())));
+    return {
+        ...filteredCustomHeaders,
+        Accept: 'application/json',
+        'Content-Type': 'application/json',
+    };
+};
+const railsFormHeaders = (csrfToken, customHeaders) => ({
+    ...railsFormJsonHeaders(customHeaders),
+    'X-CSRF-Token': csrfToken,
+    'X-Requested-With': 'XMLHttpRequest',
+});
+const validationMessageToString = (value) => {
+    switch (typeof value) {
+        case 'string':
+            return value;
+        case 'number':
+        case 'boolean':
+        case 'bigint':
+        case 'symbol':
+            return value.toString();
+        default: {
+            try {
+                return JSON.stringify(value) ?? Object.prototype.toString.call(value);
+            }
+            catch {
+                return Object.prototype.toString.call(value);
+            }
+        }
+    }
+};
+const toMessageArray = (value) => {
+    if (Array.isArray(value)) {
+        return value.filter((message) => message != null).map(validationMessageToString);
+    }
+    if (value == null) {
+        return [];
+    }
+    // Preserve unexpected custom-endpoint values visibly instead of silently
+    // dropping them, but ignore nullish values that cannot be displayed helpfully.
+    return [validationMessageToString(value)];
+};
+/**
+ * Normalizes a 422 response body into per-field errors. Returns `null` when the
+ * body doesn't match the documented `{ errors: { field: messages } }` shape.
+ * An empty `errors` object is still a handled validation response.
+ */
+const mapValidationErrors = (body) => {
+    if (typeof body !== 'object' || body === null) {
+        return null;
+    }
+    const { errors } = body;
+    if (typeof errors !== 'object' || errors === null || Array.isArray(errors)) {
+        return null;
+    }
+    const errorEntries = Object.entries(errors);
+    const mapped = {};
+    for (const [field, messages] of errorEntries) {
+        const fieldMessages = toMessageArray(messages);
+        if (fieldMessages.length > 0) {
+            mapped[field] = fieldMessages;
+        }
+    }
+    return mapped;
+};
+const parseJsonBody = async (response) => {
+    try {
+        return (await response.json());
+    }
+    catch {
+        return null;
+    }
+};
+const safeJsonRedirectHint = (redirectTo) => {
+    const normalizedRedirect = redirectTo.trim();
+    if (normalizedRedirect.length === 0) {
+        return null;
+    }
+    const currentLocation = typeof window === 'undefined' ? null : window.location;
+    if (currentLocation === null) {
+        return null;
+    }
+    try {
+        // Match browser relative-URL behavior: query-only hints update the current
+        // page query, while root-relative hints like `/posts/1` stay root-relative.
+        const parsedRedirect = new URL(normalizedRedirect, currentLocation.href);
+        if ((parsedRedirect.protocol === 'http:' || parsedRedirect.protocol === 'https:') &&
+            parsedRedirect.origin === currentLocation.origin) {
+            if (/^https?:\/\//i.test(normalizedRedirect)) {
+                return parsedRedirect.href;
+            }
+            return `${parsedRedirect.pathname}${parsedRedirect.search}${parsedRedirect.hash}`;
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+};
+const resolveSameOriginRequestUrl = (url) => {
+    const currentLocation = typeof window === 'undefined' ? null : window.location;
+    if (currentLocation === null || typeof document === 'undefined') {
+        // No browser origin/document is available in SSR/Node, so same-origin and
+        // CSRF guards cannot be enforced. Refuse the submit instead of guessing.
+        return null;
+    }
+    try {
+        const resolvedUrl = new URL(url, document.baseURI);
+        if ((resolvedUrl.protocol === 'http:' || resolvedUrl.protocol === 'https:') &&
+            resolvedUrl.origin === currentLocation.origin) {
+            return resolvedUrl.href;
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+};
+const extractRedirectTo = (response, responseData) => {
+    // Native fetch never reaches this when `redirect: 'error'` is set; it throws
+    // before returning a redirected Response. Keep the filter for custom fetch
+    // implementations and tests that return pre-followed responses.
+    if (response.redirected && response.url) {
+        return safeJsonRedirectHint(response.url);
+    }
+    if (typeof responseData === 'object' && responseData !== null) {
+        const { redirect_to: redirectSnake, redirectTo: redirectCamel } = responseData;
+        if (typeof redirectSnake === 'string') {
+            return safeJsonRedirectHint(redirectSnake);
+        }
+        if (typeof redirectCamel === 'string') {
+            return safeJsonRedirectHint(redirectCamel);
+        }
+    }
+    return null;
+};
+const warnOnPossibleRedirectFetchError = (fetchError) => {
+    // Keep this development-only: browsers surface `redirect: "error"` failures
+    // as opaque TypeErrors, and warning on every production network failure would
+    // be noisy without giving end users an actionable recovery path.
+    if (process.env.NODE_ENV === 'production' || !(fetchError instanceof TypeError)) {
+        return;
+    }
+    if (!/failed to fetch|networkerror|load failed/i.test(fetchError.message)) {
+        return;
+    }
+    console.warn('[useRailsForm] The request may have been rejected because the server responded with a redirect. ' +
+        'useRailsForm requires `render json:` for success responses; Rails `redirect_to` is not supported in v1.');
+};
+const staleSubmitResult = (response, error) => {
+    const result = { ok: false, stale: true };
+    if (response) {
+        result.response = response;
+    }
+    if (error !== undefined) {
+        result.error = error;
+    }
+    return result;
+};
+/**
+ * React hook for submitting form data to a Rails controller action.
+ *
+ * ```tsx
+ * const form = useRailsForm({ name: '', email: '' });
+ * // <input value={form.data.name} onChange={(e) => form.setData('name', e.target.value)} />
+ * // {form.errors.name?.[0]}
+ * // <form onSubmit={(e) => { e.preventDefault(); void form.post('/contacts'); }}>
+ * ```
+ *
+ * Submissions send `Content-Type: application/json` / `Accept: application/json`
+ * with the CSRF token from the Rails csrf-token meta tag. A 422 response with a
+ * `{ errors: { field: ["message"] } }` body (the shape rendered by the
+ * `render_model_errors` controller concern) populates `errors`; other non-2xx
+ * responses reject with `RailsFormRequestError`.
+ */
+export function useRailsForm(initialData) {
+    // Captured once on first render (Inertia useForm semantics): reset() restores
+    // these mount-time values even if the initialData prop changes later.
+    const initialDataRef = React.useRef(initialData);
+    const [data, setDataState] = React.useState(initialData);
+    const [errors, setErrors] = React.useState({});
+    const [processing, setProcessing] = React.useState(false);
+    const [wasSuccessful, setWasSuccessful] = React.useState(false);
+    // Latest data for submit(). Updated eagerly by commitData (not on render) so
+    // `setData(...); submit(...)` in the same tick posts the just-set values —
+    // React batches the state update, so `data` itself is stale until re-render.
+    const dataRef = React.useRef(data);
+    const commitData = React.useCallback((updater) => {
+        dataRef.current = updater(dataRef.current);
+        setDataState(dataRef.current);
+    }, []);
+    // Guards against state updates from stale (superseded) or unmounted submissions.
+    const submissionIdRef = React.useRef(0);
+    const pendingSubmissionsRef = React.useRef(0);
+    const mountedRef = React.useRef(true);
+    React.useEffect(() => {
+        // Re-assigning true is NOT redundant: under React StrictMode (and Fast
+        // Refresh) the cleanup runs and the effect re-runs on the same component
+        // instance, so without this the ref would stay false after the replay.
+        mountedRef.current = true;
+        // If a submission settled during the StrictMode cleanup/replay window,
+        // finishSubmission could have skipped the visible state update while
+        // mountedRef was false. Resync the flag when the same instance remounts.
+        if (pendingSubmissionsRef.current === 0) {
+            setProcessing(false);
+        }
+        return () => {
+            mountedRef.current = false;
+        };
+    }, []);
+    const setData = React.useCallback((keyOrValues, value) => {
+        if (typeof keyOrValues === 'function') {
+            commitData(keyOrValues);
+        }
+        else if (typeof keyOrValues === 'object') {
+            commitData((previousData) => ({ ...previousData, ...keyOrValues }));
+        }
+        else {
+            commitData((previousData) => ({ ...previousData, [keyOrValues]: value }));
+        }
+    }, [commitData]);
+    const clearErrors = React.useCallback((...fields) => {
+        if (fields.length === 0) {
+            setErrors({});
+            return;
+        }
+        setErrors((previousErrors) => Object.fromEntries(Object.entries(previousErrors).filter(([field]) => !fields.includes(field))));
+    }, []);
+    const setError = React.useCallback((field, messages) => {
+        setErrors((previousErrors) => ({ ...previousErrors, [field]: toMessageArray(messages) }));
+    }, []);
+    const reset = React.useCallback((...fields) => {
+        // A reset starts a fresh editing cycle: a pristine form should not still
+        // report the previous submission as successful.
+        setWasSuccessful(false);
+        if (fields.length === 0) {
+            commitData(() => initialDataRef.current);
+            clearErrors();
+            return;
+        }
+        commitData((previousData) => {
+            const nextData = { ...previousData };
+            fields.forEach((field) => {
+                nextData[field] = initialDataRef.current[field];
+            });
+            return nextData;
+        });
+        clearErrors(...fields);
+    }, [clearErrors, commitData]);
+    const submit = React.useCallback(async (method, url, options = {}) => {
+        submissionIdRef.current += 1;
+        const submissionId = submissionIdRef.current;
+        const isCurrent = () => mountedRef.current && submissionId === submissionIdRef.current;
+        const finishSubmission = () => {
+            pendingSubmissionsRef.current = Math.max(0, pendingSubmissionsRef.current - 1);
+            if (mountedRef.current && pendingSubmissionsRef.current === 0) {
+                setProcessing(false);
+            }
+        };
+        if (mountedRef.current && typeof window !== 'undefined') {
+            setWasSuccessful(false);
+            setErrors({});
+            // Safety valve: a prior submission can settle during a StrictMode
+            // cleanup window, leaving processing true even with no in-flight work.
+            if (pendingSubmissionsRef.current === 0) {
+                setProcessing(false);
+            }
+        }
+        const requestUrl = resolveSameOriginRequestUrl(url);
+        if (requestUrl === null) {
+            throw new Error('useRailsForm can only submit to same-origin URLs.');
+        }
+        const csrfToken = authenticityToken();
+        if (csrfToken === null) {
+            throw new Error('useRailsForm requires a <meta name="csrf-token"> tag before submitting. ' +
+                'Add <%= csrf_meta_tags %> to your Rails layout.');
+        }
+        pendingSubmissionsRef.current += 1;
+        setProcessing(true);
+        let response;
+        try {
+            response = await fetch(requestUrl, {
+                method: method.toUpperCase(),
+                credentials: 'same-origin',
+                // Never follow redirects while carrying explicit CSRF headers; an
+                // open redirect could otherwise leak the token to another origin.
+                redirect: 'error',
+                headers: railsFormHeaders(csrfToken, options.headers),
+                // DELETE bodies are legal per RFC 9110 but are stripped or rejected by
+                // many proxies/CDNs in practice — identify the resource in the URL.
+                body: method === 'delete' ? undefined : JSON.stringify(dataRef.current),
+            });
+        }
+        catch (fetchError) {
+            finishSubmission();
+            if (!isCurrent()) {
+                return staleSubmitResult(undefined, fetchError);
+            }
+            warnOnPossibleRedirectFetchError(fetchError);
+            throw fetchError;
+        }
+        if (response.status === 422) {
+            // Parse a clone so `response` stays readable if we end up throwing
+            // RailsFormRequestError below (e.g. the body doesn't match the shape).
+            const body = await parseJsonBody(response.clone());
+            const validationErrors = mapValidationErrors(body);
+            if (validationErrors !== null) {
+                if (isCurrent()) {
+                    setErrors(validationErrors);
+                    finishSubmission();
+                    options.onError?.(validationErrors);
+                }
+                else {
+                    finishSubmission();
+                    return staleSubmitResult(response);
+                }
+                return { ok: false, errors: validationErrors, response };
+            }
+            finishSubmission();
+            if (!isCurrent()) {
+                return staleSubmitResult(response);
+            }
+            throw new RailsFormRequestError(response, body);
+        }
+        if (!response.ok) {
+            finishSubmission();
+            if (!isCurrent()) {
+                return staleSubmitResult(response);
+            }
+            throw new RailsFormRequestError(response);
+        }
+        const responseData = await parseJsonBody(response.clone());
+        const result = {
+            ok: true,
+            responseData,
+            redirectTo: extractRedirectTo(response, responseData),
+            response,
+        };
+        if (isCurrent()) {
+            setErrors({});
+            setWasSuccessful(true);
+            finishSubmission();
+            // Guarded like the state updates: a superseded submission must not
+            // fire callbacks (e.g. navigate on redirectTo) after a newer one.
+            options.onSuccess?.(result);
+        }
+        else {
+            finishSubmission();
+            return staleSubmitResult(response);
+        }
+        return result;
+    }, 
+    // Intentionally empty: everything read inside satisfies
+    // react-hooks/exhaustive-deps — refs (dataRef, submissionIdRef, mountedRef),
+    // useState setters, and module-level imports. If you add a render-scoped
+    // value here, it must go in this array.
+    []);
+    const post = React.useCallback((url, options) => submit('post', url, options), [submit]);
+    const put = React.useCallback((url, options) => submit('put', url, options), [submit]);
+    const patch = React.useCallback((url, options) => submit('patch', url, options), [submit]);
+    const destroy = React.useCallback((url, options) => submit('delete', url, options), [submit]);
+    return {
+        data,
+        setData,
+        errors,
+        hasErrors: Object.keys(errors).length > 0,
+        processing,
+        wasSuccessful,
+        submit,
+        post,
+        put,
+        patch,
+        delete: destroy,
+        reset,
+        clearErrors,
+        setError,
+    };
+}
+//# sourceMappingURL=useRailsForm.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-on-rails",
-  "version": "17.0.0-rc.3",
+  "version": "17.0.0-rc.4",
   "description": "react-on-rails JavaScript for react_on_rails Ruby gem",
   "main": "lib/ReactOnRails.full.js",
   "type": "module",
@@ -32,6 +32,7 @@
     "./reactApis": "./lib/reactApis.cjs",
     "./webpackHelpers": "./lib/webpackHelpers.cjs",
     "./reactHydrateOrRender": "./lib/reactHydrateOrRender.js",
+    "./useRailsForm": "./lib/useRailsForm.js",
     "./turbolinksUtils": "./lib/turbolinksUtils.js",
     "./isRenderFunction": "./lib/isRenderFunction.js",
     "./ReactOnRails.client": "./lib/ReactOnRails.client.js",
@@ -44,6 +45,8 @@
     "./serverRenderReactComponent": "./lib/serverRenderReactComponent.js",
     "./@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",
@@ -72,6 +75,10 @@
     "url": "https://github.com/shakacode/react_on_rails/issues"
   },
   "homepage": "https://reactonrails.com/docs/",
+  "devDependencies": {
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/react": "^16.2.0"
+  },
   "scripts": {
     "build": "pnpm run clean && tsc",
     "build-watch": "pnpm run clean && tsc --watch",