@rangojs/router 0.17.0 → 0.19.0

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

@@ -7,7 +7,8 @@ argument-hint: "[loader]"
 # Data Loaders with loader()
 
 A loader is a server function created with `createLoader()` and registered on a
-route segment with `loader()`. It runs fresh on every request, streams its
+route segment with `loader()`. It runs fresh on every request (on a `ppr` route,
+one registered with `ssr: false` is baked into the shell instead), streams its
 result to the client, and client components read it with `useLoader()`. This
 skill covers defining, registering, consuming, revalidating, caching, and
 client-fetching loaders.
@@ -121,25 +122,39 @@ path("/product/:slug", ProductPage, { name: "product" }, () => [
 >   (plain GET only). See the hooks skill ("Scoping refetch with a `key`" and
 >   "Refreshing multiple loaders together").
 > - `cache({ key })` — a **server** cache identity (storage hit/miss/ttl/swr).
+>   On a route `cache()` over a `ppr` route, each key value also gets its own
+>   shell; keep the value set small.
 > - `revalidate()` — which **server** segments/loaders recompute during
 >   navigation and action refreshes.
 
 DSL loaders are the **live data layer**: they resolve fresh on every request,
 even when the route is inside a `cache()` boundary, so `cache()` gives you
 cached UI + fresh data by default. See "Loaders: The Live Data Layer" below.
+The exception is a `ppr` route's `ssr: false` loader: it bakes into the shell,
+and a shell HIT runs it only when its return carries promises.
 
 ### Cache safety
 
-DSL loaders can safely read `createVar({ cache: false })` variables
-because they are always resolved fresh. The read guard is bypassed for
-loader functions — they never produce stale data. 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 var in the loader and
-pass the value in as an argument. Passing the loader's `ctx` itself is fine:
-the call keys by route, params and search, like a handler `ctx` (`/use-cache`).
-A fetchable loader called with a request body (`load({ method: "POST", body })`
-or form data) is the exception: the body is not in the key, so the call runs
-uncached. Pass the body fields the function needs as arguments instead.
+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()`, `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()`,
+`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
+var in the loader and pass the value in as an argument. Passing the loader's
+`ctx` itself is fine: the call keys by route, params and search, like a handler
+`ctx` (`/use-cache`). A fetchable loader called with a request body
+(`load({ method: "POST", body })` or form data) is the exception: the body is
+not in the key, so the call runs uncached. Pass the body fields the function
+needs as arguments instead.
 
 ### ctx.use(Loader) — escape hatch
 
@@ -157,7 +172,9 @@ path("/product/:slug", async (ctx) => {
 ])
 ```
 
-`ctx.use(Loader)` is a live read, memoized for the request: however many
+`ctx.use(Loader)` is a per-request read on any render that runs the handler,
+memoized for the request (a route `cache()` HIT or a `ppr` shell HIT runs no
+handler, so the handler's output from the read is replayed): however many
 times it is called, and whether or not the loader is also registered with
 `loader()`, it runs once per request. It never reads or writes the loader
 store cache on its own: a loader's `cache()` belongs to its DSL binding
@@ -171,11 +188,16 @@ the tree).
 - The handler output depends on the loader data. If the route is inside
   `cache()`, the handler is cached with the loader result baked in —
   defeating the live data guarantee.
-- The same holds under a PPR shell capture (`/ppr`): handler consumption is
-  the BAKED lane — the loader executes at capture (identity reads permitted)
-  and the rendered value is a capture-time copy; `useLoader` client-side is
-  the live lane. One rule across `cache()`, `"use cache"`, and PPR: the
-  consumption-lane rule (`/rango` → Invariants).
+- The same holds under a PPR shell capture (`/ppr`): handler consumption is the
+  BAKED lane — the loader executes at capture and the rendered value is a
+  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()`, `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
   handler still throw, even if the data came from a loader.
 - Prefer DSL `loader()` + client `useLoader()` for data that depends on
@@ -237,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)
@@ -491,11 +514,16 @@ Loaders resolve fresh on every request, even when the route's UI segments are
 served from cache. Route-level `cache()` caches rendered segments but never
 loader data: loaders are excluded when the segments are stored and re-resolved
 when they are served. Caching a loader's own data is a separate opt-in (see
-"Opting a Loader into Caching").
+"Opting a Loader into Caching"). A `ppr` shell does store some loader data: an
+`ssr: false` loader's settled data bakes into the shell, and a HIT runs that
+loader only when its return carries promises (see "`ssr: false`" below and
+`/ppr`).
 
-Pre-rendering follows the same rule: at build time loaders are skipped entirely
-(there is no real request context), and at runtime the worker resolves them
-fresh against the live database.
+Pre-rendering follows the same rule: the build-time Flight payload skips
+loaders (there is no real request context), and at runtime the worker resolves
+them fresh against the live database. The exception is a `Prerender` + `ppr`
+route: its build-time shell capture runs `ssr: false` loaders and bakes their
+settled data into the shell, like a runtime capture.
 
 ### Parallel and streaming — latency overlaps first paint
 
@@ -516,8 +544,8 @@ If you come from a framework where the loader is a blocking step that runs
 before the response is built, this is the shift to internalize: here the
 response starts streaming first and loader data fills in. (The one deliberate
 exception is per-loader: `loader(Def, { ssr: false })` awaits that
-loader before first flush on document renders — see "`ssr: false`"
-below.)
+loader before first flush on document renders other than a `ppr` shell HIT,
+where the shell flushes first — see "`ssr: false`" below.)
 
 ### See it: `debugPerformance`
 
@@ -579,7 +607,11 @@ loader(ProductLoader, () => [cache({ ttl: 300 })]),
 
 This works wherever the DSL binding is declared, an intercept's `use()`
 included. A handler's `ctx.use(Loader)` read never caches by itself (see
-"ctx.use(Loader) — escape hatch").
+"ctx.use(Loader) — escape hatch"). Once the binding started, every
+`ctx.use(Loader)` in the request, from the handler or from another loader's
+body, gets the binding's value: one value per loader per request, a HIT
+included. A reader that runs before the binding starts (a layout's loader
+reading a route's cached loader) gets the value of its own run, as before.
 
 The loader's data is cached independently from the route's segment cache,
 using the same `SegmentCacheStore` (app-level or per-loader override).
@@ -626,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,
@@ -637,17 +670,92 @@ 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
 one user's data with everyone.
 
+**Request-scoped reads in the body must be part of the key.** The default key
+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()`,
+`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
+value. That includes a store-wide `keyGenerator` that only adds a region
+prefix, like the one described above.
+
+```typescript
+export const SessionLoader = createLoader(async () =>
+  getAccount(cookies().get("session")?.value),
+);
+
+// The miss fails: cookies() cannot be called inside loader "…SessionLoader",
+// whose own cache() has no key().
+loader(SessionLoader, () => [cache({ ttl: 60 })]),
+
+// One entry per session.
+loader(SessionLoader, () => [
+  cache({
+    ttl: 60,
+    key: (ctx) => `account:${cookies().get("session")?.value ?? "anon"}`,
+  }),
+]),
+```
+
+The same holds in a stale entry's background refresh (the refresh fails and the
+stale entry keeps serving) and for the loaders the body reads with `ctx.use()`,
+because their values land in the entry. That includes a keyed cached loader
+served from its own cache: its entry keeps the read its miss made. It also holds
+when something else ran the loader first, such as a parent layout's handler
+calling `ctx.use(SessionLoader)`: the miss reuses that run and fails the same
+way. A read that settles after the value, in a promise inside it or in a
+handle push that settles within the 5 s handle-encode timeout, can't fail a
+value that was already served: that user gets their own value, nothing is
+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.
+
+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
 
 ```typescript
@@ -665,6 +773,34 @@ loader(ProductLoader, () => [
 ]),
 ```
 
+The tags the loader body records tag the entry too: `cacheTag()` calls, the
+tags of `"use cache"` reads, render-time `cacheTag()` in server components of
+the value or a handle push, and the tags the loaders it reads with `ctx.use`
+record, including one the route, a layout or the handler started first. A
+loader it reads that has its own `cache()` also brings its `cache({ tags })`
+and, on a HIT, its entry's tags. `updateTag()` of any of them drops the entry,
+and a HIT records them again, so a route `cache()`, ppr shell or document built
+over the HIT stays evictable. A stale hit's background refresh stores the
+refreshed body's tags; it runs the loaders it reads again rather than reusing
+the page's (possibly stale) values.
+
+One case keeps a `cache({ tags })` off: a cached loader that reads another
+loader's `cache()` binding before that binding starts (for example a cached
+layout loader reading a route's cached loader), and writes its entry before
+it. That reader's entry has the tags the loader's body records, but not the
+tags only its `cache({ tags })` lists. If the reader must drop with them, record
+them in the loader body with `cacheTag()` too.
+
+```typescript
+export const ProductLoader = createLoader(async (ctx) => {
+  cacheTag(`product:${ctx.params.slug}`);
+  return db.product(ctx.params.slug);
+});
+
+loader(ProductLoader, () => [cache({ ttl: 600 })]),
+// updateTag(`product:${slug}`) drops this entry.
+```
+
 ### Stale-While-Revalidate
 
 ```typescript
@@ -691,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
 
@@ -818,7 +955,10 @@ flushes, so both signals are resolved server-side while the tree is built:
 `redirect()` replaces the whole page with the redirect carrier (still a 200
 document, the client replaces to the target on hydration) and `notFound()`
 renders the not-found UI at the owning segment with a real 404. No read site
-runs, so a `useLoader` in a layout above every Suspense boundary is safe.
+runs, so a `useLoader` in a layout above every Suspense boundary is safe. On a
+`ppr` route, a flagged loader that settles with `notFound()` or `redirect()`
+during the shell capture refuses the capture (warned once per key): that URL
+gets no shell, and its renders deliver the signal as above.
 
 Session/auth gates belong in middleware (they are request-shaped, not
 data-shaped, and middleware CAN emit a real pre-stream 302). Data-dependent
@@ -857,7 +997,9 @@ they are replayed from the entry (see "Opting a Loader into Caching").
 
 Under `cache()`, loader pushes are not stored with the cached segments: the
 loader re-runs on every hit and its live push is the only copy. (`ppr` keeps
-settled `ssr: false` pushes in the shell record — see `/ppr`.)
+the settled pushes of an `ssr: false` loader, and of the loaders it awaits, in
+the shell, and a promise-free `ssr: false` loader does not run on a shell HIT —
+see `/ppr`.)
 
 Reads are the other direction and gated: `ctx.get(handle)` throws unless the
 loader first does `await ctx.rendered()` (DSL-registered loaders only —
@@ -883,14 +1025,17 @@ path("/product/:slug", ProductPage, { name: "product" }, () => [
 The options object is typed as `LoaderOptions`
 (`import type { LoaderOptions } from "@rangojs/router"`).
 
-The knob mirrors `loading(fallback, { ssr: false })` — SSR delivery is off
-for this loader, so nothing of it is left to stream in the document:
-document renders await this loader before first flush — data is settled
-(`useLoader` reads it synchronously, no fallback paints), handle pushes beat
-the barrier snapshot, and a thrown `notFound()` deterministically precedes
-Response construction (real 404, no warm-up race). Client navigations stream
-exactly as before. Scoped per LOADER: the flagged loader awaits only itself;
-siblings keep streaming.
+The knob mirrors `loading(fallback, { ssr: false })` — SSR delivery is off for
+this loader, so nothing of it is left to stream in the document: document
+renders await this loader before first flush — data is settled (`useLoader`
+reads it synchronously, no fallback paints), handle pushes beat the barrier
+snapshot, and a thrown `notFound()` deterministically precedes Response
+construction (real 404, no warm-up race). Client navigations stream exactly as
+before (on a `ppr` route, a navigation that replays a shell captured by a
+document request serves a promise-free flagged loader from its pin, as a
+document HIT does; a snapshot captured by a navigation alone carries no pins,
+and its replay runs the loader fresh). Scoped per LOADER: the flagged loader
+awaits only itself; siblings keep streaming.
 
 Delivery is in-place, not merely in-document. React's Fizz outlines any
 COMPLETED Suspense boundary over ~500 bytes to an end-of-stream
@@ -906,17 +1051,25 @@ still outline; their reveal must wait for the CSS.
 
 The costs and constraints:
 
-- Every document load pays the flagged loader's latency before first byte.
-  That is the point — but keep flagged loaders fast, and flag loaders, not
-  routes.
+- Every document render that is not a `ppr` shell HIT pays the flagged
+  loader's latency before first byte. That is the point — but keep flagged
+  loaders fast, and flag loaders, not routes. On a HIT the shell flushes
+  first: a flagged loader whose return has no promises does not run (unless
+  the capture marked it to run: see `/ppr` → On a shell HIT), and one whose
+  return carries promises runs to fill its holes.
 - A flagged loader must not `await ctx.rendered()` / `ctx.get(handle)` — the
   document render awaits the loader before the render barrier resolves, so
   that wait is a cycle by construction; it throws a deadlock error naming the
   fix.
 - Under PPR the flag is also the bake lane: the settled non-promise data
   (handle pushes included) freezes into the stored shell — see `/ppr` → The
-  loader lane rule. The `progressiveChunkSize` auto-raise is live-document
-  only; captured shells outline per the explicit option or React's default.
+  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()`,
+  `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.
 
 Also available in `clientUrls()` route groups (`/client-urls`), where the
 loader-heavy shape makes it most useful.

package/skills/middleware/SKILL.md

@@ -75,7 +75,10 @@ render pass — normal renders, post-action revalidation, PE re-renders — its
 variables are never stale: middleware is the safest `ctx.set` rung on the
 data-passing ladder (`/rango` → "Passing data down the tree"). But it does
 not change partial revalidation boundaries between handler/layout/parallel
-segments.
+segments. On a PPR shell HIT no handler or layout runs; on a route `cache()`
+HIT the segments inside the `cache()` boundary don't run, and those above it
+do. Output that didn't run shows the values read when the shell was captured
+or the entry written.
 
 For shared segment data, use named revalidation contracts on both the producer
 and consumer segments, even when middleware is present in the chain.
@@ -271,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
@@ -334,19 +355,23 @@ the token (`createVar<T>({ cache: false })`) or per write
 (`ctx.set("user", user, { cache: false })`). Reading it with `ctx.get()` inside
 a `cache()` boundary or a `"use cache"` function then throws instead of baking
 one user's data into a shared entry (inside `"use cache"`, also through a
-middleware `ctx` passed in); loaders can still read it because they always run
-fresh (a `"use cache"` function a loader calls cannot). A middleware `ctx`
-passed to a `"use cache"` function keys the call by host, pathname, params and
-search, plus the route name once the route is matched (a global middleware
-before `next()` has none yet), and its `set()`, `header()` and `headers` writes
-throw inside the function (`/use-cache`).
+middleware `ctx` passed in); under `cache()` loaders can still read it because a
+DSL loader re-runs on every hit (a `"use cache"` function a loader calls cannot,
+and a loader bound with its own `cache()` only with a `key()`, which switches
+the check off, so the key must include the value). On a `ppr` route only a
+loader without `ssr: false` that no handler awaits may read it: a read the shell
+capture waits for refuses the capture. A middleware `ctx` passed to a
+`"use cache"` function keys the call by host, pathname, params and search, plus
+the route name once the route is matched (a global middleware before `next()`
+has none yet), and its `set()`, `header()` and `headers` writes throw inside the
+function (`/use-cache`).
 
 ## Build-Time PPR Middleware
 
 Normal `Prerender` Flight payload collection does not run middleware: there is
 no request to wrap. The exception is `Prerender` + `ppr` build-shell capture.
-After the Flight payload exists, the shell producer replays global and route
-middleware for each generated URL before it captures HTML.
+After the Flight payload exists, the build replays global and route middleware
+for each generated URL before capturing the shell.
 
 In that build-shell pass: