feat(router): PPR opt-in via the ppr path option, integral serving, render-defined holes - #645

Problem

PPR shell caching (axis 2) was opt-in only at a middleware mount — router.use(createShellCacheMiddleware({ ttlSeconds, ... })). Three consumer-visible problems: (1) no per-route control — any GET document under the mount became a shell candidate, and the freshness policy lived on the middleware, far from the route it governed; (2) a two-layer design — the middleware decided WHERE while the render layer composed, coupled through an internal x-rango-shell-resumed marker handshake; (3) the promise-hole story was undefined: whether a handler-created pending promise became a hole or shell material had no stated contract a consumer could rely on.

What a consumer writes differently

Opt-in is now a path option on the page route, and there is no middleware at all — serving is integral to the router:

// BEFORE — mount + middleware-held policy
router.use("/products", createShellCacheMiddleware({ ttlSeconds: 600, swrSeconds: 120 }));
export const patterns = urls(({ path, layout, loader, loading }) => [
  layout(ProductShell, () => [
    path("/products/:id", PricePage, { name: "product" }, () => [
      loader(LivePriceLoader),
      loading(<PriceSkeleton />),
    ]),
  ]),
]);

// AFTER — the `ppr` path option IS the opt-in AND the policy; nothing to mount
export const patterns = urls(({ path, layout, loader, loading }) => [
  layout(ProductShell, () => [
    path(
      "/products/:id",
      PricePage,
      { name: "product", ppr: { ttl: 600, swr: 120 } }, // or ppr: true (ttl 300)
      () => [loader(LivePriceLoader), loading(<PriceSkeleton />)],
    ),
  ]),
]);

PartialPrerenderProps { ttl?; swr?; tags? } is exported from the root. createShellCacheMiddleware/ShellCacheOptions are removed (pre-release rule: remove, never deprecate). The shell store is the app-level createRouter({ cache }) store; a ppr route on a store without the getShell/putShell family stays on axis 1 with a once-per-key warning. A route without ppr is pure axis 1 — zero cost, zero logs.

What a consumer sees differently

Commit after ALL middleware. The serve path sits at the top of the render pass that executeRender wraps — after the global router.use() chain AND route DSL middleware(). Any 401/redirect wins before a single shell byte, on MISS and on a warmed HIT. On a HIT the composed response commits eagerly: the stored prelude flushes first while segment resolution / the fresh Flight render / the fizz resume run behind it inside the response stream.

Render-defined holes (the hole doctrine). The background capture is mixed-chain — cache()'d segments replay, uncached handlers execute fresh, middleware never re-runs (the derived context inherits the request's post-middleware state):

• STRUCTURAL: the segment subtree under loading() — loaders masked, the boundary postpones, the fallback bakes as route structure.
• 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.
• SHELL: awaited handler data, top-level push(promise) (awaited pre-SSR, baked — the capture gate now HOLDS for that await), resolved promises, replayed cached segments.

Unified rule: a promise nested inside your data is never baked; the container settles. Want a hole for already-resolved data? loader(() => Promise.resolve(x)) + loading() — which is why live() is removed entirely.

allReady bypasses PPR: ssr.resolveStreaming returning "allReady" (the SEO/bot story) serves one complete axis-1 document.

End-to-end example

Auth-guarded PPR page with middleware-derived shell content:

// global guard — ANY middleware layer guards PPR for free (commit point is after all of them)
router.use("/account/*", async (ctx, next) => {
  const user = await verify(cookies().get("session")?.value);
  if (!user) return new Response("unauthorized", { status: 401 }); // zero shell bytes, even warmed
  ctx.set("orgName", user.orgName); // photographed into the shell by the capture (scope fidelity)
  return next();
});

export const patterns = urls(({ path, layout, loader, loading }) => [
  layout((ctx) => <AccountShell org={ctx.get("orgName")} />, () => [
    path("/account/usage", UsagePage, { name: "usage", ppr: { ttl: 300, swr: 60 } }, () => [
      loader(LiveUsageLoader),          // the hole — fresh every request
      loading(<UsageSkeleton />),
    ]),
  ]),
]);

Semantics table

Code-change summary

• urls/pattern-types.ts + urls/path-helper.ts + server/context.ts — PartialPrerenderProps, the ppr PathOption, stored on the route EntryData; exported from both root indexes.
• rsc/shell-serve.ts (new) — resolvePprConfig (default ttl 300), host-scoped buildShellKey, reactVersion gate, hasShellFamily + once-per-key warning.
• rsc/rsc-rendering.ts — the commit point: ppr config read off the classified route snapshot (available pre-match, enabling the eager HIT flush), serveShellHit (prelude-first composed stream; tail kicked off synchronously inside the ALS frame), MISS tagging + capture scheduling. The resume-marker branch and maybeScheduleShellCapture policy layer are gone.
• cache/shell-cache.ts deleted; exports removed from cache/index.ts. _shellResume/_shellCapture request-context flags removed (ShellCaptureDescriptor is passed by value); _shellCaptureRun stays.
• rsc/shell-capture.ts — replay-only bail removed (mixed-chain capture); gateFlightForCapture gains holdUntil (held for getData().then(resolveDeferredHandleValues)) so top-level pushed handle promises bake deterministically; retry/backoff/stampede/quiesce machinery unchanged.
• router/match-middleware/cache-lookup.ts — reverted to main (bail seam removed).
• src/server/live.ts + tests + all fixture usage removed.
• Kept from the prior arc: shell store family, SSR capture/resume strategies, task-hop quiesce (POST_QUIESCE_TASK_HOPS 16 — the replay Flight emits in one tick, fizz needs post-quiesce turns), retry + exponential backoff, host-scoped keys, reactVersion gate, SWR recapture, tags auto-collection.

Handle-semantics verification finding: the required contract already matched shipped code — resolvedHandleStream (handles/deferred-resolution.ts) awaits only top-level thenables (shallow isThenable) and passes containers through verbatim. The one gap was the capture gate freezing before a real-latency top-level pushed promise resolved; holdUntil closes it (holes emit no bytes, so holding only admits shell rows; bounded by the 5s guard).

Test plan

• Unit: integrated serve path against a REAL memory store (MISS policy/default-ttl/props flow-through, HIT prelude-first composition, stale/SWR recapture, reactVersion gate, host-scoped keys, no-ppr = zero store reads + zero logs, ppr:false, nonce/allReady bypasses, missing-store-family warn-once, non-200 no-schedule); capture gate holdUntil; shell store family; capture retry/backoff suite (bail test removed).
• pnpm run test:unit:all (root): router 296 files / 4774+ tests, mini, cloudflare, vite-rsc-demo — all green (+ RSC suites).
• E2e dev + production, both apps: test-app 18/18 dev + 18/18 prod (MISS→HIT, HIT streaming+TTFB, hydration-zero-errors, loader-carried 3-layer, physics hole, handles pair, no-loading() negative, security: 401 zero-shell-bytes for global AND route-DSL middleware, scope fidelity, middleware-run counter, action correctness incl. updateTag drop+recapture, PE POST); cloudflare 10/10 dev + 10/10 prod (incl. physics hole; DSL-attachment tests removed with the feature).
• Semantic matrix: dev 20/20 incl. rewritten [PPR1] (commit-after-all-middleware + capture-never-reruns-chain + scope fidelity) and kept [PPR2] (serve-time guarding); production PPR rows pass. execution-model.md updated in the same PR.
• pnpm build-router, repo-root typecheck (15/15), lint, format, check:e2e-bucketing, check:docs-api.

Notes / call-outs

• Removed public APIs: createShellCacheMiddleware, ShellCacheOptions, live() — removed, not deprecated (pre-release rule). Migration: replace mounts with the ppr path option; replace live() with a loader behind loading().
• HIT status commits at the flush: a failing hole cannot become a 500/redirect after the first shell byte — error UI renders inline (the standard streamed-SSR property). A near-unreachable redirecting match on a HIT degrades to a client-side location.replace.
• Ring-3 writes on HIT serves: the composed HIT response drains onResponse callbacks at commit (before match), so a HIT serve does not write the segment cache. Correctness is unaffected (the foreground MISS/axis-1 path writes it); noted as a perf nuance.
• Subtree inheritance of ppr (declaring it on a layout) is deliberately out of scope — noted follow-up.
• Design doc grew a dead-ideas ledger covering the full arc: middleware-as-public-surface, cache({ ppr }) coupling (segment-granular primitive for a document property), replay-only capture (deleted the promise-hole contract), the live() story, response-header opt-in, standalone shellCache(), automatic no-key capture, full-pipeline capture dispatch.