@rangojs/router 0.20.0 → 0.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "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",
@@ -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": {
@@ -217,7 +227,6 @@
     "@playwright/test": "^1.49.1",
     "@testing-library/react": ">=16",
     "@vercel/functions": "^3.0.0",
-    "@vitejs/plugin-rsc": "^0.5.35",
     "react": ">=19.2.8 <20",
     "react-dom": ">=19.2.8 <20",
     "vite": "^8.0.16",

package/skills/cache-guide/SKILL.md

@@ -166,24 +166,87 @@ exemption there). The route then serves uncached; see `/ppr`.
 
 ### Cross-deploy safety: version-segmented store keys
 
-`CFCacheStore` prefixes every **physical** store key (the CF Cache API URL and
-the KV key) with the build version — auto-generated from the
-`@rangojs/router:version` virtual module, overridable via the store's `version`
-option. A new deploy reads under a new prefix, so it can **never** read a
-previous build's entries: no cross-deploy shape drift, and no dead client-chunk
-references baked into cached RSC.
-
-The tradeoff to know: **loader/data caches use the same store**, so they're
-version-segmented too. Every deploy is therefore a _cold data cache_ — SWR can't
-soften it, because no stale entry exists under the new key. For high-traffic,
-frequently-deploying, data-bound apps that's a deploy-time origin warm-up. Decide
-deliberately: accept it (correctness over hit-rate), or split the policy — let
-the render/edge cache auto-version while a separate data store gets a stable
-`version` so its entries survive deploys. (Per-process stores like
-`MemorySegmentCacheStore` are cold on every restart anyway; this matters for
-persistent stores.) `VercelCacheStore` does not version automatically: pass a
-per-deploy `getCache({ namespace })` or its `version` option (see `/vercel`).
-See `/caching` for store setup.
+`CFCacheStore` and `VercelCacheStore` prefix every **physical** store key with a
+version, so a build only reads entries that code like its own wrote. The version
+is a hash of the code, computed per `createRouter()` by `vite build`, not the
+build time. Each router has two:
+
+- The **data version** (a hash of the router's server code) keys cached RSC
+  data: segment entries from `cache()`, `"use cache"` values, loader data.
+- The **document version** (the data version plus the SSR output, the client
+  asset file names, `base`, and the router's `Prerender` payloads) keys stored
+  HTML (PPR shells, document-cache responses). It is also sent to the browser,
+  and a mismatch with the tab's `_rsc_v` reloads the tab.
+
+Same code builds to the same versions, so a rebuild or redeploy of unchanged
+code keeps the cache, and a deploy that changes app A keeps app B's cache.
+
+| 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 |
+
+"Server code" is everything the app's server can run: its own modules, the
+dependencies it imports (bundled, or on the node preset left external and
+resolved from `node_modules`), and a stylesheet its server code links
+(`import "./x.css"` in a server component, or `import href from "./x.css?url"`
+for a document `<link>`): the stylesheet's hashed URL is in what the server
+renders, so a change to the compiled CSS clears that app's cached data. A
+`clientUrls()` module is client code that also tells the server what to run:
+changing which loaders a route declares, its `loading` or its transition
+counts as a server change; changing the components it renders does not. Under
+a host router, apps are independent when the host mounts them lazily
+(`.lazy(() => import(...))`); routers one module imports statically share
+that module's code.
+
+The key families: `CFCacheStore` keys segment entries and `fn:` items with the
+data version and `doc:` responses and `shell2:` shells with the document
+version. `VercelCacheStore` does the same by default (families `s`, `i` data;
+`r`, `h` document). `MemorySegmentCacheStore` has no version; the process is its
+scope.
+
+Tag invalidation markers are stored without a version, so `updateTag()` and
+`revalidateTag()` apply to entries of every version, including a version that
+comes back in a rollback.
+
+- **Force a clear:** change `version` (`createRouter({ version })`,
+  `createRSCHandler({ version })`, `new CFCacheStore({ version })` or
+  `new VercelCacheStore({ version })` all use that exact value for both
+  versions), or invalidate tags.
+- **Keep the old "every deploy clears the cache" behavior:** set `version` to a
+  per-deploy value (a build id), or on Vercel keep a deployment-scoped
+  `getCache({ namespace: process.env.VERCEL_DEPLOYMENT_ID })`.
+- **Separate environments:** two deployments built from the same code have the
+  same versions. If they share a store (the same KV namespace), they share
+  entries. Give each environment its own KV namespace or cache namespace, or its
+  own `version`.
+
+Two things give a router a new version on every build, and with it a cold
+cache on every deploy:
+
+- **No stable encryption key.** The key that encrypts inline server-action
+  bound arguments is part of the version of every router whose code encrypts
+  with it. Pass `rango({ encryptionKey: process.env.RANGO_ENCRYPTION_KEY })`
+  (see `/use-cache`); the build prints a note when a router needs it.
+- **A `Prerender` or `Static()` handler whose output differs per build**: a
+  timestamp, a random id, or an inline action with bound arguments rendered at
+  build time (its arguments are encrypted with a random IV, stable key or not).
+- **An import the server build leaves external and cannot read**: a package
+  that is not in `node_modules` at build time, a path that does not resolve, a
+  URL. The build names it.
+
+Every build prints each router's versions and writes what they were computed
+from to `node_modules/.rangojs-router-build/cache-versions.json`. Diff that
+file between two builds to see which chunk or payload moved a version; its
+`unownedFiles` lists the server files in no router's version (the host entry
+of lazily mounted apps), where a change keeps every app's cache.
+
+A custom persistent store keys the same way with `getCacheVersions()` from
+`@rangojs/router/cache`, called per operation inside the request: `data` for
+segment entries and items, `document` for responses and shells, no version on
+its tag-invalidation records. See `/caching` for store setup.
 
 ### Client cache: forward/back is mutation-aware
 
@@ -226,8 +289,9 @@ recompute for a merely-aging entry.
   `/document-cache`. A platform CDN may independently consume the same header
   and bypass the function on hits; see `/deployment-caching`.
 
-SWR softens normal TTL expiry, **not** a cross-deploy cold cache — a new build
-has no stale entry to serve (see version-segmented store keys above).
+SWR softens normal TTL expiry, **not** a version change — a deploy that changes
+a router's code reads under a new version and has no stale entry to serve (see
+version-segmented store keys above).
 
 Store support is layer-specific. `CFCacheStore` and `VercelCacheStore` support
 SWR for segment, document/response, item (`"use cache"` and cached loaders), and
@@ -238,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
@@ -280,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)
 });
 ```
 
@@ -564,9 +589,13 @@ const router = createRouter<AppBindings>({
 });
 ```
 
-`CFCacheStore` prefixes every key with the build version, so a deploy never
-reads the previous build's entries (override with `version`). See `/cache-guide`
-→ "Cross-deploy safety" and `/cloudflare` for bindings.
+`CFCacheStore` prefixes every key with a version computed per `createRouter()`
+from that router's built code: segment entries and `fn:` items with the data
+version, `doc:` responses and `shell2:` shells with the document version. A
+deploy that changes a router's code reads under a new version; a deploy that does
+not keeps the entries. Tag invalidation markers carry no version, so `updateTag()`
+reaches entries of every version. `version` replaces both versions with one
+value. See `/cache-guide` → "Cross-deploy safety" and `/cloudflare` for bindings.
 
 ### With KV L2 Persistence
 
@@ -755,10 +784,11 @@ the store adds SWR, tag invalidation, and the family split on top of it.
 import { getCache, waitUntil } from "@vercel/functions";
 import { VercelCacheStore } from "@rangojs/router/cache";
 
-// A per-deploy namespace: Vercel does not reconcile entries across deploys.
+// No deployment id in the namespace: the store versions its keys itself, so a
+// deploy that does not change a router keeps that router's entries.
 // One handle per process: the store keeps its PPR shell and tag-marker
 // memos per handle.
-const runtimeCache = getCache({ namespace: process.env.VERCEL_DEPLOYMENT_ID });
+const runtimeCache = getCache();
 
 const router = createRouter({
   document: Document,
@@ -794,6 +824,12 @@ beyond the per-item cap are dropped with a warning. The official client swallows
 `expireTag` failures, so treat `updateTag()` on Vercel as best-effort. See
 `/vercel` for the preset and the remaining options (`version`, `name`, `debug`).
 
+`VercelCacheStore` versions its keys by default: families `s` and `i` take the
+router's data version, `r` and `h` its document version, and tag markers
+(`rg:tm:{tag}`) take none. `version` replaces both. To clear the cache on every
+deploy, set `version` to a per-deploy value or keep a deployment-scoped
+`getCache({ namespace: process.env.VERCEL_DEPLOYMENT_ID })`.
+
 ## Cache purity & tainted objects
 
 A `cache()` boundary caches everything except loaders, so anything read inside a
@@ -1083,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/client-urls/SKILL.md

@@ -376,6 +376,22 @@ a hard load of the target URL renders the full route.
   throwers in the client `ErrorBoundary`; `useFetchLoader` works unchanged
   (route-independent lane; `revalidate()` deliberately not consulted).
   Pinned in the router repo's client-urls hook-probe e2e.
+- **Location state follows the same split as the route hooks.** Inside the
+  optimistic branch (the destination and the group's client layouts)
+  `useLocationState` reads the state the navigation carries (`<Link state>`,
+  `router.push(url, { state })`) from the first optimistic render, before the
+  server answers: a product page can show the name its link carried while
+  its loader streams. Chrome outside the group, and content a navigation
+  keeps on screen (a same-route navigation, a destination that suspends with
+  no boundary), keep the committed entry's state until the canonical commit.
+  State a redirect carries arrives with that commit (an action's
+  `setLocationState` without a redirect is applied when its response
+  arrives), and a navigation that is superseded or cancelled leaves none
+  behind. A `flash` slot read in the branch is cleared from history once the
+  navigation commits, not before. In the branch the value is the object the
+  navigation passed; from the commit on it is the entry's copy (a structured
+  clone), so an object-valued slot is a new, equal object at that point.
+  Do not key an effect on its identity across the two.
 - **Editing the module in dev:** projections refresh via HMR discovery; if a
   route-shape edit ever serves stale routes, restart dev — and if you are
   developing the router itself, rebuild the router dist before `pnpm dev`

package/skills/cloudflare/SKILL.md

@@ -48,7 +48,8 @@ export default defineConfig({
 Worker runs the RSC entry and loads SSR inside the same isolate.
 
 `buildEnv: "auto"` gives `Prerender` and `Static` handlers a real `ctx.env` at
-build time through Wrangler's `getPlatformProxy()` (local bindings). Omit it
+build time through Wrangler's `getPlatformProxy()` (local bindings), reading
+the wrangler config from the Vite root whatever the working directory. Omit it
 (default `false`) when build-time rendering must not touch bindings; `ctx.env`
 then throws during build rendering. See `/prerender`.
 
@@ -183,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

@@ -57,7 +57,7 @@ and multi-region composition without replacing its routing or data model.
 | Middleware              | Global + segment-scoped subtree                                                                            | Single root Proxy (matcher filters paths); no subtree scope                    | Request/server-function middleware                                                 | [Hono middleware + handler interceptors](https://waku.gg/#interceptors) |
 | Observability           | Built-in CF + Vercel OTel phase spans, `Server-Timing`, perf waterfall                                     | Built-in OTel spans; no equivalent router-phase waterfall                      | Client/data devtools                                                               | No equivalent built-in phase model                                      |
 | Deploy targets          | Node, Cloudflare, Vercel — all with presets                                                                | Node/Vercel first; other platforms through adapters                            | Broad Vite/Rsbuild runtime support                                                 | Node plus adapters                                                      |
-| Deployment skew         | Automatic build-version handshake for navigation, prefetch, and actions; safe reload on mismatch           | `deploymentId` mismatch reload; Vercel can pin clients to an immutable deploy  | Application/platform policy                                                        | Build-id mismatch reload (v1.0-beta)                                    |
+| Deployment skew         | Automatic version handshake for navigation, prefetch, and actions; safe reload on mismatch                 | `deploymentId` mismatch reload; Vercel can pin clients to an immutable deploy  | Application/platform policy                                                        | Build-id mismatch reload (v1.0-beta)                                    |
 | Multi-tenant            | `createHostRouter()` built-in                                                                              | Roll your own                                                                  | Roll your own                                                                      | Roll your own                                                           |
 | Testing primitives      | Ships `@rangojs/router/testing` (handlers/loaders/mw/Flight/e2e)                                           | No comparable handler/Flight primitives                                        | Documented patterns; no shipped utils                                              | No comparable handler/Flight primitives                                 |
 | Client runtime          | ~50 KB Rango + ~115 KB React/RSC, per-route chunks                                                         | Configuration-dependent                                                        | Configuration-dependent                                                            | Deliberately light                                                      |
@@ -336,8 +336,9 @@ first-class primitive.
 
 ### Deployment skew is detected before stale code executes
 
-The Vite plugin generates a build version and injects it into the RSC handler and
-initial payload. The browser returns that version on every partial navigation,
+`vite build` computes a document version per `createRouter()` from that router's
+built code (the server code, the SSR output, the client asset file names, `base`,
+and its Prerender payloads) and ships it in the initial payload metadata. The browser returns that version on every partial navigation,
 prefetch, and Server Action. If an old tab reaches a newer server, request
 classification detects the mismatch before resolving the route or executing the
 action and responds with `X-RSC-Reload`. The browser then performs a clean document
@@ -348,13 +349,16 @@ falling through to a misleading 404.
 The protection covers fresh, completed-prefetch, and in-flight-prefetch responses.
 For action requests, the reload returns to the same-origin referrer rather than the
 internal action URL. The cache side follows the same correctness rule:
-`CFCacheStore` automatically versions its physical Cache API and KV keys, so a new
-build cannot replay Flight containing an old component shape or dead client-chunk
-reference. `VercelCacheStore` exposes the same version segmentation, but — unlike
-`CFCacheStore` — does not default `version` to the build version: skew safety is
-opt-in via the `version` option or the recommended deployment-specific Runtime
-Cache namespace. The browser's Rango state also includes
-the build version, rotating HTTP and in-memory prefetch cache identity on boot.
+`CFCacheStore` and `VercelCacheStore` automatically version their physical keys
+(Cache API and KV keys on Cloudflare): cached RSC data (segment entries, `"use
+cache"` values, loader data) by a data version, a hash of the router's server
+code, and stored HTML (PPR shells, document-cache responses) by the document
+version. A build whose router code changed cannot replay Flight containing an old
+component shape or dead client-chunk reference, and a rebuild of unchanged code
+keeps its cache. Tag invalidation markers carry no version, so `updateTag()`
+reaches entries of every version. The `version` option replaces both versions.
+The browser's Rango state also includes the document version, rotating HTTP and
+in-memory prefetch cache identity on boot.
 
 Next.js deserves explicit credit here: its
 [`deploymentId`](https://nextjs.org/docs/app/api-reference/config/next-config-js/deploymentId)
@@ -587,10 +591,10 @@ dropped rather than warmed. `useLinkStatus()` exposes `{ pending }` for the owni
 link.
 
 **Rango State ties prefetch and client-cache invalidation together.** It is a
-session-cookie value shaped as `{buildVersion}:{invalidationTimestamp}`. Navigation
+session-cookie value shaped as `{documentVersion}:{invalidationTimestamp}`. Navigation
 and prefetch requests send it as `X-Rango-State`, and RSC responses vary on that
 header, so the browser HTTP cache and Rango's decoded prefetch map share one cache
-identity. A deployment changes the version; a mutation rotates the timestamp. Old
+identity. A deployment that changes the router's code or client assets changes the version; a mutation rotates the timestamp. Old
 responses become unreachable under the retired identity instead of requiring every
 cache layer to delete the same entries successfully.
 
@@ -751,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.