@rangojs/router 0.20.0 → 0.21.0

package/src/testing/render-route.tsx

@@ -35,11 +35,19 @@
  *     useRouter().replace kind "replace", refresh() kind "revalidate".
  *     Back/forward, action and optimistic clientUrls() swap decisions are
  *     e2e territory.
+ *   - Location state reaches readers the way it does in production:
+ *     NavigationProvider holds the committed entry's state next to the
+ *     payload, so a navigation whose loader the test holds keeps the entry
+ *     being left on screen with its own state. A `popstate` event is a
+ *     back/forward onto the entry history.state holds; the tree has one
+ *     location, so no page is restored with it. A server action's state, a
+ *     redirect's and an intercept's are e2e territory.
  * What it DOES cover: client hooks that read NavigationProvider /
  * OutletContext — useParams, useReverse, useHref, useMount, useNavigation,
  * useRouter, usePathname, useSearchParams, Outlet/useOutlet nesting and seeded
  * descendant pending state, useLoader/useFetchLoader (seeded data),
- * useLocationState (seeded), and useHandle (seeded).
+ * useLocationState (seeded, or written by a navigation), and useHandle
+ * (seeded).
  * Basename-mounted apps: pass the `basename` option so useRouter().basename,
  * <Link> prefixing, and useMount/useHref resolve against the mount prefix
  * (without it they resolve at the root "/"). For an include("/shop", ...)
@@ -48,7 +56,12 @@
  */
 
 import { decideTransitionGatedOff } from "../browser/transition-when.js";
-import { useEffect, type ReactNode, type ComponentType } from "react";
+import {
+  StrictMode,
+  useEffect,
+  type ReactNode,
+  type ComponentType,
+} from "react";
 import type { RenderResult } from "@testing-library/react";
 import { renderSegments } from "../segment-system.js";
 import {
@@ -62,6 +75,7 @@ import {
   shouldStartViewTransition,
 } from "../browser/partial-update.js";
 import type {
+  NavigateOptions,
   NavigateOptionsInternal,
   NavigationStore,
   NavigationBridge,
@@ -80,10 +94,13 @@ import type {
   TransitionConfig,
   TransitionWhenKind,
 } from "../types.js";
-import type { LocationStateDefinition } from "../browser/react/location-state-shared.js";
+import {
+  setLocationStateVersion,
+  type LocationStateDefinition,
+} from "../browser/react/location-state-shared.js";
 import {
   buildHistoryState,
-  hasLocationState,
+  clearLocationStateOnDocumentLoad,
   pushHistoryWithIdx,
   resolveNavigationState,
 } from "../browser/history-state.js";
@@ -230,6 +247,8 @@ export interface RenderRouteOptions {
    * `useLocationState(StateDef)`. Like loaders, a real `createLocationState()`
    * handle has an empty injected key in a bare test, so pass `[def, value]`
    * pairs; renderRoute assigns a synthetic key and writes it to `history.state`.
+   * With `hydrate: true` a `clearOnReload` definition's seed is removed before
+   * hydration, as on a document load.
    *
    * @example
    * renderRoute([{ path: "/", Component: FlashBanner }], {
@@ -265,6 +284,24 @@ export interface RenderRouteOptions {
    * computes the segment id for you). Merged with `handles`.
    */
   handle?: HandleDataSeed;
+  /**
+   * Handle values a document delivers after hydration, as a loader's push
+   * that is not in the document's handle snapshot is (a push made after the
+   * handler output settled, or any loader push on a PPR shell HIT). Each
+   * entry is `[handle, values]`: the handle's values after the update, which
+   * replace its `handles` seed once the root has hydrated (or mounted). With
+   * `hydrate: true` the server HTML is rendered from `handles`, and a reader
+   * inside a `<Suspense>` boundary hydrates after the update was applied, as
+   * a boundary that hydrates after the root does in production.
+   *
+   * @example
+   * const { serverHtml, recoverableErrors } = await renderRoute(routes, {
+   *   hydrate: true,
+   *   handles: [[Notes, ["from-handler"]]],
+   *   lateHandles: [[Notes, ["from-handler", "from-loader"]]],
+   * });
+   */
+  lateHandles?: ReadonlyArray<readonly [Handle<any, any>, unknown[]]>;
   /**
    * Route name -> pattern map. Informational for parity with the server test
    * context; client useReverse takes its map directly as an argument, so this
@@ -326,6 +363,25 @@ export interface RenderRouteOptions {
    * not override a `"none"` default.
    */
   defaultPrefetch?: PrefetchStrategy;
+  /**
+   * Hydrate instead of mounting fresh: the same element is rendered to HTML
+   * (react-dom/server `renderToString`), placed in the container and hydrated.
+   * The result gains `serverHtml` and `recoverableErrors`
+   * (RenderRouteHydrateResult). `data-hydrated` is set on `<html>` after
+   * hydration, as production's root does, and removed on unmount.
+   *
+   * Limits:
+   * - The server pass runs without `window` and `document`, and only those. A
+   *   hook that reads a global that stays defined there (`history`,
+   *   `localStorage`, `navigator`) outside a server snapshot renders the same
+   *   in both passes here and can still mismatch in real SSR.
+   * - Content that suspends in the server pass (`lazy`, a pending or untracked
+   *   `use()` promise) is emitted as its fallback and client-rendered, not
+   *   hydrated; React reports the boundary in `recoverableErrors`. Outside any
+   *   `<Suspense>` it rejects.
+   * - Needs @testing-library/react >= 16.2.0; throws on older versions.
+   */
+  hydrate?: boolean;
 }
 
 /**
@@ -356,10 +412,20 @@ export interface TestRouterHandle {
    * `options.transition: false` is the per-navigation opt-out
    * (`router.push(url, { transition: false })`, `<Link transition={false}>`):
    * the commit is urgent and no transition({ when }) predicate is called.
+   *
+   * `options.state` and `options.replace: true` write the history entry the
+   * way `useRouter().push(url, { state })` and `.replace(url, { state })` do,
+   * so a test can carry location state on a navigation whose loader it
+   * holds: `state` pushes an entry with it, `replace: true` replaces the
+   * current entry (with `state`, or with none, which drops the entry's
+   * location state as a production replace does). With neither, history is
+   * left alone and readers keep the state they have: `navigate(url)` and
+   * `navigate(url, { replace: false })` are the same call.
    */
   navigate(
     url: string,
-    options?: Pick<RenderRouteOptions, "loaders"> & { transition?: boolean },
+    options?: Pick<RenderRouteOptions, "loaders"> &
+      Pick<NavigateOptions, "state" | "replace" | "transition">,
   ): Promise<void>;
   /**
    * Re-render the current location, as router.refresh() does: a spec's
@@ -379,6 +445,21 @@ export interface TestRouterHandle {
 /** Result of renderRoute: RTL's render result plus the router handle. */
 export type RenderRouteResult = RenderResult & { router: TestRouterHandle };
 
+/** Result of renderRoute with `hydrate: true`. */
+export type RenderRouteHydrateResult = RenderRouteResult & {
+  /** The HTML the server pass produced, as placed in the container. */
+  serverHtml: string;
+  /**
+   * Messages of the errors React recovered from (`onRecoverableError`): a
+   * hydration mismatch that made it re-render on the client, or a boundary the
+   * server pass could not finish. Empty means the tree hydrated as rendered.
+   * Live: React appends for as long as the root is mounted. An attribute-only
+   * mismatch is NOT here — React keeps the server attribute and only logs it
+   * with `console.error` in development.
+   */
+  recoverableErrors: string[];
+};
+
 interface ResolvedMatch {
   params: Record<string, string>;
   pathname: string;
@@ -419,6 +500,45 @@ function DelegatedPrefetchRegistration({
   return null;
 }
 
+/**
+ * initBrowserApp calls the bridge's registerLinkInterception, which is where
+ * production listens for `popstate` (navigation-bridge.ts); a rendered tree
+ * has no initBrowserApp.
+ */
+function LinkInterceptionRegistration({
+  bridge,
+}: {
+  bridge: NavigationBridge;
+}): null {
+  useEffect(() => bridge.registerLinkInterception(), [bridge]);
+  return null;
+}
+
+/**
+ * The marker production's root sets from its effect after hydration
+ * (browser/rsc-router.tsx Rango), so a boundary that hydrates in a later pass
+ * finds it set, as in production. Removed on unmount: a test unmounts its
+ * root, production never does.
+ */
+function HydratedMarker(): null {
+  useEffect(() => {
+    document.documentElement.dataset.hydrated = "";
+    return () => document.documentElement.removeAttribute("data-hydrated");
+  }, []);
+  return null;
+}
+
+/**
+ * Applies `lateHandles` from an effect after the tree's: where production's
+ * root effect releases the document's late handle channel
+ * (browser/rsc-router.tsx hydrationCommitted). A boundary that hydrates in a
+ * later pass finds the update applied.
+ */
+function LateHandles({ apply }: { apply: () => void }): null {
+  useEffect(apply, [apply]);
+  return null;
+}
+
 function matchLeaf(
   pattern: string,
   pathname: string,
@@ -504,6 +624,14 @@ function buildSegments(
   return segments;
 }
 
+export function renderRoute(
+  routes: RenderRouteSpec[],
+  options: RenderRouteOptions & { hydrate: true },
+): Promise<RenderRouteHydrateResult>;
+export function renderRoute(
+  routes: RenderRouteSpec[],
+  options?: RenderRouteOptions,
+): Promise<RenderRouteResult>;
 export async function renderRoute(
   routes: RenderRouteSpec[],
   options: RenderRouteOptions = {},
@@ -539,11 +667,17 @@ export async function renderRoute(
   const loaderData = seedLoaders(options.loaderData ?? {}, options.loaders);
 
   if (typeof window !== "undefined") {
+    // The tree has no app version (its bridge reports none), so a seed needs
+    // none either. Reset what an initBrowserApp in the same file may have left.
+    setLocationStateVersion(undefined);
     const stateObj: Record<string, unknown> = {};
     for (const [def, value] of options.locationState ?? []) {
       stateObj[withLocationStateKey(def).__rsc_ls_key] = value;
     }
     window.history.replaceState(stateObj, "");
+    // Hydrate mode is a document load of the seeded entry: run start-up's
+    // step (initBrowserApp), not a copy of it.
+    if (options.hydrate) clearLocationStateOnDocumentLoad();
   }
 
   const resolve = (pathname: string): ResolvedMatch => {
@@ -609,14 +743,33 @@ export async function renderRoute(
 
   const eventController = createEventController({ initialLocation: url });
   eventController.setParams(initialMatch.params);
+  // The seeded entry, as initBrowserApp commits the document's.
+  eventController.commitLocationState(window.history.state);
   // Resolve-by-default: resolve any deferred (Promise) seeded handle values
   // before applying, so the seeded handles reach collect/useHandle resolved —
   // matching what the server/client do in a real app.
   const resolvedSeed = await resolveDeferredHandleValues(handleSeed);
-  eventController.setHandleData(
-    resolvedSeed,
-    initialSegments.map((s) => s.id),
-  );
+  const initialSegmentIds = initialSegments.map((s) => s.id);
+  eventController.setHandleData(resolvedSeed, initialSegmentIds);
+  // As initBrowserApp before hydrateRoot: what a hydrating reader reads.
+  eventController.freezeHydrationHandleState();
+  // A late update carries the full state: the seed with these handles' values
+  // replaced, resolved as the browser resolves a late yield before applying.
+  let applyLateHandles: (() => void) | undefined;
+  if (options.lateHandles && leafRouteSegmentId !== undefined) {
+    const lateSeed = cloneHandleSeed(resolvedSeed);
+    for (const [handle, values] of options.lateHandles) {
+      const id = (handle as unknown as { $$id: string }).$$id;
+      (lateSeed[id] ??= {})[leafRouteSegmentId] = values;
+    }
+    const lateState = await resolveDeferredHandleValues(lateSeed);
+    // Flushed, not left to the notify timer: renderRoute's act() has
+    // returned by then.
+    applyLateHandles = () => {
+      eventController.setHandleData(lateState, initialSegmentIds);
+      eventController.flushRouteState();
+    };
+  }
 
   let warnedNavLifecycle = false;
   const navigate = async (
@@ -633,10 +786,11 @@ export async function renderRoute(
     // A useRouter().push/replace or <Link> navigation (`history`) writes its
     // entry the way production does (navigation-bridge.ts navigate ->
     // navigation-transaction.ts commit): the dev state check, typed entries
-    // spread onto history.state, the idx stamp, and the __rsc_locationstate
-    // event when the old or new entry carries location state. The URL stays
-    // put: renderRoute tracks location on the event controller, not
-    // window.location. router.navigate() and refresh() leave history alone.
+    // spread onto history.state, the idx stamp, and the entry state committed
+    // on the event controller, which the provider takes with the payload.
+    // The URL stays put: renderRoute tracks location on the event
+    // controller, not window.location. router.navigate() without `state` or
+    // `replace: true`, and refresh(), leave history alone.
     const history = navOptions?.history;
     const historyState = history
       ? buildHistoryState(
@@ -702,16 +856,13 @@ export async function renderRoute(
     eventController.setParams(match.params);
     store.setCurrentUrl(nextUrl.href);
     store.setSegmentIds(segments.map((s) => s.id));
-    let notifyLocationState = false;
     if (history) {
-      notifyLocationState =
-        hasLocationState(window.history.state) ||
-        hasLocationState(historyState);
       pushHistoryWithIdx(
         historyState ?? null,
         window.location.href,
         history.replace ?? false,
       );
+      eventController.commitLocationState(historyState);
     }
     const emit: UpdateSubscriber = (update) => store.emitUpdate(update);
     await act(async () => {
@@ -723,9 +874,6 @@ export async function renderRoute(
       } else {
         emit({ root, metadata });
       }
-      if (notifyLocationState) {
-        window.dispatchEvent(new Event("__rsc_locationstate"));
-      }
     });
   };
 
@@ -739,8 +887,20 @@ export async function renderRoute(
     navigate: (target, navigateOptions) =>
       navigate(target, { history: navigateOptions ?? {} }),
     refresh: () => refresh(),
-    handlePopstate: async () => {},
-    registerLinkInterception: () => () => {},
+    // Back/forward onto the entry history.state holds. The tree has one
+    // location, so nothing is restored: a treeless commit of that entry, as
+    // production's traversal that keeps every segment
+    // (navigation-transaction.ts commit). Flushed, not left to the notify
+    // timer: the dispatching test's act() has returned by then.
+    handlePopstate: async () => {
+      eventController.commitLocationState(window.history.state, true);
+      eventController.flushRouteState();
+    },
+    registerLinkInterception: () => {
+      const onPopstate = (): void => void bridge.handlePopstate();
+      window.addEventListener("popstate", onPopstate);
+      return () => window.removeEventListener("popstate", onPopstate);
+    },
     registerDelegatedPrefetch: () =>
       setupNavigationBridgeDelegatedPrefetch(
         store,
@@ -764,6 +924,52 @@ export async function renderRoute(
     outletPending: options.outletPending,
   });
 
+  // The marker sits after the provider so its effect runs after the tree's,
+  // like the effect of production's root component.
+  const ui = (
+    <>
+      <NavigationProvider
+        store={store}
+        eventController={eventController}
+        initialPayload={{ root: initialTree, metadata: initialMetadata }}
+        bridge={bridge}
+        basename={basename}
+        themeConfig={
+          options.theme === undefined ? null : resolveThemeConfig(options.theme)
+        }
+        nonce={options.nonce}
+      />
+      <DelegatedPrefetchRegistration bridge={bridge} />
+      <LinkInterceptionRegistration bridge={bridge} />
+      {options.hydrate && <HydratedMarker />}
+      {applyLateHandles && <LateHandles apply={applyLateHandles} />}
+    </>
+  );
+
+  let serverHtml: string | undefined;
+  const recoverableErrors: string[] = [];
+  if (options.hydrate) {
+    // RTL forwards onRecoverableError to hydrateRoot from 16.2.0. 16.0-16.1
+    // are inside the peer range and drop it (their render() never names the
+    // option), which would leave `recoverableErrors` empty on a real mismatch.
+    if (!String(render).includes("onRecoverableError")) {
+      throw new Error(
+        "renderRoute: `hydrate` needs @testing-library/react >= 16.2.0. Older " +
+          "versions do not pass onRecoverableError to hydrateRoot, so a " +
+          "hydration mismatch would go unreported.",
+      );
+    }
+    const { getConfig } = await import("@testing-library/react");
+    const { renderToString } = await import("react-dom/server");
+    // RTL wraps the hydrated element the same way.
+    const serverUi = getConfig().reactStrictMode ? (
+      <StrictMode>{ui}</StrictMode>
+    ) : (
+      ui
+    );
+    serverHtml = withoutBrowserGlobals(() => renderToString(serverUi));
+  }
+
   // Wrap render in an awaited async act so a tree that suspends (async loaders,
   // loading states, deferred handle entries that arrive as a Promise) settles its
   // Suspense within act — otherwise React orphans the resolution ("a component
@@ -772,30 +978,32 @@ export async function renderRoute(
   let result!: Awaited<ReturnType<typeof render>>;
   const container = document.body.appendChild(document.createElement("div"));
   prefetchRoot = container;
+  if (serverHtml !== undefined) container.innerHTML = serverHtml;
   await act(async () => {
-    result = render(
-      <>
-        <NavigationProvider
-          store={store}
-          eventController={eventController}
-          initialPayload={{ root: initialTree, metadata: initialMetadata }}
-          bridge={bridge}
-          basename={basename}
-          themeConfig={
-            options.theme === undefined
-              ? null
-              : resolveThemeConfig(options.theme)
-          }
-          nonce={options.nonce}
-        />
-        <DelegatedPrefetchRegistration bridge={bridge} />
-      </>,
-      { baseElement: document.body, container },
-    );
+    result = render(ui, {
+      baseElement: document.body,
+      container,
+      ...(serverHtml !== undefined && {
+        hydrate: true,
+        onRecoverableError: (error: unknown) => {
+          recoverableErrors.push(
+            error instanceof Error ? error.message : String(error),
+          );
+        },
+      }),
+    });
   });
 
   const router: TestRouterHandle = {
-    navigate,
+    navigate: (target, navOptions) =>
+      navigate(target, {
+        loaders: navOptions?.loaders,
+        transition: navOptions?.transition,
+        history:
+          navOptions?.state !== undefined || navOptions?.replace
+            ? navOptions
+            : undefined,
+      }),
     refresh,
     pathname: () => new URL(eventController.getLocation().href).pathname,
     params: () => eventController.getParams(),
@@ -803,7 +1011,33 @@ export async function renderRoute(
     eventController,
   };
 
-  return Object.assign(result, { router });
+  if (serverHtml === undefined) return Object.assign(result, { router });
+  return Object.assign(result, { router, serverHtml, recoverableErrors });
+}
+
+/**
+ * Runs the server pass without `window` and `document`, the two globals
+ * SSR-aware code probes. A DOM test environment defines both, so with them in
+ * place a `typeof window` branch takes its client side, renders the client
+ * HTML, and the mismatch it causes in production hydrates clean. `fn` must be
+ * synchronous (renderToString, not a streaming entry): nothing else may run
+ * while they are gone.
+ */
+function withoutBrowserGlobals<T>(fn: () => T): T {
+  const scope = globalThis as { window?: unknown; document?: unknown };
+  const windowDescriptor = Object.getOwnPropertyDescriptor(scope, "window")!;
+  const documentDescriptor = Object.getOwnPropertyDescriptor(
+    scope,
+    "document",
+  )!;
+  try {
+    delete scope.window;
+    delete scope.document;
+    return fn();
+  } finally {
+    Object.defineProperty(scope, "window", windowDescriptor);
+    Object.defineProperty(scope, "document", documentDescriptor);
+  }
 }
 
 function makeMetadata(

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

@@ -44,6 +44,8 @@ import {
   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,
@@ -77,6 +79,22 @@ export interface ServeShellRequestOptions<TEnv = any> {
   partial?: true | { from?: string; segments?: readonly string[] };
 }
 
+/** 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}. */
 export interface ServeShellRequestResult {
   /** The handler's Response. Its body is already read: see `body`. */
@@ -113,6 +131,11 @@ 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>;
 }
 
 type ShellHandler = ReturnType<typeof createRSCHandler>;
@@ -203,8 +226,39 @@ const SSR_STUB: SSRModule = {
   },
 };
 
-/** Handlers per router, keyed by the `cacheStore` override or the router. */
-const handlers = new WeakMap<object, WeakMap<object, ShellHandler>>();
+type HandleChannel = AsyncIterable<HandleData> | undefined;
+
+/**
+ * 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 { deserializeResult } = await import("../cache/segment-codec.js");
+  const { metadata } = await deserializeResult<{
+    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 };
+}
+
+/**
+ * Handlers per router, keyed by the `cacheStore` override or the router. A
+ * handler resolves its router's versions when it is created, so an entry is
+ * reused only while the router would still resolve the versions it was made
+ * with: a setBuildVersions() call (a simulated deploy) that changes them gets
+ * a new handler.
+ */
+const handlers = new WeakMap<
+  object,
+  WeakMap<object, { handler: ShellHandler; versions: string }>
+>();
 
 async function getHandler(
   router: Rango<any, any>,
@@ -212,10 +266,21 @@ 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 { data, document } = resolveRouterVersions(
+    internal.id,
+    internal.version,
+  );
+  const versions = `${data}\0${document}`;
   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,11 +295,10 @@ 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;
 }
 
@@ -358,16 +422,18 @@ export async function serveShellRequest<TEnv = any>(
   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 +443,8 @@ export async function serveShellRequest<TEnv = any>(
       });
       return read?.entry ?? null;
     },
+    async readHandles() {
+      return flight ? decodePayloadHandles(flight) : 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/types/handler-context.ts

@@ -462,11 +462,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;
   /**