@rangojs/router 0.32.0 → 0.33.1

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
@@ -126,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;
@@ -517,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. */
@@ -891,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;
@@ -931,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);
@@ -945,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.
@@ -1009,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);
@@ -1109,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
@@ -1323,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/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

package/src/types/handler-context.ts

@@ -520,11 +520,13 @@ export type InternalHandlerContext<
   /**
    * @internal A revalidate() predicate that read the source page
    * (`currentParams`, `currentUrl`, `fromRouteName`) kept a held segment, so
-   * this match's diff is right for that source only (#1331). Set by
-   * evaluateRevalidation (router/revalidation.ts); match-result.ts turns it
-   * into `sourceHeld`, which scopes a prefetch of the response to its source.
+   * 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?: true;
+  _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
@@ -679,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
@@ -301,10 +300,22 @@ export interface MatchResult {
   interceptTargeted?: true;
   /**
    * Set on a partial match when a revalidate() predicate read the source page
-   * and kept a held segment: the diff is that source's. The RSC handler
-   * scopes its prefetch entry to it, like `interceptTargeted` (#1331).
+   * 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?: true;
+  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";