@rangojs/router 0.0.0-experimental.97 → 0.0.0-experimental.98914650

package/src/rsc/handler.ts

@@ -8,7 +8,7 @@
  */
 
 import { createElement } from "react";
-import { RouteNotFoundError } from "../errors.js";
+import { isRouteNotFoundError } from "../errors.js";
 import { matchMiddleware, executeMiddleware } from "../router/middleware.js";
 import {
   runWithRequestContext,
@@ -31,6 +31,7 @@ import {
   interceptRedirectForPartial,
   buildRouteMiddlewareEntries,
 } from "./helpers.js";
+import { guardOutgoingRedirect } from "./redirect-guard.js";
 import { isWebSocketUpgradeResponse } from "../response-utils.js";
 import {
   handleResponseRoute,
@@ -57,6 +58,7 @@ import {
   getRouterTrie,
 } from "../route-map-builder.js";
 import type { HandlerContext } from "./handler-context.js";
+import type { CacheErrorCategory } from "../cache/cache-error.js";
 import type { SegmentCacheStore } from "../cache/types.js";
 import { buildRouterTrieFromUrlpatterns } from "./manifest-init.js";
 import { handleProgressiveEnhancement } from "./progressive-enhancement.js";
@@ -66,7 +68,10 @@ import {
   type ActionContinuation,
 } from "./server-action.js";
 import { handleLoaderFetch } from "./loader-fetch.js";
-import { checkRequestOrigin, type OriginCheckPhase } from "./origin-guard.js";
+import {
+  checkRequestOrigin,
+  ORIGIN_CHECK_PHASE_BY_MODE,
+} from "./origin-guard.js";
 import { handleRscRendering } from "./rsc-rendering.js";
 import {
   withTimeout,
@@ -83,6 +88,7 @@ import {
   startSSRSetup,
   getSSRSetup,
   mayNeedSSR,
+  isRscRequest,
   SSR_SETUP_VAR,
 } from "./ssr-setup.js";
 import {
@@ -124,12 +130,35 @@ import {
  * });
  * ```
  */
+
+/**
+ * Response that tells the client to do a full document navigation. Shared by
+ * the terminal reload plans (version-mismatch and app-switch): an empty 200
+ * carrying X-RSC-Reload, which the client turns into window.location.href.
+ */
+function createReloadResponse(reloadUrl: string) {
+  return createResponseWithMergedHeaders(null, {
+    status: 200,
+    headers: {
+      "X-RSC-Reload": reloadUrl,
+      "content-type": "text/x-component;charset=utf-8",
+    },
+  });
+}
+
 export function createRSCHandler<
   TEnv = unknown,
   TRoutes extends Record<string, string> = Record<string, string>,
 >(options: CreateRSCHandlerOptions<TEnv, TRoutes>) {
   const { router, version = VERSION, nonce: nonceProvider } = options;
 
+  // Handler-owned registry of explicit per-scope stores from cache({ store }).
+  // Lives in the closure so it is scoped per handler (multi-router deployments
+  // get separate registries) and accumulates every explicit store this handler
+  // resolves across requests. updateTag()/revalidateTag() iterate it to reach
+  // stores not covered by the app-level ctx._cacheStore.
+  const explicitTaggedStores = new Set<SegmentCacheStore>();
+
   // Use provided deps or default to @vitejs/plugin-rsc/rsc exports
   const deps = options.deps ?? rscDeps;
   const {
@@ -264,12 +293,13 @@ export function createRSCHandler<
   function createRedirectFlightResponse(
     redirectUrl: string,
     locationState?: Record<string, unknown>,
+    external?: boolean,
   ): Response {
     const redirectPayload: RscPayload = {
       metadata: {
         pathname: redirectUrl,
         segments: [],
-        redirect: { url: redirectUrl },
+        redirect: { url: redirectUrl, ...(external && { external: true }) },
         ...(locationState && { locationState }),
       },
     };
@@ -421,9 +451,12 @@ export function createRSCHandler<
       url,
       variables,
       cacheStore,
+      explicitTaggedStores,
       cacheProfiles: router.cacheProfiles,
       executionContext: executionCtx,
       themeConfig: router.themeConfig,
+      stateCookieName: router.resolvedStateCookieName,
+      version,
     });
     if (earlyMetricsStore) {
       requestContext._debugPerformance = true;
@@ -433,7 +466,7 @@ export function createRSCHandler<
     // can surface non-fatal errors through the router's onError callback.
     requestContext._reportBackgroundError = (
       error: unknown,
-      category: string,
+      category: CacheErrorCategory,
     ) => {
       callOnError(error, "cache", {
         request,
@@ -539,7 +572,12 @@ export function createRSCHandler<
         response.headers.set("Server-Timing", fullTiming);
       }
 
-      return response;
+      // Single open-redirect chokepoint: every response (PE, full-page,
+      // middleware short-circuit, response-route) funnels through here, so
+      // guarding browser-followed (3xx) redirects once covers them all and any
+      // future redirect exit. Soft SPA/Flight redirects are 200/204 and pass
+      // through untouched (validated client-side instead).
+      return guardOutgoingRedirect(response, url.origin, router.basename);
     });
   };
 
@@ -597,10 +635,7 @@ export function createRSCHandler<
         routerId: router.id,
       });
     } catch (error) {
-      if (
-        error instanceof RouteNotFoundError ||
-        (error instanceof Error && error.name === "RouteNotFoundError")
-      ) {
+      if (isRouteNotFoundError(error)) {
         // Let the render path handle 404 — match()/matchPartial() will
         // re-throw RouteNotFoundError and the catch block in
         // executeRenderWithMiddleware renders the not-found page.
@@ -641,24 +676,18 @@ export function createRSCHandler<
       console.log(
         `[RSC] Version mismatch: client=${url.searchParams.get("_rsc_v")}, server=${version}. Forcing reload.`,
       );
-      return createResponseWithMergedHeaders(null, {
-        status: 200,
-        headers: {
-          "X-RSC-Reload": plan.reloadUrl,
-          "content-type": "text/x-component;charset=utf-8",
-        },
-      });
+      return createReloadResponse(plan.reloadUrl);
+    }
+
+    if (plan.mode === "app-switch") {
+      // Cross-app SPA navigation crossed a host-router app boundary. Force a
+      // real document navigation so the target app's document is re-established
+      // (stylesheets, theme, warmup, prefetch-TTL). See request-classification.
+      return createReloadResponse(plan.reloadUrl);
     }
 
     // ---- 3. Origin guard (gate for action/loader/PE modes) ----
-    const originPhase: OriginCheckPhase | null =
-      plan.mode === "action"
-        ? "action"
-        : plan.mode === "loader"
-          ? "loader"
-          : plan.mode === "pe-render"
-            ? "pe-form"
-            : null;
+    const originPhase = ORIGIN_CHECK_PHASE_BY_MODE[plan.mode];
     if (originPhase) {
       const originResult = await checkRequestOrigin(
         request,
@@ -925,47 +954,17 @@ export function createRSCHandler<
       );
     }
 
-    // ---- Full render / Partial render (or PE that fell through) ----
-    if (plan.mode === "full-render" || plan.mode === "partial-render") {
-      const isPartial = plan.mode === "partial-render";
-      return executeRenderWithMiddleware(
-        plan.route.routeMiddleware,
-        plan.negotiated,
-        plan.route.routeKey,
-        routeReverse,
-        request,
-        env,
-        url,
-        variables,
-        nonce,
-        handleStore,
-        isPartial,
-      );
-    }
-
-    // PE that fell through (handleProgressiveEnhancement returned null)
-    // falls back to full render
-    if (plan.mode === "pe-render") {
-      return executeRenderWithMiddleware(
-        plan.route.routeMiddleware,
-        false,
-        plan.route.routeKey,
-        routeReverse,
-        request,
-        env,
-        url,
-        variables,
-        nonce,
-        handleStore,
-        false,
-      );
-    }
-
-    // Redirect plan that wasn't handled above (full-page redirect — let
-    // the pipeline handle it via match() which returns { redirect: url })
+    // Full render, partial render, fallen-through PE, and full-page redirect all
+    // render through the same middleware-wrapped path. Only full/partial-render
+    // carry negotiation + the partial flag; pe/redirect render plainly.
+    const isPartial = plan.mode === "partial-render";
+    const negotiated =
+      plan.mode === "full-render" || plan.mode === "partial-render"
+        ? plan.negotiated
+        : false;
     return executeRenderWithMiddleware(
       plan.route.routeMiddleware,
-      false,
+      negotiated,
       plan.route.routeKey,
       routeReverse,
       request,
@@ -974,7 +973,7 @@ export function createRSCHandler<
       variables,
       nonce,
       handleStore,
-      false,
+      isPartial,
     );
   }
 
@@ -1025,10 +1024,19 @@ export function createRSCHandler<
       } catch (error) {
         // Check if middleware/handler returned Response
         if (error instanceof Response) {
+          // An action revalidation render is delivered to the client over the
+          // same Flight-parsing path as a partial navigation, so a Response
+          // thrown during it must be converted exactly like a partial one
+          // (raw 200 -> hard-nav hint, 3xx -> Flight redirect). Without this,
+          // the no-middleware path returns the raw Response (the with-middleware
+          // path is already covered by the isPartial || actionContinuation
+          // guard below).
+          const treatAsPartial = isPartial || actionContinuation != null;
+
           // During partial (client-side navigation), a 200 Response from a handler
           // means the route serves raw content (JSON, text, etc.), not JSX.
           // Signal the browser to hard-navigate so it renders the raw response.
-          if (isPartial && error.status === 200) {
+          if (treatAsPartial && error.status === 200) {
             console.warn(
               `[RSC] Route handler at ${url.pathname} returned a Response during client-side navigation. ` +
                 `Falling back to hard navigation. Use data-external on the <Link> to avoid the extra round-trip.`,
@@ -1042,7 +1050,7 @@ export function createRSCHandler<
             });
           }
 
-          if (isPartial) {
+          if (treatAsPartial) {
             const intercepted = interceptRedirectForPartial(
               error,
               createRedirectFlightResponse,
@@ -1054,10 +1062,7 @@ export function createRSCHandler<
         }
 
         // Render 404 page for unmatched routes
-        const isRouteNotFound =
-          error instanceof RouteNotFoundError ||
-          (error instanceof Error && error.name === "RouteNotFoundError");
-        if (isRouteNotFound) {
+        if (isRouteNotFoundError(error)) {
           callOnError(error, "routing", {
             request,
             url,
@@ -1092,6 +1097,7 @@ export function createRSCHandler<
               rootLayout: router.rootLayout,
               handles: handleStore.stream(),
               version,
+              stateCookieName: router.resolvedStateCookieName,
               themeConfig: router.themeConfig,
               warmupEnabled: router.warmupEnabled,
               initialTheme: requireRequestContext().theme,
@@ -1104,16 +1110,15 @@ export function createRSCHandler<
             },
           });
 
-          const isRscRequest =
-            isPartial ||
-            (!request.headers.get("accept")?.includes("text/html") &&
-              !url.searchParams.has("__html")) ||
-            url.searchParams.has("__rsc");
-
-          if (isRscRequest) {
+          if (isRscRequest(request, url, isPartial)) {
             return createResponseWithMergedHeaders(rscStream, {
               status: 404,
-              headers: { "content-type": "text/x-component;charset=utf-8" },
+              headers: {
+                "content-type": "text/x-component;charset=utf-8",
+                // Router identity for the client's pre-decode integrity check; a
+                // same-app 404 matches and applies in place. See response-adapter.
+                "X-RSC-Router-Id": router.id,
+              },
             });
           }
 

package/src/rsc/helpers.ts

@@ -10,7 +10,32 @@ import {
 } from "../server/request-context.js";
 import type { RequestContext } from "../server/request-context.js";
 import { resolveLocationStateEntries } from "../browser/react/location-state-shared.js";
+import { isRedirectResponse } from "../response-utils.js";
+import {
+  EXTERNAL_REDIRECT_MARKER,
+  isExternalRedirect,
+  markExternalRedirect,
+} from "../redirect-origin.js";
 import type { MiddlewareEntry, MiddlewareFn } from "../router/middleware.js";
+import { formatCacheSignalHeader } from "../router/telemetry.js";
+import type { RscPayload } from "./types.js";
+
+/**
+ * DEVELOPMENT/TEST ONLY. When the debug cache signal gate is on,
+ * match/matchPartial populate ctx._cacheSignal. Emit it as the X-Rango-Cache
+ * header. When the gate is off, ctx._cacheSignal is undefined and NOTHING is
+ * attached — output is byte-identical to the default. Header mutation failures
+ * are swallowed so immutable Response headers (e.g. protocol-switch) are safe.
+ */
+function applyCacheSignalHeader(target: Headers, ctx: RequestContext): void {
+  const signal = ctx._cacheSignal;
+  if (!signal || signal.length === 0) return;
+  try {
+    target.set("X-Rango-Cache", formatCacheSignalHeader(signal));
+  } catch {
+    // Headers immutable — skip.
+  }
+}
 
 /**
  * Copy stub headers from the request context onto a target Headers instance:
@@ -21,6 +46,10 @@ import type { MiddlewareEntry, MiddlewareFn } from "../router/middleware.js";
 function applyStubHeaders(target: Headers, stub: Headers): void {
   stub.forEach((value, name) => {
     try {
+      // The reserved external-redirect marker is internal and never a trust
+      // signal; never copy a stub value (e.g. a stray ctx.header() call) onto a
+      // browser-facing response. The opt-in is the out-of-band brand.
+      if (name.toLowerCase() === EXTERNAL_REDIRECT_MARKER) return;
       if (name.toLowerCase() === "set-cookie") {
         target.append(name, value);
       } else if (!target.has(name)) {
@@ -44,10 +73,19 @@ function drainOnResponseCallbacks(
   const callbacks = ctx._onResponseCallbacks;
   if (callbacks.length === 0) return response;
   ctx._onResponseCallbacks = [];
+  // An onResponse callback may return a NEW Response (e.g. to add a header),
+  // which drops the out-of-band external-redirect brand (brand is keyed on
+  // Response object identity). Preserve a redirect(url, { external: true })
+  // opt-in across that rebuild so a callback can't silently neutralize the
+  // off-host redirect at the guard chokepoint.
+  const wasExternal = isExternalRedirect(response);
   let result = response;
   for (const callback of callbacks) {
     result = callback(result) ?? result;
   }
+  if (wasExternal && !isExternalRedirect(result)) {
+    markExternalRedirect(result);
+  }
   return result;
 }
 
@@ -84,6 +122,7 @@ export function createResponseWithMergedHeaders(
   const mergedHeaders = new Headers(init.headers);
   applyStubHeaders(mergedHeaders, ctx.res.headers);
   ctx.res.headers.delete("set-cookie");
+  applyCacheSignalHeader(mergedHeaders, ctx);
 
   // ctx.res.status overrides init.status when explicitly set (e.g. 404 for
   // notFound, 500 for error). Default ctx.res.status is 200.
@@ -114,8 +153,20 @@ export function createSimpleRedirectResponse(redirectUrl: string): Response {
 
 /**
  * Carry over headers from a source redirect Response to a wrapper Response.
- * Skips Location and X-RSC-Redirect (intentionally replaced by the wrapper)
- * and appends Set-Cookie to avoid clobbering multiple cookie headers.
+ * Skips Location and X-RSC-Redirect (intentionally replaced by the wrapper) and
+ * appends Set-Cookie to avoid clobbering multiple cookie headers.
+ *
+ * This is a GENERIC copier used by every redirect-rebuild path (PE
+ * extractRedirectResponse, the SPA intercept below, the guard's neutralize
+ * rebuild), so it has two redirect-specific jobs:
+ *
+ * 1. NEVER copy the reserved external-redirect header: it is no longer a trust
+ *    signal (the opt-in is the out-of-band brand), and a forged value from a
+ *    proxied upstream must not ride a rebuilt response to the browser.
+ * 2. Transfer the out-of-band external brand: a rebuilt document-native redirect
+ *    has to carry the opt-in to the guard chokepoint, which reads and clears it.
+ *    Without this transfer, redirect(url, { external: true }) would be silently
+ *    neutralized on any rebuild path (fail-closed, but a feature regression).
  */
 export function carryOverRedirectHeaders(
   source: Response,
@@ -124,12 +175,16 @@ export function carryOverRedirectHeaders(
   source.headers.forEach((value, name) => {
     const lower = name.toLowerCase();
     if (lower === "location" || lower === "x-rsc-redirect") return;
+    if (lower === EXTERNAL_REDIRECT_MARKER) return;
     if (lower === "set-cookie") {
       target.headers.append(name, value);
     } else if (!target.headers.has(name)) {
       target.headers.set(name, value);
     }
   });
+  if (isExternalRedirect(source)) {
+    markExternalRedirect(target);
+  }
 }
 
 /**
@@ -143,28 +198,62 @@ export function interceptRedirectForPartial(
   createRedirectFlightResponse: (
     redirectUrl: string,
     locationState?: Record<string, unknown>,
+    external?: boolean,
   ) => Response,
 ): Response | null {
-  const redirectUrl = response.headers.get("Location");
-  if (!(response.status >= 300 && response.status < 400 && redirectUrl)) {
+  if (!isRedirectResponse(response)) {
     return null;
   }
+  const redirectUrl = response.headers.get("Location")!;
+  // redirect(url, { external: true }) marks an explicit off-host redirect via
+  // the out-of-band brand (not a wire header). On the SPA/action channel the
+  // intent must travel as a Flight payload (metadata.redirect.external) so the
+  // client does a scheme-validated hard navigation (location.assign) rather than
+  // a partial fetch. The client re-validates the scheme; see partial-update.ts.
+  const external = isExternalRedirect(response);
   const locationState = getLocationState();
   let intercepted: Response;
   if (locationState) {
     intercepted = createRedirectFlightResponse(
       redirectUrl,
       resolveLocationStateEntries(locationState),
+      external,
     );
+  } else if (external) {
+    intercepted = createRedirectFlightResponse(redirectUrl, undefined, true);
   } else {
     intercepted = createSimpleRedirectResponse(redirectUrl);
   }
 
   carryOverRedirectHeaders(response, intercepted);
+  // Defense-in-depth at the SPA browser-facing exit: carryOverRedirectHeaders
+  // already refuses to copy the reserved marker, but strip any value that might
+  // exist on `intercepted` so a forged header can never ride the 200/204 to the
+  // browser. The external intent travels in metadata.redirect.external (Flight),
+  // where the client re-validates the scheme.
+  try {
+    intercepted.headers.delete(EXTERNAL_REDIRECT_MARKER);
+  } catch {
+    // Immutable headers: the marker was never copied here, so this is inert.
+  }
 
   return intercepted;
 }
 
+/**
+ * Attach location state set during a request to a payload's metadata.
+ * No-op if no location state was set. Callers must ensure payload.metadata
+ * is populated (the non-null assertion holds for the partial/action payloads
+ * that reach this helper).
+ */
+export function attachLocationStateIfPresent(payload: RscPayload): void {
+  const locationState = getLocationState();
+  if (locationState) {
+    payload.metadata!.locationState =
+      resolveLocationStateEntries(locationState);
+  }
+}
+
 /**
  * Only cache successful responses. Non-200 statuses (errors, redirects) are
  * not cached -- notFound() produces 500 in response routes, and explicit
@@ -191,7 +280,6 @@ export function buildRouteMiddlewareEntries<TEnv>(
       regex: null,
       paramNames: [],
       handler: mw.handler,
-      mountPrefix: null,
     } as MiddlewareEntry<TEnv>,
     params: mw.params,
   }));

package/src/rsc/index.ts

@@ -1,5 +1,5 @@
 /**
- * RSC Router - RSC Entry Point
+ * Rango - RSC Entry Point
  *
  * This module provides RSC utilities for server-side rendering,
  * server actions, loader fetching, and progressive enhancement.

package/src/rsc/json-route-result.ts

@@ -0,0 +1,38 @@
+/**
+ * Shared serialization for `json()` response-route results.
+ *
+ * Kept in its own lightweight module (depends only on `errors.js`) so the
+ * `dispatch()` testing primitive can import it WITHOUT dragging in
+ * `response-route-handler.ts`'s heavy runtime graph, which transitively reaches
+ * a Vite virtual module and breaks a plain (non-Vite) vitest import.
+ */
+
+import { RouterError } from "../errors.js";
+
+/**
+ * Serialize a `json()` response-route result, rejecting a nested unresolved
+ * Promise (the forgotten-await footgun: `() => ({ data: fetchSomething() })`).
+ * `JSON.stringify` would silently emit `{}` for a Promise, shipping empty data;
+ * the RSC pipeline awaits nested promises but this path does not. Throwing
+ * `RESPONSE_NOT_SERIALIZABLE` makes the failure loud.
+ *
+ * Shared by the production response-route handler and the `dispatch()` testing
+ * primitive so a `dispatch` json test of a forgotten await fails exactly where
+ * production 500s, instead of going green.
+ */
+export function stringifyJsonRouteResult(result: unknown): string {
+  return JSON.stringify(result, (_key, value) => {
+    if (
+      value != null &&
+      typeof (value as { then?: unknown }).then === "function"
+    ) {
+      throw new RouterError(
+        "RESPONSE_NOT_SERIALIZABLE",
+        "A json() response route returned a Promise (likely a forgotten " +
+          "await). Await async values before returning so they serialize, " +
+          "instead of emitting an empty {}.",
+      );
+    }
+    return value;
+  });
+}

package/src/rsc/manifest-init.ts

@@ -13,6 +13,7 @@ import {
   setRouteTrie,
   setRouterManifest,
   setRouterTrie,
+  setRouterPrecomputedEntries,
 } from "../route-map-builder.js";
 
 /**
@@ -36,47 +37,13 @@ export async function buildRouterTrieFromUrlpatterns(
     undefined,
     router.basename ? { urlPrefix: router.basename } : undefined,
   );
-  if (
-    generated._routeAncestry &&
-    Object.keys(generated._routeAncestry).length > 0
-  ) {
-    const { buildRouteTrie } = await import("../build/route-trie.js");
-    // Map each route to its include() staticPrefix so the trie
-    // returns the correct sp for lazy entry lookup in findMatch.
-    const routeToStaticPrefix: Record<string, string> = {};
-    for (const name of Object.keys(generated.routeManifest)) {
-      routeToStaticPrefix[name] = "";
-    }
-    // Override with prefix from include() entries so the trie
-    // returns the correct sp for lazy entry lookup in findMatch.
-    // Walk recursively to include routes in nested includes.
-    if (generated.prefixTree) {
-      const visitPrefixNode = (node: any): void => {
-        const sp = node.staticPrefix || "";
-        for (const route of node.routes || []) {
-          routeToStaticPrefix[route] = sp;
-        }
-        for (const child of Object.values(node.children || {})) {
-          visitPrefixNode(child);
-        }
-      };
-      for (const node of Object.values(generated.prefixTree)) {
-        visitPrefixNode(node);
-      }
-    }
-    const trie = buildRouteTrie(
-      generated.routeManifest,
-      generated._routeAncestry,
-      routeToStaticPrefix,
-      generated.routeTrailingSlash,
-      generated.prerenderRoutes
-        ? new Set(generated.prerenderRoutes)
-        : undefined,
-      generated.passthroughRoutes
-        ? new Set(generated.passthroughRoutes)
-        : undefined,
-      generated.responseTypeRoutes,
-    );
+  // Build the trie through the SAME shared helper the production discovery uses
+  // (discover-routers.ts), so the dev runtime-rebuilt trie and the prod
+  // serialized trie cannot drift. buildPerRouterTrie returns null when there
+  // are no routes.
+  const { buildPerRouterTrie } = await import("../build/route-trie.js");
+  const trie = buildPerRouterTrie(generated);
+  if (trie) {
     setRouterTrie(router.id, trie);
     // Set global trie only if not already set by another router
     if (!getRouteTrie()) {
@@ -84,6 +51,26 @@ export async function buildRouterTrieFromUrlpatterns(
     }
   }
   setRouterManifest(router.id, generated.routeManifest);
+
+  // Match the production discovery path: precompute leaf-include entries so the
+  // match-time shortcut in evaluateLazyEntry applies in dev/Cloudflare too.
+  // Without this, dev re-runs each matched leaf include's handler at match time
+  // (evaluateLazyEntry) AND again at render time (loadManifest); with it, the
+  // match-time run is skipped and the handler runs once per first request.
+  // Identical route ownership to the handler path (the shortcut is guarded by
+  // the same prefixIsShared and #506 checks production uses).
+  const { flattenLeafEntries } = await import("../build/prefix-tree-utils.js");
+  const precomputed: Array<{
+    staticPrefix: string;
+    routes: Record<string, string>;
+  }> = [];
+  flattenLeafEntries(
+    generated.prefixTree,
+    generated.routeManifest,
+    precomputed,
+  );
+  setRouterPrecomputedEntries(router.id, precomputed);
+
   // Merge into global manifest (needed for reverse/href across routers)
   const existing = hasCachedManifest() ? getGlobalRouteMap() : {};
   setCachedManifest({ ...existing, ...generated.routeManifest });