feat(router): PPR shell caching — createShellCacheMiddleware, prelude+postponed store family, fizz resume - #641

Problem

Even on a full segment/prerender cache hit, the worker re-does the whole HTML tier on every document request: deserialize stored segments, re-encode a fresh Flight stream, then run a complete fizz render over the entire tree. TTFB always pays for the shell render and every upstream read it needs. The only HTML-level cache a consumer had was the all-or-nothing document cache — which freezes loader output too, so any page with live data (prices, stock, per-request content) could not be HTML-cached at all.

React 19.2 shipped Partial Pre-rendering in stable (prerender from react-dom/static + resume from react-dom/server). This PR uses it to add a second, opt-in render axis: cache the rendered HTML shell (prelude bytes + postponed state), serve those bytes on the first read of the request, and resume fizz for just the live loader holes. The browser sees one ordinary streamed document.

Design doc: packages/rangojs-router/docs/design/ppr-shell-resume.md (canonical; includes the POC evidence and the hole contract).

Before / after

// BEFORE — live-data pages could not be HTML-cached: the document cache
// freezes loader output, so /products served stale prices for the whole TTL.
const router = createRouter<AppEnv>()
  .use("/products", createDocumentCacheMiddleware({ ttlSeconds: 300 }))
  .route(...);

// AFTER — the shell (layouts, nav, static content, hydration islands) is
// cached and flushed instantly; loaders stay live and stream into the shell
// per request. First byte no longer waits on the shell render or the loader.
const router = createRouter<AppEnv>()
  .use("/products", createShellCacheMiddleware({ ttlSeconds: 300, swrSeconds: 60 }))
  .route(...);

End-to-end consumer example

The hole contract: shell material lives in a layout; the loader-consuming route below it carries loading() — that boundary is where capture postpones and resume stitches. (Reference fixtures: tests/cloudflare-basic/src/pages/ppr-shell.tsx, packages/rangojs-router/e2e/test-app/src/urls/shell-cache.tsx.)

// router.tsx
const router = createRouter<AppEnv>({ cache: (env) => ({ store: new CFCacheStore({ kv: env.CACHE_KV }) }) })
  .use("/product", createShellCacheMiddleware({ ttlSeconds: 600, swrSeconds: 120 }))
  .routes(urls);

// urls.tsx — shell in the layout, hole behind loading()
layout(ProductShellLayout, () => [            // header, nav, islands, handle reads = shell
  path("/product/:id", PricePage, { name: "product" }, () => [
    loader(LivePriceLoader),                  // masked at capture, fresh on every serve
    loading(<PriceSkeleton />),               // the hole boundary capture postpones at
  ]),
]),

// Second hole primitive — a deterministic hole for ANY boundary, even when
// the data is already resolved (Promise.resolve, warm in-memory reads):
async function Greeting() {
  const name = await live(() => Promise.resolve(currentUserName())); // hole, not shell
  return <span>Hi {name}</span>;
}

First GET: x-rango-shell: MISS, normal axis-1 stream, background capture stores { prelude, postponed }. Later GETs: x-rango-shell: HIT — the frozen prelude (layout + skeleton) flushes before the loader even starts; the live price + React's $RC stitch arrive in the same response.

Semantics

What changed (key mechanics)

• Middleware createShellCacheMiddleware (src/cache/shell-cache.ts, exported from @rangojs/router/cache): bypass matrix, getShell + reactVersion gate, marker-gated composition (prepends prelude bytes iff the render layer set the internal x-rango-shell-resumed marker), host-scoped default keys (${host}${pathname}${sortedSearch}:shell — multi-tenant safe). Calls next() exactly once on every path; on MISS/stale it sets a _shellCapture descriptor before that single next() (the executor's per-entry next() is a single-use latch — an earlier design that re-ran next() for capture threw "Middleware called next() more than once" in real workers).
• Render orchestration (src/rsc/rsc-rendering.ts, src/rsc/shell-capture.ts, src/rsc/full-payload.ts): resume branch (final authority: nonce/allReady/partial/feature-detect guards) marks the response; after the response is built, scheduleShellCapture (stampede-guarded) runs the capture in the background — a derived request context (Object.create(reqCtx): fresh handle store, fresh tag set, _shellCaptureRun: true) re-derives the shell via router.match(), renders a fresh Flight stream over the shared buildFullPayload, then seal → quiesce → prerender + abort → putShell. Quiesce is task-quantized, not wall-clock: the capture Flight stream runs through a gate that declares quiet after 2 consecutive byte-silent macrotask hops and then FREEZES (never closes/errors — pending rows stay pending so fizz postpones them; a late error row can never corrupt a prelude); the fizz side aborts after fixed task hops (maxWaitMs remains only as a pathological guard). Masked loaders emit no bytes, so shell settlement is measured against genuine byte-silence — genuinely pending promises reliably become holes, microtask-resolvable values reliably land in the shell (the same discriminator Next 16 uses, verified against its source).
• Loader masking (src/router/segment-resolution/loader-mask.ts, gated in loader-cache.ts + fresh.ts): during the active capture run only (_shellCaptureRun), route loaders are never executed — their slots get never-resolving promises so the loading() boundary postpones. Strict no-op when the flag is unset.
• SSR strategies (src/ssr/index.tsx, src/ssr/ssr-root.tsx): createShellCaptureHandler / createShellResumeHandler over the extracted createSsrRootComponent, wired by the SSR virtual entry (virtual-entries.ts) importing prerender from react-dom/static.edge and resume from react-dom/server.edge. Capture sanity gate refuses trivial preludes (no <body>); resume handles the no-holes DATA variant.
• Store family (src/cache/types.ts ShellCacheEntry + optional getShell/putShell): implemented in the memory, Cloudflare KV, and Vercel runtime-cache stores; participates in tag invalidation; the middleware threads its resolved store onto the capture descriptor so a store-attached middleware reads and writes ONE store.
• Capture guard (src/server/cookie-store.ts): cookies()/headers() throw during the active capture render, turning a silent cross-user shell leak into a loud capture-time error.
• live() (src/server/live.ts, exported from @rangojs/router): the deterministic hole primitive — our analogue of Next's connection()/hanging-promise pattern, but stronger: the thunk form live(() => fetchX()) never runs during capture (no cost, no side effects), where connection() only marks dynamic. During the capture run it returns a never-settling promise (identical lifecycle to the loader mask); on serve and client it is a passthrough. Guarded against "use cache"/cache() scopes: the inner cache rings deep-settle and freeze values before ring-4 capture could ever mask them, so live() there throws with a use-a-loader message instead of silently freezing (or leaking per-user data into) a shared cache entry.
• Consumer skill (skills/ppr/SKILL.md, indexed in /rango and /cache-guide): the creating-holes decision table (intent → mechanism), the hole contract, the cache onion (PPR as ring 4 between segment cache and document cache), loader-carried promises (three-layer HIT streaming), the passed-promises latency-class doctrine, live(), partial navigations (soft navs are already PPR-shaped at the data tier — bypass is by design), execution matrix, and a first-class security section — including a Next.js-PPR false-friends row (opt-in runtime middleware, loading() holes; a hand-rolled <Suspense> is not a hole).
• Parked follow-up spec (docs/design/vercel-chain-ppr.md): the Vercel CDN-stitched chain protocol (PoP-served shell + POST next-resume with the postponed state length-prefixed inside the fallback file), reverse-engineered from @vercel/next source, with the HMAC-envelope security requirement for any body-transported postponed state. Documented, deliberately not implemented.

Why the background capture uses router.match() instead of a pipeline re-run: the middleware chain (auth, logging, the single-use next() latch) must run once per request; match() re-runs only route handlers/segment resolution and inherits the foreground's post-middleware context state.

Test plan

• Unit: 4780 passed (296 files) + 66 RSC — includes new suites for the middleware (bypass matrix, marker composition, SWR, host scoping, single-next regression under a latched next()), capture orchestration (runShellCapture happy/redirect/null/stampede, store-attached two-store round-trip through the real write path), loader masking (flag semantics: descriptor never masks, only the active run), cookie/header capture guards, SSR capture/resume handlers (fake-deps seam), and CF/Vercel/memory shell store families
• Userland dogfood (mini, @rangojs/router/testing runMiddleware + real memory store): MISS tagging, bypass, HIT composition (prelude-first, $RC + __FLIGHT_DATA in the same body, marker stripped) — 23 passed
• E2E dev and production, cloudflare-basic (e2e/ppr-shell.test.ts) and test-app (e2e/shell-cache.test.ts): 10/10 in each of the four runs — MISS→HIT header flip; HIT first chunk = frozen shell + fallback, no live content, TTFB under the 400ms loader delay; live content + $RC stitch in the same response; loader-carried promise three-layer ordering (shell → outer + inner fallback → inner value); live(() => Promise.resolve(...)) rendered as a hole (fallback before </html>, value after); no-loading() route stays MISS forever while its nested promise still streams on axis 1; HIT hydration with zero hydration errors; RSC bypass; live-path render + soft-nav
• Semantic matrix: 39/39 across projects (axis-1 execution guarantees untouched)
• pnpm run typecheck (15/15), pnpm run lint, pnpm run format, pnpm check:e2e-bucketing — all green on the rebased branch

Notes

• The hole contract is the headline consumer rule: a hole exists only where the route-level loading() boundary separates loader consumption from the shell. A hand-rolled <Suspense> + useLoader is NOT a hole (loader data is awaited at tree-build in the loading-less branch and useLoader reads resolved context data). That shape correctly refuses capture and now warns once per key — previously it was a silent eternal MISS, which is what made this expensive to diagnose. Documented in the design doc ("The hole contract") with the repro evidence.
• Consistency: the fresh Flight payload is hydration's source of truth; shell content that is not cache-replayed or deterministic degrades to a hydration repair, bounded by TTL/SWR. Guidance: cache() the route so the same replayed segments feed capture and every resume; keep per-request data in loaders.
• Document cache vs shell cache: pick one per route — stacking both makes the document cache cache the composite, which is correct output but makes shell caching redundant there.
• Promise doctrine (deterministic capture): a promise's latency class picks its side — genuinely pending promises reliably become holes (they cannot win a task-quantized window); resolved/microtask promises reliably land in the shell. Where intent must decide instead of latency, say it in code: live() for a guaranteed hole, a loader behind loading() for the route-level live lane, await for shell material. The only nondeterministic sliver left is I/O completing within ~2 event-loop turns of shell quiet — self-healing via TTL/recapture, and only reachable by code that declared no intent.
• A cold-worker capture can occasionally abort mid-render (AbortError, logged as retryable via reportCacheError); the next request recaptures and hits — self-healing by design.
• Out of scope (v1, tracked in the design docs): build-time capture in the prerender pipeline, the warm-then-render two-pass for network-fed uncached shells (research attached in the design doc), the Vercel chain adapter (spec parked in docs/design/vercel-chain-ppr.md), CF Cache-API L1 tier for shell entries, deleteShell (mismatched entries age out via TTL), Flight-byte splicing for partial navigations.