@rangojs/router 0.33.1 → 0.34.0

package/src/browser/navigation-transaction.ts

@@ -17,8 +17,10 @@ import type { EventController, NavigationHandle } from "./event-controller.js";
 import { debugLog } from "./logging.js";
 import {
   buildHistoryState,
+  keptEntryState,
   mergeLocationState,
   pushHistoryWithIdx,
+  shownLocationState,
 } from "./history-state.js";
 
 export { resolveNavigationState } from "./history-state.js";
@@ -67,6 +69,8 @@ interface CommitOptions {
    * screen stays (EventController.commitLocationState).
    */
   treeless?: boolean;
+  /** Commits onto the entry on screen, keeping its location state (see keptEntryState). */
+  sameEntry?: boolean;
 }
 
 /**
@@ -227,16 +231,20 @@ export function createNavigationTransaction(
       return { scroll: { enabled: scroll } };
     }
 
-    const historyState = buildHistoryState(
-      opts.state,
-      { intercept, sourceUrl: interceptSourceUrl },
-      serverState,
-    );
+    const marks = { intercept, sourceUrl: interceptSourceUrl };
+    const historyState = opts.sameEntry
+      ? keptEntryState(window.history.state, marks, serverState)
+      : buildHistoryState(opts.state, marks, serverState);
 
     pushHistoryWithIdx(historyState, url, replace ?? false);
     ensureHistoryKey();
     store.rememberDisplayedEntry(opts.metadata);
-    eventController.commitLocationState(historyState, opts.treeless);
+    eventController.commitLocationState(
+      opts.sameEntry
+        ? shownLocationState(eventController.getLocationState(), serverState)
+        : historyState,
+      opts.treeless,
+    );
 
     handle.complete(parsedUrl);
 

package/src/browser/partial-update.ts

@@ -616,7 +616,10 @@ export function createPartialUpdater(
 
     // The page the client is on, which the server diffs the target against:
     // the committed entry (the store's URL until tx.commit()), whose segment
-    // ids are sent above, or the intercept's source. Never window.location:
+    // ids are sent above. A navigation names an intercept's source in its own
+    // header, so the client path stays the committed URL (the slot's params
+    // compare against it); an action's or a stale revalidation's refetch
+    // still names the source as the client path. Never window.location:
     // a popstate has already moved it to the popped entry before that
     // entry's fetch commits. Sent from there, a back/forward was told the
     // target is also the source and kept the page being left (#1030), and a
@@ -624,7 +627,8 @@ export function createPartialUpdater(
     // against the popped entry while holding the page on screen's copies, so
     // a layout kept for one page showed the other's.
     const previousUrl =
-      (mode.type !== "leave-intercept" && interceptSourceUrl) ||
+      ((mode.type === "action" || mode.type === "stale-revalidation") &&
+        interceptSourceUrl) ||
       segmentState.currentUrl;
 
     if (IS_BROWSER_DEBUG) {
@@ -711,11 +715,15 @@ export function createPartialUpdater(
       targetUrl: url,
       segmentIds: segments,
       previousUrl,
-      // The entry being left (a popstate has not moved it yet), unless
-      // previousUrl names an intercept's source.
+      // The entry being left (a popstate has not moved it yet). Dropped
+      // whenever an intercept source is present: the server diffs from the
+      // source, which `_rsc_rt` does not name, and ignores it beside the
+      // source header (router/navigation-snapshot.ts resolveNavigation).
       rewriteTarget: interceptSourceUrl
         ? undefined
         : store.getHistoryEntryMemory()?.rewriteTarget,
+      interceptSourceUrl:
+        mode.type === "navigate" ? interceptSourceUrl : undefined,
       staleRevalidation:
         mode.type === "stale-revalidation" || segments.length === 0,
       boundary,

package/src/browser/prefetch/fetch.ts

@@ -279,9 +279,9 @@ function executePrefetchFetch(
   rangoState: string,
   /**
    * An intent prefetch (prefetchDirect: hover, `prefetch()`): sent as
-   * PREFETCH_INTENT so the server defers nothing, as in the navigation it
-   * starts early. A speculative one (prefetchQueued) sends `1` and lets the
-   * server defer `prefetch: false` work (docs/design/prefetch-false.md, R16).
+   * PREFETCH_INTENT so the server runs `prefetch: "intent"` work and defers
+   * only `prefetch: false` work. A speculative one (prefetchQueued) sends `1`
+   * and lets the server defer both (docs/design/prefetch-false.md, R16).
    */
   intent: boolean,
   expectedRouterId?: string,

package/src/client-urls/client-urls.ts

@@ -5,6 +5,7 @@ import { joinMount } from "../router/substitute-pattern-params.js";
 import { tryTrieMatch } from "../router/trie-matching.js";
 import type { LoaderDefinition } from "../types.js";
 import { isHoistedRevalidateRef } from "./hoisted-revalidate.js";
+import { isPrefetchFlag, type PrefetchFlag } from "../prefetch-markers.js";
 import type {
   ClientPathOptions,
   ClientTransitionConfig,
@@ -141,7 +142,7 @@ interface LoaderItem extends ItemBase {
   readonly definition: LoaderDefinition<any, any>;
   readonly revalidate: ClientUrlLoaderRecord["revalidate"];
   readonly ssr?: false;
-  readonly prefetch?: false;
+  readonly prefetch?: PrefetchFlag;
 }
 
 interface RevalidateItem extends ItemBase {
@@ -360,10 +361,11 @@ export const loader: ClientUrlHelpers["loader"] = (
   if (
     process.env.NODE_ENV !== "production" &&
     options?.prefetch !== undefined &&
-    typeof options.prefetch !== "boolean"
+    typeof options.prefetch !== "boolean" &&
+    options.prefetch !== "intent"
   ) {
     throw new Error(
-      `clientUrls() loader() prefetch must be a boolean (got ${JSON.stringify(options.prefetch)}). Omit it (or pass true) to run the loader in prefetches.`,
+      `clientUrls() loader() prefetch must be a boolean or "intent" (got ${JSON.stringify(options.prefetch)}). Omit it (or pass true) to run the loader in prefetches.`,
     );
   }
   const items = use ? runUse(use, "loader use") : [];
@@ -379,7 +381,9 @@ export const loader: ClientUrlHelpers["loader"] = (
       )
       .map((item) => item.fn),
     ...(options?.ssr === false ? { ssr: false as const } : {}),
-    ...(options?.prefetch === false ? { prefetch: false as const } : {}),
+    ...(isPrefetchFlag(options?.prefetch)
+      ? { prefetch: options.prefetch }
+      : {}),
   });
 };
 
@@ -630,7 +634,7 @@ function applyConfig(
           loader: item.definition,
           revalidate: Object.freeze([...item.revalidate]),
           ...(item.ssr === false ? { ssr: false as const } : {}),
-          ...(item.prefetch === false ? { prefetch: false as const } : {}),
+          ...(item.prefetch !== undefined ? { prefetch: item.prefetch } : {}),
         }),
       );
     } else if (item.type === "loading") {
@@ -754,8 +758,8 @@ function collectIntercepts(
             Object.freeze({
               loader: useItem.definition,
               revalidate: Object.freeze([...useItem.revalidate]),
-              ...(useItem.prefetch === false
-                ? { prefetch: false as const }
+              ...(useItem.prefetch !== undefined
+                ? { prefetch: useItem.prefetch }
                 : {}),
             }),
           );

package/src/client-urls/server-projection.ts

@@ -113,6 +113,11 @@ export interface ClientUrlProjectionRoute {
    *  loader(), so a prefetch of the route defers them. Absent (= none) in
    *  projections serialized before the option existed. */
   readonly deferrableLoaderIndices?: readonly number[];
+  /** Indices into loaderIds of loaders declared loader(Def, { prefetch:
+   *  "intent" }); materialization passes the option through, so a
+   *  speculative prefetch defers them and an intent prefetch runs them.
+   *  Absent (= none) in projections serialized before the option existed. */
+  readonly intentLoaderIndices?: readonly number[];
   /** Per loader (aligned with loaderIds), its revalidate() arguments in
    *  declaration order: a hoisted predicate's key, whose registration
    *  materialization attaches (revalidate-registry.ts), or a boolean
@@ -140,6 +145,8 @@ export interface ClientUrlProjectionIntercept {
   readonly hasLoading: boolean;
   /** As on a route (ClientUrlProjectionRoute.deferrableLoaderIndices). */
   readonly deferrableLoaderIndices?: readonly number[];
+  /** As on a route (ClientUrlProjectionRoute.intentLoaderIndices). */
+  readonly intentLoaderIndices?: readonly number[];
   /** As on a route (ClientUrlProjectionRoute.loaderRevalidate). */
   readonly loaderRevalidate?: readonly (readonly (string | boolean)[])[];
 }
@@ -381,7 +388,7 @@ function serializeLoaderOptions(
   options: SerializeClientUrlPatternsOptions,
 ): Pick<
   ClientUrlProjectionRoute,
-  "deferrableLoaderIndices" | "loaderRevalidate"
+  "deferrableLoaderIndices" | "intentLoaderIndices" | "loaderRevalidate"
 > {
   const loaderRevalidate = loaders.map(({ loader, revalidate }) =>
     revalidate.flatMap((entry): (string | boolean)[] => {
@@ -403,10 +410,17 @@ function serializeLoaderOptions(
     loaders,
     ({ prefetch }) => prefetch === false,
   );
+  const intentLoaderIndices = indicesWhere(
+    loaders,
+    ({ prefetch }) => prefetch === "intent",
+  );
   return {
     ...(deferrableLoaderIndices.length > 0
       ? { deferrableLoaderIndices: Object.freeze(deferrableLoaderIndices) }
       : {}),
+    ...(intentLoaderIndices.length > 0
+      ? { intentLoaderIndices: Object.freeze(intentLoaderIndices) }
+      : {}),
     ...(loaderRevalidate.some((keys) => keys.length > 0)
       ? {
           loaderRevalidate: Object.freeze(
@@ -582,6 +596,7 @@ interface ProjectedLoaders {
     | "loaderRevalidate"
     | "awaitedLoaderIndices"
     | "deferrableLoaderIndices"
+    | "intentLoaderIndices"
   >;
   /** Names the owner in an error: `route "/a"`, `intercept ".b"`. */
   readonly label: string;
@@ -817,8 +832,8 @@ function materializeRouteItems(
   };
 
   // The loader() items of a route's or an intercept's projected loaders: each
-  // stub with its `ssr: false` and `prefetch: false` flags and its
-  // revalidate() predicates.
+  // stub with its `ssr: false` and `prefetch` flags and its revalidate()
+  // predicates.
   const materializeLoaders = (owner: ProjectedLoaders) =>
     owner.projected.loaderIds.map((id, loaderIndex) => {
       const revalidators = loaderRevalidators(reference, owner, loaderIndex);
@@ -831,6 +846,9 @@ function materializeRouteItems(
           ...(owner.projected.deferrableLoaderIndices?.includes(
             loaderIndex,
           ) && { prefetch: false }),
+          ...(owner.projected.intentLoaderIndices?.includes(loaderIndex) && {
+            prefetch: "intent" as const,
+          }),
         },
         () => revalidators.map((fn) => revalidate(fn)),
       );

package/src/client-urls/types.ts

@@ -7,6 +7,7 @@ import type {
 } from "../types.js";
 import type { DefaultEnv } from "../types/global-namespace.js";
 import type { HoistedRevalidateRef } from "./hoisted-revalidate.js";
+import type { PrefetchFlag } from "../prefetch-markers.js";
 import type { TrieMatchResult } from "../router/trie-matching.js";
 import type { PathOptions } from "../urls/pattern-types.js";
 import type { SearchSchema } from "../search-params.js";
@@ -85,13 +86,12 @@ export interface ClientUrlLoaderRecord {
    */
   readonly ssr?: false;
   /**
-   * loader(Def, { prefetch: false }): a viewport or render prefetch of the
-   * route, or of an intercept's target from its source, defers this loader
-   * (a hover prefetch runs it) and the click
-   * that adopts it runs it in its fill request (see {@link LoaderOptions}).
-   * Projected onto the materialized stub.
+   * loader(Def, { prefetch: false | "intent" }): a prefetch of the route, or
+   * of an intercept's target from its source, defers this loader and the
+   * click that adopts it runs it in its fill request (see
+   * {@link LoaderOptions}). Projected onto the materialized stub.
    */
-  readonly prefetch?: false;
+  readonly prefetch?: PrefetchFlag;
 }
 
 /**
@@ -169,14 +169,13 @@ export interface ClientUrlHelpers {
    * settled return freezes into the shell (nested promises stay live
    * holes).
    *
-   * Pass `{ prefetch: false }` to keep this loader out of the route's
-   * viewport and render prefetches; a hover prefetch runs it (see
-   * {@link LoaderOptions}). An in-group click still shows
-   * the destination at once, commits the adopted prefetch with the other
-   * loaders' data, and runs only the flagged loaders in its one fill
-   * request. A `layout()` loader with the flag is flagged on every route
-   * below it. Inside intercept() it defers the loader in a viewport or
-   * render prefetch of the intercept from its source, as in urls().
+   * Pass `{ prefetch: false | "intent" }` to keep this loader out of the
+   * route's prefetches (see {@link LoaderOptions}). An in-group click still
+   * shows the destination at once, commits the adopted prefetch with the
+   * other loaders' data, and runs only the flagged loaders in its one fill
+   * request. A `layout()` loader with the
+   * flag is flagged on every route below it. Inside intercept() it defers
+   * the loader in a prefetch of the intercept from its source, as in urls().
    */
   readonly loader: <TData>(
     definition: LoaderDefinition<TData>,

package/src/errors.ts

@@ -6,6 +6,8 @@
  * - Cause property for structured debugging data
  */
 
+import { isPrefetchFlag } from "./prefetch-markers.js";
+
 /**
  * Options for error construction
  */
@@ -418,6 +420,21 @@ export function assertBooleanOption(
   );
 }
 
+/**
+ * Rejects a `prefetch` DSL option that is neither a boolean nor `"intent"`
+ * (undefined passes), as an invariant.
+ */
+export function assertPrefetchOption(
+  value: unknown,
+  option: string,
+  effect: string,
+): void {
+  invariant(
+    value === undefined || typeof value === "boolean" || isPrefetchFlag(value),
+    `${option} must be a boolean or "intent" (got ${JSON.stringify(value)}). Omit it (or pass true) to ${effect}.`,
+  );
+}
+
 /**
  * Sanitize errors for production - prevents leaking sensitive information
  *

package/src/loader-store.ts

@@ -58,14 +58,26 @@ export interface LoaderEntry<T = unknown> {
   readonly isLoading: boolean;
   /** Identifies the request that produced this snapshot. 0 means "no request". */
   readonly requestId: number;
+  /**
+   * Route data (a route reader's `contextData`, by identity) of the readers on
+   * screen when `value` was requested. A route reader shows `value` only while
+   * its own route data is in this set.
+   */
+  readonly valueFor: ReadonlySet<unknown>;
+  /** The same for the latest request: `isLoading` and `error`. */
+  readonly requestFor: ReadonlySet<unknown>;
 }
 
+const NO_ROUTE_DATA: ReadonlySet<unknown> = new Set();
+
 const EMPTY_SNAPSHOT: LoaderEntry = Object.freeze({
   value: undefined,
   hasValue: false,
   error: null,
   isLoading: false,
   requestId: 0,
+  valueFor: NO_ROUTE_DATA,
+  requestFor: NO_ROUTE_DATA,
 });
 
 /**
@@ -106,6 +118,8 @@ export interface SubscribeOptions {
    * its own lifecycle.
    */
   onStreamPending?: () => void;
+  /** The subscriber's committed route data. Route-context readers only. */
+  routeData?: () => unknown;
 }
 
 interface InternalEntry {
@@ -139,6 +153,7 @@ interface InternalEntry {
   refetch: (() => Promise<void>) | undefined;
   /** Subscribers' `onStreamPending` callbacks (see SubscribeOptions). */
   streamPendingListeners: Set<() => void>;
+  routeDataSources: Set<() => unknown>;
 }
 
 /**
@@ -188,6 +203,7 @@ export class LoaderStore {
         groups: new Map(),
         refetch: undefined,
         streamPendingListeners: new Set(),
+        routeDataSources: new Set(),
       };
       this.entries.set(bucketKey, e);
     }
@@ -234,9 +250,12 @@ export class LoaderStore {
     e.listeners.add(cb);
     const onStreamPending = options?.onStreamPending;
     if (onStreamPending) e.streamPendingListeners.add(onStreamPending);
+    const routeData = options?.routeData;
+    if (routeData) e.routeDataSources.add(routeData);
     return () => {
       e.listeners.delete(cb);
       if (onStreamPending) e.streamPendingListeners.delete(onStreamPending);
+      if (routeData) e.routeDataSources.delete(routeData);
       // Group membership is refcounted per subscriber so refreshGroups() never
       // fetches for an unmounted reader, and a bucket shared by subscribers in
       // different groups stays in each group until ALL of that group's
@@ -414,16 +433,30 @@ export class LoaderStore {
    * error during the new request. Gated on `requestId === latestRequestId`
    * for symmetry with the other mutators.
    */
-  beginRequest(bucketKey: string, requestId: number): void {
+  beginRequest(
+    bucketKey: string,
+    requestId: number,
+    initiatorRouteData?: () => unknown,
+  ): void {
     const e = this.entries.get(bucketKey);
     if (!e || requestId !== e.latestRequestId) return;
-    if (e.snapshot.isLoading && e.snapshot.error === null) return;
+    const requestFor = new Set<unknown>();
+    if (initiatorRouteData) requestFor.add(initiatorRouteData());
+    for (const read of e.routeDataSources) requestFor.add(read());
+    const prev = e.snapshot;
+    if (
+      prev.isLoading &&
+      prev.error === null &&
+      [...requestFor].every((d) => prev.requestFor.has(d))
+    ) {
+      return;
+    }
     e.snapshot = Object.freeze({
-      value: e.snapshot.value,
-      hasValue: e.snapshot.hasValue,
+      ...prev,
       error: null,
       isLoading: true,
       requestId,
+      requestFor,
     });
     this.notify(e);
   }
@@ -442,6 +475,8 @@ export class LoaderStore {
       error: null,
       isLoading: false,
       requestId,
+      valueFor: e.snapshot.requestFor,
+      requestFor: e.snapshot.requestFor,
     });
     this.notify(e);
     this.dropIfSettled(bucketKey, e);
@@ -461,6 +496,8 @@ export class LoaderStore {
       error,
       isLoading: false,
       requestId,
+      valueFor: e.snapshot.valueFor,
+      requestFor: e.snapshot.requestFor,
     });
     this.notify(e);
     this.dropIfSettled(bucketKey, e);

package/src/prefetch-markers.ts

@@ -12,13 +12,27 @@ export const PREFETCH_HEADER = "X-Rango-Prefetch";
 /**
  * PREFETCH_HEADER's value on an intent prefetch: a hover or an explicit
  * `prefetch()` call (browser/prefetch/fetch.ts prefetchDirect). The server
- * defers nothing in it: `prefetch: false` loaders and the work behind a
- * flagged `loading()` run, as in the navigation it starts early. A
- * speculative prefetch (viewport, render) sends `1`, and any value other than
- * this one reads as speculative.
+ * runs the work flagged `prefetch: "intent"` in it and defers the work
+ * flagged `prefetch: false`. A speculative prefetch (viewport, render) sends
+ * `1` and defers both; any value other than this one reads as speculative.
  */
 export const PREFETCH_INTENT = "intent";
 
+/**
+ * A recorded `prefetch` flag of loader() or loading(): `false` defers the
+ * work in every prefetch, `"intent"` in a speculative one only
+ * (router/segment-resolution/prefetch-deferral.ts).
+ */
+export type PrefetchFlag = false | typeof PREFETCH_INTENT;
+
+/** A `prefetch` DSL option as written: a boolean, or `"intent"`. */
+export type PrefetchOption = boolean | PrefetchFlag;
+
+/** The option asks for deferral: `prefetch: false` or `prefetch: "intent"`. */
+export function isPrefetchFlag(value: unknown): value is PrefetchFlag {
+  return value === false || value === PREFETCH_INTENT;
+}
+
 /**
  * The last row of a prefetch whose render reported an error
  * (rsc/prefetch-render-error.ts): a Flight hint with a code React does not

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

@@ -491,9 +491,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,