@rangojs/router 0.32.0 → 0.33.0

package/skills/links/SKILL.md

@@ -457,7 +457,7 @@ export const useAccountReverse = () => useReverse(accountRoutes);
 Components call `useAccountReverse()`; a renamed or moved module changes one
 file. The wrapper resolves like `useReverse`: against the nearest `include()`
 mount, so call a module's hook from components under that module's own mount.
-Inside a nested module it builds a wrong URL with no error (dc-t57); pass
+Inside a nested module it builds a wrong URL with no error; pass
 cross-module links from the server there.
 
 ### How it resolves
@@ -542,7 +542,7 @@ Both happen synchronously during `reverse()` — wrap calls in try/catch (or an
 
 ### The leading dot is optional
 
-`reverse("post")` and `reverse(".post")` resolve **identically** — the leading dot is cosmetic. The map you import IS the scope, so there is no separate global namespace to disambiguate and the dot carries no meaning; it exists only as a readability convention and for parity with `ctx.reverse(".name")` on the server. A module's `routes` map is right only inside that module's own mount: it resolves against the current mount, so another module's map gives a wrong URL with no error, and `useReverse(NamedRoutes)` is correct only at the root mount (under a mount it double-prefixes). There is no client API for links that cross modules under a nested mount (dc-t57). Build them on the server, where global names resolve fully, and pass them down:
+`reverse("post")` and `reverse(".post")` resolve **identically** — the leading dot is cosmetic. The map you import IS the scope, so there is no separate global namespace to disambiguate and the dot carries no meaning; it exists only as a readability convention and for parity with `ctx.reverse(".name")` on the server. A module's `routes` map is right only inside that module's own mount: it resolves against the current mount, so another module's map gives a wrong URL with no error, and `useReverse(NamedRoutes)` is correct only at the root mount (under a mount it double-prefixes). There is no client API for links that cross modules under a nested mount. Build them on the server, where global names resolve fully, and pass them down:
 
 ```tsx
 // server layout or handler
@@ -619,7 +619,8 @@ A prefetch is a navigation sent early (a partial request with an
 `X-Rango-Prefetch` header), and by default the server renders everything for
 it: every handler and every loader. That is the point, a click then commits
 without a request, but it is also forty renders for a grid of forty links.
-Keep the expensive part out of the prefetch on the route, not on the link:
+Keep the expensive part out of speculative (viewport, render) prefetches on
+the route, not on the link:
 
 ```tsx
 // skip one loader
@@ -632,11 +633,107 @@ A click that adopts such a prefetch commits what was prefetched, shows the
 fallback for the deferred part, and sends one extra request for it. Only what
 is new to the page is deferred: a segment already on screen (the layout of the
 section you are in, the route itself on `/product/a` to `/product/b`) is
-prefetched as usual. See
+prefetched as usual.
+
+A hover prefetch is treated as intent and runs everything, flagged work
+included (`X-Rango-Prefetch: intent`, where a viewport or render prefetch
+sends `1`); so does `useRouter().prefetch()`. Its click commits complete with
+no extra request. A hover sends that request only when the link has no
+prefetch cached or in flight: on a viewport link whose prefetch has already
+answered, it sends nothing, and the click fetches the deferred part as above.
+See
 `/loader` → "`prefetch: false`" and `/route` → "`loading()` options". To stop
 a link or a whole section from prefetching at all, use the `prefetch` prop or
 `data-prefetch-scope` above.
 
+### Shared prefetches and `prefetchKey`
+
+A prefetch is stored for its target URL and shared by every page. A link to
+`/products/42` prefetched on the home page is not fetched again on the search
+page or on page 2 of a list, and a click from any of them adopts that one
+entry. This is deliberate: without it, a paginated list or a product grid
+would prefetch every visible link again after each navigation.
+
+The answer is a diff against the page that asked. The server leaves out the
+segments that page already shows, and the click fills them from the copies on
+screen. A shared answer is right on every page as long as that diff does not
+depend on which page asked. With the defaults it does not: a standalone layout
+is held from every page that shows it, and a route, with any layout inside its
+`path()`, re-renders whenever its params or search change.
+
+When the diff does depend on the page, the server scopes the answer. A
+click from a page outside the scope then sends its own request.
+
+The answer is page-only (`x-rsc-prefetch-scope: source`) when:
+
+- An intercept targets the route, or the page that sent the prefetch,
+  whether or not it applies here.
+- The answer defers a `prefetch: false` loader or `loading()` that the page
+  does not show yet (a viewport or render prefetch; a hover's defers nothing).
+- A `revalidate()` on the target read `currentUrl` and kept its segment.
+- A `revalidate()` on the route, or on a segment inside its `path()`, read
+  the page being left and kept the segment through the route's default
+  (it returned `undefined`, or the `defaultShouldRevalidate` it was given).
+  That default compares the target's params and search with the page's,
+  which no read records.
+- The answer kept a segment for the page that asked and sends no segment at
+  all: a page that adopted it would keep its whole tree.
+
+The answer is shared between a group of pages
+(`x-rsc-prefetch-scope: params; <label>`) when:
+
+- A `revalidate()` on the target read `currentParams` or `fromRouteName`
+  and kept its segment. That keep was decided from what the rule read, so it
+  is right on every page with equal values of those reads, and only there:
+  another page holds a copy rendered for other params. The server records
+  each param a rule reads by name (a spread, `JSON.stringify` or
+  `structuredClone` reads them all), the route name for `fromRouteName`, and
+  the page's set of params, and answers with the values; the browser stores
+  the answer under them and looks it up with the params of the page on
+  screen. The locale rule (`currentParams.locale !== nextParams.locale`)
+  shares each prefetch between the pages of one locale.
+- The target is prerendered and the page that asked has the same route
+  params: the stored answer keeps a layout that has `revalidate()` rules
+  without running them, which is right for the pages with the same params.
+
+A scoped answer, page-only or grouped, is sent `cache-control: private,
+no-cache` over the route's own header, and the document cache does not store
+it: a shared cache keys a navigation by its URL, not by the page that sent it
+(`/document-cache` → "What's NOT Cached").
+
+Page-only entries are keyed by the page's full URL, query string and hash
+included, so each page prefetches those targets again: `?page=2` and `?page=3`
+each make their own. Grouped entries are shared by `?page=2` and `?page=3`
+when the rule did not read the page. The answer stays correct either way;
+the cost is the sharing. Read the params a rule needs by name and avoid
+`currentUrl` in a rule on a layout above most of the app.
+`/app-structure` → "Prefetches are shared" lists the structures that need no
+such rule.
+
+`prefetchKey=":source"` asks for the same scope on one link, for a target
+whose answer depends on the page that sent it in a way the server cannot
+see:
+
+```tsx
+<Link to={href} prefetchKey=":source">
+  Back to results
+</Link>;
+// The same for a programmatic prefetch
+router.prefetch(href, { key: ":source" });
+```
+
+The server tracks only the three fields above. Use the key when the
+dependency runs through anything else:
+
+- `context` in a `revalidate()` (the handler context: the request, its
+  headers and cookies, and middleware variables);
+- a handler, loader or middleware that reads the request's `Referer`, which
+  the browser sets to the page that sent the prefetch (unless the page's
+  `Referrer-Policy` strips it).
+
+`":source"` is the only value. It costs the same as a page-only entry, so put
+it on the links that need it, never on every link of an app.
+
 ## When to use what
 
 | Context          | API                                                | Resolves                                  | Use for                                                          |

package/skills/loader/SKILL.md

@@ -218,7 +218,11 @@ Loaders receive a request-scoped context that shares its read surface with
 route handlers (`params`, `request`, `url`, `env`, `get`, `use`, `reverse`).
 It has no handler-only writers: there is no `ctx.set`, `ctx.headers`, or
 `ctx.setLocationState` (a loader can stream after the response has started,
-so response-shaping belongs in middleware or the handler).
+so response-shaping belongs in middleware or the handler). Calling
+`getRequestContext().setLocationState()` from a loader is not supported
+either: the payload takes the request's location state before loaders
+settle, so such a write may arrive or may be dropped, and a `ppr` shell HIT
+never sends it (see `/hooks` `state.md`, "State on a document response").
 
 ### Full field surface
 
@@ -490,7 +494,11 @@ the same `$id ?? $$id` precedence the router uses to derive `actionId`, so it
 matches in both dev and production. The raw `actionId` string stays available on
 the same context as an escape hatch, alongside `actionResult`, `formData`,
 `actionUrl`, `currentParams`/`nextParams`, `currentUrl`/`nextUrl`,
-`fromRouteName`/`toRouteName`, and the full handler `context`.
+`fromRouteName`/`toRouteName`, and the full handler `context`. Reading
+`currentParams` or `fromRouteName` and keeping the segment shares a prefetch
+of that answer only between the pages with equal values of what was read;
+reading `currentUrl` makes it page-only (`/links` → "Shared prefetches and
+`prefetchKey`"); `context` is not tracked.
 
 ### Revalidation Contracts for Loader Dependencies
 
@@ -1183,20 +1191,20 @@ 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 Prefetches
+## `prefetch: false` — Keep a Loader Out of Speculative 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:
+out of those speculative (viewport and render) prefetches:
 
 ```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 prefetch
+  loader(ReviewsLoader, { prefetch: false }), // expensive: skipped in a viewport prefetch
   loading(<ProductSkeleton />),
 ]),
 ```
@@ -1204,11 +1212,22 @@ path("/product/:slug", ProductPage, { name: "product" }, () => [
 (`prefetch` sits beside `ssr` in `LoaderOptions`; combine them as
 `{ ssr: false, prefetch: false }` if you need both.)
 
-What happens:
-
-- A **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.
+A hover is different: 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.
 - 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
@@ -1258,16 +1277,18 @@ function Reviews() {
 
 The limits:
 
-- **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
-  every 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
-  prefetch is still in flight reuses that prefetch, as it does without the
+- **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
   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.
+  prefetch. A click while a hover's prefetch is in flight 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
@@ -1360,8 +1381,9 @@ The limits:
   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 prefetch of
-  the intercept's target from its source page defers the flagged loader: the
+- **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
   `loading()` the slot is empty until the fill answers, as on a plain click
@@ -1371,16 +1393,21 @@ The limits:
   `revalidate()`, so an action from the modal re-runs only those that say so
   (see `/intercept`).
 - **`ppr` and `ssr: false`.** On a `ppr` route an `ssr: false` loader is the
-  bake lane and is served from the shell, so `prefetch: false` is ignored for
-  it and development logs a warning. Under `cache()` and `Prerender` the flag
-  works as above (see `/caching`, `/prerender`, `/ppr`).
+  bake lane. A prefetch that replays a shell a document request captured
+  serves it from its pin: it is not deferred, does not run, and the click
+  sends nothing. Every other prefetch (a navigation-only shell, a cold page,
+  an explicit `cache()` hit) defers it as above, and the click sends one
+  fill. Under `cache()` and `Prerender` the flag works as above (see
+  `/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`.
 
 Test it with `serveShellRequest(router, url, { partial: { prefetch: true } })`
-and `result.readDeferred()` (see `/testing`).
+and `result.readDeferred()` (see `/testing`). That is a speculative prefetch;
+add `headers: { "X-Rango-Prefetch": "intent" }` to serve a hover's, which
+defers nothing.
 
 ## Fetchable Loaders
 

package/skills/migrate-nextjs/SKILL.md

@@ -649,6 +649,11 @@ parallel({ "@sidebar": BlogSidebar }, () => [
 ]);
 ```
 
+The sidebar rule reads `currentParams` and keeps the sidebar on an unchanged
+`:slug`, so a prefetch of the same post (another tab, `?sort=`) is shared by
+the pages of that post: the rule read its slug. Links to other posts stay
+shared. `/links` → "Shared prefetches and `prefetchKey`".
+
 **Server-side caching** — `cache()` DSL, loader-level `cache()`, and `"use cache"`
 control what gets cached and for how long. This is separate from `revalidate()`:
 
@@ -833,8 +838,9 @@ router cache — map to Rango's prefetch system: per-Link
 option) warms the target's partial RSC payload before the click, and a click
 on a warmed link commits the prefetched payload as a whole — the complete
 page lands instantly, no fetch waterfall. Prefetched entries survive being
-used (they re-arm in place) and expire by `prefetchCacheTTL`; actions and
-`invalidateClientCache()` flush them so a stale payload is never committed.
+used (they re-arm in place) and expire by `prefetchCacheTTL`.
+`invalidateClientCache()` flushes them; a server action marks them stale, so
+a click on one shows it and then revalidates the page in the background.
 
 ```tsx
 <Link to="/product/widget" prefetch="viewport">

package/skills/migrate-react-router/data-and-actions.md

@@ -245,6 +245,11 @@ path("/product/:slug", ProductPage, { name: "product" }, () => [
 ]);
 ```
 
+On an unchanged `:slug` this rule keeps the route after reading `currentParams`,
+so a prefetch of the same product (a tab, `?sort=price`) is shared by the
+pages of that product: the rule read its slug. Links to other products stay
+shared. `/links` → "Shared prefetches and `prefetchKey`".
+
 Note: RR7's `shouldRevalidate` controls client-side loader re-fetching. Rango's
 `revalidate()` controls which segments re-run during partial rendering after
 navigation or actions. The intent is the same — skip unnecessary work — but

package/skills/ppr/SKILL.md

@@ -512,6 +512,13 @@ full: a HIT runs no handler, so a handler's `ctx.setLocationState()` does not
 happen on a HIT. Set it from middleware (see `/hooks` `state.md`, "State on a
 document response").
 
+A HIT sends exactly the state set before its render: its headers, which
+make it `private, no-store`, leave before the tail runs, so a write during
+the tail (a loader calling `getRequestContext().setLocationState()`, which
+is not supported) is not sent. A HIT that read a document redirect's cookie
+and then degrades into a reload sets the cookie again from its reload
+script, so the forced MISS still carries the state.
+
 ### Opting out per request with `ctx.dynamic()`
 
 Middleware and handlers can call `ctx.dynamic()` to force this request onto a
@@ -1158,11 +1165,25 @@ A `ppr` route's handler output is stored, so a `loading()` flagged with
 and its partial replay are served as usual and only the live loaders behind
 the fallback are deferred. A live loader registered with `{ prefetch: false }` is
 skipped the same way, and the click that adopts the prefetch sends one fill
-request for it. An `ssr: false` loader is the bake lane and is served from the
-shell, so on a `ppr` route `prefetch: false` is ignored for it, and
-development logs a warning that the loader "is registered with ssr: false
-and prefetch: false on a ppr route"; drop one of the two options. See
-`/loader` → "`prefetch: false`".
+request for it.
+
+An `ssr: false` loader (the bake lane) registered with `{ prefetch: false }`
+is deferred too, unless the prefetch serves it from a pin of a shell a
+document request captured:
+
+| The prefetch                                           | The flagged `ssr: false` loader                                       |
+| ------------------------------------------------------ | --------------------------------------------------------------------- |
+| 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                                                        |
+
+A cold prefetch still schedules the background capture that stores the
+page's navigation shell, and that capture runs the loader once. Once a
+document request has captured the page's shell, prefetches replay it and
+serve the loader from its pin, as without the flag. Since such a loader can be deferred, it must not
+`await ctx.rendered()` (it throws on every request, as any deferrable loader
+does). See `/loader` → "`prefetch: false`".
 
 ### The layout-with-loaders playbook (the storefront case)
 

package/skills/prerender/SKILL.md

@@ -1020,7 +1020,10 @@ in dev. A removed page is the exception: its marker answers 404 in dev too.
   that only a refresh produced.
 - **Connected clients can lag.** A refresh has no response to reach open tabs:
   a client that prefetched the page keeps its copy for `prefetchCacheTTL`
-  (default 300s, in memory only). Lower it if the window matters.
+  (default 300s): in memory, and in the browser's HTTP cache too when the
+  route runs no loader (the prefetch then carries
+  `Cache-Control: private, max-age=<prefetchCacheTTL>`). Lower it if the
+  window matters.
 - **Entries are per deploy.** Keys carry the router's data version, so a deploy
   that changes server code starts from the build entries again; a client-only
   deploy keeps refreshed pages.

package/skills/route/SKILL.md

@@ -242,10 +242,10 @@ 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 `<Link>` prefetches; 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 viewport and render prefetches (a hover prefetch runs it); the click shows the fallback and fetches that part itself. |
 
 ```tsx
 path("/orders", OrdersPage, { name: "orders" }, () => [
@@ -255,8 +255,8 @@ 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 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 viewport
+or render 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

package/skills/router-setup/SKILL.md

@@ -250,7 +250,8 @@ Notes:
 - `discovery: { include?, exclude? }` filters which files the route-discovery
   scan reads, as root-relative globs (e.g. `include: ["src/routes/**"]`).
   `exclude` replaces the default excludes (`__tests__`, `__mocks__`, `dist`,
-  `coverage`, `*.test.*`, `*.spec.*`) rather than adding to them.
+  `coverage`, `*.test.*`, `*.rsc-test.*`, `*.spec.*`) rather than adding to
+  them.
 - `progressiveChunkSize` sets React's Fizz `progressiveChunkSize` for document
   renders and PPR shell capture. Unset, documents whose route has a
   `loader(Def, { ssr: false })` raise it automatically so that content stays

package/skills/server-actions/SKILL.md

@@ -531,11 +531,42 @@ See `/middleware` for the full cross-segment revalidation contract.
 ## Client Cache After an Action
 
 `revalidate()` decides what the server re-renders **in the action's response**.
-Separately, the browser invalidates its own caches once the action's response
-arrives: it marks the history cache stale (Back renders the cached entry, then
-revalidates), flushes the prefetch cache, rotates the router's state cookie,
-and tells other open tabs to do the same. This happens for every action that
-reached the server, including ones that threw. No setup is needed.
+Separately, the browser marks its own caches stale once the action's response
+arrives: the history cache (Back renders the cached entry, then revalidates)
+and every prefetch (a click on a link prefetched before the action shows that
+page at once, then revalidates it in the background), and it tells other open
+tabs that share a segment with the page to do the same and refresh. Nothing is
+flushed. The action's response bumps only the write part of the router's state
+cookie (`{build}:{invalidation}:{write}`), which every prefetch and navigation
+sends as `X-Rango-State`: responses vary on it, so a partial response a route
+caches with its own `Cache-Control: max-age` is not answered from the
+browser's HTTP cache after the write, in this tab, after a reload, or in
+another tab. The client's in-memory caches read only
+`{build}:{invalidation}`, so the write marks them stale and drops nothing.
+This happens for every action that reached the server, including ones that
+threw or redirected, and for a form posted before hydration. No setup is
+needed.
+
+```text
+/product/1: /cart prefetched (cart:2), click "Add to cart"
+  the action's response          (header: cart:3)
+  click the /cart link           /cart shows at once (cart:2)
+  one background revalidation    (cart:3)
+```
+
+The pre-write values show for one round trip, a layout loader that re-runs
+on navigation included. `useNavigation().state` stays `"idle"` during the
+revalidation, and nothing remounts. A new hover on the link replaces the
+stale prefetch with a fresh one. A stale prefetch answers one click only: a
+second click on the same link fetches the page, and Back/Forward onto a page
+the history cache no longer holds never uses it. Visible links do not
+prefetch again after an action. A tab that shares no segment with the page
+(or an app with `crossTabSync: false`) gets no message and does not refresh;
+its next prefetch or navigation sees the bumped state and marks its own
+history and prefetches stale, so a click on a link it prefetched before the
+write shows that page, then revalidates it. Call `invalidateClientCache()` in the action
+for the full flush: it drops every prefetch, rotates the state's invalidation
+part, and other tabs adopt it.
 
 ### When the user navigates while the action runs
 
@@ -596,9 +627,11 @@ export async function saveDraft(formData: FormData) {
 ```
 
 What it suppresses, for this action only: the stale-marking of the history
-cache, the prefetch flush, the state-cookie rotation, the cross-tab broadcast,
-and the background revalidation the client runs when the user navigated while
-the action was in flight (above). What it does not change:
+cache and of the prefetches, the state cookie's write bump, the cross-tab
+broadcast, and the background
+revalidation the client runs when the user navigated while the action was in
+flight (above). A click on a prefetch made before it shows that prefetch with
+no revalidation. What it does not change:
 
 - The action's own response still carries the revalidation render your
   `revalidate()` rules select, and the client applies it.

package/skills/testing/client-components.md

@@ -79,6 +79,21 @@ type RenderRouteResult = RenderResult & {
     // re-render the current location, as router.refresh() does:
     // a spec's when gets kind "revalidate" (`to` is `from`)
     refresh(): 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(
+      url: string,
+      options?: {
+        loaders?: ReadonlyArray<readonly [LoaderDefinition<any>, unknown]>;
+      },
+    ): void;
+    // land a server action's response: `loaders` are the post-write values,
+    // the page on screen re-renders with them, and (without keepClientCache)
+    // every history entry and prefetch is marked stale
+    action(options?: {
+      loaders?: ReadonlyArray<readonly [LoaderDefinition<any>, unknown]>;
+      keepClientCache?: boolean;
+    }): Promise<void>;
     pathname(): string;
     params(): Record<string, string>;
     store: NavigationStore; // advanced
@@ -420,19 +435,20 @@ it("dims the held price while the next product streams", async () => {
 });
 ```
 
-| Pending state                                                                                  | Under `renderRoute`                                                                                                                                                                                                  |
-| ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `useLoader().isLoading` on the reader a `transition` navigate() holds, pending seed            | Modeled: `true` on the OLD data until the promise settles, then `false` with the new data in the same commit.                                                                                                        |
-| `transition` navigate(), settled seed (a plain value)                                          | `false`; the data swaps in the commit.                                                                                                                                                                               |
-| navigate() without `transition`, pending seed                                                  | Urgent commit (production's cold-navigation lane): the read suspends to the nearest `<Suspense>` fallback (with none, React keeps the previous tree). No flag.                                                       |
-| `transition: { when }` returning false, or `navigate(url, { transition: false })`              | Same as without `transition`: urgent, with production's decision (`kind: "push"`; `refresh()` is `"revalidate"`). `transition: false` calls no predicate.                                                            |
-| Production's other hold lanes (same-structure search/filter nav, fully-prefetched, optimistic) | NOT modeled — without `transition` navigate() stays urgent. Assert those at e2e.                                                                                                                                     |
-| `useNavigation().state`, `useLinkStatus().pending`                                             | Modeled: navigate() starts the navigation as a click does. `loading` from the call, `idle` in the commit, held with it; `pending` true for the destination's link until that commit, held with it too.               |
-| `useAction().state`                                                                            | Stays `idle`: navigate() runs no action. e2e.                                                                                                                                                                        |
-| `useHandle()` on a held navigation, `navigate(url, { handles, loaders })`                      | Modeled: `handles` arrive on the response's handle stream, so readers keep the page being left's values while React holds the page and take the new ones with its commit.                                            |
-| `useNavigation().isStreaming` past the commit, `navigate(url, { streamUntil })`                | Modeled: the stream opens a task after the call (`pendingUrl` clears) and ends when the promise settles or a newer navigation aborts it; settle it inside `await act(async () => ...)`.                              |
-| A navigation started while React holds a page (a newer click, a `transition: false` commit)    | `await router.navigate(...)` shows its page, with or without `act()`. A `<Link>` click goes inside `await act(async () => { ... })`: `fireEvent`'s synchronous `act()` drops React's retry of the held page.         |
-| A back/forward restored from the history cache (`pop`)                                         | Modeled for the mounted entry and one a navigate() wrote: the page and its handle values come back, decided by `transition({ when })` as kind `"pop"`. A stale entry's revalidation and a restore that fetches: e2e. |
+| Pending state                                                                                        | Under `renderRoute`                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `useLoader().isLoading` on the reader a `transition` navigate() holds, pending seed                  | Modeled: `true` on the OLD data until the promise settles, then `false` with the new data in the same commit.                                                                                                                                                                                                                                                                                                                             |
+| `transition` navigate(), settled seed (a plain value)                                                | `false`; the data swaps in the commit.                                                                                                                                                                                                                                                                                                                                                                                                    |
+| navigate() without `transition`, pending seed                                                        | Urgent commit (production's cold-navigation lane): the read suspends to the nearest `<Suspense>` fallback (with none, React keeps the previous tree). No flag.                                                                                                                                                                                                                                                                            |
+| `transition: { when }` returning false, or `navigate(url, { transition: false })`                    | Same as without `transition`: urgent, with production's decision (`kind: "push"`; `refresh()` is `"revalidate"`). `transition: false` calls no predicate.                                                                                                                                                                                                                                                                                 |
+| Production's other hold lanes (same-structure search/filter nav, fully-prefetched, optimistic)       | NOT modeled — without `transition` navigate() stays urgent. Assert those at e2e.                                                                                                                                                                                                                                                                                                                                                          |
+| `useNavigation().state`, `useLinkStatus().pending`                                                   | Modeled: navigate() starts the navigation as a click does. `loading` from the call, `idle` in the commit, held with it; `pending` true for the destination's link until that commit, held with it too.                                                                                                                                                                                                                                    |
+| `useAction().state`                                                                                  | Stays `idle`: navigate() runs no action. e2e.                                                                                                                                                                                                                                                                                                                                                                                             |
+| `useHandle()` on a held navigation, `navigate(url, { handles, loaders })`                            | Modeled: `handles` arrive on the response's handle stream, so readers keep the page being left's values while React holds the page and take the new ones with its commit.                                                                                                                                                                                                                                                                 |
+| `useNavigation().isStreaming` past the commit, `navigate(url, { streamUntil })`                      | Modeled: the stream opens a task after the call (`pendingUrl` clears) and ends when the promise settles or a newer navigation aborts it; settle it inside `await act(async () => ...)`.                                                                                                                                                                                                                                                   |
+| A navigation started while React holds a page (a newer click, a `transition: false` commit)          | `await router.navigate(...)` shows its page, with or without `act()`. A `<Link>` click goes inside `await act(async () => { ... })`: `fireEvent`'s synchronous `act()` drops React's retry of the held page.                                                                                                                                                                                                                              |
+| A back/forward restored from the history cache (`pop`)                                               | Modeled for the mounted entry and one a navigate() wrote: the page and its handle values come back, decided by `transition({ when })` as kind `"pop"`. A stale entry's revalidation and a restore that fetches: e2e.                                                                                                                                                                                                                      |
+| A click on a prefetch made before an action, `prefetch(url)`, `action({ loaders })`, `navigate(url)` | Modeled: the click commits the prefetch's data at once; once it settled, the page revalidates in Back's lane with the post-write data (`useNavigation().state` stays `idle`, nothing remounts). `router.revalidations()` lists each revalidation request (its URL and held segment ids), decided by production's guards. `action({ keepClientCache: true })` keeps the prefetch fresh: no revalidation. The prefetch request itself: e2e. |
 
 - Per-navigation seeds merge over the render-time `loaders`/`loaderData` for THAT navigation only; a later `navigate()` without `loaders` falls back to the render-time data.
 - 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.)