@rangojs/router 0.32.0 → 0.33.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.32.0",
+  "version": "0.33.1",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",
@@ -259,7 +259,7 @@
     "node": ">=24.0.0"
   },
   "scripts": {
-    "build": "pnpm run build:types && pnpm exec esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm exec esbuild src/testing/vitest.ts --bundle --format=esm --outfile=dist/testing/vitest.js --platform=node --packages=external && pnpm exec esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js && mkdir -p dist/bin/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/bin/plugins/cloudflare-protocol-loader-hook.mjs",
+    "build": "pnpm run build:types && pnpm exec esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm exec esbuild src/testing/vitest.ts --bundle --format=esm --outfile=dist/testing/vitest.js --platform=node --packages=external && rm -rf dist/bin && pnpm exec esbuild src/bin/rango.ts --bundle --format=esm --splitting --outdir=dist/bin --platform=node --packages=external && chmod +x dist/bin/rango.js && mkdir -p dist/bin/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/bin/plugins/cloudflare-protocol-loader-hook.mjs",
     "build:types": "rm -rf dist/types && pnpm exec tsc -p tsconfig.types.json",
     "typecheck": "tsc --noEmit && tsc -p tsconfig.strict-check.json --noEmit && tsc -p tsconfig.augment-check.json --noEmit",
     "test": "playwright test",

package/skills/app-structure/SKILL.md

@@ -112,6 +112,21 @@ here for the rules they share.
    keeps the visitor's URL. A loader, handler or server action
    cannot rewrite, and a loop answers 508. Redirect when the new URL should
    show (`/middleware`, "Rewrite").
+9. **Keep prefetches shared.** One prefetch of a page serves every page
+   that links to it. A `revalidate()` that reads the page being left and
+   keeps its segment shares those prefetches only between the pages with
+   equal values of what it read (`currentParams.locale`: the pages of one
+   locale); one that reads `currentUrl` makes them page-only. Read params
+   by name, keep page-specific blocks in their route, and write such a rule
+   for chrome that shows a param's data
+   ([Prefetches are shared](#prefetches-are-shared)).
+10. **A layout keeps its `<Outlet />` in one place.** Branch inside one shape
+    (`<>{promo ? <Banner /> : null}<Outlet /></>`), never between a bare
+    `return <Outlet />` and a wrapped one: the outlet moves, and every page
+    below remounts when the branch flips, its state reset and its mount
+    effects run again. When an early return is unavoidable and the other
+    branch is only a fragment, give the outlet the same `key` in both
+    (`/layout`, "Moving the Outlet remounts its children").
 
 ## A small app: one module
 
@@ -217,6 +232,72 @@ name a route alike. One unnamed level in the root module is fine.
 For where boundaries and `revalidate()` rules go inside that chrome so
 navigations stay smooth, see the `ux-architecture` skill.
 
+## Prefetches are shared
+
+In production every visible `<Link>` prefetches its page, and one prefetch
+of a page serves every page that links to it: a product prefetched on the
+home page is not fetched again on the search page or on page 2 of a list
+(`/links` → "Shared prefetches and `prefetchKey`"). A structure keeps that
+sharing as long as no segment's answer depends on the page being left.
+
+The default rules keep it: a standalone layout is held from every page that
+shows it, and a route re-renders when its params or search change. A
+`revalidate()` that reads the page being left and keeps its segment narrows
+it to what the rule read. A rule that reads `currentParams` or
+`fromRouteName` shares the answer between the pages with equal values of
+those reads (the params a rule reads by name, every param when it spreads
+`currentParams`, the route name for `fromRouteName`; the page's set of params
+always counts). A rule that reads `currentUrl` makes it page-only: the server
+stores the answer for the exact page that sent it, query string and hash
+included, and each page prefetches those links again. The answer stays
+correct; what is lost is the sharing.
+
+| What you are placing                                                                                                                               | Put it in                                                                    | Prefetches                                                                                                                                          |
+| -------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| A block that belongs to one page (a category's hero, a product's breadcrumb)                                                                       | that page's route: its handler, or a layout inside its `path()` (below)      | Shared. It re-renders with its route on a param or search change. In a layout other pages share it would need a rule that reads the page being left |
+| Links that follow a mount param (`:locale`, `:accountId`, `:projectId`)                                                                            | a client component with `useReverse(routes)` (rule 7)                        | Shared. The links follow `useParams()`, and the layout stays held with no rule                                                                      |
+| Chrome that shows a param's data (the locale's messages, a project's name)                                                                         | the layout, with a `revalidate()` comparing `currentParams` and `nextParams` | Shared between the pages with the same value of that param where the rule keeps the layout (the pages of one locale or one project)                 |
+| A page whose answer depends on the page that sent it through something the server cannot see (`context` in a `revalidate()`, the `Referer` header) | `prefetchKey=":source"` on the links to it                                   | Page-only, for those links                                                                                                                          |
+
+The third row is the one to weigh: write that rule for chrome that must
+follow the param, read the param by name, and keep everything else that
+varies by page out of the layout.
+
+Chrome that one kind of page has (a category's hero and breadcrumbs, a
+product's gallery frame) can be a layout of its own route instead of a
+template shared with other pages. A layout declared inside a `path()` belongs
+to that route (`/layout`, "Orphan Layout"):
+
+```tsx
+urls(({ path, layout }) => [
+  path("/c/:category", CategoryPage, { name: "category" }, () => [
+    layout(CategoryLayout), // the hero: re-renders with the category
+  ]),
+  path("/p/:slug", ProductPage, { name: "product" }, () => [
+    layout(ProductLayout),
+  ]),
+]);
+```
+
+- **No rule, shared prefetches.** It re-renders on its route's param or
+  search change by default, so nothing reads the page being left.
+- **It cannot leak.** The category's layout is not in the product page's
+  tree, so no navigation can keep it above a product page or the cart.
+- **What it costs.** Its handler runs on every param or search change of its
+  route, `?page=2` included; cache an expensive read with `"use cache"`. Without
+  a `transition()` in its chain (the route, this layout or a layout above) it
+  remounts on a param change, like the route. A navigation to another route
+  mounts that route's layout: nothing is held between them.
+- **In a `clientUrls()` group** a `path()` takes no `layout()`, only
+  `loader()`, `loading()` and `transition()` (`/client-urls`). A group
+  layout has no `revalidate()` of its own: it is a client component, so the
+  params it reads with `useParams()` are always the current page's. Its
+  loaders are held on navigation like a server layout's, though, so hero
+  data from a layout loader needs a rule that reads the page being left.
+  Put the block in the route component and its data in a loader on the
+  `path()`: that loader re-runs when the params or search change, with no
+  rule.
+
 ## Growing an app
 
 1. **Start with one `urls()` module** ([A small app](#a-small-app-one-module)).

package/skills/app-structure/e-commerce.md

@@ -424,12 +424,13 @@ without JavaScript too (`/server-actions` → "Progressive Enhancement").
 
 ## Why
 
-| Choice                                        | Why                                                                        |
-| --------------------------------------------- | -------------------------------------------------------------------------- |
-| `ppr` on category and product pages           | The shared part is HTML from the shell; only the holes render per request  |
-| `"use cache"` + `cacheTag()` for product data | One read for every visitor, and the tag reaches the shells that baked it   |
-| Live loaders for price, stock, cart           | Fresh on every request, shell HITs included                                |
-| `CartLoader` on the store layout              | One badge on every page; held on navigations; narrowed to cart actions     |
-| `TRACKING_SEARCH_PARAMS` excluded             | Campaign links do not multiply shells                                      |
-| `prefetch: false` on reviews                  | Every product card prefetches its page; few shoppers scroll to the reviews |
-| Checkout without `ppr` or `cache()`           | Nothing on it is shared                                                    |
+| Choice                                                  | Why                                                                                                                                                                                                                                                                                                                               |
+| ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ppr` on category and product pages                     | The shared part is HTML from the shell; only the holes render per request                                                                                                                                                                                                                                                         |
+| `"use cache"` + `cacheTag()` for product data           | One read for every visitor, and the tag reaches the shells that baked it                                                                                                                                                                                                                                                          |
+| Live loaders for price, stock, cart                     | Fresh on every request, shell HITs included                                                                                                                                                                                                                                                                                       |
+| `CartLoader` on the store layout                        | One badge on every page; held on navigations; narrowed to cart actions                                                                                                                                                                                                                                                            |
+| `TRACKING_SEARCH_PARAMS` excluded                       | Campaign links do not multiply shells                                                                                                                                                                                                                                                                                             |
+| `prefetch: false` on reviews                            | Every product card prefetches its page; few shoppers scroll to the reviews                                                                                                                                                                                                                                                        |
+| Category content in `CategoryPage`, not a shared layout | A category hero belongs there too, or in a layout inside the category `path()`. In a layout shared with product pages it needs a `revalidate()` that reads the page being left, and every prefetch under that layout is shared only between the pages of one category ([Prefetches are shared](./SKILL.md#prefetches-are-shared)) |
+| Checkout without `ppr` or `cache()`                     | Nothing on it is shared                                                                                                                                                                                                                                                                                                           |

package/skills/app-structure/large-app.md

@@ -710,6 +710,10 @@ Rules of thumb:
   keeps the page being left on screen until the fill answers.
 - A same-route click (`/app/projects/1` to `/app/projects/2`) prefetches a
   flagged loader as usual: only data the page does not have yet is deferred.
+- One prefetch of a page serves every page that links to it. A `revalidate()`
+  that reads the page being left and keeps its segment shares it only between
+  the pages with equal values of what it read
+  ([Prefetches are shared](./SKILL.md#prefetches-are-shared)).
 
 Details: `/loader` → "`prefetch: false`", `/client-urls` → "`prefetch: false`".
 
@@ -802,11 +806,14 @@ reverse(".issues", { projectId: "api" }); // /acme/api/issues
 
 - A link into another module (the project nav's "Account settings") is built
   on the server and passed as a prop or loader data. `useReverse(accountRoutes)`
-  in a project component gives a wrong URL with no error (dc-t57).
+  in a project component gives a wrong URL with no error.
 - A server layout stays held when `:projectId` changes (partial rendering by
   design), so links it rendered keep the old project. Render the project
   switcher and nav in a client component with `useReverse(routes)`, or give
-  the layout a `revalidate()` comparing `projectId`.
+  the layout a `revalidate()` comparing `projectId`. Prefer the client
+  component: the rule reads the page being left, so a prefetch it keeps the
+  layout for is shared only between the pages of one project
+  ([Prefetches are shared](./SKILL.md#prefetches-are-shared)).
 - The account layout's `ctx.reverse(".settings")` resolves in the account
   module on every page below it, the project's pages included: it links to
   `/acme/settings`, not the project's settings route.
@@ -854,6 +861,12 @@ export function ProjectNav() {
 }
 ```
 
+`ProjectNavLoader`'s rule has the same cost: it reads `currentParams`, so a
+prefetch from `/acme/web/issues` to `/acme/web/settings` is shared only by
+the pages of the `web` project with the same set of params. Use it for links that need the server; links that
+stay inside the project module can come from `useReverse(routes)` in
+`ProjectNav`, with no rule.
+
 ## Why each piece sits where it does
 
 | Piece                                      | Where                                                          | Why                                                                                                                                                   |
@@ -880,6 +893,9 @@ export function ProjectNav() {
   user's name): the capture is refused and the page never serves a shell.
 - **`prefetch: false` on every loader**: each click then waits for a fill.
   Flag the expensive, rarely-clicked ones.
+- **A layout that moves its `<Outlet />` between branches** (a bare
+  `return <Outlet />` on one, a wrapped one on another): every page below it
+  remounts when the branch flips. Keep one shape (`/layout`).
 - **A bare `isAction(refs)` predicate**: it is a hard `false` on navigation
   too, so the loader stops following param changes. Use
   `isAction() ? isAction(refs) : undefined` (`/loader`).

package/skills/caching/SKILL.md

@@ -1121,7 +1121,7 @@ results first, outermost first:
 | deeper nesting                                | Composes the same way; the innermost boundary adds its default key without a `key` of its own, its request kind with one                                     |
 | under a `cache({ store })` on another store   | Also that store's `keyGenerator` result, one part per store: empty for a store that returns the default key while another's differs, none when all return it |
 | `cache(false)`                                | No caching, as before; a `cache()` re-enabled below it stays in the partition                                                                                |
-| no `key` anywhere                             | The default key, or the store's `keyGenerator` result, as before                                                                                             |
+| no `key` anywhere                             | The default key, or the store's `keyGenerator` result, then the request kind when that result does not start with it                                         |
 
 - No `key()` result, whatever it returns, equals a default key or a
   composed key, and no two composed keys are equal: a namespaced result
@@ -1150,10 +1150,15 @@ results first, outermost first:
   empty result there fails key resolution, so the request renders uncached,
   and the router warns once naming the store. On the same store the inner
   boundary's own default key already carries it (or its own `key()`
-  overrides it). Keep the default key in the result
-  (`` `${locale}:${defaultKey}` ``): its prefix is the request kind, and a
-  result without it gives a document request, a navigation and each
-  intercept navigation one record.
+  overrides it). A `keyGenerator` result keeps the request kind: the
+  default key starts with it (`doc:`, `partial:`, `intercept:<intercept>:`),
+  and a result that does not gets it as a last part (`items` is stored as
+  `items|doc` for a document request), so a document request, a navigation
+  and each intercept navigation keep their own record whatever it returns.
+  Build on the default key (`` `${defaultKey}|${locale}` ``) and the result
+  is the key, byte for byte. A prefix before it
+  (`` `${locale}:${defaultKey}` ``) keeps the kind too, but no longer starts
+  with it, so the kind is appended (`en%3Adoc%3A…|doc`).
 - A response route's entry (`path.json()` and the other response routes) is
   keyed the same way, behind a `response:` prefix. A `ppr` route's shell is
   partitioned by the chain's `key()` results, namespaced the same way, since

package/skills/client-urls/SKILL.md

@@ -278,7 +278,11 @@ the arguments and type of a `urls()` loader's (`ShouldRevalidateFn` from
 `actionUrl`, `actionResult`, `formData`, `method`,
 `routeName`/`fromRouteName`/`toRouteName`, and `stale`. Nothing runs in the
 browser before the request goes out; there is no client-computed decision and
-no hybrid.
+no hybrid. A predicate that reads `currentParams` or `fromRouteName` and
+keeps its segment shares a prefetch of that answer only between the pages
+with equal values of what it read, and one that reads `currentUrl` makes it
+page-only, as in `urls()` (`/links` → "Shared prefetches and
+`prefetchKey`").
 
 You still write the predicate in the `"use client"` module, or in a
 component's `.use`. The rango Vite plugin hoists each `revalidate()` argument
@@ -400,7 +404,7 @@ Everything after that is decided on the server, while it handles that request:
   the action's `actionResult` and `formData` (above). A loader that holds keeps
   the data the page shows.
 - **The browser's caches.** When the response arrives the browser marks its
-  history cache stale and drops its prefetches, unless the action called
+  history cache and its prefetches stale, unless the action called
   `keepClientCache()` (`/server-actions` → "Client Cache After an Action").
 - **A loader that fails on its rerun** reaches your `onError` on the server,
   and in the browser it throws at its read, below.
@@ -619,21 +623,23 @@ shell, such as a `useActionState` form (React suspends it once to encode its
 action), is in the first flush too: the router gives React up to three more
 turns before it, and none when the document is already complete.
 
-## `prefetch: false` — keep a loader out of prefetches
+## `prefetch: false` — keep a loader out of speculative prefetches
 
 A `<Link>` prefetch of a group route runs its loaders. Flag the expensive one
-and the prefetch skips it:
+and a viewport or render prefetch skips it. A hover prefetch, and
+`useRouter().prefetch()`, is intent to click: it runs the loader, and the
+click sends no fill (`/loader` → "`prefetch: false`").
 
 ```tsx
 path("/product/:slug", ProductPage, { name: "product" }, () => [
   loader(PriceLoader),
-  loader(ReviewsLoader, { prefetch: false }), // kept out of prefetches
+  loader(ReviewsLoader, { prefetch: false }), // kept out of viewport prefetches
   loading(<ProductSkeleton />),
 ]),
 ```
 
-A click inside the group still shows the destination at once. With the
-prefetch received, the URL and the other loaders' data move with the click
+A click inside the group still shows the destination at once. With a
+viewport or render prefetch received, the URL and the other loaders' data move with the click
 too, `useOutlet().pending` ends with that commit, and one follow-up request
 (the fill) runs only the flagged loaders. Read the flagged loader inside its
 own `<Suspense>` to show the page and that fallback at once; with no boundary
@@ -654,10 +660,11 @@ rest of the destination; otherwise it is held. A same-route click
 - `loading()` in `clientUrls()` takes no options, and a flagged `loading()`
   on a server layout above the group defers nothing for the group's routes.
 - On an `intercept()` loader the flag works as in `urls()`: an in-group
-  prefetch of the intercept's target defers it, and the click opens the modal
-  at once with one fill for it.
-- With `ssr: false` on a `ppr` group route the flag is ignored (the bake
-  lane), as on a server route.
+  viewport or render prefetch of the intercept's target defers it, and the
+  click opens the modal at once with one fill for it; a hover's runs it.
+- With `ssr: false` on a `ppr` group route the flag works as on a server
+  route: deferred unless the prefetch serves the loader from a pin of a
+  document-captured shell (`/ppr` → "`prefetch: false` on a `ppr` route").
 - Test it with `serveShellRequest` in the Flight project: mount the module
   itself, and `rangoUseClientTransform()` installs the group's projection
   (`/testing` → `serve-shell-request.md`, "`clientUrls()` routes"). It also
@@ -738,6 +745,17 @@ a hard load of the target URL renders the full route.
   throwers in the client `ErrorBoundary`; `useFetchLoader` works unchanged
   (route-independent lane; `revalidate()` deliberately not consulted).
   Pinned in the router repo's client-urls hook-probe e2e.
+- **An action called on the optimistic frame runs against the committed
+  page.** The destination mounts at the click, before the navigation
+  commits, so an action its mount effect calls is sent from the page the URL
+  bar still shows: the server runs it with that page's request context
+  (`ctx.url`, `ctx.params`, its middleware) and re-renders that page, not
+  the destination. Nothing of that render reaches the destination, and a
+  write still refreshes the destination once it commits (unless the action
+  called `keepClientCache()`). Pass what the action needs as arguments
+  instead of reading the request's URL or params. A link prefetched before
+  the click (the production default, `viewport`) usually commits before the
+  effect runs.
 - **Location state follows the same split as the route hooks.** Inside the
   optimistic branch (the destination and the group's client layouts)
   `useLocationState` reads the state the navigation carries (`<Link state>`,

package/skills/comparison/references/framework-comparison.md

@@ -583,9 +583,11 @@ the bounded cache uses a configurable TTL. `Save-Data`,
 `prefers-reduced-data`, or `prefetchCacheTTL: false` disable speculation.
 
 Correctness is part of the prefetch contract. Keys include Rango state, destination
-URL, and the mounted segment set used to compute the diff. Server actions rotate
-state and abort stale speculative work; a generation check prevents a late result
-from repopulating an invalidated cache. Routes an intercept targets are automatically
+URL, and the mounted segment set used to compute the diff. Server actions mark
+every prefetch stale without aborting it: a click on a stale one shows it at once,
+then revalidates the page in the background. `invalidateClientCache()` rotates
+state and aborts speculative work; a generation check prevents a late result from
+repopulating a flushed cache. Routes an intercept targets are automatically
 source-scoped, matched or not,
 and malformed, cross-origin, foreign-router, redirect, and reload responses are
 dropped rather than warmed. `useLinkStatus()` exposes `{ pending }` for the owning
@@ -595,7 +597,7 @@ link.
 session-cookie value shaped as `{documentVersion}:{invalidationTimestamp}`. Navigation
 and prefetch requests send it as `X-Rango-State`, and RSC responses vary on that
 header, so the browser HTTP cache and Rango's decoded prefetch map share one cache
-identity. A deployment that changes the router's code or client assets changes the version; a mutation rotates the timestamp. Old
+identity. A deployment that changes the router's code or client assets changes the version; `invalidateClientCache()` rotates the timestamp. Old
 responses become unreachable under the retired identity instead of requiring every
 cache layer to delete the same entries successfully.
 
@@ -609,10 +611,13 @@ cookie. Across those two seats, it covers mutations initiated outside the action
 bridge: REST calls, client-observed WebSocket events, authentication changes, or
 middleware/loader decisions.
 
-Server Actions invalidate automatically after a response reaches the browser. If
-an action knows it changed nothing that any route renders, `keepClientCache()` is
-the explicit per-response escape hatch: it suppresses that automatic state
-rotation, prefetch flush, broadcast, and revalidation fetch. Together,
+Server Actions mark the history and prefetch caches stale automatically after a
+response reaches the browser, without rotating the state: the response bumps
+only its write part, so the browser HTTP cache misses on responses from before
+the write while the in-memory caches go stale. If an action knows it
+changed nothing that any route renders, `keepClientCache()` is the explicit
+per-response escape hatch: it suppresses that stale-marking, the broadcast, and
+the revalidation fetch. Together,
 `invalidateClientCache()` and `keepClientCache()` give application code control in
 both directions — force a miss for mutations the router cannot observe, or preserve
 the current state for a known no-op.

package/skills/document-cache/SKILL.md

@@ -217,6 +217,14 @@ suffixes are still appended.
   request that holds no segments (`router.refresh()`, a cross-tab refresh).
   Each renders at the origin and is not stored, because its data may predate
   a write and the cache cannot tell.
+- A client navigation whose answer depends on the page it came from: a
+  `revalidate()` rule that read `currentParams`, `currentUrl` or
+  `fromRouteName` kept a segment, or an intercept targets the route. The key
+  names the segments the client holds, not its page, so `/c/tv` would get the
+  answer `/c/audio` got for `/c/audio?sort=x` and keep its own hero. It is sent
+  `private, no-cache` over the route's `Cache-Control` and is not stored. One
+  whose rule re-rendered the segment is right from every page and is stored as
+  usual.
 - Non-GET requests
 - Responses without an `s-maxage` `Cache-Control` directive
 - Responses whose `Cache-Control` also contains `private`, `no-store`, or an

package/skills/hooks/navigation.md

@@ -160,14 +160,14 @@ function NavigationControls() {
 }
 ```
 
-| Method                   | Behaviour                                                                                                       |
-| ------------------------ | --------------------------------------------------------------------------------------------------------------- |
-| `push(url, options?)`    | Navigate and add a history entry. Returns a promise.                                                            |
-| `replace(url, options?)` | Navigate and replace the current history entry. Returns a promise.                                              |
-| `refresh()`              | Re-fetch the current route's server data, keeping client state. Returns a promise.                              |
-| `prefetch(url, opts?)`   | Prefetch a target. `{ key: ":source" }` scopes the entry to the source page (parity with `<Link prefetchKey>`). |
-| `back()`                 | `history.back()`; on the first entry of the session it replaces to the app root instead of leaving the app.     |
-| `forward()`              | `history.forward()`.                                                                                            |
+| Method                   | Behaviour                                                                                                                     |
+| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
+| `push(url, options?)`    | Navigate and add a history entry. Returns a promise.                                                                          |
+| `replace(url, options?)` | Navigate and replace the current history entry. Returns a promise.                                                            |
+| `refresh()`              | Re-fetch the current route's server data, keeping client state. Returns a promise.                                            |
+| `prefetch(url, opts?)`   | Prefetch a target. `{ key: ":source" }` scopes the entry to the source page (parity with `<Link prefetchKey>`, see `/links`). |
+| `back()`                 | `history.back()`; on the first entry of the session it replaces to the app root instead of leaving the app.                   |
+| `forward()`              | `history.forward()`.                                                                                                          |
 
 `push` / `replace` options: `scroll` (`false` keeps the current scroll
 position), `revalidate` (default `true`, see below), `transition` (`false`

package/skills/hooks/outlets.md

@@ -28,6 +28,10 @@ function DashboardLayout() {
 `ParallelOutlet` requires the name and reads clearer at the call site. See
 `/layout` and `/parallel` for the server side.
 
+An outlet that moves between a layout's branches (bare in one, wrapped in
+another) remounts its children; see `/layout`, "Moving the Outlet remounts its
+children".
+
 ### useOutlet()
 
 Access outlet content and its client-route presentation state programmatically:

package/skills/hooks/state.md

@@ -365,7 +365,15 @@ path("/checkout/callback", async (ctx) => {
 - **`ppr` and cached routes.** A shell HIT and a `cache()` hit run no
   handler, so a handler there cannot set state on that request. Set it from
   middleware, which runs on every request; the HIT still serves, with the
-  state in its live payload.
+  state in its live payload. A HIT sends exactly the state set before its
+  render: its headers leave before its tail runs, so they decide then
+  whether the response is private.
+- **Not from a loader.** A loader has no `setLocationState`, and calling
+  `getRequestContext().setLocationState()` from one is not supported: the
+  payload takes the request's state before loaders settle, so a loader's
+  write may arrive (a `ppr` MISS then renders in full) or be dropped, and a
+  shell HIT never sends it. Set state from middleware, the handler or an
+  action.
 - **The cookie.** It is named after the router's state cookie
   (`<stateCookieName>-ls`, `__Host-` prefixed on https), `HttpOnly`,
   `SameSite=Lax`, `Path=/`, and lives 60 seconds. Only the next GET document
@@ -378,7 +386,11 @@ path("/checkout/callback", async (ctx) => {
   is one such cookie per router: two document redirects within a moment (two
   tabs) keep only the later one's state. Without https there is no `__Host-`
   prefix, so a sibling subdomain could set the cookie: treat state that
-  arrives this way as a message to show, not as a fact to act on.
+  arrives this way as a message to show, not as a fact to act on. A `ppr`
+  shell HIT that read the cookie and then cannot finish its tail reloads the
+  page into a full render; its headers already cleared the cookie, so its
+  reload script sets it again first (from script, so without `HttpOnly`,
+  for the moment the reload takes), and the reload shows the state.
 - **Known limit: a redirect from one router to another.** The cookie is
   named after the redirecting router's state cookie, which holds its router
   id (`<stateCookiePrefix>_<routerId>`), and a router reads only its own. On
@@ -607,9 +619,12 @@ from module-level callbacks too. Imported from the root entry `@rangojs/router`,
 it is selected by export conditions:
 
 - **Client** (client component or module): marks the history cache stale,
-  flushes the prefetch cache, rotates the router state, and notifies other tabs
-  — the same thing a completed server action does. During SSR of a client
-  component it is a no-op (dev warning).
+  flushes the prefetch cache, rotates the router state, and notifies other
+  tabs, which adopt the new state and flush theirs. That is more than a
+  completed server action does: an action marks history and prefetches stale
+  and rotates nothing (its response bumps only the state's write part, so the
+  browser HTTP cache misses on responses from before the write). During SSR
+  of a client component it is a no-op (dev warning).
 - **Server** (handler, server component, middleware, loader, or action): writes
   a rotated state `Set-Cookie` for the responding client, which marks its
   caches stale when it next reads them. Idempotent within a request; throws
@@ -618,9 +633,10 @@ it is selected by export conditions:
   from handler code writes the cookie only on the renders that run it (a
   MISS); call it from middleware, which runs on every request, HITs included.
 
-Server actions already invalidate automatically; to suppress that for a no-op
-action, call `keepClientCache()` inside it (see `/server-actions` → "Client
-Cache After an Action").
+Server actions already mark the caches stale automatically; to suppress that
+for a no-op action, call `keepClientCache()` inside it, and for the full flush
+and rotation, call `invalidateClientCache()` inside it (see `/server-actions` →
+"Client Cache After an Action").
 
 ```tsx
 "use client";

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,13 +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, unless a `revalidate()` that read the source page kept a
-segment (`MatchResult.sourceHeld`, same header).
+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

@@ -12,6 +12,12 @@ layout stays mounted while you navigate between the routes it wraps. This skill
 covers layout forms, outlets, orphan layouts (a layout inside a `path()`), and
 layout revalidation.
 
+**Rule: a layout keeps its `<Outlet />` in one place on every branch.** Branch
+around the outlet, never around it and the outlet together: an early
+`return <Outlet />` beside a wrapped one remounts every child segment each time
+the branch flips (state resets, mount effects and the actions they call run
+again). See [Moving the Outlet remounts its children](#moving-the-outlet-remounts-its-children).
+
 Related skills: `/parallel` (named slots rendered by a layout), `/intercept`
 (modal slots), `/route` (the routes a layout wraps), `/router-setup` (the
 `document` shell that renders `<html>`).
@@ -131,6 +137,49 @@ function ShopLayout() {
 
 A layout's `transition()` config wraps the content that flows through `<Outlet />` — not the layout chrome itself, and not sibling `<ParallelOutlet />` slots. Stacking transitions across nested layouts collapses around the deepest default outlet content. See [skills/view-transitions](../view-transitions/SKILL.md) for the full wrap rules and intercept-modal interaction.
 
+### Moving the Outlet remounts its children
+
+React keeps a subtree mounted only while each element on its path keeps the
+same type at the same position. A layout that returns a bare `<Outlet />` on
+one branch and wraps it on another (a fragment, a `<div>`) moves the outlet,
+so when the branch flips, every child segment unmounts and mounts again:
+client state resets, mount effects run again (an action they call is sent
+again), and the content flashes. Prefer one shape with the branch inside it:
+
+```tsx
+// Remounts the children whenever `promo` flips
+function CategoryLayout({ promo }: { promo: boolean }) {
+  if (!promo) return <Outlet />;
+  return (
+    <>
+      <PromoBanner />
+      <Outlet />
+    </>
+  );
+}
+
+// Keeps them mounted: the outlet keeps its position
+function CategoryLayout({ promo }: { promo: boolean }) {
+  return (
+    <>
+      {promo ? <PromoBanner /> : null}
+      <Outlet />
+    </>
+  );
+}
+```
+
+A stable `key` on the outlet (`<Outlet key="outlet" />` in both branches)
+also keeps the children mounted when the only difference is a top-level
+fragment: React reads a component's unkeyed top-level fragment as a list of
+siblings and matches the keyed outlet across it. It does not help when one
+branch wraps the outlet in an element (a `<div>`, a provider): the outlet then
+sits one level deeper, and keys match only among siblings.
+
+All of this applies to `<ParallelOutlet />` too. To reset the children on
+purpose, change a `key` on a stable wrapper rather than relying on a shape
+change.
+
 ## Named Outlets
 
 For parallel routes, use named outlets (`<Outlet name="@sidebar" />` is
@@ -267,6 +316,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` →