@rangojs/router 0.17.0 → 0.18.0

package/skills/prerender/SKILL.md

@@ -20,8 +20,9 @@ The handler code and its imports are removed from the production bundle.
 
 ## Not this skill if…
 
-- You want a cached HTML shell captured at runtime, with holes and loaders
-  staying live per request — see `/ppr`.
+- You want a cached HTML shell captured at runtime, with holes staying live
+  per request (loaders without `ssr: false` run per request; `ssr: false`
+  loaders bake) — see `/ppr`.
 - You want runtime segment caching with TTL/SWR — that is the `cache()` DSL:
   see `/caching`. Prerender is the same cache filled at build time.
 - You are unsure which cache layer you need — start at `/cache-guide`.
@@ -244,15 +245,14 @@ In client and SSR environments, ALL prerender handlers are always stubbed.
 ## Sub-use Semantics
 
 Everything inside the path's use() callback is part of the pre-rendered route
-subtree (the "B segment" in the design docs) and gets pre-rendered. Loaders are
-the exception — they stay live:
+subtree and gets pre-rendered. Loaders are the exception — they stay live:
 
 ```typescript
 path("/blog/:slug", BlogPost, { name: "blog.post" }, () => [
-  layout(<PostLayout />, () => [        // inside B -> pre-rendered
+  layout(<PostLayout />, () => [        // inside the route -> pre-rendered
     loader(PostMetaLoader),              // live at runtime, bundled normally
   ]),
-  parallel({ "@sidebar": BlogSidebar }), // inside B -> pre-rendered
+  parallel({ "@sidebar": BlogSidebar }), // inside the route -> pre-rendered
 ])
 ```
 
@@ -327,9 +327,16 @@ implicitly re-run outer prerender-derived handlers/layouts.
 ## Prerender + PPR Build Shells
 
 A `Prerender` page may also declare `ppr` on the path option. The build still
-stores the Flight payload first. After that, a build-shell step ("producer B"
-in the design docs) tries to bake the HTML shell for each generated URL so the
-first document request can be an `x-rango-shell: HIT`.
+stores the Flight payload first. After that, the build-time shell capture
+tries to bake the HTML shell for each generated URL so the first document
+request can be an `x-rango-shell: HIT`. A route partitioned by
+`cache({ key })` or a store `keyGenerator` never serves that build shell (the
+build captured one partition); each partition captures at runtime, a
+once-per-route warning says so, and a `keyGenerator` that returns the default
+key unchanged keeps it. When the route's `cache()` scope (its own, or one
+inherited from a layout) refuses a request — `cache(false)`, or a
+`condition()` that returns false — that request gets no shell at all, the
+build shell included: it renders like a cache miss.
 
 That shell capture is request-shaped enough to run middleware safely:
 
@@ -362,14 +369,15 @@ entry STILL serves and a runtime recapture is scheduled that upgrades it in plac
 (SWR is the upgrade path from build entry → fresher runtime entry). Because the
 `Prerender` handler is evicted from the production bundle, that recapture never
 re-runs the handler — it replays the same build-time segments and only refreshes
-`cache()`-scoped data baked into the shell. **If nothing in the shell is
-`cache()`-backed, `ttl` has nothing to refresh** — reach for `updateTag` (or a
+what the capture reads again: `cache()`-scoped data baked into the shell, and
+the data of `ssr: false` loaders, which run at every capture. **If the shell
+bakes neither, `ttl` has nothing to refresh** — reach for `updateTag` (or a
 redeploy) instead of a shorter `ttl`.
 
-`ctx.dynamic()` opts a request off the shell axis ONLY. A `Prerender` route has
+`ctx.dynamic()` opts a request off the shell ONLY. A `Prerender` route has
 no live handler to fall back to (it was evicted), so a `dynamic()` request still
-serves the build-baked segments — fresh loaders in their holes, not a fresh
-handler render. There is no "fully dynamic" render for a prerendered route.
+serves the build-baked segments — fresh loaders, not a fresh handler render.
+There is no "fully dynamic" render for a prerendered route.
 
 ## Dev Mode
 
@@ -635,6 +643,11 @@ Passthrough entries are logged distinctly:
 Loaders on pre-rendered routes run at request time. They are bundled normally
 and need `cache()` for caching. Do not use build-only APIs in loaders.
 
+The exception is an `ssr: false` loader on a `Prerender` + `ppr` route: the
+build-time shell capture runs it and bakes its settled data into the shell,
+and a shell HIT runs it only when its return carries promises (`/ppr` → "The
+bake lane"). The Flight payload collection itself still skips loaders.
+
 ### Build-time handle data is frozen
 
 Handle values pushed via `ctx.use()` DURING pre-rendering (handler pushes at

package/skills/rango/SKILL.md

@@ -26,7 +26,9 @@ with the shape, then pick a primitive.
   inside a cached render. They run **in parallel** right after middleware and
   **stream**, so data latency overlaps first paint instead of blocking it (a
   cache hit streams UI instantly while loaders resolve fresh alongside). Opt into
-  caching explicitly. See `/loader` → "Parallel and streaming".
+  caching explicitly. See `/loader` → "Parallel and streaming". The one
+  exception is a `ppr` route's `ssr: false` loader: it bakes into the shell
+  and runs on a shell HIT only when its return carries promises (`/ppr`).
 - **One identity, one store** — loaders, handles, cached fns, and actions are all
   `path#export`; all caches share one store. Entries expire by TTL/SWR, and are
   tagged via `cache({ tags })` or runtime `cacheTag(...tags)`; built-in stores
@@ -68,8 +70,9 @@ Reach for the next rung only when the one above doesn't fit — the higher rungs
 are immune to partial-revalidation staleness by construction.
 
 1. **A loader** (`loader()` + `useLoader()`). Loaders resolve fresh on every
-   pass — full renders, action revalidations, cache hits. Nothing to keep in
-   sync. If the data can be a loader, make it a loader.
+   pass — full renders, action revalidations, cache hits, PPR shell HITs (on a
+   `ppr` route, keep it off `ssr: false`, which bakes it into the shell).
+   Nothing to keep in sync. If the data can be a loader, make it a loader.
 2. **Middleware `ctx.set()`**. Route middleware wraps every render pass,
    including post-action revalidation and PE re-renders, so its variables are
    never stale. Right for request-shaped context: auth, session, locale.
@@ -114,7 +117,7 @@ stated, greppable contract.
 | guarantee loader output in the SSR HTML | `loader(L, { ssr: false })`        | /loader                 |
 | pre-render a route at build time        | `Prerender(...)` wrapper           | /prerender              |
 | feed live loaders from a cached shell   | replayed handle + `ctx.rendered()` | /shell-manifest         |
-| cache the HTML shell, keep loaders live | `ppr` path option                  | /ppr                    |
+| cache HTML shell, live loaders as holes | `ppr` path option                  | /ppr                    |
 | choose in-function vs CDN caching       | deployment cache boundary          | /deployment-caching     |
 | stream SSE / upgrade a WebSocket        | `path.stream()` / `path.any()`     | /streams-and-websockets |
 
@@ -123,15 +126,26 @@ stated, greppable contract.
 - `path()`/`include()` are always visible in `urls()`; config helpers are extractable.
 - **Cache decides freshness; `revalidate()` decides client-update.** Orthogonal; compose.
 - Loaders resolve fresh every request (even inside `cache()`) and never run twice/request.
+  The exception is a `ppr` route's `ssr: false` loader: it bakes into the shell
+  and runs on a shell HIT only when its return carries promises.
 - **The consumption-lane rule.** For every shared artifact (`cache()`,
   `"use cache"`, the PPR shell): server-side handler consumption
-  (`await ctx.use(loader)`) yields a BAKED copy — identity reads
-  (`cookies()`/`headers()`) are permitted there and the capture-time value
-  freezes into the shared artifact (a documented footgun; see `/caching` →
-  "Cache purity & tainted objects"). Client-side consumption (`useLoader` in
-  a `"use client"` component) is the LIVE lane. DSL `loader()` segments
-  follow their PPR lane (only `ssr: false` bakes; see `/ppr` → The loader
-  lane rule). Pinned by semantic-matrix row PPR3.
+  (`await ctx.use(loader)`) yields a BAKED copy — the capture-time value
+  freezes into the shared artifact. Identity reads (`cookies()`/`headers()`,
+  a `{ cache: false }` variable) inside that loader are permitted under
+  `cache()`/`"use cache"` (a documented footgun; see `/caching` → "Cache
+  purity & tainted objects") but REFUSE a PPR capture: the route serves
+  uncached until the read moves to a live loader. Client-side consumption
+  (`useLoader` in a `"use client"` component) is the LIVE lane. DSL
+  `loader()` segments follow their PPR lane (only `ssr: false` bakes; see
+  `/ppr` → The loader lane rule).
+- **A PPR shell HIT never runs a handler.** Everything a handler produces
+  (promises it passes under `<Suspense>`, async server components, handle
+  pushes, loaders it awaits) is shell material, as under `cache()`; a HIT
+  runs middleware and live loaders only (an `ssr: false` loader runs there
+  only when its return carries promises). Live data belongs in a loader without
+  `ssr: false`, read with `useLoader` under `loading()` or an inline
+  `<Suspense>`.
 - Inside `"use cache"`: `cookies()`/`headers()` and `ctx` side-effects
   (`set`/`header`/`setTheme`/`onResponse`/`setLocationState`) throw; `ctx.use(Handle)`
   is captured on miss and replayed on hit. A non-cacheable variable read
@@ -162,17 +176,22 @@ stated, greppable contract.
 Same words, different jobs — this is the most common source of the
 `revalidate()`-is-caching misread.
 
-| You may know                            | Maps to Rango axis | Watch out                                                                                                                                                                                                                                                                               |
-| --------------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Next.js `export const revalidate = N`   | **Axis 1** (cache) | Same word, opposite meaning. Next's `revalidate` is time-based cache expiry; Rango's `revalidate()` is **axis 2**. Use `cache({ ttl })` for the Next behavior.                                                                                                                          |
-| Next.js `revalidateTag` / `updateTag`   | **Axis 1** (cache) | Cache busting by tag. Tag via `cache({ tags })` / `cacheTag(...tags)`; invalidate with `updateTag(...tags)` (awaitable, read-your-own-writes) or `revalidateTag(...tags)` (background, non-blocking). Built-in stores index by tag. No `revalidatePath` (path-based busting); use tags. |
-| React Router / Remix `shouldRevalidate` | **Axis 2**         | This is the correct mental model for Rango's `revalidate()`.                                                                                                                                                                                                                            |
-| HTTP `Cache-Control` / ISR              | Deployment layer   | Complete-response deployment layer. A CDN hit bypasses Rango entirely; the store-backed middleware does not. See `/deployment-caching` and `/document-cache`.                                                                                                                           |
-| Next.js PPR (partial prerendering)      | HTML shell layer   | Same React primitive, different transport: Rango serves shells in-function after middleware. Ordinary `ppr` captures at runtime; `Prerender + ppr` captures at build. See `/ppr`, `/prerender`, and `/deployment-caching`.                                                              |
-| Remix/RR `loader`                       | live data          | Like Rango loaders, fresh per request — but Rango loaders run in parallel and stream (latency overlaps first paint), and can opt into caching on demand.                                                                                                                                |
+| You may know                            | Maps to Rango                | Watch out                                                                                                                                                                                                                                                                               |
+| --------------------------------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Next.js `export const revalidate = N`   | **Value freshness** (cache)  | Same word, opposite meaning. Next's `revalidate` is time-based cache expiry; Rango's `revalidate()` is **partial-render selection**. Use `cache({ ttl })` for the Next behavior.                                                                                                        |
+| Next.js `revalidateTag` / `updateTag`   | **Value freshness** (cache)  | Cache busting by tag. Tag via `cache({ tags })` / `cacheTag(...tags)`; invalidate with `updateTag(...tags)` (awaitable, read-your-own-writes) or `revalidateTag(...tags)` (background, non-blocking). Built-in stores index by tag. No `revalidatePath` (path-based busting); use tags. |
+| React Router / Remix `shouldRevalidate` | **Partial-render selection** | This is the correct mental model for Rango's `revalidate()`.                                                                                                                                                                                                                            |
+| HTTP `Cache-Control` / ISR              | Deployment layer             | Complete-response deployment layer. A CDN hit bypasses Rango entirely; the store-backed middleware does not. See `/deployment-caching` and `/document-cache`.                                                                                                                           |
+| Next.js PPR (partial prerendering)      | HTML shell layer             | Same React primitive, different transport: Rango serves shells in-function after middleware. Ordinary `ppr` captures at runtime; `Prerender + ppr` captures at build. See `/ppr`, `/prerender`, and `/deployment-caching`.                                                              |
+| Remix/RR `loader`                       | live data                    | Like Rango loaders, fresh per request — but Rango loaders run in parallel and stream (latency overlaps first paint), and can opt into caching on demand.                                                                                                                                |
 
-See `/cache-guide` for the axis-1 decision guide, `/loader` and `/route` for
-`revalidate()` (axis 2), and `/document-cache` for the edge layer.
+Next.js PPR and Rango's `ppr` also differ in the hole model: in Rango only
+loaders make holes. A handler's own promise under `<Suspense>` bakes into the
+shell, as under `cache()`.
+
+See `/cache-guide` for the cache decision guide, `/loader` and `/route` for
+`revalidate()` (partial-render selection), and `/document-cache` for the edge
+layer.
 
 ## Canonical shape
 
@@ -277,18 +296,18 @@ Grouped by concern — read when you need to…
 
 **Data & caching** — fetch, mutate, and cache:
 
-| Skill                 | Description                                                                                                                                                       |
-| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `/loader`             | Data loaders with `createLoader()` and `revalidate()`                                                                                                             |
-| `/server-actions`     | Mutations with `"use server"`, useActionState, validation, revalidation                                                                                           |
-| `/caching`            | Segment caching with memory or KV stores                                                                                                                          |
-| `/use-cache`          | Function-level caching with `"use cache"` directive                                                                                                               |
-| `/cache-guide`        | When to use `cache()` vs `"use cache"` — differences and decision guide                                                                                           |
-| `/document-cache`     | Store-backed complete-response middleware using Cache-Control policy                                                                                              |
-| `/deployment-caching` | Choose between in-function caches, store-backed responses, and an external CDN cache                                                                              |
-| `/ppr`                | PPR shell caching: cached shell served instantly, live holes resumed — a hole is a `loading()` subtree OR a pending promise under `<Suspense>` (no loader needed) |
-| `/prerender`          | Pre-render route segments at build time (Passthrough live fallback)                                                                                               |
-| `/shell-manifest`     | Replayed handles as cache metadata read by live loaders (frozen shell, batched live holes)                                                                        |
+| Skill                 | Description                                                                                                                                                           |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `/loader`             | Data loaders with `createLoader()` and `revalidate()`                                                                                                                 |
+| `/server-actions`     | Mutations with `"use server"`, useActionState, validation, revalidation                                                                                               |
+| `/caching`            | Segment caching with memory or KV stores                                                                                                                              |
+| `/use-cache`          | Function-level caching with `"use cache"` directive                                                                                                                   |
+| `/cache-guide`        | When to use `cache()` vs `"use cache"` — differences and decision guide                                                                                               |
+| `/document-cache`     | Store-backed complete-response middleware using Cache-Control policy                                                                                                  |
+| `/deployment-caching` | Choose between in-function caches, store-backed responses, and an external CDN cache                                                                                  |
+| `/ppr`                | PPR shell caching: cached shell served instantly, live holes resumed — a hole is a live loader read under `loading()` or an inline `<Suspense>`; handler output bakes |
+| `/prerender`          | Pre-render route segments at build time (Passthrough live fallback)                                                                                                   |
+| `/shell-manifest`     | Replayed handles as cache metadata read by live loaders (frozen shell, batched live holes)                                                                            |
 
 **Client & presentation** — build the client-side UX:
 

package/skills/route/SKILL.md

@@ -329,12 +329,17 @@ cache({ ttl: 60 }, () => [
 ]);
 ```
 
-The same read throws inside a `"use cache"` function body, where the value
-would be stored without being part of the key — pass it in as an argument
-instead. The guard does not follow derived values (a string copied out of
-`Session` and cached elsewhere is not tracked). Loaders are exempt — they run
-fresh on every request — but a `"use cache"` function a loader calls is not. Cacheable vars (the default) can be read freely
-inside cache scopes. See `/cache-guide` → "Context Variable Cache Safety".
+The same read throws inside a `"use cache"` function body, where the value would
+be stored without being part of the key — pass it in as an argument instead. The
+guard does not follow derived values (a string copied out of `Session` and
+cached elsewhere is not tracked). Under `cache()`, loaders are exempt — a DSL
+loader re-runs on every hit — but a `"use cache"` function a loader calls is
+not, and neither is a loader bound with its own `cache()` without a `key()` (any
+`key()` switches the check off, so it must include the value; `/loader` → "Cache
+Key"). On a `ppr` route the exemption does not cover a loader the shell capture
+waits for (`ssr: false`, or awaited by a handler via `ctx.use()`): the read
+refuses the capture. Cacheable vars (the default) can be read freely inside
+cache scopes. See `/cache-guide` → "Context Variable Cache Safety".
 
 ### Revalidation Contracts for Handler Data
 
@@ -543,7 +548,7 @@ interface HandlerContext<TParams = {}, TEnv = DefaultEnv, TSearch = {}> {
   build: boolean; // true while pre-rendering at build time
   dev: boolean; // true under Vite dev
   dynamic(): void; // opt this request out of PPR shell capture (see /ppr)
-  theme?: Theme; // plus setTheme?() — only when the router enables themes (/theme)
+  readonly theme?: Theme; // plus setTheme?() — only when the router enables themes; a read is guarded like cookies() (/theme)
 }
 ```
 

package/skills/router-setup/SKILL.md

@@ -163,7 +163,7 @@ interface RangoOptions<TEnv> {
   viewTransition?: "auto" | false; // Router-placed <ViewTransition> default (/view-transitions)
   warmup?: boolean; // Connection warmup after idle (default true)
   strictMode?: boolean; // Hydrate inside <React.StrictMode> (default true)
-  stateCookiePrefix?: string; // Prefix of the state cookie `{prefix}_{routerId}` (default "rango-state")
+  stateCookiePrefix?: string; // Prefix of the state cookie `{prefix}_{routerId}` and the fresh-reads cookie `{prefix}-fresh` (default "rango-state")
 
   // --- Request handling ---
   nonce?: (
@@ -752,7 +752,9 @@ the check.
   render counts in development. Production behavior is unchanged.
 - `stateCookiePrefix`: rename the state cookie that keys the client caches. The
   `_{routerId}` suffix is always kept so sibling apps on one origin do not
-  collide.
+  collide. The prefix also names the fresh-reads cookie `{prefix}-fresh`
+  (`rango-state-fresh` by default) that `updateTag()`/`revalidateTag()` set
+  on a store with per-isolate memos; a consent-manager list needs both names.
 - `nonce: () => true`: generate a CSP nonce per request and apply it to the
   router's inline scripts. Return a string to supply your own, or
   `false`/`""` to skip it for one request. Middleware reads it with

package/skills/scripts/SKILL.md

@@ -114,7 +114,10 @@ during navigation.
 > means it is silently dropped. If a loader must contribute an inline script
 > to the document, register it `loader(Def, { ssr: false })` so the
 > document render awaits the push; otherwise push from a handler (or use an
-> `async` config, which stays reactive).
+> `async` config, which stays reactive). On a `ppr` route a loader without
+> `ssr: false` never runs during the shell capture, so its inline/ordered
+> script is dropped on every shell HIT; with `ssr: false` the push bakes into
+> the shell.
 
 **Nonce caveat for soft-nav async.** The "nonce is applied automatically" claim
 holds for DOCUMENT-RENDERED scripts (they carry the nonce in the SSR HTML). An
@@ -185,6 +188,10 @@ Otherwise allow the vendor hosts. For GTM/GA4 (Google's wildcards): `script-src
 `frame-src https://*.googletagmanager.com` for the GTM `<noscript>` iframe. See
 [Google's CSP guide](https://developers.google.com/tag-platform/security/guides/csp).
 
+A per-request nonce also takes a `ppr` route off its shell: a shared shell
+cannot carry one request's nonce, so the route renders normally (no shell) and
+warns once per key. See `/ppr` → "What always renders without a shell".
+
 ## Not covered (do it yourself)
 
 - **`onLoad` / `onReady` / `onError`** — callbacks can't cross the server handle

package/skills/server-actions/SKILL.md

@@ -37,6 +37,17 @@ Actions mutate state; route handlers and loaders read the latest state. After
 an action finishes, Rango performs a server-side revalidation render for the
 matched route so the UI receives fresh segment output and loader data.
 
+Segments under a route `cache()` re-render fresh on that render (actions skip
+the route cache lookup and write). A loader with its own `cache()` and a
+`"use cache"` read return their stored entry, and a `ppr` route's stored shell
+is not evicted, unless the action invalidates their tags.
+`await updateTag(...tags)` purges them before the revalidation render, so the
+action's own response reads fresh (`revalidateTag()` gives that render fresh
+reads too; only its durable write runs in the background). On a store that keeps
+per-isolate memos (`CFCacheStore`, `VercelCacheStore`) the response also sets
+the fresh-reads cookie (`rango-state-fresh` by default), so the same user's next
+requests skip those memos (see `/caching` → "The fresh-reads cookie").
+
 The main control point is `revalidate((ctx) => ...)` on the segment that owns
 the data. Match specific actions by imported reference with `ctx.isAction()`;
 use raw `actionId` only when you intentionally need path or directory matching.

package/skills/shell-manifest/SKILL.md

@@ -9,8 +9,8 @@ argument-hint:
 Use this when a cached or prerendered shell has dynamic holes, and the live
 data layer needs to know **what the shell actually contains** — which
 products, which slots, which keys. The frozen render describes itself
-through a handle; loaders (always live) read that description and fetch
-exactly the dynamic data the shell needs, in one batch.
+through a handle; live loaders (no `ssr: false`) read that description and
+fetch exactly the dynamic data the shell needs, in one batch.
 
 Canonical case: a prerendered product list where prices must stay live.
 
@@ -32,16 +32,19 @@ batched.
 ## The mechanism (three features composed)
 
 1. **Handles record data at render time.** The handler pushes to a handle
-   (`ctx.use(Handle)`) while it renders — at build time for `Prerender`, on
-   the cache miss for `cache()`. (Loader bodies can push handles too — see
-   `/loader` — but a live loader's push is request-time and is NOT part of
-   the replayed artifact; a manifest handle must be pushed by the code that
-   gets frozen with the shell. An `ssr: false` loader on a `ppr` route is the
-   exception: its settled pushes are recorded and replayed, and its re-run
-   replaces them with its live pushes — `/ppr` "On a shell HIT".)
+   (`ctx.use(Handle)`) while it renders — at build time for `Prerender`, on the
+   cache miss for `cache()`. (Loader bodies can push handles too — see `/loader`
+   — but a live loader's push is request-time and is NOT part of the replayed
+   artifact; a manifest handle must be pushed by the code that gets frozen with
+   the shell. An `ssr: false` loader on a `ppr` route is the exception: its
+   settled pushes are recorded with the shell. On a HIT, one whose return has no
+   promises does not run (unless the capture marked it to run), so the recorded
+   pushes are what the page shows; one whose return carries promises runs on
+   every HIT, and its pushes replace the recorded ones — `/ppr` "On a shell
+   HIT".)
 2. **Replay on every hit.** Handle data is stored with the Flight payload
-   and replayed into the handle store on cache/prerender hits — handler code
-   does not re-run, but its pushes do.
+   and replayed into the handle store on cache, prerender and `ppr` shell
+   hits — handler code does not re-run, but its pushes do.
 3. **Loaders read after the render barrier.** A DSL loader can
    `await ctx.rendered()` (waits for all non-loader segments to settle —
    fresh render or replay alike), then `ctx.get(Handle)` returns the
@@ -185,7 +188,13 @@ const prices = await runLoader(PriceLoader, {
 
 This tests the loader's post-barrier logic. The real
 push → store → replay → barrier wiring is covered at the e2e tier (dev +
-production), like every cache-path behavior.
+production), like every cache-path behavior. On a `ppr` route,
+`serveShellRequest(router, url, { cacheStore })` from
+`@rangojs/router/testing/flight` runs the real capture and HIT in a unit test
+(react-server Vitest): serve the URL twice with the same store; the second
+response is a HIT, and its `flight` carries the live loader's output for the
+replayed ids. Call `resetShellTestState()` in `beforeEach`. Recipe:
+`/testing` → `serve-shell-request.md`.
 
 ## Related
 

package/skills/testing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: testing
-description: Test @rangojs/router apps — unit (loaders, middleware, server actions, handles, transition/clientUrls predicates), client components (renderRoute), RSC/Flight (renderServerTree, renderHandler), integration (dispatch), and e2e (dev+prod parity, progressive enhancement). Use when writing a unit test for a loader, middleware, action, or handler, setting up vitest for a Rango app, or testing a route end-to-end in dev and production.
+description: Test @rangojs/router apps — unit (loaders, middleware, server actions, handles, transition/clientUrls predicates), client components (renderRoute), RSC/Flight (renderServerTree, renderHandler, serveShellRequest for PPR shells), integration (dispatch), and e2e (dev+prod parity, progressive enhancement). Use when writing a unit test for a loader, middleware, action, or handler, setting up vitest for a Rango app, or testing a route end-to-end in dev and production.
 argument-hint: [layer]
 ---
 
@@ -108,8 +108,10 @@ Each primitive links to its sub-file (API + recipe + caveats).
 | navigation, hydration, PE parity, view transitions, real SSR                                                                       | e2e          | [`createRangoE2E` -> `parityDescribe`/`expectParity`](./e2e-parity.md)                                   | `@rangojs/router/testing/e2e`    |
 | a `"use cache"` hit in a handler (the body runs once across renders; the value round-trips)                                        | RSC unit     | [`renderHandler` + seeded `cacheStore`](./render-handler.md#a-use-cache-hit)                             | `@rangojs/router/testing/flight` |
 | a `"use cache"` hit in a loader (the same, in the react-server project)                                                            | RSC unit     | [`runLoader` + seeded `cacheStore`](./loader.md)                                                         | `@rangojs/router/testing`        |
+| a loader's own `cache()` (HIT, `updateTag()` of a tag its body recorded)                                                           | RSC unit     | [`runLoader` + `cache` + seeded `cacheStore`](./loader.md)                                               | `@rangojs/router/testing`        |
 | cache hit/miss/stale, prerender (= a cache hit by design)                                                                          | e2e + signal | [`assertCacheStatus` (header) / `assertCacheDecision` (telemetry sink)](./cache-prerender.md)            | `@rangojs/router/testing[/e2e]`  |
-| PPR shell HIT/MISS (`ppr` path option), shell store key / getShell after flush                                                     | e2e + signal | [`assertShellStatus` / `shellCacheKey` + store](./cache-prerender.md#ppr-shell-and-navigation-replay)    | `@rangojs/router/testing[/e2e]`  |
+| a `ppr` route's shell: MISS -> capture -> HIT, what the shell froze vs what a HIT renders live, tag eviction, navigation replay    | RSC unit     | [`serveShellRequest`](./serve-shell-request.md)                                                          | `@rangojs/router/testing/flight` |
+| PPR shell HIT/MISS in real HTML (`ppr` path option), shell store key / getShell after flush                                        | e2e + signal | [`assertShellStatus` / `shellCacheKey` + store](./cache-prerender.md#ppr-shell-and-navigation-replay)    | `@rangojs/router/testing[/e2e]`  |
 | generated route map drift vs runtime                                                                                               | unit (node)  | [`assertGeneratedRoutesMatch`](./reverse-and-types.md)                                                   | `@rangojs/router/testing`        |
 | a platform binding (`env.DB` / Durable Object / `env.R2`)                                                                          | unit/integr. | [your own double via `env`](./bindings.md)                                                               | (any primitive's `env` option)   |
 
@@ -125,7 +127,8 @@ Cross-references to the DSL skills: `/loader`, `/middleware`, `/server-actions`,
   [`predicates.md`](./predicates.md), [`reverse-and-types.md`](./reverse-and-types.md)
 - Unit (DOM): [`client-components.md`](./client-components.md)
 - RSC unit: [`flight.md`](./flight.md), [`server-tree.md`](./server-tree.md),
-  [`render-handler.md`](./render-handler.md)
+  [`render-handler.md`](./render-handler.md),
+  [`serve-shell-request.md`](./serve-shell-request.md)
 - Integration: [`response-routes.md`](./response-routes.md)
 - E2E: [`e2e-parity.md`](./e2e-parity.md), [`cache-prerender.md`](./cache-prerender.md)
 
@@ -134,24 +137,25 @@ Cross-references to the DSL skills: `/loader`, `/middleware`, `/server-actions`,
 Where each runtime export is documented (types such as `RunLoaderOptions` sit
 beside their function):
 
-| Entry                                     | Exports                                                                                                                                                      | Documented in                                    |
-| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------ |
-| `@rangojs/router/testing`                 | `runLoader`, `runLoaderResult`                                                                                                                               | [`loader.md`](./loader.md)                       |
-|                                           | `runMiddleware`                                                                                                                                              | [`middleware.md`](./middleware.md)               |
-|                                           | `runInRequestContext`, `createTestRequestContext`, `runWithRequestContext`, `toRequest`, `seedVariables`                                                     | [`server-actions.md`](./server-actions.md)       |
-|                                           | `runTransitionWhen`, `runClientRevalidate`                                                                                                                   | [`predicates.md`](./predicates.md)               |
-|                                           | `collectHandle`                                                                                                                                              | [`handles.md`](./handles.md)                     |
-|                                           | `dispatch`                                                                                                                                                   | [`response-routes.md`](./response-routes.md)     |
-|                                           | `assertCacheStatus`, `assertCacheDecision`, `parseCacheHeader`, `createCacheSink`, `filterCacheDecisions`                                                    | [`cache-prerender.md`](./cache-prerender.md)     |
-|                                           | `assertShellStatus`, `parseShellStatus`, `shellCacheKey`, `SHELL_STATUS_HEADER`, `assertPprReplayStatus`, `parsePprReplayStatus`, `PPR_REPLAY_STATUS_HEADER` | [`cache-prerender.md`](./cache-prerender.md)     |
-|                                           | `assertGeneratedRoutesMatch`, `diffGeneratedRoutes`                                                                                                          | [`reverse-and-types.md`](./reverse-and-types.md) |
-| `@rangojs/router/testing/dom`             | `renderRoute`                                                                                                                                                | [`client-components.md`](./client-components.md) |
-| `@rangojs/router/testing/flight`          | `renderToFlightString`, `normalizeFlight`, `assertFlightRuntimeAvailable`                                                                                    | [`flight.md`](./flight.md)                       |
-|                                           | `renderServerTree`, `findClientBoundaries`, `findElements`, `textContent`, `assertFlightTreeRuntimeAvailable`                                                | [`server-tree.md`](./server-tree.md)             |
-|                                           | `renderHandler`                                                                                                                                              | [`render-handler.md`](./render-handler.md)       |
-| `@rangojs/router/testing/flight-matchers` | `flightMatchers` (`toMatchFlight`, `toMatchFlightSnapshot`)                                                                                                  | [`flight.md`](./flight.md)                       |
-| `@rangojs/router/testing/vitest`          | `rangoTestConfig`, `rangoTestAliases`, `rangoInlineDeps`, `rangoUseClientTransform`, `rangoUseCacheTransform`                                                | [`setup.md`](./setup.md)                         |
-| `@rangojs/router/testing/e2e`             | `createRangoE2E` and its standalone helpers; the cache/shell status helpers above are re-exported here                                                       | [`e2e-parity.md`](./e2e-parity.md)               |
+| Entry                                     | Exports                                                                                                                                                      | Documented in                                        |
+| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------- |
+| `@rangojs/router/testing`                 | `runLoader`, `runLoaderResult`                                                                                                                               | [`loader.md`](./loader.md)                           |
+|                                           | `runMiddleware`                                                                                                                                              | [`middleware.md`](./middleware.md)                   |
+|                                           | `runInRequestContext`, `createTestRequestContext`, `runWithRequestContext`, `toRequest`, `seedVariables`                                                     | [`server-actions.md`](./server-actions.md)           |
+|                                           | `runTransitionWhen`, `runClientRevalidate`                                                                                                                   | [`predicates.md`](./predicates.md)                   |
+|                                           | `collectHandle`                                                                                                                                              | [`handles.md`](./handles.md)                         |
+|                                           | `dispatch`                                                                                                                                                   | [`response-routes.md`](./response-routes.md)         |
+|                                           | `assertCacheStatus`, `assertCacheDecision`, `parseCacheHeader`, `createCacheSink`, `filterCacheDecisions`                                                    | [`cache-prerender.md`](./cache-prerender.md)         |
+|                                           | `assertShellStatus`, `parseShellStatus`, `shellCacheKey`, `SHELL_STATUS_HEADER`, `assertPprReplayStatus`, `parsePprReplayStatus`, `PPR_REPLAY_STATUS_HEADER` | [`cache-prerender.md`](./cache-prerender.md)         |
+|                                           | `assertGeneratedRoutesMatch`, `diffGeneratedRoutes`                                                                                                          | [`reverse-and-types.md`](./reverse-and-types.md)     |
+| `@rangojs/router/testing/dom`             | `renderRoute`                                                                                                                                                | [`client-components.md`](./client-components.md)     |
+| `@rangojs/router/testing/flight`          | `renderToFlightString`, `normalizeFlight`, `assertFlightRuntimeAvailable`                                                                                    | [`flight.md`](./flight.md)                           |
+|                                           | `renderServerTree`, `findClientBoundaries`, `findElements`, `textContent`, `assertFlightTreeRuntimeAvailable`                                                | [`server-tree.md`](./server-tree.md)                 |
+|                                           | `renderHandler`                                                                                                                                              | [`render-handler.md`](./render-handler.md)           |
+|                                           | `serveShellRequest`, `resetShellTestState`                                                                                                                   | [`serve-shell-request.md`](./serve-shell-request.md) |
+| `@rangojs/router/testing/flight-matchers` | `flightMatchers` (`toMatchFlight`, `toMatchFlightSnapshot`)                                                                                                  | [`flight.md`](./flight.md)                           |
+| `@rangojs/router/testing/vitest`          | `rangoTestConfig`, `rangoTestAliases`, `rangoInlineDeps`, `rangoUseClientTransform`, `rangoUseCacheTransform`                                                | [`setup.md`](./setup.md)                             |
+| `@rangojs/router/testing/e2e`             | `createRangoE2E` and its standalone helpers; the cache/shell status helpers above are re-exported here                                                       | [`e2e-parity.md`](./e2e-parity.md)                   |
 
 ## Pre-push checklist
 

package/skills/testing/cache-prerender.md

@@ -119,17 +119,17 @@ expect(decision.segments?.[0].shouldRevalidate).toBe(true);
 
 ## PPR shell and navigation replay
 
-**DSL:** `ppr: true | PartialPrerenderProps` on a page route (see `/ppr`). **Not** the same header as `X-Rango-Cache` — shell is a second render axis.
-
-| Helper                                    | Import                               | Role                                                                                                                                                                                                                            |
-| ----------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `assertShellStatus(res, "HIT" \| "MISS")` | `@rangojs/router/testing` or `…/e2e` | Assert `x-rango-shell` on a **real document** Response                                                                                                                                                                          |
-| `parseShellStatus(res)`                   | same                                 | `"HIT" \| "MISS" \| null` (null = header absent / unrecognized)                                                                                                                                                                 |
-| `shellCacheKey(url, searchParams?)`       | same                                 | Production shell store key (`host+pathname+sorted search+:shell`) for `store.getShell` / custom stores. Pass your router's `cache.searchParams` config as the second argument when it sets one — the production key applies it. |
-| `SHELL_STATUS_HEADER`                     | same                                 | `"x-rango-shell"` constant                                                                                                                                                                                                      |
-| `assertPprReplayStatus(res, expected)`    | same                                 | Assert fresh/stale replay or a bounded bypass decision                                                                                                                                                                          |
-| `parsePprReplayStatus(res)`               | same                                 | Structured replay/bypass status, or null for an absent/unrecognized header                                                                                                                                                      |
-| `PPR_REPLAY_STATUS_HEADER`                | same                                 | `"x-rango-ppr-replay"` constant                                                                                                                                                                                                 |
+**DSL:** `ppr: true | PartialPrerenderProps` on a page route (see `/ppr`). **Not** the same header as `X-Rango-Cache` — the shell is cached separately from the segments.
+
+| Helper                                          | Import                               | Role                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| ----------------------------------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `assertShellStatus(res, "HIT" \| "MISS")`       | `@rangojs/router/testing` or `…/e2e` | Assert `x-rango-shell` on a **real document** Response                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `parseShellStatus(res)`                         | same                                 | `"HIT" \| "MISS" \| null` (null = header absent / unrecognized)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `shellCacheKey(url, searchParams?, partition?)` | same                                 | Production shell store key (`host+pathname+sorted search+:shell`, then `\|partition`) for `store.getShell` / custom stores. Pass your router's `cache.searchParams` config as the second argument when it sets one — the production key applies it. For a route whose `cache({ key })` or store `keyGenerator` partitions its record, pass what that function returns for the request as `partition`: the shell is partitioned the same way. Under nested keyed `cache()` boundaries, pass their `key()` results as an array, outermost first. |
+| `SHELL_STATUS_HEADER`                           | same                                 | `"x-rango-shell"` constant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `assertPprReplayStatus(res, expected)`          | same                                 | Assert fresh/stale replay or a bounded bypass decision                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `parsePprReplayStatus(res)`                     | same                                 | Structured replay/bypass status, or null for an absent/unrecognized header                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `PPR_REPLAY_STATUS_HEADER`                      | same                                 | `"x-rango-ppr-replay"` constant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 
 ### What unit can prove vs e2e
 
@@ -137,10 +137,11 @@ expect(decision.segments?.[0].shouldRevalidate).toBe(true);
 | -------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | **Unit** | store family + key identity | `MemorySegmentCacheStore` + `shellCacheKey(url)` + `putShell`/`getShell` / tag eviction — dogfood in `e2e/mini/test/shell-store-family.test.ts` and `src/testing/__tests__/shell-status.test.ts` |
 | **Unit** | header helper contract      | `assertShellStatus` on a Response that already carries the header (characterizes the helper; **never** invent a HIT to claim capture worked)                                                     |
+| **Unit** | real capture → HIT, replay  | `serveShellRequest(router, url, { cacheStore })` (react-server project); only the HTML step is stubbed — [`./serve-shell-request.md`](./serve-shell-request.md)                                  |
 | **E2E**  | live MISS → capture → HIT   | document GET, poll until `x-rango-shell: HIT` (background capture) — `e2e/shell-cache.test.ts`                                                                                                   |
 | **E2E**  | partial replay decision     | soft navigation to a warmed shell and `assertPprReplayStatus(response, { outcome: "HIT", freshness: "fresh" })`                                                                                  |
 
-`dispatch` is RSC-free: it never runs shell serve/capture. `renderHandler` only surfaces `ctx.dynamic()` opt-out, not bake/serve.
+`dispatch` is RSC-free: it never runs shell serve/capture. `renderHandler` only surfaces `ctx.dynamic()` opt-out, not bake/serve. The HIT contract — no handler runs, the handler output is the capture's copy, live loaders re-run — is asserted through `serveShellRequest`: count your handler's runs and a live loader's across a MISS and the HITs after it, and check that only the loader's moves ([`./serve-shell-request.md`](./serve-shell-request.md)). A route partitioned by `cache({ key })` or a store `keyGenerator` has a shell per partition: `serveShellRequest` reports the key the serve path resolved (`result.key`), and `shellCacheKey` takes the partition as its third argument.
 
 ### Recipe (e2e)
 
@@ -185,7 +186,7 @@ it("stores the shell under the production key", async () => {
 ## Caveats
 
 - The `X-Rango-Cache` header is emitted ONLY when the gate is on: `createRouter({ debugCacheSignal: true })` or `process.env.RANGO_TEST_SIGNALS === "1"`. Off by default — zero production surface. With the gate off, `assertCacheStatus` throws a clear "header missing" error.
-- `x-rango-shell` is always set on document GETs the serve path considered for a ppr route (no debug gate). Absent header = axis-1 fall-open or non-ppr.
+- `x-rango-shell` is always set on document GETs the serve path considered for a ppr route (no debug gate). Absent header = a normal render (no shell): the request fell open, or the route has no `ppr`.
 - v1 is COARSE: route-level, keyed by the route NAME (e.g. `product.detail`), NOT the URL pattern (`/products/:id`); not per-individual-segment. The signal is built from `ctx.routeKey`, so a pattern-shaped key never matches. (`parseCacheHeader` exposes the raw `{ routeKey: status }` map if you need it.)
 - Prerender is indistinguishable from a cache hit by design — no static `.html`/`.rsc` files, the worker handles every request and looks up a stored Flight payload; the browser cannot tell. Do not assert "prerendered" from the DOM. Assert via the signal (`assertCacheStatus(res, seg, "prerendered")`) and run prerender assertions in PRODUCTION mode (the build-time artifacts only exist after `pnpm build`).
 - In a Playwright e2e import the cache-status / shell-status helpers from the `/e2e` entry — the `@rangojs/router/testing` barrel is Vitest-only (it pulls a build-only virtual that does not resolve in a plain Playwright runner). Zero-prod-surface alternative for segment cache: the telemetry sink (`createCacheSink`/`filterCacheDecisions`), no header at all. Note: the non-RSC `dispatch()` primitive never emits either header — get the Response from the router's real RSC fetch path.
@@ -194,5 +195,5 @@ it("stores the shell under the production key", async () => {
 ## See also
 
 - `/caching`, `/prerender`, `/use-cache`, `/ppr` — the DSL this tests
-- Siblings: [`./e2e-parity.md`](./e2e-parity.md), [`./response-routes.md`](./response-routes.md)
+- Siblings: [`./e2e-parity.md`](./e2e-parity.md), [`./response-routes.md`](./response-routes.md), [`./serve-shell-request.md`](./serve-shell-request.md)
 - Long-form prose: [docs/testing.md](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/testing.md) — section "Cache, SWR, and prerender"

package/skills/testing/loader.md

@@ -27,6 +27,7 @@
 | `use`           | `UseResolver`                                                   | Dynamic resolver for `ctx.use(OtherLoader)` composition. `loaders` wins when both match.                                                                                                                                   |
 | `cacheStore`    | `SegmentCacheStore`                                             | Cache store backing `use cache` functions. Without one, a cached function bypasses and runs uncached (its taint/profile guards never fire).                                                                                |
 | `cacheProfiles` | `Record<string, CacheProfile>`                                  | Cache profiles, the `createRouter({ cacheProfiles })` shape.                                                                                                                                                               |
+| `cache`         | `PartialCacheOptions`                                           | Run the loader through the `cache()` a route binds it with (`loader(Loader, () => [cache({...})])` takes the same options), against `cache.store`, else `cacheStore`. See the caveat below.                                |
 | `stateCookie`   | `StateCookieSeed` (`{ prefix?, routerId?, version? }`)          | Customize the rango state cookie a loader calling `invalidateClientCache()` rotates (the name is always seeded — default `rango-state_router_0`).                                                                          |
 | `rendered`      | `boolean \| (() => void \| Promise<void>)`                      | Mock the `ctx.rendered()` render barrier so a loader that `await ctx.rendered()`s can be unit-tested. By default `ctx.rendered()` throws. `true` resolves immediately; a function controls timing/side effects.            |
 | `handles`       | `ReadonlyArray<readonly [Handle<any, any>, unknown]>`           | Seed the values `ctx.get(SomeHandle)` returns — the ACCUMULATED handle data read after `await ctx.rendered()`. Matched by handle reference. (Loader handle WRITES need no seed — see `runLoaderResult(...).handlePushes`.) |
@@ -122,8 +123,24 @@ it("asserts a loader's set-cookie + redirect (runLoaderResult)", async () => {
 - A `createLoader()` definition imported through the CLIENT build has its body dropped — `runLoader` throws a clear error pointing to the `rangoTestConfig()` preset or the raw body. A router using `Prerender()`/`createLoader()`/`Static()` now constructs in a bare test (each assigns a runtime fallback `$$id`); only the whole router _file_ may still need the plugin (its page modules pull app deps / `virtual:` modules).
 - No `cookies`/`headers` option: seed a cookie by passing a full Request with a Cookie header — `{ request: new Request(url, { headers: { Cookie: "sid=abc" } }) }`. (`search`/`method` are baked onto this request for you.)
 - `ctx.search` (typed) defaults to `{}`; `opts.search` only sets the raw `ctx.searchParams`. Seed the typed object with `searchData`. (The harness seeds `searchData` verbatim — it does NOT run a typed-search SCHEMA, so schema parsing/validation is e2e.)
-- `ctx.theme`/`ctx.setTheme` are NOT on the loader context — theme accessors are handler-only. (The `theme` option seeds the underlying request context for `use cache` theme resolution, but a loader body cannot read theme.) `redirect()` does no basename prefixing unless you seed `basename`.
+- `ctx.theme`/`ctx.setTheme` are NOT on the loader context — they are handler/middleware-only. The `theme` option seeds the request context's theme config, so a loader body reads the visitor's theme with `getRequestContext().theme` (seed the cookie through `request`). That read is guarded like `cookies()` (#971): allowed in a loader body, but it throws inside a `"use cache"` function. `redirect()` does no basename prefixing unless you seed `basename`.
 - A `"use cache"` hit needs real Flight, which loads only under the react-server condition. In the react-server project (a `*.rsc-test.ts` file, see [`./setup.md`](./setup.md)) with `cacheStore` seeded, the body runs once across `runLoader` calls and the value round-trips. The write is a background (`waitUntil`) task `runLoader` does not await: a call before it lands joins the still-running execution, a call after it reads the store (wait with `vi.waitFor` on a `cacheStore.setItem` spy). In the node project a call looks up the store but never writes, so every call runs the body. A function written with the directive needs `rangoUseCacheTransform()` in the project's `plugins` (see [`./render-handler.md`](./render-handler.md#a-use-cache-hit)).
+- The `cache` option runs the loader through the production loader-cache read-through, so it needs the react-server project for the same reason. A HIT returns the stored value without running the body and records the tags the body recorded when the entry was written, so `updateTag()` of one (inside `runInRequestContext(fn, { cacheStore })`) drops the entry. There is no in-flight join here: wait for the write before the next call, or that call misses too. A raw body is keyed by its function reference. `runLoaderResult(...).handlePushes` lists the body's pushes, so a HIT reports none (the replay into the page's handle store is not modeled).
+
+  ```ts
+  const load = () =>
+    runLoader(productLoader, {
+      params: { id: "1" },
+      cacheStore,
+      cache: { ttl: 300 },
+    });
+  await load(); // MISS: the body runs and calls cacheTag("product:1")
+  await vi.waitFor(() => expect(setItem).toHaveBeenCalledTimes(1));
+  await load(); // HIT: the body does not run
+  await runInRequestContext(() => updateTag("product:1"), { cacheStore });
+  await load(); // MISS again
+  ```
+
 - Platform bindings are yours to double via `env` (see `./bindings.md`).
 
 ## See also