- PPR shell caching (the `ppr` path option; `PartialPrerenderProps` exported from the root) — an opt-in second render axis, integral to the router (no middleware). It caches the rendered HTML shell (React `prerender`'s prelude bytes plus the `postponed` resume state, one coupled `ShellCacheEntry`) and, on a hit, commits the composed response after the WHOLE middleware chain: prelude bytes flush first, then fizz resumes only the holes; the browser sees one ordinary streamed document. Holes are render-defined — `loading()` subtrees (structural; loaders masked at capture), pending promises in handed-over data under the consumer's Suspense (physics), everything else shell (top-level pushed handle promises are awaited pre-SSR and baked; the capture gate holds for that await, bounded by `ppr.captureTimeout` — default 15s; expiry with pushes pending refuses the capture, so a partial head snapshot is never stored). The background capture is mixed-chain (cached segments replay, uncached handlers execute — the cookies()/headers() capture guard is load-bearing) and never re-runs middleware (the derived context inherits post-middleware state). Backed by the optional `getShell`/`putShell` store family (memory/CF/Vercel), reactVersion+buildVersion-gated (isValidShellHit; a redeploy invalidates like a React upgrade, hasIntactShellPayload rejects corrupt payloads pre-commit, a failed HIT tail schedules a healing recapture) and tag-invalidatable. Shell/payload PARITY on a HIT is guaranteed by the CAPTURE DATA SNAPSHOT (`cache/shell-snapshot.ts`, internal): a pre-render write barrier settles the foreground's deferred cache writes so the capture replays the foreground's cache generation (never clobbers it); the capture render records its cache-store read-hits + writes (`RecordingShellStore`, excluding the shell family; `captureAndStoreShell` fires the capture's isolated `onResponse` so the ring-3 segment write runs and is recorded), stores them on `ShellCacheEntry.snapshot` (carried through the CF/Vercel envelopes), and `serveShellHit`'s tail render replays them AS FRESH (`SeededShellStore`) so a shell-baked cached value that DRIFTED (shorter-ttl `cache()`, tag-invalidated item) still matches the frozen prelude — parity beats freshness inside the shell; freshness comes from holes, the shell ttl/swr, and `ppr.tags`. Actions, progressive enhancement, per-request nonce, and `streamMode: "allReady"` (the SEO/bot story) always take axis 1. On a HIT the tail's hydration payload is FRAGMENT-SPLICED (#700): replayed segments carry their STORED per-segment Flight strings verbatim (`__rangoFragment` envelopes, `src/segment-fragments.ts`) instead of being deserialized and re-serialized per request; the SSR resume pass and browser hydration expand them through their own Flight deserializers, so the browser still can't tell. Operability (issue #651): `PartialPrerenderProps.maxSnapshotBytes` (default 8 MiB) skips an over-cap snapshot (shell still stored; once-per-key report; documented drift on later HITs); the `debugShellCapture` router option (`ShellCaptureDebug`/`ShellCaptureDebugEvent`, exported) emits one structured event per capture attempt/skip — outcome, barrier/write-settle waits, prelude/snapshot bytes, backoff state — and in dev the terminal event mirrors into the NEXT ppr GET's Server-Timing (`ppr-capture;desc="…"`, plus a `ppr:shell-read` metric); a KV-less `CFCacheStore` warns once per isolate that its shell family is inert. See [PPR shell caching design](../design/ppr-shell-resume.md).
0 commit comments