@rangojs/router 0.20.0 → 0.22.0

package/src/testing/serve-shell-request.ts

@@ -27,6 +27,14 @@
  * capture refuses for a root postpone (a live loader read with no boundary
  * above it) or an SSR render error is captured here.
  *
+ * A `Prerender` route serves its handler layer from the artifact
+ * `router.matchForPrerender` bakes for the URL (on its first request, kept
+ * until resetShellTestState), through the production prerender store. Its
+ * first `ppr` request is a MISS with a runtime capture, as a URL without a
+ * build-time shell is in production; build-time shells are e2e-only. An
+ * on-demand route (`Prerender(..., { onDemand })`) bakes nothing here: it
+ * serves from its prerender store, as a refresh-only page does in production.
+ *
  * Must run under the `react-server` condition (the rsc Vitest project), with
  * `rangoTestAliases()` resolving `@vitejs/plugin-rsc/rsc/server` to the stub
  * that carries the Flight runtime.
@@ -36,14 +44,21 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import { toInternal, type Rango } from "../router/router-interfaces.js";
 import { ensureRouterManifest } from "../route-map-builder.js";
 import type { SegmentCacheStore, ShellCacheEntry } from "../cache/types.js";
+import {
+  awaitLaterMillisecond,
+  createCollectingExecutionContext,
+} from "../cache/background-task.js";
 import type { ExecutionContext } from "../types/request-scope.js";
 import type { HandlerCacheConfig, SSRModule } from "../rsc/types.js";
 import type { createRSCHandler } from "../rsc/handler.js";
+import { setDefaultSSRModuleLoaderForTests } from "../rsc/ssr-module-loader.js";
 import {
   POST_QUIESCE_TASK_HOPS,
   SHELL_CAPTURE_MAX_WAIT_MS,
 } from "../rsc/shell-capture-constants.js";
 import { SEGMENT_FRAGMENT_CAPABILITY_HEADER } from "../segment-fragments.js";
+import { resolveDeferredHandleValues } from "../handles/deferred-resolution.js";
+import type { HandleData } from "../server/handle-store.js";
 import { _getRequestContext } from "../server/request-context.js";
 import {
   parsePprReplayStatus,
@@ -75,6 +90,30 @@ export interface ServeShellRequestOptions<TEnv = any> {
    * `result.replayStatus`.
    */
   partial?: true | { from?: string; segments?: readonly string[] };
+  /**
+   * POST this form as a submit before hydration: the no-JS request the
+   * progressive-enhancement path runs the action for and re-renders the page
+   * after. Build it with `createActionForm`. The response is the document
+   * (`flight` is its payload, `formState` what the SSR render received).
+   * Not with `partial`.
+   */
+  form?: FormData;
+}
+
+/** A response's handle data, as the browser consumes it. */
+export interface ShellRequestHandles {
+  /**
+   * What the document hydrates with: `metadata.handles`, read to its end
+   * before hydration starts. For a `partial` request, the last state the
+   * navigation streamed.
+   */
+  hydration: HandleData;
+  /**
+   * The states `metadata.handlesLate` delivered, in order. Each one replaces
+   * the client's handle data after hydration. Empty when nothing arrived
+   * late, and for a `partial` request.
+   */
+  late: HandleData[];
 }
 
 /** Result of {@link serveShellRequest}. */
@@ -113,6 +152,24 @@ export interface ServeShellRequestResult {
    * (CFCacheStore, VercelCacheStore) it warms the memo like any other read.
    */
   readEntry(): Promise<ShellCacheEntry | null>;
+  /**
+   * Decode the handle data of `flight` as the browser reads it, deferred
+   * values resolved. Undefined when no Flight was rendered.
+   */
+  readHandles(): Promise<ShellRequestHandles | undefined>;
+  /**
+   * The form state the SSR render received (the `formState` render option),
+   * or undefined when it received none.
+   */
+  formState: unknown;
+  /**
+   * The payload's `formState` as the browser reads it, the value the entry
+   * hands `hydrateRoot`. Undefined when the payload carries none (or no
+   * Flight was rendered). Rejects when the action's state is not
+   * Flight-serializable: the document still renders, and the entry
+   * hydrates without it.
+   */
+  readPayloadFormState(): Promise<unknown>;
 }
 
 type ShellHandler = ReturnType<typeof createRSCHandler>;
@@ -126,6 +183,8 @@ interface Recorder {
   rendered?: boolean;
   /** The HIT tail's Flight text. */
   tail?: string;
+  /** The formState render option of the document render. */
+  formState?: unknown;
 }
 
 const recorders = new AsyncLocalStorage<Recorder>();
@@ -145,9 +204,12 @@ function recordShellKey(recorder: Recorder | undefined): void {
 }
 
 const SSR_STUB: SSRModule = {
-  async renderHTML(rscStream) {
+  async renderHTML(rscStream, options) {
     const recorder = recorders.getStore();
-    if (recorder) recorder.rendered = true;
+    if (recorder) {
+      recorder.rendered = true;
+      recorder.formState = options?.formState ?? undefined;
+    }
     recordShellKey(recorder);
     return rscStream;
   },
@@ -203,8 +265,134 @@ const SSR_STUB: SSRModule = {
   },
 };
 
-/** Handlers per router, keyed by the `cacheStore` override or the router. */
-const handlers = new WeakMap<object, WeakMap<object, ShellHandler>>();
+/**
+ * `router.prerender()` warms a route through `router.fetch`, whose handler is
+ * built with no `loadSSRModule` and so reaches for the Vite RSC module loader
+ * this project cannot run. It gets the stub the handlers below get:
+ * everything else on a warm's path (router.fetch, createRSCHandler, the match
+ * pipeline, the capture) is production code. A warm runs outside a
+ * serveShellRequest call, so the stub records nothing for it.
+ */
+setDefaultSSRModuleLoaderForTests(async () => SSR_STUB);
+
+type HandleChannel = AsyncIterable<HandleData> | undefined;
+
+/** Decode a Flight payload as the browser does. */
+async function decodePayload<T>(flight: string): Promise<T> {
+  const { deserializeResult } = await import("../cache/segment-codec.js");
+  return deserializeResult<T>(flight);
+}
+
+/**
+ * Read a payload's two handle channels as browser/rsc-router.tsx does:
+ * `handles` to its end, then every `handlesLate` state.
+ */
+async function decodePayloadHandles(
+  flight: string,
+): Promise<ShellRequestHandles> {
+  const { metadata } = await decodePayload<{
+    metadata?: { handles?: HandleChannel; handlesLate?: HandleChannel };
+  }>(flight);
+  let hydration: HandleData = {};
+  for await (const data of metadata?.handles ?? []) hydration = data;
+  const late: HandleData[] = [];
+  for await (const data of metadata?.handlesLate ?? []) {
+    late.push(await resolveDeferredHandleValues(data));
+  }
+  return { hydration: await resolveDeferredHandleValues(hydration), late };
+}
+
+/**
+ * Each router's Prerender artifacts by manifest key, as `vite build` bakes
+ * them (router.matchForPrerender), baked on a URL's first request the way the
+ * dev server's /__rsc_prerender endpoint bakes them (`devMode`: a Passthrough
+ * route keeps getParams()). `baked` holds the pathnames already tried, one
+ * that baked nothing (ctx.passthrough()) included.
+ */
+let prerenderArtifacts = new WeakMap<
+  object,
+  { payloads: Map<string, string>; baked: Set<string> }
+>();
+
+/**
+ * Serve a Prerender route's handler layer from its build-time artifact, as
+ * production does: through the store the built worker reads
+ * (createPrerenderStore over globalThis.__loadPrerenderManifestModule,
+ * installed as shell-prerender-phase.ts installs it for build-time shells).
+ * `env` stands in for the build's `buildEnv`. Returns the undo, or undefined
+ * when `pathname` matches no Prerender route.
+ */
+async function servePrerenderArtifacts(
+  router: Rango<any, any>,
+  pathname: string,
+  env: unknown,
+): Promise<(() => void) | undefined> {
+  const internal = toInternal(router);
+  const matched = await internal.findMatch(pathname);
+  // A build bakes an on-demand route only for the params getParams() lists;
+  // a refresh-only page serves from its prerender store alone. A Passthrough
+  // route is baked here like a build bakes it: the `devMode` render below
+  // asks its getParams() and declines a param it does not list. A plain
+  // on-demand route is not: nothing here asks its getParams(), and baking
+  // every requested param would hide the 404 an unbaked one answers.
+  if (!matched?.pr || (matched.od && !matched.pt)) return undefined;
+  let artifacts = prerenderArtifacts.get(router);
+  if (!artifacts) {
+    prerenderArtifacts.set(
+      router,
+      (artifacts = { payloads: new Map(), baked: new Set() }),
+    );
+  }
+  const { payloads, baked } = artifacts;
+  if (!baked.has(pathname)) {
+    const result = await internal.matchForPrerender(
+      pathname,
+      {},
+      undefined,
+      matched.pt === true,
+      env,
+      true,
+    );
+    const { hashParams } = await import("../prerender/param-hash.js");
+    baked.add(pathname);
+    if (result && !result.passthrough) {
+      payloads.set(
+        `${result.routeName}/${hashParams(result.params)}`,
+        JSON.stringify({ segments: result.segments, handles: result.handles }),
+      );
+    }
+  }
+  const [{ createPrerenderStore }, { setPrerenderStoreForTests }] =
+    await Promise.all([
+      import("../prerender/store.js"),
+      import("../router/match-middleware/cache-lookup.js"),
+    ]);
+  const previousLoader = globalThis.__loadPrerenderManifestModule;
+  globalThis.__loadPrerenderManifestModule = async () => ({
+    default: Object.fromEntries([...payloads.keys()].map((key) => [key, key])),
+    loadPrerenderAsset: async (key) => ({
+      default: JSON.parse(payloads.get(key)!),
+    }),
+  });
+  const previousStore = setPrerenderStoreForTests(createPrerenderStore());
+  return () => {
+    globalThis.__loadPrerenderManifestModule = previousLoader;
+    setPrerenderStoreForTests(previousStore);
+  };
+}
+
+/**
+ * Handlers per router, keyed by the `cacheStore` override or the router. A
+ * handler binds its router's document version when it is created, so an entry
+ * is reused only while the router would still resolve that version: a
+ * setBuildVersions() call (a simulated deploy) that changes it gets a new
+ * handler. The data version is read per request, so a data-only change reuses
+ * the handler, as a long-lived worker would.
+ */
+const handlers = new WeakMap<
+  object,
+  WeakMap<object, { handler: ShellHandler; versions: string }>
+>();
 
 async function getHandler(
   router: Rango<any, any>,
@@ -212,10 +400,20 @@ async function getHandler(
 ): Promise<ShellHandler> {
   let byStore = handlers.get(router);
   if (!byStore) handlers.set(router, (byStore = new WeakMap()));
+  const internal = toInternal(router);
+  // Imported here, like the handler below: the module binds the build-only
+  // `@rangojs/router:version` virtual, which a flight-only test config (one
+  // that never serves a request) does not alias.
+  const { resolveRouterVersions } =
+    await import("../server/build-version-table.js");
+  // What createRSCHandler would resolve for this router now.
+  const { document: versions } = resolveRouterVersions(
+    internal.id,
+    internal.version,
+  );
   const cached = byStore.get(cacheStore ?? router);
-  if (cached) return cached;
+  if (cached?.versions === versions) return cached.handler;
 
-  const internal = toInternal(router);
   const routerCache = internal.cache;
   // Resolved per request, as the handler resolves the router's own config.
   const cache = (env: unknown, ctx?: ExecutionContext): HandlerCacheConfig => {
@@ -230,17 +428,28 @@ async function getHandler(
   const handler = createRSCHandler({
     router: internal,
     nonce: internal.nonce,
-    version: internal.version,
     loadSSRModule: async () => SSR_STUB,
     cache: routerCache || cacheStore ? cache : undefined,
   });
-  byStore.set(cacheStore ?? router, handler);
+  byStore.set(cacheStore ?? router, { handler, versions });
   return handler;
 }
 
 function buildRequest(url: URL, options: ServeShellRequestOptions): Request {
   const headers = new Headers(options.headers);
   const partial = options.partial;
+  if (options.form) {
+    if (partial) {
+      throw new Error(
+        "serveShellRequest: form cannot be combined with partial",
+      );
+    }
+    return new Request(url, {
+      method: "POST",
+      headers,
+      body: options.form,
+    });
+  }
   if (!partial) {
     if (!headers.has("accept")) headers.set("accept", "text/html");
     return new Request(url, { headers });
@@ -263,25 +472,30 @@ function buildRequest(url: URL, options: ServeShellRequestOptions): Request {
  * starts as a fresh worker would: the capture's stampede guard, its backoff
  * (a refused capture backs its URL off for later tests too), the shell path's
  * once-per-key warnings, the build-shell manifest memo, the "use cache"
- * in-flight leaders and warnings, and CFCacheStore's isolate memos (shells,
+ * in-flight leaders and warnings, CFCacheStore's isolate memos (shells,
  * tag markers, tag hints) and warnings, which every CFCacheStore in the
- * process shares by namespace and URL. Call it in `beforeEach`, never while
- * a request is in flight. VercelCacheStore's memos live on the `cache`
- * handle it is given: a new handle starts empty.
+ * process shares by namespace and URL, and the Prerender artifacts baked so
+ * far. Call it in `beforeEach`, never while a request is in flight.
+ * VercelCacheStore's memos live on the `cache` handle it is given: a new
+ * handle starts empty.
  */
 export async function resetShellTestState(): Promise<void> {
-  const [capture, serve, buildShells, cf, cacheRuntime] = await Promise.all([
-    import("../rsc/shell-capture.js"),
-    import("../rsc/shell-serve.js"),
-    import("../rsc/shell-build-manifest.js"),
-    import("../cache/cf/cf-cache-store.js"),
-    import("../cache/cache-runtime.js"),
-  ]);
+  prerenderArtifacts = new WeakMap();
+  const [capture, serve, buildShells, cf, cacheRuntime, cacheLookup] =
+    await Promise.all([
+      import("../rsc/shell-capture.js"),
+      import("../rsc/shell-serve.js"),
+      import("../rsc/shell-build-manifest.js"),
+      import("../cache/cf/cf-cache-store.js"),
+      import("../cache/cache-runtime.js"),
+      import("../router/match-middleware/cache-lookup.js"),
+    ]);
   capture.resetShellCaptureStateForTests();
   serve.resetShellServeStateForTests();
   buildShells.resetBuildShellManifestForTests();
   cf.resetCFShellMemoForTests();
   cacheRuntime.resetCacheRuntimeForTests();
+  cacheLookup.resetOverlayRevalidationsForTests();
 }
 
 /** Settle background tasks, including ones scheduled while settling. */
@@ -323,19 +537,15 @@ export async function serveShellRequest<TEnv = any>(
   await ensureRouterManifest(router.id);
   const handler = await getHandler(router, options.cacheStore);
   const request = buildRequest(target, options);
-  const tasks: Promise<unknown>[] = [];
-  const executionContext: ExecutionContext = {
-    waitUntil(promise) {
-      tasks.push(
-        Promise.resolve(promise).catch((error) =>
-          console.error("[waitUntil] Background task failed:", error),
-        ),
-      );
-    },
-    passThroughOnException() {},
-  };
+  const executionContext = createCollectingExecutionContext();
+  const { tasks } = executionContext;
   const recorder: Recorder = {};
-  while (Date.now() === called) await macrotask();
+  const unservePrerender = await servePrerenderArtifacts(
+    router,
+    target.pathname,
+    options.env,
+  );
+  await awaitLaterMillisecond(called);
 
   const { response, body } = await recorders.run(recorder, async () => {
     try {
@@ -346,6 +556,7 @@ export async function serveShellRequest<TEnv = any>(
       return { response, body: await response.text() };
     } finally {
       await settle(tasks);
+      unservePrerender?.();
     }
   });
 
@@ -353,21 +564,24 @@ export async function serveShellRequest<TEnv = any>(
     recorder.cache && recorder.cache.enabled !== false
       ? recorder.cache
       : undefined;
-  const key = recorder.shellKey ?? shellCacheKey(target, config?.searchParams);
+  const key =
+    recorder.shellKey ?? shellCacheKey(router, target, config?.searchParams);
   const tail = recorder.tail;
   const isFlight =
     recorder.rendered ||
     response.headers.get("content-type")?.includes("text/x-component");
+  const prelude =
+    tail !== undefined && body.endsWith(tail)
+      ? body.slice(0, body.length - tail.length)
+      : undefined;
+  const flight = tail ?? (isFlight && body ? body : undefined);
   return {
     response,
     body,
     shellStatus: parseShellStatus(response),
     replayStatus: parsePprReplayStatus(response),
-    prelude:
-      tail !== undefined && body.endsWith(tail)
-        ? body.slice(0, body.length - tail.length)
-        : undefined,
-    flight: tail ?? (isFlight && body ? body : undefined),
+    prelude,
+    flight,
     key,
     async readEntry() {
       // Passive, like the serve path's own reads: a stale entry's SWR
@@ -377,5 +591,16 @@ export async function serveShellRequest<TEnv = any>(
       });
       return read?.entry ?? null;
     },
+    async readHandles() {
+      return flight ? decodePayloadHandles(flight) : undefined;
+    },
+    formState: recorder.formState,
+    async readPayloadFormState() {
+      if (!flight) return undefined;
+      const payload = await decodePayload<{
+        formState?: Promise<unknown>;
+      }>(flight);
+      return payload.formState;
+    },
   };
 }

package/src/testing/shell-status.ts

@@ -15,7 +15,7 @@
  * 2. **Smallest status signals:** `x-rango-shell` (`HIT` | `MISS`) on document
  *    GETs, and `x-rango-ppr-replay` on partial requests to ppr routes. A replay
  *    HIT is reported only when matching consumes the captured segment record.
- *    Secondary unit signal: `store.getShell(shellCacheKey(url))` after a real
+ *    Secondary unit signal: `store.getShell(shellCacheKey(router, url))` after a real
  *    capture flush (background `putShell`). There is no Flight flag for shell HIT.
  *
  * 3. **A real MISS → capture → HIT in unit tests:** `serveShellRequest`
@@ -82,10 +82,16 @@ export interface ShellCachePartition {
 }
 
 /**
- * Shell store key for a document URL: the production `buildShellKey` (host +
- * pathname + sorted search + `:shell`) and `partitionShellKey`, both from the
- * React-free leaf `rsc/shell-capture-constants.ts`, so the testing barrel never
- * imports the shell-serve module (it pulls React).
+ * Shell store key of `router` for a document URL: the production
+ * `buildShellKey` (router id + host + pathname + sorted search + `:shell`)
+ * and `partitionShellKey`, both from the React-free leaf
+ * `rsc/shell-capture-constants.ts`, so the testing barrel never imports the
+ * shell-serve module (it pulls React).
+ *
+ * `router` is the router that serves the URL, or anything carrying its `id`
+ * (`{ id }` where the router cannot be imported, as in a Playwright test). A
+ * shell belongs to one router: two routers serving one host and path keep
+ * two entries.
  *
  * Accepts a `URL` or an absolute/relative request URL string (relative strings
  * resolve against `http://localhost`). Pass the router's `cache.searchParams`
@@ -101,13 +107,18 @@ export interface ShellCachePartition {
  *   `{ keys, generated }` (see {@link ShellCachePartition}).
  */
 export function shellCacheKey(
+  router: { readonly id: string },
   url: URL | string,
   searchParams?: CacheSearchParams,
   partition?: string | readonly string[] | ShellCachePartition,
 ): string {
   const resolved =
     typeof url === "string" ? new URL(url, "http://localhost") : url;
-  const key = buildShellKey(resolved, compileSearchParamsFilter(searchParams));
+  const key = buildShellKey(
+    router.id,
+    resolved,
+    compileSearchParamsFilter(searchParams),
+  );
   if (partition === undefined) return key;
   const { keys = [], generated = [] }: ShellCachePartition =
     typeof partition === "string"

package/src/testing/vitest-stubs/plugin-rsc.ts

@@ -17,10 +17,15 @@
  *
  * Without the condition React's server build refuses to load, so the codec
  * functions throw and a "use cache" call runs uncached. Any other load failure
- * (a moved vendored path, a missing peer) throws. The action entries stay
- * inert either way: no primitive decodes an action request.
+ * (a moved vendored path, a missing peer) throws. decodeAction and
+ * decodeFormState decode a no-JS form POST under the condition, resolving its
+ * action from the modules createActionForm() registered, as do
+ * `loadServerAction` and `decodeReply` for a plain form action. Without the
+ * condition they stay inert.
  */
 
+import { loadServerModule } from "../internal/server-modules.js";
+
 /** React's server build throws this on load without the react-server condition. */
 const MISSING_REACT_SERVER_CONDITION =
   /"react-server" condition must be enabled/;
@@ -52,11 +57,7 @@ async function loadFlightRuntime() {
   // Resolves the `$$decode-client:` / `$$preserve:` ids a cached value's client
   // and server references decode to; any other id would load a server module.
   core.setRequireModule({
-    load: (id) => {
-      throw new Error(
-        `plugin-rsc stub: server reference module "${id}" is not loadable in a test`,
-      );
-    },
+    load: (id) => loadServerModule(id),
   });
   return { server, client, core };
 }
@@ -121,7 +122,32 @@ export const encodeReply = (
     : unavailable("encodeReply");
 export const createClientTemporaryReferenceSet = (): unknown =>
   runtime ? runtime.client.createTemporaryReferenceSet() : {};
-export const loadServerAction = (): undefined => undefined;
-export const decodeReply = (): undefined => undefined;
-export const decodeAction = (): undefined => undefined;
-export const decodeFormState = (): undefined => undefined;
+export const loadServerAction = (id: string): Promise<unknown> | undefined => {
+  if (!runtime) return undefined;
+  const [file, name] = id.split("#");
+  return Promise.resolve(loadServerModule(file!)[name!]);
+};
+export const decodeReply = (
+  body: string | FormData,
+  options?: object,
+): Promise<unknown> | undefined =>
+  runtime
+    ? runtime.server.decodeReply(body, referenceManifest("$$server:"), options)
+    : undefined;
+export const decodeAction = (
+  body: FormData,
+): Promise<unknown> | null | undefined =>
+  runtime
+    ? runtime.server.decodeAction(body, referenceManifest("$$server:"))
+    : undefined;
+export const decodeFormState = (
+  actionResult: unknown,
+  body: FormData,
+): Promise<unknown> | undefined =>
+  runtime
+    ? runtime.server.decodeFormState(
+        actionResult,
+        body,
+        referenceManifest("$$server:"),
+      )
+    : undefined;

package/src/testing/vitest-stubs/version.ts

@@ -1,5 +1,8 @@
 // Stub for the build-only `@rangojs/router:version` virtual module, shipped so
 // consumers do not have to author it. The rango Vite plugin injects this at
 // build time; in a bare Vitest process it must be aliased to a stub. Empty
-// string keeps generated URLs free of a version path segment.
+// string keeps generated URLs free of a version path segment. There is no
+// build table here; setBuildVersions (@rangojs/router/testing) installs one
+// for a test that needs per-router versions.
 export const VERSION = "";
+export const ROUTER_VERSIONS: undefined = undefined;

package/src/thenable-status.ts

@@ -14,3 +14,13 @@ export function unwrapsSynchronously(stream: Promise<unknown>): boolean {
     status === "resolved_module"
   );
 }
+
+/**
+ * A resolved thenable for a use() whose result is ignored: React reads the
+ * "fulfilled" stamp and returns at once. `_debugInfo` keeps React DevTools from
+ * listing a 0 ms promise on every reader that calls it.
+ */
+export const SETTLED_THENABLE: Promise<undefined> = Object.assign(
+  Promise.resolve(undefined),
+  { status: "fulfilled", value: undefined, _debugInfo: [] },
+);

package/src/types/handler-context.ts

@@ -449,6 +449,13 @@ export type InternalHandlerContext<
   _responseType?: string;
   /** Route name for cache key scoping (prevents cross-route collisions). */
   _routeName?: string;
+  /**
+   * @internal The on-demand overlay holds a "removed" marker for this request
+   * (tryPrerenderLookup, cache-lookup.ts); gateOnDemandProducer reads it. On
+   * this context, not the request's: withCacheLookup documents that the
+   * request ALS can be lost mid-pipeline on workerd.
+   */
+  _prerenderRemoved?: true;
   /**
    * @internal Loader-cache override table: loaderId -> memoized data promise.
    * A single stable ctx.use interceptor consults this instead of chaining one
@@ -462,11 +469,14 @@ export type InternalHandlerContext<
    */
   _loaderCacheOriginalUse?: (item: any) => any;
   /**
-   * @internal A loader-cache HIT asks before replaying a loader's recorded
-   * pushes: true when that loader has not run in this request and no other
-   * replay delivered it; its later run then replaces the replayed values
-   * (HandleStore.pushReplayed). One copy per loader per request. See
-   * setupLoaderAccess.
+   * @internal A loader-cache or "use cache" HIT asks before replaying a
+   * loader's recorded pushes: true when that loader has not run in this
+   * request and no other replay delivered it; its later run then replaces
+   * the replayed values (HandleStore.pushReplayed). One copy per loader per
+   * request. A record's restore does not ask (restoreHandles): its copies
+   * are the pinned loader's own, or placeholders the claimed replay
+   * replaces. Absent on a stale refresh's ctx, whose pushes are diverted
+   * (handle-snapshot.ts appendHandles). See setupLoaderAccess.
    */
   _claimLoaderPushes?: (loaderId: string) => boolean;
   /**

package/src/types/route-entry.ts

@@ -82,6 +82,12 @@ export interface RouteEntry<TEnv = any> {
    */
   passthroughRouteKeys?: Set<string>;
 
+  /**
+   * Route keys in this entry that opted into on-demand prerender.
+   * Used by the non-trie match path to set the `od` flag.
+   */
+  onDemandRouteKeys?: Set<string>;
+
   // === Lazy evaluation fields ===
 
   /**