feat(ppr): producer B — emit the shell entry at build time for prerendered routes (#699) - #701

Closes #699. Builds on the Prerender+ppr composition groundwork merged in #697.

Problem statement

A route combining a build-time handler with the shell option — path("/docs/:slug", Prerender(getParams, handler), { name: "docs", ppr: { ttl, swr } }) — served its first request after every deploy as x-rango-shell: MISS: the complete Flight payload existed since vite build, but the HTML prelude half of the shell entry was produced only by a runtime background capture triggered by traffic. Every deploy paid a cold MISS, capture latency, and warm-up traffic per URL, and the capture path is physics-sensitive (quiet windows, cold module graphs) — the entire CI hardening campaign in #697 exists because of it. This PR produces the complete ShellCacheEntry at vite build (producer B), so the first-ever request serves x-rango-shell: HIT with the frozen prelude and live streaming loader holes. Dev gets the same semantics via on-demand production.

Before vs. after

// The route definition is UNCHANGED — no new API:
path("/pp/:slug", PrerenderPprArticle, { name: "pp.article", ppr: { ttl: 300, swr: 120 } })

# BEFORE (runtime capture only)              # AFTER (producer B)
$ curl -H "Accept: text/html" /pp/alpha      $ curl -H "Accept: text/html" /pp/alpha
x-rango-shell: MISS   <- first request       x-rango-shell: HIT    <- first request
...background capture runs...                (frozen prelude + streaming loader hole,
$ curl -H "Accept: text/html" /pp/alpha       loaders live: seq advances per request)
x-rango-shell: HIT    <- second request

End-to-end consumer example

// src/urls/docs.tsx
export const DocsArticle = Prerender(
  async () => (await listSlugs()).map((slug) => ({ slug })),
  async (ctx) => (
    <article>
      <h1>{(await getDoc(ctx.params.slug)).title}</h1>
      <ParallelOutlet name="@viewers" />
    </article>
  ),
);

export const docsPatterns = urls(({ path, loader, loading, parallel }) => [
  path("/docs/:slug", DocsArticle,
    { name: "docs.article", ppr: { ttl: 86_400, tags: ["docs"] } },
    () => [parallel({
      "@viewers": {
        handler: ViewerBadge,
        use: () => [loader(ViewerCountLoader), loading(<span>...</span>)],
      },
    })],
  ),
]);

vite build now logs SHELL OK /docs/<slug> per URL and the deployed worker serves every first request as a shell HIT: the article HTML is the frozen prelude, the viewer badge streams fresh per request, and updateTag("docs") evicts the baked entries.

Semantics

Code changes

Build (producer B):

• vite/discovery/prerender-collection.ts + router/prerender-match.ts: matchForPrerender surfaces the matched route's ppr option; collection records shell candidates and retains Flight payload JSONs on DiscoveryState.
• vite/discovery/shell-prerender-phase.ts (new): a buildApp post hook — the prelude embeds the BUILT client bootstrap URL, which does not exist at buildStart — reuses the buildStart temp server (kept alive on state), seeds an in-realm prerender store from the retained payloads, and drives the capture per URL. Stages __ps-*.js assets + a lazy __shell-manifest.js and injects globalThis.__loadShellManifestModule into the built RSC entry (mirroring the prerender manifest; the worker handles every request — no static file serving). Manifest keys are pathname-only: router $$ids hash filePath:lineNumber of the TRANSFORMED source and differ between the temp server's transform chain and the main build's, so a temp-realm router id can never be looked up by the shipped worker; cross-router pathname collisions are declined at build instead.
• prerender/build-shell-capture.ts (new): the capture core over a synthetic build request context (createRequestContext over the build env — no ambient identity, so the identity guard is trivially satisfied). Reuses producer A verbatim via deriveShellCaptureContext (extracted from attemptCapture in rsc/shell-capture.ts — mask funnel, liveness bookkeeping, snapshot recording, implicit doc-cache scope; one implementation, two producers) + the existing captureAndStoreShell. The capture's match() re-enters withCacheLookup and REPLAYS the prerender store — no handler execution, the fix(vite): prerender collection ran trieless — catch-all shadowed nested routes; Prerender + ppr composition coverage #697 composition path — and a fetchedKeys assertion refuses any capture that never consulted the store. Entries are stamped with the MAIN build's version (new api.getBuildVersion() on the version plugin — the temp server's own stamp would fail the serve gate forever).
• SSR half: composed from the temp server's SSR environment runner (react-dom/static prerender + Flight client) with the built entry as bootstrap. Production-hashed client references (only resolvable in built bundles) bridge to dev refKeys through a wrapped __vite_rsc_client_require__ using the same computeProductionHash reverse map. The fix(vite): prerender collection ran trieless — catch-all shadowed nested routes; Prerender + ppr composition coverage #697 payload-settlement abort gate is inherited — first attempt lands on cold graphs.

Serve:

• rsc/shell-build-manifest.ts (new): lookupBuildShell on a runtime shell-store MISS in rsc-rendering.ts, serving through the same serveShellHit. Gates: search-less request, reactVersion/buildVersion, payload integrity, tag markers. Every fault degrades to a MISS.
• cache/types.ts + three stores: new optional isTagsInvalidatedSince(tags, sinceMs) — CF wraps its existing KV tag-marker check; the memory store records per-tag invalidation instants; the Vercel store writes its own tm-family markers on invalidateTags (the platform's expireTag deletes entries and keeps no queryable history; marker writes are strict so a failed one rejects like a failed expireTag).

Dev:

• /__rsc_shell endpoint (router-discovery.ts), mirroring /__rsc_prerender: runs the same capture core in the dev realms (main-server envs on node; the shared temp Node server on cloudflare, whose virtual:entry-ssr now lazily resolves to the REAL rango SSR entry), memoized per router HMR generation AND caller version. Policy-free: the serve gate sends the resolved ttl/swr/tags/version. A /__rsc_prerender pre-flight warms the payload memo and refuses non-prerenderable routes. The read-through's dev branch arms only for trie pr-flagged routes and its fetch is deadline-bounded at 20s (the response IS an inline capture: attempt + in-place retry).

Bundled fix — handlerLiveHoles dropped by persistent stores (pre-existing #695 bug): both KVShellEnvelope and VercelShellEnvelope omitted the flag, so a handler-live entry read back from KV/Vercel silently armed the handler-free fast path — holes only a handler re-run can fill never filled on a HIT. Fixed with round-trip regression tests, shown red without the envelope fix (2 failed) and green with it (52/52). Producer B needs the flag to survive persistence, which is where it became load-bearing.

Test plan

• Unit (red-before-green for the envelope fix): shell envelope round-trips (CF + Vercel), isTagsInvalidatedSince on all three stores, lookupBuildShell serve gates incl. the dev branch — 88 tests across 4 files; pnpm run test:unit:all green.
• E2e, dev + production, both apps: prerender-ppr.test.ts (test-app) and ppr-shell.test.ts (cloudflare-basic) gain: first-request HIT with frozen prelude + hole fallback (pins the zero-runtime-capture contract on bare pathnames), loader liveness across baked HITs (seq advances — loaders never bake), updateTag eviction (dedicated route+tag per app; baked entry rejected via markers, then producer A recaptures). Existing ?probe= composition tests keep passing untouched (search-bearing URLs never read the manifest). Local: test-app 7/7 dev + 7/7 production; cloudflare-basic 24/24 production + 24/24 dev.
• pnpm run typecheck, pnpm run lint, pnpm run format, pnpm check:e2e-bucketing — green; *.gen.ts regenerated in both apps.
• Manual: vite preview first-ever request to /pp/alpha = HIT with built bootstrap URL in the prelude; dev server first request = HIT via /__rsc_shell.

Notes

• Userland testing primitives: no new primitive-reachable API (the ppr path option is unchanged; producer B is build/serve infrastructure), so coverage is unit + dev/production e2e rather than a testing-primitive extension.
• Router id instability across realms (found here): $$id hashes filePath:lineNumber of TRANSFORMED source, so dev-transform and build-transform ids differ for the same createRouter(). Producer B routes around it with pathname-only manifest keys; worth its own issue — anything else assuming cross-realm id stability (state cookie names?) inherits the same hazard.
• Store-less apps: a ppr route without a shell-family store still degrades to axis 1 with the existing warning; baked entries are not served without a store. Deliberate: staleness/eviction semantics need the store.
• Preinit head links: build-time preludes carry the built bootstrap (bootstrapModules form) but not the perf(ssr): head-executing module scripts — preinit client-reference chunks, bootstrapModules entry #694 preinit chunk links (the hook isn't installed in the phase's composed SSR half). Perf-only; a follow-up can feed the built chunk map.
• Vercel preset ordering: the shell phase's buildApp post hook runs before vercel-output.ts's (plugin order), so .vercel/output picks up the shell manifest; not yet exercised by a vercel e2e.