@rangojs/router 0.33.2 → 0.34.0

package/skills/ux-architecture/SKILL.md

@@ -314,16 +314,20 @@ The rule: **prefetch broadly, and flag what is expensive.**
   already on screen whose `revalidate()` re-runs it for the destination is
   prefetched with it, so the click does not wait on a fill for data the page
   is already showing.
-- `prefetch: false` applies to speculative prefetches: viewport and render.
-  A hover, or `useRouter().prefetch()`, is intent to click and runs the
-  loader, so its click needs no fill. A hover over a link a viewport prefetch
-  already answered sends nothing, and that click still fills.
+- `prefetch: false` applies to every prefetch, hovers included.
+  `prefetch: "intent"` applies to speculative prefetches only (viewport and
+  render): a hover, or `useRouter().prefetch()`, is intent to click and runs
+  the loader, so on a route whose flags are all `"intent"` its click needs no
+  fill. Pick `"intent"` for a loader worth starting on hover, `false` for one
+  too expensive to run on every cursor pass. A hover over a link a viewport
+  prefetch already answered sends nothing, and that click still fills.
 - The trade-off of a deferring prefetch, measured on a `clientUrls()` tab in
-  a consumer app (dev, a loaded machine), before a hover's prefetch ran
-  flagged loaders: with the tab's loader flagged, a hover then a click 150 ms
-  later showed the content in 843 to 918 ms; with the tab prefetched whole, in
-  77 to 157 ms. The flagged click pays the fill request and then React's
-  300 ms on the tab's fallback. A viewport-prefetched link still pays it.
+  a consumer app (dev, a loaded machine): with the tab's loader skipped by
+  the hover's prefetch, a hover then a click 150 ms later showed the content
+  in 843 to 918 ms; with the tab prefetched whole, in 77 to 157 ms. The
+  deferred click pays the fill request and then React's 300 ms on the tab's
+  fallback. `prefetch: "intent"` buys the second number on hover; a
+  viewport-prefetched link still pays the first.
 - A click that adopts a prefetch with a flagged loader shows the page at once
   and sends one fill request for the flagged loaders. Read a flagged loader
   under its own `<Suspense>`: with no boundary, React keeps the page being
@@ -335,7 +339,7 @@ The rule: **prefetch broadly, and flag what is expensive.**
   or a grid does not prefetch each link again after every navigation. The server
   makes an answer page-only (`x-rsc-prefetch-scope: source`) when sharing it
   would be wrong: an intercept targets the route or the page sending it, the
-  answer defers a `prefetch: false` unit the page does not show yet, a
+  answer defers a flagged unit the page does not show yet, a
   `revalidate()` on the target read `currentUrl` and kept its segment, a rule
   on the route (or inside its `path()`) read the page being left and kept the
   segment through the route's default, or a kept answer sends no segment at
@@ -388,7 +392,8 @@ The rule: **prefetch broadly, and flag what is expensive.**
   and the list stays mounted under it; a document load of the URL renders the
   full page; Back closes the modal. Recipe 3.5.
 - An intercept's loaders each take their own `revalidate()`, and a flagged
-  `prefetch: false` loader opens the modal at once with its `loading()`. Its
+  (`prefetch: false` or `"intent"`) loader opens the modal at once with its
+  `loading()`. Its
   errors render the declaring layout's `errorBoundary()`.
 - Inside a group, `intercept()` takes a dot-local named target in the same
   definition and `loader()`/`loading()` only, and only navigations from inside

package/src/browser/navigation-bridge.ts

@@ -489,6 +489,9 @@ export function createNavigationBridge(
         // Clear intercept source URL to ensure server doesn't treat this as intercept
         store.setInterceptSourceUrl(null);
       }
+      // The page under an open intercept; null once leaving. Navigations
+      // send it so the server resolves the target from there.
+      const interceptSourceUrl = store.getInterceptSourceUrl() ?? undefined;
 
       // Before navigating away, update the source page's cache with the latest
       // handleData. This ensures the cache has correct handleData even if handles
@@ -560,6 +563,8 @@ export function createNavigationBridge(
         !cachedSegments.some((s) => s.type === "error") &&
         !isInterceptOnlyCache(cachedSegments) &&
         !isLeavingIntercept &&
+        // The history entry's segments are not what the client holds here.
+        !interceptSourceUrl &&
         !cached?.stale &&
         !options?._skipCache &&
         // A cached intercept entry for this URL (from any source page) means
@@ -637,6 +642,7 @@ export function createNavigationBridge(
             ? { type: "leave-intercept" as const }
             : {
                 type: "navigate" as const,
+                ...(interceptSourceUrl && { interceptSourceUrl }),
                 ...(hasUsableCache
                   ? {
                       targetCacheSegments: cachedSegments,

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/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,