@rangojs/router 0.33.2 → 0.34.1

package/skills/testing/serve-shell-request.md

@@ -20,13 +20,13 @@ A `Prerender` route is served as in production: from the artifact `router.matchF
 
 ### Options — `ServeShellRequestOptions`
 
-| Field        | Type                                                                                                                                                                       | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `cacheStore` | `SegmentCacheStore`                                                                                                                                                        | The store for this request, in place of the store your `createRouter({ cache })` config returns. The rest of that config (`enabled`, `searchParams`) still applies. Omit it to use the router's own store.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `env`        | `TEnv`                                                                                                                                                                     | Bindings, as `router.fetch(request, { env })` passes them. A function `cache` config receives them.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `headers`    | `HeadersInit`                                                                                                                                                              | Request headers (e.g. `cookie`). A document request defaults `accept` to `text/html`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `partial`    | `true \| { from?: string; rewriteTarget?: string; segments?: string[]; prefetch?: boolean; fill?: boolean; interceptSource?: string; stale?: boolean; boundary?: string }` | Serve the navigation request the browser sends instead of a document GET: from `from` (default the site root) with `segments` mounted (default none). `prefetch: true` sends the speculative kind a viewport or render `<Link>` prefetch sends (`X-Rango-Prefetch: 1`), so `prefetch: false` work is deferred; add `headers: { "X-Rango-Prefetch": "intent" }` to send a hover's or `prefetch()`'s intent prefetch instead, which defers nothing. `fill: true` sends the follow-up request (`_rsc_fill=1`) the browser makes after adopting a prefetch; pass the prefetch's delivered ids, without the deferred ones, as `segments`, and the same URL as `from`. `interceptSource` sends the intercept source (`X-RSC-Router-Intercept-Source`) the browser sends with the fill of an intercept, whose `from` is that source too. `rewriteTarget` sends what the page at `from` carried as its payload's `metadata.rewriteTarget` when middleware rewrote it (`_rsc_rt`), as the browser does, so the server diffs against the route that rendered that page. `stale: true` sends a stale request (`_rsc_stale`), as the browser sends it: every `revalidate()` sees `stale: true` (see `revalidate()`'s `stale`), segments take an action's revalidation defaults, and it renders live, as an action does: neither the route cache (`cache()`) nor the document cache serves or stores it, and a `ppr` route's `replayStatus` is `{ outcome: "BYPASS", reason: "stale" }`. `boundary` names the error segment of a thrown action's boundary the page at `from` shows (`_rsc_boundary`), as the background revalidation an earlier action owes that page sends it, with `stale: true` and no `segments`: the response renders every segment above the boundary and nothing at or below it, claims the boundary in `matched` and sends no segment for it. The server reads it only beside `stale`. |
-| `action`     | `{ ref: Function; id: string; args?: unknown[]; segments?: string[]; rewriteTarget?: string }`                                                                             | Send the request a JS server action call makes from the page at `url`: a POST of `args` (encoded as the browser encodes them) with `?_rsc_action`, the `rsc-action` header, `X-RSC-Router-Client-Path` and `_rsc_segments` (the page's mounted segment ids, default none), plus the page's `rewriteTarget` as for `partial`. Registers `ref` under `id` (`<module id>#<export name>`). Not with `partial` or `form`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| Field        | Type                                                                                                                                                                       | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `cacheStore` | `SegmentCacheStore`                                                                                                                                                        | The store for this request, in place of the store your `createRouter({ cache })` config returns. The rest of that config (`enabled`, `searchParams`) still applies. Omit it to use the router's own store.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `env`        | `TEnv`                                                                                                                                                                     | Bindings, as `router.fetch(request, { env })` passes them. A function `cache` config receives them.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `headers`    | `HeadersInit`                                                                                                                                                              | Request headers (e.g. `cookie`). A document request defaults `accept` to `text/html`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `partial`    | `true \| { from?: string; rewriteTarget?: string; segments?: string[]; prefetch?: boolean; fill?: boolean; interceptSource?: string; stale?: boolean; boundary?: string }` | Serve the navigation request the browser sends instead of a document GET: from `from` (default the site root) with `segments` mounted (default none). `prefetch: true` sends the speculative kind a viewport or render `<Link>` prefetch sends (`X-Rango-Prefetch: 1`), so `prefetch: false` and `prefetch: "intent"` work is deferred; add `headers: { "X-Rango-Prefetch": "intent" }` to send a hover's or `prefetch()`'s intent prefetch instead, which runs the `"intent"` work and defers the `false` work. `fill: true` sends the follow-up request (`_rsc_fill=1`) the browser makes after adopting a prefetch; pass the prefetch's delivered ids, without the deferred ones, as `segments`, and the same URL as `from`. `interceptSource` sends the intercept source (`X-RSC-Router-Intercept-Source`) the browser sends with the fill of an intercept, whose `from` is that source too. `rewriteTarget` sends what the page at `from` carried as its payload's `metadata.rewriteTarget` when middleware rewrote it (`_rsc_rt`), as the browser does, so the server diffs against the route that rendered that page. `stale: true` sends a stale request (`_rsc_stale`), as the browser sends it: every `revalidate()` sees `stale: true` (see `revalidate()`'s `stale`), segments take an action's revalidation defaults, and it renders live, as an action does: neither the route cache (`cache()`) nor the document cache serves or stores it, and a `ppr` route's `replayStatus` is `{ outcome: "BYPASS", reason: "stale" }`. `boundary` names the error segment of a thrown action's boundary the page at `from` shows (`_rsc_boundary`), as the background revalidation an earlier action owes that page sends it, with `stale: true` and no `segments`: the response renders every segment above the boundary and nothing at or below it, claims the boundary in `matched` and sends no segment for it. The server reads it only beside `stale`. |
+| `action`     | `{ ref: Function; id: string; args?: unknown[]; segments?: string[]; rewriteTarget?: string }`                                                                             | Send the request a JS server action call makes from the page at `url`: a POST of `args` (encoded as the browser encodes them) with `?_rsc_action`, the `rsc-action` header, `X-RSC-Router-Client-Path` and `_rsc_segments` (the page's mounted segment ids, default none), plus the page's `rewriteTarget` as for `partial`. Registers `ref` under `id` (`<module id>#<export name>`). Not with `partial` or `form`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 
 ### Returns — `ServeShellRequestResult`
 
@@ -294,6 +294,18 @@ expect(await fill.readDeferred()).toEqual([]); // a fill defers nothing
 
 `deliveredIds` is the payload's `metadata.matched`, read from `prefetch.flight`. Count the loader's runs in your own fixture: the prefetch ran it zero times, the fill once.
 
+For a loader marked `prefetch: "intent"`, send the hover's prefetch too: it runs that loader and still defers a `prefetch: false` one beside it.
+
+```ts
+const hover = await serveShellRequest(router, "/product/1", {
+  cacheStore,
+  headers: { "X-Rango-Prefetch": "intent" },
+  partial: { from: "/", prefetch: true },
+});
+// loader(RelatedLoader, { prefetch: "intent" }) ran; ReviewsLoader is deferred.
+expect(await hover.readDeferred()).toHaveLength(1);
+```
+
 ### Intercepts
 
 A prefetch of an `intercept()`'s target from its source page defers the intercept's flagged loaders, loader segments of its slot (`${parent}.@modalD${i}.${$$id}`). The browser sends the fill of an intercept from the source, with the intercept source header: pass both.

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/loader-store.ts

@@ -28,6 +28,10 @@
  *     cancelled on resubscribe so a StrictMode / transition remount does not
  *     reclaim a bucket that is about to be reused, and is held until any
  *     in-flight load settles.
+ *   - Owned buckets (one reader's private refresh-group bucket,
+ *     `useLoader(L, { refreshGroup })` without a key) are sticky while that
+ *     reader is mounted and dropped like an ephemeral bucket once it leaves:
+ *     no other reader names the bucket, and a remount takes a new one.
  *
  * Each router's NavigationStore owns one (navigation-store.ts), and hooks reach
  * it through NavigationStoreContext: the router store is the single source of
@@ -97,6 +101,13 @@ export interface SubscribeOptions {
    * subscriber attaches, and from then on resets via `clearFamily`.
    */
   ephemeral?: boolean;
+  /**
+   * When true, the bucket belongs to this subscriber alone (a private
+   * refresh-group bucket, which no other reader names): it is reset by
+   * `clearFamily` while subscribed, and dropped after the subscriber leaves
+   * even when sticky. Read at unsubscribe, so pass it on every subscribe.
+   */
+  owned?: boolean;
   /**
    * Cross-loader refresh group name(s). Tags this bucket so `refreshGroups(name)`
    * can refresh it alongside buckets of other loaders. A bucket may be tagged
@@ -130,8 +141,8 @@ interface InternalEntry {
   /** Family id (loader.$$id) this bucket belongs to. */
   loaderId: string;
   /**
-   * True once any non-ephemeral subscriber has attached. Sticky buckets are
-   * never reference-count-dropped; they reset via clearFamily().
+   * True once any non-ephemeral subscriber has attached. Sticky buckets reset
+   * via clearFamily() and are reference-count-dropped only when owned.
    */
   sticky: boolean;
   /** A deferred refcount-drop microtask is scheduled and not yet cancelled. */
@@ -223,8 +234,8 @@ export class LoaderStore {
    * Subscribe to entry changes for `bucketKey`.
    * Returns an unsubscribe function. A sticky bucket's entry is kept around even
    * after the last subscriber leaves so that an in-flight `load()` can still
-   * commit if the consumer remounts. An ephemeral bucket is dropped once its
-   * last subscriber leaves (deferred, see maybeScheduleRefcountClear).
+   * commit if the consumer remounts. An ephemeral or owned bucket is dropped
+   * once its last subscriber leaves (deferred, see maybeScheduleRefcountClear).
    */
   subscribe(
     bucketKey: string,
@@ -261,7 +272,7 @@ export class LoaderStore {
       // different groups stays in each group until ALL of that group's
       // subscribers have left (order-independent).
       for (const group of groups) this.releaseGroup(group, bucketKey, e);
-      this.maybeScheduleRefcountClear(bucketKey, e);
+      this.maybeScheduleRefcountClear(bucketKey, e, options?.owned);
     };
   }
 
@@ -354,17 +365,18 @@ export class LoaderStore {
   }
 
   /**
-   * Schedule a deferred drop for an ad-hoc (never-sticky) bucket whose last
-   * subscriber just left. Deferred to a microtask so a StrictMode / transition
-   * remount that resubscribes in the same tick cancels it.
+   * Schedule a deferred drop for an ad-hoc (never-sticky) or owned bucket
+   * whose last subscriber just left. Deferred to a microtask so a StrictMode /
+   * transition remount that resubscribes in the same tick cancels it.
    */
   private maybeScheduleRefcountClear(
     bucketKey: string,
     e: InternalEntry,
+    owned: boolean | undefined,
   ): void {
     if (e.listeners.size > 0) return;
-    // Sticky buckets persist for remount; they reset via clearFamily().
-    if (e.sticky) return;
+    // Sticky buckets persist for remount unless owned; they reset via clearFamily().
+    if (e.sticky && !owned) return;
     if (e.pendingClear) return;
     e.pendingClear = true;
     queueMicrotask(() => {
@@ -393,7 +405,7 @@ export class LoaderStore {
     }
   }
 
-  /** Drop an ephemeral bucket that settled with no subscribers left. */
+  /** Drop an ephemeral or owned bucket that settled with no subscribers left. */
   private dropIfSettled(bucketKey: string, e: InternalEntry): void {
     if (e.clearWhenSettled && e.listeners.size === 0) {
       e.clearWhenSettled = false;
@@ -523,7 +535,8 @@ export class LoaderStore {
    * Reset a single bucket entry. Bumps `latestRequestId` so any in-flight
    * `load()` whose promise is still pending will fail its gate when it resolves
    * and be dropped — prevents pre-navigation loads from clobbering the new
-   * route's context. The entry itself is kept (sticky-bucket semantics).
+   * route's context. The entry itself is kept (sticky-bucket semantics),
+   * unless it was only waiting for that request to be dropped.
    */
   clear(bucketKey: string): void {
     const e = this.entries.get(bucketKey);
@@ -532,6 +545,9 @@ export class LoaderStore {
     if (e.snapshot === EMPTY_SNAPSHOT) return;
     e.snapshot = EMPTY_SNAPSHOT;
     this.notify(e);
+    // An owned bucket left mid-flight waits for its request to settle, which
+    // the bump above stops from committing.
+    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