@rangojs/router 0.20.0 → 0.22.0

package/src/rsc/handler.ts

@@ -1,5 +1,4 @@
 /// <reference types="@vitejs/plugin-rsc/types" />
-/// <reference path="../vite/plugins/version.d.ts" />
 /**
  * RSC Request Handler
  *
@@ -16,6 +15,7 @@ import {
   getRequestContext,
   _getRequestContext,
   createRequestContext,
+  captureRequestEntryContext,
 } from "../server/request-context.js";
 import * as rscDeps from "@vitejs/plugin-rsc/rsc/server";
 import type {
@@ -47,7 +47,10 @@ import {
   type ResponseRouteMatch,
 } from "./response-route-handler.js";
 import { nonce as nonceToken, resolveProviderNonce } from "./nonce.js";
-import { VERSION } from "@rangojs/router:version";
+import {
+  resolvePrerenderVersion,
+  resolveRouterVersions,
+} from "../server/build-version-table.js";
 import type { ErrorPhase } from "../types.js";
 import type { RouterRequestInput } from "../router/router-interfaces.js";
 import {
@@ -87,6 +90,8 @@ import {
 } from "./origin-guard.js";
 import { handleRscRendering } from "./rsc-rendering.js";
 import { withoutShellMissMarker } from "./shell-serve.js";
+import { readWarmMark } from "../prerender/warm-request.js";
+import { defaultSSRModuleLoaderForTests } from "./ssr-module-loader.js";
 import {
   withTimeout,
   isTimeoutEnabled,
@@ -169,7 +174,18 @@ export function createRSCHandler<
   TEnv = unknown,
   TRoutes extends Record<string, string> = Record<string, string>,
 >(options: CreateRSCHandlerOptions<TEnv, TRoutes>) {
-  const { router, version = VERSION, nonce: nonceProvider } = options;
+  const { router, nonce: nonceProvider } = options;
+  // A consumer-set version (this option, else createRouter({ version })) is
+  // used for both; otherwise the router's own pair from the build.
+  const versions = resolveRouterVersions(
+    router.id,
+    options.version ?? router.version,
+  );
+  // Everything the handler itself versions is tied to the HTML a tab holds:
+  // payload metadata (what the browser echoes as `_rsc_v`), the reload check,
+  // shell stamping and gating, the rango state value. The data version is only
+  // a cache-key prefix, read by the stores from the request context.
+  const version = versions.document;
 
   // Handler-owned registry of explicit per-scope stores from cache({ store }).
   // Lives in the closure so it is scoped per handler (multi-router deployments
@@ -195,7 +211,13 @@ export function createRSCHandler<
   // In dev mode Vite may hot-reload the module, so skip memoization.
   const rawLoadSSRModule: LoadSSRModule =
     options.loadSSRModule ??
-    (() => import.meta.viteRsc.loadModule("ssr", "index"));
+    (() =>
+      // The test seam (ssr-module-loader.ts). Gated on the build mode, not
+      // NODE_ENV: the rsc Vitest project forces NODE_ENV=production, its mode
+      // is "test", and a production build folds the whole branch away.
+      ((import.meta as any).env?.MODE !== "production" &&
+        defaultSSRModuleLoaderForTests()?.()) ||
+      import.meta.viteRsc.loadModule("ssr", "index"));
   let _ssrModulePromise: Promise<SSRModule> | undefined;
   const loadSSRModule: LoadSSRModule =
     process.env.NODE_ENV === "production"
@@ -442,12 +464,17 @@ export function createRSCHandler<
     input: RouterRequestInput<TEnv> = {},
   ): Promise<Response> {
     const handlerStart = performance.now();
+    // Before any router scope: see captureRequestEntryContext.
+    const runAtRequestEntry = captureRequestEntryContext();
     // A degraded PPR HIT's reload carries the forced-MISS marker: keep only
     // the flag (set on the request context below) and drop the marker before
     // anything reads the request, so middleware, handlers, loaders, cache
     // keys and the SSR search seed see the URL the visitor asked for.
     const unmarkedRequest = withoutShellMissMarker(incomingRequest);
     const request = unmarkedRequest ?? incomingRequest;
+    // A router.prerender() warm: the mark is the incoming Request object
+    // itself (prerender/warm-request.ts), read before anything rebuilds it.
+    const warm = readWarmMark(incomingRequest);
     // Create the metrics store at handler start so handler:total has startTime=0
     // and all metrics are relative to the request entry point.
     const earlyMetricsStore = router.debugPerformance
@@ -499,10 +526,12 @@ export function createRSCHandler<
     let searchParamsFilter: SearchParamsFilter | undefined;
     const cacheOption = options.cache ?? router.cache;
     if (cacheOption && !url.searchParams.has("__no_cache")) {
+      // A warm writes to the store the trigger checked the scope of.
       const cacheConfig =
-        typeof cacheOption === "function"
+        warm?.cacheConfig ??
+        (typeof cacheOption === "function"
           ? cacheOption(env, executionCtx)
-          : cacheOption;
+          : cacheOption);
 
       if (cacheConfig.enabled !== false) {
         cacheStore = cacheConfig.store;
@@ -512,6 +541,28 @@ export function createRSCHandler<
       }
     }
 
+    // Resolve the writable prerender store (durable overlay) for the serve path.
+    // Same factory-or-object shape as cache, resolved per request from env/ctx
+    // (never memoized). The version resolves per request, as router.prerender()
+    // resolves it per refresh, so both sides key off the same table state.
+    let resolvedPrerender:
+      | import("../prerender/on-demand.js").ResolvedPrerender<any>
+      | undefined;
+    const prerenderOption = router._prerenderConfig;
+    if (prerenderOption) {
+      const prerenderConfig =
+        typeof prerenderOption === "function"
+          ? prerenderOption(env, executionCtx)
+          : prerenderOption;
+      if (prerenderConfig?.store) {
+        resolvedPrerender = {
+          config: prerenderConfig,
+          routerId: router.id,
+          version: resolvePrerenderVersion(router.id, router.version),
+        };
+      }
+    }
+
     // Route manifest is populated at startup via the virtual module
     // (virtual:rsc-router/routes-manifest). In build/production, it's inlined
     // into the bundle. In dev mode (Node), the discovery plugin populates it
@@ -566,15 +617,21 @@ export function createRSCHandler<
       url,
       variables,
       cacheStore,
+      prerender: resolvedPrerender,
       searchParamsFilter,
       explicitTaggedStores,
       cacheProfiles: router.cacheProfiles,
       executionContext: executionCtx,
       themeConfig: router.themeConfig,
       stateCookieName: router.resolvedStateCookieName,
-      version,
+      versions,
     });
     if (unmarkedRequest) requestContext._shellForcedMiss = true;
+    requestContext._runAtRequestEntry = runAtRequestEntry;
+    if (warm) {
+      requestContext._prerenderWarm = warm;
+      requestContext._renderErrors = warm.renderErrors;
+    }
     // Gate on the SAME enabled-semantics withTimeout uses (isTimeoutEnabled):
     // a `renderStartMs: 0` / negative opt-out disables the timeout, so the
     // driver's cursor bookkeeping (which only the timeout reads) must be off too.

package/src/rsc/progressive-enhancement.ts

@@ -438,6 +438,11 @@ function renderPeResponse<TEnv>(
       strictMode: ctx.router.strictMode,
       initialTheme: payloadInitialTheme(getRequestContext()),
     },
+    // The same decoded value the SSR render receives, never a second decode:
+    // hydrateRoot needs it on the client or useActionState resets. A promise,
+    // so a state Flight cannot serialize (a class instance) rejects only this
+    // slot instead of failing the payload root and the whole document.
+    ...(reactFormState ? { formState: Promise.resolve(reactFormState) } : {}),
   };
 
   const trace = getRequestContext()._activeRoutine;
@@ -470,7 +475,6 @@ function renderPeResponse<TEnv>(
     {
       // metricsStore=undefined is safe: the handler already stashed the early
       // SSR setup promise, so this reuses it instead of starting setup again.
-      // reactFormState travels through the SSR option, not RscPayload.
       html: createSsrHtmlStage({
         ctx,
         request,

package/src/rsc/response-cache-serve.ts

@@ -33,9 +33,11 @@ import {
   finalizeResponse,
 } from "./helpers.js";
 import { reportCacheError } from "../cache/cache-error.js";
-import { cacheKeyBase } from "../cache/cache-key-utils.js";
+import { requestKeyBase } from "../cache/cache-key-utils.js";
+import { isWarmReplace, noteWarmWrite } from "../prerender/warm-request.js";
 import {
   executionStart,
+  markResponseStart,
   predatesInvalidation,
   type ExecutionStart,
 } from "../cache/tag-invalidation.js";
@@ -104,7 +106,7 @@ export async function serveResponseRouteWithCache(
   // Default key: response:{type}: + host-namespaced base (sorted search, reserved
   // _rsc*/__* params excluded). Same composition as document/segment tiers so
   // the host-namespacing and search-normalization rules cannot drift.
-  let cacheKey = `response:${responseType}:${cacheKeyBase(url.host, url.pathname, url.searchParams, undefined, reqCtx._searchParamsFilter)}`;
+  let cacheKey = `response:${responseType}:${requestKeyBase(reqCtx, url.host, url.pathname, url.searchParams, undefined, reqCtx._searchParamsFilter)}`;
 
   // Keyed like the segment record (CacheScope.resolveKeyFrom): with key()
   // results on the cache() chain (a full override, namespaced, #975) or an
@@ -180,15 +182,19 @@ export async function serveResponseRouteWithCache(
     }
     await store2.putResponse!(
       cacheKey,
-      fresh,
+      markResponseStart(fresh, start),
       cacheScope!.ttl,
       cacheScope!.swr,
       responseTags,
     );
+    noteWarmWrite(reqCtx, "response");
   };
 
   try {
-    const cached = await store.getResponse(cacheKey);
+    // A router.prerender() warm takes the miss branch and replaces the entry.
+    const cached = isWarmReplace(reqCtx)
+      ? null
+      : await store.getResponse(cacheKey);
     if (cached && canServeCached(cached.response)) {
       if (!cached.shouldRevalidate) {
         return applyPreHandlerCallbacks(cached.response);

package/src/rsc/rsc-rendering.ts

@@ -18,6 +18,7 @@ import {
   buildShellLoaderSeed,
   countSnapshotFamilies,
   hasDocRecord,
+  shellPrerenderHandles,
 } from "../cache/shell-snapshot.js";
 import { appendMetric } from "../router/metrics.js";
 import type { MetricsStore } from "../server/context.js";
@@ -93,6 +94,10 @@ import {
   type DevShellLookup,
 } from "./shell-build-manifest.js";
 import { contextGet } from "../context-var.js";
+import {
+  isWarmReplace,
+  noteWarmShellEvent,
+} from "../prerender/warm-request.js";
 import {
   resolveSwrWindow,
   staleShellRecaptureDue,
@@ -465,6 +470,13 @@ function* shellServePlan<TEnv>(
 ): RoutinePlan<ShellServeOutcome> {
   const { ctx, request, env, url, isPartial, handleStore, nonce, reqCtx } =
     input;
+  const manifestEntry = reqCtx._classifiedRoute?.manifestEntry;
+
+  // A router.prerender() warm (prerender/warm-request.ts) reports the shell of
+  // a ppr route: "not-eligible" stands for every gate below that passes, until
+  // a HIT or a capture event overwrites it.
+  const warm = reqCtx._prerenderWarm;
+  if (warm && resolvePprConfig(manifestEntry)) warm.shell ??= "not-eligible";
 
   if (
     isPartial ||
@@ -474,9 +486,11 @@ function* shellServePlan<TEnv>(
   ) {
     return { kind: "pass" };
   }
-  const manifestEntry = reqCtx._classifiedRoute?.manifestEntry;
   const pprConfig = resolvePprConfig(manifestEntry);
   if (!pprConfig) return { kind: "pass" };
+  // In replace mode the request is a MISS without reading a shell, and its
+  // capture is forced (ShellCaptureDescriptor.force).
+  const warmReplace = isWarmReplace(reqCtx);
   // A degraded HIT's reload (shellReloadScript) renders like a cache miss:
   // no shell read, no capture, so it can never degrade again. The handler
   // stripped the marker from the request and left this flag.
@@ -487,7 +501,7 @@ function* shellServePlan<TEnv>(
   // other visitor. Every step below, a HIT included, therefore runs without
   // one.
   const store = reqCtx._cacheStore;
-  const baseKey = buildShellKey(url, reqCtx._searchParamsFilter);
+  const baseKey = buildShellKey(ctx.router.id, url, reqCtx._searchParamsFilter);
   if (activeRequestNonce(nonce, reqCtx) !== undefined) {
     // Declared intent that cannot be honored deserves a diagnostic (unlike an
     // undeclared route, which is silent): a ppr route gated off by an active
@@ -551,12 +565,16 @@ function* shellServePlan<TEnv>(
   // A MISS schedules its capture after rendering: taken before the read, this
   // lets that capture skip itself when another request's capture stored the
   // shell in between (ShellCaptureDescriptor.storedSeqAtRead).
-  const storedSeqAtRead = lastStoredCaptureSeq(key);
+  // A warm's capture is its own: one another request stored meanwhile does
+  // not cancel it, so it takes no sequence.
+  const storedSeqAtRead = warmReplace ? undefined : lastStoredCaptureSeq(key);
   // SSR setup starts before route handling, so read the shell before joining it
   // to overlap the remaining setup work with cache I/O.
-  const cached = yield* step("shell-read", () =>
-    readShellEntry(store, key, reqCtx, pprConfig.tags),
-  );
+  const cached = warmReplace
+    ? null
+    : yield* step("shell-read", () =>
+        readShellEntry(store, key, reqCtx, pprConfig.tags),
+      );
 
   // allReady (ssr.resolveStreaming) bypasses PPR entirely: buffering defeats
   // streaming, so bots/SEO crawlers get one complete axis-1 document. These
@@ -579,6 +597,15 @@ function* shellServePlan<TEnv>(
     pprConfig,
     store,
   );
+  if (warm) {
+    // The warm learns its capture's outcome from the capture's own events,
+    // ahead of the router's debugShellCapture sink.
+    const routerSink = descriptor.debugSink;
+    descriptor.debugSink = (event) => {
+      noteWarmShellEvent(warm, event);
+      routerSink?.(event);
+    };
+  }
   // MISS (no entry, invalid reactVersion, a tombstone, or store read
   // failure): axis 1 + a background capture scheduled once the response is
   // known servable.
@@ -587,6 +614,10 @@ function* shellServePlan<TEnv>(
     descriptor: { ...descriptor, storedSeqAtRead },
     ssrModule,
   };
+  // Neither the stored shell nor the build shell is read: a warm renders.
+  if (warmReplace) {
+    return { ...miss, descriptor: { ...descriptor, force: true } };
+  }
 
   // A HIT replays the handler layer from the entry's doc record (`docKey`),
   // or, for a Prerender route, from the prerender store. An entry that has
@@ -612,6 +643,9 @@ function* shellServePlan<TEnv>(
         "[ShellServe] getShell",
       );
     } else {
+      // An onlyIfStale warm found a servable shell; a recapture scheduled
+      // below overwrites this through the capture's events.
+      if (warm) warm.shell = "fresh";
       // Stale (SWR) hit: serve the stale shell now, recapture in the
       // background (stampede-guarded + backoff inside scheduleShellCapture),
       // at most once per SHELL_MIN_RECAPTURE_INTERVAL_MS of the shell's age.
@@ -680,17 +714,23 @@ function* shellServePlan<TEnv>(
     // route warned. A search-bearing URL never reads one: nothing to probe.
     const routeName = reqCtx._classifiedRoute?.routeKey;
     if (
-      !partitionBuildShellCheckDone(url.pathname, routeName) &&
+      !partitionBuildShellCheckDone(ctx.router.id, url.pathname, routeName) &&
       shellSearchSeed(url, reqCtx._searchParamsFilter) === ""
     ) {
       const found = yield* step("build-shell-check", () =>
-        hasBuildShell(url.pathname, devShellLookup),
+        hasBuildShell(ctx.router.id, url.pathname, devShellLookup),
+      );
+      notePartitionBuildShellCheck(
+        ctx.router.id,
+        url.pathname,
+        routeName,
+        found,
       );
-      notePartitionBuildShellCheck(url.pathname, routeName, found);
     }
   } else {
     buildHit = yield* step("build-shell-lookup", () =>
       lookupBuildShell(
+        ctx.router.id,
         url,
         ctx.version,
         store,
@@ -705,6 +745,7 @@ function* shellServePlan<TEnv>(
     ? openShellDocumentMetered(reqCtx, { entry: buildHit.entry })
     : null;
   if (buildHit && buildDocument) {
+    if (warm) warm.shell = "fresh";
     // Past ppr.ttl: still serve the baked entry, recapture upgrades it.
     if (buildHit.stale) {
       yield* handoff("shell-recapture", () =>
@@ -1336,7 +1377,7 @@ async function matchPartialWithPprReplay<TEnv>(
   // null and the seeded record could not have been consulted, which used to
   // read as a misleading `snapshot-miss` AFTER two wasted getShell reads.
   // Same predicate as resolveNavigation, decided before any store I/O.
-  if (!getNavigationContextHeader(request)) {
+  if (!getNavigationContextHeader(request, url.origin)) {
     return runMatch({ outcome: "BYPASS", reason: "no-navigation-context" });
   }
   // Fragment passthrough (#700), extended to partial replay. Navigation
@@ -1398,7 +1439,7 @@ async function matchPartialWithPprReplay<TEnv>(
   // The visitor's own partition (resolveShellPartition): replay never
   // crosses into another partition's shell.
   const key = await resolveRequestShellKey(
-    buildShellKey(url, reqCtx._searchParamsFilter),
+    buildShellKey(ctx.router.id, url, reqCtx._searchParamsFilter),
     routeSnapshot,
     store,
     reqCtx,
@@ -1745,6 +1786,17 @@ function serveShellHit(
     // close over that same context or a streaming tail inherits the base
     // context's premature non-streaming handle snapshot.
     wireRenderBarrier(tailCtx, handleStore);
+    // The tail's render barrier resolves once its record is replayed and
+    // before a loader runs (cache-lookup.ts withCacheLookup, yieldFromStore).
+    // The store then holds what the prelude was rendered from, so that is
+    // the snapshot the document hydrates with; what this request's loaders
+    // do to it afterwards reaches the client after hydration
+    // (HandleStore.freezeDocumentSnapshot, issue #1035).
+    const resolveRenderBarrier = tailCtx._resolveRenderBarrier;
+    tailCtx._resolveRenderBarrier = (segments) => {
+      handleStore.freezeDocumentSnapshot();
+      resolveRenderBarrier(segments);
+    };
     return tailCtx;
   };
 
@@ -1885,7 +1937,7 @@ function serveShellHit(
     // fresh; a promise-free bake-lane loader is served from its pin
     // (_shellLoaderSeed, loader-cache.ts). A Prerender route's tail takes
     // the handler layer from the prerender store before this scope is
-    // consulted.
+    // consulted, and the loader pushes from `prerenderHandles`.
     seededCtx._shellImplicitCache = {
       ttl: descriptor.ttl,
       swr: descriptor.swr,
@@ -1893,6 +1945,7 @@ function serveShellHit(
       keyPrefix: "doc",
       docTail: true,
       fixedDocKey: entry.docKey,
+      prerenderHandles: shellPrerenderHandles(records),
     };
     // Fragment splice (issue #700): store hits in THIS tail emit their stored
     // segment fragments verbatim (expanded by segment-fragments.ts). The flag

package/src/rsc/shell-build-manifest.ts

@@ -11,8 +11,9 @@
  * served through the same serveShellHit as a captured one.
  *
  * Lifecycle:
- * - No expiry until the next deploy — the buildVersion gate retires entries
- *   the moment a new build ships (a new manifest replaces them anyway).
+ * - No expiry until the next deploy: every build ships its own manifest, and
+ *   its entries carry that build's document version for the router, which is
+ *   what the buildVersion gate compares.
  * - `ppr.ttl` drives STALENESS ONLY: past createdAt + ttl the entry still
  *   serves, but a runtime recapture is scheduled — SWR is the UPGRADE path
  *   from build entry to fresher runtime entry, not the bootstrap path. The
@@ -54,7 +55,7 @@ export interface BuildShellEntry {
 }
 
 interface ShellManifestModule {
-  /** Manifest key (pathname — see shell-manifest-key.ts) -> asset specifier. */
+  /** Manifest key (router id + pathname, shell-manifest-key.ts) -> asset specifier. */
   default: Record<string, string>;
   loadShellAsset: (spec: string) => Promise<{ default: BuildShellEntry }>;
 }
@@ -90,9 +91,8 @@ function loadManifest(): Promise<ShellManifestModule | null> {
  * Only the per-request gates (tag markers, staleness) stay outside the memo;
  * the document HIT decodes the prelude once per serve (openShellDocument),
  * partial replay never does. `null` memoizes a failed verdict —
- * deterministically invalid. Spec-only keying is sound because buildVersion is
- * process-constant on the manifest path (folded into the shipped worker; dev
- * never loads a manifest).
+ * deterministically invalid. Keyed by the asking router's document version as
+ * well as the spec: the verdict is that version's.
  */
 const validatedSpecs = new Map<string, ValidatedBuildShellEntry | null>();
 
@@ -110,7 +110,8 @@ async function validatedManifestRecord(
   spec: string,
   buildVersion: string,
 ): Promise<ValidatedBuildShellEntry | undefined> {
-  let verdict = validatedSpecs.get(spec);
+  const memoKey = `${buildVersion}\u0000${spec}`;
+  let verdict = validatedSpecs.get(memoKey);
   if (verdict === undefined) {
     const record = (await mod.loadShellAsset(spec)).default;
     verdict =
@@ -118,7 +119,7 @@ async function validatedManifestRecord(
       hasIntactShellPayload(record.entry)
         ? (record as ValidatedBuildShellEntry)
         : null;
-    validatedSpecs.set(spec, verdict);
+    validatedSpecs.set(memoKey, verdict);
   }
   return verdict ?? undefined;
 }
@@ -267,9 +268,11 @@ async function fetchDevShellEntry(
  * request is search-less, like the entries lookupBuildShell serves): a
  * manifest entry for the path in production, a Prerender route in dev. No
  * asset load and no dev capture: it only decides whether a request that
- * cannot read the build shell deserves a warning.
+ * cannot read the build shell deserves a warning. The manifest entry is the
+ * one staged for the router `routerId` (shell-manifest-key.ts).
  */
 export async function hasBuildShell(
+  routerId: string,
   pathname: string,
   dev?: DevShellLookup,
 ): Promise<boolean> {
@@ -277,11 +280,12 @@ export async function hasBuildShell(
     return dev?.isPrerenderRoute === true;
   }
   const mod = await loadManifest();
-  return mod?.default[buildShellManifestKey(pathname)] !== undefined;
+  return mod?.default[buildShellManifestKey(routerId, pathname)] !== undefined;
 }
 
 /**
  * Look up the baked shell entry for a request, applying every serve gate:
+ * the serving router's own entry only (`routerId`, shell-manifest-key.ts),
  * search-less requests only (the build captured the bare pathname; a
  * search-bearing URL has its own shell identity owned by runtime capture),
  * version validity, payload integrity, and tag-invalidation markers. Returns
@@ -294,6 +298,7 @@ export async function hasBuildShell(
  * traffic the shell was prerendered for.
  */
 export async function lookupBuildShell(
+  routerId: string,
   url: URL,
   buildVersion: string,
   store: SegmentCacheStore,
@@ -311,7 +316,7 @@ export async function lookupBuildShell(
     if (hasManifest) {
       const mod = await loadManifest();
       if (!mod) return null;
-      const spec = mod.default[buildShellManifestKey(url.pathname)];
+      const spec = mod.default[buildShellManifestKey(routerId, url.pathname)];
       if (!spec) return null;
       record = await validatedManifestRecord(mod, spec, buildVersion);
     } else if (dev) {
@@ -338,7 +343,7 @@ export async function lookupBuildShell(
         // diagnostic; the route keeps runtime-capture semantics.
         warnOnce(
           "build-shell-tag-check",
-          buildShellManifestKey(url.pathname),
+          buildShellManifestKey(routerId, url.pathname),
           () =>
             `[rango] Build-time shell for "${url.pathname}" carries cache tags, but ` +
             "the app cache store cannot answer tag-invalidation history durably " +

package/src/rsc/shell-capture-constants.ts

@@ -6,7 +6,10 @@
  * pulling the capture orchestration module or shell-serve.ts (React).
  */
 
-import { sortedSearchString } from "../cache/cache-key-utils.js";
+import {
+  routerKeyPrefix,
+  sortedSearchString,
+} from "../cache/cache-key-utils.js";
 import type { SearchParamsFilter } from "../cache/search-params-filter.js";
 
 /**
@@ -85,13 +88,14 @@ export function shellSearchSeed(url: URL, filter?: SearchParamsFilter): string {
 }
 
 /**
- * Shell cache key: host + pathname + sorted search + a `:shell` namespace suffix
- * (so it can never collide with a document-cache key; the store further isolates
- * the shell family internally).
+ * Shell cache key: router id + host + pathname + sorted search + a `:shell`
+ * namespace suffix (so it can never collide with a document-cache key; the
+ * store further isolates the shell family internally).
  *
  * The key includes the request HOST: in a multi-tenant host-router deployment
  * (one worker, one shared KV/runtime-cache store) a host-less key would serve
- * tenant A's captured shell to tenant B's users.
+ * tenant A's captured shell to tenant B's users. It starts with the serving
+ * ROUTER for the same reason (cache-key-utils.ts, the router rule).
  *
  * `filter` is the request's compiled `cache.searchParams` config
  * (ctx._searchParamsFilter): excluded params collapse onto one shell slot.
@@ -99,8 +103,12 @@ export function shellSearchSeed(url: URL, filter?: SearchParamsFilter): string {
  * and lookup makes every shell request a permanent miss. The testing helper
  * `shellCacheKey` (testing/shell-status.ts) builds its key with it too.
  */
-export function buildShellKey(url: URL, filter?: SearchParamsFilter): string {
-  return `${url.host}${url.pathname}${shellSearchSeed(url, filter)}:shell`;
+export function buildShellKey(
+  routerId: string,
+  url: URL,
+  filter?: SearchParamsFilter,
+): string {
+  return `${routerKeyPrefix(routerId)}${url.host}${url.pathname}${shellSearchSeed(url, filter)}:shell`;
 }
 
 /**
@@ -173,6 +181,30 @@ export const POST_QUIESCE_TASK_HOPS = 16;
  */
 export const SHELL_CAPTURE_TASK_HARD_CAP_MS = 25_000;
 
+/**
+ * Why a capture attempt refused to store its shell
+ * (ShellCaptureDebugEvent.refusal, `caches.refusal` on a `router.prerender()`
+ * result): `identity` (a request-scoped read: cookies(), headers(), the
+ * theme, a `{ cache: false }` variable), `dynamic` (`ctx.dynamic()`),
+ * `loader` (a `{ ssr: false }` loader rejected, or settled with
+ * redirect()/notFound()), `no-record` (no doc record: the route's cache()
+ * refused the write, or the handler output failed), `handles` (a pushed
+ * handle value did not finish encoding), `size` (over the store's value
+ * limit), `record-expired` (the route cache() record the capture wrote ran
+ * out first), `invalidated` (a tag of the shell was invalidated after the
+ * capture started), `uncacheable` (the store cannot hold the entry).
+ */
+export type ShellCaptureRefusal =
+  | "identity"
+  | "dynamic"
+  | "loader"
+  | "no-record"
+  | "handles"
+  | "size"
+  | "record-expired"
+  | "invalidated"
+  | "uncacheable";
+
 /**
  * Shared PPR loader-lane hint, appended to every capture warning or error
  * whose fix depends on the lane (shell-capture.ts warnings, the cookie-store.ts