@rangojs/router 0.25.0 → 0.26.0

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

@@ -836,14 +836,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
@@ -997,60 +1000,73 @@ pushes stay as the prelude rendered them, even where a live loader also
 awaits it, while its data is fresh. (They follow the run instead once the
 entry has lost a pin, because the loader that awaits it then runs.) To keep
 its pushes live, declare it as its own `loader()` on the route. A push the
-capture cannot record (a deferred push, or one holding a promise) marks every
-loader record of the page to run: those bodies then still run on each replay,
-in the background, and that push reaches the page (from the loader's own
-`cache()` entry when it hits) with the run's value, on a document HIT and on
-a client navigation alike. On a document HIT it arrives after hydration.
-
-**Handles on a shell HIT.** A promise pushed from a loader is live and is
-never in a shell. To have a value in the shell's HTML, push it settled
-(await it) from the `ssr: false` loader, or push it from the handler.
-
-Three things follow, in this order of scope:
-
-1. **What is in a shell's HTML** changes only for promise pushes of
-   `ssr: false` loaders and of the loaders they await: `push(promise)`, or a
-   pushed value that holds a promise. Those run at capture, and the shell
-   renders no element for such a push. A loader without `ssr: false` never
-   ran at capture, so nothing of it was ever in the shell.
-2. **On a shell HIT every loader push made during the request arrives after
+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                     |
+| the run of an `ssr: false` loader the shell has no pin for                                 | the capture's push     | hydrates with the capture's, then shows the run's |
 
-A value a loader pushes as a promise is therefore in the HTML of a document
-MISS (the render awaits it) and of a route without `ppr`, and not in the
-HTML of a shell HIT. When a crawler or the first paint needs it, change one
-line:
+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

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

package/skills/testing/server-actions.md

@@ -8,22 +8,22 @@
 
 ### Options — `CreateTestContextOptions<TEnv>`
 
-| Field           | Type                                                   | Meaning                                                                                                                                                                                                                                                                                                                                                                                                               |
-| --------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `env`           | `TEnv`                                                 | Platform bindings the action reads (`ctx.env`). Default `{}`. Double them yourself (see `./bindings.md`).                                                                                                                                                                                                                                                                                                             |
-| `request`       | `Request \| string`                                    | The request to run under. A `string` becomes `new Request(url)`; pass a full `Request` to seed a `Cookie` header. Default origin `http://localhost/`.                                                                                                                                                                                                                                                                 |
-| `requestInit`   | `RequestInit`                                          | Init merged when `request` is a string (e.g. `{ method, headers, body }`).                                                                                                                                                                                                                                                                                                                                            |
-| `variables`     | `Record<string, unknown>`                              | Raw backing store for `ctx.get()` / `ctx.set()`, pre-seeded from `vars`.                                                                                                                                                                                                                                                                                                                                              |
-| `vars`          | `VarsInit`                                             | Vars a prior middleware would have set (object or `[token, value]` list).                                                                                                                                                                                                                                                                                                                                             |
-| `routeMap`      | `Record<string, string>`                               | Route name -> pattern map enabling `ctx.reverse()` without global state.                                                                                                                                                                                                                                                                                                                                              |
-| `routeName`     | `string`                                               | Current route name (drives `ctx.reverse()` self-references).                                                                                                                                                                                                                                                                                                                                                          |
-| `params`        | `Record<string, string>`                               | Route params on `ctx.params`.                                                                                                                                                                                                                                                                                                                                                                                         |
-| `basename`      | `string`                                               | Router basename, normalized exactly like `createRouter({ basename })`; drives `redirect()` prefixing. Default `undefined`.                                                                                                                                                                                                                                                                                            |
-| `cacheStore`    | `SegmentCacheStore`                                    | Backing store for `use cache` functions (same shape as `createRouter({ cache })`). Without it, cached functions run uncached and their guards never fire.                                                                                                                                                                                                                                                             |
-| `cacheProfiles` | `Record<string, CacheProfile>`                         | Profiles for `use cache: "name"`, same shape as `createRouter({ cacheProfiles })`. An unknown profile throws.                                                                                                                                                                                                                                                                                                         |
-| `theme`         | `ThemeConfig \| true`                                  | Theme config (same shape as `createRouter({ theme })`). Without it `ctx.theme` / `ctx.setTheme` are inert.                                                                                                                                                                                                                                                                                                            |
-| `build`         | `boolean`                                              | Seed `ctx.build` (default `false`) for code that branches on the build-time PPR shell-capture pass. With `true`, `ctx.waitUntil()` is inert, as at build time.                                                                                                                                                                                                                                                        |
-| `stateCookie`   | `StateCookieSeed` (`{ prefix?, routerId?, version? }`) | Customize the rango state cookie an action calling `invalidateClientCache()` rotates. The name is ALWAYS seeded (default `rango-state_router_0`) so the rotation `Set-Cookie` fires like production; override `prefix`/`routerId` to match `createRouter({ stateCookiePrefix, id })`, or `version` (the app's version, as `createRouter({ version })` would set it; value is `{version}:{timestamp}`, default `"0"`). |
+| Field           | Type                                                   | Meaning                                                                                                                                                                                                                                                                                                                                                                         |
+| --------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `env`           | `TEnv`                                                 | Platform bindings the action reads (`ctx.env`). Default `{}`. Double them yourself (see `./bindings.md`).                                                                                                                                                                                                                                                                       |
+| `request`       | `Request \| string`                                    | The request to run under. A `string` becomes `new Request(url)`; pass a full `Request` to seed a `Cookie` header. Default origin `http://localhost/`.                                                                                                                                                                                                                           |
+| `requestInit`   | `RequestInit`                                          | Init merged when `request` is a string (e.g. `{ method, headers, body }`).                                                                                                                                                                                                                                                                                                      |
+| `variables`     | `Record<string, unknown>`                              | Raw backing store for `ctx.get()` / `ctx.set()`, pre-seeded from `vars`.                                                                                                                                                                                                                                                                                                        |
+| `vars`          | `VarsInit`                                             | Vars a prior middleware would have set (object or `[token, value]` list).                                                                                                                                                                                                                                                                                                       |
+| `routeMap`      | `Record<string, string>`                               | Route name -> pattern map enabling `ctx.reverse()` without global state.                                                                                                                                                                                                                                                                                                        |
+| `routeName`     | `string`                                               | Current route name (drives `ctx.reverse()` self-references).                                                                                                                                                                                                                                                                                                                    |
+| `params`        | `Record<string, string>`                               | Route params on `ctx.params`.                                                                                                                                                                                                                                                                                                                                                   |
+| `basename`      | `string`                                               | Router basename, normalized exactly like `createRouter({ basename })`; drives `redirect()` prefixing. Default `undefined`.                                                                                                                                                                                                                                                      |
+| `cacheStore`    | `SegmentCacheStore`                                    | Backing store for `use cache` functions (same shape as `createRouter({ cache })`). Without it, cached functions run uncached and their guards never fire.                                                                                                                                                                                                                       |
+| `cacheProfiles` | `Record<string, CacheProfile>`                         | Profiles for `use cache: "name"`, same shape as `createRouter({ cacheProfiles })`. An unknown profile throws.                                                                                                                                                                                                                                                                   |
+| `theme`         | `ThemeConfig \| true`                                  | Theme config (same shape as `createRouter({ theme })`). Without it `ctx.theme` / `ctx.setTheme` are inert.                                                                                                                                                                                                                                                                      |
+| `build`         | `boolean`                                              | Seed `ctx.build` (default `false`) for code that branches on the build-time PPR shell-capture pass. With `true`, `ctx.waitUntil()` is inert, as at build time.                                                                                                                                                                                                                  |
+| `stateCookie`   | `StateCookieSeed` (`{ prefix?, routerId?, version? }`) | Customize the rango state cookie an action calling `invalidateClientCache()` rotates. The name is ALWAYS seeded (default `rango-state_router_0`) so the rotation `Set-Cookie` fires like production; override `prefix`/`routerId` to match `createRouter({ stateCookiePrefix, id })`, or `version` (a seeded app version: the value is `{version}:{timestamp}`, default `"0"`). |
 
 ### Context — `RequestContext<TEnv>` (what your code receives)
 

package/skills/vercel/SKILL.md

@@ -120,7 +120,7 @@ The cache factory receives `(env, ctx)`: on Vercel `env` is `process.env` and `c
 
 `router.prerender()` can warm a route into this store before traffic (`/prerender` → "Warm any route before traffic"). The Runtime Cache is per region, so `VercelCacheStore` declares `scope: "regional"`: a warm fills the region the call runs in. That is all traffic when the project's functions run in one region (the default `iad1` for new projects, and every Hobby project); on a multi-region project it warms one region and the others fill on first use. The router does not detect the region count. The memory store used off-platform above is refused in production and allowed under the dev server.
 
-`getCache()` takes no deployment id: `VercelCacheStore` puts a version in front of every key itself (data version for families `s`, `i`; document version for `r`, `h`; none for tag markers), computed per `createRouter()` from its built code. A deploy that does not change a router keeps its entries; a deploy that changes it reads under new keys. `version` on the store (or on `createRouter`) replaces both versions. 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 })`. Two environments built from the same code share entries if they share a cache namespace; give each its own namespace or `version`.
+`getCache()` takes no deployment id: `VercelCacheStore` puts a version in front of every key itself (data version for families `s`, `i`; document version for `r`, `h`; none for tag markers), computed per `createRouter()` from its built code. A deploy that does not change a router keeps its entries; a deploy that changes it reads under new keys. To clear the cache on every deploy, keep a deployment-scoped `getCache({ namespace: process.env.VERCEL_DEPLOYMENT_ID })`. Two environments built from the same code share entries if they share a cache namespace; give each its own namespace.
 
 ## Host routers (multi-app)
 

package/src/cache/cf/cf-cache-store.ts

@@ -500,8 +500,6 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   private readonly namespace?: string;
   private readonly explicitBaseUrl?: string;
   private readonly waitUntil?: (fn: () => Promise<void>) => void;
-  /** The `version` option: used for every versioned family when set. */
-  private readonly explicitVersion?: string;
   private readonly edgeLookupTimeoutMs: number;
   private readonly edgeReadTimeoutMs: number;
   private readonly kvReadTimeoutMs: number;
@@ -554,7 +552,6 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     // the internal host. Only the explicit override can be captured eagerly.
     this.explicitBaseUrl = options.baseUrl;
     this.defaults = options.defaults;
-    this.explicitVersion = options.version;
     // Coalesce only finite numbers to the override; a non-finite value (NaN from
     // `Number(env.UNSET)`, or Infinity) would otherwise sail past `?? DEFAULT`
     // (which only replaces null/undefined) into setTimeout, where NaN/Infinity
@@ -1628,8 +1625,8 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     // stamp). Carried on doc L1 entries for the herd guard; never serve them.
     headers.delete(CACHE_EXPIRES_AT_HEADER);
     headers.delete(CACHE_REVALIDATING_AT_HEADER);
-    // Finding #3 (read side): strip per-client signals a pre-fix or
-    // pinned-version L1 entry may carry. See the read-side note in the design doc.
+    // Finding #3 (read side): strip per-client signals a pre-fix L1 entry
+    // may carry. See the read-side note in the design doc.
     stripPerClientSignals(headers);
     return new Response(response.body, {
       status: response.status,
@@ -2952,7 +2949,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   private keyToRequest(key: string, family: KeyVersion): Request {
     const encodedKey = encodeURIComponent(key);
     return new Request(
-      `${this.resolveBaseUrl()}${versionKeyPrefix(this.explicitVersion, family)}${encodedKey}`,
+      `${this.resolveBaseUrl()}${versionKeyPrefix(family)}${encodedKey}`,
       { method: "GET" },
     );
   }
@@ -2976,7 +2973,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
    * @internal
    */
   private async toKVKey(key: string, family: KeyVersion): Promise<string> {
-    const composed = `${versionKeyPrefix(this.explicitVersion, family)}${key}`;
+    const composed = `${versionKeyPrefix(family)}${key}`;
     if (kvKeyByteLength(composed) <= KV_MAX_KEY_BYTES) return composed;
     const prefix = truncateToBytes(composed, KV_KEY_PRESERVED_PREFIX_BYTES);
     return `${prefix}~${await kvKeyDigest(composed)}`;

package/src/cache/cf/cf-cache-types.ts

@@ -322,23 +322,6 @@ export interface CFCacheStoreOptions<TEnv = unknown> {
    */
   tagCacheTtl?: number;
 
-  /**
-   * Cache version string override. When set, this exact value prefixes every
-   * versioned key the store writes (`v/{version}/...`), for cached data and
-   * stored HTML alike; changing it makes every earlier entry unreachable.
-   *
-   * Leave it unset for the default: the store keys with the versions of the
-   * router serving the request. Segment entries and `"use cache"` items use
-   * the router's data version; document responses and PPR shells use its
-   * document version (see `createRouter({ version })`). Those are computed
-   * from the router's built code, so a deploy that does not change the router
-   * keeps its entries.
-   *
-   * Tag invalidation markers are never versioned: an invalidation applies to
-   * the entries of every version, including one that comes back in a rollback.
-   */
-  version?: string;
-
   /**
    * Latency budget (ms) for an L1 edge cache (CF Cache API) read. A `match`
    * slower than this is abandoned and treated as a miss, so a degraded colo

package/src/cache/handle-snapshot.ts

@@ -177,8 +177,8 @@ export type OwnedPushDelivery = (loaderId: string) => RecordAuthority;
  * says the record supplies that loader's value too ("pin", "copies"), and is
  * a placeholder (pushPlaceholder) everywhere else: without `owned`, every
  * owner. Neither claims its loader, so the loader's own cache() HIT still
- * delivers (the thenable pushes a restored copy lets through, or its entry's
- * pushes in a placeholder's place).
+ * delivers (the pushes holding a promise a restored copy lets through, or its
+ * entry's pushes in a placeholder's place).
  */
 export function restoreHandles(
   handles: Record<string, SegmentHandleData>,

package/src/cache/types.ts

@@ -445,7 +445,7 @@ export interface ShellCacheEntry {
   /** React.version captured at prerender time; the read-time invalidation gate. */
   reactVersion: string;
   /**
-   * Build version captured at prerender time: the RSC handler's `version`,
+   * Build version captured at prerender time: the RSC handler's version,
    * which is the router's DOCUMENT version (router-versions.ts) — a hash of
    * its server code and the client asset names by default, a stamp bumped on
    * dev RSC-module edits. The second read-time gate: a persistent shared
@@ -686,11 +686,13 @@ export interface ShellSnapshotLoaderValue {
    */
   holes: 0 | 1;
   /**
-   * 1 when the capture saw a loader push it could not record (a deferred
-   * push, one with masked nested promises, or one made outside any loader
-   * body): a HIT then still runs the loader body in the background
-   * (pin-first) so those pushes reach the page. 0: a hole-free record is
-   * served from the pin alone and its body does not run on a HIT.
+   * 1 when the capture saw a loader push it could not record (one whose
+   * settled value holds masked nested promises, one a live-lane loader made,
+   * or one made outside any loader body): a HIT then still runs the loader
+   * body in the background (pin-first) so those pushes reach the page. A
+   * pushed promise that settles thenable-free is recorded (#1182).
+   * 0: a hole-free record is served from the pin alone and its body does not
+   * run on a HIT.
    *
    * Both bits are always written. A record stored before they existed (v0.17)
    * reads each missing bit as 1 (buildShellLoaderSeed): its snapshot lacks

package/src/cache/vercel/vercel-cache-store.ts

@@ -330,7 +330,7 @@ export interface VercelCacheStoreOptions<TEnv = unknown> {
    *
    * Vercel does not reconcile entries between deployments; the store does it
    * through its keys, which carry the serving router's cache versions (see
-   * `version`). So a deploy that changes a router's code stops reading that
+   * `getCacheVersions`). So a deploy that changes a router's code stops reading that
    * router's old entries, and a deploy that does not keeps them. A namespace
    * that changes per deployment (`getCache({ namespace: VERCEL_DEPLOYMENT_ID })`)
    * still works and clears the cache on every deploy, which is what you want
@@ -363,19 +363,6 @@ export interface VercelCacheStoreOptions<TEnv = unknown> {
     defaultKey: string,
   ) => string | Promise<string>;
 
-  /**
-   * Version override, folded into every versioned key as `v/{version}/...`.
-   * When set, this exact value is used for cached data and stored HTML alike;
-   * changing it makes everything this store wrote before unreachable.
-   *
-   * Leave it unset for the default: the store keys with the versions of the
-   * router serving the request, as CFCacheStore does. Segments and `"use
-   * cache"` items use the router's data version; responses and PPR shells use
-   * its document version (see `createRouter({ version })`). Tag markers are
-   * never versioned, so an invalidation applies to every version.
-   */
-  version?: string;
-
   /**
    * Max serialized entry size in bytes before a write is skipped. Defaults to
    * VERCEL_MAX_ITEM_BYTES (2 MB - the platform's hard cap).
@@ -537,8 +524,6 @@ export class VercelCacheStore<
 
   private readonly cache: VercelRuntimeCache;
   private readonly waitUntil?: (promise: Promise<unknown>) => void;
-  /** The `version` option: used for every versioned family when set. */
-  private readonly explicitVersion?: string;
   private readonly maxItemBytes: number;
   private readonly memo: ResolvedShellMemoOptions;
   private readonly handleMemos: VercelHandleMemos;
@@ -563,7 +548,6 @@ export class VercelCacheStore<
     this.waitUntil = options.waitUntil;
     this.defaults = options.defaults;
     this.keyGenerator = options.keyGenerator;
-    this.explicitVersion = options.version;
     this.maxItemBytes = options.maxItemBytes ?? VERCEL_MAX_ITEM_BYTES;
     this.maxShellEntryBytes = Math.floor((this.maxItemBytes * 3) / 4);
     this.memo = resolveShellMemoOptions(options.memo, {
@@ -1516,7 +1500,7 @@ export class VercelCacheStore<
   // cross-family one reads as corrupt. See the class doc for passing a wider
   // hash (sha256) when many keys are live.
   private toStoreKey(key: string, family: CacheFamily): string {
-    return `${versionKeyPrefix(this.explicitVersion, FAMILY_VERSION[family])}rg:${family}:${key}`;
+    return `${versionKeyPrefix(FAMILY_VERSION[family])}rg:${family}:${key}`;
   }
 
   private async write(

package/src/handles/deferred-resolution.ts

@@ -116,8 +116,9 @@ function keptValues(resolved: ResolvedValue[]): unknown[] {
  * so a push the record leaves out must not be in the prelude either: it
  * rendered an element no HIT's hydration data matched (issue #1035). Which
  * pushes a record keeps is the capture funnel's decision (shell-capture.ts
- * deriveShellCaptureContext: today it leaves out a deferred loader push and
- * one holding a masked promise), not this function's.
+ * deriveShellCaptureContext: it leaves out a loader push whose settled value
+ * holds a masked promise, and one a live-lane loader made), not this
+ * function's.
  */
 export async function* resolvedHandleStream(
   handleStore: HandleStore,

package/src/handles/meta.ts

@@ -231,6 +231,11 @@ function collectMeta(segments: MetaDescriptor[][]): MetaDescriptor[] {
  * (resolve-by-default), so they participate in deduplication and `%s`
  * title-templating identically to synchronous descriptors. A descriptor that
  * resolves to `null`/`undefined` (or rejects) is dropped.
+ *
+ * On a ppr route, a descriptor a handler or an `ssr: false` loader pushes,
+ * promise or not, is in the shell's `<head>` on every HIT (#1182). One a
+ * loader without `ssr: false` pushes is live: on a HIT it arrives after
+ * hydration.
  */
 export const Meta: Handle<MetaDescriptor, MetaDescriptor[]> = createHandle<
   MetaDescriptor,