@rangojs/router 0.17.0 → 0.19.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
@@ -782,8 +795,8 @@ At runtime, the cache-lookup middleware checks `ctx.isIntercept`:
   intercept-resolution middleware runs live. This handles `when` config conditions
   that prevented pre-rendering.
 
-The `when` config selector receives an `InterceptSelectorContext` with `from.pathname`
-which is unknown at build time. All intercepts are pre-rendered unconditionally;
+The `when` config selector receives an `InterceptSelectorContext` whose `from`
+location (the page being left) is unknown at build time. All intercepts are pre-rendered unconditionally;
 `when` is evaluated at runtime by the intercept-resolution middleware.
 
 ### Example: Pre-rendered route with intercept
@@ -807,7 +820,7 @@ layout(ShopLayout, () => [
     "@modal",
     ".detail",
     <ProductModal />,
-    { when: ({ from }) => from.pathname === "/shop" },
+    { when: ({ from }) => from.url.pathname === "/shop" },
     () => [loader(ProductLoader)],
   ),
 ])

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,16 +126,29 @@ 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.
-- Inside `"use cache"`: `cookies()`/`headers()` and `ctx` side-effects
+  (`await ctx.use(loader)`) yields a BAKED copy — the capture-time value
+  freezes into the shared artifact. Identity reads (`cookies()`/`headers()`/
+  `ctx.request.headers`, a `{ cache: false }` variable) inside that loader
+  are permitted under a route `cache()` (a documented footgun; see
+  `/caching` → "Cache purity & tainted objects"). They throw inside
+  `"use cache"` (when the cached function is the first to read the loader in
+  the request; an already-started loader's value is stored unchecked) and 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()`/`ctx.request.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
   (`createVar({ cache: false })`) throws too — see the correctness bullet below.
@@ -149,6 +165,23 @@ stated, greppable contract.
 - Nested caches: the outer cache window bounds the inner — an inner shorter TTL
   only applies when the enclosing cache recomputes; put a value in a loader if it
   must be fresher. See `/cache-guide` → "Combining Both".
+- **A predicate runs where its effect lands.** A server-tree `revalidate()`
+  decides what the server re-sends, so it runs on the server; an `intercept({
+when })` selector decides what the server renders, so it runs on the server;
+  a `clientUrls()` `revalidate()` and `transition({ when })` decide a browser
+  commit, so they run in the browser. A browser predicate sees URLs, params,
+  route names, history state and action data, never `get()`, `env` or handler
+  state; in a server `urls()` it is written inline (the build hoists it into a
+  client module) or imported from a `"use client"` module (`/view-transitions`).
+- **Vocabulary.** `revalidate()` keeps React Router's `shouldRevalidate`
+  dialect (`currentUrl`/`nextUrl`, `currentParams`/`nextParams`). Navigation
+  selectors (`intercept({ when })`, `transition({ when })`) use `from`/`to`
+  locations (`{ url, params, routeName }`, plus `state` in the browser).
+- **A throwing predicate yields the conservative default.** For
+  `transition({ when })` that is no hold (an urgent commit) plus
+  `console.error`; for a `revalidate()` it is the default decision it would
+  have deferred to, logged; for an `intercept({ when })` selector it is no
+  intercept (the full page renders), logged with the route name.
 
 ## Don't confuse
 
@@ -162,17 +195,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 +315,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)
 }
 ```
 
@@ -603,6 +608,8 @@ whether the routes mount.
 
 A route can configure its own `transition()` — the wrap goes around the route's component itself (routes are leaves; they have no separate default outlet channel). If the route component renders a `<ParallelOutlet />` directly, that slot remains inside the route's VT subtree, so prefer mounting parallel slots in a layout when combining intercept modals with route-level transitions. See [skills/view-transitions](../view-transitions/SKILL.md) for examples and the wrap-location rules across layouts, routes, and slots.
 
+`transition({ when })` and `revalidate()` decide different things: `when` (a browser predicate) gates the hold, `revalidate()` decides whether the route segment is re-sent. A `revalidate()` returning false keeps the client's segment on a navigation whatever `when` returns, including a `ppr` navigation replayed from the shell.
+
 ## Handler-attached `.use`
 
 Page handlers can carry their own loader, middleware, error boundaries, parallels, and other defaults via a `.use` callback — so the page is self-contained and reusable across mount sites without re-wiring the same items.

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]
 ---
 
@@ -89,29 +89,32 @@ The single rule that drives everything:
 
 Each primitive links to its sub-file (API + recipe + caveats).
 
-| The behavior is…                                                                                                                   | Layer        | Primitive                                                                                                | Import root                      |
-| ---------------------------------------------------------------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------- | -------------------------------- |
-| a `reverse` / `href` / params / env TYPE contract (a wrong name or missing param must not compile)                                 | types (tsc)  | [`@ts-expect-error` / `expectTypeOf`](./reverse-and-types.md)                                            | `@rangojs/router/client` + `tsc` |
-| one loader's data logic                                                                                                            | unit (node)  | [`runLoader`](./loader.md)                                                                               | `@rangojs/router/testing`        |
-| a loader's cookie / header / thrown `redirect()`/`notFound()` / handle-push output                                                 | unit (node)  | [`runLoaderResult`](./loader.md)                                                                         | `@rangojs/router/testing`        |
-| one middleware's ordering / short-circuit / cookie+header merge                                                                    | unit (node)  | [`runMiddleware`](./middleware.md)                                                                       | `@rangojs/router/testing`        |
-| a `"use server"` action's cookie / header / flash output (even on `throw redirect()`)                                              | unit (node)  | [`runInRequestContext`](./server-actions.md)                                                             | `@rangojs/router/testing`        |
-| a `transition({ when })` gate (keep/drop) against nav source / target / action metadata                                            | unit (node)  | [`runTransitionWhen`](./predicates.md) (`{ kept, whenContext }`; `{ ppr: true }` for pre-handler timing) | `@rangojs/router/testing`        |
-| a `clientUrls()` `revalidate()` / `isAction(ref)` predicate                                                                        | unit (node)  | [`runClientRevalidate`](./predicates.md) (production chain evaluator + locked defaults)                  | `@rangojs/router/testing`        |
-| a handle's `collect`/accumulator, a seeded handle read, or a loader handle write                                                   | unit         | [`collectHandle` / seeded `handles` / `handlePushes`](./handles.md)                                      | `@rangojs/router/testing`        |
-| a CLIENT component reading router context (`useParams`/`useReverse`/`Outlet`/`useNavigation`/`useLoader`)                          | unit (DOM)   | [`renderRoute`](./client-components.md)                                                                  | `@rangojs/router/testing/dom`    |
-| a stale indicator from `useLoader().isLoading` while a `transition()` navigation re-runs the loader                                | unit (DOM)   | [`renderRoute` + `navigate(url, { loaders })`](./client-components.md#held-navigation)                   | `@rangojs/router/testing/dom`    |
-| a redirect / status / headers / cookies / **response route** (json/text/html/xml/md), no Flight                                    | integration  | [`dispatch`](./response-routes.md)                                                                       | `@rangojs/router/testing`        |
-| a real async **Server Component** (assert what it rendered: typed boundary props, server-rendered host content, inlined-vs-island) | RSC unit     | [`renderServerTree` + `findClientBoundaries`/`findElements`](./server-tree.md)                           | `@rangojs/router/testing/flight` |
-| the exact Flight **wire payload** shape (a drift snapshot)                                                                         | RSC unit     | [`renderToFlightString` + `toMatchFlightSnapshot`](./flight.md)                                          | `@rangojs/router/testing/flight` |
-| a real route **handler** `(ctx) => rsc` (params/loaders/vars -> rendered RSC + effects)                                            | RSC unit     | [`renderHandler`](./render-handler.md)                                                                   | `@rangojs/router/testing/flight` |
-| 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`        |
-| 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]`  |
-| 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)   |
+| The behavior is…                                                                                                                   | Layer        | Primitive                                                                                             | Import root                      |
+| ---------------------------------------------------------------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------- | -------------------------------- |
+| a `reverse` / `href` / params / env TYPE contract (a wrong name or missing param must not compile)                                 | types (tsc)  | [`@ts-expect-error` / `expectTypeOf`](./reverse-and-types.md)                                         | `@rangojs/router/client` + `tsc` |
+| one loader's data logic                                                                                                            | unit (node)  | [`runLoader`](./loader.md)                                                                            | `@rangojs/router/testing`        |
+| a loader's cookie / header / thrown `redirect()`/`notFound()` / handle-push output                                                 | unit (node)  | [`runLoaderResult`](./loader.md)                                                                      | `@rangojs/router/testing`        |
+| one middleware's ordering / short-circuit / cookie+header merge                                                                    | unit (node)  | [`runMiddleware`](./middleware.md)                                                                    | `@rangojs/router/testing`        |
+| a `"use server"` action's cookie / header / flash output (even on `throw redirect()`)                                              | unit (node)  | [`runInRequestContext`](./server-actions.md)                                                          | `@rangojs/router/testing`        |
+| a `transition({ when })` browser predicate against `{ kind, from, to, action }`                                                    | unit (node)  | [`runTransitionWhen`](./predicates.md) (`{ applied, gatedOff, context }`)                             | `@rangojs/router/testing`        |
+| a `clientUrls()` `revalidate()` / `isAction(ref)` predicate                                                                        | unit (node)  | [`runClientRevalidate`](./predicates.md) (production chain evaluator + locked defaults)               | `@rangojs/router/testing`        |
+| a handle's `collect`/accumulator, a seeded handle read, or a loader handle write                                                   | unit         | [`collectHandle` / seeded `handles` / `handlePushes`](./handles.md)                                   | `@rangojs/router/testing`        |
+| a CLIENT component reading router context (`useParams`/`useReverse`/`Outlet`/`useNavigation`/`useLoader`)                          | unit (DOM)   | [`renderRoute`](./client-components.md)                                                               | `@rangojs/router/testing/dom`    |
+| a stale indicator from `useLoader().isLoading` while a `transition()` navigation re-runs the loader                                | unit (DOM)   | [`renderRoute` + `navigate(url, { loaders })`](./client-components.md#held-navigation)                | `@rangojs/router/testing/dom`    |
+| a component reading `useLocationState(Def)` after `router.push(url, { state: [Def(value)] })`                                      | unit (DOM)   | [`renderRoute` + `withLocationStateKey`](./client-components.md#location-state)                       | `@rangojs/router/testing[/dom]`  |
+| a redirect / status / headers / cookies / **response route** (json/text/html/xml/md), no Flight                                    | integration  | [`dispatch`](./response-routes.md)                                                                    | `@rangojs/router/testing`        |
+| a real async **Server Component** (assert what it rendered: typed boundary props, server-rendered host content, inlined-vs-island) | RSC unit     | [`renderServerTree` + `findClientBoundaries`/`findElements`](./server-tree.md)                        | `@rangojs/router/testing/flight` |
+| the exact Flight **wire payload** shape (a drift snapshot)                                                                         | RSC unit     | [`renderToFlightString` + `toMatchFlightSnapshot`](./flight.md)                                       | `@rangojs/router/testing/flight` |
+| a real route **handler** `(ctx) => rsc` (params/loaders/vars -> rendered RSC + effects)                                            | RSC unit     | [`renderHandler`](./render-handler.md)                                                                | `@rangojs/router/testing/flight` |
+| 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]`  |
+| 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)   |
 
 Cross-references to the DSL skills: `/loader`, `/middleware`, `/server-actions`,
 `/handler-use`, `/hooks`, `/response-routes`, `/route`, `/caching`, `/prerender`,
@@ -125,7 +128,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 +138,26 @@ 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)                         |
+|                                           | `withLocationStateKey`                                                                                                                                       | [`client-components.md`](./client-components.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