@rangojs/router 0.1.0 → 0.1.1

package/src/vite/discovery/virtual-module-codegen.ts

@@ -24,6 +24,19 @@ import type { DiscoveryState } from "./state.js";
  */
 const MANIFEST_EXTERNALIZE_THRESHOLD = 512 * 1024;
 
+function devDiscoveryBootstrap(state: DiscoveryState): string[] {
+  if (
+    state.isBuildMode ||
+    state.opts?.preset !== "cloudflare" ||
+    state.devDiscoveryEpoch === undefined
+  ) {
+    return [];
+  }
+
+  const epoch = state.devDiscoveryEpoch;
+  return [`globalThis.__RANGO_DEV_DISCOVERY_EPOCH = ${epoch};`];
+}
+
 /**
  * Generate the code for the main virtual:rsc-router/routes-manifest module.
  */
@@ -39,11 +52,9 @@ export function generateRoutesManifestModule(state: DiscoveryState): string {
     // module and re-evaluates it on the next request, calling
     // setCachedManifest() with fresh data. No manual sync needed.
     const genFileImports: string[] = [];
-    const genFileVars: string[] = [];
-    const routersWithoutGenFile: Array<{
-      id: string;
-      manifest: Record<string, string>;
-    }> = [];
+    // Per-entry NamedRoutes import var, aligned with perRouterManifests
+    // (null for routers without a gen file).
+    const genFileVarByEntry: Array<string | null> = [];
     let varIdx = 0;
 
     for (const entry of state.perRouterManifests) {
@@ -61,17 +72,20 @@ export function generateRoutesManifestModule(state: DiscoveryState): string {
         genFileImports.push(
           `import { NamedRoutes as ${varName} } from ${JSON.stringify(genPath)};`,
         );
-        genFileVars.push(varName);
+        genFileVarByEntry.push(varName);
       } else {
-        routersWithoutGenFile.push({
-          id: entry.id,
-          manifest: entry.routeManifest,
-        });
+        genFileVarByEntry.push(null);
       }
     }
 
+    const serverImports = [
+      "setCachedManifest",
+      "setRouterManifest",
+      ...(state.isBuildMode ? ["registerRouterManifestLoader"] : []),
+      "clearAllRouterData",
+    ];
     const lines = [
-      `import { setCachedManifest, setRouterManifest, registerRouterManifestLoader, clearAllRouterData } from "@rangojs/router/server";`,
+      `import { ${serverImports.join(", ")} } from "@rangojs/router/server";`,
       ...genFileImports,
       // Clear stale per-router cached data (manifest, trie, precomputed entries)
       // before re-populating. In Cloudflare dev mode, program reloads re-evaluate
@@ -81,62 +95,80 @@ export function generateRoutesManifestModule(state: DiscoveryState): string {
       `clearAllRouterData();`,
     ];
 
-    if (genFileVars.length > 0) {
+    if (varIdx > 0) {
       lines.push(
         `function __flat(r) { const o = {}; for (const [k, v] of Object.entries(r)) o[k] = typeof v === "string" ? v : v.path; return o; }`,
       );
     }
 
-    if (genFileVars.length === 1 && routersWithoutGenFile.length === 0) {
-      lines.push(`setCachedManifest(__flat(${genFileVars[0]}));`);
+    // Each router's flattened map is materialized ONCE and the same object is
+    // shared between the global cachedManifest and the per-router map (a
+    // single-router app previously held two byte-identical maps, and __flat
+    // ran twice per router on cold start). Sharing is safe: every consumer
+    // reads these maps; lazy-include deltas mutate globalRouteMap, a different
+    // object (see registerRouteMap in route-map-builder.ts).
+    const routerMapVars: string[] = [];
+    for (const [i, entry] of state.perRouterManifests.entries()) {
+      const mapVar = `__m${i}`;
+      const genVar = genFileVarByEntry[i];
+      const init = genVar
+        ? `__flat(${genVar})`
+        : jsonParseExpression(entry.routeManifest);
+      lines.push(`const ${mapVar} = ${init};`);
+      routerMapVars.push(mapVar);
+    }
+
+    if (routerMapVars.length === 1) {
+      lines.push(`setCachedManifest(${routerMapVars[0]});`);
     } else {
-      const parts: string[] = [];
-      for (const v of genFileVars) parts.push(`...__flat(${v})`);
-      for (const { manifest } of routersWithoutGenFile)
-        parts.push(`...${jsonParseExpression(manifest)}`);
-      lines.push(`setCachedManifest({ ${parts.join(", ")} });`);
+      lines.push(
+        `setCachedManifest({ ${routerMapVars.map((v) => `...${v}`).join(", ")} });`,
+      );
     }
 
-    let genVarIdx = 0;
-    for (const entry of state.perRouterManifests) {
-      if (entry.sourceFile) {
-        const varName = genFileVars[genVarIdx++];
-        lines.push(
-          `setRouterManifest(${JSON.stringify(entry.id)}, __flat(${varName}));`,
-        );
-      } else {
-        lines.push(
-          `setRouterManifest(${JSON.stringify(entry.id)}, ${jsonParseExpression(entry.routeManifest)});`,
-        );
-      }
+    for (const [i, entry] of state.perRouterManifests.entries()) {
+      lines.push(
+        `setRouterManifest(${JSON.stringify(entry.id)}, ${routerMapVars[i]});`,
+      );
     }
 
     // Per-router trie and precomputedEntries are NOT inlined eagerly.
     // They live in the per-router lazy chunks (generatePerRouterModule) and
     // are loaded via ensureRouterManifest(routerId), which is awaited before
-    // every request in router.fetch() and before findMatch is reached.
-    // Inlining the merged versions here would duplicate the per-router data
-    // (the merged trie/precomputedEntries equal the per-router data for
-    // single-router apps; for multi-router, the merged trie is dead code
-    // because find-match.ts only consumes per-router tries).
+    // every request in router.fetch() and before findMatch is reached
+    // (Bundle Hygiene rule #1: route data in exactly one lazy chunk).
     //
     // In dev mode, the handler also falls back to Phase 2 regex matching
     // against live router.urlpatterns, which is always correct after a
     // program reload.
 
-    for (const routerId of state.perRouterManifestDataMap.keys()) {
-      lines.push(
-        `registerRouterManifestLoader(${JSON.stringify(routerId)}, () => import(${JSON.stringify(VIRTUAL_ROUTES_MANIFEST_ID + "/" + routerId)}));`,
-      );
+    // Loaders are registered in BUILD only. ensureRouterManifest() marks a
+    // loader-supplied trie authoritative (misses are hard 404s), which is only
+    // valid for a build-time trie from complete discovery. In dev the loader
+    // would preempt the handler's buildRouterTrieFromUrlpatterns fallback
+    // (rsc/handler.ts) and can install a STALE trie after a Cloudflare program
+    // reload: the per-router virtual module's only invalidation edge is the
+    // gen-file import, which lags the urls.tsx edit by one reload cycle, so a
+    // browser full-reload landing in that window renders a removed route from
+    // the stale-but-authoritative trie and never converges. Dev must always
+    // rebuild from live router.urlpatterns instead.
+    if (state.isBuildMode) {
+      for (const routerId of state.perRouterManifestDataMap.keys()) {
+        lines.push(
+          `registerRouterManifestLoader(${JSON.stringify(routerId)}, () => import(${JSON.stringify(VIRTUAL_ROUTES_MANIFEST_ID + "/" + routerId)}));`,
+        );
+      }
     }
     if (!state.isBuildMode && state.devServerOrigin) {
       lines.push(
         `globalThis.__PRERENDER_DEV_URL = ${JSON.stringify(state.devServerOrigin)};`,
       );
     }
+    lines.push(...devDiscoveryBootstrap(state));
     return lines.join("\n");
   }
 
+  const lines: string[] = [];
   if (!state.isBuildMode) {
     const origin =
       state.devServerOrigin ||
@@ -145,10 +177,11 @@ export function generateRoutesManifestModule(state: DiscoveryState): string {
         `http://localhost:${state.devServer.config.server.port || 5173}`);
     if (origin) {
       state.devServerOrigin = origin;
-      return `globalThis.__PRERENDER_DEV_URL = ${JSON.stringify(origin)};`;
+      lines.push(`globalThis.__PRERENDER_DEV_URL = ${JSON.stringify(origin)};`);
     }
   }
-  return `// Route manifest will be populated at runtime`;
+  lines.push(...devDiscoveryBootstrap(state));
+  return lines.join("\n") || `// Route manifest will be populated at runtime`;
 }
 
 /**

package/src/vite/plugins/version-injector.ts

@@ -54,7 +54,6 @@ export function createVersionInjectorPlugin(
       const prepend: string[] = RSC_ENTRY_BOOTSTRAP_IMPORTS.map(
         (id) => `import "${id}";`,
       );
-
       let newCode = code;
       const needsVersion =
         code.includes("createRSCHandler") &&

package/src/vite/plugins/virtual-entries.ts

@@ -26,7 +26,17 @@ async function initializeApp() {
   // context, including strictMode (default true) from createRouter. StrictMode
   // is the default; createRouter({ strictMode: false }) ships the opt-out in the
   // payload metadata. StrictMode emits no DOM, so toggling never changes markup.
-  const { strictMode } = await initBrowserApp({ rscStream, deps });
+  const { strictMode, initialPayload } = await initBrowserApp({ rscStream, deps });
+
+  if (import.meta.hot) {
+    const { startDevDiscoveryHandshake } = await import(
+      "@rangojs/router/internal/browser/dev-discovery"
+    );
+    startDevDiscoveryHandshake(
+      initialPayload.metadata?.devDiscoveryEpoch,
+      import.meta.hot
+    );
+  }
 
   const app = createElement(Rango);
   hydrateRoot(

package/src/vite/router-discovery.ts

@@ -19,6 +19,12 @@ import {
   createScanFilter,
 } from "../build/generate-route-types.js";
 import { firstCodeMatchIndex } from "../build/route-types/source-scan.js";
+import {
+  DEV_DISCOVERY_EPOCH_HEADER,
+  DEV_DISCOVERY_PROBE_HEADER,
+  DEV_DISCOVERY_QUERY_EVENT,
+  DEV_DISCOVERY_READY_EVENT,
+} from "../dev-discovery-protocol.js";
 import {
   DEV_SHELL_PROBE_TIMEOUT_MS,
   normalizeCaptureTimeout,
@@ -472,6 +478,45 @@ export function createRouterDiscoveryPlugin(
       if ((globalThis as any).__rscRouterDiscoveryActive) return;
       s.devServer = server;
 
+      let workerReadyEpoch: number | undefined;
+      const publishDevDiscoveryReady = (epoch: number) => {
+        if (epoch <= (workerReadyEpoch ?? -1)) return;
+        workerReadyEpoch = epoch;
+        (server.environments as any)?.client?.hot?.send({
+          type: "custom",
+          event: DEV_DISCOVERY_READY_EVENT,
+          data: { epoch },
+        });
+        debugDiscovery?.("hmr: workerd ready at epoch %d", epoch);
+      };
+      if (opts?.preset === "cloudflare") {
+        const registeredClientHotChannels = new Set<any>();
+        const registerDevDiscoveryHotChannels = () => {
+          const clientHot = (server.environments as any)?.client?.hot;
+          if (clientHot && !registeredClientHotChannels.has(clientHot)) {
+            registeredClientHotChannels.add(clientHot);
+            clientHot.on(
+              DEV_DISCOVERY_QUERY_EVENT,
+              (_payload: unknown, client: any) => {
+                if (workerReadyEpoch === undefined) return;
+                client.send(DEV_DISCOVERY_READY_EVENT, {
+                  epoch: workerReadyEpoch,
+                });
+              },
+            );
+          }
+          debugDiscovery?.(
+            "hmr: dev discovery browser channel registered (client=%s)",
+            !!clientHot,
+          );
+        };
+
+        registerDevDiscoveryHotChannels();
+        if (server.httpServer && !server.httpServer.listening) {
+          server.httpServer.once("listening", registerDevDiscoveryHotChannels);
+        }
+      }
+
       // Serve the internal-debug module no-cache: consumers resolve it into
       // node_modules, where dev's immutable `?v=` caching pinned browsers to a
       // stale baked INTERNAL_RANGO_DEBUG. See internalDebugNoCacheMiddleware.
@@ -500,6 +545,7 @@ export function createRouterDiscoveryPlugin(
       const getDevServerOrigin = () =>
         server.resolvedUrls?.local?.[0]?.replace(/\/$/, "") ||
         `http://localhost:${server.config.server.port || 5173}`;
+      let devServerClosed = false;
 
       // Shared temp server for Cloudflare dev (no module runner in workerd).
       // Used by both discover() (route type generation) and the prerender
@@ -510,6 +556,7 @@ export function createRouterDiscoveryPlugin(
 
       // Clean up the temporary server and build env when the dev server shuts down
       server.httpServer?.on("close", () => {
+        devServerClosed = true;
         if (prerenderTempServer) {
           prerenderTempServer.close().catch(() => {});
           prerenderTempServer = null;
@@ -953,16 +1000,6 @@ export function createRouterDiscoveryPlugin(
         if (s.mergedRouteManifest && serverMod.setCachedManifest) {
           serverMod.setCachedManifest(s.mergedRouteManifest);
         }
-        if (
-          s.mergedPrecomputedEntries &&
-          s.mergedPrecomputedEntries.length > 0 &&
-          serverMod.setPrecomputedEntries
-        ) {
-          serverMod.setPrecomputedEntries(s.mergedPrecomputedEntries);
-        }
-        if (s.mergedRouteTrie && serverMod.setRouteTrie) {
-          serverMod.setRouteTrie(s.mergedRouteTrie);
-        }
         const perRouterSetters: Array<[Map<string, any>, string]> = [
           [s.perRouterManifestDataMap, "setRouterManifest"],
           [s.perRouterTrieMap, "setRouterTrie"],
@@ -1436,6 +1473,22 @@ export function createRouterDiscoveryPlugin(
             writeCombinedRouteTypesWithTracking(s);
           }
         };
+        const routeShapeSignature = () =>
+          JSON.stringify(
+            s.perRouterManifests.map(
+              ({
+                id,
+                routeManifest,
+                routeTrailingSlash,
+                routeSearchSchemas,
+              }) => ({
+                id,
+                routeManifest,
+                routeTrailingSlash,
+                routeSearchSchemas,
+              }),
+            ),
+          );
 
         const maybeHandleGeneratedRouteFileMutation = (
           filePath: string,
@@ -1474,6 +1527,7 @@ export function createRouterDiscoveryPlugin(
           // populated manifest there's nothing useful to do, so bail
           // before involving the gate machine at all.
           if (!hasMainRunner && s.perRouterManifests.length === 0) return;
+          let previousRouteShape = routeShapeSignature();
           await gate.runRefreshCycle(async () => {
             const hmrStart = performance.now();
             try {
@@ -1528,7 +1582,19 @@ export function createRouterDiscoveryPlugin(
               // original call already resolved on the failed cycle. A failed
               // cycle throws above and never reaches here, so a broken edit
               // never reloads the worker onto bad source.
-              if (rscEnv && !rscEnv.runner) forceCloudflareWorkerReload(rscEnv);
+              if (rscEnv && !rscEnv.runner) {
+                const nextRouteShape = routeShapeSignature();
+                let expectedEpoch: number | undefined;
+                if (nextRouteShape !== previousRouteShape) {
+                  expectedEpoch = Math.max(
+                    Date.now(),
+                    (s.devDiscoveryEpoch ?? 0) + 1,
+                  );
+                  s.devDiscoveryEpoch = expectedEpoch;
+                }
+                previousRouteShape = nextRouteShape;
+                forceCloudflareWorkerReload(rscEnv, expectedEpoch);
+              }
             } catch (err: any) {
               s.lastDiscoveryError = {
                 message: err?.message ?? String(err),
@@ -1562,7 +1628,8 @@ export function createRouterDiscoveryPlugin(
         // HMR update for them and the entry chain is never evicted.
         //
         // Fix: after discovery completes, (1) invalidate the worker env's
-        // Node-side module graph, then (2) send a full-reload to the worker.
+        // Node-side module graph, (2) send a full-reload to the worker, then
+        // (3) probe until the active router reports the new discovery epoch.
         // Step (2) alone is insufficient: the full-reload handler clears the
         // runner's evaluatedModules and re-imports entrypoints, but each
         // re-import fetches the module back through this Node-side graph, which
@@ -1570,13 +1637,19 @@ export function createRouterDiscoveryPlugin(
         // rebuilds the stale route table and the new route 404s/hits the
         // catch-all. Invalidating the graph forces a fresh transform on
         // re-fetch (the same mechanism refreshTempRscEnv uses for discovery),
-        // so the re-import re-runs createRouter() with the new routes. This is
-        // the programmatic equivalent of the dev-server "r + enter" restart,
-        // scoped to the worker environment instead of tearing down the server.
-        const forceCloudflareWorkerReload = (rscEnv: any) => {
+        // so the re-import re-runs createRouter() with the new routes. The probe
+        // is detached because the refresh callback still holds the discovery
+        // gate; awaiting it here would deadlock the request that proves the new
+        // router is active. Once it succeeds, the client hot channel broadcasts
+        // readiness to open and newly-booted stale documents.
+        const forceCloudflareWorkerReload = (
+          rscEnv: any,
+          expectedEpoch: number | undefined,
+        ) => {
           if (!rscEnv?.hot) return;
-          try {
-            const graph = rscEnv.moduleGraph;
+
+          const graph = rscEnv.moduleGraph;
+          const reloadWorkerd = () => {
             if (graph?.invalidateAll) {
               graph.invalidateAll();
               debugDiscovery?.("hmr: invalidated workerd rsc module graph");
@@ -1585,12 +1658,49 @@ export function createRouterDiscoveryPlugin(
             debugDiscovery?.(
               "hmr: forced workerd rsc env reload (full-reload)",
             );
-          } catch (err: any) {
+          };
+          reloadWorkerd();
+
+          if (expectedEpoch === undefined) return;
+          void (async () => {
+            const deadline = Date.now() + 15_000;
+            do {
+              if (devServerClosed || expectedEpoch !== s.devDiscoveryEpoch) {
+                return;
+              }
+              await new Promise<void>((resolve) => setTimeout(resolve, 25));
+              if (devServerClosed || expectedEpoch !== s.devDiscoveryEpoch) {
+                return;
+              }
+              try {
+                const response = await fetch(getDevServerOrigin() + "/", {
+                  cache: "no-store",
+                  headers: {
+                    [DEV_DISCOVERY_PROBE_HEADER]: String(expectedEpoch),
+                  },
+                  signal: AbortSignal.timeout(1_000),
+                });
+                if (
+                  !devServerClosed &&
+                  expectedEpoch === s.devDiscoveryEpoch &&
+                  response.headers.get(DEV_DISCOVERY_EPOCH_HEADER) ===
+                    String(expectedEpoch)
+                ) {
+                  publishDevDiscoveryReady(expectedEpoch);
+                  return;
+                }
+                // A response without the expected epoch proves an older worker
+                // evaluation won the race after the initial invalidation. Clear
+                // that completed evaluation and retry the reload.
+                reloadWorkerd();
+              } catch {}
+            } while (Date.now() < deadline);
+
             debugDiscovery?.(
-              "hmr: workerd reload failed: %s",
-              err?.message ?? err,
+              "hmr: workerd readiness probe timed out at epoch %d",
+              expectedEpoch,
             );
-          }
+          })();
         };
 
         const scheduleRouteRegeneration = () => {

package/src/vite/utils/manifest-utils.ts

@@ -1,7 +1,4 @@
-export {
-  flattenLeafEntries,
-  buildRouteToStaticPrefix,
-} from "../../build/prefix-tree-utils.js";
+export { flattenLeafEntries } from "../../build/prefix-tree-utils.js";
 
 /**
  * Wrap a value as `JSON.parse('...')` instead of a JS object literal.

package/src/vite/utils/shared-utils.ts

@@ -252,6 +252,13 @@ export function onwarn(
 export function getManualChunks(id: string): string | undefined {
   const normalized = Vite.normalizePath(id);
 
+  if (
+    /\/browser\/prefetch\/(?:runtime|fetch|queue|observer|policy|resource-ready)\.[cm]?[jt]sx?(?:[?#].*)?$/.test(
+      normalized,
+    )
+  ) {
+    return undefined;
+  }
   if (
     normalized.includes("node_modules/react/") ||
     normalized.includes("node_modules/react-dom/") ||