react-on-rails-pro 16.7.0-rc.2 → 16.7.0-rc.3

package/lib/tanstack-router/clientHydrate.js

@@ -1,6 +1,7 @@
 import * as React from 'react';
 /* eslint-disable import/prefer-default-export, no-underscore-dangle */
 const { createElement, useEffect, useRef } = React;
+const sharedHydrationInitStates = new WeakMap();
 function extractDehydratedData(dehydratedRouter) {
     if (!dehydratedRouter || typeof dehydratedRouter !== 'object') {
         return undefined;
@@ -33,6 +34,77 @@ function preloadMatchedRouteChunks(router, matches) {
         console.error('react-on-rails-pro/tanstack-router: Error preloading matched route chunks:', error);
     });
 }
+// Each guard repeats the matchRoutes check so TypeScript narrows correctly
+// when either hydration path is used independently.
+function hasLegacyHydrationStore(router) {
+    return typeof router.matchRoutes === 'function' && typeof router.__store?.setState === 'function';
+}
+function hasStoresHydrationApi(router) {
+    const { stores } = router;
+    return (typeof router.matchRoutes === 'function' &&
+        typeof stores?.status?.set === 'function' &&
+        typeof stores?.resolvedLocation?.set === 'function' &&
+        typeof stores?.setMatches === 'function');
+}
+function hasHydrationInternals(router) {
+    // The ordering here is load-bearing: legacy `__store` wins when both APIs
+    // are present, so routers exposing both during a TanStack upgrade keep
+    // taking the well-tested __store.setState path until the legacy API is
+    // removed. applyHydrationMatches mirrors this preference at the call site.
+    return hasLegacyHydrationStore(router) || hasStoresHydrationApi(router);
+}
+function throwMissingHydrationInternals() {
+    throw new Error('react-on-rails-pro/tanstack-router: router.matchRoutes() and router.__store.setState() or ' +
+        'router.stores.setMatches() are required but not available. Ensure @tanstack/react-router ' +
+        '>=1.139.0 <2.0.0 is installed; older 1.x routers expose __store.setState(), while newer ' +
+        '1.x routers expose stores.setMatches().');
+}
+/**
+ * Apply server-rendered route matches to the router's internal hydration state.
+ *
+ * Precondition: callers must validate the router with `hasHydrationInternals(router)`
+ * before invoking this; the union parameter type encodes that contract so TypeScript
+ * enforces it at the call site.
+ */
+function applyHydrationMatches(router, matches) {
+    if (hasLegacyHydrationStore(router)) {
+        router.__store.setState((s) => ({
+            ...s,
+            status: 'idle',
+            resolvedLocation: s.location,
+            matches,
+        }));
+        return;
+    }
+    // Legacy path didn't match, so the union narrows to TanStackRouterStoresHydrationInternals.
+    const applyStoresUpdate = () => {
+        router.stores.status.set('idle');
+        // The freshly-created router has not rendered or awaited work yet, so
+        // router.state.location matches the legacy __store updater's s.location.
+        // Invariant: router.update({ history }) does not mutate state.location synchronously;
+        // if that ever changes, this path and the legacy __store path diverge.
+        router.stores.resolvedLocation.set(router.state.location);
+        router.stores.setMatches(matches);
+    };
+    if (typeof router.batch === 'function') {
+        router.batch(applyStoresUpdate);
+        return;
+    }
+    // Without router.batch, the stores API cannot make these writes atomic like
+    // legacy __store.setState(); this render-phase update runs before
+    // RouterProvider subscribes, so hydration still starts from the final state.
+    // NOTE: correctness here depends on RouterProvider not subscribing to stores
+    // during synchronous render. Re-validate this path on TanStack Router major upgrades.
+    // In practice router.batch is present in the supported range (>=1.139.0), so this
+    // branch is a defensive belt-and-suspenders fallback rather than an expected runtime
+    // path — the dev warning below should not fire on a correctly pinned dependency.
+    if (process.env.NODE_ENV !== 'production') {
+        console.warn('react-on-rails-pro/tanstack-router: router.batch is unavailable; stores hydration writes ' +
+            'are not atomic. Upgrade @tanstack/react-router to a version that exposes router.batch ' +
+            'for safer hydration.');
+    }
+    applyStoresUpdate();
+}
 /**
  * Converts a dehydrated match ID (using \0 separator) back to the standard
  * route ID format (using / separator) used by matchRoutes().
@@ -74,9 +146,7 @@ function applyDehydratedMatchData(matches, ssrMatches, onMissingSsrMatch) {
         return m;
     });
 }
-function TanStackHydrationApp({ options, incomingProps, 
-// eslint-disable-next-line @typescript-eslint/no-unused-vars -- Required by TanStackHydrationAppProps interface.
-railsContext: _railsContext, RouterProvider, createBrowserHistory, }) {
+function TanStackHydrationApp({ options, incomingProps, railsContext: _railsContext, RouterProvider, createBrowserHistory, }) {
     const dehydratedState = incomingProps.__tanstackRouterDehydratedState;
     const hasSsrPayload = dehydratedState != null;
     const hasDehydratedRouter = dehydratedState?.dehydratedRouter !== undefined && dehydratedState.dehydratedRouter !== null;
@@ -113,91 +183,122 @@ railsContext: _railsContext, RouterProvider, createBrowserHistory, }) {
         // 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.
+        //
+        // Cross-mount invariant: sharedHydrationInitStates dedupes per-router
+        // side effects (loadRouteChunk, __store.setState, options.hydrate) across
+        // React 18 StrictMode's double-render-with-fresh-hooks behavior — which
+        // resets useRef on each pass, so this `routerRef.current === null` guard
+        // alone fires twice when options.createRouter returns the same instance.
         const router = options.createRouter();
-        // Set browser history for client-side navigation
-        const browserHistory = createBrowserHistory();
-        router.update({ history: browserHistory });
-        // 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);
-            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;
+        const cachedInit = sharedHydrationInitStates.get(router);
+        if (cachedInit) {
+            // Same router instance was already initialized by a discarded render
+            // (or prior mount). Reattach the pending preload/hydrate promises to
+            // this mount's refs so the post-hydration effect awaits the original
+            // work; restore didSetSsrFlag so cleanup correctly clears router.ssr.
+            routeChunkPreloadPromiseRef.current = cachedInit.routeChunkPreloadPromise;
+            hydrationCallbackPromiseRef.current = cachedInit.hydrationCallbackPromise;
+            didSetSsrFlagRef.current = cachedInit.didSetSsrFlag;
+        }
+        else {
+            // Set browser history for client-side navigation
+            const browserHistory = createBrowserHistory();
+            // Snapshot state.location before router.update so the dev-mode assertion
+            // below can verify the equivalence the stores hydration path relies on
+            // (see applyHydrationMatches: router.stores.resolvedLocation.set
+            // assumes router.update does not mutate state.location synchronously).
+            const locationBeforeUpdate = process.env.NODE_ENV !== 'production' ? router.state.location : undefined;
+            router.update({ history: browserHistory });
+            if (process.env.NODE_ENV !== 'production' &&
+                hasStoresHydrationApi(router) &&
+                // Identity check only: an in-place mutation of the same location object
+                // would slip past this guard. The dev warning is best-effort.
+                router.state.location !== locationBeforeUpdate) {
+                console.warn('react-on-rails-pro/tanstack-router: router.update({ history }) mutated router.state.location ' +
+                    'synchronously. The stores hydration path writes router.state.location to ' +
+                    'router.stores.resolvedLocation, which would diverge from the legacy __store path that ' +
+                    'snapshots the pre-update s.location. File an issue with your @tanstack/react-router version.');
             }
-            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);
+            // 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/stores, loadRouteChunk, looseRoutesById). Keep @tanstack/react-router ' +
+                        'within the supported range (>=1.139.0 <2.0.0) and run integration tests when upgrading.');
                 }
-                // 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);
+                // Validate internal APIs before using them.
+                if (!hasHydrationInternals(router)) {
+                    throwMissingHydrationInternals();
                 }
-            }
-            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;
+                // 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 = router.matchRoutes(router.state.location);
+                routeChunkPreloadPromiseRef.current = preloadMatchedRouteChunks(router, rawMatches);
+                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.
+                applyHydrationMatches(router, 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;
                 }
-                throw error;
             }
+            sharedHydrationInitStates.set(router, {
+                routeChunkPreloadPromise: routeChunkPreloadPromiseRef.current,
+                hydrationCallbackPromise: hydrationCallbackPromiseRef.current,
+                didSetSsrFlag: didSetSsrFlagRef.current,
+            });
         }
         routerRef.current = router;
     }
@@ -267,6 +368,14 @@ railsContext: _railsContext, RouterProvider, createBrowserHistory, }) {
             if (latestEffectRunIdRef.current === effectRunId && didSetSsrFlagRef.current) {
                 router.ssr = undefined;
                 didSetSsrFlagRef.current = false;
+                // Keep sharedHydrationInitStates in sync so a later mount of the
+                // same cached router doesn't restore a stale didSetSsrFlag=true and
+                // trigger the dev sanity-check warning below on a router whose ssr
+                // flag was already cleared correctly.
+                const cached = sharedHydrationInitStates.get(router);
+                if (cached) {
+                    cached.didSetSsrFlag = false;
+                }
             }
         });
         return () => {
@@ -278,6 +387,10 @@ railsContext: _railsContext, RouterProvider, createBrowserHistory, }) {
                 if (latestEffectRunIdRef.current === effectRunId && didSetSsrFlagRef.current) {
                     router.ssr = undefined;
                     didSetSsrFlagRef.current = false;
+                    const cached = sharedHydrationInitStates.get(router);
+                    if (cached) {
+                        cached.didSetSsrFlag = false;
+                    }
                 }
             });
             const cancellableRouter = router;

package/lib/tanstack-router/serverRender.js

@@ -2,6 +2,14 @@ import { createElement } from 'react';
 import { normalizeSearch } from "./utils.js";
 /**
  * Builds a React element tree with RouterProvider and optional AppWrapper.
+ *
+ * No <Suspense> boundary is inserted here. The client hydration tree renders
+ * RouterProvider directly without a wrapping <Suspense>, so introducing one
+ * on the server would emit `<!--$-->`/`<!--/$-->` markers (React 19's
+ * `renderToString` emits these for every Suspense boundary, even
+ * non-suspended ones) and break hydration parity. If RouterProvider suspends
+ * during SSR, React's own `renderToString` throws synchronously — that is
+ * already a loud failure mode and does not need a custom guard.
  */
 function buildAppElement(router, RouterProvider, AppWrapper, wrapperProps) {
     let app = createElement(RouterProvider, { router });

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

@@ -1,4 +1,15 @@
 import type { ComponentType, ReactNode } from 'react';
+/**
+ * Shape of a writable TanStack store atom. Used by the modern `router.stores`
+ * API exposed on TanStackRouter below.
+ *
+ * `set` is declared as an overload to match the upstream `@tanstack/store`
+ * `Atom.set` signature (which is an overload, not a union parameter); a union
+ * parameter would not be structurally assignable from the upstream type.
+ */
+export type TanStackRouterWritableStore<TValue = unknown> = {
+    set: ((value: TValue) => void) & ((updater: (prev: TValue) => TValue) => void);
+};
 /**
  * Minimal type for TanStack Router instance.
  * We use this instead of importing @tanstack/react-router directly
@@ -13,6 +24,12 @@ export interface TanStackRouter {
     __store?: {
         setState: (updater: (s: Record<string, unknown>) => Record<string, unknown>) => void;
     };
+    stores?: {
+        status: TanStackRouterWritableStore<'idle' | 'pending'>;
+        resolvedLocation: TanStackRouterWritableStore<TanStackRouter['state']['location']>;
+        setMatches: (nextMatches: unknown[]) => void;
+    };
+    batch?: (callback: () => void) => void;
     looseRoutesById?: Record<string, unknown>;
     loadRouteChunk?: (route: unknown) => Promise<unknown>;
     state: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-on-rails-pro",
-  "version": "16.7.0-rc.2",
+  "version": "16.7.0-rc.3",
   "description": "React on Rails Pro package with React Server Components support",
   "main": "lib/ReactOnRails.full.js",
   "type": "module",
@@ -48,7 +48,7 @@
     "./ServerComponentFetchError": "./lib/ServerComponentFetchError.js"
   },
   "dependencies": {
-    "react-on-rails": "16.7.0-rc.2"
+    "react-on-rails": "16.7.0-rc.3"
   },
   "peerDependencies": {
     "react": ">= 16",
@@ -74,6 +74,8 @@
   },
   "homepage": "https://reactonrails.com/docs/pro/",
   "devDependencies": {
+    "@tanstack/react-router": "1.163.3",
+    "@tanstack/store": "0.9.1",
     "@types/mock-fs": "^4.13.4",
     "mock-fs": "^5.5.0",
     "react": "^19.0.3",