@rangojs/router 0.18.0 → 0.19.0

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

@@ -489,7 +489,7 @@ layout(<ShopLayout />, () => [
     "@modal",
     "product.detail",
     ProductQuickView,
-    { when: ({ from }) => from.pathname === "/products" },
+    { when: ({ from }) => from.url.pathname === "/products" },
     () => [
       loader(ProductLoader),
       loading(<QuickViewSkeleton />),
@@ -508,8 +508,10 @@ middleware, layout, loaders, loading state, and loader-level caching and
 `intercept()`) can choose by navigation source.
 
 This is integrated with the rest of the runtime rather than implemented as URL
-masking plus local component state. Intercepts get source-scoped prefetch entries
-so a modal Flight payload cannot leak into direct navigation. A prerendered target
+masking plus local component state. A route an intercept targets gets
+source-scoped prefetch entries whether or not the intercept applied, so neither a
+modal Flight payload nor a full page prefetched from another page is reused where
+the intercept decides differently. A prerendered target
 can store a separate intercept variant while its loaders still run live at
 request time. An action can revalidate the open intercept without remounting its
 subtree or forcing the preserved background to render. See the
@@ -578,7 +580,8 @@ the bounded cache uses a configurable TTL. `Save-Data`,
 Correctness is part of the prefetch contract. Keys include Rango state, destination
 URL, and the mounted segment set used to compute the diff. Server actions rotate
 state and abort stale speculative work; a generation check prevents a late result
-from repopulating an invalidated cache. Intercepts are automatically source-scoped,
+from repopulating an invalidated cache. Routes an intercept targets are automatically
+source-scoped, matched or not,
 and malformed, cross-origin, foreign-router, redirect, and reload responses are
 dropped rather than warmed. `useLinkStatus()` exposes `{ pending }` for the owning
 link.
@@ -754,7 +757,7 @@ from two hosts, route scopes, param sets, or query variants therefore does not
 collapse into one entry just because both calls received a `ctx` object.
 
 The same boundary guards operations whose meaning cannot survive a hit. Direct
-`cookies()`/`headers()` reads and request/response mutations such as `ctx.set()`,
+`cookies()`/`headers()`/`ctx.request.headers` reads and request/response mutations such as `ctx.set()`,
 `ctx.header()`, status, theme, and location-state writes throw inside
 `"use cache"`. If a cached function pushes typed handles through
 `ctx.use(Breadcrumbs)` or `ctx.use(Meta)`, Rango captures those pushes on a miss and

package/skills/document-cache/SKILL.md

@@ -219,6 +219,30 @@ the variant suffixes are still appended.
   error during the render. The current request still gets the errored render,
   the next request renders fresh, and on a stale refresh the stale entry keeps
   serving.
+- A page rendered with a visitor's stored theme other than `defaultTheme`.
+  That happens only when `Cache-Control` was set after the render (see
+  "Theme" below).
+
+## Theme
+
+With `theme` enabled, the page payload carries the theme `useTheme()` starts
+at (`initialTheme`). A page whose response opted in to this cache before
+`next()` starts it at the no-cookie default (`defaultTheme`), whoever rendered
+it (#978), so a visitor with no stored theme never inherits the theme of the
+visitor who warmed the entry. A visitor with a stored theme sees theirs after
+hydration, and the `<html>` class is right before paint either way (the theme
+script reads the cookie). Any other render, a 404 included, starts at the
+visitor's own theme.
+
+The render decides from the `Cache-Control` the handler or middleware set
+before `await next()`. A header set after `next()` (or in `onResponse`) arrives
+once the page is rendered, so the cache stores that response only when it was
+rendered with the default theme. Set `Cache-Control` in the handler or before
+`next()` so every visitor's miss can fill the entry.
+
+A handler that reads `ctx.theme` on a stored route is not guarded: the stored
+document shows that visitor's theme to everyone. Read the theme with
+`useTheme()` instead (see `/theme`).
 
 ## Invalidation
 

package/skills/hooks/SKILL.md

@@ -66,7 +66,9 @@ the one for your case.
   Rango-specific hook for tracking actions called outside a
   `<form action={...}>` flow.
 - [`./state.md`](./state.md) — `useLocationState` (persistent + flash state,
-  `.read()`/`.write()`/`.delete()`), `invalidateClientCache()`.
+  `.read()`/`.read(location)`/`.write()`/`.delete()`, typed `state` on `router.push()` /
+  `router.replace()`, serializability errors that name the failing field),
+  `invalidateClientCache()`.
 - [`./outlets.md`](./outlets.md) — `Outlet`, `ParallelOutlet`, `useOutlet`.
 - [`./urls.md`](./urls.md) — `useParams`, `usePathname`, `useSearchParams`,
   `useHref`, `useMount`, `useReverse`.

package/skills/hooks/navigation.md

@@ -67,8 +67,10 @@ function NavigationControls() {
 | `forward()`              | `history.forward()`.                                                                                            |
 
 `push` / `replace` options: `scroll` (`false` keeps the current scroll
-position), `revalidate` (default `true`, see below), and `state` (location
-state, see [`./state.md`](./state.md)).
+position), `revalidate` (default `true`, see below), `transition` (`false`
+skips the route's `transition()` for this navigation, see below), and `state`
+(location state: `[MyState(value)]` for typed entries, or plain
+structured-clone-safe data; see [`./state.md`](./state.md)).
 
 Target resolution: a path starting with `/` is app-absolute and gets the
 router `basename` prefixed. A relative path (`"cart"`, `"./cart"`) resolves
@@ -95,6 +97,25 @@ If the pathname changes, `revalidate: false` is silently ignored and a full navi
 
 Plain `<a>` tags can opt in via `data-revalidate="false"`.
 
+#### Skipping the transition
+
+Pass `transition: false` to present one navigation without the route's
+`transition()`: the commit is urgent (the `loading()` skeleton streams) and no
+view transition runs, the same result as a `transition({ when })` predicate
+returning `false`. No predicate is called. Back/forward, actions and
+revalidation are unaffected.
+
+```tsx
+router.push("/photos/2", { transition: false });
+
+<Link to="/photos/2" transition={false}>
+  Next
+</Link>;
+```
+
+Plain `<a>` tags can opt in via `data-transition="false"`. See
+`/view-transitions` → "Conditional transitions".
+
 ### useSegments()
 
 Access current URL path and matched route segments:

package/skills/hooks/state.md

@@ -12,6 +12,9 @@ import { useLocationState, createLocationState } from "@rangojs/router/client";
 
 // Define typed state (all export patterns supported)
 // Keys are auto-injected by the Vite plugin -- no manual key needed.
+// In a unit test (no plugin), key it with withLocationStateKey(ProductState,
+// "ProductState") from @rangojs/router/testing: outside production, an
+// unkeyed definition throws on first use.
 export const ProductState = createLocationState<{
   name: string;
   price: number;
@@ -81,8 +84,87 @@ definition:
 const state = useLocationState<{ from?: string }>(); // { from?: string } | undefined
 ```
 
+### State on router.push() / router.replace()
+
 The same `state` option exists on `router.push()` / `router.replace()` (see
-[`./navigation.md`](./navigation.md)).
+[`./navigation.md`](./navigation.md)), with the same type as `<Link state>`
+(minus the click-time getter): `HistoryState`, which is
+`readonly LocationStateEntry[]` (typed entries) or `PlainHistoryState` (plain,
+structured-clone-safe data). Both types are exported from
+`@rangojs/router/client`.
+
+```tsx
+"use client";
+import { useLocationState, useRouter } from "@rangojs/router/client";
+import { GridState } from "./state"; // createLocationState<{ count: number }>()
+
+function LoadMore() {
+  const router = useRouter();
+  const grid = useLocationState(GridState);
+  const count = grid?.count ?? 20;
+  return (
+    <button
+      onClick={() =>
+        router.replace("?page=2", { state: [GridState({ count: count + 20 })] })
+      }
+    >
+      Load more
+    </button>
+  );
+}
+```
+
+Typed entries always go in an array, with nothing else in it. Three mistakes
+are compile errors:
+
+```tsx
+router.push(url, { state: GridState({ count: 3 }) }); // entry without the array
+router.push(url, { state: [GridState] }); // definition, not called
+router.push(url, { state: [GridState({ count: 3 }), { from: "list" }] }); // mixed
+```
+
+Without the array, the entry's own `__rsc_ls_*` fields would land on
+`history.state` and `useLocationState(GridState)` would read `undefined`; an
+uncalled definition throws `DataCloneError` in `history.pushState`; in a mixed
+array only the first element picks the format, so the rest are lost. For
+untyped (JS) callers, development builds throw an error for each that names
+the definition's key (or the offending index) and the fix.
+
+Plain state is checked at the top level only. It rejects functions, symbols,
+`Promise`, `WeakMap`, `WeakSet`, and values typed `unknown` (narrow an
+`unknown` value, or annotate it as `PlainHistoryState`). Array, `Map`, and
+`Set` elements are checked the same way, but plain object members are not.
+These still compile and still throw `DataCloneError` at `history.pushState`:
+
+- a function, symbol, or React element inside a plain object
+  (`{ onClose: () => {} }`);
+- a top-level `ReactElement` or DOM node (`HTMLElement`), which look like
+  plain objects to the type.
+
+Store plain data and rebuild the rest on arrival, or use a typed
+`createLocationState<T>()` definition, whose `T` is checked all the way down.
+
+### When a type fails the serializability check
+
+`createLocationState<T>()` rejects values that cannot survive
+`history.state`'s structured clone: functions, class constructors, symbols,
+React/RSC content, and fields typed `unknown`. The compile error names the
+failing field and the reason:
+
+```
+Argument of type '{ items: never[]; cursor: string; }' is not assignable to
+parameter of type '... & LocationStateUnsafe<"`unknown` cannot be verified as
+serializable; give it a concrete type", "items[].info.values">'.
+```
+
+The path uses `.` for fields, `[string]` / `[number]` for index signatures
+(`Record<string, T>`), `[]` for array and `Set` elements, `[0]` for tuple
+elements, `<key>` / `<value>` for `Map` keys and values, and `<root>` when the
+value itself is unsafe. A field typed `any` is never reported. When several fields fail, the error lists one `LocationStateUnsafe` per
+path. An object's own unsafe fields are reported before anything nested
+deeper, so a class instance or DOM node stops at its methods
+(`row.el.click`); fix those and the next compile names the rest. The walk
+stops 8 levels deep, reporting the deepest path it reached.
 
 ### Flash State (read-once)
 
@@ -160,6 +242,15 @@ const flash = FlashMessage.read();
 const product = ProductState.read();
 ```
 
+`.read(location)` reads this definition's slot from any `{ state }` snapshot
+instead of the current entry, such as the `from` / `to` of a
+`transition({ when })` context. It works without `window` and never clears
+flash state:
+
+```tsx
+transition({ when: ({ to }) => ProductState.read(to) !== undefined });
+```
+
 > **Hydration:** `.read()` returns `undefined` on the server but may return
 > a real value on the first client render (history state survives reload).
 > Do not call `.read()` directly during the initial render of a component;
@@ -191,11 +282,12 @@ const current = ProductState.read();
 ProductState.delete();
 ```
 
-| Method      | Updates `history.state` | Fires `useLocationState` rerender | SSR behavior        |
-| ----------- | ----------------------- | --------------------------------- | ------------------- |
-| `.read()`   | no                      | n/a (returns snapshot)            | returns `undefined` |
-| `.write()`  | yes (replace this slot) | no                                | throws              |
-| `.delete()` | yes (remove this slot)  | no                                | throws              |
+| Method            | Updates `history.state` | Fires `useLocationState` rerender | SSR behavior        |
+| ----------------- | ----------------------- | --------------------------------- | ------------------- |
+| `.read()`         | no                      | n/a (returns snapshot)            | returns `undefined` |
+| `.read(location)` | no                      | n/a (reads the given snapshot)    | reads the snapshot  |
+| `.write()`        | yes (replace this slot) | no                                | throws              |
+| `.delete()`       | yes (remove this slot)  | no                                | throws              |
 
 ## Cache Control
 

package/skills/intercept/SKILL.md

@@ -214,24 +214,41 @@ intercept(
   "product",
   <ProductModal />,
   // Only intercept when coming from a different section
-  { when: ({ from }) => !from.pathname.startsWith("/shop/product/") },
+  { when: ({ from }) => !from.url.pathname.startsWith("/shop/product/") },
   () => [
     loader(ProductLoader),
   ]
 )
 ```
 
-`when` is a synchronous match-time selector. It receives `from` / `to` (URLs),
-`fromRouteName` / `toRouteName` (named routes only), `params` (the target's),
-`segments` (the client's current segment path and ids), `request`, and `env`.
-Pass an array of predicates for AND logic (all must return true). Omit `when`
-entirely and the intercept always activates. `when` is not re-evaluated during
-action revalidation, so an open modal stays open after an action.
+`when` is a synchronous match-time selector that runs on the server. It
+receives `from` and `to` (the destination), each `{ url, params, routeName }`
+— the shape `transition({ when })` sees, without `state`, because history
+state never reaches the server — plus `segments` (the client's current
+segment path and ids), `request`, and `env`. `from` is the page the
+navigation leaves, except while an intercept is open: then it is the
+intercept's source page, the page under the modal (`match-api.ts`,
+`navigation-snapshot.ts` `effectiveFromUrl`). Opening `/item/1` as a modal
+over `/list/open` and then navigating to `/item/2` from inside the modal
+gives `from.url.pathname === "/list/open"`, not `/item/1`. That differs from
+`transition({ when })`'s `from`, which is always the committed location on
+screen. `routeName` is set for named routes only. Pass an array of predicates
+for AND logic (all must return true). Omit `when` entirely and the intercept
+always activates. `when` is not re-evaluated during action revalidation, so
+an open modal stays open after an action. A selector that throws does not
+intercept: the full page renders and the error is logged with the route name.
+
+A prefetch of a route an intercept targets is stored per source page, whether
+or not the intercept applies from that page (`rsc-rendering.ts`
+`x-rsc-prefetch-scope: source`, set from `MatchResult.interceptTargeted`). A
+full page prefetched from a page where `when` is false never serves a click
+from a page where it is true. Routes no intercept targets keep one shared
+prefetch entry.
 
 ```typescript
 // Intercept only when opened from the shop index
 intercept("@modal", "product", <ProductModal />, {
-  when: ({ fromRouteName }) => fromRouteName === "index",
+  when: ({ from }) => from.routeName === "index",
 })
 ```
 
@@ -242,8 +259,8 @@ intercept(
   <ProductModal />,
   {
     when: [
-      ({ from }) => from.pathname.startsWith("/shop"),
-      ({ params }) => params.slug !== "featured",
+      ({ from }) => from.url.pathname.startsWith("/shop"),
+      ({ to }) => to.params.slug !== "featured",
     ],
   },
   () => [
@@ -401,7 +418,7 @@ layout(ShopLayout, () => [
     "@modal",
     ".detail",
     <ProductModal />,
-    { when: ({ from }) => from.pathname.startsWith("/shop") },
+    { when: ({ from }) => from.url.pathname.startsWith("/shop") },
     () => [loader(ProductLoader)],
   ),
 ])
@@ -482,7 +499,7 @@ export const shopPatterns = urls(({
       "@modal",
       ".product", // dot-local: resolves to "shop.product" in this include
       <ProductModalContent />,
-      { when: ({ from }) => !from.pathname.startsWith("/shop/product/") },
+      { when: ({ from }) => !from.url.pathname.startsWith("/shop/product/") },
       () => [
         layout(<ModalWrapper />),
         loading(<ProductModalSkeleton />),

package/skills/loader/SKILL.md

@@ -139,11 +139,13 @@ A DSL loader without `ssr: false` can read `createVar({ cache: false })`
 variables: it runs on every request, `cache()` and PPR shell HITs included, so
 the read guard is bypassed for it. On a `ppr` route the capture runs an
 `ssr: false` loader, and a loader a handler awaits, and bakes their values into
-the shell: a `cookies()`, `headers()` or `{ cache: false }` read there refuses
-the capture, so the route keeps rendering without a shell (warned once per key).
+the shell: a `cookies()`, `headers()`, `ctx.request.headers` or
+`{ cache: false }` read there refuses the capture, so the route keeps
+rendering without a shell (warned once per key).
 A loader bound with its own `cache()` is the other exception: its value is
-stored and shared, so a miss whose body read `cookies()`, `headers()`, a
-non-cacheable variable or the theme fails unless the binding has a `key()` or a
+stored and shared, so a miss whose body read `cookies()`, `headers()`,
+`ctx.request.headers`, a non-cacheable variable or the theme fails unless the
+binding has a `key()` or a
 store `keyGenerator`, which must then include them (see "Cache Key"). A
 `"use cache"` function the loader calls is not a loader body: a non-cacheable
 read inside it throws, also through the loader's `ctx` passed in, so read the
@@ -191,8 +193,9 @@ the tree).
   capture-time copy served on every HIT (a HIT never runs the handler);
   `useLoader` of a loader without `ssr: false` is the live lane (an `ssr: false`
   loader is the bake lane however it is read). Unlike `cache()`, an identity
-  read inside that loader (`cookies()`, `headers()`, a `{ cache: false }`
-  variable) refuses the capture, so the route stays uncached. One rule across
+  read inside that loader (`cookies()`, `headers()`, `ctx.request.headers`, a
+  `{ cache: false }` variable) refuses the capture, so the route stays
+  uncached. One rule across
   `cache()`, `"use cache"`, and PPR: the consumption-lane rule (`/rango` →
   Invariants).
 - Non-cacheable variable reads (`createVar({ cache: false })`) inside the
@@ -256,7 +259,8 @@ export const ProductLoader = createLoader(async (ctx) => {
   // Platform bindings (DB, KV, etc.) — plain bindings from createRouter<TEnv>()
   const db = ctx.env.DB;
 
-  // Request headers
+  // Request headers (guarded like headers(): an unkeyed loader cache() fill
+  // or a ppr capture of this loader refuses the read)
   const auth = ctx.request.headers.get("Authorization");
 
   // Variables set by middleware (from Rango.Vars augmentation)
@@ -654,6 +658,7 @@ at two levels:
 import { cookies } from "@rangojs/router";
 
 // Full override — key function replaces the default entirely
+// Stored as "loader:{loaderId}:key:product%3Ashoe%3Aen"
 loader(ProductLoader, () => [
   cache({
     ttl: 300,
@@ -665,12 +670,22 @@ loader(ProductLoader, () => [
 // Set in the store configuration, applies to all entries in that store
 ```
 
-Resolution priority (same as route-level `cache()`):
+Resolution priority (same order as route-level `cache()`):
 
-1. `key(ctx)` from cache options — full override
-2. `store.keyGenerator(ctx, defaultKey)` — store-level modification
+1. `key(ctx)` from cache options — full override, stored namespaced as
+   `loader:{loaderId}:key:` plus the result's URI encoding
+2. `store.keyGenerator(ctx, defaultKey)` — store-level modification, stored
+   as returned
 3. Default key — `loader:{loaderId}:{host}{pathname}:{sortedParams}`
 
+Because the `key()` result is namespaced by the loader id, no value it
+returns, request input included, can name another loader's entry or a
+default key: two loaders whose `key()` returns the same value keep separate
+entries. A readable prefix is still good practice. A store `keyGenerator`
+result is stored as returned, so build it on the `defaultKey` it receives
+(which carries the loader id): a generator that returns raw request input
+can still name another entry.
+
 A `key` function (or store `keyGenerator`) that throws is **not** caught: the
 loader fails as if its body threw. There is no silent fallback to the default
 key, because a personalised key collapsing onto the broad default would share
@@ -680,9 +695,10 @@ one user's data with everyone.
 names no user, so one entry serves everyone who requests the same loader, host,
 path and params. A route `cache()` around the route does not partition it
 either: a loader's own `cache()` is an independent layer, keyed only by what it
-declares. On a miss, a body that reads `cookies()`, `headers()` or a
-non-cacheable variable (`createVar({ cache: false })`, or a value written with
-`ctx.set(..., { cache: false })`) therefore **fails**, and nothing is stored,
+declares. On a miss, a body that reads `cookies()`, `headers()`,
+`ctx.request.headers` or a non-cacheable variable (`createVar({ cache: false })`,
+or a value written with `ctx.set(..., { cache: false })`) therefore **fails**,
+and nothing is stored,
 unless the binding declares identity with a `key()` or a store `keyGenerator`.
 The check tests only that one of them is there, not what it contains: any
 `key()` or store `keyGenerator` switches it off, so it must itself include the
@@ -720,11 +736,25 @@ stored, and `onError` gets the same error. A push still pending after the
 timeout drops the entry's handles, and the value is stored without them. A loader with no `cache()` of its own
 reads request data freely.
 
-Two kinds of read are not seen, the same as in `"use cache"`: raw reads such
-as `ctx.request.headers` or `getRequestContext().cookie()`, and a value
-computed outside the loader and handed in, such as a per-request memo a handler
-filled from `cookies()` before the loader awaited it. Key what those carry
-too. If the value must stay per request, drop the loader's `cache()` instead.
+The raw reads count the same: `ctx.request.headers` (the loader's
+`ctx.request` is the request's own `Request`) and `getRequestContext().cookie()`
+/ `.cookies()` fail an unkeyed miss exactly like `cookies()`. A `key()` or a
+store `keyGenerator` reads them freely, since that is how the entry is
+partitioned:
+
+```typescript
+loader(LocaleLoader, () => [
+  cache({
+    ttl: 60,
+    key: (ctx) => `lang:${ctx.request.headers.get("accept-language") ?? "en"}`,
+  }),
+]),
+```
+
+One kind of read is not seen, the same as in `"use cache"`: a value computed
+outside the loader and handed in, such as a per-request memo a handler filled
+from `cookies()` before the loader awaited it. Key what it carries too. If the
+value must stay per request, drop the loader's `cache()` instead.
 
 ### Tags for Invalidation
 
@@ -797,7 +827,8 @@ loader(ProductLoader, () => [
 ```
 
 When `condition` returns false, the loader runs fresh and the cache is bypassed
-entirely (no read, no write).
+entirely (no read, no write). Like `key()`, a `condition()` reads request
+identity freely: it decides whether the entry is used, it is not stored in it.
 
 ### Per-Loader Store Override
 
@@ -1035,8 +1066,8 @@ The costs and constraints:
   loader lane rule. On a HIT, a flagged loader whose return has no promises is
   served from the shell and does not run (unless the capture marked it to run:
   see `/ppr` → On a shell HIT); one whose return carries promises
-  runs on every HIT, with its baked parts overlaid. A `cookies()`, `headers()`
-  or `{ cache: false }` read in it refuses the capture. The
+  runs on every HIT, with its baked parts overlaid. A `cookies()`, `headers()`,
+  `ctx.request.headers` or `{ cache: false }` read in it refuses the capture. The
   `progressiveChunkSize` auto-raise is live-document only; captured shells
   outline per the explicit option or React's default.
 

package/skills/middleware/SKILL.md

@@ -274,6 +274,24 @@ export const myMiddleware: Middleware = async (ctx, next) => {
 Cookies and request headers are not `ctx` members; use the free functions
 `cookies()` and `headers()` from `@rangojs/router`.
 
+Middleware reads request identity freely: `cookies()`, `headers()` and
+`ctx.request.headers` alike. The same `Request` reaches handlers and loaders
+as `ctx.request`, and there `ctx.request.headers` answers like `headers()`: it
+throws inside a `cache()` boundary or a `"use cache"` function and refuses a
+`ppr` shell capture (#976). To render a header on a cached or `ppr` route,
+copy it here with `ctx.set()` (a cacheable variable) and include it in the
+route's `cache()` `key()`, so each value gets its own record and shell:
+
+```typescript
+const Tier = createVar<string>();
+
+export const tierMiddleware: Middleware = async (ctx, next) => {
+  ctx.set(Tier, ctx.request.headers.get("x-tier") ?? "free");
+  return next();
+};
+// cache({ key: (ctx) => `tier:${ctx.request.headers.get("x-tier") ?? "free"}` }, ...)
+```
+
 ### Changing the response after `next()`
 
 After `await next()`, `ctx.header()` and `ctx.headers` write to the real

package/skills/migrate-nextjs/SKILL.md

@@ -303,7 +303,7 @@ The main content always goes through `<Outlet />` via the `path()` handler.
 layout(<ShopLayout />, () => [
   path("/product/:id", ProductPage, { name: "product" }),
   intercept("@modal", ".product", <ProductModal />, {
-    when: ({ from }) => from.pathname.startsWith("/shop"),
+    when: ({ from }) => from.url.pathname.startsWith("/shop"),
   }),
 ])
 ```
@@ -504,8 +504,8 @@ Differences that matter during migration:
   gives one shell per key value, and `cache(false)` or a false `condition()`
   means no shell.
 - **Request-scoped reads in shell material refuse the capture** (in Next they
-  silently force dynamic rendering). `cookies()`, `headers()`, a
-  `{ cache: false }` variable, and `ctx.dynamic()` refuse it anywhere the
+  silently force dynamic rendering). `cookies()`, `headers()`,
+  `ctx.request.headers`, a `{ cache: false }` variable, and `ctx.dynamic()` refuse it anywhere the
   capture waits: a handler, a promise it passes or pushes, an async component,
   a loader it awaits. Per-user reads must move into a live loader (no
   `ssr: false`; a nested promise does not help). A normal `ctx.get()` value is

package/skills/observability/SKILL.md

@@ -97,7 +97,7 @@ and, when the tail finishes, one console line (wrapped here):
 ```
 [RSC Perf] GET /ppr-large/holes shell tail: complete snapshot=4ms
 snapshot-read=2ms snapshot-bytes=1019145b snapshot-parse-cpu=2ms
-records=segment:1 pruned=item:5 seed=4ms seed-cpu=0ms match=4ms handover=4ms
+records=segment:1 seed=4ms seed-cpu=0ms match=4ms handover=4ms
 first-html=5ms complete=55ms prelude=628949b tail=1033762b
 ```
 
@@ -116,10 +116,11 @@ first-html=5ms complete=55ms prelude=628949b tail=1033762b
   hinted marker reads ran before the entry named its tags), and `fresh-reads`
   when the request carried the cookie.
 - `records=` counts the snapshot records the tail was seeded with, by
-  family; `pruned=` counts the ones the capture dropped because no reader of
-  the entry consumes them. Here every HIT tail replays the handler layer from
-  the one segment record, so the five `"use cache"` item records that produced
-  it were not stored.
+  family. Here every HIT tail replays the handler layer from the one segment
+  record; a bake-lane loader adds `loader:N` pins. `pruned=` appears only when
+  a navigation-only entry drops the loader pins it has no reader for
+  (`pruned=loader:N`): a document entry records only the doc record and the
+  loader pins, so there is nothing else to prune.
 - `snapshot=`, `seed=`, `match=`, `first-html=` are offsets from the commit,
   not durations; `snapshot-read=`, `snapshot-parse-cpu=` and `seed-cpu=` are
   durations.

package/skills/parallel/SKILL.md

@@ -280,7 +280,7 @@ layout(<AccountLayout />, () => [
 
 A slot's `loading()` (whether from `handler.use` or explicit) makes that slot an independent streaming unit, exactly as in the **Streaming Behavior** section above.
 
-Under a shared artifact (`cache()`, `"use cache"`, a PPR shell), the server-side `await ctx.use(CartLoader)` above is the BAKED lane — the capture-time value freezes into the artifact. Under `cache()`/`"use cache"` an identity read (`cookies()`, `headers()`) inside the loader bakes too; under a PPR shell it refuses the capture, so the route stays uncached. Consume the loader client-side (`useLoader` in a `"use client"` component, the slot's `loading()` as its boundary) to keep the slot live per request. One rule, stated once: `/rango` → Invariants ("the consumption-lane rule").
+Under a shared artifact (`cache()`, `"use cache"`, a PPR shell), the server-side `await ctx.use(CartLoader)` above is the BAKED lane — the capture-time value freezes into the artifact. An identity read (`cookies()`, `headers()`, `ctx.request.headers`) inside the loader bakes too under `cache()`; inside `"use cache"` it throws when the cached function is the first to read the loader in the request (an already-started loader's value is stored unchecked); under a PPR shell it refuses the capture, so the route stays uncached. Consume the loader client-side (`useLoader` in a `"use client"` component, the slot's `loading()` as its boundary) to keep the slot live per request. One rule, stated once: `/rango` → Invariants ("the consumption-lane rule").
 
 The `parallel` mount site has the narrowest allow-list for `handler.use` items — slots cannot bring their own middleware or layout, only `revalidate`, `loader`, `loading`, `errorBoundary`, `notFoundBoundary`, and `transition`. See [skills/handler-use](../handler-use/SKILL.md) for the full table and merge rules.