@rangojs/router 0.22.1 → 0.23.0

package/src/types/segments.ts

@@ -172,6 +172,15 @@ export interface ResolvedSegment {
    */
   awaitBeforeFlush?: true;
   parallelLoading?: ReactNode; // For parallel-owned loaders: the parallel's loading fallback
+  /**
+   * A prefetch skipped this segment's work (`prefetch: false`): a loader
+   * carries no `loaderData`, a layout/route/parallel unit carries
+   * `component: null` and its fallback. The browser shows the fallback and
+   * sends a fill request for it (browser/partial-update.ts); until that
+   * lands the segment is a placeholder, never a held copy. Only ever on a
+   * prefetch response: see docs/design/prefetch-false.md.
+   */
+  deferred?: true;
   // Intercept loader fields (for streaming loader data in parallel segments)
   loaderDataPromise?: Promise<any[]> | any[]; // Loader data promise or resolved array
   loaderIds?: string[]; // IDs ($$id) of loaders for this segment
@@ -253,10 +262,12 @@ export interface MatchResult {
   /**
    * Every segment id whose handler actually ran on the server this request,
    * including ones with `component === null` that get filtered out of
-   * `segments`/`diff` to avoid wasted bytes. Drives the client's handle-
-   * cleanup pass — a slot that re-resolves and pushes nothing must clear
-   * its previous handle bucket, but `diff` doesn't carry it because the
-   * segment payload doesn't either. A superset of `diff`.
+   * `segments`/`diff` to avoid wasted bytes, and every loader segment that
+   * ran. Drives the client's handle merge (handles/pushed-by.ts) — a slot
+   * that re-resolves and pushes nothing must clear its previous handle
+   * bucket, but `diff` doesn't carry it because the segment payload doesn't
+   * either; a loader that ran replaces its pushes, one that did not keeps
+   * them. A superset of `diff`.
    */
   resolvedIds: string[];
   /**
@@ -304,3 +315,14 @@ export interface MatchResult {
     params: Record<string, string>;
   }>;
 }
+
+/**
+ * A `prefetch: false` placeholder (ResolvedSegment.deferred): a segment whose
+ * work a prefetch skipped, waiting for its fill. Never a held copy of the
+ * segment it stands for.
+ */
+export function isPlaceholder(
+  segment: Pick<ResolvedSegment, "deferred">,
+): boolean {
+  return segment.deferred === true;
+}

package/src/urls/path-helper-types.ts

@@ -30,7 +30,6 @@ import type {
   InterceptUseItem,
   LoaderUseItem,
   TypedCacheItem,
-  TransitionItem,
   TypedTransitionItem,
   TypedRouteItem,
   TypedIncludeItem,
@@ -362,6 +361,12 @@ export type PathHelpers<TEnv> = {
    * flag BAKES: the loader executes at shell capture and its settled return
    * freezes into the shell (nested promises stay live holes) — the pre-flush
    * promise applied to the prelude.
+   *
+   * Pass `{ prefetch: false }` to keep the loader out of prefetches: a
+   * prefetch skips it and the click that adopts the prefetch fetches it in
+   * one follow-up request (see {@link LoaderOptions}). Only on a segment the
+   * client does not have yet: a loader the client already holds runs in the
+   * prefetch when it revalidates.
    */
   loader: <TData>(
     loaderDef: LoaderDefinition<TData>,
@@ -370,11 +375,25 @@ export type PathHelpers<TEnv> = {
   ) => LoaderItem;
 
   /**
-   * Attach a loading component to the current route/layout
+   * Attach a loading component to the current route/layout.
+   *
+   * `{ ssr: false }` skips the fallback on document requests. `{ prefetch:
+   * false }` keeps what the fallback covers out of prefetches, when this
+   * entry's segment is new to the client: the entry's handler, its loaders,
+   * its orphan layouts and parallel slots and, for a layout, every deeper
+   * entry. The click that adopts the prefetch shows the fallback and fetches
+   * them in one follow-up request, which reads cache() and "use cache" as
+   * any request does (a prefetch reads neither for skipped work). A segment
+   * the client already holds is never deferred: a prefetch renders it as
+   * usual when it revalidates, and what is below it follows its own flags.
+   * To keep a child out of prefetches while moving inside a section, flag
+   * the child's own loading(). An entry whose handler output is stored
+   * (cache(), ppr, Prerender/Static) is served as usual and only its loaders
+   * are skipped.
    */
   loading: (
     component: ReactNode | (() => ReactNode),
-    options?: { ssr?: boolean },
+    options?: { ssr?: boolean; prefetch?: boolean },
   ) => LoadingItem;
 
   /**
@@ -422,8 +441,11 @@ export type PathHelpers<TEnv> = {
    * the browser (never on the server); see TransitionWhenFn.
    */
   transition: {
-    (): TransitionItem;
-    (config: TransitionConfig): TransitionItem;
+    // Typed {} phantoms, not bare TransitionItem: a phantom-less item matches
+    // `TypedTransitionItem<infer R>` with R inferred as Record<string, any>,
+    // which disables route-name checking for the sibling map.
+    (): TypedTransitionItem<{}, {}>;
+    (config: TransitionConfig): TypedTransitionItem<{}, {}>;
     <const TChildren extends readonly (AllUseItems | readonly AllUseItems[])[]>(
       children: () => TChildren,
     ): TypedTransitionItem<

package/src/urls/type-extraction.ts

@@ -12,6 +12,11 @@ import type { LocalOnlyInclude, UnnamedRoute } from "./pattern-types.js";
 // Route Type Extraction Utilities
 // ============================================================================
 
+/** Drops string index signatures, keeping literal and template keys. */
+type StripStringIndex<T> = {
+  [K in keyof T as string extends K ? never : K]: T[K];
+};
+
 /**
  * Prefix route names with a given prefix (e.g., "blog" + "post" = "blog.post")
  *
@@ -117,15 +122,21 @@ type ExtractRoutesFromItem<T> =
           : TUrlPrefix extends string
             ? PrefixPatterns<TRoutes, TUrlPrefix>
             : TRoutes
-      : // TypedLayoutItem: extract child routes from phantom type
+      : // Phantom-less items (global transition/cache/layout, factories typed
+        // as a use item) match the Typed* shapes with the child map inferred
+        // as the Record<string, any> constraint; the string index signature
+        // turns route-name checking off for the whole map. Strip only the
+        // index and keep literal keys, so a loosely typed include() beside
+        // named routes still contributes those names.
+        // TypedLayoutItem: extract child routes from phantom type
         T extends TypedLayoutItem<infer TChildRoutes>
-        ? TChildRoutes
+        ? StripStringIndex<TChildRoutes>
         : // TypedCacheItem: extract child routes from phantom type
           T extends TypedCacheItem<infer TChildRoutes>
-          ? TChildRoutes
+          ? StripStringIndex<TChildRoutes>
           : // TypedTransitionItem: extract child routes from phantom type
             T extends TypedTransitionItem<infer TChildRoutes>
-            ? TChildRoutes
+            ? StripStringIndex<TChildRoutes>
             : // Fallback (won't extract routes)
               {};
 
@@ -206,16 +217,25 @@ type ExtractResponsesFromItem<T> =
             ? TResponses
             : {}
       : T extends TypedLayoutItem<any, infer TChildResponses>
-        ? TChildResponses extends Record<string, unknown>
-          ? TChildResponses
+        ? StripStringIndex<TChildResponses> extends infer R extends Record<
+            string,
+            unknown
+          >
+          ? R
           : {}
         : T extends TypedCacheItem<any, infer TChildResponses>
-          ? TChildResponses extends Record<string, unknown>
-            ? TChildResponses
+          ? StripStringIndex<TChildResponses> extends infer R extends Record<
+              string,
+              unknown
+            >
+            ? R
             : {}
           : T extends TypedTransitionItem<any, infer TChildResponses>
-            ? TChildResponses extends Record<string, unknown>
-              ? TChildResponses
+            ? StripStringIndex<TChildResponses> extends infer R extends Record<
+                string,
+                unknown
+              >
+              ? R
               : {}
             : {};
 

package/src/use-loader.tsx

@@ -20,6 +20,7 @@ import {
   type LoaderStore,
 } from "./loader-store.js";
 import { NavigationStoreContext } from "./browser/react/context.js";
+import { Defer, readDefer } from "./browser/defer.js";
 import { decodeLoaderEntry } from "./decode-loader-results.js";
 import { warnAwaitedSsrSuspension } from "./ssr-suspension-warning.js";
 import { SETTLED_THENABLE } from "./thenable-status.js";
@@ -51,12 +52,14 @@ const NOT_FOUND = Symbol("not-found");
  * available value from a still-streaming per-loader promise. A pending stream
  * is `use()`d at the read site (implicit suspension); the promise identity is
  * stable per commit (it comes from the provider's memoized context value /
- * element props), which use() requires across replays.
+ * element props), which use() requires across replays. A `prefetch: false`
+ * hole is a Defer (browser/defer.ts), read by its rule: every reader of the
+ * loader reads the one defer.
  */
 type LoaderLookup =
   | typeof NOT_FOUND
   | { value: unknown }
-  | { stream: Promise<unknown> };
+  | { stream: Promise<unknown> | Defer<unknown> };
 
 function lookupLoaderStreams(
   loaderStreams: Record<string, unknown> | undefined,
@@ -64,9 +67,9 @@ function lookupLoaderStreams(
 ): LoaderLookup {
   if (!loaderStreams || !(loaderId in loaderStreams)) return NOT_FOUND;
   const entry = loaderStreams[loaderId];
-  // Within the loaderStreams channel a Promise always means "still streaming";
-  // settled entries are undecoded result values, never promises.
-  return entry instanceof Promise
+  // Within the loaderStreams channel a Promise or a Defer always means "still
+  // streaming"; settled entries are undecoded result values, never promises.
+  return entry instanceof Promise || entry instanceof Defer
     ? { stream: entry }
     : { value: decodeLoaderEntry(entry) };
 }
@@ -163,7 +166,7 @@ function useLoaderInternal<T>(
   const walk = useMemo((): {
     contextData: T | undefined;
     hasContextData: boolean;
-    pendingStream?: Promise<unknown>;
+    pendingStream?: Promise<unknown> | Defer<unknown>;
     /** { ssr: false } loader ids seen on the chain up to (and including) the
      *  level that owned the read — input for the dev SSR suspension warning. */
     awaitedLoaderIds?: string[];
@@ -217,18 +220,20 @@ function useLoaderInternal<T>(
   // every COMPLETED render.
   const { hasContextData } = walk;
   let contextData = walk.contextData;
+  const stream = walk.pendingStream;
   // Dev only (suspense-audit.ts): the stream this reader is handed. The test
   // is a build-time constant, so the hook is called on every render or never.
   if (process.env.NODE_ENV !== "production" && INTERNAL_RANGO_SUSPENSE_AUDIT) {
-    useReadAudit(loader.$$id, walk.pendingStream);
-  }
-  if (walk.pendingStream) {
-    warnAwaitedSsrSuspension(
+    useReadAudit(
       loader.$$id,
-      walk.awaitedLoaderIds,
-      walk.pendingStream,
+      stream instanceof Defer ? stream.promise : stream,
     );
-    contextData = decodeLoaderEntry(use(walk.pendingStream)) as T;
+  }
+  if (stream instanceof Defer) {
+    contextData = decodeLoaderEntry(readDefer(stream)) as T;
+  } else if (stream) {
+    warnAwaitedSsrSuspension(loader.$$id, walk.awaitedLoaderIds, stream);
+    contextData = decodeLoaderEntry(use(stream)) as T;
   } else if (hasContextData) {
     // React logs a render that finishes without use() at a place whose reader
     // suspended in use() on mount, so every read with route context calls it.

package/src/vite/discovery/client-urls-projection.ts

@@ -2,10 +2,9 @@ import { existsSync, readFileSync } from "node:fs";
 import { isAbsolute, relative, resolve } from "node:path";
 import { normalizePath, parseAst } from "vite";
 import {
-  serializeClientUrlPatterns,
+  projectClientUrlsModule,
   type ClientUrlProjection,
 } from "../../client-urls/server-projection.js";
-import type { ClientUrlPatterns } from "../../client-urls/types.js";
 import {
   computeProductionHash,
   hashRefKey,
@@ -191,22 +190,19 @@ export async function refreshRecordedClientUrlProjections(
   }
 
   for (const [source, referenceIds] of referenceIdsBySource) {
-    let definition: unknown;
+    let module: Record<string, unknown>;
     try {
-      definition = (await ssrEnv.runner.import(source)).default;
+      module = await ssrEnv.runner.import(source);
     } catch {
       continue;
     }
-    if (
-      (typeof definition !== "object" && typeof definition !== "function") ||
-      definition === null ||
-      (definition as { __brand?: unknown }).__brand !== "client-urls"
-    ) {
+    let projection: ClientUrlProjection | undefined;
+    try {
+      projection = projectClientUrlsModule(module, { hoisted: true });
+    } catch {
       continue;
     }
-    const projection = serializeClientUrlPatterns(
-      definition as ClientUrlPatterns,
-    );
+    if (!projection) continue;
     debug?.(
       "pre-entry refresh %s -> [%s]",
       source,
@@ -288,21 +284,24 @@ export async function discoverClientUrlProjections(
         cause,
       );
     }
-    const definition = module.default;
-    if (
-      (typeof definition !== "object" && typeof definition !== "function") ||
-      definition === null ||
-      (definition as { __brand?: unknown }).__brand !== "client-urls"
-    ) {
+    let projection: ClientUrlProjection | undefined;
+    try {
+      projection = projectClientUrlsModule(module, { hoisted: true });
+    } catch (cause) {
+      throw projectionError(
+        referenceIds[0],
+        source,
+        cause instanceof Error ? cause.message : String(cause),
+        cause,
+      );
+    }
+    if (!projection) {
       throw projectionError(
         referenceIds[0],
         source,
         'the module default export must be created by clientUrls() and have __brand === "client-urls"',
       );
     }
-    const projection = serializeClientUrlPatterns(
-      definition as ClientUrlPatterns,
-    );
     for (const referenceId of referenceIds) {
       nextProjections.set(referenceId, projection);
     }

package/src/vite/discovery/discover-routers.ts

@@ -42,6 +42,30 @@ import {
 
 const debug = createRangoDebugger(NS.discovery);
 
+const SERVER_MODULE_ID = "@rangojs/router/server";
+
+/** Passes discoverRouters runs before giving up on a runner that keeps reloading. */
+const MAX_DISCOVERY_PASSES = 3;
+
+/** A discovery pass result: the runner reloaded mid-pass, redo it. */
+const RUNNER_RELOADED = Symbol("rango.discovery.runnerReloaded");
+
+/**
+ * Whether the runner's `@rangojs/router/server` is no longer `serverMod`. A
+ * Vite module runner full reload clears its evaluated-module cache, so the
+ * next import evaluates a fresh copy with empty module-level registries.
+ */
+async function runnerReloadedSince(
+  rscEnv: any,
+  serverMod: unknown,
+): Promise<boolean> {
+  try {
+    return (await rscEnv.runner.import(SERVER_MODULE_ID)) !== serverMod;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Import the user's entry via RSC runner, generate manifests for each
  * discovered router, build route tries, and optionally run prerender
@@ -49,25 +73,70 @@ const debug = createRangoDebugger(NS.discovery);
  *
  * Returns the imported `@rangojs/router/server` module so the caller
  * can access the RouterRegistry and manifest setters.
+ *
+ * A pass reads the router registry and installs clientUrls projections on ONE
+ * `@rangojs/router/server` instance, and checks that the runner still serves
+ * it. A runner full reload during the pass (a watched-file change at boot)
+ * splits the realm: a router module bound to the old instance registers there
+ * while urls modules re-evaluate against a fresh one, so include() looks its
+ * projection up in the fresh, empty Map ("include() could not resolve the
+ * server projection"). Such a pass is redone, at most
+ * MAX_DISCOVERY_PASSES times; the redo evaluates the entry in one realm.
  */
 export async function discoverRouters(
   state: DiscoveryState,
   rscEnv: any,
   ssrEnv?: any,
 ): Promise<any> {
-  if (!state.resolvedEntryPath) return;
-
-  // Import the router package FIRST (leaf module, no side effects on user
-  // code) so recorded clientUrls projections can be refreshed BEFORE the entry
-  // import: routers re-created by that import call `.routes(reference)` at
-  // module scope and materialize whatever projection is installed at that
-  // moment. On HMR re-discovery that must be the CURRENT module contents, not
-  // the previous pass's snapshot (see refreshRecordedClientUrlProjections).
-  const serverMod = await timed(
-    debug,
-    "inner: import @rangojs/router/server",
-    () => rscEnv.runner.import("@rangojs/router/server"),
-  );
+  const entryPath = state.resolvedEntryPath;
+  if (!entryPath) return;
+
+  for (let pass = 1; ; pass++) {
+    // Imported BEFORE the entry so recorded clientUrls projections can be
+    // refreshed first: routers re-created by the entry import materialize
+    // whatever projection is installed at that moment, which on HMR
+    // re-discovery must be the CURRENT module contents, not the previous
+    // pass's snapshot (see refreshRecordedClientUrlProjections). It is also
+    // the realm baseline of the reload checks; #637 read the registry off a
+    // pre-entry copy without one.
+    const serverMod = await timed(
+      debug,
+      "inner: import @rangojs/router/server",
+      () => rscEnv.runner.import(SERVER_MODULE_ID),
+    );
+    let result: unknown;
+    try {
+      result = await discoverRoutersPass(
+        state,
+        rscEnv,
+        ssrEnv,
+        entryPath,
+        serverMod,
+      );
+    } catch (error) {
+      if (!(await runnerReloadedSince(rscEnv, serverMod))) throw error;
+      result = RUNNER_RELOADED;
+    }
+    if (result !== RUNNER_RELOADED) return result;
+    if (pass === MAX_DISCOVERY_PASSES) {
+      throw new Error(
+        `[rango] Route discovery did not settle: the RSC module runner reloaded during ${MAX_DISCOVERY_PASSES} consecutive discovery passes.`,
+      );
+    }
+    debug?.(
+      "inner: module runner reloaded mid-pass, redoing discovery (pass %d)",
+      pass + 1,
+    );
+  }
+}
+
+async function discoverRoutersPass(
+  state: DiscoveryState,
+  rscEnv: any,
+  ssrEnv: any,
+  entryPath: string,
+  serverMod: any,
+): Promise<any> {
   await timed(debug, "inner: refresh recorded client URL projections", () =>
     refreshRecordedClientUrlProjections(state, ssrEnv, serverMod),
   );
@@ -76,10 +145,11 @@ export async function discoverRouters(
   // For node preset: this is the router file (createRouter() registers in RouterRegistry).
   // For cloudflare preset: this is the worker entry (which imports the router).
   await timed(debug, "inner: import entry", () =>
-    rscEnv.runner.import(state.resolvedEntryPath),
+    rscEnv.runner.import(entryPath),
   );
+  if (await runnerReloadedSince(rscEnv, serverMod)) return RUNNER_RELOADED;
 
-  let registry: Map<string, any> = serverMod.RouterRegistry;
+  const registry: Map<string, any> = serverMod.RouterRegistry;
 
   if (!registry || registry.size === 0) {
     // No RSC routers found directly. Check for host routers with lazy handlers
@@ -105,16 +175,10 @@ export async function discoverRouters(
           debug?.("caught error while resolving %s: %O", context, error);
         }
 
-        // Re-read RouterRegistry - sub-app createRouter() calls should have populated it
-        const freshServerMod = await rscEnv.runner.import(
-          "@rangojs/router/server",
-        );
-        const freshRegistry: Map<string, any> = freshServerMod.RouterRegistry;
-
-        if (freshRegistry && freshRegistry.size > 0) {
-          // Update references so the manifest generation below uses the fresh data
-          Object.assign(serverMod, freshServerMod);
-          registry = freshRegistry;
+        // Sub-app createRouter() calls populate the same live registry, unless
+        // a reload moved them to a fresh realm.
+        if (await runnerReloadedSince(rscEnv, serverMod)) {
+          return RUNNER_RELOADED;
         }
       }
     } catch (error) {
@@ -125,7 +189,7 @@ export async function discoverRouters(
 
     // If still no routers after host router resolution, fail
     if (!registry || registry.size === 0) {
-      throw new DiscoveryError(state.resolvedEntryPath, discoveryErrors);
+      throw new DiscoveryError(entryPath, discoveryErrors);
     }
   }
 
@@ -351,6 +415,10 @@ export async function discoverRouters(
     }
   }
 
+  // A reload after the entry import leaves this pass's projections and
+  // manifests on a realm the runner no longer serves.
+  if (await runnerReloadedSince(rscEnv, serverMod)) return RUNNER_RELOADED;
+
   // Commit all local state to the shared discovery state atomically.
   // This ensures a failed re-discovery (e.g. from a transient module
   // evaluation error) preserves the last known-good state.

package/src/vite/discovery/state.ts

@@ -196,14 +196,30 @@ export interface DiscoveryState {
   buildEnvDispose?: (() => Promise<void> | void) | null;
 
   /**
-   * Set when the most recent HMR re-discovery threw. Cleared on the next
-   * successful discovery. Surfaced via debug logs so we can detect "manifest
-   * frozen at last-good after error → user fix in non-route file → no
-   * rediscovery trigger" scenarios.
+   * Set when the most recent discovery threw: an HMR re-discovery, or the
+   * cold dev discovery on a main RSC runner. Cleared on the next successful
+   * discovery. While set, the route-file watcher treats any in-scan source
+   * change as a rediscovery trigger (recovery mode).
    */
   lastDiscoveryError?: { message: string; at: number } | null;
 }
 
+/**
+ * Whether the route-file watcher can re-run runtime discovery. A committed
+ * manifest is the usual precondition. A failed cold discovery commits none,
+ * so on a main RSC runner its recorded failure qualifies too; without that
+ * the dev server stayed broken until a restart.
+ */
+export function canRefreshRuntimeDiscovery(
+  state: Pick<DiscoveryState, "perRouterManifests" | "lastDiscoveryError">,
+  hasMainRunner: boolean,
+): boolean {
+  return (
+    state.perRouterManifests.length > 0 ||
+    (hasMainRunner && !!state.lastDiscoveryError)
+  );
+}
+
 export function createDiscoveryState(
   entryPath: string | undefined,
   opts: PluginOptions | undefined,

package/src/vite/discovery/virtual-module-codegen.ts

@@ -46,6 +46,22 @@ function devDiscoveryBootstrap(state: DiscoveryState): string[] {
   return [`globalThis.__RANGO_DEV_DISCOVERY_EPOCH = ${epoch};`];
 }
 
+/** Clear, then install every projection in state.clientUrlProjectionMap. */
+function clientUrlProjectionReplay(state: DiscoveryState): string[] {
+  // Sorted: the map fills in transform order, which varies between runs,
+  // and this module's bytes feed cache versions (build-versions.ts).
+  const projections = [...(state.clientUrlProjectionMap ?? [])].sort(
+    ([a], [b]) => compareStrings(a, b),
+  );
+  return [
+    `clearClientUrlProjections();`,
+    ...projections.map(
+      ([referenceId, projection]) =>
+        `setClientUrlProjection(${JSON.stringify(referenceId)}, ${jsonParseExpression(projection)});`,
+    ),
+  ];
+}
+
 /**
  * Generate the code for the main virtual:rsc-router/routes-manifest module.
  */
@@ -110,19 +126,7 @@ export function generateRoutesManifestModule(state: DiscoveryState): string {
       TRANSITION_WHEN_VALIDATION,
     ];
 
-    if (hasClientUrlModules) {
-      lines.push(`clearClientUrlProjections();`);
-      // Sorted: the map fills in transform order, which varies between runs,
-      // and this module's bytes feed cache versions (build-versions.ts).
-      const projections = [...(state.clientUrlProjectionMap ?? [])].sort(
-        ([a], [b]) => compareStrings(a, b),
-      );
-      for (const [referenceId, projection] of projections) {
-        lines.push(
-          `setClientUrlProjection(${JSON.stringify(referenceId)}, ${jsonParseExpression(projection)});`,
-        );
-      }
-    }
+    if (hasClientUrlModules) lines.push(...clientUrlProjectionReplay(state));
 
     if (varIdx > 0) {
       lines.push(
@@ -197,13 +201,14 @@ export function generateRoutesManifestModule(state: DiscoveryState): string {
     return lines.join("\n");
   }
 
+  // No manifest: discovery has not committed one (a failed cold pass commits
+  // nothing). The projections the failed pass computed still replay, so the
+  // realm serving requests can resolve include()s of clientUrls() modules.
   const lines: string[] = [
-    `import { ${hasClientUrlModules ? "clearClientUrlProjections, " : ""}enableTransitionWhenValidation } from "@rangojs/router/server";`,
+    `import { ${hasClientUrlModules ? "clearClientUrlProjections, setClientUrlProjection, " : ""}enableTransitionWhenValidation } from "@rangojs/router/server";`,
     TRANSITION_WHEN_VALIDATION,
   ];
-  if (hasClientUrlModules) {
-    lines.push(`clearClientUrlProjections();`);
-  }
+  if (hasClientUrlModules) lines.push(...clientUrlProjectionReplay(state));
   if (!state.isBuildMode) {
     const origin =
       state.devServerOrigin ||