react-on-rails-pro 16.5.1 → 16.6.0-rc.1

package/lib/ClientSideRenderer.d.ts

@@ -1,8 +1,8 @@
 export declare function renderOrHydrateComponent(domIdOrElement: string | Element): Promise<void>;
-export declare const renderOrHydrateImmediateHydratedComponents: () => Promise<void>;
+export declare const renderOrHydrateCompleteComponents: () => Promise<void>;
 export declare const renderOrHydrateAllComponents: () => Promise<void>;
 export declare function hydrateStore(storeNameOrElement: string | Element): Promise<void>;
-export declare const hydrateImmediateHydratedStores: () => Promise<void>;
+export declare const hydrateCompleteStores: () => Promise<void>;
 export declare const hydrateAllStores: () => Promise<void>;
 export declare function unmountAll(): void;
 //# sourceMappingURL=ClientSideRenderer.d.ts.map

package/lib/ClientSideRenderer.js

@@ -17,12 +17,9 @@ import { isServerRenderHash } from 'react-on-rails/isServerRenderResult';
 import { supportsHydrate, supportsRootApi, unmountComponentAtNode } from 'react-on-rails/reactApis';
 import reactHydrateOrRender from 'react-on-rails/reactHydrateOrRender';
 import { debugTurbolinks } from 'react-on-rails/turbolinksUtils';
-import { onPageLoaded } from 'react-on-rails/pageLifecycle';
 import * as StoreRegistry from "./StoreRegistry.js";
 import * as ComponentRegistry from "./ComponentRegistry.js";
 const REACT_ON_RAILS_STORE_ATTRIBUTE = 'data-js-react-on-rails-store';
-const IMMEDIATE_HYDRATION_PRO_WARNING = "[REACT ON RAILS] The 'immediate_hydration' feature requires the React on Rails Pro gem to be installed on the server. " +
-    'Please visit https://pro.reactonrails.com/ for installation details.';
 async function delegateToRenderer(componentObj, props, railsContext, domNodeId, trace) {
     const { name, component, isRenderer } = componentObj;
     if (isRenderer) {
@@ -57,24 +54,14 @@ class ComponentRenderer {
             return this.render(el, railsContext);
         });
     }
+    hasStartedRendering() {
+        return this.renderPromise !== undefined;
+    }
     /**
      * Used for client rendering by ReactOnRails. Either calls ReactDOM.hydrate, ReactDOM.render, or
      * delegates to a renderer registered by the user.
      */
     async render(el, railsContext) {
-        const isImmediateHydrationRequested = el.getAttribute('data-immediate-hydration') === 'true';
-        // rorPro signals gem presence on the server, not license validity.
-        const hasProGemInstalled = railsContext.rorPro;
-        // Handle immediate_hydration feature usage without Pro gem installed
-        if (isImmediateHydrationRequested && !hasProGemInstalled) {
-            console.warn(IMMEDIATE_HYDRATION_PRO_WARNING);
-            // Fallback to standard behavior: wait for page load before hydrating
-            if (document.readyState === 'loading') {
-                await new Promise((resolve) => {
-                    onPageLoaded(resolve);
-                });
-            }
-        }
         // This must match lib/react_on_rails/helper.rb
         const name = el.getAttribute('data-component-name') || '';
         const { domNodeId } = this;
@@ -176,6 +163,9 @@ class StoreRenderer {
         StoreRegistry.setStore(name, store);
         this.state = 'hydrated';
     }
+    hasStartedHydrating() {
+        return this.hydratePromise !== undefined;
+    }
     waitUntilHydrated() {
         if (this.state === 'hydrating' && this.hydratePromise) {
             return this.hydratePromise;
@@ -192,7 +182,11 @@ export function renderOrHydrateComponent(domIdOrElement) {
     debugTurbolinks('renderOrHydrateComponent', domId);
     let root = renderedRoots.get(domId);
     if (!root) {
-        root = new ComponentRenderer(domIdOrElement);
+        const newRoot = new ComponentRenderer(domIdOrElement);
+        if (!newRoot.hasStartedRendering()) {
+            return Promise.resolve();
+        }
+        root = newRoot;
         renderedRoots.set(domId, root);
     }
     return root.waitUntilRendered();
@@ -214,8 +208,8 @@ async function forAllElementsAsync(selector, callback) {
  * - Therefore, if nextSibling exists (even whitespace or comments), the closing
  *   tag was parsed and the content is guaranteed to be complete
  *
- * Elements without a nextSibling will be hydrated later when their
- * immediate hydration script executes and calls reactOnRailsComponentLoaded().
+ * Elements without a nextSibling will be hydrated via inline scripts as streaming completes (Pro),
+ * or on DOMContentLoaded (non-Pro).
  *
  * See: https://github.com/shakacode/react_on_rails/issues/2283
  */
@@ -224,7 +218,10 @@ async function forAllCompleteElementsAsync(selector, callback) {
     const completeEls = Array.from(els).filter((el) => el.nextSibling !== null);
     await Promise.all(completeEls.map(callback));
 }
-export const renderOrHydrateImmediateHydratedComponents = () => forAllCompleteElementsAsync('.js-react-on-rails-component[data-immediate-hydration="true"]', renderOrHydrateComponent);
+// For Pro streaming pages: hydrate all components whose markup has been fully streamed
+// (identified by having a nextSibling). On non-streaming pages this matches ALL components,
+// but ClientSideRenderer memoizes by DOM node id so the later DOMContentLoaded sweep is a no-op.
+export const renderOrHydrateCompleteComponents = () => forAllCompleteElementsAsync('.js-react-on-rails-component', renderOrHydrateComponent);
 export const renderOrHydrateAllComponents = () => forAllElementsAsync('.js-react-on-rails-component', renderOrHydrateComponent);
 function unmountAllComponents() {
     renderedRoots.forEach((root) => root.unmount());
@@ -244,12 +241,16 @@ export async function hydrateStore(storeNameOrElement) {
         if (!storeDataElement) {
             return;
         }
-        storeRenderer = new StoreRenderer(storeDataElement);
+        const newStoreRenderer = new StoreRenderer(storeDataElement);
+        if (!newStoreRenderer.hasStartedHydrating()) {
+            return;
+        }
+        storeRenderer = newStoreRenderer;
         storeRenderers.set(storeName, storeRenderer);
     }
     await storeRenderer.waitUntilHydrated();
 }
-export const hydrateImmediateHydratedStores = () => forAllCompleteElementsAsync(`[${REACT_ON_RAILS_STORE_ATTRIBUTE}][data-immediate-hydration="true"]`, hydrateStore);
+export const hydrateCompleteStores = () => forAllCompleteElementsAsync(`[${REACT_ON_RAILS_STORE_ATTRIBUTE}]`, hydrateStore);
 export const hydrateAllStores = () => forAllElementsAsync(`[${REACT_ON_RAILS_STORE_ATTRIBUTE}]`, hydrateStore);
 function unmountAllStores() {
     storeRenderers.forEach((storeRenderer) => storeRenderer.unmount());

package/lib/createReactOnRailsPro.js

@@ -11,12 +11,12 @@
  * For licensing terms, please see:
  * https://github.com/shakacode/react_on_rails/blob/master/REACT-ON-RAILS-PRO-LICENSE.md
  */
+import { getRailsContext } from 'react-on-rails/context';
 import { onPageLoaded, onPageUnloaded } from 'react-on-rails/pageLifecycle';
 import { debugTurbolinks } from 'react-on-rails/turbolinksUtils';
 import * as ProComponentRegistry from "./ComponentRegistry.js";
 import * as ProStoreRegistry from "./StoreRegistry.js";
-import { renderOrHydrateComponent, hydrateStore, renderOrHydrateAllComponents, hydrateAllStores, renderOrHydrateImmediateHydratedComponents, hydrateImmediateHydratedStores, unmountAll, } from "./ClientSideRenderer.js";
-// Pro client startup with immediate hydration support
+import { renderOrHydrateComponent, hydrateStore, renderOrHydrateAllComponents, hydrateAllStores, renderOrHydrateCompleteComponents, hydrateCompleteStores, unmountAll, } from "./ClientSideRenderer.js";
 async function reactOnRailsPageLoaded() {
     debugTurbolinks('reactOnRailsPageLoaded [PRO]');
     await Promise.all([hydrateAllStores(), renderOrHydrateAllComponents()]);
@@ -35,8 +35,20 @@ function clientStartup() {
     }
     // eslint-disable-next-line no-underscore-dangle
     globalThis.__REACT_ON_RAILS_EVENT_HANDLERS_RAN_ONCE__ = true;
-    void renderOrHydrateImmediateHydratedComponents();
-    void hydrateImmediateHydratedStores();
+    const railsContext = getRailsContext();
+    if (railsContext === null) {
+        // Context element not yet in DOM — expected in streaming scenarios.
+        // Early Pro hydration skipped; the page-loaded sweep will recover all components.
+        if (process.env.NODE_ENV !== 'production' && typeof console !== 'undefined') {
+            console.debug('[React on Rails] railsContext not available at clientStartup — early Pro hydration skipped, falling back to page-load sweep.');
+        }
+    }
+    else if (railsContext.rorPro) {
+        // Streaming pages can trigger these incrementally as markup arrives. The later
+        // page-loaded sweep is safe because ClientSideRenderer memoizes by DOM/store id.
+        void renderOrHydrateCompleteComponents();
+        void hydrateCompleteStores();
+    }
     onPageLoaded(reactOnRailsPageLoaded);
     onPageUnloaded(reactOnRailsPageUnloaded);
 }
@@ -103,7 +115,7 @@ export default function createReactOnRailsPro(baseObjectCreator, currentGlobal =
         globalThis.ReactOnRails = reactOnRailsPro;
         // Reset options to defaults (only on first initialization)
         reactOnRailsPro.resetOptions();
-        // Run Pro client startup with immediate hydration support (only on first initialization)
+        // Run Pro client startup (only on first initialization)
         clientStartup();
     }
     return reactOnRailsPro;

package/lib/tanstack-router/clientHydrate.d.ts

@@ -1,11 +1,9 @@
-import { type ComponentType, type ReactElement } from 'react';
+import { type ReactElement } from 'react';
 import type { TanStackHistory, TanStackRouter, TanStackRouterOptions } from './types.ts';
 import type { RailsContext } from 'react-on-rails/types';
 export declare function clientHydrateTanStackApp(options: TanStackRouterOptions, props: Record<string, unknown>, railsContext: RailsContext & {
     serverSide: false;
 }, RouterProvider: React.ComponentType<{
     router: TanStackRouter;
-}>, RouterClient: ComponentType<{
-    router: TanStackRouter;
-}> | undefined, createBrowserHistory: () => TanStackHistory): ReactElement;
+}>, createBrowserHistory: () => TanStackHistory): ReactElement;
 //# sourceMappingURL=clientHydrate.d.ts.map

package/lib/tanstack-router/clientHydrate.js

@@ -1,82 +1,229 @@
-import { createElement, useEffect, useRef } from 'react';
-function setTanStackSsrGlobal(ssrRouter) {
-    const globalState = window;
-    const existing = globalState.$_TSR;
-    const tsrGlobal = existing ?? {
-        buffer: [],
-        h() {
-            this.hydrated = true;
-        },
-        e() {
-            this.streamEnded = true;
-        },
-        c() { },
-        p(script) {
-            if (!this.initialized) {
-                this.buffer.push(script);
-                return;
-            }
-            script();
-        },
-    };
-    tsrGlobal.router = ssrRouter;
-    globalState.$_TSR = tsrGlobal;
+import { Suspense, createElement, useEffect, useRef } from 'react';
+function RouteChunkPreloadGate({ preloadPromise, preloadSettledRef, isHydrating, children, }) {
+    // During SSR hydration (first render), skip the suspension gate to avoid a
+    // hydration mismatch: the server rendered RouterProvider content directly,
+    // so throwing a promise here would cause Suspense to render the null fallback
+    // instead of matching the server HTML. After hydration completes (the
+    // post-mount effect sets didTriggerPostHydrationLoadRef), the gate activates
+    // normally for any subsequent re-renders.
+    if (!isHydrating && preloadPromise && !preloadSettledRef.current) {
+        // eslint-disable-next-line @typescript-eslint/only-throw-error -- Suspense boundaries intentionally suspend on thrown Promise.
+        throw preloadPromise;
+    }
+    return children;
+}
+function extractDehydratedData(dehydratedRouter) {
+    if (!dehydratedRouter || typeof dehydratedRouter !== 'object') {
+        return undefined;
+    }
+    return dehydratedRouter.dehydratedData;
+}
+function preloadMatchedRouteChunks(router, matches) {
+    const { loadRouteChunk, looseRoutesById } = router;
+    if (typeof loadRouteChunk !== 'function' || !looseRoutesById) {
+        return null;
+    }
+    const routeChunkPromises = [];
+    matches.forEach((match) => {
+        const { routeId } = match;
+        if (typeof routeId !== 'string') {
+            return;
+        }
+        const route = looseRoutesById[routeId];
+        if (!route) {
+            return;
+        }
+        routeChunkPromises.push(loadRouteChunk(route));
+    });
+    if (!routeChunkPromises.length) {
+        return null;
+    }
+    return Promise.all(routeChunkPromises)
+        .then(() => undefined)
+        .catch((error) => {
+        console.error('react-on-rails-pro/tanstack-router: Error preloading matched route chunks:', error);
+    });
+}
+/**
+ * Converts a dehydrated match ID (using \0 separator) back to the standard
+ * route ID format (using / separator) used by matchRoutes().
+ *
+ * Inverse of dehydrateSsrMatchId() in serverRender.ts, which replaces '/'
+ * with '\0' to match the $_TSR bootstrap wire format used by TanStack Router's
+ * DehydrateRouter component (see @tanstack/react-router/src/DehydrateRouter.tsx).
+ */
+function rehydrateMatchId(dehydratedId) {
+    return dehydratedId.split('\0').join('/');
+}
+/**
+ * Applies server-rendered match data (loaderData, beforeLoadContext, status, etc.)
+ * from the dehydrated SSR payload to fresh client matches. This ensures the first
+ * client render can access the same data the server used, preventing mismatches
+ * for routes that render from loader results.
+ */
+function applyDehydratedMatchData(matches, ssrMatches, onMissingSsrMatch) {
+    return matches.map((match) => {
+        const m = match;
+        const ssrMatch = ssrMatches.find((sm) => rehydrateMatchId(sm.i) === m.id);
+        if (ssrMatch) {
+            return {
+                ...m,
+                status: ssrMatch.s,
+                updatedAt: ssrMatch.u,
+                ...(ssrMatch.l !== undefined ? { loaderData: ssrMatch.l } : {}),
+                ...(ssrMatch.b !== undefined ? { __beforeLoadContext: ssrMatch.b } : {}),
+                ...(ssrMatch.e !== undefined ? { error: ssrMatch.e } : {}),
+                ...(ssrMatch.ssr !== undefined ? { ssr: ssrMatch.ssr } : {}),
+            };
+        }
+        // No server match — override pending to success to prevent MatchInner
+        // from throwing loadPromise (which would cause Suspense suspension).
+        if (m.status === 'pending') {
+            onMissingSsrMatch?.(m);
+            return { ...m, status: 'success' };
+        }
+        return m;
+    });
 }
 function TanStackHydrationApp({ options, incomingProps, 
 // eslint-disable-next-line @typescript-eslint/no-unused-vars -- Required by TanStackHydrationAppProps interface.
-railsContext: _railsContext, RouterProvider, RouterClient, createBrowserHistory, }) {
-    // eslint-disable-next-line no-underscore-dangle -- Internal hydration payload key injected by server-side render.
+railsContext: _railsContext, RouterProvider, createBrowserHistory, }) {
     const dehydratedState = incomingProps.__tanstackRouterDehydratedState;
-    const ssrRouter = dehydratedState?.ssrRouter;
     const hasSsrPayload = dehydratedState != null;
-    const hasSsrRouter = ssrRouter !== undefined;
     const hasDehydratedRouter = dehydratedState?.dehydratedRouter !== undefined && dehydratedState.dehydratedRouter !== null;
     const routerRef = useRef(null);
-    // This only deduplicates the manual load within one mounted hydration instance.
-    // A full remount creates a fresh router and may legitimately issue another load.
     const didTriggerPostHydrationLoadRef = useRef(false);
-    const didInitializeSsrGlobalRef = useRef(false);
+    const didSetSsrFlagRef = useRef(false);
+    const routeChunkPreloadPromiseRef = useRef(null);
+    const routeChunkPreloadSettledRef = useRef(true);
+    const hydrationCallbackPromiseRef = useRef(null);
+    const didWarnPrivateInternalsRef = useRef(false);
+    const warnedMissingSsrMatchIdsRef = useRef(new Set());
+    const warnMissingSsrMatch = (match) => {
+        if (process.env.NODE_ENV !== 'development') {
+            return;
+        }
+        const routeId = typeof match.id === 'string' || typeof match.id === 'number' ? String(match.id) : '<unknown>';
+        if (warnedMissingSsrMatchIdsRef.current.has(routeId)) {
+            return;
+        }
+        warnedMissingSsrMatchIdsRef.current.add(routeId);
+        console.warn(`react-on-rails-pro/tanstack-router: No server match found for route "${routeId}". ` +
+            'Overriding match.status from "pending" to "success" to prevent hydration suspension.');
+    };
     if (routerRef.current === null) {
+        // Intentionally initialize the hydration router during render so the very
+        // first RouterProvider render sees SSR-injected matches and the temporary
+        // router.ssr flag. Moving this to an effect causes a first-render mismatch
+        // (the provider would render before hydration state is injected).
+        //
+        // Safety invariant: all mutations in this block target only the router
+        // instance created here and routerRef.current is assigned only after the
+        // block completes. If React discards this render (StrictMode/concurrency),
+        // the discarded router instance is dropped and a fresh instance is created
+        // and initialized on the next render.
         const router = options.createRouter();
         // Set browser history for client-side navigation
         const browserHistory = createBrowserHistory();
         router.update({ history: browserHistory });
-        // Hydrate router with dehydrated state from server.
-        if (hasSsrRouter) {
-            // RouterClient will hydrate the route matches from window.$_TSR.
-        }
-        else if (hasDehydratedRouter && typeof router.hydrate === 'function') {
-            router.hydrate(dehydratedState.dehydratedRouter);
-        }
-        else if (hasDehydratedRouter) {
-            throw new Error('react-on-rails-pro/tanstack-router: Cannot hydrate SSR payload. ' +
-                'router.hydrate() is required but not available on your TanStack Router version. ' +
-                'Ensure @tanstack/react-router >=1.139.0 <2.0.0 is installed and provides router.hydrate().');
-        }
-        // Keep SSR mode enabled on hydration paths so Transitioner does not run
-        // a client-only initial load before hydration settles.
-        if (!hasSsrRouter && hasSsrPayload && router.ssr !== true) {
-            router.ssr = true;
+        // Only apply SSR hydration when a server payload exists.
+        // Client-only renders (prerender: false) must not set router.ssr or
+        // inject matches — the Transitioner handles initial loading for those.
+        if (hasSsrPayload) {
+            if (process.env.NODE_ENV === 'development' && !didWarnPrivateInternalsRef.current) {
+                didWarnPrivateInternalsRef.current = true;
+                console.warn('react-on-rails-pro/tanstack-router: Hydration uses TanStack Router private internals ' +
+                    '(matchRoutes, __store, loadRouteChunk, looseRoutesById). Keep @tanstack/react-router ' +
+                    'within the supported range (>=1.139.0 <2.0.0) and run integration tests when upgrading.');
+            }
+            // Validate internal APIs before using them.
+            if (typeof router.matchRoutes !== 'function' || !router.__store?.setState) {
+                throw new Error('react-on-rails-pro/tanstack-router: router.matchRoutes() and router.__store are required ' +
+                    'but not available. Ensure @tanstack/react-router >=1.139.0 <2.0.0 is installed.');
+            }
+            const hydrationRouter = router;
+            // Synchronously inject route matches to match server-rendered output.
+            // The server fully loads routes (via router.load()) before rendering, so
+            // all matches are resolved. We replicate this on the client so the initial
+            // render produces the same component tree as the server HTML.
+            //
+            // When ssrRouter match data is available (from serverRenderTanStackAppAsync),
+            // we apply loaderData, beforeLoadContext, status, etc. from the server payload
+            // so routes that render from loader results can hydrate correctly.
+            // Otherwise we override 'pending' to 'success' to prevent MatchInner from
+            // throwing loadPromise (which would cause Suspense suspension).
+            const rawMatches = hydrationRouter.matchRoutes(hydrationRouter.state.location);
+            routeChunkPreloadPromiseRef.current = preloadMatchedRouteChunks(router, rawMatches);
+            if (routeChunkPreloadPromiseRef.current) {
+                routeChunkPreloadSettledRef.current = false;
+                void routeChunkPreloadPromiseRef.current.finally(() => {
+                    routeChunkPreloadSettledRef.current = true;
+                });
+            }
+            else {
+                routeChunkPreloadSettledRef.current = true;
+            }
+            const ssrMatches = dehydratedState?.ssrRouter?.matches;
+            const matches = ssrMatches?.length
+                ? applyDehydratedMatchData(rawMatches, ssrMatches, warnMissingSsrMatch)
+                : rawMatches.map((match) => {
+                    const m = match;
+                    if (m.status === 'pending') {
+                        warnMissingSsrMatch(m);
+                        return { ...m, status: 'success' };
+                    }
+                    return m;
+                });
+            // Render-phase store injection is required for hydration parity: this
+            // must happen before the first RouterProvider render.
+            hydrationRouter.__store.setState((s) => ({
+                ...s,
+                status: 'idle',
+                resolvedLocation: s.location,
+                matches,
+            }));
+            // Set SSR flag so the Transitioner skips its initial router.load() call,
+            // preventing a state update during hydration that would cause a mismatch.
+            // The shape matches TanStack Router's internal $_TSR hydration contract
+            // (the Transitioner only checks truthiness).
+            // Preserve user-set values from createRouter() (e.g. TanStack Start).
+            if (!router.ssr) {
+                router.ssr = { manifest: undefined };
+                didSetSsrFlagRef.current = true;
+            }
+            try {
+                // Run user-defined hydration callback for custom dehydratedData
+                // (for example external query/cache payloads), matching TanStack
+                // Router's ssr-client behavior.
+                if (typeof router.options?.hydrate === 'function') {
+                    const hydrationResult = router.options.hydrate(extractDehydratedData(dehydratedState?.dehydratedRouter));
+                    // Let async hydration failures reject so we do not continue into
+                    // router.load() with partially hydrated client state.
+                    hydrationCallbackPromiseRef.current = Promise.resolve(hydrationResult).then(() => undefined);
+                }
+                // Backward-compatibility hook: if user router exposes router.hydrate(),
+                // invoke it with the full dehydrated router payload.
+                if (hasDehydratedRouter && typeof router.hydrate === 'function') {
+                    router.hydrate(dehydratedState.dehydratedRouter);
+                }
+            }
+            catch (error) {
+                // If render-phase hydration throws, clear only the temporary SSR flag
+                // created by this module so retries are not blocked.
+                if (didSetSsrFlagRef.current) {
+                    router.ssr = undefined;
+                    didSetSsrFlagRef.current = false;
+                }
+                throw error;
+            }
         }
         routerRef.current = router;
     }
     const router = routerRef.current;
-    if (hasSsrRouter && typeof window !== 'undefined' && !didInitializeSsrGlobalRef.current) {
-        setTanStackSsrGlobal(ssrRouter);
-        didInitializeSsrGlobalRef.current = true;
-    }
     // After mount, trigger router.load() to enable client-side navigation.
     // The SSR flag prevented auto-loading, so we do it manually here.
     useEffect(() => {
-        if (!router) {
-            return undefined;
-        }
-        if (hasSsrRouter) {
-            return undefined;
-        }
-        // Only SSR hydration needs a manual load call.
-        // For client-only renders, Transitioner handles initial loading.
-        if (!hasSsrPayload) {
+        if (!router || !hasSsrPayload) {
             return undefined;
         }
         if (didTriggerPostHydrationLoadRef.current) {
@@ -84,38 +231,83 @@ railsContext: _railsContext, RouterProvider, RouterClient, createBrowserHistory,
         }
         didTriggerPostHydrationLoadRef.current = true;
         let cancelled = false;
-        // `cancelled` only suppresses logging for a discarded mount. The in-flight load still
-        // completes unless the router exposes a best-effort cancelLoad() hook.
-        router.load().catch((err) => {
+        const runPostHydrationLoad = async () => {
+            if (hydrationCallbackPromiseRef.current) {
+                await hydrationCallbackPromiseRef.current;
+                if (cancelled) {
+                    return;
+                }
+            }
+            if (routeChunkPreloadPromiseRef.current) {
+                await routeChunkPreloadPromiseRef.current;
+                if (cancelled) {
+                    return;
+                }
+            }
+            if (cancelled) {
+                return;
+            }
+            await router.load();
+        };
+        void runPostHydrationLoad()
+            .catch((err) => {
             if (!cancelled) {
                 console.error('react-on-rails-pro/tanstack-router: Error loading routes after hydration:', err);
             }
+        })
+            .finally(() => {
+            // Always clear temporary router.ssr set by this module, regardless of
+            // cancellation state. In React 18 StrictMode, the effect cleanup sets
+            // cancelled=true and didTriggerPostHydrationLoadRef prevents re-trigger
+            // on re-mount — if we skip cleanup here the SSR flag stays set
+            // permanently, blocking the Transitioner from ever calling router.load().
+            // The didSetSsrFlagRef guard ensures we only clear values this module
+            // created, preserving user-provided router.ssr from createRouter().
+            if (didSetSsrFlagRef.current) {
+                router.ssr = undefined;
+                didSetSsrFlagRef.current = false;
+            }
         });
         return () => {
             cancelled = true;
+            if (didSetSsrFlagRef.current) {
+                router.ssr = undefined;
+                didSetSsrFlagRef.current = false;
+            }
             const cancellableRouter = router;
             if (typeof cancellableRouter.cancelLoad === 'function') {
                 cancellableRouter.cancelLoad();
             }
         };
-    }, [hasSsrPayload, hasSsrRouter, router]);
-    const RouterRoot = hasSsrRouter && typeof window !== 'undefined' && RouterClient ? RouterClient : RouterProvider;
-    let app = createElement(RouterRoot, { router });
+    }, [hasSsrPayload, router]);
+    // Always use RouterProvider directly — matching the server-rendered tree.
+    // RouterClient is NOT used because it wraps RouterProvider in <Await> which
+    // introduces a Suspense boundary that doesn't exist in the server HTML,
+    // causing React hydration mismatch errors.
+    //
+    // RouteChunkPreloadGate blocks re-renders until matched lazy chunks finish
+    // preloading (when preload support is available). During the initial SSR
+    // hydration render, the gate is skipped to match the server-rendered tree
+    // and avoid a hydration mismatch. After the post-mount effect runs
+    // (didTriggerPostHydrationLoadRef becomes true), the gate activates normally.
+    let app = createElement(Suspense, { fallback: null }, createElement(RouteChunkPreloadGate, {
+        preloadPromise: routeChunkPreloadPromiseRef.current,
+        preloadSettledRef: routeChunkPreloadSettledRef,
+        isHydrating: hasSsrPayload && !didTriggerPostHydrationLoadRef.current,
+    }, createElement(RouterProvider, { router })));
     if (options.AppWrapper) {
         const wrapperProps = { ...incomingProps };
-        // eslint-disable-next-line no-underscore-dangle -- Internal hydration payload key should not reach user AppWrapper props.
         delete wrapperProps.__tanstackRouterDehydratedState;
         app = createElement(options.AppWrapper, wrapperProps, app);
     }
     return app;
 }
-export function clientHydrateTanStackApp(options, props, railsContext, RouterProvider, RouterClient, createBrowserHistory) {
+export function clientHydrateTanStackApp(options, props, railsContext, RouterProvider, createBrowserHistory) {
     return createElement(TanStackHydrationApp, {
         options,
         incomingProps: props,
         railsContext,
         RouterProvider,
-        RouterClient,
         createBrowserHistory,
     });
 }

package/lib/tanstack-router/index.d.ts

@@ -43,9 +43,10 @@ interface TanStackRouterDeps {
         router: TanStackRouter;
     }>;
     /**
-     * Optional RouterClient component from @tanstack/react-router/ssr/client.
-     * When provided, it enables TanStack Router's SSR client hydration path for
-     * router versions that do not expose router.dehydrate()/router.hydrate().
+     * @deprecated No longer used for hydration. RouterProvider is always used
+     * directly to match the server-rendered tree. RouterClient caused hydration
+     * mismatches because it wraps RouterProvider in <Await> which suspends.
+     * Kept for backward compatibility only.
      */
     RouterClient?: React.ComponentType<{
         router: TanStackRouter;

package/lib/tanstack-router/index.js

@@ -48,6 +48,7 @@ export { serverRenderTanStackAppAsync } from "./serverRender.js";
  */
 export function createTanStackRouterRenderFunction(options, deps) {
     const { RouterProvider, RouterClient, createMemoryHistory, createBrowserHistory } = deps;
+    let didWarnRouterClientDeprecated = false;
     const renderFn = (props = {}, railsContext) => {
         if (!railsContext) {
             throw new Error('react-on-rails-pro/tanstack-router: railsContext is required. ' +
@@ -66,7 +67,13 @@ export function createTanStackRouterRenderFunction(options, deps) {
         // This intentionally creates a fresh closure per renderFn call so the client component
         // captures the current railsContext and TanStack Router dependencies for that mount.
         return function TanStackRouterClientApp(clientProps = {}) {
-            return clientHydrateTanStackApp(options, clientProps, railsContext, RouterProvider, RouterClient, createBrowserHistory);
+            if (RouterClient && !didWarnRouterClientDeprecated) {
+                didWarnRouterClientDeprecated = true;
+                console.warn('react-on-rails-pro/tanstack-router: The RouterClient parameter is deprecated and ignored. ' +
+                    'RouterProvider is now used directly to avoid SSR hydration mismatches. ' +
+                    'You can safely remove the RouterClient import from your createTanStackRouterRenderFunction call.');
+            }
+            return clientHydrateTanStackApp(options, clientProps, railsContext, RouterProvider, createBrowserHistory);
         };
     };
     // Mark as a render function so React on Rails executes it rather than treating it

package/lib/tanstack-router/serverRender.js

@@ -1,16 +1,5 @@
 import { createElement } from 'react';
 import { normalizeSearch } from "./utils.js";
-/**
- * Enables TanStack Router's internal SSR mode and verifies the flag is writable.
- */
-function enableRouterSsrMode(router) {
-    const routerWithSsrFlag = router;
-    routerWithSsrFlag.ssr = true;
-    if (!routerWithSsrFlag.ssr) {
-        throw new Error('react-on-rails-pro/tanstack-router: Expected router.ssr to accept a boolean flag. ' +
-            'Please check that your @tanstack/react-router version is compatible.');
-    }
-}
 /**
  * Builds a React element tree with RouterProvider and optional AppWrapper.
  */
@@ -80,12 +69,15 @@ export async function serverRenderTanStackAppAsync(options, props, railsContext,
     const memoryHistory = createMemoryHistory({ initialEntries: [url] });
     router.update({ history: memoryHistory });
     // Async path uses router.load() public API, so no private store access is needed.
+    // No router.ssr flag is set here: React effects (including Transitioner's auto-load)
+    // do not execute during server-side renderToString, and router.dehydrate() does not
+    // depend on router.ssr.
     await router.load();
-    // Ensure SSR output avoids client-only Suspense wrappers that can cause hydration mismatch.
-    enableRouterSsrMode(router);
     const dehydratedState = {
         url,
         dehydratedRouter: typeof router.dehydrate === 'function' ? router.dehydrate() : null,
+        // Keep ssrRouter payload for compatibility and to restore server match data
+        // before first client render.
         ssrRouter: buildSsrRouterState(router),
     };
     return {

package/lib/tanstack-router/types.d.ts

@@ -9,6 +9,12 @@ export interface TanStackRouter {
         history: TanStackHistory;
     }) => void;
     load: () => Promise<void>;
+    matchRoutes?: (location: unknown) => unknown[];
+    __store?: {
+        setState: (updater: (s: Record<string, unknown>) => Record<string, unknown>) => void;
+    };
+    looseRoutesById?: Record<string, unknown>;
+    loadRouteChunk?: (route: unknown) => Promise<unknown>;
     state: {
         status: string;
         location: {
@@ -23,8 +29,11 @@ export interface TanStackRouter {
     };
     dehydrate?: () => unknown;
     hydrate?: (data: unknown) => void;
-    ssr?: boolean | {
-        manifest: unknown;
+    options?: {
+        hydrate?: (dehydratedData: unknown) => Promise<unknown> | unknown;
+    };
+    ssr?: {
+        manifest?: unknown;
     };
 }
 export interface TanStackHistory {
@@ -93,7 +102,7 @@ export interface DehydratedRouterState {
     url: string;
     /** Router dehydrated state from router.dehydrate() */
     dehydratedRouter: unknown;
-    /** TanStack Router SSR match payload used by RouterClient hydration */
+    /** Legacy TanStack SSR match payload used for compatibility and match-data restoration during hydration */
     ssrRouter?: TanStackSsrRouterState;
 }
 //# sourceMappingURL=types.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-on-rails-pro",
-  "version": "16.5.1",
+  "version": "16.6.0-rc.1",
   "description": "React on Rails Pro package with React Server Components support",
   "main": "lib/ReactOnRails.full.js",
   "type": "module",
@@ -47,7 +47,7 @@
     "./ServerComponentFetchError": "./lib/ServerComponentFetchError.js"
   },
   "dependencies": {
-    "react-on-rails": "16.5.1"
+    "react-on-rails": "16.6.0-rc.1"
   },
   "peerDependencies": {
     "react": ">= 16",