@rangojs/router 0.21.0 → 0.22.0

package/src/browser/rsc-router.tsx

@@ -6,6 +6,7 @@ import {
 import {
   createNavigationStore,
   generateHistoryKey,
+  liveHandleDataForCache,
 } from "./navigation-store.js";
 import { createEventController } from "./event-controller.js";
 import { resolveDeferredHandleValues } from "../handles/deferred-resolution.js";
@@ -27,11 +28,14 @@ import { expandPayloadFragments } from "../segment-fragments.js";
 import { initRangoState } from "./rango-state.js";
 import { registerNavigationStore } from "./navigation-store-handle.js";
 import { initPrefetchCache } from "./prefetch/cache.js";
+import {
+  auditTreeCause,
+  setSuspenseAuditStreamProbe,
+} from "../suspense-audit.js";
 import {
   setPrefetchConcurrency,
   setPrefetchDecoder,
 } from "./prefetch/loader.js";
-import { setDefaultPrefetchStrategy } from "./prefetch/default-strategy.js";
 import { setAppVersion } from "./app-version.js";
 import {
   isInterceptSegment,
@@ -147,6 +151,12 @@ export interface BrowserAppContext {
    * prefetch TTL are document-lifetime too (see AppShell).
    */
   appShellRef?: import("./app-shell.js").AppShellRef;
+  /**
+   * Resolves when the document's stream has ended and every Suspense boundary
+   * in it has been revealed. NavigationProvider closes the hydration window
+   * then (NavigationProviderProps.hydration).
+   */
+  documentRevealed: Promise<void>;
 }
 
 // Module-level state for the initialized app
@@ -255,6 +265,9 @@ export async function initBrowserApp(
   const eventController = createEventController({
     initialLocation: new URL(window.location.href),
   });
+  if (process.env.NODE_ENV !== "production") {
+    setSuspenseAuditStreamProbe(() => eventController.getState().isStreaming);
+  }
 
   // The document's entry, after the clearOnReload pass and under the version
   // set above: what readers get once they have hydrated.
@@ -307,11 +320,9 @@ export async function initBrowserApp(
     if (lateGenerator) {
       void (async () => {
         try {
-          // Applied once the root has hydrated (see hydrationCommitted): the
-          // readers that hydrated with it are subscribed by then and take
-          // the update as an ordinary one. Yields buffer in the generator
-          // meanwhile; nothing is lost.
-          await hydrationCommitted;
+          // Applied as they arrive: during the hydration window (lockHydration
+          // below) the store keeps them in order, and readers see them after
+          // the commit that hydrates every boundary (NavigationProvider).
           for await (const rawLateData of lateGenerator) {
             // Handles are async by design: a push(promise) value resolves
             // whenever it resolves — only SSR'd handles are awaited server-
@@ -337,10 +348,11 @@ export async function initBrowserApp(
   } else {
     bootLog("handles: none in payload");
   }
-  // What every reader hydrates with, whenever its boundary hydrates
-  // (useHandle): the late channel above changes the live state once the root
-  // has hydrated, and a navigation can before a streamed boundary has.
-  eventController.freezeHydrationHandleState();
+  // The hydration window: until NavigationProvider's barrier commit has
+  // hydrated every boundary, reads return the handle state the document's HTML
+  // was rendered with, and the late channel's and any navigation's handle
+  // writes wait in order (EventController.lockHydration).
+  eventController.lockHydration();
 
   // Create composable utilities
   const client = createNavigationClient(deps);
@@ -371,13 +383,10 @@ export async function initBrowserApp(
   if (prefetchConcurrency !== undefined) {
     setPrefetchConcurrency(prefetchConcurrency);
   }
-  // Apply the router-wide default Link prefetch strategy. Undefined (older
-  // server payload) keeps the module's environment-aware default, which equals
-  // the server resolver's default by contract — see default-strategy.ts.
+  // The router-wide default Link prefetch strategy, for delegated plain
+  // anchors (navigation bridge). Undefined falls back to the environment
+  // default (default-strategy.ts).
   const defaultPrefetch = initialPayload.metadata?.defaultPrefetch;
-  if (defaultPrefetch !== undefined) {
-    setDefaultPrefetchStrategy(defaultPrefetch);
-  }
 
   // Wire the RSC decoder so prefetches decode eagerly and warm the route's
   // client chunks (same createFromFetch the navigation client uses). Fragment
@@ -580,7 +589,11 @@ export async function initBrowserApp(
               intercept: responseIsIntercept,
             });
             store.setHistoryKey(historyKey);
-            const currentHandleData = eventController.getHandleState().data;
+            const currentHandleData = liveHandleDataForCache(
+              eventController,
+              store,
+              historyKey,
+            );
             store.cacheSegmentsForHistory(
               historyKey,
               segments,
@@ -588,6 +601,7 @@ export async function initBrowserApp(
             );
 
             const { main, intercept } = splitInterceptSegments(segments);
+            if (process.env.NODE_ENV !== "production") auditTreeCause("hmr");
             store.emitUpdate({
               root: renderSegments(main, {
                 interceptSegments: intercept.length > 0 ? intercept : undefined,
@@ -627,6 +641,28 @@ export async function initBrowserApp(
     linkInterceptionEnabled: linkInterception,
     version,
     appShellRef,
+    documentRevealed: new Promise<void>((resolve) => {
+      // Parsing ends with the stream, but React reveals a streamed boundary
+      // in batches up to 300 ms later (Fizz's $RC marks it `$~` and reveals
+      // it from a timer), so the boundary is still pending at
+      // DOMContentLoaded. A transition then would make React client-render
+      // it over its server HTML.
+      const start = (): void => {
+        // A reveal rewrites the same comment's data, or React removes the
+        // node; a boundary nested in revealed content joins the document
+        // only then, so resolve only once a full walk finds none.
+        let pending = unrevealedBoundaries();
+        const check = (): void => {
+          pending = pending.filter(isUnrevealed);
+          if (pending.length === 0) pending = unrevealedBoundaries();
+          if (pending.length > 0) requestAnimationFrame(check);
+          else resolve();
+        };
+        check();
+      };
+      if (document.readyState !== "loading") start();
+      else document.addEventListener("DOMContentLoaded", start, { once: true });
+    }),
   };
   browserAppContext = context;
 
@@ -634,27 +670,27 @@ export async function initBrowserApp(
   return context;
 }
 
+/**
+ * A Suspense boundary of the document React has not revealed yet: Fizz marks
+ * one `$?` while its content streams and `$~` once its reveal is queued.
+ */
+function isUnrevealed(node: Comment): boolean {
+  return node.isConnected && (node.data === "$?" || node.data === "$~");
+}
+
+function unrevealedBoundaries(): Comment[] {
+  const found: Comment[] = [];
+  const walker = document.createTreeWalker(document, NodeFilter.SHOW_COMMENT);
+  for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+    if (isUnrevealed(node as Comment)) found.push(node as Comment);
+  }
+  return found;
+}
+
 // Once-flag so the hydration-commit boot log fires a single time (StrictMode
 // re-runs the root effect; the second flush is not a second hydration).
 let hydrationCommitLogged = false;
 
-// Hydration-commit barrier for the late handle channel: the late consumer
-// applies nothing before the root's effects have run. A hydrating render
-// reads the handle state frozen before hydrateRoot (useHandle,
-// EventController.getHydrationHandleState), so an earlier application would
-// no longer mismatch (it did while the initializer read the LIVE state: seen
-// when a loader's push lost the handler-barrier race by milliseconds and its
-// late yield landed mid-hydration). What the barrier still buys: a reader
-// that hydrates after the live state moved on is rendered a second time
-// right after, since React re-renders a reader whose hydration state is not
-// the client one. Readers that hydrate with the root would all pay that;
-// after the commit they are subscribed and take the update as an ordinary
-// one. The root effect below resolves this.
-let resolveHydrationCommitted!: () => void;
-const hydrationCommitted: Promise<void> = new Promise((resolve) => {
-  resolveHydrationCommitted = resolve;
-});
-
 /**
  * Get the browser app context. Throws if initBrowserApp hasn't been called.
  */
@@ -691,13 +727,18 @@ export interface RangoProps {}
  * import * as rscBrowser from "@vitejs/plugin-rsc/browser";
  *
  * async function main() {
- *   await initBrowserApp({ rscStream, deps: rscBrowser });
+ *   const { initialPayload } = await initBrowserApp({ rscStream, deps: rscBrowser });
+ *   // Rejects when the action's state is not Flight-serializable.
+ *   const formState = await Promise.resolve(initialPayload.formState).catch(
+ *     () => undefined,
+ *   );
  *
  *   hydrateRoot(
  *     document,
  *     <React.StrictMode>
  *       <Rango />
- *     </React.StrictMode>
+ *     </React.StrictMode>,
+ *     formState ? { formState } : undefined
  *   );
  * }
  * main();
@@ -716,6 +757,7 @@ export function Rango(_props: RangoProps): React.ReactElement {
     version,
     appShellRef,
     linkInterceptionEnabled,
+    documentRevealed,
   } = getBrowserAppContext();
 
   // Signal that the React tree has hydrated. useEffect only fires after
@@ -730,9 +772,6 @@ export function Rango(_props: RangoProps): React.ReactElement {
       hydrationCommitLogged = true;
       bootLog("hydration commit (root effect flushed)");
     }
-    // Release the late handle channel (see hydrationCommitted above).
-    // StrictMode double-invoke: resolving twice is a no-op.
-    resolveHydrationCommitted();
     return cleanupPrefetch;
   }, [bridge, linkInterceptionEnabled]);
 
@@ -748,6 +787,7 @@ export function Rango(_props: RangoProps): React.ReactElement {
       version={version}
       basename={initialPayload.metadata?.basename}
       appShellRef={appShellRef}
+      hydration={{ settled: documentRevealed }}
     />
   );
 }

package/src/browser/segment-reconciler.ts

@@ -201,9 +201,9 @@ export function reconcileSegments(input: ReconcileInput): ReconcileResult {
       // inside renderSegments, causing React to unmount the entire chain
       // (LoaderBoundary > Suspense > LoaderResolver > RouteContentWrapper >
       // Suspender) every time the user opened an intercept or navigated back
-      // to a cached page. The flicker is now prevented by renderSegments'
-      // promise memoization keeping React's use() in "known fulfilled" state,
-      // so preserving `loading` keeps the element tree stable.
+      // to a cached page. The flicker is now prevented by renderSegments
+      // handing the boundary settled content and loader data, so preserving
+      // `loading` keeps the element tree stable.
       return fromCache;
     })
     .filter(Boolean) as ResolvedSegment[];

package/src/browser/server-action-bridge.ts

@@ -13,6 +13,7 @@ import {
   reconcileErrorSegments,
 } from "./segment-reconciler.js";
 import { startTransition } from "react";
+import { liveHandleDataForCache } from "./navigation-store.js";
 import type { EventController, ActionHandle } from "./event-controller.js";
 import {
   toNetworkError,
@@ -46,6 +47,7 @@ import {
   type TransitionWhenActionInput,
 } from "./transition-when.js";
 import { CLIENT_REVALIDATION_HEADER } from "../client-urls/revalidation-protocol.js";
+import { auditTreeCause } from "../suspense-audit.js";
 
 // Polyfill Symbol.dispose/asyncDispose for Safari and older browsers
 if (typeof Symbol.dispose === "undefined") {
@@ -648,7 +650,11 @@ export function createServerActionBridge(
         // handle pushed by the error-boundary render still applies — see the
         // "normal" case below for why caching after onUpdate dropped it.
         store.setSegmentIds(segmentIdsAfterError);
-        const currentHandleData = eventController.getHandleState().data;
+        const currentHandleData = liveHandleDataForCache(
+          eventController,
+          store,
+          currentKey,
+        );
         store.cacheSegmentsForHistory(
           currentKey,
           errorResult.segments,
@@ -659,6 +665,7 @@ export function createServerActionBridge(
         // Update UI with error boundary: urgent when transition({ when })
         // gated it off, like every gated-off commit.
         const errorUpdate = { root: errorTree, metadata: metadata! };
+        if (process.env.NODE_ENV !== "production") auditTreeCause("action");
         if (errorGatedOff) onUpdate(errorUpdate);
         else startTransition(() => onUpdate(errorUpdate));
 
@@ -850,7 +857,11 @@ export function createServerActionBridge(
             // Location state already applied above (pre-switch); this action's
             // UI render is skipped because a later sibling consolidates.
             store.setSegmentIds(matched);
-            const currentHandleData = eventController.getHandleState().data;
+            const currentHandleData = liveHandleDataForCache(
+              eventController,
+              store,
+              currentKey,
+            );
             store.cacheSegmentsForHistory(
               currentKey,
               fullSegments,
@@ -862,9 +873,13 @@ export function createServerActionBridge(
 
         case "normal": {
           // transition({ when }) for the action commit (kind "action"): the
-          // page does not move, so `to` is `from`. False commits urgently (a
-          // re-suspending segment streams its loading()) and switches every
-          // <ViewTransition> class to "none"; true keeps the startTransition.
+          // page does not move, so `to` is `from`. False commits urgently and
+          // switches every <ViewTransition> class to "none"; the tree below
+          // is built with isAction, which awaits segment content and loader
+          // data, so a boundary on screen is handed settled values. A build
+          // then shows no loading(); the dev server still does, because the
+          // client references of a fresh payload are still importing in that
+          // first render. True keeps the startTransition.
           // This commit runs after awaits, outside the transition React opens
           // for a form action / useActionState call, so React does not force
           // a transition on it. The tree shape never changes, so
@@ -910,7 +925,11 @@ export function createServerActionBridge(
           //
           // Location state already applied above (pre-switch). Update store.
           store.setSegmentIds(matched);
-          const currentHandleData = eventController.getHandleState().data;
+          const currentHandleData = liveHandleDataForCache(
+            eventController,
+            store,
+            currentKey,
+          );
           store.cacheSegmentsForHistory(
             currentKey,
             fullSegments,
@@ -919,6 +938,7 @@ export function createServerActionBridge(
           store.rememberDisplayedEntry(metadata?.routeName);
 
           const actionUpdate = { root: newTree, metadata: metadata! };
+          if (process.env.NODE_ENV !== "production") auditTreeCause("action");
           if (gatedOff) onUpdate(actionUpdate);
           else startTransition(() => onUpdate(actionUpdate));
           // Invalidation deferred to finalizeAction() (runs after this caches

package/src/browser/types.ts

@@ -1,4 +1,5 @@
 import type { ReactNode, ComponentType } from "react";
+import type { ReactFormState } from "react-dom/client";
 import type { ResolvedSegment, SlotState } from "../types.js";
 import type { ResolvedThemeConfig, Theme } from "../theme/types.js";
 import type { RenderSegmentsOptions } from "../segment-system.js";
@@ -14,6 +15,11 @@ import type { RenderSegmentsOptions } from "../segment-system.js";
 export interface RscPayload<TMetadata = RscMetadata> {
   metadata?: TMetadata;
   returnValue?: ActionResult;
+  /**
+   * Form state of a PE POST document, for hydrateRoot's `formState` option.
+   * Rejects when the action's state is not Flight-serializable.
+   */
+  formState?: Promise<ReactFormState>;
 }
 
 /**
@@ -459,6 +465,8 @@ export interface NavigateOptionsInternal extends Omit<
   state?: unknown;
   /** Skip segment cache (used by redirect-with-state to force re-render) */
   _skipCache?: boolean;
+  /** Server redirects already followed by this navigation chain (0 for a user navigation) */
+  _redirectHops?: number;
 }
 
 /**
@@ -554,6 +562,9 @@ export type StateListener = () => void;
  * EventController owns the public navigation lifecycle exposed by hooks.
  */
 export interface NavigationStore {
+  /** Client loader data for useLoader / useFetchLoader (loader-store.ts). */
+  readonly loaders: import("../loader-store.js").LoaderStore;
+
   // Internal segment state (for bridges)
   getSegmentState(): SegmentState;
   setPath(path: string): void;

package/src/build/generate-manifest.ts

@@ -61,6 +61,8 @@ export interface GeneratedManifest {
   prerenderRoutes?: string[];
   /** Route names wrapped with Passthrough() (live handler for runtime fallback) */
   passthroughRoutes?: string[];
+  /** Route names opted into on-demand prerender (Prerender(..., { onDemand })) */
+  onDemandRoutes?: string[];
   /** Route name → response type for non-RSC routes */
   responseTypeRoutes?: Record<string, string>;
   /** Route name -> search schema descriptor for typed URL helpers */
@@ -172,6 +174,7 @@ async function buildPrefixTreeNode(
   prerenderRoutes?: string[],
   prerenderDefs?: Record<string, any>,
   passthroughRoutes?: string[],
+  onDemandRoutes?: string[],
   responseTypeRoutes?: Record<string, string>,
   routeSearchSchemas?: Record<string, Record<string, string>>,
   routerId?: string,
@@ -264,6 +267,13 @@ async function buildPrefixTreeNode(
             passthroughRoutes.push(name);
           }
         }
+        if (
+          onDemandRoutes &&
+          entry.type === "route" &&
+          entry.isOnDemand === true
+        ) {
+          onDemandRoutes.push(name);
+        }
       }
     }
 
@@ -289,6 +299,7 @@ async function buildPrefixTreeNode(
         prerenderRoutes,
         prerenderDefs,
         passthroughRoutes,
+        onDemandRoutes,
         responseTypeRoutes,
         routeSearchSchemas,
         routerId,
@@ -455,6 +466,7 @@ export async function generateManifestFull<TEnv>(
   const prerenderRoutes: string[] = [];
   const prerenderDefs: Record<string, any> = {};
   const passthroughRoutes: string[] = [];
+  const onDemandRoutes: string[] = [];
   const responseTypeRoutes: Record<string, string> = {};
   for (const [name, entry] of manifest) {
     if (entry.type === "route" && entry.isPrerender) {
@@ -465,6 +477,9 @@ export async function generateManifestFull<TEnv>(
       if (entry.isPassthrough === true) {
         passthroughRoutes.push(name);
       }
+      if (entry.isOnDemand === true) {
+        onDemandRoutes.push(name);
+      }
     }
     if (entry.type === "route" && entry.responseType) {
       responseTypeRoutes[name] = entry.responseType;
@@ -485,6 +500,7 @@ export async function generateManifestFull<TEnv>(
       prerenderRoutes,
       prerenderDefs,
       passthroughRoutes,
+      onDemandRoutes,
       responseTypeRoutes,
       routeSearchSchemas,
       options?.routerId,
@@ -502,6 +518,7 @@ export async function generateManifestFull<TEnv>(
     prerenderRoutes: prerenderRoutes.length > 0 ? prerenderRoutes : undefined,
     passthroughRoutes:
       passthroughRoutes.length > 0 ? passthroughRoutes : undefined,
+    onDemandRoutes: onDemandRoutes.length > 0 ? onDemandRoutes : undefined,
     responseTypeRoutes:
       Object.keys(responseTypeRoutes).length > 0
         ? responseTypeRoutes

package/src/build/merge-full-manifests.ts

@@ -136,6 +136,11 @@ export function mergeFullManifests(
         manifest.passthroughRoutes,
         overwrittenRoutes,
       ),
+      onDemandRoutes: mergeRouteList(
+        merged.onDemandRoutes,
+        manifest.onDemandRoutes,
+        overwrittenRoutes,
+      ),
       responseTypeRoutes: mergeRouteRecord(
         merged.responseTypeRoutes,
         manifest.responseTypeRoutes,

package/src/build/route-trie.ts

@@ -50,5 +50,6 @@ export function buildPerRouterTrie(manifest: FullManifest): TrieNode | null {
       ? new Set(manifest.passthroughRoutes)
       : undefined,
     manifest.responseTypeRoutes,
+    manifest.onDemandRoutes ? new Set(manifest.onDemandRoutes) : undefined,
   );
 }

package/src/cache/background-task.ts

@@ -7,6 +7,8 @@
  * skipping.
  */
 
+import type { ExecutionContext } from "../types/request-scope.js";
+
 interface WaitUntilHost {
   waitUntil?: (fn: () => Promise<void>) => void;
 }
@@ -85,3 +87,62 @@ export async function settleGrowing(
   }
   return true;
 }
+
+/** Macrotask turns `awaitLaterMillisecond` waits at most. */
+export const LATER_MILLISECOND_MAX_TURNS = 10;
+
+/**
+ * Yield until `Date.now()` passes `since`, so a store's whole-millisecond tag
+ * gate (putShell vs an invalidation made just before) sees a later
+ * millisecond. Bounded: on Cloudflare the clock stands still between I/O
+ * events, so an unbounded wait could hang. At the bound the caller proceeds
+ * and a store may refuse the write, which its result reports.
+ */
+export async function awaitLaterMillisecond(
+  since: number,
+  maxTurns: number = LATER_MILLISECOND_MAX_TURNS,
+): Promise<void> {
+  for (let turn = 0; turn < maxTurns && Date.now() === since; turn++) {
+    await new Promise<void>((resolve) => setTimeout(resolve, 0));
+  }
+}
+
+/** An ExecutionContext that keeps every promise handed to `waitUntil`. */
+export interface CollectingExecutionContext extends ExecutionContext {
+  readonly tasks: Promise<unknown>[];
+}
+
+/**
+ * Wrap the caller's ExecutionContext (or none) so a caller can wait for the
+ * request's background work: the deferred cache writes, the shell capture, a
+ * store's own writes. Every other member reads through to `inner`, bound to
+ * it (workerd's methods reject a foreign `this`).
+ */
+export function createCollectingExecutionContext(
+  inner?: ExecutionContext,
+): CollectingExecutionContext {
+  const tasks: Promise<unknown>[] = [];
+  const own: CollectingExecutionContext = {
+    tasks,
+    waitUntil(promise) {
+      const task = Promise.resolve(promise);
+      // The list only waits; the host (or the log below) owns the failure.
+      tasks.push(task.catch(() => {}));
+      if (inner) inner.waitUntil(task);
+      else {
+        task.catch((error) =>
+          console.error("[waitUntil] Background task failed:", error),
+        );
+      }
+    },
+    passThroughOnException() {},
+  };
+  if (!inner) return own;
+  return new Proxy(own, {
+    get(target, prop) {
+      if (prop in target) return target[prop as keyof typeof target];
+      const value = (inner as unknown as Record<PropertyKey, unknown>)[prop];
+      return typeof value === "function" ? value.bind(inner) : value;
+    },
+  });
+}

package/src/cache/cache-key-utils.ts

@@ -22,7 +22,7 @@ import type { SearchParamsFilter } from "./search-params-filter.js";
  */
 const RESERVED_SEARCH_PARAMS = new Set(["__no_cache", "__rsc", "__html"]);
 
-function isReservedSearchParam(key: string): boolean {
+export function isReservedSearchParam(key: string): boolean {
   return key.startsWith("_rsc") || RESERVED_SEARCH_PARAMS.has(key);
 }
 
@@ -65,20 +65,37 @@ export function sortedRouteParams(
 }
 
 /**
- * Host-namespaced cache key base: `${host}${pathname}[:params][?search]`.
+ * THE ROUTER RULE (#1065). A key that names one router's output for a host
+ * and path starts with the router part, `{encodeURIComponent(routerId)}@`. A
+ * key that names a function and its arguments, or a tag, does not.
  *
- * The ONE composition of the host-namespacing rule, shared by the segment tier
- * (cache-scope.ts) and the document tier (document-cache.ts) so the rule cannot
- * drift between them. Host prefixing matters because VercelCacheStore /
- * MemorySegmentCacheStore key by the raw string (only CFCacheStore adds host
- * internally) -- on a single function serving multiple domains an
- * un-namespaced key bleeds tenant A's cached response to tenant B.
+ * - With the part: PPR shells and the build-shell manifest (buildShellKey,
+ *   buildShellManifestKey); route cache() records, the document cache and
+ *   response routes (cacheKeyBase); a loader's own cache() entry; a
+ *   `"use cache"` entry of a call that takes a ctx (a ctx is one router's:
+ *   its variables, env and reverse() map).
+ * - Without: a `"use cache"` entry of plain arguments or a bare Request
+ *   (requestArgKey); tag markers; a key the app builds itself
+ *   (`cache({ key })`, a `keyGenerator`).
  *
- * Output is BYTE-STABLE by contract: changing the composition silently
- * invalidates every persisted cache entry on upgrade. Callers append their own
- * tier-specific suffixes (`:rsc`/`:html`, segment hash) after this base.
+ * Why: a host and path do not name a router. A `hostOverride` cookie picks
+ * the router and forwards the request unmodified, and a `router.prerender()`
+ * warm requests whatever origin it resolved, so two routers on one store
+ * built one key and read each other's entry.
+ *
+ * The id (router.ts) has to be the same in every isolate and in build-time
+ * discovery: an explicit `id` and the injected `$$id` are, the `router_{n}`
+ * fallback is for a single router only (discover-routers.ts warns about
+ * more). Encoded, the id holds no `@` or `/`, and a host holds no `@`, so a
+ * key has a router part exactly when its first `@` comes before its first
+ * `/`: no id can be chosen to spell another router's key.
  */
-export function cacheKeyBase(
+export function routerKeyPrefix(routerId: string): string {
+  return `${encodeURIComponent(routerId)}@`;
+}
+
+/** `{host}{pathname}[:params][?search]`: what follows the router part. */
+function hostPathKey(
   host: string,
   pathname: string,
   searchParams?: URLSearchParams,
@@ -96,6 +113,68 @@ export function cacheKeyBase(
   return key;
 }
 
+/**
+ * Key base of one router's output (the router rule, routerKeyPrefix):
+ * `${routerId}@${host}${pathname}[:params][?search]`.
+ *
+ * The ONE composition of the namespacing rule, shared by the segment tier
+ * (cache-scope.ts), the document tier (document-cache.ts), the response tier
+ * (rsc/response-cache-serve.ts) and the loader cache so the rule cannot drift
+ * between them. Host prefixing matters because VercelCacheStore /
+ * MemorySegmentCacheStore key by the raw string (only CFCacheStore adds host
+ * internally) -- on a single function serving multiple domains an
+ * un-namespaced key bleeds tenant A's cached response to tenant B.
+ *
+ * Output is BYTE-STABLE by contract: changing the composition silently
+ * invalidates every persisted cache entry on upgrade. Callers append their own
+ * tier-specific suffixes (`:rsc`/`:html`, segment hash) after this base.
+ */
+export function cacheKeyBase(
+  routerId: string,
+  host: string,
+  pathname: string,
+  searchParams?: URLSearchParams,
+  params?: Record<string, string>,
+  filter?: SearchParamsFilter,
+): string {
+  return `${routerKeyPrefix(routerId)}${hostPathKey(host, pathname, searchParams, params, filter)}`;
+}
+
+/**
+ * cacheKeyBase for the request context `ctx`. rsc/handler.ts sets `_routerId`
+ * before the request scope opens and derived contexts inherit it, so a served
+ * request always has one. Only a hand-built context has none (a unit test,
+ * the runLoader / renderHandler primitives): its key has no router part,
+ * which no router's key equals (routerKeyPrefix).
+ */
+export function requestKeyBase(
+  ctx: { readonly _routerId?: string } | null | undefined,
+  host: string,
+  pathname: string,
+  searchParams?: URLSearchParams,
+  params?: Record<string, string>,
+  filter?: SearchParamsFilter,
+): string {
+  const routerId = ctx?._routerId;
+  return routerId === undefined
+    ? hostPathKey(host, pathname, searchParams, params, filter)
+    : cacheKeyBase(routerId, host, pathname, searchParams, params, filter);
+}
+
+/**
+ * The `"use cache"` key part of a bare Request argument: its URL, with no
+ * router part (the router rule, routerKeyPrefix).
+ */
+export function requestArgKey(url: URL, filter?: SearchParamsFilter): string {
+  return hostPathKey(
+    url.host,
+    url.pathname,
+    url.searchParams,
+    undefined,
+    filter,
+  );
+}
+
 /**
  * The prefix of a `key()` result's part in a record key (#975), and of a
  * loader's own `key()` result after its `loader:<id>:` namespace (#1009,