@rangojs/router 0.17.0 → 0.18.0

package/skills/defer-hydration/SKILL.md

@@ -15,7 +15,7 @@ storefront homepage (shell HIT, production build, M-series laptop): a single
 was dead for ~11s. Fast paint, frozen page.
 
 The obvious fix — wrap the heavy subtree in `<Suspense>` so it hydrates later —
-trades the paint away: under shell capture that boundary postpones, and the
+can trade the paint away: when that boundary postpones under shell capture, the
 frozen prelude ships an empty `<main>`. This recipe gets both: the full body
 HTML in the prelude AND its hydration off the initial task, released on first
 idle at retry-lane priority.
@@ -28,7 +28,9 @@ idle at retry-lane priority.
 | interactive (menu click works)   | ~3.5s    | ~1.6s                            | ~1.6s                     |
 
 Measure your own page before and after — the win depends on how much of the
-hydration cost lives under the boundary (see "Verifying and measuring").
+hydration cost lives under the boundary (see "Verifying and measuring"). These
+numbers were measured before PPR captures baked handler output; see the next
+section for what that changed.
 
 ## The recipe
 
@@ -102,23 +104,39 @@ inside hydrates after first idle.
 
 ## Why `fallback={children}` is load-bearing
 
-This is not a style choice; it is the half of the recipe that makes it
-PPR-compatible.
-
-Shell capture aborts on flight byte-quiet (`src/rsc/shell-capture.ts`,
-`FLIGHT_QUIET_HOPS`): once the Flight source has been byte-silent for the
-quiet window, the fizz render freezes. A big HTML subtree under _any_
-`<Suspense>` boundary cannot finish inside that window, so the boundary always
-postpones — boundary placement cannot fix it. Verified both ways: wrapping the
-client island from outside AND placing the boundary inside the island both
-baked `<!--$?--><template id="B:…">` into `<main>`, i.e. an empty body in the
-frozen prelude.
-
-With the content as the fallback, the unavoidable postpone _becomes the
-delivery mechanism_: the shell bakes the fallback, and the fallback IS the
-body. In `/ppr` hole-doctrine terms, this is the PHYSICS class exploited
-deliberately — you cannot stop the boundary from becoming a hole, so you make
-the hole's baked fallback carry the real markup.
+This is not a style choice. The recipe was built when the shell capture
+postponed any big `<Suspense>` subtree: the capture froze on Flight byte-quiet
+(`FLIGHT_QUIET_HOPS` in `src/rsc/shell-capture.ts`) while the handler output
+was still rendering, so a boundary over the page body became a hole no matter
+where it sat. Verified both ways at the time: wrapping the client island from
+outside AND placing the boundary inside the island both baked
+`<!--$?--><template id="B:…">` into `<main>`, i.e. an empty body in the frozen
+prelude. With the content as the fallback, the postpone became the delivery
+mechanism: the shell baked the fallback, and the fallback was the body.
+
+PPR captures now wait for the whole handler layer before freezing anything:
+the capture records the page's segments first (async server components
+rendered, every promise in the handler output settled) and renders its Flight
+payload from that record (`settleCaptureRecord` in `src/rsc/shell-capture.ts`).
+A boundary whose content is only handler output is therefore expected to bake
+its content as a completed boundary instead of postponing. What still
+postpones at capture is a boundary over live data: a loader without
+`ssr: false` read with `useLoader` under `loading()` or an inline
+`<Suspense>`, or a promise nested in an `ssr: false` loader's value. Run the
+prelude check in "Verifying and measuring" on your page rather than assuming
+either shape.
+
+`fallback={children}` stays the safe choice either way:
+
+- If the boundary still postpones (live data inside it), the fallback is what
+  the prelude shows, so it must be the content.
+- The sync-update trap below: a client render of the boundary shows the
+  fallback. With `fallback={children}` that is a visual no-op; with
+  `fallback={null}` it blanks the page.
+
+The hydration deferral does not depend on which shape you get: `HydrationGate`
+suspends during hydration, and React keeps the server DOM of the boundary in
+place until the gate releases.
 
 ## Why the client gate is free
 
@@ -164,13 +182,14 @@ release on interaction instead (see Variations).
 
 ## Known cost: the body rides twice (measure it, don't guess)
 
-On a shell HIT the gated subtree's HTML is in the response twice — once as the
-baked fallback in the prelude, once as the resumed hole content (the resume
-re-renders and re-ships it; there is no bake-through). Homepage measurement:
-234KB → 302KB gzipped (+68KB, +29%; raw +1.05MB). It is post-paint bandwidth,
-not render-blocking — the visible prelude streams first — but it is real bytes
-on every document GET. Weigh it per page; on a small body the recipe may not
-pay for itself.
+When the boundary postpones at capture, a shell HIT carries the gated
+subtree's HTML twice — once as the baked fallback in the prelude, once as the
+resumed hole content (the resume re-renders and re-ships it; there is no
+bake-through). Homepage measurement (postponing boundary): 234KB → 302KB
+gzipped (+68KB, +29%; raw +1.05MB). It is post-paint bandwidth, not
+render-blocking — the visible prelude streams first — but it is real bytes on
+every document GET. Weigh it per page; on a small body the recipe may not pay
+for itself. A boundary that bakes its content ships it once.
 
 ## Verifying and measuring
 
@@ -230,7 +249,8 @@ this exact space. The recipe survives that future; a primitive might not.
 
 ## Related
 
-- `/ppr` — the shell/hole mechanics this recipe rides on (hole doctrine:
-  PHYSICS class), and why the capture postpones any big Suspense subtree
-- `src/rsc/shell-capture.ts` — the byte-quiet capture window
-  (`FLIGHT_QUIET_HOPS`) that makes `fallback={children}` mandatory
+- `/ppr` — the shell/hole mechanics this recipe rides on: what bakes into the
+  shell, and which boundaries stay holes
+- `src/rsc/shell-capture.ts` — the record-first capture (`settleCaptureRecord`)
+  and the byte-quiet window (`FLIGHT_QUIET_HOPS`) that decide what the prelude
+  holds

package/skills/deployment-caching/SKILL.md

@@ -56,8 +56,11 @@ There are two shell producers:
 Both producers feed the same in-function serve path. Build-time shells are
 content-hashed modules in the server bundle, not CDN-served HTML files.
 
-`ppr.ttl`, `ppr.swr`, and `ppr.tags` govern that shell entry. They do **not**
-emit HTTP `Cache-Control` and do not configure a platform CDN.
+`ppr.ttl` and `ppr.swr` set the shell entry's lifetime, capped by the route
+`cache()` entry it was captured from (the shorter wins). Its tags are
+`ppr.tags` plus the tags its content recorded. A route `cache({ key })` or a
+store `keyGenerator` stores one shell per partition value. None of this emits
+HTTP `Cache-Control` or configures a platform CDN.
 
 ## Platform deployment shapes
 

package/skills/document-cache/SKILL.md

@@ -205,7 +205,10 @@ the variant suffixes are still appended.
 - Responses whose `Cache-Control` also contains `private`, `no-store`, or an
   unqualified `no-cache` (those win over `s-maxage` in a shared cache)
 - Responses carrying `Set-Cookie` (a per-client value must not be replayed to
-  everyone)
+  everyone). That includes a response whose request called
+  `updateTag()`/`revalidateTag()` on a store that keeps per-isolate memos
+  (`CFCacheStore`, `VercelCacheStore`): it carries the fresh-reads cookie
+  (`rango-state-fresh` by default), so it is not stored.
 - Non-200 responses
 - A 200 whose render reported an error: a component that threw after the
   response started streaming, such as an async server component whose fetch
@@ -224,7 +227,10 @@ with the request's tag set, so `updateTag()`/`revalidateTag()` evict them:
 
 - a render-callable `cacheTag("...")` in any server component on the page;
 - tags of `cache()` segments, cached loaders, and `"use cache"` functions the
-  render read.
+  render read. A `cache()` segment HIT contributes the tags its content
+  recorded when it was written (render-callable calls and `"use cache"` reads
+  inside it), so a document stored over the HIT stays evictable by them. A
+  cached loader's HIT likewise contributes the tags its body recorded.
 
 Tags are snapshotted after the response body has fully streamed, so tags from
 Suspense-streamed content are included. A `Prerender()` route's build-time

package/skills/handler-use/SKILL.md

@@ -184,6 +184,8 @@ parallel({
 });
 ```
 
+On a `ppr` route, a slot's `loading()` over handler output does not make a hole. A slot handler that awaits `ctx.use(CartLoader)` is handler output: it runs at capture, its value is baked into the shared shell, and every HIT replays it without running the handler. A `cookies()`/`headers()` read in that loader refuses the capture, so the route stays on MISS. For a per-request slot, read the loader with `useLoader()` in a `"use client"` component under the slot's `loading()` (see `/ppr` → "The layout-with-loaders playbook").
+
 ### Two scopes for explicit `use` at the mount site: shared (broadcast) and slot-local
 
 `parallel()` accepts an explicit `use()` callback that **broadcasts** to every slot in the call ([dsl-helpers.ts](../../src/route-definition/dsl-helpers.ts)). That's the right behavior for the items the parallel allow-list permits and that accumulate (`loader`, `revalidate`, `errorBoundary`, `notFoundBoundary`, `transition`) — every slot gets them. (Note: `middleware` is not allowed inside `parallel()`; see the allowed-types table above.)

package/skills/hooks/handle-and-actions.md

@@ -34,7 +34,9 @@ Writers: handlers AND loader bodies — `ctx.use(Handle)` returns the push
 function in each (middleware has no handle APIs). Loader pushes follow a delivery race (settle before
 the handler barrier → in the SSR'd document; later → applied client-side), and
 `loader(Def, { ssr: false })` makes them deterministic in the
-document. See `/loader` → "Writing Handles from Loaders". `useHandle`
+document. On a `ppr` shell HIT, a loader without `ssr: false` never ran during
+the capture, so its pushes always apply client-side; with `ssr: false` they
+bake into the shell. See `/loader` → "Writing Handles from Loaders". `useHandle`
 re-renders on every handle update, late loader pushes included.
 
 Handles can be passed as props from server to client components:

package/skills/hooks/state.md

@@ -214,7 +214,9 @@ it is selected by export conditions:
   a rotated state `Set-Cookie` for the responding client, which marks its
   caches stale when it next reads them. Idempotent within a request; throws
   inside a `cache()` / `"use cache"` boundary; a no-op with a dev warning
-  outside a request.
+  outside a request. On a `ppr` route a shell HIT runs no handler, so a call
+  from handler code writes the cookie only on the renders that run it (a
+  MISS); call it from middleware, which runs on every request, HITs included.
 
 Server actions already invalidate automatically; to suppress that for a no-op
 action, call `keepClientCache()` inside it (see `/server-actions` → "Client

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,37 @@ 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()` 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
+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 +170,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 +186,15 @@ 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()`, 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
@@ -491,11 +510,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 +540,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 +603,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).
@@ -648,6 +676,56 @@ 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()` 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.
+
+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.
+
 ### Tags for Invalidation
 
 ```typescript
@@ -665,6 +743,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
@@ -818,7 +924,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 +966,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 +994,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 +1020,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()`
+  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.
@@ -334,19 +337,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: