@rangojs/router 0.20.0 → 0.22.0

package/skills/deployment-caching/SKILL.md

@@ -20,11 +20,12 @@ To choose between the in-app layers themselves, start at `/cache-guide`.
 | `"use cache"`                     | one function result                             |                            yes |                                                          yes | caller, handlers, loaders, rendering |
 | `cache()`                         | serialized Flight segments                      |                            yes |                                                          yes | middleware, loaders, HTML rendering  |
 | `Prerender()`                     | build-time Flight segments in the server bundle |                            yes |                                                          yes | middleware, loaders, HTML rendering  |
+| `Prerender(..., { onDemand })`    | refreshed Flight segments in a writable store   |                            yes |                                                          yes | middleware, loaders, HTML rendering  |
 | `ppr`                             | HTML prelude + React postponed state            |                            yes |                                 **yes, before shell commit** | middleware, holes, hydration payload |
 | `createDocumentCacheMiddleware()` | complete response in the app cache store        |                            yes | outer middleware runs; the hit skips its downstream pipeline | nothing downstream                   |
 | HTTP CDN cache (`s-maxage`)       | complete HTTP response outside the app          |                         **no** |                                                       **no** | nothing                              |
 
-The first five rows enter the app. The first four preserve the complete request
+The first six rows enter the app. The first five preserve the complete request
 model; a document-cache middleware hit intentionally short-circuits its
 downstream pipeline. The last row is a platform cache: on a hit it serves bytes
 without invoking Rango at all.
@@ -71,12 +72,31 @@ Worker at the edge, middleware runs there, and PPR shell lookup/resume stays in
 that Worker. `CFCacheStore` supplies the app cache families; client assets are
 served separately as assets.
 
+An on-demand prerender store (`/prerender` → "On-demand refresh") on Workers
+is `createKVPrerenderStore(env.PRERENDER_KV)` from
+`@rangojs/router/prerender/cloudflare`: refreshes run from `scheduled`,
+`queue` or a webhook route, and every request to an on-demand route pays one
+KV read plus one per tag on the entry.
+
+The same `router.prerender()` call warms any other route's caches before
+traffic, when `CFCacheStore` has `kv` (shared by every colo). It fills the
+calling colo and KV; a colo that already holds its own copy keeps it until it
+expires, so a content refresh is `updateTag()` and then the warm: no colo
+serves the old copy, and a colo without one reads the warmed entry
+(`/cloudflare` → "Warm routes on Workers").
+
 ### Vercel
 
 The Vercel preset emits static client assets plus one streaming Node Function.
 HTML, Flight, prerender payloads, and PPR shells are served from that function.
 `VercelCacheStore` uses Runtime Cache inside the function; Runtime Cache is not
-Vercel's CDN/ISR cache.
+Vercel's CDN/ISR cache. Rango's on-demand prerender does not use Vercel ISR
+either: it needs a durable `WritablePrerenderStore` shared by every function
+instance, and v1 ships none for Vercel (the in-memory store is per process),
+so a Vercel app writes a small get/set adapter over its own storage.
+Warming a plain route (`/prerender` → "Warm any route before traffic") needs
+no such store: it writes to `VercelCacheStore`, in the region the call runs
+in.
 
 The preset deliberately emits no Vercel `.prerender-config.json`, response
 `chain`, or CDN-stitched resume function. Vercel's open-source Build Output
@@ -155,15 +175,16 @@ the app store, should own the complete response.
 
 ## Decision guide
 
-| Requirement                                         | Choose                                     |
-| --------------------------------------------------- | ------------------------------------------ |
-| Per-request auth or request shaping                 | in-function caching; never shared CDN HTML |
-| Stable shell with cart/session/live prices          | `ppr` with live holes                      |
-| Build-known segments with live loaders              | `Prerender()`                              |
-| Fully public response, whole-page TTL is acceptable | HTTP `s-maxage` + SWR                      |
-| Whole response reused inside the app store          | `createDocumentCacheMiddleware()`          |
-| One query or component is expensive                 | `"use cache"`                              |
-| One route subtree is expensive                      | `cache()`                                  |
+| Requirement                                         | Choose                                                |
+| --------------------------------------------------- | ----------------------------------------------------- |
+| Per-request auth or request shaping                 | in-function caching; never shared CDN HTML            |
+| Stable shell with cart/session/live prices          | `ppr` with live holes                                 |
+| Build-known segments with live loaders              | `Prerender()`                                         |
+| Prerendered page refreshed on a CMS edit, no deploy | `Prerender(..., { onDemand })` + `router.prerender()` |
+| Fully public response, whole-page TTL is acceptable | HTTP `s-maxage` + SWR                                 |
+| Whole response reused inside the app store          | `createDocumentCacheMiddleware()`                     |
+| One query or component is expensive                 | `"use cache"`                                         |
+| One route subtree is expensive                      | `cache()`                                             |
 
 For a large dynamic app, CDN-stitched PPR would mainly improve shell first-byte
 latency and avoid sending the prelude from the function. It would not remove the
@@ -175,7 +196,7 @@ provably public and shared.
 ## Related skills
 
 - `/ppr` — shell capture, holes, middleware commit point, invalidation
-- `/prerender` — build-time Flight segments and `Prerender + ppr`
+- `/prerender` — build-time Flight segments, `Prerender + ppr`, and on-demand refresh
 - `/document-cache` — store-backed complete-response middleware
 - `/vercel` — Vercel Build Output preset and Runtime Cache wiring
 - `/cloudflare` — Worker deployment and bindings

package/skills/document-cache/SKILL.md

@@ -175,20 +175,22 @@ header or logs to identify an actual CDN hit.
 
 ## Cache Key Generation
 
-The default key is the host, pathname, and sorted search string (internal
-`_rsc*` params removed, `cache.searchParams` filtering applied), followed by
-suffixes that separate response variants:
+The default key is the serving router's id, the host, pathname, and sorted
+search string (internal `_rsc*` params removed, `cache.searchParams` filtering
+applied), followed by suffixes that separate response variants:
 
-- HTML document requests: `{host}{pathname}[?search]:html`
+- HTML document requests: `{routerId}@{host}{pathname}[?search]:html`
 - RSC requests (client navigations and full-document Flight fetches):
-  `{host}{pathname}[?search]:rsc`
+  `{routerId}@{host}{pathname}[?search]:rsc`
 - Client navigations additionally add a hash of the segments the client already
   has (`:{segmentHash}`), so navigations from pages with different layouts get
   different cached payloads, and a `:fragments` marker when the client accepts
   fragment envelopes.
 
-A custom `keyGenerator(url)` replaces only the `{host}{pathname}[?search]` part;
-the variant suffixes are still appended.
+A custom `keyGenerator(url)` replaces the whole
+`{routerId}@{host}{pathname}[?search]` part, router id included, so a generator
+used by routers that share a store must keep them apart itself; the variant
+suffixes are still appended.
 
 ## What Gets Cached
 
@@ -320,13 +322,13 @@ everything else.
 
 ## Document Cache vs Segment Cache
 
-| Feature      | Document Cache                        | Segment Cache (`cache()`)         |
-| ------------ | ------------------------------------- | --------------------------------- |
-| Granularity  | Full response                         | Individual segments               |
-| Opt-in       | `Cache-Control` `s-maxage`            | `cache({ ttl, swr })`             |
-| Loaders      | Frozen with the response              | Always run fresh                  |
-| Use case     | Static pages                          | Dynamic compositions              |
-| Key includes | host + URL + variant (+ segment hash) | host + pathname + params + search |
+| Feature      | Document Cache                                 | Segment Cache (`cache()`)                  |
+| ------------ | ---------------------------------------------- | ------------------------------------------ |
+| Granularity  | Full response                                  | Individual segments                        |
+| Opt-in       | `Cache-Control` `s-maxage`                     | `cache({ ttl, swr })`                      |
+| Loaders      | Frozen with the response                       | Always run fresh                           |
+| Use case     | Static pages                                   | Dynamic compositions                       |
+| Key includes | router + host + URL + variant (+ segment hash) | router + host + pathname + params + search |
 
 Use document cache for mostly-static pages. Use segment cache when different parts of a page have different cache requirements.
 

package/skills/hooks/SKILL.md

@@ -68,6 +68,9 @@ the one for your case.
 - [`./state.md`](./state.md) — `useLocationState` (persistent + flash state,
   `.read()`/`.read(location)`/`.write()`/`.delete()`, typed `state` on `router.push()` /
   `router.replace()`, serializability errors that name the failing field),
+  state from another deploy (dropped by the router, no version to manage), the
+  `createLocationState` options (`flash`; `clearOnReload` for state that must
+  not come back after a refresh, such as a "load more" list),
   `invalidateClientCache()`.
 - [`./outlets.md`](./outlets.md) — `Outlet`, `ParallelOutlet`, `useOutlet`.
 - [`./urls.md`](./urls.md) — `useParams`, `usePathname`, `useSearchParams`,
@@ -94,3 +97,25 @@ the one for your case.
 | `useAction()`             | Server action state                                            | state, actionId, payload, error, result                                         |
 | `useLocationState()`      | History state (persists or flash)                              | T \| undefined                                                                  |
 | `invalidateClientCache()` | Force client caches to miss (function, not a hook; root entry) | `void`                                                                          |
+
+## Hydration
+
+On a document load every router hook renders what the server rendered until
+the document has finished streaming, wherever the component sits. A component
+in a `<Suspense>` or `loading()` boundary that streams in after the rest of
+the page hydrates with the document's pathname, params, search params and
+segments, an idle `useNavigation()` and `useAction()`, a `useLinkStatus()` that
+is not pending, the handle data the HTML was rendered from, and `undefined`
+location state, even when a navigation or an action has started meanwhile. It
+cannot mismatch its server HTML.
+
+- Navigation state, params and action state: the component shows the live
+  value right after it hydrates.
+- Handle data a loader pushed late, and the entry's location state: every
+  reader gets them once the whole document has streamed and hydrated, in one
+  transition. A reader re-renders only when its selection changes.
+- A navigation that commits before then mounts its page with the live values
+  from its first render. A boundary of the document that persists across that
+  navigation and has not hydrated yet then hydrates against the live values;
+  where they differ from its HTML, React reports the mismatch and renders that
+  boundary on the client.

package/skills/hooks/handle-and-actions.md

@@ -39,6 +39,11 @@ the capture, so its pushes always apply client-side; with `ssr: false` they
 bake into the shell. See `/loader` → "Writing Handles from Loaders". `useHandle`
 re-renders on every handle update, late loader pushes included.
 
+On a document load `useHandle` hydrates with the handle data its HTML was
+rendered from, wherever the reader sits; late loader pushes reach every reader
+once the document has finished streaming and every boundary has hydrated (see
+`SKILL.md`, "Hydration").
+
 Handles can be passed as props from server to client components:
 
 ```tsx

package/skills/hooks/navigation.md

@@ -27,6 +27,34 @@ function IsLoading() {
 }
 ```
 
+#### Pending UI, Back/Forward included
+
+A link click, `router.push()` and a Back/Forward that has to fetch its entry
+report a pending navigation the same way. While the page being left is still
+on screen:
+
+| What you want to show                          | Read                                                                                |
+| ---------------------------------------------- | ----------------------------------------------------------------------------------- |
+| a request is out, nothing has arrived          | `state === "loading"`; `pendingUrl` is the URL being fetched                        |
+| the page has not fully arrived yet             | `isStreaming`: true from the start of the request until the stream ends             |
+| which page is on screen while the request runs | `location`, or `usePathname()` / `useSearchParams()` (see [`./urls.md`](./urls.md)) |
+
+`state` and `pendingUrl` cover the network wait. Once the response has
+arrived a loader may still be streaming, and React keeps the page being left
+on screen where a navigation holds its content (a same-route change, a
+`transition()` route); `isStreaming` covers that part too, so use it for a
+progress indicator that should last until the new page is complete.
+
+On Back/Forward the address bar changes at once, before any of this: during
+the wait `window.location` is the entry being fetched, the same URL as
+`pendingUrl`, and `location` is the page on screen. A Back/Forward served
+from the client's history cache restores its page in one commit and reports
+no pending state.
+
+`location` moves when the response arrives. Where React then holds the page
+being left, it is ahead of the screen for that last part of the wait, and so
+is a URL hook in a component that first mounts then (issue #1046).
+
 ### useRouter()
 
 Access stable router actions. The returned object never changes identity, so
@@ -138,6 +166,16 @@ function Breadcrumbs() {
 const isShopRoute = useSegments((s) => s.path[0] === "shop");
 ```
 
+The selector is applied when the router store changes (a navigation or new
+handle data), as with `useNavigation` and `useAction`. A new selector function
+on a re-render takes effect at the next change. To derive from a prop, select
+the state and derive in render:
+
+```tsx
+const segments = useSegments();
+const part = segments.path[depth];
+```
+
 ### useLinkStatus()
 
 Track pending state inside a Link component. `pending` is `true` while a

package/skills/hooks/state.md

@@ -84,6 +84,59 @@ definition:
 const state = useLocationState<{ from?: string }>(); // { from?: string } | undefined
 ```
 
+### When a reader sees an entry's state
+
+A reader sees a history entry's location state together with that entry's
+page, never before it. The router keeps the state of the entry on screen next
+to the page it renders and changes both in one React commit. While a
+navigation is pending (its loader still streaming, a `transition()` holding
+the page) what is on screen keeps the state of the entry being left. That
+holds for every reader in it, including one that mounts during the wait: it
+reads the entry on screen, not the one `history.state` already holds.
+Back/forward and state the server sets on a navigation
+(`ctx.setLocationState()`, `redirect(url, { state })`) follow the same rule.
+
+| What changes the state                                       | A reader gets it                                                 |
+| ------------------------------------------------------------ | ---------------------------------------------------------------- |
+| `<Link state>`, `router.push()` / `router.replace()`         | in the commit that shows the destination                         |
+| back/forward                                                 | in the commit that restores the entry (cached or refetched)      |
+| the server, on a navigation (`setLocationState`, a redirect) | in the commit that shows the destination                         |
+| a navigation the server answers with nothing to re-render    | with the new location: the page on screen is the entry's         |
+| `router.push(url, { revalidate: false })` (no server fetch)  | with the new location: the page does not change                  |
+| a server action's `setLocationState` (no navigation)         | when the action's response arrives, added to what readers show   |
+| `Def.write()` / `Def.delete()`                               | when the entry is next restored: back/forward to it, or a reload |
+
+Three consequences:
+
+- A value keeps its identity until the entry's state changes it. A navigation
+  that carries no state re-renders no reader. One that does re-renders each
+  reader once, in the commit that already renders the page; a reader of a
+  slot the navigation carried forward unchanged (the value it got from the
+  hook, passed back) or of a slot a server action did not touch gets the same
+  object again, so its effects and memoized children do not run. Any other
+  object is a new value, equal content included: a link clicked twice
+  announces its state twice. A value is always a copy of what was passed.
+- `Def.write()` and `Def.delete()` change the history entry and nothing a
+  reader shows, whether it is mounted or mounts later. `Def.read()` returns
+  the written value at once.
+- Outside the router's provider (a second React root, a component rendered
+  bare in a test) a reader has no entry and returns `undefined`. Test with
+  `renderRoute` (see `/testing`).
+
+A reader that mounts with the destination reads the destination's state on
+its first render. Inside an optimistically rendered `clientUrls()` destination
+that is the state the navigation carries, before the server has answered (see
+`/client-urls`, "Pitfalls").
+
+The URL hooks follow the same rule for a component that is mounted across the
+navigation: on back/forward too, `usePathname()` and `useSearchParams()`
+change with the page, not at the `popstate` event (see
+[`./urls.md`](./urls.md), "When the URL hooks change"). One difference
+remains (issue #1046): a component that first mounts in the page being left,
+after the response arrived and while React still holds the destination, reads
+its own entry's location state from `useLocationState` and the destination's
+URL and params from `usePathname()`, `useSearchParams()` and `useParams()`.
+
 ### State on router.push() / router.replace()
 
 The same `state` option exists on `router.push()` / `router.replace()` (see
@@ -198,12 +251,14 @@ function FlashBanner() {
 ```
 
 Flash behavior is determined by the definition (`{ flash: true }`), not by which
-hook reads it. `useLocationState` reads the value during render (on the
-hydration render it returns `undefined` and reads in a post-mount effect, so
-SSR and hydration agree), then clears it from `history.state` via
-`replaceState` in a `useEffect`. Multiple components reading the same flash
-definition all see the value. Pressing back/forward will not re-show the flash
-since it was cleared.
+hook reads it. `useLocationState` reads the value during render (on a
+document load it returns `undefined` until the document has finished streaming
+and hydrating, so SSR and hydration agree), then clears it from `history.state` via
+`replaceState` in a `useEffect`. Every component reading the same flash
+definition sees the value, whenever it mounts, until the next navigation or
+back/forward commits its entry's state: an entry that carries no flash shows
+none. A server action's state does not end it. Pressing back/forward will not
+re-show the flash since it was cleared.
 
 Set flash state from the server via `redirect()` with state (from a handler,
 middleware, or server action). Import the definition from the shared module so
@@ -221,7 +276,9 @@ import { FlashMessage } from "../location-states";
 };
 ```
 
-Or via `ctx.setLocationState()` on any response (handlers and middleware):
+Or via `ctx.setLocationState()` from a handler or middleware. It is delivered
+with a client navigation's or an action's response; a document response
+carries no location state (there is no history entry to write it to yet):
 
 ```tsx
 (ctx) => {
@@ -230,6 +287,149 @@ Or via `ctx.setLocationState()` on any response (handlers and middleware):
 };
 ```
 
+### State from another deploy
+
+History entries survive reloads and back/forward, so a tab left open across a
+release still holds the state the older build wrote. The router drops it for
+you: every entry records the app version its location state was written under,
+and a read under any other version returns `undefined`, for typed slots and
+for plain state alike. You do not manage a version and there is none to read;
+the app version is the one the router already uses to reload a client that is
+behind the server. It is computed from the app's built code (its server code
+and the client assets), so it changes with a build that changes the app and
+stays the same across a rebuild or redeploy of unchanged code.
+
+| An entry's location state, read by                               | Result      |
+| ---------------------------------------------------------------- | ----------- |
+| the version that wrote it: navigation, back/forward, refresh     | the value   |
+| the same code rebuilt or redeployed                              | the value   |
+| a changed build, after a refresh or a restored tab               | `undefined` |
+| a changed build, on back/forward to an entry the older one wrote | `undefined` |
+| any build, when the entry predates this behavior                 | `undefined` |
+
+So location state is for the current session of the current version of the
+app: a filter carried on a link, a flash message, a scroll target. State that
+has to outlive a deploy that changes the app belongs in the URL, a cookie or
+storage. In development a
+server-module edit (HMR) changes the version too; the running page keeps its
+state, and the next document load drops it.
+
+### createLocationState options
+
+```ts
+createLocationState<TState>({
+  flash?: boolean, // read once, cleared after paint (above)
+  clearOnReload?: boolean, // drop the state on a document load (below)
+});
+```
+
+The value is always stored as-is. `clearOnReload` changes the slot's KEY in
+`history.state` instead, by a suffix on the key the Vite plugin injects
+(`<key>` below, `__rsc_ls_<file>#<ExportName>`):
+
+| Options         | Key in `history.state` | Reads `undefined` when                          |
+| --------------- | ---------------------- | ----------------------------------------------- |
+| none, `flash`   | `<key>`                | the slot is empty (`flash`: once read)          |
+| `clearOnReload` | `<key>~r`              | the entry's document was loaded since the write |
+
+`Def.__rsc_ls_key` is that key, suffix included. `~` cannot appear in an export
+name, so no other definition can end up with a suffixed key.
+
+`flash` with `clearOnReload` is rejected: `createLocationState` throws in
+development.
+
+### clearOnReload: state the server did not render with
+
+Location state lives in the browser, so the server renders a document without
+it. `useLocationState` therefore hydrates as `undefined` and applies the stored
+value once the document has finished streaming and every boundary has
+hydrated. For most state that is invisible. For state that decides
+how much content is on the page, it is a layout shift on every refresh.
+
+The case this option exists for is a "load more" list. `?page=6` loads that
+page's 50 products through a loader, and the 250 already on screen ride along
+as location state on the link, so the next page shows them at once and
+streams the new ones:
+
+```ts
+// location-states.ts
+import { createLocationState } from "@rangojs/router";
+
+export const CarriedProducts = createLocationState<Product[]>({
+  clearOnReload: true,
+});
+```
+
+```tsx
+"use client";
+import { Link, useLoader, useLocationState } from "@rangojs/router/client";
+import { ProductsLoader } from "./loaders"; // the page named by ?page
+import { CarriedProducts } from "./location-states";
+
+export function ProductList() {
+  const { data } = useLoader(ProductsLoader);
+  const carried = useLocationState(CarriedProducts) ?? [];
+  const products = [...carried, ...data.products];
+
+  return (
+    <>
+      <ul>
+        {products.map((product) => (
+          <li key={product.id}>{product.name}</li>
+        ))}
+      </ul>
+      <Link
+        to={`/products?page=${data.page + 1}`}
+        state={[CarriedProducts(products)]}
+        scroll={false}
+      >
+        Load more
+      </Link>
+    </>
+  );
+}
+```
+
+The list is a plain concatenation. After "Load more" the next page's loader
+streams while the current page stays on screen, and `carried` stays the
+current entry's until that page lands: the carried products and the loader's
+page change in one commit, so no product is ever listed twice.
+
+Without the option, a refresh of `?page=6` renders 50 products on the server
+and then inserts the stored 250 above them. With it, the refreshed page stays
+as the server rendered it:
+
+| What happens to the entry                                                 | A `clearOnReload` slot                                               |
+| ------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| The reader mounts during a client navigation (`<Link>`, `router.push`)    | applied, as without the option                                       |
+| back/forward inside the running app (popstate), a server action's state   | applied, as without the option                                       |
+| A document load: refresh, or a back/forward that loads the document       | not applied, and removed from `history.state`                        |
+| Later on that page: a reader mounts, or a navigation returns to the entry | still `undefined`; the next write (the next "Load more") stores anew |
+| The page is restored from the browser's back/forward cache                | untouched: nothing is loaded or hydrated                             |
+
+- The rule is any document load of the entry, not only the Reload button:
+  restoring a closed tab or duplicating a tab loads the document too.
+- Only the entry being loaded is cleared. Going back from it to an earlier
+  entry inside the running app is a client navigation and applies that
+  entry's state.
+- The router removes every `~r` key when the client starts, before hydration.
+  It goes by the key alone, so it does not matter whether a reader is mounted,
+  where it sits (a `<Suspense>` boundary that hydrates late included), or
+  whether the definition's module is loaded at all. Other slots on the entry
+  are left alone.
+- State the server sets is never dropped by this: a document response carries
+  no location state, and `ctx.setLocationState()` / `redirect(url, { state })`
+  reach `history.state` only through navigations and actions in the running
+  app, after start-up.
+- `.write()` stores under the same key, so it does not survive a refresh
+  either.
+- Adding the option to an existing definition moves it to the `~r` key: state
+  stored before, under the plain key, is no longer read (and is not removed).
+  Removing the option moves it back to the plain key; what was stored under
+  `~r` is removed at the next document load.
+- It cannot be combined with `flash`: flash state is removed at its first
+  read, so the pair could only drop a message nobody has seen yet.
+
 ### .read() (non-hook access)
 
 Read current location state outside React components (client-side only):
@@ -264,9 +464,11 @@ Static counterparts to `.read()`. Both mutate the current history entry's
 bookkeeping, other location state slots). Both are client-only; they throw
 when called on the server.
 
-Neither dispatches an event, so components reading via `useLocationState`
-will NOT re-render until the next navigation/popstate. Pair with `.read()`
-(or a fresh mount via back/forward/reload) instead.
+Neither changes what a `useLocationState` reader shows, mounted or mounting
+later: readers get the entry's state as it was committed (see "When a reader
+sees an entry's state"). The written value is there for `.read()` at once,
+and for readers when the entry is next restored (back/forward to it, or a
+reload).
 
 ```tsx
 "use client";
@@ -275,7 +477,7 @@ import { ProductState } from "./state";
 // Persisted across hard refresh and back/forward of this entry.
 ProductState.write({ name: "Widget", price: 9.99 });
 
-// Read later (or on next mount).
+// Read later.
 const current = ProductState.read();
 
 // Manually clear the slot. Idempotent if it isn't set.

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,34 @@ 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`.
+
+## Shared cache store
+
+Sub-apps may share one cache store (one KV namespace, one `MemorySegmentCacheStore`). Every entry that is a router's output for a host and path is keyed by that router as well; its key starts with the router's id (`{routerId}@{host}{path}...`):
+
+- PPR shells (document, navigation and build-time);
+- route `cache()` records, document-cache responses and response-route entries;
+- a loader's own `cache()` entry, and a `"use cache"` entry of a function called with a handler or loader `ctx`. A `ctx` is one router's: its context variables, its `env`, its `reverse()` map.
+
+So two sub-apps never read each other's entry, including where they serve the same host and path:
+
+- with the `hostOverride` cookie, which picks the app and forwards the request unchanged, so every app answers under the one preview origin;
+- after a `fallback()` that hands a request to another app's handler;
+- after a `router.prerender()` warm that resolved another app's host as its origin.
+
+There is nothing to configure and no namespace to manage. What it relies on is that each router has a stable id: the one the Vite plugin injects for a `createRouter({ ... })` call written with an object literal, or the `id` you pass (`createRouter({ id: "admin", ... })`). A router the plugin cannot reach, for example `createRouter(options)` with an options variable, falls back to a counter (`router_0`, `router_1`, ...) that follows module evaluation order. One such router is fine. With more than one, the build already warns (`N routers use auto-generated IDs`), because routes and cache versions are matched by the same id; the fix is the same here: pass the object literal inline or set an `id`.
+
+Not keyed by router, on purpose: a `"use cache"` entry of a function called with plain arguments or the bare `Request` (the function and its arguments name no router, so both apps share the entry), tag markers (an invalidation reaches every app), and any key you build yourself (`cache({ key })` on a route or a loader, the document cache's `keyGenerator`): keep those apart yourself where two apps must not share them.

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