@rangojs/router 0.18.0 → 0.19.0

package/skills/ppr/SKILL.md

@@ -51,7 +51,9 @@ only prerequisite is an app-level `createRouter({ cache })` store that
 implements the shell family (`getShell`/`putShell`): `MemorySegmentCacheStore`
 (dev/tests), `CFCacheStore` (Cache API L1 + optional KV L2), or
 `VercelCacheStore` (Vercel Runtime Cache). A ppr route on a store without the
-family renders normally (no shell) with a once-per-key warning.
+family renders normally (no shell) with a once-per-key warning. A custom store
+returns each `ShellCacheEntry` field as `putShell` received it, including
+`buildVersion` and `snapshot` (both required; the snapshot can be empty).
 
 ```typescript
 import { createRouter, urls } from "@rangojs/router";
@@ -138,7 +140,8 @@ lifetime. A HIT never runs a handler. To keep a value fresh per request, load
 it in a loader without `ssr: false` and read it with `useLoader` under
 `loading()` or an inline `<Suspense>`; inside an `ssr: false` loader, return
 that part as a nested promise. Request-scoped reads the capture now waits for
-refuse it: `cookies()`, `headers()`, a `{ cache: false }` variable, and
+refuse it: `cookies()`, `headers()`, `ctx.request.headers`, a
+`{ cache: false }` variable, and
 `ctx.dynamic()` inside a handler promise, an async component, a handle push, or
 a loader a handler awaits. A normal `ctx.get()` value is not guarded: shell
 material is shared per host+URL and request partition. `cache(false)`, or a
@@ -163,12 +166,17 @@ cache(
 
 The partition follows nested scopes (issue #970): a `ppr` route under a
 `cache()` nested in a keyed one is partitioned by the outer `key()` when the
-inner boundary has none, and by both composed (outermost first, each
-URI-encoded, joined by `|`) when it has its own. The route's record adds the
-inner boundary's own default key when it has no `key`; the shell partition
-does not, since the shell key already carries the URL (a store
-`keyGenerator`'s result is kept when it adds anything). See `/caching`,
-"Keys nest".
+inner boundary has none, and by both composed (outermost first, joined by
+`|`) when it has its own. Each `key()` result is namespaced as `key:` plus
+its URI encoding (issue #975), exactly as in the record key, so the shell of
+`key: () => "tier:gold"` is `<host><path>:shell|key%3Atier%253Agold`. The
+route's record adds the inner boundary's own default key when it has no
+`key`; the shell partition does not, since the shell key already carries the
+URL (a store `keyGenerator`'s result is kept when it adds anything, an
+enclosing `cache({ store })`'s on another store included, issue #974). An
+enclosing `condition()` that refuses the request means no shell, as the
+route's own does. See `/caching`, "Keys nest" and "Conditions and tags
+inherit".
 
 ```tsx
 cache({ ttl: 300, key: (ctx) => `tier:${tierOf(ctx)}` }, () => [
@@ -180,8 +188,11 @@ cache({ ttl: 300, key: (ctx) => `tier:${tierOf(ctx)}` }, () => [
 ```
 
 This is the sanctioned way to vary shell material by request: the capture
-guards still refuse `cookies()`/`headers()` in handler work, while the key
-function reads what it needs (`cookies()` included). A `key()` runs once per
+guards still refuse `cookies()`/`headers()`/`ctx.request.headers` in handler
+work, while the key function, a store `keyGenerator`, a `condition()` and a `tags()` function read
+what they need (`cookies()` and `ctx.request.headers` included, at capture
+too). To render the partition value, copy it in middleware with `ctx.set()`
+and read `ctx.get()` in the handler (see `/middleware`). A `key()` runs once per
 request: the shell read, the record lookup and the capture share its result
 (each `key()` of a nested chain once).
 One that throws serves no shell (like the record path renders uncached); a
@@ -209,9 +220,11 @@ value of it.
 
 In tests, `serveShellRequest` reports the key the serve path resolved
 (`result.key`, partition included); `shellCacheKey(url, searchParams,
-partition)` builds the same key from the partition. Under nested keyed
-scopes, pass the `key()` results as an array, outermost first
-(`shellCacheKey(url, undefined, ["tier:gold", "v:a"])`).
+partition)` builds the same key from the `key()` result, namespacing it as
+production does. Under nested keyed scopes, pass the `key()` results as an
+array, outermost first (`shellCacheKey(url, undefined, ["tier:gold",
+"v:a"])`); for a store `keyGenerator` partition pass
+`{ keys, generated }` (`/testing`, `cache-prerender.md`).
 
 ## Where PPR sits: the cache onion
 
@@ -321,8 +334,8 @@ replay its eligible snapshot. In both cases `matchPartial()`:
 - keeps the existing prefetch key, source scope, and in-flight lock unchanged.
 
 This is deliberately invisible to the browser: the response is the same
-`RscPayload` shape as any other partial navigation. Captured item/response values
-are NOT replayed on this path. Bake-lane loader pins are, when the replayed
+`RscPayload` shape as any other partial navigation. A shell snapshot holds no
+`"use cache"` or loader `cache()` values. Bake-lane loader pins are, when the replayed
 snapshot is a shell a document request captured, as on a document HIT: a
 promise-free `ssr: false` loader is served from its pin without running
 (unless the capture marked it to run: see "On a shell HIT"), and one whose
@@ -352,13 +365,20 @@ backend failure (`CACHE_READ_ERROR`) — also never falls back: it renders
 uncached, exactly as without ppr. (Document requests treat the same two
 opt-outs as a cache miss before any shell read: see the serve pipeline above.)
 
-`transition({ when })` is evaluated from the
-matched manifest before route handlers on every PPR match, so it can vary by
-URL/params/action or middleware context without disabling replay; handler-set
-context is unavailable by design. Intercepts, an active nonce, and an
+`transition({ when })` is a browser predicate: the server never evaluates
+it, so a shell, a replay and a cache entry never hold a decision. The route
+carries it as a client reference (attached right before Flight on every
+match, never stored), and the browser decides each navigation from
+`{ kind, from, to }`. Location state middleware sets reaches `to.state` on a
+replay `HIT` (middleware runs on every HIT); a handler's does not (a HIT runs
+no handler). The decision gates only how the browser commits; it never makes
+a replay send a segment. A replay `HIT`
+makes the same segment decision as the live partial path: a segment the client
+holds that the navigation does not re-send (`revalidate()` false, or a layout
+the default keeps) is omitted from the response, so the client keeps its tree
+(a list the client built up, "Load more" style, stays as it is). Intercepts, an active nonce, and an
 absent/corrupt segment snapshot fall open to the ordinary partial path when
-encountered by the shell capture. A transition already replayed from an
-explicit cache tier remains frozen by that tier's normal semantics.
+encountered by the shell capture.
 
 Two more decisions are made before any shell-store read, so probes and
 prerendered routes never spend passive `getShell` I/O:
@@ -413,17 +433,17 @@ consumer-invisible.
 
 The bounded bypass tokens, grouped by when they are decided:
 
-| Token                                                                             | Decided           | Meaning                                                                                                                                                                                                              |
-| --------------------------------------------------------------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `method`, `dynamic`, `nonce`, `store-unavailable`, `passive-read-unsupported`     | pre-read          | request/route/store ineligible for replay                                                                                                                                                                            |
-| `no-navigation-context`                                                           | pre-read          | no `X-RSC-Router-Client-Path`/`Referer`; a partial match is impossible                                                                                                                                               |
-| `prerender-store`                                                                 | pre-read or match | `Prerender()` route served by its baked artifact (pre-read probe of the normal variant; reclassified post-match when the store actually served, either variant)                                                      |
-| `intercept`                                                                       | match             | the navigation resolved to an intercept — replay is never armed for intercepts (they keep their normal cache path); no heal capture                                                                                  |
-| `cache-disabled`                                                                  | pre-read or match | `cache(false)` (pre-read, static) or `condition()` false (decided at the lookup); consumer opt-out is absolute                                                                                                       |
-| `read-error`, `no-entry`, `invalid-version`, `corrupt-entry`, `stale-build-entry` | shell read        | no usable shell entry (`no-entry`/`invalid-version`/`corrupt-entry`/`stale-build-entry` schedule the navigation-only heal capture)                                                                                   |
-| `no-segment-snapshot`                                                             | eligibility       | entry exists but its snapshot has no recorded segments for the page; on a route with an enabled `cache()` scope, it heals when the lookup did not refuse (a `condition()` false-at-capture entry becomes replayable) |
-| `explicit-cache-hit`                                                              | match             | the route's own `cache()` tier supplied the match                                                                                                                                                                    |
-| `snapshot-miss`                                                                   | match             | an eligible snapshot was seeded but matching did not consume it                                                                                                                                                      |
+| Token                                                                         | Decided           | Meaning                                                                                                                                                                                                              |
+| ----------------------------------------------------------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `method`, `dynamic`, `nonce`, `store-unavailable`, `passive-read-unsupported` | pre-read          | request/route/store ineligible for replay                                                                                                                                                                            |
+| `no-navigation-context`                                                       | pre-read          | no `X-RSC-Router-Client-Path`/`Referer`; a partial match is impossible                                                                                                                                               |
+| `prerender-store`                                                             | pre-read or match | `Prerender()` route served by its baked artifact (pre-read probe of the normal variant; reclassified post-match when the store actually served, either variant)                                                      |
+| `intercept`                                                                   | match             | the navigation resolved to an intercept — replay is never armed for intercepts (they keep their normal cache path); no heal capture                                                                                  |
+| `cache-disabled`                                                              | pre-read or match | `cache(false)` (pre-read, static) or `condition()` false (decided at the lookup); consumer opt-out is absolute                                                                                                       |
+| `read-error`, `no-entry`, `invalid-version`, `corrupt-entry`                  | shell read        | no usable shell entry (`no-entry`/`invalid-version`/`corrupt-entry` schedule the navigation-only heal capture)                                                                                                       |
+| `no-segment-snapshot`                                                         | eligibility       | entry exists but its snapshot has no recorded segments for the page; on a route with an enabled `cache()` scope, it heals when the lookup did not refuse (a `condition()` false-at-capture entry becomes replayable) |
+| `explicit-cache-hit`                                                          | match             | the route's own `cache()` tier supplied the match                                                                                                                                                                    |
+| `snapshot-miss`                                                               | match             | an eligible snapshot was seeded but matching did not consume it                                                                                                                                                      |
 
 ### Capture-generation invalidation
 
@@ -522,10 +542,9 @@ curl -s -D - -o /dev/null https://app.example.com/products/1 | grep -i x-rango-s
   capture diagnoses itself. A stored attempt reports `recordSettleMs`
   (`record=` in the log line): how long the capture waited for the handler
   layer to settle (promises it passes or pushes, async server components,
-  loaders it awaits) and its segment record to encode; `bakeWaitMs` (`bake=`):
-  how long the slowest remaining bake source (a top-level pushed handle promise
-  or a bake-lane loader container) held the capture gate; and `entryBytes`
-  (`entry=`): the stored entry's size. In dev, past 2s, the slow source is also
+  loaders it awaits, top-level pushed handle promises and bake-lane loader
+  containers) and its segment record to encode; and `entryBytes` (`entry=`):
+  the stored entry's size. In dev, past 2s, the settle is also
   named once per key in a console warning with the remedies (`cache()` the
   work / move it into a live loader / return it as a nested promise or drop
   `ssr: false` in a bake-lane loader). In dev, with
@@ -776,7 +795,9 @@ identifiers — served to anonymous visitors.)
   consumer's `<Suspense>` on every HIT (the same mask as bake-lane loader data,
   at any depth of plain objects, arrays and JSX props; a promise inside a
   `Map`, `Set`, or class instance is not masked). A live-lane
-  loader never runs at capture, so all of its pushes happen per request.
+  loader never runs at capture unless a handler or an `ssr: false` loader
+  awaits it; either
+  way its pushes, and those of the loaders it awaits, are live on every HIT.
 
 ### Want a hole for already-resolved data?
 
@@ -865,18 +886,41 @@ loader(ProductLoader, { ssr: false }), // promise-free: baked, not run on a HIT
 loader(ReviewsLoader),                 // live: the hole, under loading()
 ```
 
+**A hole never reads the shell's copy of a value.** The shell stores its
+recorded segments and the `ssr: false` loaders' baked containers, and no
+`"use cache"` or loader `cache()` value. Every cache read on a HIT goes to
+the store: a live loader's, a nested promise's, and the body of an
+`ssr: false` loader that runs on the HIT. So a live loader that reads the
+same `"use cache"` key as an `ssr: false` loader shows the store's current
+value once it refreshes, while the baked container keeps the capture's. If a
+hole needs a stable value, give it its own cache (`"use cache"` with a
+profile, or a loader `cache()`); the shell never provides one.
+
 **Handle pushes from a bake-lane loader appear once.** The capture records
 the settled, thenable-free handle pushes of every loader body it runs (the
 prelude rendered them): the `ssr: false` loader's own, those of the loaders
-it awaits with `ctx.use()`, and those its own `cache()` entry replays. Every HIT restores them with the handler layer. A
-loader that does run on the HIT (a hole-carrying bake-lane loader, or a live
-loader awaiting the same loader) replaces its restored pushes in place, so
-any handle, deduping or not, shows each value once; a push that lands after
-the document's handle snapshot reaches the client after hydration. A push the
-capture cannot record (a deferred push, or one holding a promise) marks the
-loader records to run: those
-bodies then still run on each HIT, in the background, so the push reaches the
-page.
+it awaits with `ctx.use()`, and those its own `cache()` entry replays. Every
+HIT restores them with the handler layer, and they stand: a bake-lane loader
+that does run on the HIT (a hole-carrying one) reads the store, so its settled
+pushes, and those a `"use cache"` hit inside its body replays, are dropped
+instead of replacing the restored ones. Any handle, deduping or not, shows
+each value once, and it is the value the prelude rendered. A loader the route
+also registers on the live lane is a hole: its live run replaces its restored
+pushes, and those of the loaders it awaits, so they show its live value, even
+when a bake-lane loader running on the HIT awaits it. A run that throws or
+makes no push shows none of the capture's once its run ends; a hole slower
+than the handler barrier shows the shell's copy in the first snapshot until
+then. A hole with its own loader `cache()` that hits shows the pushes that
+entry recorded, none if it recorded none, matching its data. A dependency the route does not
+register, which an `ssr: false` loader awaited at capture outside any live
+loader, is on neither lane: its settled pushes stay as the prelude rendered
+them, even where a live loader also awaits it, while its data is fresh. To
+keep its pushes live, declare it as its own `loader()` on the route. A push the capture cannot record (a
+deferred push, or one holding a promise) marks every loader record of the
+page to run: those bodies then still run on each HIT, in the background, and
+that push reaches the page (from the loader's own `cache()` entry when it
+hits) with the run's value; a push that lands after the document's handle snapshot
+reaches the client after hydration.
 
 Four hard edges (each e2e/unit-pinned):
 
@@ -893,7 +937,7 @@ Four hard edges (each e2e/unit-pinned):
   response. The one exception: a handler that calls `ctx.dynamic()` FIRST
   re-permits its own header/cookie write (#735) — a dynamic() render never
   HITs, so the write is deterministic (see "Opting out per request").
-- **Identity refuses.** `cookies()`/`headers()` inside a bake-lane loader
+- **Identity refuses.** `cookies()`/`headers()`/`ctx.request.headers` inside a bake-lane loader
   throws during capture and the capture REFUSES (deterministic, once-per-key
   warned) — identity can never bake into the shared shell. Drop the loader's
   `ssr: false` flag (the live lane is exempt; give it a boundary) or move the
@@ -921,7 +965,7 @@ Four hard edges (each e2e/unit-pinned):
 - **Baked containers show CAPTURE-time data** for the shell's lifetime on
   document GETs, and on soft navigations that replay a shell captured by a
   document request (`x-rango-ppr-replay: HIT`). Live loaders and their
-  item/response reads remain fresh. That IS the bake lane's meaning; if a value
+  `"use cache"` reads remain fresh. That IS the bake lane's meaning; if a value
   must be fresh on every serve, it belongs on the live lane (no `ssr: false`) or
   in a nested promise.
 
@@ -939,7 +983,8 @@ their data should bake vs stay live. Your levers, in order of preference:
    shared/config data returns as plain values (bakes, pinned per shell);
    per-request data returns as NESTED promises consumed under the widget's own
    `<Suspense>` (live holes). No `loading()`, no restructuring. One wall: a
-   bake-lane loader that reads `cookies()`/`headers()` refuses the capture —
+   bake-lane loader that reads `cookies()`/`headers()`/`ctx.request.headers`
+   refuses the capture —
    identity belongs on the live lane (a separate unflagged loader); a nested
    promise inside the flagged loader still runs during capture and trips the
    guard.
@@ -997,8 +1042,9 @@ The identity rule, stated once: per-user data on a PPR page lives in a
 live-lane loader (no `ssr: false`) consumed CLIENT-side with `useLoader` under
 `loading()` or an inline `<Suspense>`, or in a NESTED promise inside a
 bake-lane loader (a hole, fresh per request). A nested promise's body still
-runs at capture, so it must not call `cookies()`/`headers()` itself — identity
-reads belong in the live-lane loader. Reading `cookies()`, `headers()`, or a
+runs at capture, so it must not call `cookies()`/`headers()` or read
+`ctx.request.headers` itself — identity reads belong in the live-lane loader.
+Reading `cookies()`, `headers()`, `ctx.request.headers`, or a
 `{ cache: false }` variable anywhere the capture waits for refuses the capture
 by construction: handler/render code, a promise the handler passes or pushes,
 an async server component, a bake-lane loader, and a loader a handler awaits
@@ -1037,8 +1083,8 @@ Three levers, in preference order:
 
 Head material (Meta) pushed by HANDLERS cannot be a hole — the head is shell —
 so those promises bake by design; make them cheap with lever 2.
-`recordSettleMs` and `bakeWaitMs` on the capture debug event tell you what each
-capture actually paid. A
+`recordSettleMs` on the capture debug event tells you what each capture
+actually paid. A
 Meta pushed by a LIVE-lane loader is different: those loaders are masked at
 capture, so the push happens at request time and applies client-side
 (`metadata.handlesLate`) — it is never in the cached shell's head, by
@@ -1078,11 +1124,14 @@ serve-time: the commit point runs the full chain on EVERY serve.
 
 Because handlers on uncached segments EXECUTE during capture — along with
 everything they produce and every BAKE-lane loader — the capture guard is
-load-bearing: `cookies()`, `headers()`, a theme read, and a `{ cache: false }`
-variable read THROW during a capture render, and the capture
+load-bearing: `cookies()`, `headers()`, `ctx.request.headers`,
+`getRequestContext().cookie()` / `.cookies()`, a theme read, and a
+`{ cache: false }` variable read THROW during a capture render, and the capture
 is refused even when the code catches that throw, so identity can never leak
 into a shared shell through them. Live-lane loaders (every loader without
-`ssr: false`) are exempt: masked at capture, they never run there.
+`ssr: false`) are exempt when only a client component reads them: masked at
+capture, they never run there. One a handler or an `ssr: false` loader awaits
+runs at capture, and its identity reads refuse it.
 
 ## allReady: the SEO/bot story
 
@@ -1102,7 +1151,8 @@ middleware on every serve. A 401/redirect short-circuit returns before any
 shell byte.
 
 **(b) Request-scoped reads refuse the capture.** During the background capture
-render, `cookies()`, `headers()`, the visitor's theme (`ctx.theme`,
+render, `cookies()`, `headers()`, the raw reads `ctx.request.headers` and
+`getRequestContext().cookie()` / `.cookies()`, the visitor's theme (`ctx.theme`,
 `getRequestContext().theme`), and `ctx.get()` of a `{ cache: false }` variable
 (`createVar({ cache: false })`, or a value written with
 `ctx.set(..., { cache: false })`) THROW, wherever the capture waits for them:
@@ -1110,14 +1160,15 @@ a handler, a promise it passes or pushes, an async server component, a
 bake-lane loader, and a loader a handler awaits (`await ctx.use(Loader)`). The
 capture is refused even if your code catches the throw, and the route keeps
 serving MISSes with a once-per-key warning. `ctx.dynamic()` called there
-refuses it too. The live lane (no `ssr: false`) stays exempt: masked at capture, it never
-runs there.
+refuses it too. The live lane (no `ssr: false`) stays exempt when only a client
+component reads it; one a handler or an `ssr: false` loader awaits runs at
+capture, and its identity reads refuse it.
 
 **(c) Residual hazard — middleware-derived per-user state.** A NORMAL `ctx`
 variable (no `cache: false`) set by an upstream auth middleware and rendered by
 shell material is photographed into the SHARED shell (the capture inherits
-post-middleware state), and so is a raw `ctx.request.headers` read. The guard
-cannot see either. That is scope fidelity working as designed — for shared
+post-middleware state). The guard cannot see it. That is scope fidelity
+working as designed — for shared
 values. It reaches handlers and BAKE-LANE LOADERS alike: a loader reading a
 middleware-provided session object (`ctx.get("session")`) never calls
 `cookies()` itself, so whatever it returns as settled container data is
@@ -1183,13 +1234,13 @@ path(
 );
 ```
 
-| Field              | Default | Notes                                                                                                                                                                                                                                                                                                                                                    |
-| ------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ttl`              | `300`   | shell freshness window in seconds (`ppr: true` uses the default)                                                                                                                                                                                                                                                                                         |
-| `swr`              | —       | stale window: serve the stale shell + background recapture                                                                                                                                                                                                                                                                                               |
-| `tags`             | —       | operational tags UNIONED with the tags the capture collects — see "Invalidation" below                                                                                                                                                                                                                                                                   |
-| `maxSnapshotBytes` | 8 MiB   | cap on the loader pins in the entry's snapshot (bake-lane loader records and the cached items/responses those loaders read). The recorded handler layer is exempt. Over the cap the pins are dropped and the shell is stored with its handler layer (warned once per key); bake-lane loaders then read the live store, and drift is repaired client-side |
-| `captureTimeout`   | 15000ms | ONE capture deadline: the handler layer settling (promises it passes or pushes, async server components, loaders it awaits), bake-lane loaders, and the prerender; a capture that misses it stores nothing rather than a partial shell                                                                                                                   |
+| Field              | Default | Notes                                                                                                                                                                                                                                                                                                      |
+| ------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ttl`              | `300`   | shell freshness window in seconds (`ppr: true` uses the default)                                                                                                                                                                                                                                           |
+| `swr`              | —       | stale window: serve the stale shell + background recapture                                                                                                                                                                                                                                                 |
+| `tags`             | —       | operational tags UNIONED with the tags the capture collects — see "Invalidation" below                                                                                                                                                                                                                     |
+| `maxSnapshotBytes` | 8 MiB   | cap on the loader pins in the entry's snapshot (the bake-lane loader records). The recorded handler layer is exempt. Over the cap the pins are dropped and the shell is stored with its handler layer (warned once per key); bake-lane loaders then read the live store, and drift is repaired client-side |
+| `captureTimeout`   | 15000ms | ONE capture deadline: the handler layer settling (promises it passes or pushes, async server components, loaders it awaits), bake-lane loaders, and the prerender; a capture that misses it stores nothing rather than a partial shell                                                                     |
 
 A shell never outlives the route `cache()` entry it was captured from: under
 a route `cache()`, the shell is fresh no longer than that entry is (at most
@@ -1238,8 +1289,8 @@ render-callable `cacheTag()` in a plain server component (no
 `"use cache"`/`cache()` in its tree) — plus the tags of loaders on the BAKE
 lane (they execute during capture and their data is in the shell). A tag
 recorded outside what the shell renders is not on it. A live-lane loader's tags (every loader without `ssr: false`)
-attach only when a handler consumes its value with `ctx.use()`, which bakes
-it; one read only by the client stays off, since it is masked at capture and
+attach only when a handler or an `ssr: false` loader consumes its value with
+`ctx.use()`, which bakes it; one read only by the client stays off, since it is masked at capture and
 its hole is already live. `ppr.tags` adds
 operational tags the render cannot know (a tenant id, a deploy marker).
 
@@ -1267,7 +1318,7 @@ evicted by tag at all — move always-fresh data into a live-lane loader (no
 
 ## Pitfalls
 
-- **A bake-lane loader that reads `cookies()`/`headers()`**: the capture is
+- **A bake-lane loader that reads `cookies()`/`headers()`/`ctx.request.headers`**: the capture is
   REFUSED (deterministic, once-per-key warned) — the route keeps serving
   MISSes. Move identity onto the live lane (drop `ssr: false`, or split the read into
   a separate unflagged loader; give the reader a boundary). A nested promise
@@ -1299,8 +1350,9 @@ evicted by tag at all — move always-fresh data into a live-lane loader (no
   bake-lane loader data — plain BAKE-lane loader data bakes just like handler
   material.
 - **The session-object bake trap (the guard cannot save you here)**: the
-  capture guard sees `cookies()`, `headers()`, and `{ cache: false }` variable
-  reads ONLY. A handler or bake-lane loader reading a NORMAL middleware-provided
+  capture guard sees `cookies()`, `headers()`, `ctx.request.headers`, the theme
+  and `{ cache: false }` variable reads ONLY. A handler or bake-lane loader
+  reading a NORMAL middleware-provided
   session object (`ctx.get("session")`) refuses nothing. Inside a bake-lane
   loader, per-user data survives ONLY behind a nested promise — the shape is
   the declaration, and it holds for BOTH branches regardless of settle timing
@@ -1352,10 +1404,10 @@ evicted by tag at all — move always-fresh data into a live-lane loader (no
   same `"use cache"` entry reads it from the store on every HIT. It is still
   cached under its own profile; once the entry expires or is invalidated and
   refreshes, the hole shows the refreshed value next to the shell's old one. The
-  capture stores only what a HIT reads: every HIT replays the handler layer
-  from the captured segment record, so the `"use cache"` items only handler
-  code read are not stored. When a bake-lane loader read the same entry at
-  capture, the shell keeps it, and the hole gets that pinned value too.
+  shell stores no `"use cache"` value, only its recorded handler output and the
+  `ssr: false` loaders' baked containers. A hole reads the store even when a
+  bake-lane loader read the same entry at capture: the baked container keeps
+  the capture's value, and the hole shows the current entry.
 - **Uncached nondeterminism in server output is frozen, not drifting**: a raw
   `Date.now()` / `Math.random()` / uncached `fetch` in a handler or server
   component renders once per capture, and the prelude and every HIT show that

package/skills/prerender/SKILL.md

@@ -795,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
@@ -820,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

@@ -131,11 +131,13 @@ stated, greppable contract.
 - **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 — 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
+  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).
@@ -146,7 +148,7 @@ stated, greppable contract.
   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
+- 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.
@@ -163,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
 

package/skills/route/SKILL.md

@@ -608,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/testing/SKILL.md

@@ -89,31 +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`        |
-| 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)   |
+| 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`,
@@ -144,6 +145,7 @@ beside their function):
 |                                           | `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)         |