@rangojs/router 0.19.1 → 0.21.0

package/skills/hooks/urls.md

@@ -47,7 +47,7 @@ function CurrentPage() {
 }
 ```
 
-Returns the pathname string without search params or hash. Updates on navigation commit.
+Returns the pathname string without search params or hash. It is the pathname of the page on screen: it changes when a navigation's destination commits, Back/Forward included (see [When the URL hooks change](#when-the-url-hooks-change)).
 
 ### useSearchParams()
 
@@ -109,6 +109,45 @@ Options: `replace` (default false — push), `scroll` (default true),
 `revalidate` (default true; `false` skips the server fetch — legal because
 the setter never changes the pathname).
 
+### When the URL hooks change
+
+`usePathname()`, `useSearchParams()` and `useParams()` describe the page on
+screen. They change in the commit that shows a navigation's destination, not
+when the navigation starts. That holds for Back/Forward as it does for a link
+click or `router.push()`.
+
+| Navigation                                        | The hooks change                                                           |
+| ------------------------------------------------- | -------------------------------------------------------------------------- |
+| `<Link>`, `router.push()` / `router.replace()`    | when the destination commits                                               |
+| Back/Forward, entry in the client's history cache | with the restored page, in one commit                                      |
+| Back/Forward, entry fetched again                 | when the fetched page commits; until then the page being left is on screen |
+| a Back/Forward whose fetch fails                  | with the error boundary: they report the entry the browser is on           |
+| `router.push(url, { revalidate: false })`         | at once: nothing is fetched and the page stays                             |
+| inside an optimistic `clientUrls()` destination   | at the click, for that branch only (see `/client-urls`)                    |
+
+**The hooks can disagree with the address bar.** On Back/Forward the browser
+changes the URL and `history.state` before it tells the router. When the
+entry has to be fetched (it left the client's history cache, or the cache was
+cleared), the page being left stays on screen for the wait and the hooks keep
+reporting its URL, while `window.location` is already the destination's. That
+is deliberate: an active-link highlight, a breadcrumb or a filter panel
+derived from the hooks stays in step with the content next to it. For
+anything you render, read the hooks, not `window.location`.
+
+For pending UI during that wait read `useNavigation()` (see
+[`./navigation.md`](./navigation.md)): `state === "loading"` and `pendingUrl`
+(the entry being fetched) while the request is out, `isStreaming` for the
+whole wait. A Back/Forward served from the history cache has no wait.
+
+`setSearchParams((prev) => ...)` builds on the same location: called during a
+pending Back/Forward, `prev` is the search of the page on screen.
+
+One gap (issue #1046): a component that first mounts in the page being left
+after the navigation's response has arrived, while React still holds the
+destination behind a loader or a `transition()`, reads the destination's URL
+and params from these hooks. Components that were already mounted are not
+affected. It applies to a push and to Back/Forward alike.
+
 ### useHref()
 
 Mount-aware href for client components inside `include()` scopes:

package/skills/host-router/SKILL.md

@@ -370,3 +370,16 @@ apps; each app owns its own document.
 
 **Within-app** navigation is unchanged — a normal soft SPA update (the document
 stays mounted). Only crossing an app boundary triggers the reload.
+
+## Deploys and the cache
+
+Each `createRouter()` app has its own cache version, computed by `vite build` from that app's built code, so deploying a change to one app does not clear the cache of the others. Lazily mounting sub-apps (`.lazy(() => import("./apps/admin"))`) is what keeps them independent: an app's version covers everything the modules that statically import its router can run, and a lazy mount is where that stops. Routers that one module imports statically share that module's code, so a change to either moves both versions.
+
+| Deploy                                | Cached data         | Stored HTML           | Open tabs               |
+| ------------------------------------- | ------------------- | --------------------- | ----------------------- |
+| Rebuild, no code change               | kept                | kept                  | untouched               |
+| Server code of app A changes          | cleared for A only  | cleared for A only    | A's tabs reload         |
+| Client code of any app changes        | kept for every app  | cleared for every app | every app's tabs reload |
+| Server code shared by A and B changes | cleared for A and B | cleared for A and B   | A's and B's tabs reload |
+
+The host entry (the file that creates the host router and its middleware) is not part of a lazily mounted sub-app's version. If host middleware changes what an app renders from inside a cache boundary, change that app's `version` or invalidate its tags. See `/cache-guide`.

package/skills/intercept/SKILL.md

@@ -238,6 +238,12 @@ 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.
 
+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
+back to `Referer`, and only when that `Referer` is on the request's own origin
+(scheme, host and port). A request with no usable navigation context is not
+intercepted: it gets the full page.
+
 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

package/skills/loader/SKILL.md

@@ -612,6 +612,10 @@ included. A handler's `ctx.use(Loader)` read never caches by itself (see
 body, gets the binding's value: one value per loader per request, a HIT
 included. A reader that runs before the binding starts (a layout's loader
 reading a route's cached loader) gets the value of its own run, as before.
+This is by design: that loader runs live while the binding serves its entry,
+so its data and its handle push can come from different runs on that request.
+To keep them together, declare the cached loader first or read it from the
+handler.
 
 The loader's data is cached independently from the route's segment cache,
 using the same `SegmentCacheStore` (app-level or per-loader override).
@@ -648,6 +652,14 @@ rejects) skips the whole entry, as above. Entries written
 before handles were recorded replay none until they are rewritten (expiry or
 SWR revalidation).
 
+On a `ppr` route the shell keeps a copy of an `ssr: false` loader's settled
+pushes too. The two never disagree on the page: where a replay of the shell
+serves the loader's data from the shell, the shell's copy is the one shown
+and the entry only adds the deferred push the shell could not keep; where it
+does not (the loader runs or reads its entry), the entry's pushes take the
+shell copy's place, none if the entry recorded none. See `/ppr` → "On a shell
+HIT".
+
 ### Cache Key
 
 The default cache key is `loader:{loaderId}:{host}{pathname}:{sortedParams}`
@@ -993,7 +1005,13 @@ on document loads (`metadata.handlesLate`) or progressively on navigations.
 A push before your slow fetch usually beats the barrier; a push derived from
 the fetched data usually does not. When it MUST be in the document, use
 `ssr: false` below. A loader with its own `cache()` keeps its pushes on a hit —
-they are replayed from the entry (see "Opting a Loader into Caching").
+they are replayed from the entry (see "Opting a Loader into Caching"). On a
+`ppr` route the race does not apply to a document served from its shell:
+there every push a loader makes on that request applies post-hydration (see
+`/ppr`, "Handles on a shell HIT"). A `useHandle` reader inside this loader's
+`loading()` or `<Suspense>` hydrates with the data its HTML was rendered
+from and shows a later push right after, so a push after an `await` causes
+no hydration mismatch there.
 
 Under `cache()`, loader pushes are not stored with the cached segments: the
 loader re-runs on every hit and its live push is the only copy. (`ppr` keeps

package/skills/middleware/SKILL.md

@@ -426,6 +426,8 @@ export const requireAuthMiddleware: Middleware = async (ctx, next) => {
 
 Read the flash on the target page with `useLocationState(FlashMessage)`. The `{ flash: true }` option makes it auto-clear after first render. See `/hooks`.
 
+A redirect is followed on a link click, `router.push()`, and Back/Forward to an entry the client has to fetch. On Back/Forward the redirect replaces the history entry it was triggered from: Back from the target lands on the entry before the redirecting one, not on the redirecting one again.
+
 ## Authentication Middleware
 
 ```typescript

package/skills/ppr/SKILL.md

@@ -53,7 +53,8 @@ implements the shell family (`getShell`/`putShell`): `MemorySegmentCacheStore`
 `VercelCacheStore` (Vercel Runtime Cache). A ppr route on a store without the
 family renders normally (no shell) with a once-per-key warning. A custom store
 returns each `ShellCacheEntry` field as `putShell` received it, including
-`buildVersion` and `snapshot` (both required; the snapshot can be empty).
+`buildVersion` (the router's document version) and `snapshot` (both required;
+the snapshot can be empty).
 
 ```typescript
 import { createRouter, urls } from "@rangojs/router";
@@ -250,7 +251,9 @@ under `cache()` and under the shell alike.
 
 Invalidation crosses layers: `updateTag()`/`revalidateTag()` reach segment,
 shell, loader, and item entries in the same store, and shell entries
-additionally self-invalidate on `React.version` change.
+additionally self-invalidate on `React.version` change and when the router's
+document version changes (server code, SSR output, client asset names, `base`
+or Prerender payloads changed), not on every deploy.
 
 ## The serve pipeline: commit after ALL middleware
 
@@ -383,10 +386,12 @@ encountered by the shell capture.
 Two more decisions are made before any shell-store read, so probes and
 prerendered routes never spend passive `getShell` I/O:
 
-- A partial request carrying neither `X-RSC-Router-Client-Path` nor `Referer`
-  (a curl probe, a synthetic monitor) can never produce a partial match; it
-  reports `BYPASS; reason=no-navigation-context`. Alert on replay hit-rate
-  with this in mind — such probes are not cache misses.
+- A partial request carrying neither `X-RSC-Router-Client-Path` nor a
+  same-origin `Referer` (a curl probe, a synthetic monitor) can never produce
+  a partial match; it reports `BYPASS; reason=no-navigation-context`. A
+  `Referer` on another origin counts as absent: only its pathname would be
+  matched, as if it were a route of this app. Alert on replay hit-rate with
+  this in mind — such probes are not cache misses.
 - A `Prerender()` route's partial is served from the build-time prerender
   store inside matching (a better-than-HIT outcome); it reports
   `BYPASS; reason=prerender-store`. Its captures never record the page's
@@ -436,7 +441,7 @@ The bounded bypass tokens, grouped by when they are decided:
 | Token                                                                         | Decided           | Meaning                                                                                                                                                                                                              |
 | ----------------------------------------------------------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `method`, `dynamic`, `nonce`, `store-unavailable`, `passive-read-unsupported` | pre-read          | request/route/store ineligible for replay                                                                                                                                                                            |
-| `no-navigation-context`                                                       | pre-read          | no `X-RSC-Router-Client-Path`/`Referer`; a partial match is impossible                                                                                                                                               |
+| `no-navigation-context`                                                       | pre-read          | no `X-RSC-Router-Client-Path` and no same-origin `Referer`; a partial match is impossible                                                                                                                            |
 | `prerender-store`                                                             | pre-read or match | `Prerender()` route served by its baked artifact (pre-read probe of the normal variant; reclassified post-match when the store actually served, either variant)                                                      |
 | `intercept`                                                                   | match             | the navigation resolved to an intercept — replay is never armed for intercepts (they keep their normal cache path); no heal capture                                                                                  |
 | `cache-disabled`                                                              | pre-read or match | `cache(false)` (pre-read, static) or `condition()` false (decided at the lookup); consumer opt-out is absolute                                                                                                       |
@@ -896,31 +901,104 @@ value once it refreshes, while the baked container keeps the capture's. If a
 hole needs a stable value, give it its own cache (`"use cache"` with a
 profile, or a loader `cache()`); the shell never provides one.
 
-**Handle pushes from a bake-lane loader appear once.** The capture records
-the settled, thenable-free handle pushes of every loader body it runs (the
+**Handle pushes from a bake-lane loader appear once, and they match its
+data.** A loader's title, meta or breadcrumb describes the data next to it,
+so both come from the same run on every way a shell can be replayed: a
+document HIT, a client navigation, a prefetch. The capture records the
+settled, thenable-free handle pushes of every loader body it runs (the
 prelude rendered them): the `ssr: false` loader's own, those of the loaders
-it awaits with `ctx.use()`, and those its own `cache()` entry replays. Every
-HIT restores them with the handler layer, and they stand: a bake-lane loader
-that does run on the HIT (a hole-carrying one) reads the store, so its settled
-pushes, and those a `"use cache"` hit inside its body replays, are dropped
-instead of replacing the restored ones. Any handle, deduping or not, shows
-each value once, and it is the value the prelude rendered. A loader the route
-also registers on the live lane is a hole: its live run replaces its restored
-pushes, and those of the loaders it awaits, so they show its live value, even
-when a bake-lane loader running on the HIT awaits it. A run that throws or
-makes no push shows none of the capture's once its run ends; a hole slower
-than the handler barrier shows the shell's copy in the first snapshot until
-then. A hole with its own loader `cache()` that hits shows the pushes that
-entry recorded, none if it recorded none, matching its data. A dependency the route does not
-register, which an `ssr: false` loader awaited at capture outside any live
-loader, is on neither lane: its settled pushes stay as the prelude rendered
-them, even where a live loader also awaits it, while its data is fresh. To
-keep its pushes live, declare it as its own `loader()` on the route. A push the capture cannot record (a
-deferred push, or one holding a promise) marks every loader record of the
-page to run: those bodies then still run on each HIT, in the background, and
-that push reaches the page (from the loader's own `cache()` entry when it
-hits) with the run's value; a push that lands after the document's handle snapshot
-reaches the client after hydration.
+it awaits with `ctx.use()`, and those its own `cache()` entry replays. What
+a replay does with a loader's recorded pushes follows what it does with that
+loader's data:
+
+| The replay serves the loader's data from                                    | Its settled pushes are                                                                                                                                                                      |
+| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| the shell (its pinned container)                                            | the shell's: restored with the handler layer, and they stand. A loader that does run on the replay (a hole-carrying one) reads the store, and the settled pushes that run makes are dropped |
+| a run on this request (a live-lane loader, or one the shell has no pin for) | that run's: they replace the shell's copies in place; a run that throws or makes no push shows none                                                                                         |
+| the loader's own `cache()` entry                                            | that entry's: the pushes it recorded, none if it recorded none                                                                                                                              |
+
+So any handle, deduping or not, shows each value once. A pinned loader's
+pushes are the values the prelude rendered, also for the pushes a `"use
+cache"` hit inside its body replays. A loader the route also registers on
+the live lane is a hole: its live run replaces its restored pushes, and those
+of the loaders it awaits, so they show its live value, even when a bake-lane
+loader running on the replay awaits it. On a document HIT the page hydrates
+with the shell's copy and the hole's value takes its place after hydration
+("Handles on a shell HIT" below). An
+`ssr: false` loader is served from the shell only while the entry holds its
+pin: a snapshot captured by a navigation alone carries none, and a shell over
+`ppr.maxSnapshotBytes` drops them. There the loader runs fresh, and its
+pushes are that run's, like its data.
+
+A dependency the route does not register, which an `ssr: false` loader
+awaited at capture outside any live loader, is on neither lane: its settled
+pushes stay as the prelude rendered them, even where a live loader also
+awaits it, while its data is fresh. (They follow the run instead once the
+entry has lost a pin, because the loader that awaits it then runs.) To keep
+its pushes live, declare it as its own `loader()` on the route. A push the
+capture cannot record (a deferred push, or one holding a promise) marks every
+loader record of the page to run: those bodies then still run on each replay,
+in the background, and that push reaches the page (from the loader's own
+`cache()` entry when it hits) with the run's value, on a document HIT and on
+a client navigation alike. On a document HIT it arrives after hydration.
+
+**Handles on a shell HIT.** A promise pushed from a loader is live and is
+never in a shell. To have a value in the shell's HTML, push it settled
+(await it) from the `ssr: false` loader, or push it from the handler.
+
+Three things follow, in this order of scope:
+
+1. **What is in a shell's HTML** changes only for promise pushes of
+   `ssr: false` loaders and of the loaders they await: `push(promise)`, or a
+   pushed value that holds a promise. Those run at capture, and the shell
+   renders no element for such a push. A loader without `ssr: false` never
+   ran at capture, so nothing of it was ever in the shell.
+2. **On a shell HIT every loader push made during the request arrives after
+   hydration**, a live-lane loader's included. The document hydrates with
+   exactly the handle data the shell's HTML was rendered from (the handlers'
+   pushes and the settled pushes of the loaders that ran at capture), and
+   the request's own pushes follow as a normal `useHandle` update.
+3. **`useHandle` on every document, `ppr` or not:** a reader that React is
+   hydrating reads the handle data its HTML was rendered from, wherever its
+   boundary hydrates, and takes the newer data right after. So a reader
+   inside the `loading()` or `<Suspense>` of a loader that pushes after an
+   `await` hydrates clean.
+
+| On the HIT's request                                                        | In the HIT's HTML      | The client                                        |
+| --------------------------------------------------------------------------- | ---------------------- | ------------------------------------------------- |
+| a handler's push, a pinned `ssr: false` loader's settled push               | yes (the shell has it) | hydrates with it                                  |
+| a deferred push (`push(promise)`), or a push holding a promise, by a loader | no                     | gets it right after hydration                     |
+| a live-lane loader's push                                                   | no                     | gets it right after hydration                     |
+| the run of an `ssr: false` loader the shell has no pin for                  | the capture's push     | hydrates with the capture's, then shows the run's |
+
+A value a loader pushes as a promise is therefore in the HTML of a document
+MISS (the render awaits it) and of a route without `ppr`, and not in the
+HTML of a shell HIT. When a crawler or the first paint needs it, change one
+line:
+
+```ts
+ctx.use(Notes)(db.stockNote(id)); // a promise: live, after hydration on a HIT
+ctx.use(Notes)(await db.stockNote(id)); // settled: baked into the shell
+```
+
+The settled push bakes with the shell and is invalidated with it (its TTL,
+its tags). A promise is not baked, whenever it settles: it is the shape that
+says "per request", the same as a promise in the loader's data.
+
+A pinned loader's pushes are exactly the ones its capture made. If its body
+pushes a settled value only on some runs (behind a condition), a replay that
+runs it shows the capture's answer, a push or none, never a later run's next
+to the pinned data. A deferred push is the exception by design: it is
+delivered on every replay.
+
+One arrangement mixes sources by design. A loader that reads a
+`cache()`-bound loader with `ctx.use()` before that binding starts (a loader
+declared ahead of it, a parent layout) runs it live while the binding serves
+its entry, so the cached loader's data and its handle push can come from
+different runs on that request. To keep them together, declare the cached
+loader first, or read it from the handler: a handler's `ctx.use()` is where a
+loader read is baked. An entry such a request writes holds no pushes, and a
+later HIT of it then shows none for that loader.
 
 Four hard edges (each e2e/unit-pinned):
 
@@ -1187,8 +1265,9 @@ eligible captured segment snapshot, per-request CSP nonce, `streamMode:
 request the route's own `cache()` scope refuses (`cache(false)`, or a
 `condition()` returning false for it), and any store without the shell family.
 A stored shell is invalidated when
-`React.version` changes (postponed state is build-coupled), so deploys
-self-heal via recapture.
+`React.version` changes (postponed state is build-coupled) or when the router's
+document version changes, so a deploy that changes the router self-heals via
+recapture, and a deploy that does not keeps its shells.
 
 The per-request CSP nonce guarantee covers BOTH ways a nonce arrives — the
 `createRouter({ nonce })` provider AND a direct `ctx.set(nonce, value)` token
@@ -1234,13 +1313,13 @@ path(
 );
 ```
 
-| Field              | Default | Notes                                                                                                                                                                                                                                                                                                      |
-| ------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ttl`              | `300`   | shell freshness window in seconds (`ppr: true` uses the default)                                                                                                                                                                                                                                           |
-| `swr`              | —       | stale window: serve the stale shell + background recapture                                                                                                                                                                                                                                                 |
-| `tags`             | —       | operational tags UNIONED with the tags the capture collects — see "Invalidation" below                                                                                                                                                                                                                     |
-| `maxSnapshotBytes` | 8 MiB   | cap on the loader pins in the entry's snapshot (the bake-lane loader records). The recorded handler layer is exempt. Over the cap the pins are dropped and the shell is stored with its handler layer (warned once per key); bake-lane loaders then read the live store, and drift is repaired client-side |
-| `captureTimeout`   | 15000ms | ONE capture deadline: the handler layer settling (promises it passes or pushes, async server components, loaders it awaits), bake-lane loaders, and the prerender; a capture that misses it stores nothing rather than a partial shell                                                                     |
+| Field              | Default | Notes                                                                                                                                                                                                                                                                                                                                                                                                       |
+| ------------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ttl`              | `300`   | shell freshness window in seconds (`ppr: true` uses the default)                                                                                                                                                                                                                                                                                                                                            |
+| `swr`              | —       | stale window: serve the stale shell + background recapture                                                                                                                                                                                                                                                                                                                                                  |
+| `tags`             | —       | operational tags UNIONED with the tags the capture collects — see "Invalidation" below                                                                                                                                                                                                                                                                                                                      |
+| `maxSnapshotBytes` | 8 MiB   | cap on the loader pins in the entry's snapshot (the bake-lane loader records). The recorded handler layer is exempt. Over the cap the pins are dropped and the shell is stored with its handler layer (warned once per key); bake-lane loaders then run on every replay and read the live store, their handle pushes come from that run like their data, and drift from the prelude is repaired client-side |
+| `captureTimeout`   | 15000ms | ONE capture deadline: the handler layer settling (promises it passes or pushes, async server components, loaders it awaits), bake-lane loaders, and the prerender; a capture that misses it stores nothing rather than a partial shell                                                                                                                                                                      |
 
 A shell never outlives the route `cache()` entry it was captured from: under
 a route `cache()`, the shell is fresh no longer than that entry is (at most

package/skills/prerender/SKILL.md

@@ -359,8 +359,12 @@ first, so a runtime capture supersedes the baked entry once it exists.
 A build-baked shell is not on a wall clock the way a pure runtime `ppr` shell is.
 It serves from the first request after a deploy and keeps serving until one of:
 
-- **a redeploy** — the `buildVersion` gate retires every build entry (like a
-  React-version bump); the new build re-bakes;
+- **a redeploy** — the new build ships its own build shell manifest and
+  re-bakes. A shell stored at runtime for the route is replaced when the
+  router's document version changes, and a change of the prerendered payload
+  changes it (a Prerender payload is part of its router's document version, not
+  its data version, so cached data is kept); a React-version bump also retires
+  it;
 - **`updateTag`** on a tag the shell carries — drops it, so the next request
   MISSes and a runtime capture takes over.
 
@@ -697,7 +701,7 @@ emitted — wrap the route in `Passthrough()` when its segments must re-render.
 `updateTag()`/`revalidateTag()` evict runtime cache entries. They do not refresh
 a prerendered route's build-time Flight payload, which is served before the tag
 system is consulted, and a `cacheTag()` inside a `"use cache"` function that runs
-during the build has no runtime effect. A redeploy replaces the payload. To make
+during the build has no runtime effect. A redeploy replaces the payload; because a Prerender payload is part of its router's document version, a deploy whose only change is new prerendered content keeps cached data and replaces stored HTML (shells, document-cache responses) for that router. To make
 a route tag-invalidatable, serve it from the runtime cache instead (`cache()`,
 or a `Passthrough()` live handler). A build-baked **ppr shell** is different: a
 tag it carries does drop it (see "Freshness of a build shell").

package/skills/rango/SKILL.md

@@ -157,8 +157,9 @@ stated, greppable contract.
   `cacheTag(...tags)`, then `updateTag(...tags)` (awaitable) or `revalidateTag(...tags)`
   (background). Built-in stores index by tag.
 - `useLoader` / `useHandle` / `useFetchLoader` are client-only.
-- Caches are correctness-first: persistent store keys are version-segmented (no
-  cross-deploy drift), the forward/back cache is mutation-aware, and
+- Caches are correctness-first: persistent store keys are version-segmented per
+  `createRouter()` by a hash of its built code (a deploy that does not change a
+  router keeps its cache; one that does reads under new keys), the forward/back cache is mutation-aware, and
   `createVar({ cache: false })` throws on a **direct** read inside a `cache()`
   boundary or a `"use cache"` function (a deliberately non-propagating guard). See `/cache-guide` →
   "Correctness & invalidation".
@@ -422,11 +423,11 @@ npx rango generate src/urls.tsx src/api/
 
 Three modes:
 
-| Flag        | Behavior                                                                                                                  |
-| ----------- | ------------------------------------------------------------------------------------------------------------------------- |
-| (none)      | Static parser. Exits with an error, writing nothing, if an `include()` can't be resolved statically (factory or dynamic). |
-| `--static`  | Static parser, but writes partial output and prints the unresolvable includes as warnings.                                |
-| `--runtime` | Vite-based runtime discovery (full coverage; needs `vite` and `@vitejs/plugin-rsc`). `--config <path>` picks the config.  |
+| Flag        | Behavior                                                                                                                                    |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| (none)      | Static parser. Exits with an error, writing nothing, if an `include()` can't be resolved statically (factory or dynamic).                   |
+| `--static`  | Static parser, but writes partial output and prints the unresolvable includes as warnings.                                                  |
+| `--runtime` | Vite-based runtime discovery (full coverage; needs `vite`; `@vitejs/plugin-rsc` comes with the router). `--config <path>` picks the config. |
 
 ### Auto-detection
 

package/skills/router-setup/SKILL.md

@@ -170,7 +170,7 @@ interface RangoOptions<TEnv> {
     request: Request,
     env: TEnv,
   ) => string | boolean | Promise<string | boolean>;
-  version?: string; // Client/server version string; defaults to the build VERSION
+  version?: string; // Cache version and client/server version; replaces both computed versions (data and document); defaults to the versions `vite build` computes per router
   originCheck?:
     | boolean
     | ((
@@ -215,6 +215,7 @@ rango({
   headScripts: "preinit", // "preinit" (executing head module scripts) | "preload" (modulepreload hints only)
   prerender: { onError: "fail" }, // "fail" | "warn" when a Prerender/Static render throws (/prerender)
   buildEnv: false, // Build-time ctx.env for Prerender/Static handlers (/prerender)
+  encryptionKey: process.env.RANGO_ENCRYPTION_KEY, // Stable server-action encryption key (see Notes)
 });
 ```
 
@@ -234,8 +235,14 @@ Notes:
 
 - `clientChunks` default groups app client components by the directory after a
   route root (`routes/`, `app/`, `pages/`, `features/`, `handlers/`, ...), so
-  `routes/dashboard/**` becomes chunk `app-dashboard`. Flat folders such as
-  `src/components/` stay in the shared chunk. `false` restores
+  `routes/dashboard/**` becomes chunk `app-dashboard`. An `app/` directly
+  followed by another marker with a directory after it is a source root, so
+  `app/routes/product/**` is `app-product`; `app/<segment>/**`,
+  `app/components/**` and files directly in `app/routes/` keep `app-<segment>`
+  / `app-components` / `app-routes`. Flat folders such as
+  `src/components/` stay in the shared chunk. A group is the loading unit:
+  rendering any member downloads the whole group's chunk;
+  `DEBUG=rango:chunks vite build` logs each group's size. `false` restores
   `@vitejs/plugin-rsc`'s grouping (one client chunk per router). A function
   `(meta) => string | undefined` names the group per module (`undefined` keeps
   the default); `directoryClientChunks(meta)`, the default strategy, is
@@ -248,6 +255,19 @@ Notes:
   renders and PPR shell capture. Unset, documents whose route has a
   `loader(Def, { ssr: false })` raise it automatically so that content stays
   in place; see `/loader`.
+- `encryptionKey` is the key that encrypts inline server-action bound
+  arguments: base64-encoded 32 bytes (`openssl rand -base64 32`). Pass it as
+  `rango({ encryptionKey: process.env.RANGO_ENCRYPTION_KEY })`, never as a
+  literal. It is validated when `rango()` is called (invalid base64 or a wrong
+  size throws). `undefined` falls back to the `RANGO_ENCRYPTION_KEY`
+  environment variable, then to a key generated per build. The key is part of
+  the cache version of every router whose server code encrypts inline-action
+  bound arguments, so without a stable key those routers get a new version (and
+  a cleared cache) on every build; the build prints one note when that applies.
+  A router that renders no such action keeps its cache without one (`/use-cache`,
+  `/cache-guide`).
+- `createRouter({ version })` takes effect on every preset, including `node`
+  and `vercel`. It replaces both computed cache versions with that exact value.
 - `@rangojs/router/vite` also exports `poke()`, a dev-server plugin: type `e`
   then Enter (or Ctrl+R where the terminal passes it through) to full-reload
   the browser.

package/skills/testing/SKILL.md

@@ -89,32 +89,35 @@ The single rule that drives everything:
 
 Each primitive links to its sub-file (API + recipe + caveats).
 
-| The behavior is…                                                                                                                   | Layer        | Primitive                                                                                             | Import root                      |
-| ---------------------------------------------------------------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------- | -------------------------------- |
-| a `reverse` / `href` / params / env TYPE contract (a wrong name or missing param must not compile)                                 | types (tsc)  | [`@ts-expect-error` / `expectTypeOf`](./reverse-and-types.md)                                         | `@rangojs/router/client` + `tsc` |
-| one loader's data logic                                                                                                            | unit (node)  | [`runLoader`](./loader.md)                                                                            | `@rangojs/router/testing`        |
-| a loader's cookie / header / thrown `redirect()`/`notFound()` / handle-push output                                                 | unit (node)  | [`runLoaderResult`](./loader.md)                                                                      | `@rangojs/router/testing`        |
-| one middleware's ordering / short-circuit / cookie+header merge                                                                    | unit (node)  | [`runMiddleware`](./middleware.md)                                                                    | `@rangojs/router/testing`        |
-| a `"use server"` action's cookie / header / flash output (even on `throw redirect()`)                                              | unit (node)  | [`runInRequestContext`](./server-actions.md)                                                          | `@rangojs/router/testing`        |
-| a `transition({ when })` browser predicate against `{ kind, from, to, action }`                                                    | unit (node)  | [`runTransitionWhen`](./predicates.md) (`{ applied, gatedOff, context }`)                             | `@rangojs/router/testing`        |
-| a `clientUrls()` `revalidate()` / `isAction(ref)` predicate                                                                        | unit (node)  | [`runClientRevalidate`](./predicates.md) (production chain evaluator + locked defaults)               | `@rangojs/router/testing`        |
-| a handle's `collect`/accumulator, a seeded handle read, or a loader handle write                                                   | unit         | [`collectHandle` / seeded `handles` / `handlePushes`](./handles.md)                                   | `@rangojs/router/testing`        |
-| a CLIENT component reading router context (`useParams`/`useReverse`/`Outlet`/`useNavigation`/`useLoader`)                          | unit (DOM)   | [`renderRoute`](./client-components.md)                                                               | `@rangojs/router/testing/dom`    |
-| a stale indicator from `useLoader().isLoading` while a `transition()` navigation re-runs the loader                                | unit (DOM)   | [`renderRoute` + `navigate(url, { loaders })`](./client-components.md#held-navigation)                | `@rangojs/router/testing/dom`    |
-| a component reading `useLocationState(Def)` after `router.push(url, { state: [Def(value)] })`                                      | unit (DOM)   | [`renderRoute` + `withLocationStateKey`](./client-components.md#location-state)                       | `@rangojs/router/testing[/dom]`  |
-| a redirect / status / headers / cookies / **response route** (json/text/html/xml/md), no Flight                                    | integration  | [`dispatch`](./response-routes.md)                                                                    | `@rangojs/router/testing`        |
-| a real async **Server Component** (assert what it rendered: typed boundary props, server-rendered host content, inlined-vs-island) | RSC unit     | [`renderServerTree` + `findClientBoundaries`/`findElements`](./server-tree.md)                        | `@rangojs/router/testing/flight` |
-| the exact Flight **wire payload** shape (a drift snapshot)                                                                         | RSC unit     | [`renderToFlightString` + `toMatchFlightSnapshot`](./flight.md)                                       | `@rangojs/router/testing/flight` |
-| a real route **handler** `(ctx) => rsc` (params/loaders/vars -> rendered RSC + effects)                                            | RSC unit     | [`renderHandler`](./render-handler.md)                                                                | `@rangojs/router/testing/flight` |
-| navigation, hydration, PE parity, view transitions, real SSR                                                                       | e2e          | [`createRangoE2E` -> `parityDescribe`/`expectParity`](./e2e-parity.md)                                | `@rangojs/router/testing/e2e`    |
-| a `"use cache"` hit in a handler (the body runs once across renders; the value round-trips)                                        | RSC unit     | [`renderHandler` + seeded `cacheStore`](./render-handler.md#a-use-cache-hit)                          | `@rangojs/router/testing/flight` |
-| a `"use cache"` hit in a loader (the same, in the react-server project)                                                            | RSC unit     | [`runLoader` + seeded `cacheStore`](./loader.md)                                                      | `@rangojs/router/testing`        |
-| a loader's own `cache()` (HIT, `updateTag()` of a tag its body recorded)                                                           | RSC unit     | [`runLoader` + `cache` + seeded `cacheStore`](./loader.md)                                            | `@rangojs/router/testing`        |
-| cache hit/miss/stale, prerender (= a cache hit by design)                                                                          | e2e + signal | [`assertCacheStatus` (header) / `assertCacheDecision` (telemetry sink)](./cache-prerender.md)         | `@rangojs/router/testing[/e2e]`  |
-| a `ppr` route's shell: MISS -> capture -> HIT, what the shell froze vs what a HIT renders live, tag eviction, navigation replay    | RSC unit     | [`serveShellRequest`](./serve-shell-request.md)                                                       | `@rangojs/router/testing/flight` |
-| PPR shell HIT/MISS in real HTML (`ppr` path option), shell store key / getShell after flush                                        | e2e + signal | [`assertShellStatus` / `shellCacheKey` + store](./cache-prerender.md#ppr-shell-and-navigation-replay) | `@rangojs/router/testing[/e2e]`  |
-| generated route map drift vs runtime                                                                                               | unit (node)  | [`assertGeneratedRoutesMatch`](./reverse-and-types.md)                                                | `@rangojs/router/testing`        |
-| a platform binding (`env.DB` / Durable Object / `env.R2`)                                                                          | unit/integr. | [your own double via `env`](./bindings.md)                                                            | (any primitive's `env` option)   |
+| The behavior is…                                                                                                                   | Layer        | Primitive                                                                                                             | Import root                      |
+| ---------------------------------------------------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
+| a `reverse` / `href` / params / env TYPE contract (a wrong name or missing param must not compile)                                 | types (tsc)  | [`@ts-expect-error` / `expectTypeOf`](./reverse-and-types.md)                                                         | `@rangojs/router/client` + `tsc` |
+| one loader's data logic                                                                                                            | unit (node)  | [`runLoader`](./loader.md)                                                                                            | `@rangojs/router/testing`        |
+| a loader's cookie / header / thrown `redirect()`/`notFound()` / handle-push output                                                 | unit (node)  | [`runLoaderResult`](./loader.md)                                                                                      | `@rangojs/router/testing`        |
+| one middleware's ordering / short-circuit / cookie+header merge                                                                    | unit (node)  | [`runMiddleware`](./middleware.md)                                                                                    | `@rangojs/router/testing`        |
+| a `"use server"` action's cookie / header / flash output (even on `throw redirect()`)                                              | unit (node)  | [`runInRequestContext`](./server-actions.md)                                                                          | `@rangojs/router/testing`        |
+| a `transition({ when })` browser predicate against `{ kind, from, to, action }`                                                    | unit (node)  | [`runTransitionWhen`](./predicates.md) (`{ applied, gatedOff, context }`)                                             | `@rangojs/router/testing`        |
+| a `clientUrls()` `revalidate()` / `isAction(ref)` predicate                                                                        | unit (node)  | [`runClientRevalidate`](./predicates.md) (production chain evaluator + locked defaults)                               | `@rangojs/router/testing`        |
+| a handle's `collect`/accumulator, a seeded handle read, or a loader handle write                                                   | unit         | [`collectHandle` / seeded `handles` / `handlePushes`](./handles.md)                                                   | `@rangojs/router/testing`        |
+| a CLIENT component reading router context (`useParams`/`useReverse`/`Outlet`/`useNavigation`/`useLoader`)                          | unit (DOM)   | [`renderRoute`](./client-components.md)                                                                               | `@rangojs/router/testing/dom`    |
+| a stale indicator from `useLoader().isLoading` while a `transition()` navigation re-runs the loader                                | unit (DOM)   | [`renderRoute` + `navigate(url, { loaders })`](./client-components.md#held-navigation)                                | `@rangojs/router/testing/dom`    |
+| a component reading `useLocationState(Def)` after `router.push(url, { state: [Def(value)] })`                                      | unit (DOM)   | [`renderRoute` + `withLocationStateKey`](./client-components.md#location-state)                                       | `@rangojs/router/testing[/dom]`  |
+| location state while a navigation is pending (a loader the test holds), or after a back/forward                                    | unit (DOM)   | [`navigate(url, { state, loaders })`, a `popstate` event](./client-components.md#state-while-a-navigation-is-pending) | `@rangojs/router/testing[/dom]`  |
+| a CLIENT component's hydration: its first client render against its own server HTML (`typeof window`, a late `<Suspense>`)         | unit (DOM)   | [`renderRoute` + `hydrate: true`](./client-components.md#hydration)                                                   | `@rangojs/router/testing/dom`    |
+| location state with `clearOnReload`: state after a refresh vs a client navigation                                                  | unit (DOM)   | [`renderRoute` seeds, with and without `hydrate: true`](./client-components.md#location-state)                        | `@rangojs/router/testing[/dom]`  |
+| a redirect / status / headers / cookies / **response route** (json/text/html/xml/md), no Flight                                    | integration  | [`dispatch`](./response-routes.md)                                                                                    | `@rangojs/router/testing`        |
+| a real async **Server Component** (assert what it rendered: typed boundary props, server-rendered host content, inlined-vs-island) | RSC unit     | [`renderServerTree` + `findClientBoundaries`/`findElements`](./server-tree.md)                                        | `@rangojs/router/testing/flight` |
+| the exact Flight **wire payload** shape (a drift snapshot)                                                                         | RSC unit     | [`renderToFlightString` + `toMatchFlightSnapshot`](./flight.md)                                                       | `@rangojs/router/testing/flight` |
+| a real route **handler** `(ctx) => rsc` (params/loaders/vars -> rendered RSC + effects)                                            | RSC unit     | [`renderHandler`](./render-handler.md)                                                                                | `@rangojs/router/testing/flight` |
+| navigation, hydration, PE parity, view transitions, real SSR                                                                       | e2e          | [`createRangoE2E` -> `parityDescribe`/`expectParity`](./e2e-parity.md)                                                | `@rangojs/router/testing/e2e`    |
+| a `"use cache"` hit in a handler (the body runs once across renders; the value round-trips)                                        | RSC unit     | [`renderHandler` + seeded `cacheStore`](./render-handler.md#a-use-cache-hit)                                          | `@rangojs/router/testing/flight` |
+| a `"use cache"` hit in a loader (the same, in the react-server project)                                                            | RSC unit     | [`runLoader` + seeded `cacheStore`](./loader.md)                                                                      | `@rangojs/router/testing`        |
+| a loader's own `cache()` (HIT, `updateTag()` of a tag its body recorded)                                                           | RSC unit     | [`runLoader` + `cache` + seeded `cacheStore`](./loader.md)                                                            | `@rangojs/router/testing`        |
+| cache hit/miss/stale, prerender (= a cache hit by design)                                                                          | e2e + signal | [`assertCacheStatus` (header) / `assertCacheDecision` (telemetry sink)](./cache-prerender.md)                         | `@rangojs/router/testing[/e2e]`  |
+| a `ppr` route's shell: MISS -> capture -> HIT, what the shell froze vs what a HIT renders live, tag eviction, navigation replay    | RSC unit     | [`serveShellRequest`](./serve-shell-request.md)                                                                       | `@rangojs/router/testing/flight` |
+| PPR shell HIT/MISS in real HTML (`ppr` path option), shell store key / getShell after flush                                        | e2e + signal | [`assertShellStatus` / `shellCacheKey` + store](./cache-prerender.md#ppr-shell-and-navigation-replay)                 | `@rangojs/router/testing[/e2e]`  |
+| generated route map drift vs runtime                                                                                               | unit (node)  | [`assertGeneratedRoutesMatch`](./reverse-and-types.md)                                                                | `@rangojs/router/testing`        |
+| a platform binding (`env.DB` / Durable Object / `env.R2`)                                                                          | unit/integr. | [your own double via `env`](./bindings.md)                                                                            | (any primitive's `env` option)   |
 
 Cross-references to the DSL skills: `/loader`, `/middleware`, `/server-actions`,
 `/handler-use`, `/hooks`, `/response-routes`, `/route`, `/caching`, `/prerender`,
@@ -147,6 +150,7 @@ beside their function):
 |                                           | `collectHandle`                                                                                                                                              | [`handles.md`](./handles.md)                         |
 |                                           | `withLocationStateKey`                                                                                                                                       | [`client-components.md`](./client-components.md)     |
 |                                           | `dispatch`                                                                                                                                                   | [`response-routes.md`](./response-routes.md)         |
+|                                           | `setBuildVersions`                                                                                                                                           | [`serve-shell-request.md`](./serve-shell-request.md) |
 |                                           | `assertCacheStatus`, `assertCacheDecision`, `parseCacheHeader`, `createCacheSink`, `filterCacheDecisions`                                                    | [`cache-prerender.md`](./cache-prerender.md)         |
 |                                           | `assertShellStatus`, `parseShellStatus`, `shellCacheKey`, `SHELL_STATUS_HEADER`, `assertPprReplayStatus`, `parsePprReplayStatus`, `PPR_REPLAY_STATUS_HEADER` | [`cache-prerender.md`](./cache-prerender.md)         |
 |                                           | `assertGeneratedRoutesMatch`, `diffGeneratedRoutes`                                                                                                          | [`reverse-and-types.md`](./reverse-and-types.md)     |