@rangojs/router 0.33.1 → 0.34.0

package/skills/loader/SKILL.md

@@ -1191,20 +1191,22 @@ The costs and constraints:
 Also available in `clientUrls()` route groups (`/client-urls`), where the
 loader-heavy shape makes it most useful.
 
-## `prefetch: false` — Keep a Loader Out of Speculative Prefetches
+## `prefetch: false` and `prefetch: "intent"` — Keep a Loader Out of Prefetches
 
 A `<Link>` prefetch is a navigation sent early: the server renders every
 handler and every loader for it. With the default `"viewport"` strategy that
 means a grid of forty product links runs forty copies of your slowest loader
 for pages most visitors never open. Pass `prefetch: false` to keep one loader
-out of those speculative (viewport and render) prefetches:
+out of every prefetch, or `prefetch: "intent"` to keep it out of the
+speculative ones only:
 
 ```tsx
 import { Suspense } from "react";
 
 path("/product/:slug", ProductPage, { name: "product" }, () => [
-  loader(PriceLoader), // cheap: still runs in the prefetch
-  loader(ReviewsLoader, { prefetch: false }), // expensive: skipped in a viewport prefetch
+  loader(PriceLoader), // cheap: runs in every prefetch
+  loader(RelatedLoader, { prefetch: "intent" }), // skipped in a viewport prefetch, runs on hover
+  loader(ReviewsLoader, { prefetch: false }), // expensive: skipped in every prefetch
   loading(<ProductSkeleton />),
 ]),
 ```
@@ -1212,22 +1214,30 @@ path("/product/:slug", ProductPage, { name: "product" }, () => [
 (`prefetch` sits beside `ssr` in `LoaderOptions`; combine them as
 `{ ssr: false, prefetch: false }` if you need both.)
 
-A hover is different: the visitor is about to click. A hover prefetch (on a
+| Request                                                      | unflagged  | `prefetch: false`        | `prefetch: "intent"`     |
+| ------------------------------------------------------------ | ---------- | ------------------------ | ------------------------ |
+| Document, navigation                                         | runs       | runs                     | runs                     |
+| Viewport or render prefetch (`X-Rango-Prefetch: 1`)          | runs       | skipped, filled at click | skipped, filled at click |
+| Hover, `useRouter().prefetch()` (`X-Rango-Prefetch: intent`) | runs       | skipped, filled at click | runs, no fill            |
+| A prefetch already cached or in flight when the hover lands  | used as is | used as is               | used as is               |
+
+A hover means the visitor is about to click. A hover prefetch (on a
 `"hover"`, `"viewport"` or `"adaptive"` link, or a delegated plain anchor) and
-`useRouter().prefetch()` send `X-Rango-Prefetch: intent` and run the loader
-with the rest of the page, so the click commits complete and sends no second
-request. A hover sends its prefetch only when the link has none cached or in
-flight: on a link a viewport prefetch already answered, the hover sends
-nothing and the click fills the deferred loader as below. The cost is plain:
-each hover that misses the prefetch cache runs the loader, so a pointer
-passing over a list of `"hover"` links runs it once per link. Touch devices
-have no hover (`"adaptive"` resolves to viewport there) and keep the fill.
-
-What happens in a speculative prefetch:
-
-- A **viewport or render prefetch** of the route does not run the loader and
-  does not read its `cache()`; the payload marks it deferred. The rest of the
-  page prefetches as usual.
+`useRouter().prefetch()` run a loader marked `"intent"` with the rest of the
+page; when every flagged loader and `loading()` on the route is marked
+`"intent"`, the click commits complete and sends no second request. A hover
+sends its prefetch only when the link has none cached or in flight: on a link
+a viewport prefetch already answered, the hover sends nothing and the click
+fills the deferred loader as below. The cost of `"intent"` is plain: each
+hover that misses the prefetch cache runs the loader, so a pointer passing
+over a list of `"hover"` links runs it once per link. Keep a loader that is
+too expensive for that on `false`. Touch devices have no hover (`"adaptive"`
+resolves to viewport there) and keep the fill.
+
+What happens in a prefetch that skips the loader:
+
+- The prefetch does not run the loader and does not read its `cache()`; the
+  payload marks it deferred. The rest of the page prefetches as usual.
 - Only on a loader new to the page. A loader already on screen is never
   deferred: if its revalidation (its `revalidate()` or the default) re-runs
   it, it runs in the prefetch with the rest of the destination, exactly as
@@ -1277,18 +1287,18 @@ function Reviews() {
 
 The limits:
 
-- **A click before its viewport prefetch has answered waits for it, then
-  fetches the deferred part.** The flag is there to keep expensive or slow
-  work out of every speculative prefetch, so that an API that is costly to
-  call is not called for every link a visitor might click. A click that comes
-  while the link's viewport or render prefetch is still in flight reuses that
-  prefetch, as it does without the
-  flag, and sends the fill when the prefetch answers. The page shows no later
+- **A click before its prefetch has answered waits for it, then fetches the
+  deferred part.** The flag is there to keep expensive or slow work out of
+  prefetches, so that an API that is costly to call is not called for every
+  link a visitor might click. A click that comes while the link's prefetch is
+  still in flight reuses that prefetch, as it does without the flag, and
+  sends the fill when the prefetch answers. The page shows no later
   than with no prefetch; the deferred part shows its fallback until the fill
   lands, and can complete later than a click with no prefetch, by up to what
   was left of the prefetch. That is the price of keeping the work out of the
-  prefetch. A click while a hover's prefetch is in flight adopts it with no
-  fill: the loader is already running in it.
+  prefetch. A click while a hover's prefetch is in flight, on a route whose
+  flags are all `"intent"`, adopts it with no fill: the loader is already
+  running in it.
 - **A navigation started before the fill answers cancels it.** It is
   cancelled when the newer navigation starts, not when that one commits. If
   the newer navigation then ends without replacing the page (a redirect the
@@ -1313,8 +1323,9 @@ The limits:
   every request kind (a document load included, so you see it the first time
   you open the page in development) if it calls `await ctx.rendered()`. The
   fill does not re-run the entry's handler, so there is no render to wait for
-  and no handle data to read. Remove `{ prefetch: false }` from the loader, or
-  stop calling `ctx.rendered()`. Pushing a handle from the loader is fine.
+  and no handle data to read. That holds for `"intent"` too, on every request.
+  Remove the `prefetch` flag from the loader, or stop calling
+  `ctx.rendered()`. Pushing a handle from the loader is fine.
 - **`ctx.set()` values from held handlers are not visible.** The fill runs the
   deferred work and middleware only. A handler or layout the client already
   holds does not run again, so a variable it set with `ctx.set()` is missing
@@ -1376,16 +1387,17 @@ The limits:
   need it), or drop the flag from a loader the page cannot render without.
 
 - **`clientUrls()` routes take it on `loader()`.** In a `clientUrls()`
-  definition `loader(Def, { prefetch: false })` works as here: a click
+  definition `loader(Def, { prefetch: false })` and `{ prefetch: "intent" }`
+  work as here: a click
   inside the group shows the destination at once, commits the prefetched
   data with the URL, and one fill runs the flagged loaders (see
   `/client-urls` → "`prefetch: false`"). A flagged `loading()` defers nothing
   on a group route, from the group or from a server layout above it.
-- **Inside `intercept()`.** In `urls()` and in `clientUrls()`, a viewport or
-  render prefetch of the intercept's target from its source page defers the
-  flagged loader (a hover's runs it, and its click sends no fill): the
-  click opens the modal at once, with its `loading()`, and one fill, sent
-  from the source, runs the loader. The page under the modal stays. With no
+- **Inside `intercept()`.** In `urls()` and in `clientUrls()`, a prefetch of
+  the intercept's target from its source page defers the flagged loader (a
+  hover's runs a loader marked `"intent"`, and its click sends no fill for
+  it): the click opens the modal at once, with its `loading()`, and one fill,
+  sent from the source, runs the loader. The page under the modal stays. With no
   `loading()` the slot is empty until the fill answers, as on a plain click
   until its response. The modal's loaders resolve together: it shows its
   `loading()` until every one has arrived. A flagged `loading()` inside
@@ -1401,13 +1413,14 @@ The limits:
   `/caching`, `/prerender`, `/ppr` → "`prefetch: false` on a `ppr` route").
 
 To skip a handler along with its loaders, flag the `loading()` instead (see
-`/route` → "`loading()` options"). `loader(Def, { prefetch: false })` accepts
-only a boolean; anything else throws `loader() prefetch must be a boolean`.
+`/route` → "`loading()` options"). `loader(Def, { prefetch })` accepts a
+boolean or `"intent"`; anything else throws
+`loader() prefetch must be a boolean or "intent"`.
 
 Test it with `serveShellRequest(router, url, { partial: { prefetch: true } })`
 and `result.readDeferred()` (see `/testing`). That is a speculative prefetch;
 add `headers: { "X-Rango-Prefetch": "intent" }` to serve a hover's, which
-defers nothing.
+runs the `"intent"` loaders and defers the `false` ones.
 
 ## Fetchable Loaders
 

package/skills/ppr/SKILL.md

@@ -1176,7 +1176,7 @@ document request captured:
 | Replays a shell a document request captured (`HIT`)    | Served from its pin, not deferred, never run; the click sends nothing |
 | Replays a navigation-only shell, or misses (cold page) | Deferred: the click sends one fill that runs it                       |
 | Serves an explicit `cache()` hit                       | Deferred: the click sends one fill that runs it                       |
-| Hover prefetch (`X-Rango-Prefetch: intent`)            | Never deferred                                                        |
+| Hover prefetch (`X-Rango-Prefetch: intent`)            | As the rows above; a loader marked `prefetch: "intent"` runs instead  |
 
 A cold prefetch still schedules the background capture that stores the
 page's navigation shell, and that capture runs the loader once. Once a

package/skills/route/SKILL.md

@@ -242,10 +242,11 @@ path("/product/:slug", ProductPage, { name: "product" }, () => [
 
 `loading(fallback, options?)` takes two options:
 
-| Option            | Effect                                                                                                                                                            |
-| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ssr: false`      | Skip the fallback on document requests; it shows on client navigations only.                                                                                      |
-| `prefetch: false` | Keep everything behind this fallback out of viewport and render prefetches (a hover prefetch runs it); the click shows the fallback and fetches that part itself. |
+| Option               | Effect                                                                                                                                    |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `ssr: false`         | Skip the fallback on document requests; it shows on client navigations only.                                                              |
+| `prefetch: false`    | Keep everything behind this fallback out of every prefetch, hovers included; the click shows the fallback and fetches that part itself.   |
+| `prefetch: "intent"` | The same for viewport and render prefetches; a hover prefetch or `useRouter().prefetch()` runs it, and its click sends no second request. |
 
 ```tsx
 path("/orders", OrdersPage, { name: "orders" }, () => [
@@ -255,13 +256,17 @@ path("/orders", OrdersPage, { name: "orders" }, () => [
 ```
 
 **What `prefetch: false` defers.** The flag applies when the entry is new to
-the browser: the page the prefetch is sent from does not show it. A viewport
-or render prefetch then skips the entry's handler, its loaders, its orphan layouts and its
+the browser: the page the prefetch is sent from does not show it. A prefetch
+then skips the entry's handler, its loaders, its orphan layouts and its
 parallel slots. On a `layout()` the fallback covers the whole outlet, so every
 deeper entry is skipped with it. A parallel slot with its own flagged
 `loading()` is a separate unit: the route beside it still renders in the
 prefetch. The prefetch payload carries a placeholder for each skipped piece,
-marked deferred, with its fallback: the page's skeleton.
+marked deferred, with its fallback: the page's skeleton. `prefetch: "intent"`
+defers the same pieces in a viewport or render prefetch; a hover's prefetch
+renders them, so a route whose flags are all `"intent"` is prefetched whole
+on hover. Everything below about `false` holds for `"intent"` in the
+prefetches that defer it.
 
 **An entry the browser already holds is never deferred.** Inside a section
 whose `layout()` has a flagged `loading()`, the layout is on screen, so its
@@ -347,7 +352,7 @@ the block's work, its loaders included, out of prefetches. See `/caching`,
   flag does nothing there. The last `loading()` on an entry wins, flag
   included.
 - A loader behind the fallback cannot call `ctx.rendered()`; it throws on every
-  request kind. See `/loader` → "`prefetch: false`" for this and the other
+  request kind, for either flag. See `/loader` → "`prefetch: false`" for this and the other
   loader limits (`ctx.set()` values, late `redirect()`/`notFound()`, a loader a
   handler awaits).
 - A layout the client already holds is not deferred (its fallback would not
@@ -373,7 +378,8 @@ the block's work, its loaders included, out of prefetches. See `/caching`,
 - `clientUrls()` routes and `intercept()` ignore the flag.
 
 To defer a single loader and keep the handler in the prefetch, use
-`loader(Def, { prefetch: false })` instead (see `/loader`).
+`loader(Def, { prefetch: false })` or `{ prefetch: "intent" }` instead (see
+`/loader`).
 
 A `loading()` skeleton that has appeared stays at least about 300 ms before React reveals what replaces it (React's fallback throttle, [#1078](https://github.com/rangojs/rango/issues/1078)); see "Streaming with Suspense" in [loader](../loader/SKILL.md).
 

package/skills/testing/SKILL.md

@@ -101,6 +101,7 @@ Each primitive links to its sub-file (API + recipe + caveats).
 | a handle's `collect`/accumulator, a seeded handle read, or a loader handle write                                                   | unit         | [`collectHandle` / seeded `handles` / `handlePushes`](./handles.md)                                                   | `@rangojs/router/testing`        |
 | a CLIENT component reading router context (`useParams`/`useReverse`/`Outlet`/`useNavigation`/`useLoader`)                          | unit (DOM)   | [`renderRoute`](./client-components.md)                                                                               | `@rangojs/router/testing/dom`    |
 | a stale indicator from `useLoader().isLoading` while a `transition()` navigation re-runs the loader                                | unit (DOM)   | [`renderRoute` + `navigate(url, { loaders })`](./client-components.md#held-navigation)                                | `@rangojs/router/testing/dom`    |
+| a component that refreshes with `useLoader().load()` or `useRefreshLoaders()`, and the readers that show the answer                | unit (DOM)   | [`renderRoute` + `router.respondToLoads`](./client-components.md#load-and-refresh-groups)                             | `@rangojs/router/testing/dom`    |
 | a component reading `useLocationState(Def)` after `router.push(url, { state: [Def(value)] })`                                      | unit (DOM)   | [`renderRoute` + `withLocationStateKey`](./client-components.md#location-state)                                       | `@rangojs/router/testing[/dom]`  |
 | location state while a navigation is pending (a loader the test holds), or after a back/forward                                    | unit (DOM)   | [`navigate(url, { state, loaders })`, a `popstate` event](./client-components.md#state-while-a-navigation-is-pending) | `@rangojs/router/testing[/dom]`  |
 | a CLIENT component's hydration: its first client render against its own server HTML (`typeof window`, a late `<Suspense>`)         | unit (DOM)   | [`renderRoute` + `hydrate: true`](./client-components.md#hydration)                                                   | `@rangojs/router/testing/dom`    |

package/skills/testing/client-components.md

@@ -33,23 +33,23 @@
 
 ### Context — client hooks it makes resolve (what your code receives)
 
-| Hook                           | Meaning                                                                                       |
-| ------------------------------ | --------------------------------------------------------------------------------------------- |
-| `useParams`                    | Params from the matched leaf pattern, with `options.params` merged over.                      |
-| `useReverse`                   | Reverse a name->pattern map to a URL; merges `useParams()` and the `mount`/`basename` prefix. |
-| `useHref`                      | Resolve an href against the mount/basename.                                                   |
-| `useMount`                     | The `include()` mount prefix (`options.mount`), else `"/"`.                                   |
-| `useNavigation`                | Navigation controller state: `loading` from a `navigate()` call to its commit, else `idle`.   |
-| `useRouter`                    | The router handle, including `.basename`.                                                     |
-| `usePathname`                  | Current committed pathname.                                                                   |
-| `useSearchParams`              | Search params from the `request` URL.                                                         |
-| `useNonce`                     | SEEDED CSP nonce (`options.nonce`), else `undefined` (the browser default).                   |
-| `useLoader` / `useFetchLoader` | SEEDED loader data (read path, not run path). Held-navigation `isLoading` is modeled (below). |
-| `useLocationState`             | SEEDED `history.state` value, or the `state` a navigation or a `popstate` brought (below).    |
-| `useHandle`                    | SEEDED handle output (globally accumulated).                                                  |
-| `Outlet`                       | Renders the next segment in the chain (layout nesting).                                       |
-| `useOutlet`                    | Next-segment `content` plus SEEDED `options.outletPending`.                                   |
-| `useTheme`                     | Theme; throws without `options.theme` (see caveat).                                           |
+| Hook                           | Meaning                                                                                                                                                                       |
+| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `useParams`                    | Params from the matched leaf pattern, with `options.params` merged over.                                                                                                      |
+| `useReverse`                   | Reverse a name->pattern map to a URL; merges `useParams()` and the `mount`/`basename` prefix.                                                                                 |
+| `useHref`                      | Resolve an href against the mount/basename.                                                                                                                                   |
+| `useMount`                     | The `include()` mount prefix (`options.mount`), else `"/"`.                                                                                                                   |
+| `useNavigation`                | Navigation controller state: `loading` from a `navigate()` call to its commit, else `idle`.                                                                                   |
+| `useRouter`                    | The router handle, including `.basename`.                                                                                                                                     |
+| `usePathname`                  | Current committed pathname.                                                                                                                                                   |
+| `useSearchParams`              | Search params from the `request` URL.                                                                                                                                         |
+| `useNonce`                     | SEEDED CSP nonce (`options.nonce`), else `undefined` (the browser default).                                                                                                   |
+| `useLoader` / `useFetchLoader` | SEEDED loader data (read path, not run path). Held-navigation `isLoading` is modeled (below), and `load()` is answered from the seeds ([`load()`](#load-and-refresh-groups)). |
+| `useLocationState`             | SEEDED `history.state` value, or the `state` a navigation or a `popstate` brought (below).                                                                                    |
+| `useHandle`                    | SEEDED handle output (globally accumulated).                                                                                                                                  |
+| `Outlet`                       | Renders the next segment in the chain (layout nesting).                                                                                                                       |
+| `useOutlet`                    | Next-segment `content` plus SEEDED `options.outletPending`.                                                                                                                   |
+| `useTheme`                     | Theme; throws without `options.theme` (see caveat).                                                                                                                           |
 
 ### Returns — `RenderRouteResult`
 
@@ -77,8 +77,11 @@ type RenderRouteResult = RenderResult & {
       },
     ): Promise<void>;
     // re-render the current location, as router.refresh() does:
-    // a spec's when gets kind "revalidate" (`to` is `from`)
-    refresh(): Promise<void>;
+    // a spec's when gets kind "revalidate" (`to` is `from`); `loaders` is the
+    // data the response carries
+    refresh(options?: {
+      loaders?: ReadonlyArray<readonly [LoaderDefinition<any>, unknown]>;
+    }): Promise<void>;
     // keep `url` as a prefetch made now carries it (the seeds then, `loaders`
     // over them); a later navigate(url) without `loaders` commits that data
     prefetch(
@@ -94,6 +97,11 @@ type RenderRouteResult = RenderResult & {
       loaders?: ReadonlyArray<readonly [LoaderDefinition<any>, unknown]>;
       keepClientCache?: boolean;
     }): Promise<void>;
+    // what a later useLoader().load() (or refreshGroup refresh) of each
+    // loader resolves to; renders nothing
+    respondToLoads(options: {
+      loaders?: ReadonlyArray<readonly [LoaderDefinition<any>, unknown]>;
+    }): void;
     pathname(): string;
     params(): Record<string, string>;
     store: NavigationStore; // advanced
@@ -454,6 +462,46 @@ it("dims the held price while the next product streams", async () => {
 - Pass settled data as a plain value, not `Promise.resolve(value)`: React has not observed a plain promise yet, so it counts as pending and renders one `stale` frame. (A Flight chunk that has already settled carries its status and is skipped, which a plain value mirrors.)
 - `loading()` is not a spec field: a `<Suspense>` in your layout component stands in for it.
 
+## `load()` and refresh groups
+
+`useLoader().load()`, `useFetchLoader().load()` and a `useRefreshLoaders()` refresh reach renderRoute's loader endpoint, so a refresh button, a polling component, or a value one reader refreshes and another shows is unit-testable without a server or a `fetch` stub. The endpoint answers a GET for a loader with the last value the test gave it: the render-time `loaders`/`loaderData`, or `router.respondToLoads({ loaders })`, which only sets the answer (a `navigate()`, `prefetch()`, `action()` or `refresh()` seeds the page it commits, not the answer). A `load({ params })` is answered with a `loaderError`. The value is read when `load()` sends its request. A pending Promise holds the answer until it settles (`isLoading` stays `true`), and a rejected one arrives as the loader's error. The value reaches the component as given, never serialized.
+
+The answer decodes through `@vitejs/plugin-rsc/browser`, which `rangoTestAliases()` (and `rangoTestConfig()`) alias to the testing kit's stub; remove any `vi.mock("@vitejs/plugin-rsc/browser")` you wrote for it.
+
+```tsx
+import { fireEvent, waitFor } from "@testing-library/react";
+import { renderRoute } from "@rangojs/router/testing/dom";
+import { useLoader } from "@rangojs/router/client";
+import { CartLoader } from "../src/loaders"; // createLoader(fn, true)
+
+function CartBadge() {
+  const { data, load, isLoading } = useLoader(CartLoader);
+  return (
+    <button data-testid="cart" onClick={() => load()}>
+      {isLoading ? "..." : data.count}
+    </button>
+  );
+}
+
+it("refreshes the count from the server", async () => {
+  const { getByTestId, router } = await renderRoute(
+    [{ path: "/cart", Component: CartBadge }],
+    { request: "/cart", loaders: [[CartLoader, { count: 1 }]] },
+  );
+  router.respondToLoads({ loaders: [[CartLoader, { count: 3 }]] });
+  fireEvent.click(getByTestId("cart"));
+  // load() loads its decoder lazily: wait for the answer, not one act()
+  await waitFor(() => expect(getByTestId("cart").textContent).toBe("3"));
+});
+```
+
+| `load()` call                                                 | Under `renderRoute`                                                                                                                                                                                                    |
+| ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `load()` with no options, a `key`, or a `refreshGroup`        | Answered. Readers of a registered loader converge on the value; a reader that mounts later, or that a navigation brings new route data, shows that route data instead, as in production.                               |
+| `load({ params })`, `load({ method: "POST", body })`          | NOT answered: the request goes to the `fetch` your test environment has. Test the loader body with `runLoader`, and the round trip at e2e.                                                                             |
+| A loader the test never gave a value                          | Answered with an error naming the loader (`error` set; `throwOnError` throws it).                                                                                                                                      |
+| Any other request (a navigation's or action's Flight payload) | Passed through to the `fetch` installed before the mount. renderRoute never decodes one: a `navigate()` or `action()` seeds its data directly. A `fetch` stub the test installs after the mount replaces the endpoint. |
+
 ## Caveats
 
 - Client tree ONLY. Does NOT catch server/client boundary reference-identity remount bugs, real Flight serialization errors, loader execution, middleware, or handler ordering — those are `renderServerTree` / `renderHandler` / e2e territory. Loader data is SEEDED, never run. `hydrate: true` adds an HTML pass of this same client tree ([Hydration](#hydration)), not a render of your routes on a server.

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/history-state.ts

@@ -8,6 +8,7 @@ import {
   replaceCurrentHistoryState,
   resolveLocationStateEntries,
   stampLocationState,
+  type LocationStateSnapshot,
 } from "./react/location-state-shared.js";
 import { WIRE } from "../wire-params.js";
 
@@ -110,6 +111,53 @@ export function buildHistoryState(
   return Object.keys(result).length > 0 ? result : null;
 }
 
+/**
+ * The entry a commit onto the entry on screen writes (router.refresh(), the
+ * cross-tab refresh): `entryState`, read when the commit lands, keeps its
+ * location state. Its scroll key and idx go (pushHistoryWithIdx and
+ * ensureHistoryKey write them again), and its intercept marks are this
+ * commit's: a refresh renders the URL's full page. Server-set state merges
+ * over the kept state. A flash a reader already cleared from the entry stays
+ * cleared: the entry is copied, never rebuilt from what readers show.
+ */
+export function keptEntryState(
+  entryState: unknown,
+  routerState?: { intercept?: boolean; sourceUrl?: string },
+  serverState?: Record<string, unknown>,
+): Record<string, unknown> | null {
+  let result: Record<string, unknown> =
+    entryState !== null && typeof entryState === "object"
+      ? { ...entryState }
+      : {};
+  delete result.key;
+  delete result.idx;
+  delete result.intercept;
+  delete result.sourceUrl;
+  if (routerState?.intercept) {
+    result.intercept = true;
+    if (routerState.sourceUrl) result.sourceUrl = routerState.sourceUrl;
+  }
+  if (serverState && Object.keys(serverState).length > 0) {
+    result = addLocationState(result, serverState);
+  }
+  return Object.keys(result).length > 0 ? result : null;
+}
+
+/**
+ * What readers get from a commit onto the entry on screen: the state they
+ * show, plus the server's, recorded under the client's version. Not re-read
+ * from the entry, so a flash value on screen stays until the next navigation
+ * or back/forward.
+ */
+export function shownLocationState(
+  shown: LocationStateSnapshot,
+  serverState?: Record<string, unknown>,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = { ...shown, ...serverState };
+  stampLocationState(result);
+  return result;
+}
+
 /** Check if a history state object contains location state keys. */
 export function hasLocationState(state: unknown): boolean {
   if (!state || typeof state !== "object") return false;

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,
@@ -769,7 +775,12 @@ export function createNavigationBridge(
           [],
           false,
           tx.handle.signal,
-          tx.with({ url: window.location.href, replace: true, scroll: false }),
+          tx.with({
+            url: window.location.href,
+            replace: true,
+            scroll: false,
+            sameEntry: true,
+          }),
           { type: "navigate", refresh: true, boundary: shown[at]?.id },
         );
       } catch (error) {