refactor(vite): lazy per-router chunk carries only derived match data + rule #1 bundle guard - #751

Problem statement

The lazy per-router virtual module (virtual:rsc-router/routes-manifest/<routerId>) re-exported the route name->path map even though the eager manifest module already sets the identical map via setRouterManifest(). On first request, ensureRouterManifest() overwrote the eagerly-set map with the lazy copy — two write paths into perRouterManifestMap where last-writer-wins would silently mask any future divergence between them. For routers without a gen file, the map was genuinely inlined twice (once in the eager module, once in the lazy chunk) — duplicated route data in two chunks, the exact shape Bundle Hygiene rule #1 exists to prevent, just below the size where anyone noticed. Separately, rule #1 (route data in exactly one lazy chunk) had no build-time guard at all — only the dev-React check existed in build-test-app.setup.ts.

No consumer-visible change: public API, generated .gen.ts files, and runtime behavior are identical; reverse()/href() resolve from the same eagerly-set map as before.

Before vs. after (generated lazy per-router module)

Before:

import { NamedRoutes as _r } from "/app/src/router.named-routes.gen.js";
function __flat(r) { /* O(routes) flatten, second run of the same transform */ }
export const manifest = __flat(_r);
export const trie = JSON.parse("…");
export const precomputedEntries = JSON.parse("…");

After:

import "/app/src/router.named-routes.gen.js"; // module-graph edge for dev invalidation only
export const trie = JSON.parse("…");
export const precomputedEntries = JSON.parse("…");

The bare import is load-bearing: it is the edge that invalidates the per-router module when routes change in dev. Without it, a Cloudflare dev program reload re-imports the cached module and ensureRouterManifest() re-installs a stale authoritative trie (wrong 404s until full restart). Pinned by a codegen unit test.

Semantics

Code-change summary

• src/vite/discovery/virtual-module-codegen.ts — generatePerRouterModule drops the manifest export in both branches; keeps a bare side-effect gen-file import with a comment explaining why it must stay.
• src/route-map-builder.ts — ensureRouterManifest no longer reads mod.manifest; early return gates on the trie only. Eager coverage is 1:1 with loader registration (both emitted from the same loop, discover-routers.ts:239/:267).
• e2e/build-test-app.setup.ts — new bundle guard: serialized route data (detected as a JSON.parse string literal >= 8 KB; measured 40 KB trie vs 1.7 KB next-largest) must land in exactly one RSC chunk, zero client/SSR chunks, and be referenced only via dynamic import() (forbidden static-import shape matched directly so bundler formatting changes false-negative rather than failing CI). Shared collectJsFiles walker feeds both this and the existing dev-React guard.
• src/build/__tests__/per-router-manifest.test.ts, src/vite/discovery/__tests__/virtual-module-codegen.test.ts — tests updated/added to pin the new contract, including: a stray manifest field on a lazy module must not clobber the eagerly-set map.
• docs/manifests.md — documents the data-only lazy chunk and the bare-import invalidation edge.

Test plan

• pnpm run typecheck
• pnpm run test:unit:all — includes new/updated pins: virtual-module-codegen.test.ts "carries only derived match data" (module shape + bare import), per-router-manifest.test.ts "stray manifest field must not clobber the eagerly-set map"
• pnpm run lint, pnpm run format
• Bundle guard red-proven: planted duplicate data chunk fails the exactly-one assertion; planted static/bare/export-from imports of the data chunk fail the lazy-only matcher; real dynamic wiring and import.meta do not false-positive
• build-test-app setup (guard) green; test-app rebuilt — lazy chunk starts at var trie = JSON.parse(, single dynamic reference from entry
• route-types-hmr --project=hmr-routes: 17 passed, 1 flaky (flaky on base af355625 too)
• Cloudflare HMR suites (hmr.test.ts, hmr-burst-save): pass
• cloudflare-basic production e2e: 377 passed
• Multi-router example rebuilt: 4 eager setRouterManifest + 4 lazy loaders, each per-router chunk data-only

Notes

• Pre-existing failure (not this PR): tests/cloudflare-basic/e2e/hmr-route-mutations.test.ts "converges the open page to the catch-all when the viewed route is removed" fails persistently and identically on base af355625 (verified by stash + rebuild + rerun); its serial mode blocks 7 later tests in that file.
• /simplify protocol ran (4 agents). Applied: shared walker in the setup test, collect-then-assert + formatting-resilient static-import matcher for the lazy-only guard, trie-only early return, sourceFile binding. Skipped: "perRouterManifestDataMap values are write-only" (false positive — propagateDiscoveryState consumes the values, router-discovery.ts:975); relocating the guard into the plugin's generateBundle (out of scope; repo convention keeps bundle guards in the setup test — noted as a possible future deepening since chunk.imports/dynamicImports would remove the size heuristic entirely).
• The guard covers test-app (node preset, inline literal channel). The Cloudflare Text-module channel (RANGO_MANIFEST_TEXT) has no JSON.parse literal and is not covered by this guard; it remains covered by codegen unit tests.