@rangojs/router 0.31.0 → 0.33.0

package/src/testing/render-route.tsx

@@ -35,6 +35,16 @@
  *     not modeled). navigate(url, { streamUntil }) gives the navigation a
  *     response stream that stays open past the commit (isStreaming).
  *     useAction().state stays idle: no action runs.
+ *   - prefetch(url) keeps a page as a prefetch made now carries it, and
+ *     action() lands a server action's response: the page on screen
+ *     re-renders with its post-write loader data, and, without
+ *     `keepClientCache`, production's store marks every history entry and
+ *     prefetch stale (browser/navigation-store.ts). A navigate(url) to a
+ *     prefetched page commits the prefetch's data; when an action made it
+ *     stale, the page then revalidates once the navigation settled, in the
+ *     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.
  *   - 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
@@ -49,8 +59,8 @@
  *     written there, and another page is on screen, its page is restored
  *     from the history cache, with the handle values it had, as production's
  *     restore is; otherwise the tree keeps its location. A stale entry's
- *     revalidation, a restore that fetches, a server action's state, a
- *     redirect's and an intercept's are e2e territory.
+ *     revalidation on Back, a restore that fetches, a server action's
+ *     location 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
@@ -116,6 +126,7 @@ import {
 } from "../browser/react/location-state-shared.js";
 import {
   buildHistoryState,
+  applyDocumentLocationState,
   clearLocationStateOnDocumentLoad,
   pushHistoryWithIdx,
   resolveNavigationState,
@@ -125,10 +136,17 @@ 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 { setupNavigationBridgeDelegatedPrefetch } from "../browser/navigation-bridge.js";
+import {
+  scheduleStalePrefetchRevalidation,
+  setupNavigationBridgeDelegatedPrefetch,
+} from "../browser/navigation-bridge.js";
 import { resetPrefetchObserverForTesting } from "../browser/prefetch/observer.js";
 import type { PrefetchStrategy } from "../router/prefetch-default.js";
 import { auditTreeCause, forgetSuspenseAudit } from "../suspense-audit.js";
+import {
+  currentPrefetchEpoch,
+  isPrefetchStale,
+} from "../browser/prefetch/cache.js";
 
 const TEST_ORIGIN = "http://localhost";
 let activePrefetchRegistrations = 0;
@@ -274,6 +292,25 @@ export interface RenderRouteOptions {
   locationState?: ReadonlyArray<
     readonly [LocationStateDefinition<any, any>, unknown]
   >;
+  /**
+   * Location state the document response carries, as `[def, value]` pairs:
+   * what a handler, middleware or no-JS form action set with
+   * `ctx.setLocationState()` (or a document redirect carried) for this page
+   * load. Merged into the entry at start-up as initBrowserApp merges the
+   * bootstrap payload's: after `locationState` and, with `hydrate: true`,
+   * after the `clearOnReload` pass, so a `clearOnReload` slot given here is
+   * applied. With `hydrate: true` a reader hydrates as `undefined` and gets
+   * the value once the root has hydrated.
+   *
+   * @example
+   * await renderRoute([{ path: "/", Component: FlashBanner }], {
+   *   hydrate: true,
+   *   documentLocationState: [[FlashMessage, { text: "Payment declined" }]],
+   * });
+   */
+  documentLocationState?: ReadonlyArray<
+    readonly [LocationStateDefinition<any, any>, unknown]
+  >;
   /**
    * Handles to seed by REFERENCE, for components that read handle output via
    * `useHandle(SomeHandle)` (e.g. a client `Breadcrumbs` trail). Each entry is
@@ -497,6 +534,59 @@ export interface TestRouterHandle {
    * transition({ when }) decides it with kind "revalidate" (`to` is `from`).
    */
   refresh(): 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
+   * seeds, `options.loaders` merged over). A later `navigate(url)` without
+   * `loaders` commits that data, whatever the seeds are by then.
+   *
+   * The prefetch is stamped with production's stale epoch
+   * (browser/prefetch/cache.ts): an `action()` without `keepClientCache`
+   * makes it stale. A click on a stale prefetch commits it at once, then the
+   * page revalidates once the navigation settled (its `streamUntil` ended),
+   * in Back's stale-revalidation lane: `useNavigation().state` stays "idle"
+   * and `isNavigating` reads true while its request is open, `useLinkStatus`
+   * shows no pending state, and the commit runs through commitInTransition
+   * with kind "revalidate", reading the loader data current then. A newer
+   * navigation aborts it.
+   *
+   * @example
+   * router.prefetch("/cart"); // carries count 2
+   * await router.action({ loaders: [[BasketLoader, { count: 3 }]] });
+   * await router.navigate("/cart"); // count 2, at once
+   * await waitFor(() => expect(count()).toBe("3")); // revalidated
+   */
+  prefetch(url: string, options?: Pick<RenderRouteOptions, "loaders">): void;
+  /**
+   * Land a server action's response on the page on screen. `loaders` are the
+   * loader values after the action's write: they become the data every
+   * later response carries, and the page on screen re-renders with them in
+   * the action lane (commitInTransition, kind "action", unless
+   * transition({ when }) gates it off). Without `keepClientCache`,
+   * production's store then marks every history entry and every prefetch
+   * stale (`markCacheAsStaleAndBroadcast()`), as the action bridge does:
+   * nothing is flushed and the state cookie is not rotated.
+   * `keepClientCache: true` is the `keepClientCache()` directive: caches stay
+   * fresh. The action's own lifecycle (`useAction()`), its follow-up and its
+   * redirect are e2e territory.
+   */
+  action(
+    options?: Pick<RenderRouteOptions, "loaders"> & {
+      keepClientCache?: boolean;
+    },
+  ): Promise<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
+   * holds, as production's bridge plans them
+   * (navigation-bridge.ts scheduleStalePrefetchRevalidation). A click on a
+   * fresh prefetch, or after a `keepClientCache` action, starts none.
+   *
+   * @example
+   * await router.navigate("/cart"); // a stale prefetch
+   * await waitFor(() => expect(router.revalidations()).toHaveLength(1));
+   */
+  revalidations(): ReadonlyArray<{ url: string; segmentIds: string[] }>;
   /** The current committed pathname. */
   pathname(): string;
   /** The current committed params. */
@@ -510,6 +600,19 @@ export interface TestRouterHandle {
 /** Result of renderRoute: RTL's render result plus the router handle. */
 export type RenderRouteResult = RenderResult & { router: TestRouterHandle };
 
+/** `[def, value]` seeds as `history.state` slots, each def keyed. */
+function locationStateSlots(
+  seeds:
+    | ReadonlyArray<readonly [LocationStateDefinition<any, any>, unknown]>
+    | undefined,
+): Record<string, unknown> {
+  const slots: Record<string, unknown> = {};
+  for (const [def, value] of seeds ?? []) {
+    slots[withLocationStateKey(def).__rsc_ls_key] = value;
+  }
+  return slots;
+}
+
 /** Result of renderRoute with `hydrate: true`. */
 export type RenderRouteHydrateResult = RenderRouteResult & {
   /** The HTML the server pass produced, as placed in the container. */
@@ -743,14 +846,15 @@ export async function renderRoute(
     // 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, "");
+    window.history.replaceState(locationStateSlots(options.locationState), "");
     // Hydrate mode is a document load of the seeded entry: run start-up's
-    // step (initBrowserApp), not a copy of it.
+    // steps (initBrowserApp), not a copy of them.
     if (options.hydrate) clearLocationStateOnDocumentLoad();
+    if (options.documentLocationState) {
+      applyDocumentLocationState(
+        locationStateSlots(options.documentLocationState),
+      );
+    }
   }
 
   const resolve = (pathname: string): ResolvedMatch => {
@@ -857,6 +961,8 @@ export async function renderRoute(
   }
 
   type NavigateCall = Pick<RenderRouteOptions, "loaders" | "handles"> & {
+    /** The loader data the response carries: a prefetch's (prefetch()). */
+    seeds?: Record<string, unknown>;
     history?: Pick<NavigateOptionsInternal, "state" | "replace" | "transition">;
     kind?: TransitionWhenKind;
     transition?: boolean;
@@ -897,6 +1003,30 @@ export async function renderRoute(
     const written = entries.get(entryIndex());
     if (written) written.state = window.history.state;
   });
+  /**
+   * The history-cache reads production's stale-prefetch guards make
+   * (navigation-bridge.ts scheduleStalePrefetchRevalidation), over this
+   * harness's history: the store's own history key never moves here, so the
+   * key on screen is its location's, and the one cached page is the entry on
+   * screen. Marking it stale writes nothing: a stale entry's revalidation on
+   * Back is not modeled.
+   */
+  const historyView: Pick<
+    NavigationStore,
+    "getCachedSegments" | "getHistoryKey" | "updateCacheHandleData"
+  > = {
+    getHistoryKey: () => generateHistoryKey(eventController.getLocation().href),
+    getCachedSegments: (key) => {
+      const page = entries.get(entryOnScreen);
+      if (!page || generateHistoryKey(page.url.href) !== key) return undefined;
+      return {
+        segments: page.segments,
+        stale: false,
+        handleData: page.handleData,
+      };
+    },
+    updateCacheHandleData: () => {},
+  };
   /** The page being left keeps its pushes for a back/forward onto it. */
   const leaveEntry = (): void => {
     const left = entries.get(entryOnScreen);
@@ -911,9 +1041,38 @@ export async function renderRoute(
     target: string,
     navOptions?: NavigateCall,
   ): Promise<void> => {
+    // A click on a prefetched page commits the prefetch's data (prefetch());
+    // refresh() and a navigation that seeds its own loaders fetch.
+    const prefetchedPage =
+      navOptions?.kind === undefined && navOptions?.loaders === undefined
+        ? prefetchedPages.get(prefetchKeyOf(target))
+        : undefined;
+    if (prefetchedPage) {
+      navOptions = { ...navOptions, seeds: prefetchedPage.loaderData };
+      // A stale entry is served once (cache.ts consumePrefetch): the next
+      // click on the link fetches fresh.
+      if (isPrefetchStale(prefetchedPage)) {
+        prefetchedPages.delete(prefetchKeyOf(target));
+      }
+    }
     const handle = eventController.startNavigation(
       new URL(target, TEST_ORIGIN).href,
     );
+    // An action made the prefetch stale: once this navigation settled (its
+    // commit and its stream), the page revalidates. Production's own guards
+    // and plan decide it (navigation-bridge.ts
+    // scheduleStalePrefetchRevalidation), over the history this harness
+    // keeps (historyView).
+    const entry = eventController.getUnsettledNavigation();
+    if (prefetchedPage && isPrefetchStale(prefetchedPage) && entry) {
+      scheduleStalePrefetchRevalidation(
+        historyView,
+        eventController,
+        entry,
+        generateHistoryKey(new URL(target, TEST_ORIGIN).href),
+        ({ segmentIds }) => void revalidateStalePrefetch(target, segmentIds),
+      );
+    }
     // Runs in the caller's task, so a <Link> click's own act() takes it.
     // Awaited: React retries a held page with this update, and an unawaited
     // act() drops that suspended retry for good.
@@ -975,7 +1134,7 @@ export async function renderRoute(
     const segments = buildSegments(
       routes,
       match.params,
-      seedLoaders(loaderData, navOptions?.loaders),
+      seedLoaders(navOptions?.seeds ?? loaderData, navOptions?.loaders),
       mount,
     );
     const metadata = makeMetadata(nextUrl.pathname, segments, match.params);
@@ -1075,6 +1234,143 @@ export async function renderRoute(
     return navigate(current.pathname + current.search, { kind: "revalidate" });
   };
 
+  // prefetch(): the pages prefetched so far, by pathname and search, each with
+  // the loader data its response carried and the stale epoch it began under.
+  interface PrefetchedPage {
+    loaderData: Record<string, unknown>;
+    epoch: number;
+  }
+  const prefetchedPages = new Map<string, PrefetchedPage>();
+  const prefetchKeyOf = (target: string): string => {
+    const parsed = new URL(target, TEST_ORIGIN);
+    return parsed.pathname + parsed.search;
+  };
+  const prefetch = (
+    target: string,
+    prefetchOptions?: Pick<RenderRouteOptions, "loaders">,
+  ): void => {
+    prefetchedPages.set(prefetchKeyOf(target), {
+      loaderData: seedLoaders(loaderData, prefetchOptions?.loaders),
+      epoch: currentPrefetchEpoch(),
+    });
+  };
+
+  /**
+   * Re-render the page at `url` with the loader data current now, decided by
+   * transition({ when }) as `kind`. `commit()` hands it over as production's
+   * action and stale-revalidation commits do (browser/partial-update.ts):
+   * through commitInTransition unless gated off.
+   */
+  const renderPageAgain = async (
+    url: URL,
+    kind: "action" | "revalidate",
+    renderOptions: { forceAwait?: boolean; isAction?: boolean },
+  ): Promise<{ commit(): Promise<void> }> => {
+    const match = resolve(url.pathname);
+    const segments = buildSegments(routes, match.params, loaderData, mount);
+    const metadata = makeMetadata(url.pathname, segments, match.params);
+    const gatedOff = decideTransitionGatedOff(segments, () => ({
+      kind,
+      from: {
+        url: eventController.getLocation().href,
+        params: eventController.getParams(),
+        routeName: leaf.name,
+        state: window.history.state,
+      },
+      to: {
+        url,
+        params: match.params,
+        routeName: leaf.name,
+        state: window.history.state,
+      },
+    }));
+    const root = await renderSegments(segments, {
+      ...renderOptions,
+      outletPending: options.outletPending,
+      transitionGatedOff: gatedOff,
+    });
+    return {
+      commit: async () => {
+        store.setSegmentIds(segments.map((s) => s.id));
+        const shown = entries.get(entryOnScreen);
+        if (shown) shown.segments = segments;
+        const emit: UpdateSubscriber = (update) => store.emitUpdate(update);
+        await act(async () => {
+          auditTreeCause(kind === "action" ? "action" : "stale-revalidation");
+          if (gatedOff) emit({ root, metadata });
+          else {
+            commitInTransition(
+              store.loaders,
+              emit,
+              segments,
+              { root, metadata },
+              kind,
+              shouldStartViewTransition(segments, gatedOff) ? ["action"] : [],
+            );
+          }
+        });
+      },
+    };
+  };
+
+  /**
+   * Back's stale-revalidation lane (navigation-bridge.ts revalidateInBackground),
+   * after a click on a stale prefetch: a background navigation
+   * (skipLoadingState) whose response arrives a task later, rendered with
+   * the loader data current then, kind "revalidate". `segmentIds` are the
+   * ids production's plan holds; the request is recorded (revalidations()).
+   */
+  const revalidations: Array<{ url: string; segmentIds: string[] }> = [];
+  const revalidateStalePrefetch = async (
+    target: string,
+    segmentIds: string[],
+  ): Promise<void> => {
+    const nextUrl = new URL(target, TEST_ORIGIN);
+    revalidations.push({
+      url: nextUrl.pathname + nextUrl.search,
+      segmentIds,
+    });
+    const handle = eventController.startNavigation(nextUrl.href, {
+      skipLoadingState: true,
+    });
+    try {
+      await act(() => eventController.flushRouteState());
+      // Outside act(): a navigate() the test starts meanwhile runs its own.
+      await new Promise((resolve) => setTimeout(resolve, 0));
+      if (handle.signal.aborted) return;
+      const page = await renderPageAgain(nextUrl, "revalidate", {
+        forceAwait: true,
+      });
+      if (handle.signal.aborted) return;
+      handle.complete(nextUrl);
+      await page.commit();
+    } finally {
+      await act(() => {
+        handle[Symbol.dispose]();
+        eventController.flushRouteState();
+      });
+    }
+  };
+
+  // action(): the response of a server action, landing on the page on screen.
+  const action = async (
+    actionOptions?: Pick<RenderRouteOptions, "loaders"> & {
+      keepClientCache?: boolean;
+    },
+  ): Promise<void> => {
+    for (const [loader, data] of actionOptions?.loaders ?? []) {
+      loaderData[ensureSyntheticId(loader)] = data;
+    }
+    const page = await renderPageAgain(
+      new URL(eventController.getLocation().href),
+      "action",
+      { isAction: true },
+    );
+    // The action bridge's landing (server-action-bridge.ts finalizeAction).
+    if (!actionOptions?.keepClientCache) store.markCacheAsStaleAndBroadcast();
+    await page.commit();
+  };
+
   // A back/forward onto the mounted entry or one a navigation wrote, whose
   // page is not the one on screen: its page is restored from the entry, as production's
   // history-cache restore does (navigation-bridge.ts handlePopstate). Not
@@ -1289,6 +1585,9 @@ export async function renderRoute(
             : undefined,
       }),
     refresh,
+    prefetch,
+    action,
+    revalidations: () => [...revalidations],
     pathname: () => new URL(eventController.getLocation().href).pathname,
     params: () => eventController.getParams(),
     store,

package/src/testing/run-revalidate.ts

@@ -121,7 +121,11 @@ export async function runRevalidate<TEnv = any>(
     belongsToRoute: opts.belongsToRoute ?? true,
   };
   const fns = Array.isArray(fn) ? fn : [fn];
-  return runWithRequestContext(ctx as never, () =>
+  // evaluateRevalidation marks the context it decides on (_sourceHeld); a
+  // caller's own context leaves the run as it came in.
+  const own = opts.context as Record<string, unknown> | undefined;
+  const ownHadMark = own !== undefined && "_sourceHeld" in own;
+  const decision = runWithRequestContext(ctx as never, () =>
     evaluateRevalidation({
       segment,
       prevParams: currentParams,
@@ -146,4 +150,10 @@ export async function runRevalidate<TEnv = any>(
       stale: opts.stale ?? false,
     }),
   );
+  if (own === undefined || ownHadMark) return decision;
+  try {
+    return await decision;
+  } finally {
+    delete own._sourceHeld;
+  }
 }

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

@@ -99,9 +99,12 @@ export interface ServeShellRequestOptions<TEnv = any> {
    * (default none), advertising fragment passthrough. The replay decision is
    * `result.replayStatus`.
    *
-   * `prefetch: true` sends it as a `<Link>` prefetch does (the
-   * `X-Rango-Prefetch` header), so `prefetch: false` loaders and `loading()`
-   * entries are deferred: `result.readDeferred()` lists them. `fill: true`
+   * `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
    * ones, as `segments`, and the same URL as `from`. `interceptSource` sends
@@ -269,6 +272,15 @@ export interface ServeShellRequestResult {
    * hydrates without it.
    */
   readPayloadFormState(): Promise<unknown>;
+  /**
+   * The payload's location state as the browser reads it: the slots
+   * (`Def.__rsc_ls_key` to value) a document's start-up merges into its
+   * entry (or a navigation's commit, for a `partial` request). Undefined when
+   * the payload carries none (or no Flight was rendered). A redirect carries
+   * a document request's state in a `Set-Cookie` instead: pass that cookie
+   * on the request of its target to read what the target's payload carries.
+   */
+  readLocationState(): Promise<Record<string, unknown> | undefined>;
   /**
    * For an `action` request, the call's answer as the browser reads it: its
    * result and the `revalidationError` its loaders' reruns report.
@@ -806,6 +818,13 @@ export async function serveShellRequest<TEnv = any>(
       }>(flight);
       return payload.formState;
     },
+    async readLocationState() {
+      if (!flight) return undefined;
+      const payload = await decodePayload<{
+        metadata?: { locationState?: Record<string, unknown> };
+      }>(flight);
+      return payload.metadata?.locationState;
+    },
     async readAction() {
       return flight ? decodeAction(flight) : undefined;
     },

package/src/types/handler-context.ts

@@ -381,9 +381,16 @@ export type HandlerContext<
    */
   setTheme?: (theme: Theme) => void;
   /**
-   * Attach location state entries to this response.
-   * State is delivered to the client via history.pushState and accessible
-   * through the useLocationState() hook.
+   * Attach location state entries to this response, for the useLocationState()
+   * hook to read on the entry this response renders. A client navigation
+   * delivers it with its payload; a document load (a link from outside the
+   * app, a no-JS form post) with its bootstrap payload, once the page has
+   * hydrated; a redirect carries it to its target (in a one-shot cookie on a
+   * document request). A document carrying it is sent
+   * `Cache-Control: private, no-store`.
+   *
+   * Entries accumulate across definitions; for one definition the last write
+   * wins (an earlier entry of it is replaced, not merged).
    *
    * @example
    * ```typescript
@@ -510,6 +517,16 @@ export type InternalHandlerContext<
    * request is a fill. See router/segment-resolution/prefetch-deferral.ts.
    */
   _prefetchDeferral?: import("../router/segment-resolution/prefetch-deferral.js").PrefetchDeferral;
+  /**
+   * @internal A revalidate() predicate that read the source page
+   * (`currentParams`, `currentUrl`, `fromRouteName`) kept a held segment, so
+   * this match's diff is right only for pages with equal values of what the
+   * kept decisions read (#1331). Set by evaluateRevalidation
+   * (router/revalidation.ts) and the stored-entry keep
+   * (match-middleware/cache-lookup.ts); match-result.ts turns it into
+   * `sourceHeld`, which scopes a prefetch of the response to that group.
+   */
+  _sourceHeld?: import("../router/source-reads.js").SourceHeld;
   /**
    * @internal DSL loaders registered and not started, by `$$id`: a prefetch
    * deferred them, or a pass that skips loaders (`skipLoaders`) did not run
@@ -664,7 +681,7 @@ export type IsActionFn = (...actions: ActionRef[]) => boolean;
 export type ShouldRevalidateFn<TParams = GenericParams, TEnv = any> = (args: {
   /** Route params from the page being navigated away from. */
   currentParams: TParams;
-  /** Full URL of the page being navigated away from. */
+  /** Full URL of the page being navigated away from, without its #fragment. */
   currentUrl: URL;
   /** Route params for the navigation target. */
   nextParams: TParams;

package/src/types/loader-types.ts

@@ -207,10 +207,13 @@ export type LoaderFn<
 export type LoaderOptions = {
   ssr?: boolean;
   /**
-   * `prefetch: false` keeps this loader out of prefetches. A `<Link>`
-   * prefetch (a partial request with `X-Rango-Prefetch`) does not execute it;
-   * the payload marks it deferred. A document request and a navigation with
-   * no prefetch to adopt run it as usual.
+   * `prefetch: false` keeps this loader out of speculative prefetches. A
+   * viewport or render `<Link>` prefetch (a partial request with
+   * `X-Rango-Prefetch: 1`) does not execute it; the payload marks it
+   * deferred. A hover prefetch and `useRouter().prefetch()`
+   * (`X-Rango-Prefetch: intent`) count as intent to click and run it, so a
+   * click after a hover needs no follow-up request. A document request and a
+   * navigation with no prefetch to adopt run it as usual.
    *
    * A deferred loader never blocks the navigation that adopts the prefetch:
    * it behaves like a loader that is still streaming. Its own `<Suspense>`

package/src/types/segments.ts

@@ -161,7 +161,6 @@ export interface ResolvedSegment {
   parallelName?: string; // For parallels: the parallel group name (used to match with revalidations)
   // Loader-specific fields
   loaderId?: string; // For loaders: the loader $$id identifier
-  _inherited?: boolean; // For inherited loaders: dedup marker for buildMatchResult
   loaderData?: any; // For loaders: the resolved data from loader execution
   /**
    * True when this loader was awaited before first flush
@@ -299,6 +298,24 @@ export interface MatchResult {
    * source, so the RSC handler scopes its prefetch entry to it (#1007).
    */
   interceptTargeted?: true;
+  /**
+   * Set on a partial match when a revalidate() predicate read the source page
+   * and kept a held segment: the diff is right for the pages with equal values
+   * of what it read. The RSC handler scopes its prefetch entry to that group,
+   * or to the source page when the predicate read `currentUrl` (#1331).
+   */
+  sourceHeld?: import("../router/source-reads.js").SourceHeld;
+  /**
+   * Set on a partial match whose answer has nothing live in it: the cache
+   * lookup served it (a cache() record, a Prerender entry, a shell replay's
+   * record, not a stale cache() record or stale overlay entry), it sends a
+   * segment, every segment it
+   * sends is one that lookup decoded, and no loader ran. A stored segment
+   * cannot fail after the headers left, since every writer refuses a failed
+   * render; a live segment or a loader can. The RSC handler marks the request
+   * `_servedFromStorage` from it.
+   */
+  fromStorage?: true;
   /**
    * Redirect URL for trailing slash normalization.
    * When set, the RSC handler should return a 308 redirect to this URL

package/src/urls/path-helper-types.ts

@@ -364,9 +364,10 @@ export type PathHelpers<TEnv> = {
    * freezes into the shell (nested promises stay live holes) — the pre-flush
    * promise applied to the prelude.
    *
-   * Pass `{ prefetch: false }` to keep the loader out of prefetches: a
-   * prefetch skips it and the click that adopts the prefetch fetches it in
-   * one follow-up request (see {@link LoaderOptions}). Only on a segment the
+   * Pass `{ prefetch: false }` to keep the loader out of speculative
+   * prefetches (viewport, render): such a prefetch skips it and the click
+   * that adopts it fetches it in one follow-up request; a hover prefetch runs
+   * it (see {@link LoaderOptions}). Only on a segment the
    * client does not have yet: a loader the client already holds runs in the
    * prefetch when it revalidates.
    */
@@ -380,8 +381,9 @@ export type PathHelpers<TEnv> = {
    * Attach a loading component to the current route/layout.
    *
    * `{ ssr: false }` skips the fallback on document requests. `{ prefetch:
-   * false }` keeps what the fallback covers out of prefetches, when this
-   * entry's segment is new to the client: the entry's handler, its loaders,
+   * false }` keeps what the fallback covers out of viewport and render
+   * prefetches (a hover prefetch runs it), when this entry's segment is new
+   * to the client: the entry's handler, its loaders,
    * its orphan layouts and parallel slots and, for a layout, every deeper
    * entry. The click that adopts the prefetch shows the fallback and fetches
    * them in one follow-up request, which reads cache() and "use cache" as

package/src/vite/temp-rsc-server.ts

@@ -7,8 +7,8 @@
  *
  * Sits in src/vite/, not src/vite/discovery/: the loader hook URL below
  * resolves against this module's import.meta.url, and the published bundles
- * (dist/vite/index.js, dist/bin/rango.js) ship the hook at the same relative
- * path.
+ * (dist/vite/index.js, and the CLI's code-split chunks in dist/bin/) ship the
+ * hook at the same relative path.
  */
 
 import type { ViteDevServer } from "vite";