@rangojs/router 0.33.2 → 0.34.1

package/src/route-definition/dsl-helpers.ts

@@ -25,7 +25,11 @@ import {
   type InterceptConfig,
   type LoaderEntry,
 } from "../server/context";
-import { assertBooleanOption, invariant } from "../errors";
+import {
+  assertBooleanOption,
+  assertPrefetchOption,
+  invariant,
+} from "../errors";
 import { validateUserRouteName } from "../route-name.js";
 import { isCachedFunction } from "../cache/taint.js";
 import { RangoContext } from "../server/context";
@@ -48,6 +52,7 @@ import type {
   UseItems,
 } from "../route-types.js";
 import { isRenderableLoading } from "../types/boundaries.js";
+import { isPrefetchFlag } from "../prefetch-markers.js";
 import type { RouteHelpers } from "./helpers-types.js";
 import {
   resolveHandlerUse,
@@ -922,7 +927,7 @@ const loader: RouteHelpers<any, any>["loader"] = (
     "loader() ssr",
     "stream on every render",
   );
-  assertBooleanOption(
+  assertPrefetchOption(
     optionsGiven?.prefetch,
     "loader() prefetch",
     "run the loader in prefetches",
@@ -938,7 +943,9 @@ const loader: RouteHelpers<any, any>["loader"] = (
     loader: loaderDef,
     revalidate: [] as ShouldRevalidateFn<any, any>[],
     ...(optionsGiven?.ssr === false && { bake: true as const }),
-    ...(optionsGiven?.prefetch === false && { prefetch: false as const }),
+    ...(isPrefetchFlag(optionsGiven?.prefetch) && {
+      prefetch: optionsGiven.prefetch,
+    }),
     // The declaring layout's / parallel's / cache()'s scope. A route's (and
     // an intercept's) loaders have none: they resolve from the route's name,
     // like the handler.
@@ -997,7 +1004,7 @@ const loading: RouteHelpers<any, any>["loading"] = (component, options) => {
     invariant(false, "No parent entry available for loading()");
   }
 
-  assertBooleanOption(
+  assertPrefetchOption(
     options?.prefetch,
     "loading() prefetch",
     "render what the fallback covers in prefetches",
@@ -1018,8 +1025,8 @@ const loading: RouteHelpers<any, any>["loading"] = (component, options) => {
   // `parent.loading`, so the document evaluation (ssr: false) agrees with
   // the navigation one. Last loading() wins, like `loading` itself.
   parent.loadingPrefetch =
-    options?.prefetch === false && isRenderableLoading(resolved)
-      ? false
+    isPrefetchFlag(options?.prefetch) && isRenderableLoading(resolved)
+      ? options.prefetch
       : undefined;
 
   const name = `$${store.getNextIndex("loading")}`;

package/src/route-definition/helpers-types.ts

@@ -35,6 +35,7 @@ import type {
   UseItems,
 } from "../route-types.js";
 import type { StaticHandlerRef } from "../static-handler.js";
+import type { PrefetchOption } from "../prefetch-markers.js";
 
 // Re-export route item types for backward compatibility
 export type {
@@ -333,15 +334,16 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    * loader(RecommendationsLoader),  // still streams behind loading()
    * ```
    *
-   * 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
+   * Pass `{ prefetch: false }` to keep the loader out of prefetches: a
+   * prefetch skips it and the click that adopts it fetches it in one
+   * follow-up request. `{ prefetch: "intent" }` defers it in viewport and
+   * render prefetches only (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.
    *
    * ```typescript
    * loader(ReviewsLoader, { prefetch: false }),
+   * loader(RelatedLoader, { prefetch: "intent" }),
    * ```
    *
    * @param loaderDef - Loader created with createLoader()
@@ -362,16 +364,18 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    * // Skip loading on SSR, only show on client navigation
    * loading(<Skeleton />, { ssr: false })
    *
-   * // Keep everything behind this fallback out of viewport and render
-   * // prefetches (a hover prefetch runs it)
+   * // Keep everything behind this fallback out of prefetches
    * loading(<Skeleton />, { prefetch: false })
+   *
+   * // Deferred in viewport and render prefetches only
+   * loading(<Skeleton />, { prefetch: "intent" })
    * ```
    * @param component - The loading UI to show during navigation
    * @param options - Configuration options
    * @param options.ssr - If false, skip showing loading on document requests (SSR)
-   * @param options.prefetch - If false, the flag applies when this entry's
-   *   segment is new to the client. A viewport or render prefetch then skips
-   *   the whole unit (a hover prefetch runs it): the
+   * @param options.prefetch - `false` or `"intent"` (see
+   *   {@link LoaderOptions}); the flag applies when this entry's segment is
+   *   new to the client. A prefetch then skips the whole unit: the
    *   handler, its loaders, its orphan layouts and parallel slots and, for a
    *   layout, every deeper entry; the click that adopts the prefetch shows
    *   this fallback and fetches them in one follow-up request, which reads
@@ -386,7 +390,7 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    */
   loading: (
     component: ReactNode | (() => ReactNode),
-    options?: { ssr?: boolean; prefetch?: boolean },
+    options?: { ssr?: boolean; prefetch?: PrefetchOption },
   ) => LoadingItem;
   /**
    * Attach an error boundary to catch errors in this segment and children

package/src/router/loader-resolution.ts

@@ -731,17 +731,17 @@ function createLoaderExecutor<TEnv>(
           );
         }
 
-        // prefetch: false (segment-resolution/prefetch-deferral.ts). A
-        // deferrable loader runs in a fill request, where its entry is held
+        // prefetch: false or "intent" (segment-resolution/prefetch-deferral.ts).
+        // A deferrable loader runs in a fill request, where its entry is held
         // and its handler does not run: there is no render to wait for.
         // Refused on every request kind, so it is seen on a document load.
         const deferral = internal._prefetchDeferral;
         if (deferral?.scope.loaderIds.has(currentLoaderId)) {
           throw new Error(
             `ctx.rendered() is not available to loader "${currentLoaderId}": it is deferred in prefetches ` +
-              `(registered with loader(Def, { prefetch: false }), or behind a loading(fallback, { prefetch: false })), ` +
+              `(registered with loader(Def, { prefetch: false }) or { prefetch: "intent" }, or behind a loading(fallback, { prefetch: false }) or { prefetch: "intent" }), ` +
               `and the fill request that runs it afterwards does not re-run its entry's handler, so there is no render to wait for and no handle data to read. ` +
-              `Remove { prefetch: false } from the loader (or from the loading() above it), or stop calling ctx.rendered() in this loader.`,
+              `Remove { prefetch: false } or { prefetch: "intent" } from the loader (or from the loading() above it), or stop calling ctx.rendered() in this loader.`,
           );
         }
         if (deferral?.mode === "fill") {

package/src/router/match-api.ts

@@ -203,6 +203,7 @@ export async function createMatchContextForFull<TEnv>(
     prevUrl: cleanUrl,
     prevParams: {},
     prevMatch: null,
+    interceptPrev: { url: cleanUrl, params: {} },
     matched,
     manifestEntry: snapshot.manifestEntry,
     entries: snapshot.entries,
@@ -491,9 +492,7 @@ export async function createMatchContextForPartial<TEnv>(
   const deferral = planPrefetchDeferral(
     snapshot.entries,
     partialDeferralMode({
-      fill: kind === "fill",
-      // Speculative only: an intent prefetch defers nothing.
-      prefetch: kind === "prefetch",
+      kind,
       method: request.method,
       isAction,
       isShellCapture: reqCtx?._shellCaptureState?.run === true,
@@ -522,6 +521,7 @@ export async function createMatchContextForPartial<TEnv>(
     prevUrl: nav.prevUrl,
     prevParams: nav.prevParams,
     prevMatch: nav.prevMatch,
+    interceptPrev: nav.interceptPrev,
     matched,
     manifestEntry: snapshot.manifestEntry,
     entries: snapshot.entries,

package/src/router/match-context.ts

@@ -116,6 +116,7 @@ import type {
 } from "../server/context.js";
 import type { HandlerContext, ResolvedSegment } from "../types.js";
 import type { RouteMatchResult } from "./pattern-matching.js";
+import type { PrevPage } from "./navigation-snapshot.js";
 import type { InterceptResult } from "./router-context.js";
 import type { ResolutionPassInput } from "./segment-resolution/resolution-pass.js";
 import type { ActionContext } from "./types.js";
@@ -139,10 +140,13 @@ export interface MatchContext<TEnv = any> {
   /** NavigationSnapshot.heldBoundary: the walk stops above it. */
   heldBoundary?: string;
 
-  // Previous navigation state
+  // Previous navigation state: see NavigationSnapshot.
   prevUrl: URL;
   prevParams: Record<string, string>;
+  /** The match of the page left: the intercept's URL while one is open. */
   prevMatch: RouteMatchResult | null;
+  /** The page an open intercept's slot was rendered for. */
+  interceptPrev: PrevPage;
 
   // Current route match
   matched: RouteMatchResult;
@@ -225,6 +229,23 @@ export function resolutionPassInput<TEnv>(
   };
 }
 
+/**
+ * This match as the input of the pass that resolves its intercept's slot: its
+ * held segments compare with the intercept's own URL (`interceptPrev`), not
+ * with the source page under it. From /item/2 over /list/1, a link to /item/1
+ * compared with the source's params would read as param-equal and keep item
+ * 2's slot.
+ */
+export function interceptPassInput<TEnv>(
+  ctx: MatchContext<TEnv>,
+): ResolutionPassInput<TEnv> {
+  return {
+    ...resolutionPassInput(ctx),
+    prevUrl: ctx.interceptPrev.url,
+    prevParams: ctx.interceptPrev.params,
+  };
+}
+
 /**
  * Mutable state that flows through the pipeline
  */

package/src/router/match-middleware/cache-lookup.ts

@@ -49,6 +49,7 @@ import {
   type MatchPipelineState,
 } from "../match-context.js";
 import { getRouterContext, type RouterContext } from "../router-context.js";
+import type { PrevPage } from "../navigation-snapshot.js";
 import { freshPassInput } from "../segment-resolution/resolution-pass.js";
 import { observeEvent } from "../instrument.js";
 import { pushRevalidationTraceEntry, isTraceActive } from "../logging.js";
@@ -336,7 +337,12 @@ function storedEntrySends<TEnv>(
   router: RouterContext<TEnv>,
 ): (segment: ResolvedSegment) => boolean | Promise<boolean> {
   if (ctx.isFullMatch) return () => true;
-  const paramsChanged = !paramsEqual(ctx.matched.params, ctx.prevParams);
+  // An intercept variant's slot compares with the intercept's own page, the
+  // page under it with the source (MatchContext.interceptPrev).
+  const pagePrev: PrevPage = { url: ctx.prevUrl, params: ctx.prevParams };
+  const slotPrev = ctx.interceptPrev;
+  const pageParamsChanged = !paramsEqual(ctx.matched.params, pagePrev.params);
+  const slotParamsChanged = !paramsEqual(ctx.matched.params, slotPrev.params);
   const resendRouteSegments = replaceable && (ctx.isAction || ctx.stale);
   const entryRevalidateMap =
     ctx.clientSegmentSet.size > 0
@@ -345,11 +351,11 @@ function storedEntrySends<TEnv>(
   // A keep that hangs on the source's params is right for the pages with
   // the same params only: scope a prefetch of the answer to them, as a
   // predicate that compared every param would (#1331).
-  const heldForSource = (): false => {
+  const heldForSource = (prevParams: Record<string, string>): false => {
     markSourceHeld(
       ctx.handlerContext as InternalHandlerContext<any, TEnv>,
-      readsOfAllParams(ctx.prevParams),
-      { params: ctx.prevParams, routeName: undefined },
+      readsOfAllParams(prevParams),
+      { params: prevParams, routeName: undefined },
     );
     return false;
   };
@@ -362,23 +368,26 @@ function storedEntrySends<TEnv>(
       ctx.clientSegmentSet,
     );
     if (fill !== undefined) return fill;
+    const ofSlot = isInterceptSegment(segment);
+    const prev = ofSlot ? slotPrev : pagePrev;
+    const paramsChanged = ofSlot ? slotParamsChanged : pageParamsChanged;
     if (segment.type === "route" || segment.belongsToRoute === true) {
       if (paramsChanged || resendRouteSegments) return true;
       // Kept on equal params, whatever the search: a source with other
       // params is sent it.
-      return heldForSource();
+      return heldForSource(prev.params);
     }
     const revalidate = entryRevalidateMap?.get(segment.id)?.revalidate;
     if (!revalidate?.length) return false;
     // Kept on equal params: from another source the rules run and may send
     // it.
-    if (!paramsChanged) return heldForSource();
+    if (!paramsChanged) return heldForSource(prev.params);
     return router.evaluateRevalidation({
       segment,
-      prevParams: ctx.prevParams,
+      prevParams: prev.params,
       getPrevSegment: null,
       request: ctx.request,
-      prevUrl: ctx.prevUrl,
+      prevUrl: prev.url,
       nextUrl: ctx.url,
       revalidations: revalidate.map((fn, i) => ({
         name: `revalidate${i}`,

package/src/router/match-middleware/intercept-resolution.ts

@@ -103,7 +103,7 @@
  */
 import type { ResolvedSegment } from "../../types.js";
 import type { MatchContext, MatchPipelineState } from "../match-context.js";
-import { resolutionPassInput } from "../match-context.js";
+import { interceptPassInput } from "../match-context.js";
 import { getRouterContext } from "../router-context.js";
 import type { GeneratorMiddleware } from "./cache-lookup.js";
 import { debugLog } from "../logging.js";
@@ -176,7 +176,7 @@ export function withInterceptResolution<TEnv>(
     const Store = ctx.Store;
     const interceptSegments = await Store.run(() =>
       resolveInterceptEntry(
-        resolutionPassInput(ctx),
+        interceptPassInput(ctx),
         ctx.interceptResult!.intercept,
         ctx.interceptResult!.entry,
         true, // belongsToRoute
@@ -232,7 +232,7 @@ async function handleCacheHitIntercept<TEnv>(
   const loaderSegments = resolveInterceptLoadersOnly
     ? await ctx.Store.run(() =>
         resolveInterceptLoadersOnly(
-          resolutionPassInput(ctx),
+          interceptPassInput(ctx),
           ctx.interceptResult!.intercept,
           ctx.interceptResult!.entry,
           true, // belongsToRoute

package/src/router/navigation-snapshot.ts

@@ -3,12 +3,30 @@ import { requestHeaders } from "../server/request-headers.js";
 import type { RouteMatchResult } from "./pattern-matching.js";
 import { WIRE } from "../wire-params.js";
 
+/** A page held segments were rendered for: what their revalidation compares with. */
+export interface PrevPage {
+  url: URL;
+  params: Record<string, string>;
+}
+
 export interface NavigationSnapshot {
+  /**
+   * `prevUrl` and `prevParams`: the page the held page segments were rendered
+   * for. That is the page left, or the source page while an intercept is open
+   * (`hasInterceptSource`).
+   */
   prevUrl: URL;
   /** The visitor's URL of the page left, when `prevUrl` is its rewrite target. */
   prevVisitorUrl: URL | null;
   prevParams: Record<string, string>;
+  /** The match of the page left: the intercept's URL while one is open. */
   prevMatch: RouteMatchResult | null;
+  /**
+   * The page an open intercept's slot was rendered for: the intercept's own
+   * URL (match-context.ts interceptPassInput). Equals `prevUrl`/`prevParams`
+   * when the request names no intercept source.
+   */
+  interceptPrev: PrevPage;
 
   interceptContextUrl: URL;
   interceptContextMatch: RouteMatchResult | null;
@@ -176,29 +194,40 @@ export async function resolveNavigation(
   }
   // An intercept's request diffs from its source, which _rsc_rt does not name.
   const shown = interceptSourceUrl ? null : getShownRouteUrl(url);
-  const prevUrl = shown ?? visitor;
+  const left = shown ?? visitor;
 
   let interceptContextUrl: URL;
   try {
     interceptContextUrl = interceptSourceUrl
       ? withoutHash(new URL(interceptSourceUrl, url.origin))
-      : prevUrl;
+      : left;
   } catch {
-    interceptContextUrl = prevUrl;
+    interceptContextUrl = left;
   }
 
-  const prevMatch = await deps.findMatch(prevUrl.pathname);
-  const prevParams = prevMatch?.params || {};
+  const prevMatch = await deps.findMatch(left.pathname);
   const interceptContextMatch = interceptSourceUrl
     ? await deps.findMatch(interceptContextUrl.pathname)
     : prevMatch;
+  const interceptPrev: PrevPage = {
+    url: left,
+    params: prevMatch?.params || {},
+  };
+  // The page under an open intercept was rendered for the source, with its
+  // search, not for the intercept's URL.
+  const prev: PrevPage = interceptSourceUrl
+    ? {
+        url: formSearch(new URL(interceptContextUrl)),
+        params: interceptContextMatch?.params || {},
+      }
+    : interceptPrev;
 
   const isSameRouteNavigation = !!(
     interceptContextMatch && interceptContextMatch.routeKey === currentRouteKey
   );
 
   const hasInterceptSource = !!interceptSourceUrl;
-  const effectiveFromUrl = hasInterceptSource ? interceptContextUrl : prevUrl;
+  const effectiveFromUrl = hasInterceptSource ? interceptContextUrl : left;
   const effectiveFromMatch = hasInterceptSource
     ? interceptContextMatch
     : prevMatch;
@@ -212,10 +241,11 @@ export async function resolveNavigation(
   const clientSegmentSet = new Set(clientSegmentIds);
 
   return {
-    prevUrl,
+    prevUrl: prev.url,
     prevVisitorUrl: shown && visitor,
-    prevParams,
+    prevParams: prev.params,
     prevMatch,
+    interceptPrev,
     interceptContextUrl,
     interceptContextMatch,
     clientSegmentIds,
@@ -240,6 +270,7 @@ export function createNavigationSnapshot(
     prevVisitorUrl: null,
     prevParams: {},
     prevMatch: null,
+    interceptPrev: { url: defaultUrl, params: {} },
     interceptContextUrl: defaultUrl,
     interceptContextMatch: null,
     clientSegmentIds: [],