@rangojs/router 0.25.0 → 0.26.1

package/dist/types/urls/pattern-types.d.ts

@@ -60,12 +60,13 @@ export interface PartialPrerenderProps {
     /**
      * Upper bound (serialized UTF-8 bytes) on the loader pins in the capture
      * data snapshot: the bake-lane loader records. The doc record (the handler
-     * layer every HIT replays) is exempt. Over the cap the pins are dropped: the
-     * shell is still stored and every HIT still replays the handler layer, but the
-     * pinned loaders read the live store, so drifted cached content can
-     * hydration-mismatch and be repaired client-side. Reported once per key.
-     * Defaults to 8 MiB. The whole entry is bounded separately by the store's
-     * value limit (Cloudflare KV: 25 MiB); an entry over it is refused.
+     * layer every HIT replays) is exempt. A document HIT is served only from an
+     * entry that holds a pin for every `ssr: false` loader its HTML baked, so
+     * over the cap no document shell is stored: documents render in full
+     * (MISS), and client navigations still replay the handler layer and run
+     * those loaders fresh. Reported once per key. Defaults to 8 MiB. The whole
+     * entry is bounded separately by the store's value limit (Cloudflare KV:
+     * 25 MiB); an entry over it is refused.
      */
     maxSnapshotBytes?: number;
     /**

package/dist/vite/index.js

@@ -7068,8 +7068,7 @@ var DEFAULT_ROUTER_VERSIONS_KEY = "*";
 function uniformVersions(version) {
   return { data: version, document: version };
 }
-function resolveVersionsFrom(table, routerId2, override) {
-  if (override !== void 0) return uniformVersions(override);
+function resolveVersionsFrom(table, routerId2) {
   if (!table) return void 0;
   const pair = (routerId2 !== void 0 && Object.hasOwn(table, routerId2) ? table[routerId2] : void 0) ?? table[DEFAULT_ROUTER_VERSIONS_KEY];
   return pair ? { data: pair[0], document: pair[1] } : void 0;
@@ -7078,7 +7077,7 @@ function resolveVersionsFrom(table, routerId2, override) {
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.25.0",
+  version: "0.26.1",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -12257,11 +12256,7 @@ async function runShellPrerenderPhase(s, builder, versionsTable) {
       const mismatches = [];
       for (const [routerId2, routerInstance] of registry) {
         if (typeof routerInstance.match !== "function") continue;
-        const versions = resolveVersionsFrom(
-          versionsTable,
-          routerId2,
-          routerInstance.version
-        );
+        const versions = resolveVersionsFrom(versionsTable, routerId2);
         try {
           const res = await captureMod.captureShellForBuild({
             router: routerInstance,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.25.0",
+  "version": "0.26.1",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/skills/cache-guide/SKILL.md

@@ -211,17 +211,13 @@ 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
+- **Force a clear:** invalidate tags, or change the router's server code. There
+  is no `version` setting; the build versions are the only ones.
+- **Clear on every deploy:** 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`.
+  entries. Give each environment its own KV namespace or cache namespace.
 
 Two things give a router a new version on every build, and with it a cold
 cache on every deploy:

package/skills/caching/SKILL.md

@@ -616,8 +616,7 @@ 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.
+reaches entries of every version. See `/cache-guide` → "Cross-deploy safety" and `/cloudflare` for bindings.
 
 ### With KV L2 Persistence
 
@@ -859,12 +858,11 @@ global, so they read fresh in any region.
 Writes over 2 MB (the platform limit, `maxItemBytes`) are skipped, and tags
 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`).
+`/vercel` for the preset and the remaining options (`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
+(`rg:tm:{tag}`) take none. To clear the cache on every deploy, keep a deployment-scoped
 `getCache({ namespace: process.env.VERCEL_DEPLOYMENT_ID })`.
 
 ## Cache purity & tainted objects

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

@@ -356,7 +356,7 @@ 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.
+reaches entries of every version.
 The browser's Rango state also includes the document version, rotating HTTP and
 in-memory prefetch cache identity on boot.
 

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

@@ -46,12 +46,12 @@ belongs to the segment that pushed it and reaches `useHandle` when that push
 settles. The page never waits for a handle, and a handle never shows the next
 page's values over the page being left:
 
-| Case                                                                                                                                       | What `useHandle` returns                                                                                                                |
-| ------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
-| Document load                                                                                                                              | The values the HTML was rendered from. `push(promise)` and `.defer()` are awaited during SSR, so the document ships the resolved value. |
-| Navigation to a page that commits at once (a cold click that mounts new segments)                                                          | The destination's values, in the page's commit; the page's effects read them                                                            |
-| Navigation to a page React holds in a transition (`transition()`, same-route search change, fully prefetched click, a handler that awaits) | The page being left keeps its values; the destination's land in the commit right after the page, in the same task, before paint         |
-| `push(promise)` or `.defer()` on a client navigation                                                                                       | The previous value, then the new one when the promise resolves, possibly well after the page                                            |
+| Case                                                                                                                                       | What `useHandle` returns                                                                                                                                                                                                                                                                                                     |
+| ------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Document load                                                                                                                              | The values the HTML was rendered from. `push(promise)` and `.defer()` are awaited during SSR, so the document ships the resolved value. On a `ppr` shell HIT that holds for the handlers' and the `ssr: false` loaders' pushes, which the shell baked; a live-lane loader's push arrives right after hydration (see `/ppr`). |
+| Navigation to a page that commits at once (a cold click that mounts new segments)                                                          | The destination's values, in the page's commit; the page's effects read them                                                                                                                                                                                                                                                 |
+| Navigation to a page React holds in a transition (`transition()`, same-route search change, fully prefetched click, a handler that awaits) | The page being left keeps its values; the destination's land in the commit right after the page, in the same task, before paint                                                                                                                                                                                              |
+| `push(promise)` or `.defer()` on a client navigation                                                                                       | The previous value, then the new one when the promise resolves, possibly well after the page                                                                                                                                                                                                                                 |
 
 You never see a pending value, a blank, or the destination's title over the old
 page. A crumb whose `content` is a promise read with `use()` in `<Suspense>`

package/skills/host-router/SKILL.md

@@ -382,7 +382,7 @@ Each `createRouter()` app has its own cache version, computed by `vite build` fr
 | 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`.
+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, invalidate its tags. See `/cache-guide`.
 
 ## Shared cache store
 

package/skills/loader/SKILL.md

@@ -668,12 +668,13 @@ rejects) skips the whole entry, as above. Entries written
 before handles were recorded replay none until they are rewritten (expiry or
 SWR revalidation).
 
-On a `ppr` route the shell keeps a copy of an `ssr: false` loader's settled
-pushes too. The two never disagree on the page: where a replay of the shell
-serves the loader's data from the shell, the shell's copy is the one shown
-and the entry only adds the deferred push the shell could not keep; where it
-does not (the loader runs or reads its entry), the entry's pushes take the
-shell copy's place, none if the entry recorded none. See `/ppr` → "On a shell
+On a `ppr` route the shell keeps a copy of an `ssr: false` loader's pushes
+too, a pushed promise resolved (#1182). The two never disagree on the page:
+where a replay of the shell serves the loader's data from the shell, the
+shell's copy is the one shown and the entry only adds a push whose value
+holds a promise, which the shell could not keep; where it does not (the
+loader runs or reads its entry), the entry's pushes take the shell copy's
+place, none if the entry recorded none. See `/ppr` → "Handles on a shell
 HIT".
 
 ### Cache Key
@@ -1040,9 +1041,9 @@ handler reserved with `.defer()` instead (`/breadcrumbs`, "Deferred content").
 
 Under `cache()`, loader pushes are not stored with the cached segments: the
 loader re-runs on every hit and its live push is the only copy. (`ppr` keeps
-the settled pushes of an `ssr: false` loader, and of the loaders it awaits, in
-the shell, and a promise-free `ssr: false` loader does not run on a shell HIT —
-see `/ppr`.)
+the pushes of an `ssr: false` loader, and of the loaders it awaits, in the
+shell, a pushed promise resolved, and a promise-free `ssr: false` loader does
+not run on a shell HIT — see `/ppr`.)
 
 Reads are the other direction and gated: `ctx.get(handle)` throws unless the
 loader first does `await ctx.rendered()` (DSL-registered loaders only —

package/skills/ppr/SKILL.md

@@ -372,7 +372,8 @@ replay its eligible snapshot. In both cases `matchPartial()`:
 - runs live DSL loaders fresh with their normal `loading()` streaming
   behavior, and serves bake-lane loaders from the pins of a shell captured by a
   document request; a snapshot captured by a navigation alone carries no pins,
-  and its replay runs them fresh (see below);
+  nor does the navigation-only entry a capture over `ppr.maxSnapshotBytes`
+  stores, and their replay runs them fresh (see below);
 - keeps the existing prefetch key, source scope, and in-flight lock unchanged.
 
 This is deliberately invisible to the browser: the response is the same
@@ -382,8 +383,9 @@ snapshot is a shell a document request captured, as on a document HIT: a
 promise-free `ssr: false` loader is served from its pin without running
 (unless the capture marked it to run: see "On a shell HIT"), and one whose
 return holds promises runs with its baked parts overlaid. A snapshot captured
-by a navigation alone carries no pins, and its replay runs them fresh. Loaders
-without `ssr: false` stay live.
+by a navigation alone carries no pins, nor does an entry over
+`ppr.maxSnapshotBytes`, and its replay runs them fresh. Loaders without
+`ssr: false` stay live.
 
 A route's own `cache()` scope — including one inherited from an ancestor, the
 common app-wide storefront shape — COMPOSES with replay instead of disabling
@@ -836,14 +838,17 @@ that settled inside the capture window pinned its capture-time value into the
 shared shell; found live as a storefront basket — with the capturing session's
 identifiers — served to anonymous visitors.)
 
-### Handles: handler pushes bake; loader pushes keep "nesting = liveness"
+### Handles: handler and bake-lane pushes bake; loader pushes keep "nesting = liveness"
 
 - `ctx.use(H)(promise)` from a handler — a TOP-LEVEL pushed promise is awaited
   at capture and BAKED into the shell (bounded by `ppr.captureTimeout`, 15s by
   default).
-- A promise pushed from a LOADER is never in the shell and the capture does not
-  wait for it: however slow it is (or if it never settles), the shell is still
-  stored, and the HIT's own loader run delivers the value after hydration.
+- `ctx.use(H)(promise)` (or `.defer()`) from an `ssr: false` LOADER, or a
+  loader it awaits — awaited at capture and BAKED the same way, judged by the
+  value it settles to, as `push(await promise)` would be (#1182). One that
+  rejects, or does not settle within `ppr.captureTimeout`, refuses the
+  capture, as a handler's does. A loader without `ssr: false` never runs at
+  capture, so its pushes are never in the shell.
 - `ctx.use(H)({ x: promise })` from a HANDLER — also baked. The capture waits
   for every promise nested in a handler's push, at any depth of plain objects,
   arrays and JSX props, before it records the handles every HIT replays. Keep
@@ -921,7 +926,9 @@ by a navigation alone carries no pins, and its replay runs these loaders fresh.
   fill the holes — and the recorded baked paths are overlaid onto the fresh
   result, so the payload matches the prelude while the nested promises stream
   fresh. A fresh rejection skips the overlay and goes to the loader's error
-  boundary. Give it its own cache,
+  boundary: on a document HIT the payload then carries the error where the
+  HTML has the baked value, and React renders that part again on the client
+  (one hydration mismatch, the one known residual of a HIT). Give it its own cache,
   `loader(Def, { ssr: false }, () => [cache({ ttl })])`, so that run reads
   through the loader cache.
 
@@ -982,9 +989,12 @@ loader running on the replay awaits it. On a document HIT the page hydrates
 with the shell's copy and the hole's value takes its place after hydration
 ("Handles on a shell HIT" below). An
 `ssr: false` loader is served from the shell only while the entry holds its
-pin: a snapshot captured by a navigation alone carries none, and a shell over
-`ppr.maxSnapshotBytes` drops them. There the loader runs fresh, and its
-pushes are that run's, like its data.
+pin: a snapshot captured by a navigation alone carries none, and a capture
+over `ppr.maxSnapshotBytes` stores the navigation half only, without them.
+There a navigation runs the loader fresh, and its pushes are that run's, like
+its data. A document HIT is served only from an entry that holds a pin for
+every `ssr: false` loader its HTML baked, so a document never hydrates one
+loader's run over HTML rendered from the capture's value.
 
 A `Prerender` + `ppr` page follows the same table. Its handler layer comes
 from the prerendered payload, which never holds a loader push (loaders do not
@@ -994,63 +1004,76 @@ on its own, and a HIT restores them as above (#1057).
 A dependency the route does not register, which an `ssr: false` loader
 awaited at capture outside any live loader, is on neither lane: its settled
 pushes stay as the prelude rendered them, even where a live loader also
-awaits it, while its data is fresh. (They follow the run instead once the
-entry has lost a pin, because the loader that awaits it then runs.) To keep
+awaits it, while its data is fresh. (They follow the run instead when the
+replayed entry has no pin for the loader that awaits it, because that loader
+then runs.) To keep
 its pushes live, declare it as its own `loader()` on the route. A push the
-capture cannot record (a deferred push, or one holding a promise) marks every
-loader record of the page to run: those bodies then still run on each replay,
-in the background, and that push reaches the page (from the loader's own
-`cache()` entry when it hits) with the run's value, on a document HIT and on
-a client navigation alike. On a document HIT it arrives after hydration.
-
-**Handles on a shell HIT.** A promise pushed from a loader is live and is
-never in a shell. To have a value in the shell's HTML, push it settled
-(await it) from the `ssr: false` loader, or push it from the handler.
-
-Three things follow, in this order of scope:
-
-1. **What is in a shell's HTML** changes only for promise pushes of
-   `ssr: false` loaders and of the loaders they await: `push(promise)`, or a
-   pushed value that holds a promise. Those run at capture, and the shell
-   renders no element for such a push. A loader without `ssr: false` never
-   ran at capture, so nothing of it was ever in the shell.
-2. **On a shell HIT every loader push made during the request arrives after
+capture cannot record (one whose value, once settled, holds a promise) marks
+every loader record of the page to run: those bodies then still run on each
+replay, in the background, and that push reaches the page (from the loader's
+own `cache()` entry when it hits) with the run's value, on a document HIT and
+on a client navigation alike. On a document HIT it arrives after hydration.
+
+**Handles on a shell HIT.** The shell holds what its capture's document
+rendered: the handlers' pushes and the `ssr: false` loaders' pushes, a
+promise (`push(promise)`, `.defer()`) resolved. A pushed promise is judged by
+the value it settles to, as `push(await promise)` would be (#1182). A
+live-lane loader's push is never in a shell.
+
+Four things follow, in this order of scope:
+
+1. **What is in a shell's HTML.** The capture awaits a promise an
+   `ssr: false` loader (or a loader it awaits) pushes, under
+   `ppr.captureTimeout`, and bakes the value. One that settles to a value
+   holding a promise is live: the shell renders no element for it. A loader
+   without `ssr: false` never runs at capture, so nothing of it is ever in
+   the shell.
+2. **A pushed promise that fails refuses the capture.** One that rejects, or
+   does not settle within `ppr.captureTimeout`, keeps the route on MISS, as
+   a handler's does, and the warning names the loader and the handle. Catch
+   it and push a fallback, or push it from a live-lane loader.
+3. **On a shell HIT every loader push made during the request arrives after
    hydration**, a live-lane loader's included. The document hydrates with
    exactly the handle data the shell's HTML was rendered from (the handlers'
-   pushes and the settled pushes of the loaders that ran at capture), and
-   the request's own pushes follow as a normal `useHandle` update.
-3. **`useHandle` on every document, `ppr` or not:** a reader that React is
+   pushes and the pushes of the loaders that ran at capture), and the
+   request's own pushes follow as a normal `useHandle` update.
+4. **`useHandle` on every document, `ppr` or not:** a reader that React is
    hydrating reads the handle data its HTML was rendered from, wherever its
    boundary hydrates, and takes the newer data right after. So a reader
    inside the `loading()` or `<Suspense>` of a loader that pushes after an
    `await` hydrates clean.
 
-| On the HIT's request                                                        | In the HIT's HTML      | The client                                        |
-| --------------------------------------------------------------------------- | ---------------------- | ------------------------------------------------- |
-| a handler's push, a pinned `ssr: false` loader's settled push               | yes (the shell has it) | hydrates with it                                  |
-| a deferred push (`push(promise)`), or a push holding a promise, by a loader | no                     | gets it right after hydration                     |
-| a live-lane loader's push                                                   | no                     | gets it right after hydration                     |
-| the run of an `ssr: false` loader the shell has no pin for                  | the capture's push     | hydrates with the capture's, then shows the run's |
+| On the HIT's request                                                                       | In the HIT's HTML      | The client                    |
+| ------------------------------------------------------------------------------------------ | ---------------------- | ----------------------------- |
+| a handler's push, a pinned `ssr: false` loader's push (`push(promise)` and `.defer()` too) | yes (the shell has it) | hydrates with it              |
+| a push by an `ssr: false` loader whose value holds a promise                               | no                     | gets it right after hydration |
+| a live-lane loader's push                                                                  | no                     | gets it right after hydration |
 
-A value a loader pushes as a promise is therefore in the HTML of a document
-MISS (the render awaits it) and of a route without `ppr`, and not in the
-HTML of a shell HIT. When a crawler or the first paint needs it, change one
-line:
+So a title an `ssr: false` loader pushes to `Meta`, promise or not, is in
+every HIT's `<head>`: a crawler and a link preview see it. It bakes with the
+shell and is invalidated with it (its TTL, its tags, `updateTag()`). A value
+that must stay per request comes from a loader without `ssr: false`, which
+nothing has to read:
 
 ```ts
-ctx.use(Notes)(db.stockNote(id)); // a promise: live, after hydration on a HIT
-ctx.use(Notes)(await db.stockNote(id)); // settled: baked into the shell
+const StockNote = createLoader(async (ctx) => {
+  ctx.use(Notes)(db.stockNote(ctx.params.id)); // live: after hydration on a HIT
+  return null;
+});
+path("/product/:id", ProductPage, { name: "product", ppr: true }, () => [
+  loader(Product, { ssr: false }), // bakes: its data and its pushes
+  loader(StockNote), // live lane: runs on every request
+]);
 ```
 
-The settled push bakes with the shell and is invalidated with it (its TTL,
-its tags). A promise is not baked, whenever it settles: it is the shape that
-says "per request", the same as a promise in the loader's data.
+Or nest the value in a settled push (`{ label, count: promise }`): the whole
+push then stays live, and every pinned body of the page runs on each HIT.
 
 A pinned loader's pushes are exactly the ones its capture made. If its body
-pushes a settled value only on some runs (behind a condition), a replay that
-runs it shows the capture's answer, a push or none, never a later run's next
-to the pinned data. A deferred push is the exception by design: it is
-delivered on every replay.
+pushes a value only on some runs (behind a condition), a replay that runs it
+shows the capture's answer, a push or none, never a later run's next to the
+pinned data. A push whose value holds a promise is the exception by design:
+it is delivered on every replay.
 
 One arrangement mixes sources by design. A loader that reads a
 `cache()`-bound loader with `ctx.use()` before that binding starts (a loader
@@ -1392,13 +1415,13 @@ path(
 );
 ```
 
-| Field              | Default | Notes                                                                                                                                                                                                                                                                                                                                                                                                       |
-| ------------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ttl`              | `300`   | shell freshness window in seconds (`ppr: true` uses the default)                                                                                                                                                                                                                                                                                                                                            |
-| `swr`              | —       | stale window: serve the stale shell + background recapture                                                                                                                                                                                                                                                                                                                                                  |
-| `tags`             | —       | operational tags UNIONED with the tags the capture collects — see "Invalidation" below                                                                                                                                                                                                                                                                                                                      |
-| `maxSnapshotBytes` | 8 MiB   | cap on the loader pins in the entry's snapshot (the bake-lane loader records). The recorded handler layer is exempt. Over the cap the pins are dropped and the shell is stored with its handler layer (warned once per key); bake-lane loaders then run on every replay and read the live store, their handle pushes come from that run like their data, and drift from the prelude is repaired client-side |
-| `captureTimeout`   | 15000ms | ONE capture deadline: the handler layer settling (promises it passes or pushes, async server components, loaders it awaits), bake-lane loaders, and the prerender; a capture that misses it stores nothing rather than a partial shell                                                                                                                                                                      |
+| Field              | Default | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| ------------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ttl`              | `300`   | shell freshness window in seconds (`ppr: true` uses the default)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `swr`              | —       | stale window: serve the stale shell + background recapture                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `tags`             | —       | operational tags UNIONED with the tags the capture collects — see "Invalidation" below                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `maxSnapshotBytes` | 8 MiB   | cap on the loader pins in the entry's snapshot (the bake-lane loader records). The recorded handler layer is exempt. A document HIT is served only from an entry that holds a pin for every `ssr: false` loader its HTML baked, so over the cap no document shell is stored: the entry keeps the handler layer only, documents are a MISS (full SSR, no hydration error, no remount), client navigations still replay the handler layer and run the bake-lane loaders fresh, and the URL backs off like a refused capture. Warned once per key: "the document shell was not stored; raise maxSnapshotBytes or shrink the ssr: false data" |
+| `captureTimeout`   | 15000ms | ONE capture deadline: the handler layer settling (promises it passes or pushes, async server components, loaders it awaits), bake-lane loaders, and the prerender; a capture that misses it stores nothing rather than a partial shell                                                                                                                                                                                                                                                                                                                                                                                                    |
 
 A shell never outlives the route `cache()` entry it was captured from: under
 a route `cache()`, the shell is fresh no longer than that entry is (at most

package/skills/prerender/SKILL.md

@@ -1329,9 +1329,9 @@ write that started before an invalidation of one of its tags is refused.
 ### Limits worth knowing
 
 - **Only the router's own handler.** A warm goes through `router.fetch`, the
-  handler `createRouter`'s `cache`, `nonce` and `version` configure. An app
-  entry that builds its own `createRSCHandler({ cache, version })` is not what
-  a warm runs: put those options on `createRouter`.
+  handler `createRouter`'s `cache` and `nonce` configure. An app
+  entry that builds its own `createRSCHandler({ cache })` is not what a warm
+  runs: put the option on `createRouter`.
 - **Document records only.** Navigation (`partial:`) and intercept records
   fill on the first navigation.
 - **One location at a time.** A warm does not reach a copy another location

package/skills/router-setup/SKILL.md

@@ -266,8 +266,6 @@ Notes:
   a cleared cache) on every build; the build prints one note when that applies.
   A router that renders no such action keeps its cache without one (`/use-cache`,
   `/cache-guide`).
-- `createRouter({ version })` takes effect on every preset, including `node`
-  and `vercel`. It replaces both computed cache versions with that exact value.
 - `@rangojs/router/vite` also exports `poke()`, a dev-server plugin: type `e`
   then Enter (or Ctrl+R where the terminal passes it through) to full-reload
   the browser.

package/skills/testing/render-handler.md

@@ -8,23 +8,23 @@ A Rango route handler is a pure function `(ctx) => rsc` — the function you pas
 
 ### Options — `RenderHandlerOptions`
 
-| Field                  | Type                                                   | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| ---------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `params`               | `Record<string, string>`                               | Route params surfaced as `ctx.params`.                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `env`                  | `TEnv`                                                 | Environment bindings surfaced as `ctx.env`.                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `request`              | `Request \| string`                                    | Backing Request (string or `Request`); defaults to a localhost GET.                                                                                                                                                                                                                                                                                                                                                                                  |
-| `headers`              | `HeadersInit`                                          | Request headers (e.g. `Cookie`) the handler reads via `cookies()`. Used only when `request` is a string or omitted; a passed `Request` keeps its own headers.                                                                                                                                                                                                                                                                                        |
-| `build`                | `boolean`                                              | Seed `ctx.build` (default `false`) to test a handler that branches on the build-time pass, including calling `ctx.dynamic()` on a miss. Assert the opt-out via `result.dynamic`.                                                                                                                                                                                                                                                                     |
-| `theme`                | `ThemeConfig \| true`                                  | Theme config (`createRouter({ theme })` shape). Without it `ctx.theme`/`ctx.setTheme` are inert; pass one to test a handler that reads the theme or writes the theme cookie.                                                                                                                                                                                                                                                                         |
-| `vars`                 | `VarsInit` (object or `[[Var, value]]` tuples)         | Variables a prior middleware set, read via `ctx.get(...)`.                                                                                                                                                                                                                                                                                                                                                                                           |
-| `routeName`            | `string`                                               | Matched route name (drives `ctx.routeName` and scoped reverse).                                                                                                                                                                                                                                                                                                                                                                                      |
-| `routeMap`             | `Record<string, string>`                               | Route name -> pattern map enabling `ctx.reverse()`.                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `loaders`              | `ReadonlyArray<readonly [LoaderDefinition, unknown]>`  | Seed the data `ctx.use(SomeLoader)` returns. Matched by loader reference; NO real loader runs.                                                                                                                                                                                                                                                                                                                                                       |
-| `clientComponents`     | `Record<string, unknown>`                              | `"use client"` components in the handler's RSC, so they serialize as real boundaries when `rangoUseClientTransform()` is not wired. Keyed by name.                                                                                                                                                                                                                                                                                                   |
-| `stateCookie`          | `StateCookieSeed` (`{ prefix?, routerId?, version? }`) | Customize the rango state cookie a handler calling `invalidateClientCache()` rotates. The name is ALWAYS seeded (default `rango-state_router_0`) so the rotation `Set-Cookie` fires like production rather than no-opping; override `prefix`/`routerId` to match your `createRouter({ stateCookiePrefix, id })`, or `version` (the app's version, as `createRouter({ version })` would set it; the value is `{version}:{timestamp}`, default `"0"`). |
-| `cacheStore`           | `SegmentCacheStore`                                    | Segment cache store backing a `"use cache"` function the handler invokes (e.g. `new MemorySegmentCacheStore()`). WITHOUT it, `registerCachedFunction` takes the uncached bypass and the cached path is NOT exercised (the runtime emits a one-time warning under the test runner). Pair with `cacheProfiles`.                                                                                                                                        |
-| `cacheProfiles`        | `Record<string, CacheProfile>`                         | Cache profiles in the `createRouter({ cacheProfiles })` shape, required for `"use cache: profileName"` resolution once a `cacheStore` is wired.                                                                                                                                                                                                                                                                                                      |
-| `inActionRevalidation` | `boolean`                                              | Render as if inside a server action's revalidation render (production sets this in `revalidateAfterAction`). A stale `"use cache"` entry whose profile sets `foregroundOnAction: true` then re-executes in the FOREGROUND (fresh result in this render) instead of SWR. Pair with `cacheStore` + `cacheProfiles` to exercise the opt-in.                                                                                                             |
+| Field                  | Type                                                   | Meaning                                                                                                                                                                                                                                                                                                                                                                                                    |
+| ---------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `params`               | `Record<string, string>`                               | Route params surfaced as `ctx.params`.                                                                                                                                                                                                                                                                                                                                                                     |
+| `env`                  | `TEnv`                                                 | Environment bindings surfaced as `ctx.env`.                                                                                                                                                                                                                                                                                                                                                                |
+| `request`              | `Request \| string`                                    | Backing Request (string or `Request`); defaults to a localhost GET.                                                                                                                                                                                                                                                                                                                                        |
+| `headers`              | `HeadersInit`                                          | Request headers (e.g. `Cookie`) the handler reads via `cookies()`. Used only when `request` is a string or omitted; a passed `Request` keeps its own headers.                                                                                                                                                                                                                                              |
+| `build`                | `boolean`                                              | Seed `ctx.build` (default `false`) to test a handler that branches on the build-time pass, including calling `ctx.dynamic()` on a miss. Assert the opt-out via `result.dynamic`.                                                                                                                                                                                                                           |
+| `theme`                | `ThemeConfig \| true`                                  | Theme config (`createRouter({ theme })` shape). Without it `ctx.theme`/`ctx.setTheme` are inert; pass one to test a handler that reads the theme or writes the theme cookie.                                                                                                                                                                                                                               |
+| `vars`                 | `VarsInit` (object or `[[Var, value]]` tuples)         | Variables a prior middleware set, read via `ctx.get(...)`.                                                                                                                                                                                                                                                                                                                                                 |
+| `routeName`            | `string`                                               | Matched route name (drives `ctx.routeName` and scoped reverse).                                                                                                                                                                                                                                                                                                                                            |
+| `routeMap`             | `Record<string, string>`                               | Route name -> pattern map enabling `ctx.reverse()`.                                                                                                                                                                                                                                                                                                                                                        |
+| `loaders`              | `ReadonlyArray<readonly [LoaderDefinition, unknown]>`  | Seed the data `ctx.use(SomeLoader)` returns. Matched by loader reference; NO real loader runs.                                                                                                                                                                                                                                                                                                             |
+| `clientComponents`     | `Record<string, unknown>`                              | `"use client"` components in the handler's RSC, so they serialize as real boundaries when `rangoUseClientTransform()` is not wired. Keyed by name.                                                                                                                                                                                                                                                         |
+| `stateCookie`          | `StateCookieSeed` (`{ prefix?, routerId?, version? }`) | Customize the rango state cookie a handler calling `invalidateClientCache()` rotates. The name is ALWAYS seeded (default `rango-state_router_0`) so the rotation `Set-Cookie` fires like production rather than no-opping; override `prefix`/`routerId` to match your `createRouter({ stateCookiePrefix, id })`, or `version` (a seeded app version: the value is `{version}:{timestamp}`, default `"0"`). |
+| `cacheStore`           | `SegmentCacheStore`                                    | Segment cache store backing a `"use cache"` function the handler invokes (e.g. `new MemorySegmentCacheStore()`). WITHOUT it, `registerCachedFunction` takes the uncached bypass and the cached path is NOT exercised (the runtime emits a one-time warning under the test runner). Pair with `cacheProfiles`.                                                                                              |
+| `cacheProfiles`        | `Record<string, CacheProfile>`                         | Cache profiles in the `createRouter({ cacheProfiles })` shape, required for `"use cache: profileName"` resolution once a `cacheStore` is wired.                                                                                                                                                                                                                                                            |
+| `inActionRevalidation` | `boolean`                                              | Render as if inside a server action's revalidation render (production sets this in `revalidateAfterAction`). A stale `"use cache"` entry whose profile sets `foregroundOnAction: true` then re-executes in the FOREGROUND (fresh result in this render) instead of SWR. Pair with `cacheStore` + `cacheProfiles` to exercise the opt-in.                                                                   |
 
 ### Context — `HandlerContext` (what your handler receives)
 

package/skills/testing/serve-shell-request.md

@@ -249,7 +249,7 @@ Vitest runs no Vite id transform, so give each router an explicit `id` when a te
 | `hydration` | What the document hydrates with (`metadata.handles`, read to its end before hydration starts). For a `partial` request, the last state it streamed. |
 | `late`      | The states that arrived on the late channel (`metadata.handlesLate`), in order. Each replaces the client's handle data after hydration. Often `[]`. |
 
-On a HIT the client hydrates with exactly what the shell was rendered from, so `hydration` is also what the shell's HTML holds, and whatever this request's loaders push, replace or drop is in `late` (see `/ppr`, "Handles on a shell HIT"):
+On a HIT the client hydrates with exactly what the shell was rendered from, so `hydration` is also what the shell's HTML holds (the handlers' pushes and the `ssr: false` loaders', a pushed promise resolved), and whatever this request's loaders push, replace or drop is in `late` (see `/ppr`, "Handles on a shell HIT"):
 
 ```ts
 // The handler pushed ctx.use(Notes)("from-handler"); a live loader pushes