fix(vite): prerender collection ran trieless — catch-all shadowed nested routes; Prerender + ppr composition coverage - #697

Problem statement

Two consumer-observable problems, found by the same coverage work:

1. Prerender + ppr composition was unverified. A route combining a build-time Prerender() handler with the ppr shell option — "the shell exists before the first visitor, loaders stream live" — had zero test coverage in either app, so nothing pinned that the two caching axes compose.
2. A real collection bug (pre-existing, no ppr needed): in an app that declares a root path("/*") catch-all before a layout-nested Prerender route, pnpm build logged OK for every enumerated URL but baked the catch-all page's content under catchAll/<paramHash> manifest keys. At runtime the (correct) trie matched the real route, found no manifest entry, and — with the handler evicted to a stub — served a hard 404 DataNotFoundError for every prerendered URL. Without eviction the failure is quieter and worse: wrong content served as a healthy 200.

Root cause

Build-time prerender collection resolves each enumerated URL through matchForPrerender → findMatch(pathname) in the RSC runner realm. findMatch is trie-first with a regex fallback, and the fallback is insertion-order-sensitive — the design note in rsc/manifest-init.ts says it plainly: "The trie is essential for correct wildcard priority — without it, the regex fallback matches catch-all patterns before specific routes."

Dev installs the tries into the RSC realm on every discovery/HMR pass (propagateDiscoveryState). But that lives inside configureServer, which early-returns in build mode — so collection was the one findMatch consumer in the system running trieless. /ppr-shell/prerendered/alpha → regex fallback → /* wins (declared first, same prefix group since layout() doesn't change the URL prefix) → artifact keyed catchAll/<hash> containing the wildcard page.

Why nothing caught it before: include()-mounted prerender routes (articles) form their own static-prefix entry that is spliced ahead of the root entry, and the router's test-app has no root path("/*") at all — the shadowing shape simply wasn't in any fixture.

The fix

src/vite/discovery/discover-routers.ts: after the per-router tries are built and committed to discovery state — and before expandPrerenderRoutes — install them into the RSC realm through the same setters dev uses (setRouteTrie + the per-router setRouterManifest/setRouterTrie/setRouterPrecomputedEntries loop, mirroring propagateDiscoveryState). Build-collection, dev, and runtime now share the identical trie-ranked matcher. markRouterTrieAuthoritative is deliberately NOT called, so a genuine trie gap still falls back to regex, exactly as in dev.

if (serverMod.setRouteTrie && newMergedRouteTrie) {
  serverMod.setRouteTrie(newMergedRouteTrie);
}
const perRouterSetters: Array<[Map<string, unknown>, string]> = [
  [newPerRouterManifestDataMap, "setRouterManifest"],
  [newPerRouterTrieMap, "setRouterTrie"],
  [newPerRouterPrecomputedMap, "setRouterPrecomputedEntries"],
];
for (const [map, fn] of perRouterSetters) { /* … */ }

This is bundle-safe: the setters run on the build's temp RSC server at discovery time (the same call dev makes), not in the emitted eager manifest chunk.

The composition, now pinned end to end

path(
  "/pp/:slug",
  PrerenderPprArticle,                                   // Prerender(getParams, handler)
  { name: "pp.article", ppr: { ttl: 300, swr: 120 } },   // + the shell option
  () => [
    parallel({
      "@ppseq": {
        handler: PrerenderPprSeqSlot,                    // slot-owned live data
        use: () => [loader(PrerenderPprSeqLoader), loading(<Fallback />)],
      },
    }),
  ],
),

Semantics pinned by the suites (identical fixture shape in both apps):

Test plan

• Red-before-green for the fix: the cloudflare composition test failed on unfixed code with the exact consumer symptom (404, DataNotFoundError, manifest carrying two corrupted catchAll/<hash> artifacts with params: {"*": "ppr-shell/prerendered/…"}); with the fix the manifest bakes pprShellPrerendered/<hash> keys, the bogus catchAll artifacts disappear, and the suite is green.
• New e2e: prerender-ppr.test.ts (test-app, 4 tests: MISS→HIT, prelude/hole composition, loader liveness across HITs, per-param shells) — dev AND (production). Cloudflare-basic: composition test inside describePprShell — dev AND (production), full suite 288/288 on workerd/KV locally. THE DECISIVE ROOT CAUSE (found via per-phase capture instrumentation, validated red-to-green on truly cold boots): Flight byte-quiet is not fizz render-readiness. A fully REPLAYED (prerendered) route's capture Flight render is pure replay — all bytes emit in ~1-3ms and go quiet — so the quiesce fired and the abort followed after 16 near-zero-cost macrotask hops, while fizz could not emit even <html> until the payload root settled (every referenced client-module load = real module-runner I/O in dev: 2-6ms warm, 137-184ms cold, worse on GH runners). The abort landed first → zero-byte prelude → NULL on every attempt (dev's per-render $$cache= reference tag defeats module-load memoization, so retries re-pay the I/O). Ordinary ppr routes never hit it — live handler execution keeps Flight noisy long enough. Fixed in captureShellHTML: the abort now additionally awaits payload settlement (SsrRootOptions.onPayloadSettled) or the prerender itself settling, bounded by the existing maxWaitMs deadline. Cold boots (rm -rf .vite) now land the FIRST capture attempt.

Along the way the same investigation surfaced and fixed three adjacent hardening gaps, all keepers: per-isolate capture serialization (concurrent captures starved each other's quiet windows — an earlier revision CI-skipped the cloudflare DEV instance over this before the true root cause emerged — concurrent captures starve each other's task-quantized quiet windows (one grinding capture, here the /__rsc_prerender round-trip whose per-request module re-import pegs a slow runner, keeps a sibling byte-silent past its abort budget: rotating eternal-MISS victims across four CI runs). Fixed in this PR by serializing capture execution per isolate (src/rsc/capture-queue.ts, unit-tested: concurrency=1, order, rejection isolation); the quarantine and warmup exclusions are fully lifted — every test runs everywhere again. Validated post-fix: router shell suites 32+32 dev+production, cloudflare ppr battlefield 26/26 and the full suite under CI=true with zero capture cross-talk.

• Existing prerender nets green: test-app prerender suite 60/60 (dev+production); cloudflare prerender/articles/build-output suites inside the 288.
• Vite-plugin safety nets: hmr project suites 14/14, route-types 4/4 (the CLAUDE.md-named route-types-hmr spec does not exist; these are the current equivalents).
• Gate: pnpm run typecheck, pnpm run test:unit:all (0 failures), pnpm run lint, pnpm run format; *.gen.ts committed for both apps.

Notes

• The bug predates the shell fast path and does not require ppr — any getParams-bearing Prerender route declared inline under layouts after a root catch-all baked wrong-content artifacts. ppr only made the symptom louder (404 instead of silently serving the catch-all page as a 200).
• With the fix, collection also stops producing the corrupted catch-all artifacts, shrinking the manifest to only real entries.
• This composition is the on-ramp to "producer B" (build-time shell entries — Prerender emitting the PPR shell itself); that remains a named follow-up.