@rangojs/router 0.31.0 → 0.33.0

package/skills/intercept/SKILL.md

@@ -278,9 +278,29 @@ gives `from.url.pathname === "/list/open"`, not `/item/1`. That differs from
 `transition({ when })`'s `from`, which is always the committed location on
 screen. `routeName` is set for named routes only. Pass an array of predicates
 for AND logic (all must return true). Omit `when` entirely and the intercept
-always activates. `when` is not re-evaluated during action revalidation, so
-an open modal stays open after an action. A selector that throws does not
-intercept: the full page renders and the error is logged with the route name.
+always activates. A selector that throws does not intercept: the full page
+renders and the error is logged with the route name.
+
+A server action from an open intercept re-renders that intercept, the one
+whose slot the page holds, and opens no other intercept that targets the
+route. Its `when` is not evaluated again, so the intercept stays open after
+the action even when its `when` would now reject. The page can hold the slots
+of more than one of the route's intercepts: two intercepts on one layout that
+fill the same slot share it, and a `parallel()` of an intercept's slot name
+holds that slot whether or not an intercept is open there. Whether they are
+declared for the route's name or its local name inside `include()`, the
+action sets aside the intercepts whose slot a `parallel()` fills on their
+layout and renders the one that is left, its `when` not evaluated. When
+several are left (the same-slot pair), the action evaluates their `when`
+again, with `from` the intercept's source page, and the first that passes
+renders; when none passes, the first of them renders. When a `parallel()`
+fills every held slot, that rule applies to all of them.
+
+`when` selects an intercept; it does not authorize one. An action request
+that names an intercept's slot renders that intercept without its `when`,
+and a navigation request can claim any source page. Guard data in the target
+route's middleware, which runs for every intercept render, or in the
+intercept's loaders.
 
 The server learns `from` from the `X-RSC-Router-Client-Path` header, which the
 rango client sends on every navigation. A partial request without it falls
@@ -291,12 +311,13 @@ intercepted: it gets the full page.
 ### `prefetch: false` on an intercept's loaders
 
 `loader(Def, { prefetch: false })` inside `intercept()` keeps that loader out
-of a prefetch of the target from the source page:
+of a viewport or render prefetch of the target from the source page (a hover
+prefetch runs it, and its click opens the modal complete with no fill):
 
 ```typescript
 intercept("@modal", "product", <ProductModal />, () => [
   loader(ProductLoader),
-  loader(ReviewsLoader, { prefetch: false }), // skipped in the prefetch
+  loader(ReviewsLoader, { prefetch: false }), // skipped in a viewport prefetch
   loading(<ModalSkeleton />),
 ]);
 ```
@@ -311,12 +332,13 @@ flagged loader with `ctx.use()` before its first `await` (or one with no
 `loading()`) gets it run in the prefetch instead: one run, no fill for it.
 `loading(…, { prefetch: false })` inside `intercept()` defers nothing.
 
-A prefetch of a route an intercept targets is stored per source page, whether
-or not the intercept applies from that page (`rsc-rendering.ts`
-`x-rsc-prefetch-scope: source`, set from `MatchResult.interceptTargeted`). A
-full page prefetched from a page where `when` is false never serves a click
-from a page where it is true. Routes no intercept targets keep one shared
-prefetch entry.
+A prefetch of a route an intercept targets, or one sent from such a route, is
+stored per source page, whether or not the intercept applies from that page
+(`rsc-rendering.ts` `x-rsc-prefetch-scope: source`, set from
+`MatchResult.interceptTargeted`). A full page prefetched from a page where
+`when` is false never serves a click from a page where it is true. Other
+prefetches keep one shared entry, unless a `revalidate()` that read the source
+page kept a segment (`MatchResult.sourceHeld`, same header).
 
 ```typescript
 // Intercept only when opened from the shop index

package/skills/layout/SKILL.md

@@ -267,6 +267,17 @@ layout(LocaleLayout, () => [
 ])
 ```
 
+A rule that reads `currentParams` or `fromRouteName` and keeps the layout
+shares a prefetch between the pages with equal values of what it read: the
+locale rule above keeps the layout on every `/en` to `/en` navigation, so one
+prefetch of a link serves every `/en` page, and a French page prefetches its
+own. Spreading `currentParams` reads every param, so read the ones the rule
+needs by name; a rule that reads `currentUrl` makes the prefetch page-only
+(`/links` → "Shared prefetches and `prefetchKey`").
+Write it for chrome that must follow the param; a block that belongs to one
+page goes in its route or in an orphan layout inside its `path()` (above),
+which re-renders with the route and needs no rule.
+
 `revalidate(false)` on a standalone layout only restates the default.
 The return shapes (hard boolean, soft `{ defaultShouldRevalidate }`, or defer)
 and the `revalidate(true | false)` shorthand are covered in `/loader` →

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

@@ -500,6 +500,25 @@ Rango warns with the shell key and backs capture off instead of rendering the
 same doomed generation on every request. Move a deterministic self-invalidation
 out of render code if you want the shell to persist.
 
+### Location state on a ppr route
+
+A shared shell never holds location state: the capture builds its own
+payload, without it. State set before the render (from middleware, or the
+one-shot cookie a document redirect left for this request) rides the live
+payload: a HIT serves the shell with the state in its tail's payload, a MISS
+carries it and still captures. Either response leaves `private, no-store`.
+State a handler sets skips the capture of that MISS, so that route renders in
+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
@@ -1146,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.
@@ -645,6 +678,14 @@ Redirects from actions render the **target** route tree's matched segments
 source page's — the target is what the user sees next. See `/hooks
 useLocationState` for reading flash state on the target page.
 
+The same holds for a form posted without JS (or before hydration): an action
+that redirects with `state` carries it to the target in a one-shot cookie,
+and one that sets it with `getRequestContext().setLocationState()` and does
+not redirect carries it in the re-rendered page. Either way the target reads
+it with `useLocationState` once it has hydrated. Prefer a `303` redirect, so a
+refresh does not post the form again. State that crosses a no-JS redirect
+travels as JSON (see `/hooks` `state.md`, "State on a document response").
+
 Build the target by name rather than a literal path:
 `throw redirect(getRequestContext().reverse("account.settings"))`. It fills
 mount params (`:accountId`, `:locale`) from the page URL the action was called