@rangojs/router 0.21.0 → 0.22.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.21.0",
+  "version": "0.22.1",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",
@@ -125,6 +125,16 @@
       "react-server": "./src/cloudflare/index.ts",
       "default": "./src/cloudflare/index.ts"
     },
+    "./prerender": {
+      "types": "./dist/types/prerender/index.d.ts",
+      "react-server": "./src/prerender/index.ts",
+      "default": "./src/prerender/index.ts"
+    },
+    "./prerender/cloudflare": {
+      "types": "./dist/types/prerender/cloudflare.d.ts",
+      "react-server": "./src/prerender/cloudflare.ts",
+      "default": "./src/prerender/cloudflare.ts"
+    },
     "./vercel": {
       "types": "./dist/types/vercel/index.d.ts",
       "react-server": "./src/vercel/index.ts",
@@ -184,7 +194,7 @@
   },
   "dependencies": {
     "@types/debug": "^4.1.12",
-    "@vitejs/plugin-rsc": "^0.5.35",
+    "@vitejs/plugin-rsc": "^0.5.36",
     "debug": "^4.4.1",
     "magic-string": "^0.30.17",
     "picomatch": "^4.0.4",
@@ -208,7 +218,7 @@
     "jiti": "^2.7.0",
     "react": "^19.3.0",
     "react-dom": "^19.3.0",
-    "vitest": "^4.1.9",
+    "vitest": "^4.1.11",
     "@shared/e2e": "0.0.1"
   },
   "peerDependencies": {

package/skills/cache-guide/SKILL.md

@@ -302,25 +302,26 @@ local/dev behavior, not as proof that segment SWR is active.
 
 ## Key Differences
 
-|                      | `cache()` DSL                                         | `"use cache"` directive                                                             |
-| -------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------- |
-| **Scope**            | Route segment tree (handler + children + parallels)   | Single function return value                                                        |
-| **Defined at**       | Route definition site (`urls.ts`)                     | Inside function body or at file top                                                 |
-| **Cache key**        | Request type + host + pathname + params + search      | Function identity + serialized non-tainted args                                     |
-| **Execution on hit** | All-or-nothing: entire handler skipped                | Partial: function body skipped, calling code runs                                   |
-| **Runtime control**  | `condition` to disable, custom `key` function         | None — if the directive is present, it caches                                       |
-| **Side effects**     | Response side effects throw inside the boundary       | `ctx.headers.set()`, `ctx.set()`, etc. throw                                        |
-| **Handle data**      | Handler pushes replayed; loader pushes re-run live    | Captured and replayed when it receives `ctx`                                        |
-| **Loaders**          | Always fresh — excluded from cache, opt-in per loader | Can be used inside loaders                                                          |
-| **Nesting**          | Inner TTLs override; `key()` partitions compose       | Compose by calling cached functions from uncached; inner tags reach the outer entry |
+|                      | `cache()` DSL                                             | `"use cache"` directive                                                             |
+| -------------------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| **Scope**            | Route segment tree (handler + children + parallels)       | Single function return value                                                        |
+| **Defined at**       | Route definition site (`urls.ts`)                         | Inside function body or at file top                                                 |
+| **Cache key**        | Request type + router + host + pathname + params + search | Function identity + serialized non-tainted args                                     |
+| **Execution on hit** | All-or-nothing: entire handler skipped                    | Partial: function body skipped, calling code runs                                   |
+| **Runtime control**  | `condition` to disable, custom `key` function             | None — if the directive is present, it caches                                       |
+| **Side effects**     | Response side effects throw inside the boundary           | `ctx.headers.set()`, `ctx.set()`, etc. throw                                        |
+| **Handle data**      | Handler pushes replayed; loader pushes re-run live        | Captured and replayed when it receives `ctx`                                        |
+| **Loaders**          | Always fresh — excluded from cache, opt-in per loader     | Can be used inside loaders                                                          |
+| **Nesting**          | Inner TTLs override; `key()` partitions compose           | Compose by calling cached functions from uncached; inner tags reach the outer entry |
 
 ### cache() Cache Key
 
-The default key is `{requestType}:{host}{pathname}[:params][?search]`, where
-requestType is `doc`, `partial`, or `intercept`. The same URL is therefore cached
-separately for full document loads, client navigations, and intercept
+The default key is `{requestType}:{routerId}@{host}{pathname}[:params][?search]`,
+where requestType is `doc`, `partial`, or `intercept`. The same URL is therefore
+cached separately for full document loads, client navigations, and intercept
 navigations. The host keeps tenants apart when one deployment serves several
-domains; the search part is sorted, excludes the router's internal params, and
+domains, and the router id keeps two routers on one store apart when both
+serve the same host and path (see `/host-router`, "Shared cache store"); the search part is sorted, excludes the router's internal params, and
 honors `createRouter({ cache: { searchParams } })`.
 
 A custom `key` function replaces the whole default key (e.g., to key by user role
@@ -344,8 +345,8 @@ The key is `use-cache:{functionId}:{serializedArgs}` where functionId is a stabl
 ID from the Vite transform (module path + export name) and args are serialized
 (stable JSON when every arg is JSON-safe, RSC `encodeReply()` otherwise).
 Request-scoped arguments are excluded: route fields read off `ctx` (handler,
-loader or middleware: host, route name, pathname, params, search) and a
-`Request`'s URL are folded in, and `env`
+loader or middleware: router id, host, route name, pathname, params, search) and
+a `Request`'s URL are folded in, and `env`
 is left out. React element slots stay out of the key; any other argument that
 cannot be serialized (a function, a class instance) runs the call uncached. See
 `/use-cache`.

package/skills/caching/SKILL.md

@@ -164,9 +164,10 @@ cache(
 );
 ```
 
-- **Default key**: `{doc|partial|intercept}:{host}{pathname}[:params][?search]`
+- **Default key**: `{doc|partial|intercept}:{routerId}@{host}{pathname}[:params][?search]`
   — document requests, client navigations, and intercept navigations are cached
-  separately. The search part honors `cache.searchParams` (below).
+  separately, and so are two routers that share a store (see `/host-router`,
+  "Shared cache store"). The search part honors `cache.searchParams` (below).
 - **`key`** is a full override: it bypasses the default key, the store's
   `keyGenerator`, and the search-param filter. The result is stored
   namespaced (`key:` plus its URI encoding), so whatever it returns, request
@@ -300,8 +301,13 @@ is not stored after it. A `"use cache"` call, a stale entry's background
 refresh, a loader's own `cache()`, a route `cache()` render or a
 document-cache render that read its data before one of its tags was
 invalidated still returns what it read, but its store write is skipped:
-every store stamps an entry when it is written, so the old value would be
-served as newer than the invalidation. The next read runs it again. A
+the old value would be served as newer than the invalidation. The next read
+runs it again. A write that gets through anyway (another colo's marker not
+visible yet) is still rejected on later reads by `CFCacheStore` with KV, which
+stamps an entry with the start of the execution that produced it, not its
+write time; `MemorySegmentCacheStore` refuses such a write. `VercelCacheStore`
+and `CFCacheStore` L1 hits in purge mode or without KV read no marker for
+data, so the write gate is their only guard across requests. A
 `"use cache"` call already running when one of its tags is invalidated is
 not joined by later calls either. Its tags include those of the
 `"use cache"` functions it calls. Another isolate's invalidation is caught
@@ -523,6 +529,24 @@ already expressible with `cache({ key })`.
 | `CFCacheStore`            | `@rangojs/router/cache` | Cloudflare Workers (Cache API L1 + optional KV L2) |
 | `VercelCacheStore`        | `@rangojs/router/cache` | Vercel Functions (Vercel Runtime Cache)            |
 
+### Filling a cache before traffic
+
+Every cache above fills from the first request that misses. To pay that
+render before a visitor does (after a deploy, after an `updateTag()`), warm
+the URL: `router.prerender({ env, ctx })(url)` sends it through the router's
+handler in a mode where every cache read misses and every write replaces the
+entry, so the route's `ppr` shell, `cache()` records, `"use cache"` results,
+loader caches and document cache entry are rewritten under the keys a
+visitor reads, with the old entries serving until then. See `/prerender` →
+"Warm any route before traffic".
+
+A warm only writes to a store that is shared beyond the place the call runs.
+Each store says where its entries can be read (`scope`): `CFCacheStore` with
+`kv` is `"global"`, without `kv` `"local"`; `VercelCacheStore` is `"regional"`
+(a warm fills the region it runs in); `MemorySegmentCacheStore` is `"local"`
+(refused in production, allowed under the dev server; a single-process server
+opts in with `new MemorySegmentCacheStore({ scope: "global" })`).
+
 ### Memory Store
 
 For development, tests, and single-instance deployments. Entries live in
@@ -535,6 +559,7 @@ const store = new MemorySegmentCacheStore({
   defaults: { ttl: 60 }, // segments ignore swr on this store
   maxEntries: 1000, // per-family FIFO cap (default 1000)
   name: "app", // optional: keep entries across Vite HMR module reloads
+  scope: "local", // default; "global" only when ONE process serves the app (see /prerender warming)
 });
 ```
 
@@ -1094,6 +1119,17 @@ A per-boundary store becomes reachable by `updateTag()`/`revalidateTag()` only
 once that boundary has been matched in the current process. For data you
 invalidate by tag, prefer the app-level store.
 
+A store you implement declares where its entries can be read, or
+`router.prerender()` refuses to warm into it (a store that declares nothing is
+treated as `"local"`):
+
+```typescript
+const store: SegmentCacheStore = {
+  scope: "global", // every location reads the same entries; or "regional"
+  // get, set, delete, ...
+};
+```
+
 If you implement `SegmentCacheStore` yourself, `invalidateTags(tags)` is called
 synchronously inside the invalidating request, and `revalidateTag()` does not
 await it. For that request to read its own writes, record the tags and the

package/skills/catalog.json

@@ -185,7 +185,7 @@
     },
     {
       "name": "prerender",
-      "description": "Pre-render route segments at build time with Prerender (with getParams), Passthrough live fallback, Static segments, and Skip. Use when a page's content is mostly static and shouldn't render on every request, speeding up cold responses, reading build-only data (files, build env), or deciding which routes to prerender vs render live.",
+      "description": "Pre-render route segments at build time with Prerender (with getParams), Passthrough live fallback, Static segments, and Skip, refresh them from a running app with on-demand prerender (Prerender onDemand + router.prerender, ISR-style), and warm any other route's runtime caches (ppr shell, cache(), \"use cache\", document cache) before traffic with the same router.prerender. Use when a page's content is mostly static and shouldn't render on every request, speeding up cold responses, reading build-only data (files, build env), refreshing one page from a webhook, cron or queue without a redeploy, removing a deleted item's page (prerender.remove, or notFound() in a refresh), making routes ready after a deploy or an updateTag so no visitor pays the first render, or deciding which routes to prerender vs render live.",
       "argumentHint": "[passthrough]",
       "path": "skills/prerender/SKILL.md"
     },

package/skills/cloudflare/SKILL.md

@@ -184,6 +184,137 @@ keeps serving a purged shell until `memo.shellMs` passes. Set
 user's next request; cross-colo KV propagation (and `tagCacheTtl`) still
 applies. Details: `/caching` → "The fresh-reads cookie".
 
+## On-demand prerender on Workers
+
+A `Prerender(..., { onDemand })` route (`/prerender` → "On-demand refresh")
+needs a durable store for its refreshed entries. On Workers that is KV:
+
+```typescript
+import { createKVPrerenderStore } from "@rangojs/router/prerender/cloudflare";
+
+export const router = createRouter<AppBindings>({
+  document: Document,
+  urls: urlpatterns,
+  prerender: (env) => ({
+    store: createKVPrerenderStore(env.PRERENDER_KV),
+    ttl: 3600, // soft: a stale entry still serves
+    // Present = stale-while-revalidate: a stale hit schedules this via waitUntil.
+    onRevalidate: (target, liveEnv) => liveEnv.PRERENDER_QUEUE.send({ target }),
+  }),
+});
+```
+
+Add the `PRERENDER_KV` namespace (and the queue, if you use one) to
+`wrangler.jsonc` and to `AppBindings`. Refreshes run from the Worker's other
+handlers, with the live `env`:
+
+```typescript
+export default {
+  fetch: (request: Request, env: AppBindings, ctx: ExecutionContext) =>
+    router.fetch(request, { env, ctx }),
+
+  // Cron sweep: re-render only what went stale.
+  async scheduled(
+    _event: ScheduledEvent,
+    env: AppBindings,
+    ctx: ExecutionContext,
+  ) {
+    const ids = await env.CMS.listProductIds();
+    const prerender = router.prerender({ env, ctx });
+    ctx.waitUntil(
+      prerender.many(
+        ids.map((id) => ({ route: "products.detail", params: { id } })),
+        { concurrency: 4, onlyIfStale: true },
+      ),
+    );
+  },
+
+  // Queue consumer: the queue owns dedup across isolates. onlyIfStale: a
+  // message can run after another one refreshed the page, or after
+  // prerender.remove() removed it; then it renders nothing.
+  async queue(
+    batch: MessageBatch<{ target: PrerenderTargetObject }>,
+    env: AppBindings,
+    ctx: ExecutionContext,
+  ) {
+    const targets = batch.messages.map((m) => m.body.target);
+    ctx.waitUntil(
+      router
+        .prerender({ env, ctx })
+        .many(targets, { concurrency: 8, onlyIfStale: true }),
+    );
+  },
+};
+```
+
+`PrerenderTargetObject` comes from `@rangojs/router/prerender`. It is what
+`onRevalidate` receives, and the `router.prerender({ env, ctx })` runner (and its
+`.many()`) accepts it as is on a router typed with named routes. A queue hands it back as JSON, so type the
+message body with it (as above) or assert it: `JSON.parse(raw) as
+PrerenderTargetObject`.
+
+The KV store writes no `expirationTtl` (entries never expire; `ttl` is soft)
+and keys entries by router id and the router's data version, so a deploy that
+changes server code starts from the build entries again.
+`router.prerender({ env, ctx }).markStale(tags)` writes per-tag markers under
+`__rango_pr_tag__/{encoded routerId}/`, a namespace separate from `updateTag()`'s and
+scoped to the router that marked (routers sharing one KV namespace do not mark
+each other's entries); a read checks one marker per tag on the entry,
+uncached, so keep tag counts small. Markers have no expiry (`/prerender` ->
+"KV tag markers"). Neither `updateTag()` nor `revalidateTag()` reaches this
+store.
+
+## Warm routes on Workers
+
+`router.prerender()` also warms a route that is not on-demand: its `ppr`
+shell, `cache()` records, `"use cache"` results and document cache entry are
+rewritten before a visitor asks (`/prerender` → "Warm any route before
+traffic"). On Workers:
+
+- **`CFCacheStore` needs `kv`.** With KV the store is shared by every colo
+  (`scope: "global"`) and a warm is allowed; without it entries live in one
+  colo's Cache API and the call returns `skipped-store-not-shared`.
+- **Give `scheduled` and `queue` an origin.** Cache keys carry the host, and
+  those handlers have no request to take it from:
+
+  ```typescript
+  async scheduled(_event: ScheduledEvent, env: AppBindings, ctx: ExecutionContext) {
+    const prerender = router.prerender({
+      env,
+      ctx,
+      origin: "https://shop.example",
+    });
+    ctx.waitUntil(prerender.many(["/", "/products/1"], { onlyIfStale: true }));
+  },
+  ```
+
+  A webhook route or a server action needs none: the warm uses the origin of
+  the request it is called from.
+
+- **A warm fills the colo it runs in, and KV.** Another colo that already
+  holds its own Cache API copy keeps serving it until it expires; an L1 hit
+  never consults KV. After a deploy no colo holds a copy, so the warm's KV
+  entry is what each one reads next. For a content change, invalidate and then
+  warm, in this order:
+
+  ```typescript
+  await updateTag(`product:${id}`); // no colo serves the old copy any more
+  await router.prerender({ env, ctx })(`/products/${id}`); // writes the new one
+  ```
+
+  A colo with no copy of its own reads the warmed entry from KV. A colo that
+  was still holding the old copy treats it as a miss and renders once for
+  itself (it does not read the fresher KV entry). With `tagPurge` the purge
+  evicts every colo's copy, so they all read the warmed entry.
+
+- **Entries under 60 seconds stay in one colo.** KV's minimum `expirationTtl`
+  is 60 s, so a segment, item or response entry whose `ttl + swr` is shorter
+  is written to the Cache API only, and a warm of it reaches the calling colo
+  alone. Shells always reach KV.
+- **KV writes take time to spread.** Cloudflare documents up to 60 seconds or
+  more before a write is visible in other locations; a visitor elsewhere in
+  that window renders the page as before.
+
 ## Tracing on Workers
 
 `createCloudflareTracing()` from `@rangojs/router/cloudflare` emits the

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

@@ -755,7 +755,7 @@ applications do not have to remember to mark every context manually.
 
 For a `"use cache"` function, a tainted context object is not serialized wholesale
 into the cache key. Rango instead extracts the safe identity dimensions that make
-the call reusable without collisions: host, route name, pathname, params, response
+the call reusable without collisions: router, host, route name, pathname, params, response
 type, and normalized user-facing search params. A shared cached function called
 from two hosts, route scopes, param sets, or query variants therefore does not
 collapse into one entry just because both calls received a `ctx` object.

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

@@ -97,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

@@ -40,10 +40,9 @@ bake into the shell. See `/loader` → "Writing Handles from Loaders". `useHandl
 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, then takes whatever arrived since. That holds wherever the
-reader sits: a reader inside a `<Suspense>` or `loading()` boundary, which
-hydrates after the rest of the page, does not see a late loader push during
-its hydration render, so it cannot mismatch its server HTML.
+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:
 

package/skills/hooks/navigation.md

@@ -166,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

@@ -251,9 +251,9 @@ 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
+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
@@ -342,7 +342,8 @@ development.
 
 Location state lives in the browser, so the server renders a document without
 it. `useLocationState` therefore hydrates as `undefined` and applies the stored
-value right after. For most state that is invisible. For state that decides
+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

package/skills/host-router/SKILL.md

@@ -383,3 +383,21 @@ Each `createRouter()` app has its own cache version, computed by `vite build` fr
 | 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/loader/SKILL.md

@@ -662,9 +662,11 @@ HIT".
 
 ### Cache Key
 
-The default cache key is `loader:{loaderId}:{host}{pathname}:{sortedParams}`
-(the host keeps multi-tenant hosts from sharing entries). This can be customized
-at two levels:
+The default cache key is
+`loader:{loaderId}:{routerId}@{host}{pathname}:{sortedParams}`: the host keeps
+multi-tenant hosts from sharing entries, and the router id keeps two routers
+that mount the loader on one store apart (see `/host-router`, "Shared cache
+store"). This can be customized at two levels:
 
 ```typescript
 import { cookies } from "@rangojs/router";
@@ -688,7 +690,7 @@ Resolution priority (same order as route-level `cache()`):
    `loader:{loaderId}:key:` plus the result's URI encoding
 2. `store.keyGenerator(ctx, defaultKey)` — store-level modification, stored
    as returned
-3. Default key — `loader:{loaderId}:{host}{pathname}:{sortedParams}`
+3. Default key — `loader:{loaderId}:{routerId}@{host}{pathname}:{sortedParams}`
 
 Because the `key()` result is namespaced by the loader id, no value it
 returns, request input included, can name another loader's entry or a

package/skills/middleware/SKILL.md

@@ -426,7 +426,7 @@ 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.
+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. The client follows at most 20 redirects in one navigation; a loop (two pages redirecting to each other) stops there with the error boundary and a `[rango] Server redirect loop` console error.
 
 ## Authentication Middleware