@rangojs/router 0.33.1 → 0.34.0

package/src/router/segment-resolution/prefetch-deferral.ts

@@ -1,6 +1,9 @@
 /**
- * `prefetch: false`: what a prefetch request defers and what its fill request
- * runs (docs/design/prefetch-false.md).
+ * `prefetch: false` and `prefetch: "intent"`: what a prefetch request defers
+ * and what its fill request runs (docs/design/prefetch-false.md). A
+ * speculative prefetch (viewport, render) defers both flags; an intent
+ * prefetch (a hover, `prefetch()`) defers `false` only and runs `"intent"`
+ * work as if it were unflagged.
  *
  * Two layers. The SCOPE is static per matched chain: which loader
  * registrations are deferrable and which entries can be a handler unit. The
@@ -37,19 +40,19 @@ import {
 import { requestHeaders } from "../../server/request-headers.js";
 import type { HandlerContext, InternalHandlerContext } from "../../types.js";
 import type { CacheScope } from "../../cache/cache-scope.js";
-import { PREFETCH_HEADER, PREFETCH_INTENT } from "../../prefetch-markers.js";
+import {
+  PREFETCH_HEADER,
+  PREFETCH_INTENT,
+  isPrefetchFlag,
+  type PrefetchFlag,
+} from "../../prefetch-markers.js";
 import { WIRE } from "../../wire-params.js";
 import { isInterceptSegment } from "../../browser/intercept-utils.js";
 
 /**
  * What a request says it is, read once when its context is created
  * (RequestContext._requestKind). A fill is marked on the raw URL and wins
- * over the prefetch header. `"prefetch"` is a speculative prefetch (viewport,
- * render) and `"intent"` a hover or an explicit `prefetch()` call
- * (PREFETCH_INTENT): both are prefetches, and only the first defers. Whether
- * a prefetch defers anything is decided per match, by partialDeferralMode: a
- * shell capture inherits the context of the request that scheduled it and is
- * never a prefetch.
+ * over the prefetch header; an intent prefetch carries PREFETCH_INTENT.
  */
 export function requestKind(
   request: Request,
@@ -69,8 +72,8 @@ export function isPrefetchKind(kind: RequestKind | undefined): boolean {
   return kind === "prefetch" || kind === "intent";
 }
 
-/** Static, per matched chain. */
-interface DeferralScope {
+/** What one kind of prefetch can defer in a matched chain. */
+interface DeferralSet {
   /**
    * Loader registrations a prefetch can defer, each with what makes it so:
    * `true` for its own flag, else the segment ids of the flagged entries whose
@@ -78,8 +81,6 @@ interface DeferralScope {
    * segments is new to the client.
    */
   readonly loaders: ReadonlyMap<LoaderEntry, true | readonly string[]>;
-  /** `$$id`s of `loaders`: the loaders that cannot call ctx.rendered(). */
-  readonly loaderIds: ReadonlySet<string>;
   /**
    * Entries whose handler a prefetch can skip (a flagged loading() with a
    * fallback to show). `index` is the chain index that owns the entry: its
@@ -90,6 +91,24 @@ interface DeferralScope {
   readonly units: ReadonlyMap<EntryData, DeferralUnit>;
 }
 
+/**
+ * Static, per matched chain: what a speculative prefetch defers (every flag,
+ * `false` or `"intent"`), and in `intent` what an intent prefetch defers.
+ */
+interface DeferralScope extends DeferralSet {
+  /**
+   * `$$id`s of `loaders`: the loaders that cannot call ctx.rendered(). The
+   * speculative set on every request: a loader an intent prefetch runs is
+   * still run by a speculative prefetch's fill, where its handler does not.
+   */
+  readonly loaderIds: ReadonlySet<string>;
+  /**
+   * What an intent prefetch defers: the scope with every `"intent"` flag
+   * read as unflagged. Absent when no flag is `"intent"`: the scope itself.
+   */
+  readonly intent?: DeferralSet;
+}
+
 interface DeferralUnit {
   readonly index: number;
   readonly ids: readonly string[];
@@ -98,6 +117,11 @@ interface DeferralUnit {
 /** Per match: InternalHandlerContext._prefetchDeferral. */
 export interface PrefetchDeferral {
   readonly scope: DeferralScope;
+  /**
+   * What this request defers: `scope`, or `scope.intent` for an intent
+   * prefetch. The ctx.rendered() guards read `scope`.
+   */
+  readonly defers: DeferralSet;
   /**
    * "prefetch": deferral replaces execution. "fill": the request that follows
    * an adopted prefetch; a held segment is skipped outright. Unset on every
@@ -188,10 +212,36 @@ const EMPTY_SCOPE: DeferralScope = {
 
 const scopes = new WeakMap<EntryData, DeferralScope>();
 
+/** A flag an intent prefetch defers: `false` only. */
+const offFlag = (flag: PrefetchFlag | undefined): boolean => flag === false;
+/** A flag only an intent prefetch runs. */
+const intentFlag = (flag: PrefetchFlag | undefined): boolean =>
+  flag === PREFETCH_INTENT;
+
+const isEmptySet = (set: DeferralSet): boolean =>
+  set.loaders.size === 0 && set.units.size === 0;
+
+/**
+ * The scope of a collector, which returns what a prefetch whose flags
+ * `counts` accepts defers. `intent` is set only when an `"intent"` flag
+ * changes what is deferred: the collector under `intentFlag` finds something.
+ */
+function scopeOf(
+  collect: (counts: (flag: PrefetchFlag | undefined) => boolean) => DeferralSet,
+): DeferralScope {
+  const all = collect(isPrefetchFlag);
+  if (isEmptySet(all)) return EMPTY_SCOPE;
+  return {
+    ...all,
+    loaderIds: new Set([...all.loaders.keys()].map((l) => l.loader.$$id)),
+    ...(!isEmptySet(collect(intentFlag)) && { intent: collect(offFlag) }),
+  };
+}
+
 /**
  * The deferral scope of a matched chain, memoized on its leaf entry (entries
  * are per-isSSR manifest objects, replaced on HMR). EMPTY_SCOPE when nothing
- * in the tree declares `prefetch: false`.
+ * in the tree declares `prefetch: false` or `prefetch: "intent"`.
  */
 export function resolveDeferralScope(
   entries: readonly EntryData[],
@@ -200,9 +250,18 @@ export function resolveDeferralScope(
   if (!leaf) return EMPTY_SCOPE;
   const cached = scopes.get(leaf);
   if (cached) return cached;
+  const scope = scopeOf((counts) => collectDeferrable(entries, counts));
+  scopes.set(leaf, scope);
+  return scope;
+}
 
+/** What a prefetch whose flags are those `counts` accepts defers in a chain. */
+function collectDeferrable(
+  entries: readonly EntryData[],
+  counts: (flag: PrefetchFlag | undefined) => boolean,
+): DeferralSet {
+  const leaf = entries[entries.length - 1]!;
   const loaders = new Map<LoaderEntry, true | readonly string[]>();
-  const loaderIds = new Set<string>();
   const units = new Map<EntryData, DeferralUnit>();
   const chain = new Set(entries);
   // A clientUrls() group route renders loading() itself and its handler is
@@ -212,7 +271,7 @@ export function resolveDeferralScope(
   // layout's above it; a flagged loading() defers nothing.
   const clientGroupChain = leaf.clientGroup !== undefined;
   const flagsLoading = (entry: EntryData): boolean =>
-    !clientGroupChain && entry.loadingPrefetch === false;
+    !clientGroupChain && counts(entry.loadingPrefetch);
 
   // `behind`: the segment ids of the flagged entries whose fallback covers
   // `entry`'s loaders.
@@ -222,12 +281,11 @@ export function resolveDeferralScope(
     index: number,
   ): void => {
     for (const loaderEntry of entry.loader ?? []) {
-      const own = loaderEntry.prefetch === false;
+      const own = counts(loaderEntry.prefetch);
       if (!own && behind.length === 0) continue;
       // An ssr: false loader on a ppr route is in scope too: whether this
       // request serves it from a shell pin is per request (defersLoader).
       loaders.set(loaderEntry, own ? true : behind);
-      loaderIds.add(loaderEntry.loader.$$id);
     }
     for (const parallelEntry of getParallelEntries(entry.parallel)) {
       // A slot's segment id, as resolveParallelSegments
@@ -262,13 +320,7 @@ export function resolveDeferralScope(
     // A layout's fallback covers its outlet: every deeper chain entry.
     if (flagged && entry.type !== "route") behind = own;
   });
-
-  const scope: DeferralScope =
-    loaders.size === 0 && units.size === 0
-      ? EMPTY_SCOPE
-      : { loaders, loaderIds, units };
-  scopes.set(leaf, scope);
-  return scope;
+  return { loaders, units };
 }
 
 const interceptScopes = new WeakMap<InterceptEntry, DeferralScope>();
@@ -286,24 +338,21 @@ export function resolveInterceptDeferralScope(
 ): DeferralScope {
   const cached = interceptScopes.get(intercept);
   if (cached) return cached;
-  const flagged = intercept.loader.filter((l) => l.prefetch === false);
-  const scope: DeferralScope =
-    flagged.length === 0
-      ? EMPTY_SCOPE
-      : {
-          loaders: new Map(flagged.map((l) => [l, true as const])),
-          loaderIds: new Set(flagged.map((l) => l.loader.$$id)),
-          units: new Map(),
-        };
+  const scope = scopeOf((counts) => ({
+    loaders: new Map(
+      intercept.loader
+        .filter((l) => counts(l.prefetch))
+        .map((l) => [l, true as const]),
+    ),
+    units: new Map(),
+  }));
   interceptScopes.set(intercept, scope);
   return scope;
 }
 
 /**
- * Which half of the feature a partial request is, if either (`fill` and
- * `prefetch` are requestKind's answer). `prefetch` is a speculative prefetch
- * only: an intent prefetch defers nothing, like the navigation it starts
- * early (R16). Both halves are GETs: a request of
+ * The kind a partial request plans its deferral as, if any (requestKind's
+ * answer, filtered). Both halves of the feature are GETs: a request of
  * another method that carries either marker is a normal request. A prefetch
  * defers only on a plain GET navigation: an action re-renders what it
  * changed, and a shell capture is never a prefetch whatever the request that
@@ -311,17 +360,20 @@ export function resolveInterceptDeferralScope(
  * capture runs the full match): each one states its own reason.
  */
 export function partialDeferralMode(request: {
-  fill: boolean;
-  prefetch: boolean;
+  kind: RequestKind | undefined;
   method: string;
   isAction: boolean;
   isShellCapture: boolean;
-}): PrefetchDeferral["mode"] {
+}): RequestKind | undefined {
   if (request.method !== "GET") return undefined;
-  if (request.fill) return "fill";
-  return request.prefetch && !request.isAction && !request.isShellCapture
-    ? "prefetch"
-    : undefined;
+  if (request.kind === "fill") return "fill";
+  if (
+    isPrefetchKind(request.kind) &&
+    (request.isAction || request.isShellCapture)
+  ) {
+    return undefined;
+  }
+  return request.kind;
 }
 
 export const NOTHING_HELD: ReadonlySet<string> = new Set();
@@ -331,16 +383,22 @@ export const NOTHING_HELD: ReadonlySet<string> = new Set();
  * request is not a fill (the common case: nothing to carry). `held` is the
  * client's segment ids as the request listed them. `scope` is the chain's
  * unless the request resolves an intercept (resolveInterceptDeferralScope).
+ * An intent prefetch plans as a prefetch over `scope.intent`: a tree whose
+ * flags are all `"intent"` defers nothing in it, and its response is the
+ * navigation's (no `_payloadDeferred`, so no source scope).
  */
 export function planPrefetchDeferral(
   entries: readonly EntryData[],
-  mode: PrefetchDeferral["mode"],
+  requested: RequestKind | undefined,
   matched: { pr?: boolean; od?: boolean },
   cacheScope: CacheScope | null | undefined,
   held: ReadonlySet<string> = NOTHING_HELD,
   scope: DeferralScope = resolveDeferralScope(entries),
 ): PrefetchDeferral | undefined {
-  if (scope === EMPTY_SCOPE && mode !== "fill") return undefined;
+  if (scope === EMPTY_SCOPE && requested !== "fill") return undefined;
+  const mode = requested === "intent" ? "prefetch" : requested;
+  const defers: DeferralSet =
+    requested === "intent" ? (scope.intent ?? scope) : scope;
 
   const leaf = entries[entries.length - 1];
   let storedFrom = Infinity;
@@ -368,7 +426,7 @@ export function planPrefetchDeferral(
   const skipped = new Set<string>();
   let skipsChain = false;
   if (mode === "prefetch") {
-    for (const [entry, unit] of scope.units) {
+    for (const [entry, unit] of defers.units) {
       if (!unitEligible(storedFrom, entry, unit)) continue;
       for (const id of unit.ids) {
         if (held.has(id)) continue;
@@ -382,7 +440,7 @@ export function planPrefetchDeferral(
     write: !skipsChain,
     refresh: mode !== "fill",
   };
-  return { scope, mode, storedFrom, held, skipped, record };
+  return { scope, defers, mode, storedFrom, held, skipped, record };
 }
 
 export function getPrefetchDeferral(
@@ -529,7 +587,7 @@ export function defersLoader(
 ): boolean {
   const plan = getPrefetchDeferral(ctx);
   if (plan?.mode !== "prefetch" || plan.held.has(segmentId)) return false;
-  const by = plan.scope.loaders.get(loaderEntry);
+  const by = plan.defers.loaders.get(loaderEntry);
   const deferrable =
     by === true || (by !== undefined && by.some((id) => !plan.held.has(id)));
   return deferrable && !servesPin(loaderEntry);

package/src/rsc/rsc-rendering.ts

@@ -1120,7 +1120,7 @@ function renderPreparedRscResponse<TEnv>(
 
   const rscHeaders: Record<string, string> = {
     "content-type": "text/x-component;charset=utf-8",
-    vary: `accept, X-Rango-State, X-RSC-Router-Client-Path, ${SEGMENT_FRAGMENT_CAPABILITY_HEADER}, ${SEGMENT_FRAGMENT_RECOVERY_HEADER}`,
+    vary: `accept, X-Rango-State, X-RSC-Router-Client-Path, X-RSC-Router-Intercept-Source, ${SEGMENT_FRAGMENT_CAPABILITY_HEADER}, ${SEGMENT_FRAGMENT_RECOVERY_HEADER}`,
     // Router identity, so the client can verify pre-decode (before importing
     // chunks) that this content payload belongs to its app and refuse a
     // foreign one (cache/proxy/bug). Control-only reload/redirect responses

package/src/server/context.ts

@@ -14,6 +14,7 @@ import type {
 import { invariant, DslContextError } from "../errors";
 import type { DefaultRouteName } from "../types/global-namespace.js";
 import type { ContextVar } from "../context-var.js";
+import type { PrefetchFlag } from "../prefetch-markers.js";
 import { PPR_LANE_HINT } from "../rsc/shell-capture-constants.js";
 import type { ShellCaptureState } from "../rsc/shell-capture.js";
 import {
@@ -125,13 +126,13 @@ export type EntryPropDatas = {
 export type EntryPropRender = {
   loading?: ReactNode | false;
   /**
-   * loading(fallback, { prefetch: false }) with a renderable fallback: a
-   * speculative prefetch defers what the fallback covers while the entry's
+   * loading(fallback, { prefetch: false | "intent" }) with a renderable
+   * fallback: a prefetch defers what the fallback covers while the entry's
    * segment is new to the client
    * (router/segment-resolution/prefetch-deferral.ts). Set on both DSL
    * evaluations, whatever `ssr` did to `loading`.
    */
-  loadingPrefetch?: false;
+  loadingPrefetch?: PrefetchFlag;
   /**
    * loading(fallback, { ssr: false }), on both DSL evaluations; a document
    * then sets `loading` to false (applyDocumentModeLoading).
@@ -172,11 +173,11 @@ export type LoaderEntry = {
    */
   bake?: true;
   /**
-   * loader(Def, { prefetch: false }): a speculative prefetch defers this
+   * loader(Def, { prefetch: false | "intent" }): a prefetch defers this
    * registration while its segment is new to the client
    * (router/segment-resolution/prefetch-deferral.ts).
    */
-  prefetch?: false;
+  prefetch?: PrefetchFlag;
   /**
    * The declaring layout's / parallel's / cache()'s include scope, for the
    * loader body's `ctx.reverse(".name")` (its DSL kickoff carries it,

package/src/testing/render-route.tsx

@@ -45,6 +45,13 @@
  *     lane production's Back uses (useNavigation() idle), with the loader
  *     data current then. The prefetch request, its decode and the HTTP cache
  *     are e2e territory.
+ *   - useLoader().load() and a refreshGroup refresh reach the loader endpoint:
+ *     renderRoute answers a GET for `_rsc_loader=<id>` with the last value the
+ *     test gave that loader (the render seeds or respondToLoads()),
+ *     unencoded; a pending Promise holds the answer until it settles, and a
+ *     rejection is the loader's error. Needs the testing kit's
+ *     `@vitejs/plugin-rsc/browser` alias (rangoTestAliases). A load() with params
+ *     is answered with a loaderError; a body and non-GET loads are not answered.
  *   - A spec's transition({ when }) decides every commit with production's
  *     browser decision: navigate() and useRouter().push model kind "push",
  *     useRouter().replace kind "replace", refresh() kind "revalidate", and a
@@ -128,14 +135,18 @@ import {
   buildHistoryState,
   applyDocumentLocationState,
   clearLocationStateOnDocumentLoad,
+  keptEntryState,
   pushHistoryWithIdx,
   resolveNavigationState,
+  shownLocationState,
 } from "../browser/history-state.js";
 import { withLocationStateKey } from "./location-state-key.js";
 import type { Handle } from "../handle.js";
 import type { ThemeConfig } from "../theme/types.js";
 import { resolveThemeConfig } from "../theme/constants.js";
 import { isUnderTestRunner } from "../runtime-env.js";
+import { loaderAnswerResponse } from "./vitest-stubs/plugin-rsc-browser.js";
+import { WIRE } from "../wire-params.js";
 import {
   scheduleStalePrefetchRevalidation,
   setupNavigationBridgeDelegatedPrefetch,
@@ -532,8 +543,10 @@ export interface TestRouterHandle {
   /**
    * Re-render the current location, as router.refresh() does: a spec's
    * transition({ when }) decides it with kind "revalidate" (`to` is `from`).
+   * `options.loaders` is the loader data the response carries, merged over
+   * the render-time seeds as in navigate().
    */
-  refresh(): Promise<void>;
+  refresh(options?: Pick<RenderRouteOptions, "loaders">): Promise<void>;
   /**
    * Prefetch `url`, as a `<Link>` hover or viewport trigger does: the page is
    * kept with the loader data its response would carry now (the render-time
@@ -575,6 +588,17 @@ export interface TestRouterHandle {
       keepClientCache?: boolean;
     },
   ): Promise<void>;
+  /**
+   * Set what the loader endpoint answers from now on: a later
+   * `useLoader().load()` or refreshGroup refresh of each loader resolves to
+   * its value (a pending Promise holds the answer, a rejection is the
+   * loader's error). Renders nothing; the page on screen keeps its data.
+   *
+   * @example
+   * router.respondToLoads({ loaders: [[CartLoader, { count: 3 }]] });
+   * fireEvent.click(getByText("Refresh")); // load(): count 3
+   */
+  respondToLoads(options: Pick<RenderRouteOptions, "loaders">): void;
   /**
    * The background revalidations a click on a stale prefetch started, in
    * order: the page's pathname and search, and the segment ids the request
@@ -689,6 +713,38 @@ function LinkInterceptionRegistration({
   return null;
 }
 
+/**
+ * The loader endpoint `useLoader().load()` fetches (`_rsc_loader=<id>`):
+ * installed on `fetch` while the tree is mounted, every other request passed
+ * through. A test that stubs `fetch` after the mount replaces it.
+ */
+function LoaderEndpoint({
+  answer,
+}: {
+  answer: (loaderId: string, hasParams: boolean) => Promise<Response>;
+}): null {
+  useEffect(() => {
+    const passThrough = globalThis.fetch;
+    // useLoader fetches with a URL string and an init.
+    const endpoint: typeof fetch = (input, init) => {
+      const url = new URL(String(input), TEST_ORIGIN);
+      const loaderId = url.searchParams.get(WIRE.loader);
+      if (
+        loaderId !== null &&
+        (init?.method ?? "GET").toUpperCase() === "GET"
+      ) {
+        return answer(loaderId, url.searchParams.has(WIRE.loaderParams));
+      }
+      return passThrough(input, init);
+    };
+    globalThis.fetch = endpoint;
+    return () => {
+      if (globalThis.fetch === endpoint) globalThis.fetch = passThrough;
+    };
+  }, [answer]);
+  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
@@ -841,6 +897,43 @@ export async function renderRoute(
     return out;
   };
   const loaderData = seedLoaders(options.loaderData ?? {}, options.loaders);
+  // What the loader endpoint answers (LoaderEndpoint): the render seeds, then
+  // what respondToLoads() gave each loader.
+  const loadAnswers: Record<string, unknown> = { ...loaderData };
+  // The payload has rsc/loader-fetch.ts's shape; the value is taken when the
+  // request is made, as a server reads its data then.
+  const answerLoad = async (
+    loaderId: string,
+    hasParams: boolean,
+  ): Promise<Response> => {
+    type Answer = Parameters<typeof loaderAnswerResponse>[0];
+    const failure = (name: string, message: string): Answer => ({
+      loaderResult: null,
+      loaderError: { name, message },
+    });
+    let payload: Answer;
+    if (hasParams) {
+      payload = failure(
+        "Error",
+        `renderRoute does not answer parameterized load() calls (loader "${loaderId}"). Call load() without params, or stub fetch.`,
+      );
+    } else if (!(loaderId in loadAnswers)) {
+      payload = failure(
+        "Error",
+        `renderRoute: no value for loader "${loaderId}". Seed it with \`loaders\` or router.respondToLoads().`,
+      );
+    } else {
+      try {
+        payload = { loaderResult: await loadAnswers[loaderId] };
+      } catch (error) {
+        payload = failure(
+          error instanceof Error ? error.name : "Error",
+          error instanceof Error ? error.message : String(error),
+        );
+      }
+    }
+    return loaderAnswerResponse(payload);
+  };
 
   if (typeof window !== "undefined") {
     // The tree has no app version (its bridge reports none), so a seed needs
@@ -967,6 +1060,8 @@ export async function renderRoute(
     kind?: TransitionWhenKind;
     transition?: boolean;
     streamUntil?: Promise<unknown>;
+    /** refresh(): a commit onto the entry on screen. */
+    sameEntry?: boolean;
   };
 
   // The page each history entry shows, by the entry's `idx` stamp (the
@@ -1120,7 +1215,7 @@ export async function renderRoute(
     // 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.
+    // `replace: true` leaves history alone.
     const history = navOptions?.history;
     const historyState = history
       ? buildHistoryState(
@@ -1199,6 +1294,18 @@ export async function renderRoute(
         history.replace ?? false,
       );
       eventController.commitLocationState(historyState);
+    } else if (navOptions?.sameEntry) {
+      // refresh() commits onto the entry on screen as production's does
+      // (navigation-transaction.ts sameEntry): the entry keeps its location
+      // state, readers keep what they show.
+      pushHistoryWithIdx(
+        keptEntryState(window.history.state),
+        window.location.href,
+        true,
+      );
+      eventController.commitLocationState(
+        shownLocationState(eventController.getLocationState()),
+      );
     }
     entryOnScreen = entryIndex();
     entries.set(entryOnScreen, {
@@ -1229,9 +1336,15 @@ export async function renderRoute(
     });
   };
 
-  const refresh = (): Promise<void> => {
+  const refresh = (
+    refreshOptions?: Pick<RenderRouteOptions, "loaders">,
+  ): Promise<void> => {
     const current = new URL(eventController.getLocation().href);
-    return navigate(current.pathname + current.search, { kind: "revalidate" });
+    return navigate(current.pathname + current.search, {
+      kind: "revalidate",
+      loaders: refreshOptions?.loaders,
+      sameEntry: true,
+    });
   };
 
   // prefetch(): the pages prefetched so far, by pathname and search, each with
@@ -1358,9 +1471,7 @@ export async function renderRoute(
       keepClientCache?: boolean;
     },
   ): Promise<void> => {
-    for (const [loader, data] of actionOptions?.loaders ?? []) {
-      loaderData[ensureSyntheticId(loader)] = data;
-    }
+    Object.assign(loaderData, seedLoaders({}, actionOptions?.loaders));
     const page = await renderPageAgain(
       new URL(eventController.getLocation().href),
       "action",
@@ -1508,6 +1619,7 @@ export async function renderRoute(
       />
       <DelegatedPrefetchRegistration bridge={bridge} />
       <LinkInterceptionRegistration bridge={bridge} />
+      <LoaderEndpoint answer={answerLoad} />
       {options.hydrate && <HydratedMarker />}
       {applyLateHandles && <AfterTree run={applyLateHandles} />}
       {resolveDocumentRevealed && <AfterTree run={resolveDocumentRevealed} />}
@@ -1587,6 +1699,9 @@ export async function renderRoute(
     refresh,
     prefetch,
     action,
+    respondToLoads: (respondOptions) => {
+      Object.assign(loadAnswers, seedLoaders({}, respondOptions.loaders));
+    },
     revalidations: () => [...revalidations],
     pathname: () => new URL(eventController.getLocation().href).pathname,
     params: () => eventController.getParams(),

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

@@ -100,13 +100,13 @@ export interface ServeShellRequestOptions<TEnv = any> {
    * `result.replayStatus`.
    *
    * `prefetch: true` sends the speculative kind a viewport or render
-   * `<Link>` prefetch sends (`X-Rango-Prefetch: 1`), so `prefetch: false`
-   * loaders and `loading()` entries are deferred: `result.readDeferred()`
-   * lists them. A hover's or `prefetch()`'s intent prefetch defers nothing;
-   * serve it with `prefetch: true` and `headers: { "X-Rango-Prefetch":
-   * "intent" }`, which `prefetch: true` leaves as given. `fill: true`
-   * sends the request the browser follows an adopted prefetch with
-   * (`_rsc_fill`): pass the ids the prefetch delivered, without the deferred
+   * `<Link>` prefetch sends (`X-Rango-Prefetch: 1`), so loaders and
+   * `loading()` entries flagged `prefetch: false` or `"intent"` are deferred:
+   * `result.readDeferred()` lists them. A hover's intent prefetch defers
+   * `false` only; serve it with `prefetch: true` and `headers: {
+   * "X-Rango-Prefetch": "intent" }`, which `prefetch: true` leaves as given.
+   * `fill: true` sends the request the browser follows an adopted prefetch
+   * with (`_rsc_fill`): pass the ids the prefetch delivered, without the deferred
    * ones, as `segments`, and the same URL as `from`. `interceptSource` sends
    * the intercept source (`X-RSC-Router-Intercept-Source`) the browser sends
    * from an open modal and with the fill of an intercept, whose `from` is

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

@@ -0,0 +1,61 @@
+/**
+ * Stub for `@vitejs/plugin-rsc/browser`, shipped so consumers do not have to
+ * write a per-file `vi.mock(...)`. The real entry imports the
+ * `virtual:vite-rsc/client-references` Vite virtual at the top level, which a
+ * bare Vitest process cannot resolve.
+ *
+ * The router reaches this module from `useLoader().load()` and a
+ * `refreshGroup` refresh (use-loader.tsx imports deps/browser.ts lazily).
+ * renderRoute answers those requests (render-route.tsx), and a DOM test has
+ * no Flight server to encode an answer: renderRoute's seeds are client values
+ * already. So the answer travels with its Response object, and
+ * `createFromFetch` hands it back unchanged, as a decoded payload. Any other
+ * response is rejected. The remaining exports exist for the re-export in
+ * deps/browser.ts; navigations, actions and the document are not decoded
+ * here.
+ */
+
+const answers = new WeakMap<object, unknown>();
+
+/**
+ * A loader endpoint Response whose decoded payload is `payload`
+ * (`{ loaderResult }` or `{ loaderResult: null, loaderError }`, as
+ * rsc/loader-fetch.ts answers).
+ */
+export function loaderAnswerResponse(payload: {
+  loaderResult: unknown;
+  loaderError?: { message: string; name: string };
+}): Response {
+  const response = new Response(null, {
+    headers: { "content-type": "text/x-component" },
+  });
+  answers.set(response, payload);
+  return response;
+}
+
+export async function createFromFetch<T>(
+  response: Promise<Response> | Response,
+): Promise<T> {
+  const settled = await response;
+  if (!answers.has(settled)) {
+    throw new Error(
+      "@vitejs/plugin-rsc/browser test stub: createFromFetch decodes only " +
+        "the loader answers renderRoute gives (useLoader().load(), a " +
+        "refreshGroup refresh). Real Flight responses are e2e territory.",
+    );
+  }
+  return answers.get(settled) as T;
+}
+
+function unavailable(name: string): never {
+  throw new Error(
+    `@vitejs/plugin-rsc/browser test stub: ${name} is not available in a ` +
+      "bare Vitest process. Real Flight responses are e2e territory.",
+  );
+}
+
+export const createFromReadableStream = (): Promise<never> =>
+  unavailable("createFromReadableStream");
+export const encodeReply = (): Promise<never> => unavailable("encodeReply");
+export const setServerCallback = (): void => {};
+export const createTemporaryReferenceSet = (): unknown => new Map();

package/src/testing/vitest.ts

@@ -229,6 +229,11 @@ export function rangoTestAliases(
       find: /^@vitejs\/plugin-rsc\/rsc(\/(server|client))?$/,
       replacement: here("src/testing/vitest-stubs/plugin-rsc.ts"),
     },
+    // useLoader().load() decodes renderRoute's loader answers through it.
+    {
+      find: /^@vitejs\/plugin-rsc\/browser$/,
+      replacement: here("src/testing/vitest-stubs/plugin-rsc-browser.ts"),
+    },
   ];
   if (rsdServerEdgePath) {
     aliases.push({