@rangojs/router 0.21.0 → 0.22.1

package/src/router.ts

@@ -14,6 +14,14 @@ import {
   isValidDevDiscoveryEpoch,
 } from "./dev-discovery-protocol.js";
 import { createReverse, type ReverseFunction } from "./reverse.js";
+import {
+  resolvePrerenderVersion,
+  resolveRouterVersions,
+} from "./server/build-version-table.js";
+import { isDevEnvironment } from "./errors.js";
+import { isViteDevServer } from "./cache/store-scope.js";
+import { createPrerenderTrigger } from "./prerender/create-prerender-trigger.js";
+import { createMemoryPrerenderStore } from "./prerender/memory-prerender-store.js";
 import {
   registerRouteMap,
   getRouterManifest,
@@ -155,6 +163,7 @@ export function createRouter<TEnv = any>(
     notFound,
     onError,
     cache,
+    prerender: prerenderConfigOption,
     cacheProfiles: cacheProfilesOption,
     theme: themeOption,
     urls: urlsOption,
@@ -181,6 +190,16 @@ export function createRouter<TEnv = any>(
     strictMode: strictModeOption = true,
   } = options;
 
+  const defaultDevPrerenderStore = prerenderConfigOption
+    ? undefined
+    : createMemoryPrerenderStore();
+  const effectivePrerenderConfigOption =
+    prerenderConfigOption ??
+    ((() =>
+      isViteDevServer() && defaultDevPrerenderStore
+        ? { store: defaultDevPrerenderStore }
+        : undefined) as RangoOptions<TEnv>["prerender"]);
+
   // Debug cache signal gate (DEVELOPMENT/TEST ONLY). Enabled by the
   // debugCacheSignal option OR the RANGO_TEST_SIGNALS=1 env flag. When off,
   // no X-Rango-Cache header is emitted and output is byte-identical.
@@ -744,6 +763,77 @@ export function createRouter<TEnv = any>(
     );
   }
 
+  // Shared reverse function (also the value behind router.reverse).
+  const reverseFn = createReverse(mergedRouteMap);
+  const reverseLoose = reverseFn as unknown as (
+    name: string,
+    params?: Record<string, string>,
+  ) => string;
+
+  // On-demand prerender binder (router.prerender({ env, ctx }) -> runner with .many / .markStale).
+  // Requestless: runProducer runs matchForPrerender with onDemand=true (arming
+  // the personalization guard); the store/config resolve per call from {env,ctx}.
+  // The key version is the router's data version, resolved by the same call the
+  // handler's overlay read makes (resolvePrerenderVersion), so the keys agree.
+  const prerenderTrigger = createPrerenderTrigger<TEnv, {}>({
+    routerId,
+    resolveVersion: () => resolvePrerenderVersion(routerId, version),
+    isDev: isDevEnvironment,
+    isViteDevServer,
+    ensureManifest: () => ensureRouterManifest(routerId),
+    resolveConfig: (env, ctx) => {
+      const opt = effectivePrerenderConfigOption;
+      if (!opt) return undefined;
+      return typeof opt === "function" ? opt(env, ctx) : opt;
+    },
+    reverse: (route, params) => {
+      try {
+        return reverseLoose(route, params);
+      } catch {
+        return undefined;
+      }
+    },
+    matchRoute: async (pathname) => {
+      const m = await findMatch(pathname);
+      if (!m) return null;
+      return {
+        routeName: m.routeKey,
+        params: m.params,
+        isOnDemand: m.od === true,
+        isPassthrough: m.pt === true,
+      };
+    },
+    runProducer: ({ pathname, isPassthrough, env, dev }) =>
+      _matchForPrerender<TEnv>(
+        pathname,
+        {},
+        {
+          ...prerenderDeps,
+          versions: resolveRouterVersions(routerId, version),
+        },
+        undefined,
+        isPassthrough,
+        env,
+        dev,
+        true,
+      ),
+    // A warm goes through router.fetch's handler: the one createRouter's own
+    // cache, nonce and version configure. An entry that passes them to
+    // createRSCHandler itself is not what a warm runs.
+    resolveCacheConfig: (env, ctx) =>
+      typeof cache === "function" ? cache(env, ctx) : cache,
+    // Called from inside a request, the warm leaves that request's scopes:
+    // it runs in the context the request entered the handler with
+    // (RequestContext._runAtRequestEntry).
+    fetch: (request, input) => {
+      const atRequestEntry = _getRequestContext()?._runAtRequestEntry;
+      return atRequestEntry
+        ? atRequestEntry(() => router.fetch(request, input))
+        : router.fetch(request, input);
+    },
+    ambientOrigin: () => _getRequestContext()?.url.origin,
+  });
+
   // Create match handler functions bound to router state
   const matchHandlers = createMatchHandlers<TEnv>({
     buildRouterContext,
@@ -866,6 +956,7 @@ export function createRouter<TEnv = any>(
       // Collect route keys that have prerender handlers (for non-trie match path)
       let prerenderRouteKeys: Set<string> | undefined;
       let passthroughRouteKeys: Set<string> | undefined;
+      let onDemandRouteKeys: Set<string> | undefined;
       for (const [name, entry] of manifest.entries()) {
         if (entry.type === "route" && entry.isPrerender) {
           if (!prerenderRouteKeys) prerenderRouteKeys = new Set();
@@ -874,6 +965,10 @@ export function createRouter<TEnv = any>(
             if (!passthroughRouteKeys) passthroughRouteKeys = new Set();
             passthroughRouteKeys.add(name);
           }
+          if (entry.isOnDemand === true) {
+            if (!onDemandRouteKeys) onDemandRouteKeys = new Set();
+            onDemandRouteKeys.add(name);
+          }
         }
       }
 
@@ -900,6 +995,7 @@ export function createRouter<TEnv = any>(
             cacheProfiles: resolvedCacheProfiles,
             ...(prerenderRouteKeys ? { prerenderRouteKeys } : {}),
             ...(passthroughRouteKeys ? { passthroughRouteKeys } : {}),
+            ...(onDemandRouteKeys ? { onDemandRouteKeys } : {}),
           });
         }
       } else {
@@ -920,6 +1016,7 @@ export function createRouter<TEnv = any>(
           cacheProfiles: resolvedCacheProfiles,
           ...(prerenderRouteKeys ? { prerenderRouteKeys } : {}),
           ...(passthroughRouteKeys ? { passthroughRouteKeys } : {}),
+          ...(onDemandRouteKeys ? { onDemandRouteKeys } : {}),
         });
       }
 
@@ -1020,7 +1117,7 @@ export function createRouter<TEnv = any>(
     // Type-safe URL builder using merged route map
     // Types are tracked through the builder chain via TRoutes parameter
     // Seeded with static route names from the generated file (injected by Vite)
-    reverse: createReverse(mergedRouteMap),
+    reverse: reverseFn,
 
     // Expose accumulated route map for typeof extraction
     // Returns {} initially, but builder chain accumulates specific route types
@@ -1037,6 +1134,15 @@ export function createRouter<TEnv = any>(
     // Expose cache configuration for RSC handler
     cache,
 
+    // Expose the prerender store config (durable overlay) for the RSC handler to
+    // resolve per request. Stored under _prerenderConfig because `prerender` on
+    // the instance is the trigger method (router.prerender()).
+    _prerenderConfig: effectivePrerenderConfigOption,
+
+    // On-demand prerender trigger: router.prerender({ env, ctx })(target),
+    // plus .many() and .markStale() on the runner.
+    prerender: prerenderTrigger,
+
     // Expose notFound component for RSC handler
     notFound,
 

package/src/rsc/handler.ts

@@ -15,6 +15,7 @@ import {
   getRequestContext,
   _getRequestContext,
   createRequestContext,
+  captureRequestEntryContext,
 } from "../server/request-context.js";
 import * as rscDeps from "@vitejs/plugin-rsc/rsc/server";
 import type {
@@ -46,7 +47,10 @@ import {
   type ResponseRouteMatch,
 } from "./response-route-handler.js";
 import { nonce as nonceToken, resolveProviderNonce } from "./nonce.js";
-import { resolveRouterVersions } from "../server/build-version-table.js";
+import {
+  resolvePrerenderVersion,
+  resolveRouterVersions,
+} from "../server/build-version-table.js";
 import type { ErrorPhase } from "../types.js";
 import type { RouterRequestInput } from "../router/router-interfaces.js";
 import {
@@ -86,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,
@@ -205,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"
@@ -452,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
@@ -509,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;
@@ -522,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
@@ -576,6 +617,7 @@ export function createRSCHandler<
       url,
       variables,
       cacheStore,
+      prerender: resolvedPrerender,
       searchParamsFilter,
       explicitTaggedStores,
       cacheProfiles: router.cacheProfiles,
@@ -585,6 +627,11 @@ export function createRSCHandler<
       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", () =>
@@ -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,
@@ -1896,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,
@@ -1904,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

@@ -55,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 }>;
 }
@@ -92,9 +92,7 @@ function loadManifest(): Promise<ShellManifestModule | null> {
  * the document HIT decodes the prelude once per serve (openShellDocument),
  * partial replay never does. `null` memoizes a failed verdict —
  * deterministically invalid. Keyed by the asking router's document version as
- * well as the spec: the manifest key is pathname-only (shell-manifest-key.ts),
- * so under a host router two routers with different versions can ask about one
- * record.
+ * well as the spec: the verdict is that version's.
  */
 const validatedSpecs = new Map<string, ValidatedBuildShellEntry | null>();
 
@@ -270,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> {
@@ -280,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
@@ -297,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,
@@ -314,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) {
@@ -341,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