@rangojs/router 0.0.0-experimental.140 → 0.0.0-experimental.141

package/skills/ppr/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: ppr
-description: PPR shell caching — serve a cached HTML shell instantly and resume live loader holes (createShellCacheMiddleware)
+description: PPR shell caching — opt a page route in with the `ppr` path option; the router serves the cached HTML shell instantly and resumes the live holes
 argument-hint: "[setup]"
 ---
 
 # PPR Shell Caching
 
-Caches the rendered HTML **shell** of a route (React `prerender` prelude bytes
-plus `postponed` state) and, on a later request, flushes those bytes before any
-render work happens, then resumes fizz for just the live loader holes. The
+Caches the rendered HTML **shell** of a page route (React `prerender` prelude
+bytes plus `postponed` state) and, on a later request, flushes those bytes
+before any render work happens, then resumes fizz for just the live holes. The
 browser sees one ordinary streamed document; loaders stay fresh on every
 request. This is the second render axis — the default axis-1 path is untouched,
 and every ineligible request falls open to it.
@@ -17,21 +17,35 @@ Compare `/document-cache`, which freezes the WHOLE response including loader
 output. Shell caching is for pages that mix a stable shell with live data: the
 shell is shared per host+URL, the holes are per request.
 
-## Setup
+## Setup: one path option, no middleware
 
-The middleware needs a store that implements the shell family
-(`getShell`/`putShell`): `MemorySegmentCacheStore` (dev/tests), `CFCacheStore`
-(Cloudflare KV), or `VercelCacheStore` (runtime cache). It defaults to the
-app-level store from `createRouter({ cache })`; a store without the family
-disables the middleware (fail-open to axis 1).
+PPR is a DOCUMENT-level property declared on the page route via the `ppr` path
+option. Serving is **integral to the router** — there is nothing to mount. The
+only prerequisite is an app-level `createRouter({ cache })` store that
+implements the shell family (`getShell`/`putShell`): `MemorySegmentCacheStore`
+(dev/tests), `CFCacheStore` (Cloudflare KV), or `VercelCacheStore` (runtime
+cache). A ppr route on a store without the family stays on axis 1 with a
+once-per-key warning.
 
 ```typescript
-import { createRouter } from "@rangojs/router";
-import {
-  createShellCacheMiddleware,
-  CFCacheStore,
-} from "@rangojs/router/cache";
-import { urlpatterns } from "./urls";
+import { createRouter, urls } from "@rangojs/router";
+import { CFCacheStore } from "@rangojs/router/cache";
+
+export const urlpatterns = urls(({ path, layout, loader, loading }) => [
+  layout(ProductShell, () => [
+    path(
+      "/products/:id",
+      PricePage,
+      // `ppr` is the whole opt-in AND the policy. `ppr: true` uses the default
+      // ttl (300s); an object sets ttl/swr/tags (PartialPrerenderProps).
+      { name: "product", ppr: { ttl: 600, swr: 120 } },
+      () => [
+        loader(LivePriceLoader),
+        loading(<PriceSkeleton />), // the structural hole boundary
+      ],
+    ),
+  ]),
+]);
 
 const router = createRouter<AppBindings>({
   document: Document,
@@ -40,383 +54,236 @@ const router = createRouter<AppBindings>({
     store: new CFCacheStore({ kv: env.CACHE_KV, ctx: ctx! }),
   }),
 });
-
-// Path-scoped: only the routes that fit the shell/hole shape below.
-router.use(
-  "/products",
-  createShellCacheMiddleware({ ttlSeconds: 600, swrSeconds: 120 }),
-);
-
 export default router;
 ```
 
+A route WITHOUT the `ppr` option is pure axis 1: no store read, no capture, no
+logs, zero cost. `ppr` is per page route — declaring it on a layout is not
+supported (subtree inheritance is a possible follow-up).
+
 ## Where PPR sits: the cache onion
 
 Rango's caches layer like an onion — each ring stores a progressively more
-"cooked" representation of the same page, and PPR is a new ring, not a
-replacement for any existing one. From innermost (raw values) to outermost
-(final bytes):
+"cooked" representation of the same page. From innermost (raw values) to
+outermost (final bytes):
 
 | Ring                    | Primitive                                | What is stored                                     | What stays live on a hit               |
 | ----------------------- | ---------------------------------------- | -------------------------------------------------- | -------------------------------------- |
 | 1. Function values      | `"use cache"`                            | a function's return value                          | everything around the call             |
 | 2. Loader values        | `loader(Fn, () => [cache({...})])`       | one loader's result (opt-in; loaders default live) | all other loaders, handlers, rendering |
 | 3. Segments (Flight)    | `cache()` route / build-time `prerender` | serialized rendered segments + replayed handles    | loaders, HTML render                   |
-| 4. **HTML shell (PPR)** | `createShellCacheMiddleware`             | rendered prelude bytes + React postponed state     | loaders (the holes), hydration payload |
+| 4. **HTML shell (PPR)** | `ppr` path option                        | rendered prelude bytes + React postponed state     | the holes, hydration payload           |
 | 5. Whole response       | `/document-cache`                        | final response bytes, headers included             | nothing — all-or-nothing               |
 
-Each ring is derived from the ones inside it, and PPR makes that literal:
-the captured shell is the fizz render of ring 3's replayed segments, which is
-why shell/payload consistency holds by construction on `cache()` routes. The
-rings compose in one request: a HIT serves ring 4's bytes instantly, the
-resume pass replays ring 3's segments for the hydration payload, a hole's
-loader may consult ring 2, and a component inside it may consult ring 1.
-
-The onion also explains the boundary with ring 5: the document cache freezes
-loaders too (no holes, coarser but simpler), which is why stacking both on
-one route is pointless — pick the outermost ring whose "stays live" column
-matches the route (see Pitfalls).
-
-Invalidation crosses rings: `invalidateTags` reaches segment, shell, loader,
-and item entries in the same store, and shell entries additionally
-self-invalidate on `React.version` change. TTL/SWR are per-ring — an inner
-ring's shorter TTL shows through a hole immediately (loaders are live), but
-shell-embedded content refreshes only on the shell's own recapture.
-
-## Creating holes: I want X → do Y
-
-A shell-cached route is a stable shell with live **holes** punched through it.
-Everything hinges on where the hole is, and the hole is always a route-level
-`loading()` boundary. Start here:
-
-| I want…                                                                                    | Do this                                                                                                                                                                                                                                 |
-| ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Live per-request data in the page                                                          | a route `loader()` **+ route-level `loading()`** — the loader is the hole, `loading()` is the boundary the capture postpones at and the resume stitches into                                                                            |
-| A slow nested value streamed **inside** the hole                                           | return `{ outer, pendingData: Promise }` from the loader; `use(pendingData)` under the consumer's OWN inner `<Suspense>` (see "Loader-carried promises")                                                                                |
-| A hole for data that is **already resolved** (in-memory, `Promise.resolve`, a cached read) | wrap it in **`live(() => …)`** under your own `<Suspense>` — masked at capture exactly like a loader, so it postpones instead of settling into the shared shell (see "live()")                                                          |
-| Shell-safe, deterministic data                                                             | `await` it in a **handler** — it is shell material, frozen into the prelude                                                                                                                                                             |
-| **Per-user** data                                                                          | a `loader` (masked at capture, always fresh), or **`live()`** for a boundary that is not a route loader. NEVER a handler or middleware-derived `ctx` state — those run during capture and bake into the **shared** shell (see Security) |
-| A slow nested value on a route with **no** `loading()`                                     | still fine on axis 1: the tree-build await is SHALLOW, so `{ outer, pendingData }` streams the inner under the consumer's `<Suspense>` — but the route is not shell-cacheable                                                           |
-
-The last row is the common trap: "no `loading()` blocks" does NOT mean "nested
-promises can't stream". They stream today, unchanged by PPR — the route just
-has no hole, so shell caching stays off for it (eternal MISS, below).
-
-## The hole contract (read this before wiring a route)
-
-A hole exists ONLY where the route-level `loading()` boundary separates loader
-consumption from the shell. `loading()` becomes `LoaderBoundary`
-(`src/route-content-wrapper.tsx`) — a `<Suspense>` whose resolver `use()`es the
-loader promise INSIDE it — so the masked loader postpones exactly there and the
-prelude freezes the layouts plus the fallback. Two consequences:
-
-1. Shell material (static content, handle reads, interactive client islands)
-   lives in a **layout** above the loader route.
-2. The loader-consuming route below carries **`loading()`**.
+PPR is ORTHOGONAL to `cache()` (ring 3): a ppr route may be uncached (its
+handlers run fresh on every serve and during capture), fully `cache()`d (its
+segments replay), or mixed. One useful cache() property to know: the segment
+codec **deep-settles promises at the ring-3 write**, so nothing inside a
+`cache()` boundary can stay live — that is a cache() fact, not a ppr one.
+
+Invalidation crosses rings: `updateTag()`/`revalidateTag()` reach segment,
+shell, loader, and item entries in the same store, and shell entries
+additionally self-invalidate on `React.version` change.
+
+## The serve pipeline: commit after ALL middleware
+
+On a document GET to a ppr route the router runs:
+
+1. **match** — route identified, `ppr` config read from the matched route;
+2. **the WHOLE middleware chain** — the global `router.use()` chain AND route
+   DSL `middleware()`; both are guards, and the COMMIT POINT is after all of
+   them: any rejection/redirect/401 wins before a single shell byte, on MISS
+   and on a warmed HIT alike;
+3. **shell lookup** — `getShell(key)` on the app store (key =
+   host+pathname+sorted search);
+4. **HIT** — the composed response is committed immediately: the stored prelude
+   bytes flush first, while segment resolution, the fresh Flight render (the
+   full hydration payload — there is no Flight-side resume), and the fizz
+   `resume` of just the holes run BEHIND them inside the response stream;
+5. **MISS** — plain axis-1 serve, tagged `x-rango-shell: MISS`, plus a
+   background capture (stampede-guarded, retry-in-place, exponential backoff).
+
+`x-rango-shell: HIT | MISS` is the observability header. Because the commit
+point is after the chain, an unauthorized request NEVER sees shell bytes — put
+auth middleware anywhere (global or route DSL) and it guards PPR for free.
+
+## The hole doctrine (encode this in your head)
+
+Holes are **render-defined**, decided by the shape of the tree, on three rules:
+
+| Class          | What makes the hole                                                                                                                                                                | At capture                                                                             | At serve                           |
+| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ---------------------------------- |
+| **STRUCTURAL** | the ENTIRE segment subtree under a `loading()` registration                                                                                                                        | loaders masked; the LoaderBoundary postpones; the fallback bakes in as route structure | loaders run fresh; resume fills it |
+| **PHYSICS**    | any promise NESTED in handed-over data still pending at capture, under the consumer's own `<Suspense>` — handler props, handle containers (`push({ x: promise })`), loader-carried | real I/O cannot win the task-quantized quiet window; the boundary postpones            | the promise settles and streams in |
+| **SHELL**      | awaited handler data, TOP-LEVEL `push(promise)` (awaited before SSR), resolved promises, replayed `cache()` segments                                                               | baked into the prelude                                                                 | served from the frozen prelude     |
+
+The unified rule for promises: **a promise nested inside your data is never
+baked; the container settles.** The one asymmetry to remember versus loaders: a
+LOADER container is a hole via `loading()` (the whole loader value is live),
+while a HANDLE container is shell via root consumption (the handles generator
+is drained before SSR) — only the promises nested inside it stay live.
+
+### Handles: "nesting = liveness"
+
+- `ctx.use(H)(promise)` — a TOP-LEVEL pushed promise is awaited server-side
+  before SSR (`resolvedHandleStream`) and BAKED into the shell. The capture
+  gate is held open for the same await, so real latency here is safe (bounded
+  by the capture's 5s guard).
+- `ctx.use(H)({ x: promise })` — the container passes through verbatim
+  (resolution is shallow); the nested promise streams to the consumer, who must
+  `<Suspense>` it. Under capture that boundary postpones — a hole.
+
+### Want a hole for already-resolved data?
+
+Put it in a loader: `loader(() => Promise.resolve(x))` + `loading()`. Loaders
+are always the live lane — masked at capture, fresh on every serve — no matter
+how fast the value settles.
+
+### The structural negative: a loader route without loading()
+
+The loading-less branch awaits loader data at TREE-BUILD, above every Suspense
+boundary, so under capture's masked loaders the whole tree pins above `<body>`,
+the prelude comes back trivial, and the sanity gate refuses to store. Observable
+symptom: `x-rango-shell: MISS` forever plus a once-per-key worker warning. Add
+`loading()` to the loader route and keep shell material in a layout.
 
-```typescript
-export const urlpatterns = urls(({ path, layout, loader, loading }) => [
-  // Shell: header, nav, islands, handle pushes. Frozen into the prelude.
-  layout(ProductShellLayout, () => [
-    // Hole: the live price. Masked at capture, fresh on every serve.
-    path("/products/:id", PricePage, { name: "product" }, () => [
-      loader(LivePriceLoader),
-      loading(<PriceSkeleton />), // the boundary capture postpones at
-    ]),
-  ]),
-]);
-```
+## Execution matrix
 
-**Why a route without `loading()` can never be a hole — even with a fast
-loader.** The loading-less branch in `renderSegments` (`src/segment-system.tsx`)
-awaits loader data at TREE-BUILD (`await buildLoaderPromise(...)`), above every
-Suspense boundary. That await is SHALLOW — it settles only the loader's OUTER
-value — but during capture the loader is masked WHOLE: `createMaskedLoaderPromise`
-(`src/router/segment-resolution/loader-mask.ts`) hands back a never-resolving
-promise for the entire value, so even the outer never settles. The tree-build
-await pins the whole tree above `<body>`, the prelude comes back trivial, and
-the sanity gate refuses to store. Observable symptom: `x-rango-shell: MISS` on
-every request forever, plus a **once-per-key** worker warning you can grep for —
-`produced no usable shell … without a route-level loading() boundary`
-(`src/rsc/shell-capture.ts`).
-
-Whole-loader masking is deliberate scar tissue, not a limitation to route
-around. Loaders are the ONE lane exempt from the `cookies()`/`headers()` capture
-guard — they always run fresh on serve — so running a loader even _partially_
-during capture could bake a per-user outer field into the shared shell, breaking
-freshness and the security model at once. Finer-grained masking is intentionally
-not offered. A hand-rolled `<Suspense>` around a `useLoader()` reader does not
-help either: the pin is at the tree-build await, which is _above_ it.
-
-## Loader-carried promises: streaming inside a hole
-
-A hole is not limited to one value. A loader can return its outer value fast and
-carry a **nested promise** that settles later; `FlightSerialize` preserves the
-`Promise` across the RSC boundary (`src/serialize.ts`), so the client `use()`es
-it under its OWN inner `<Suspense>` — a second streaming layer _inside_ the hole.
+| Phase            | MISS (foreground)      | Background capture                                                 | HIT (foreground)                                            |
+| ---------------- | ---------------------- | ------------------------------------------------------------------ | ----------------------------------------------------------- |
+| Middleware chain | runs (full)            | **NOT re-run** — inherits the request's post-middleware context    | runs (full) — commit point is after it                      |
+| `router.match`   | runs                   | re-runs under a derived context                                    | runs (behind the flushed prelude)                           |
+| Handlers         | run                    | run on UNCACHED segments; `cache()`d segments replay (mixed-chain) | run (same mixed-chain rules as any render)                  |
+| Loaders          | run **fresh**          | **MASKED** (never execute) — the structural holes                  | run **fresh**                                               |
+| Flight render    | full                   | full                                                               | full (hydration needs the whole payload — no Flight resume) |
+| HTML production  | full fizz              | `prerender` + abort → prelude + postponed                          | `resume` only the holes — O(paths to holes)                 |
+| Shell store      | schedules a bg capture | `putShell(key, …)`                                                 | `getShell(key)`; a stale/SWR hit also schedules a recapture |
+| Prelude bytes    | —                      | —                                                                  | flushed FIRST, before segment resolution starts             |
+
+Middleware is not re-run during capture because it already ran for the
+triggering request — the capture's derived context inherits the
+post-middleware state (`ctx` variables included, which is what makes
+middleware-derived shell content photograph correctly). Guarding is
+serve-time: the commit point runs the full chain on EVERY serve.
+
+Because handlers on uncached segments EXECUTE during capture, the
+`cookies()`/`headers()` capture guard is load-bearing: those reads THROW during
+a capture render (`assertNotInsideShellCapture`), so identity can never leak
+into a shared shell through them. Loaders are exempt (always fresh).
+
+## allReady: the SEO/bot story
+
+`ssr: { resolveStreaming: ... }` returning `"allReady"` (e.g. for bot user
+agents) bypasses PPR entirely — the request gets one complete, fully-buffered
+axis-1 document. Crawlers that dislike streamed shells get a finished page;
+regular users get the streamed shell. No configuration interaction: allReady
+wins.
 
-```typescript
-// loader — outer resolves fast; the nested promise settles later
-export const StreamLoader = createLoader(async () => {
-  const pendingData = new Promise<string>((r) =>
-    setTimeout(() => r("slow inner value"), 300),
-  );
-  return { label: "fast outer value", pendingData };
-});
-```
+## Security
 
-```tsx
-// consumer (client): use() the nested promise under an INNER Suspense
-"use client";
-import { Suspense, use } from "react";
-import { useLoader } from "@rangojs/router/client";
-
-function Inner({ promise }: { promise: Promise<string> }) {
-  return <span>{use(promise)}</span>;
-}
-
-export function StreamView({ loader }: { loader: LoaderDefinition<Data> }) {
-  const { data } = useLoader(loader); // resolves the OUTER value
-  return (
-    <>
-      <div>{data.label}</div>
-      <Suspense fallback={<div>loading inner…</div>}>
-        <Inner promise={data.pendingData} /> {/* streams the nested value */}
-      </Suspense>
-    </>
-  );
-}
-```
+Shell caching shares one shell per host+URL across all users:
 
-Route shape is unchanged: `loader(StreamLoader)` + `loading(<Skeleton />)`. On a
-**HIT** the resume streams three progressive layers in one response body:
-
-1. the cached shell prelude (layout + the `loading()` fallback) — flushed
-   instantly, before any render work;
-2. the outer loader value fills the hole, carrying the inner `<Suspense>`
-   fallback;
-3. the nested-promise inner value + React's `$RC` boundary stitch.
-
-Capture never sees any of this: the loader is masked, so the whole subtree
-postpones at `loading()` and the nested promise costs nothing at capture time.
-That is what makes loader-carried promises DETERMINISTIC — contrast the
-handler-passed promise below, which races the capture's quiet window. The
-three-layer timeline is pinned in dev + production e2e
-(`tests/cloudflare-basic/e2e/ppr-shell.test.ts`, `e2e/shell-cache.test.ts`).
-
-One nuance: a loader with a `cache(...)` config deep-settles on write, so a
-loader-cache HIT delivers the inner promise already resolved.
-
-## live(): a deterministic hole for any boundary
-
-`loading()` makes a route LOADER a hole. `live()` makes ANY boundary a hole —
-including one whose data is already resolved. During the background capture
-`live()` behaves exactly like the loader mask: it returns a never-settling
-promise, so the consuming `<Suspense>` postpones and the prelude freezes only the
-fallback. On the serve pass (and on the client) it is a passthrough — the thunk
-runs, or the promise passes through unchanged.
-
-```tsx
-import { Suspense } from "react";
-import { live } from "@rangojs/router";
-
-async function Greeting() {
-  // Promise.resolve(...) would normally SETTLE during capture and bake into the
-  // shared shell. live() holds it out, so this boundary postpones instead.
-  const name = await live(() => Promise.resolve(currentUserName()));
-  return <span>Hi {name}</span>;
-}
-
-// under the frozen shell:
-// <Suspense fallback={<span>…</span>}>
-//   <Greeting />
-// </Suspense>
-```
+**(a) Access control is sound by construction.** The commit point is after ALL
+middleware on every serve. A 401/redirect short-circuit returns before any
+shell byte.
 
-Two forms:
-
-- **Thunk (preferred): `live(() => value)`** — during capture the thunk NEVER
-  runs (no fetch, no cost); the boundary is a pure hole.
-- **Value: `live(promise)`** — the work already fired before `live()` saw it, so
-  during capture the real promise is DISCARDED and a hole returned in its place.
-  Use it only when you already hold the promise; prefer the thunk otherwise.
-
-`live()` is what makes a resolved value a hole at all: a bare `Promise.resolve(x)`
-under `<Suspense>` settles inside the capture's quiet window and freezes into the
-shell. It is also the escape hatch for the passed-promise trap below. The
-capture/serve split is pinned in dev + production e2e (the "live() makes a
-resolved promise a HOLE" case in `tests/cloudflare-basic/e2e/ppr-shell.test.ts`
-and `e2e/shell-cache.test.ts`).
-
-## Passed promises are not holes
-
-The pattern that looks like a hole but is not: a **handler** creates a promise
-and passes it as a prop to a client component that `use()`s it inside its own
-`<Suspense>`. Only route **loaders** (and `live()`) are masked at capture — a
-handler and any promise it creates EXECUTE during the background capture render.
-What happens next is decided by the promise's LATENCY CLASS against the
-capture's quiet window (task-quantized: it closes a couple of macrotask hops
-after the last Flight byte, not on a wall clock). Both sides are reliable —
-just in opposite directions:
-
-- Resolved or microtask-resolvable (`Promise.resolve`, a warm in-memory read):
-  reliably SHELL, every capture — it settles in the same window as plain JSX.
-  If the value is per-request, that is a deterministic bug: frozen into the
-  shared shell until TTL (hydration repairs it from the fresh payload —
-  degraded, not corrupt, but a drift you shipped).
-- Genuinely pending real I/O: reliably a HOLE — it cannot win a task-quantized
-  window. Resume fills it at serve. The capture still paid the promise's
-  execution cost and side effects, though. The only nondeterministic sliver
-  left is I/O completing within ~2 event-loop turns of the shell going quiet
-  — freakishly fast, self-healing via TTL/recapture, and only reachable by
-  code that declared no intent.
-
-An async HANDLER (a streamed `loading()` handler returning a promise) is the
-deliberate opposite: it is tracked in the handle store, and capture WAITS for
-handlers to settle before aborting — handler output is shell material by
-design, never a hole.
-
-Verdict: a promise's latency class picks its side — you can safely assume a
-genuinely pending, unresolved promise becomes a hole. But that decision was
-made by latency, not by you. Wherever intent and latency could disagree —
-per-request data that might get cache-fast, a value that must never appear in
-the shared shell — say it in code: **`live()`** for a guaranteed hole (masked
-at capture like a loader; prefer the thunk form so nothing runs during
-capture), a loader behind `loading()` for route-level live data (zero capture
-cost, and its nested promises stream too, per above), a plain `await` for
-shell-safe deterministic data. Unwrapped promises are for the cases where
-either outcome is acceptable.
-
-Note on `useLoader()`: it never observes pending data. Inside a `loading()`
-route, `LoaderBoundary` resolves the loader promise INSIDE its own Suspense
-before children render, so `useLoader().data` (the OUTER value) is always
-resolved; `isLoading` is client-side refetch state, not a server pending signal.
-A nested promise on that data is separate — it streams under the consumer's own
-inner `<Suspense>` (above). Multiple holes per page (several `loading()`
-routes/parallels) are fine: resume fills every postponed boundary.
+**(b) Identity can't leak via cookies/headers.** `cookies()` and `headers()`
+THROW during the background capture render. A shell that reads them is
+PPR-ineligible by construction.
 
-## Execution matrix
+**(c) Residual hazard — middleware-derived per-user state.** A `ctx` variable
+set by an upstream auth middleware and rendered by shell material is
+photographed into the SHARED shell (the capture inherits post-middleware
+state). That is scope fidelity working as designed — for shared values. If the
+value is per-user: shell-cache only public/shared pages, put per-user content
+in loaders, or key per variant at the CDN tier.
 
-Three passes, three different cost profiles. The foreground request is never
-blocked on the background capture.
-
-| Phase            | MISS (foreground)      | Background capture                                              | HIT (foreground)                                            |
-| ---------------- | ---------------------- | --------------------------------------------------------------- | ----------------------------------------------------------- |
-| Middleware chain | runs (full)            | **NOT re-run** — inherits the request's post-middleware context | runs (full)                                                 |
-| `router.match`   | runs                   | re-runs under a derived context                                 | runs                                                        |
-| Handlers         | run                    | run                                                             | run                                                         |
-| Loaders          | run **fresh**          | **MASKED** (never execute)                                      | run **fresh**                                               |
-| Flight render    | full                   | full                                                            | full (hydration needs the whole payload — no Flight resume) |
-| HTML production  | full fizz              | `prerender` + abort → prelude + postponed                       | `resume` only the holes — O(paths to holes)                 |
-| Shell store      | schedules a bg capture | `putShell(key, …)`                                              | `getShell(key)`; a stale/SWR hit also schedules a recapture |
-| Prelude bytes    | —                      | —                                                               | prepended by the middleware before the resumed body         |
-
-Loader freshness under PPR is **identical to axis 1**: loaders — the outer value
-AND any nested promise — run fresh on every request, including HITs. Only the
-HTML _around_ the hole came from cache. Background capture is scheduled via
-`runBackground` (`waitUntil` on workerd, fire-and-forget in Node dev), so it
-never delays the served response. Re-deriving through `router.match()` rather
-than a second `next()` is what keeps middleware from running twice
-(`src/rsc/shell-capture.ts`).
+## What always stays on axis 1
 
-## Security
+Non-GET, RSC/partial/action/loader fetches, per-request CSP nonce,
+`streamMode: "allReady"`, redirects, 404s, error renders, routes without `ppr`,
+and any store without the shell family. A stored shell is invalidated when
+`React.version` changes (postponed state is build-coupled), so deploys
+self-heal via recapture.
 
-Shell caching shares one shell per host+URL across all users, so its safety
-rests on three things — the first two are enforced, the third is on you.
-
-**(a) Access control is sound.** The middleware runs on every request, including
-HITs, and composition is **marker-gated**: the middleware prepends the cached
-prelude ONLY when the live response carries the internal `x-rango-shell-resumed`
-marker (`src/cache/shell-cache.ts`). Any middleware short-circuit — a 401, a
-redirect, a 404 — never resumes, so it never carries the marker and passes
-through **untouched**, never composed with a cached shell. Put auth middleware
-upstream of the shell middleware and unauthorized users get their 401/redirect,
-not someone else's cached page.
-
-**(b) Identity can't leak into a shared shell.** `cookies()` and `headers()`
-THROW during the background capture render (`assertNotInsideShellCapture`,
-`src/server/cookie-store.ts`), the same guard family as `"use cache"` and
-`cache()`. A shell that reads cookies is PPR-ineligible by construction.
-
-**(c) Residual hazard — state it plainly.** Middleware-derived per-user state is
-NOT guarded: a `ctx` variable set by an upstream auth middleware and read by a
-handler WITHOUT `cookies()`/`headers()` is invisible to guard (b). The background
-capture inherits the triggering request's post-middleware context and bakes that
-state into the shared shell. Mitigations, in order of preference:
-
-- shell-cache only **public/shared** pages;
-- put all per-user content in **loaders** (the enforced, masked lane);
-- `isEnabled` to disable the middleware for authenticated sessions;
-- `keyGenerator` to add a per-variant dimension (it owns the FULL key identity,
-  including host — see Options).
-
-Shell content that still varies per request degrades to a hydration repair
-(bounded by TTL/SWR), not corruption — but it is a smell. `cache()` the route so
-the same replayed segments feed the captured shell and every resumed render.
+## Options: PartialPrerenderProps
 
-## What always stays on axis 1
+```typescript
+path("/products/:id", Page, { name: "product", ppr: true }, use);
+path(
+  "/products/:id",
+  Page,
+  { name: "product", ppr: { ttl: 600, swr: 120, tags: ["catalog"] } },
+  use,
+);
+```
 
-Non-GET, RSC/partial/action/loader fetches, per-request CSP nonce,
-`streamMode: "allReady"`, redirects, 404s, error renders, and any store without
-the shell family. A stored shell is also invalidated when `React.version`
-changes (postponed state is build-coupled), so deploys self-heal via recapture.
-
-First byte on a HIT does not wait on the shell render or the loader. Hydration
-uses the fresh per-request Flight payload, so interactivity is unaffected.
-
-## Partial navigations
-
-Soft navigations (`_rsc_partial`) bypass this middleware, and that is by
-design, not a gap: a partial response has no HTML tier — no fizz render to
-skip, which is the entire cost document-PPR eliminates. On a `cache()` route a
-partial navigation already delivers the PPR contract at the data tier:
-replayed cached segments flush immediately (in-memory after the store read),
-loaders run fresh and stream their rows into the same response, and the
-client shows `loading()` fallbacks until they arrive. Shell instantly, live
-holes revived — same semantics, different wire format.
-
-For warm-navigation latency, combine `cache()` with prefetching: a prefetched
-partial payload is the client-side analogue of the shell cache, and loaders
-still stream fresh on arrival. Document-PPR covers the cold full-document
-load; prefetch + `cache()` covers navigation.
-
-What partial navigations do NOT get is the byte-level shortcut: the worker
-still deserializes stored segments and re-encodes the Flight payload per
-request. Serving a stored Flight byte-prefix and appending fresh loader rows
-would require hand-managed row-ID alignment — React has no Flight-side
-resume (no postponed-state equivalent exists for Flight) — and is a deferred
-optimization, tracked in the design doc's out-of-scope list.
-
-## Options
-
-| Option         | Default                             | Notes                                                                                                                                  |
-| -------------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
-| `store`        | app-level `_cacheStore`             | must implement `getShell`/`putShell`; the capture writes to the SAME store the middleware reads                                        |
-| `ttlSeconds`   | `300`                               | shell freshness window                                                                                                                 |
-| `swrSeconds`   | —                                   | stale window: serve stale + background recapture                                                                                       |
-| `keyGenerator` | `${host}${pathname}${sortedSearch}` | custom keys own the FULL identity — include the host unless the store is provably single-host (multi-tenant shells must never collide) |
-| `isEnabled`    | —                                   | per-request opt-out predicate (e.g. disable for authed sessions)                                                                       |
-| `skipPaths`    | `[]`                                | path-prefix opt-out                                                                                                                    |
-| `debug`        | `false`                             | HIT/MISS/CAPTURED logging                                                                                                              |
+| 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 render auto-collects — see "Invalidation" below |
+
+The shell store is always the app-level `createRouter({ cache })` store; the
+default key is `${host}${pathname}${sortedSearch}:shell` (host-scoped so
+multi-tenant shells never collide).
+
+## Invalidation: tags vs revalidate()
+
+`updateTag()`/`revalidateTag()` is the ONLY lever that changes the frozen shell
+HTML; `revalidate()` is a DATA lever that never touches it.
+
+A captured shell auto-carries the UNION of the non-loader tags recorded during
+the capture render — every `cacheTag(...)` from a `"use cache"` function or
+`cache()` segment that ran as shell material. Loader tags never attach (the
+holes are already live). `ppr.tags` adds operational tags the render cannot
+know (a tenant id, a deploy marker).
+
+| Lever                                         | Reaches the frozen shell?                                     | Reaches the holes?                                  |
+| --------------------------------------------- | ------------------------------------------------------------- | --------------------------------------------------- |
+| `updateTag` / `revalidateTag` on a SHELL tag  | YES — drops the shell → MISS → recapture                      | n/a (holes are already live)                        |
+| `updateTag` / `revalidateTag` on a LOADER tag | no — loader tags never attach to a shell                      | drops that loader's cached value (if it `cache()`s) |
+| `revalidate()` (named revalidation contract)  | **no** — re-runs segments/loaders for the PAYLOAD, never HTML | yes — the hole re-renders with fresh data           |
 
 ## Pitfalls
 
 - **Loader route without `loading()`**: eternal MISS plus a once-per-key
-  console warning. Move shell material to a layout and add `loading()` (see "The
-  hole contract").
-- **Handler-passed promise for live data**: nondeterministic race, drift into
-  the shared shell. Use a loader behind `loading()`, or wrap it in `live()`.
-- **`live()` value form (`live(promise)`)**: the work already fired before
-  `live()` saw it, so during capture the promise still runs and its side effects
-  still happen — only its result is held out of the shell. Prefer the thunk form
-  `live(() => …)` so nothing executes during capture.
-- **Per-user state via `ctx` variables**: not guarded — see Security (c).
-- **Stacking with `/document-cache`**: pick one per route. The document cache
-  would cache the composite — correct output, but it makes shell caching
-  redundant there.
+  console warning (see "The structural negative").
+- **Per-user value in shell material**: baked into the shared shell —
+  deterministically, not by race (handler promises deep-settle at the ring-3
+  write on cached chains; awaited/resolved values bake everywhere). Put
+  per-user data in a loader.
+- **Theme on a HIT is capture-then-corrected**: the resume tree replays the
+  CAPTURE's `initialTheme` (resume requires it to match the frozen prelude);
+  the visitor's cookie theme is applied pre-paint by the FOUC script and
+  re-synced post-mount by ThemeProvider. Nothing to configure — but a themed
+  component in the shell may briefly render the captured theme's markup before
+  the post-mount re-sync.
+- **Shell shows CAPTURE-time data for the shell's lifetime**: a `cache()`/`"use
+cache"` value baked into the shell is PINNED at capture (the capture data
+  snapshot) and replayed on every HIT, so the shell stays byte-identical to the
+  frozen prelude even after that cache entry expires, gets recomputed, or is
+  tag-invalidated. This is deliberate — parity beats freshness inside the shell.
+  If a shell region needs to be fresh, put it under a `loading()` hole (holes are
+  never pinned) or make the SHELL itself invalidatable by adding the tag to
+  `ppr.tags`. Ring-1/ring-3 tag invalidation does NOT drop the shell.
+- **Uncached nondeterminism in the shell is a hydration hazard**: a raw
+  `Date.now()` / `Math.random()` / uncached `fetch` rendered directly in shell
+  material (outside any cache ring) drifts between capture and hit and the
+  snapshot CANNOT pin it — it was never a cache read. It will mismatch the frozen
+  prelude and detonate hydration. Wrap it in `cache()`/`"use cache"` (then it is
+  pinned) or move it under a `loading()` hole.
+- **Stacking with `/document-cache`**: pick one per route — the document cache
+  would cache the composite.
 - **Dev + HMR**: works, but edits produce stale shells until TTL/recapture.
-- A cold-worker capture can occasionally abort mid-render; it is logged as
-  retryable and the next request recaptures — self-healing, not an error.
+- **Dev cold-start cadence**: expect `MISS -> (in-place retry) -> HIT`. A
+  refused capture is negatively cached with an exponential window (1s doubling
+  to a 60s cap), so declaring `ppr` on an ineligible route never re-renders it
+  on every request.
+- **HIT status is committed at the flush**: a failing hole cannot become a
+  500/redirect after the first shell byte — error UI renders inline via
+  Suspense/error boundaries (the same property any streamed SSR page has after
+  its shell flushes).
 
 ## Related