@rangojs/router 0.1.0 → 0.2.0

package/dist/vite/index.js

@@ -2309,7 +2309,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(
@@ -2520,7 +2530,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.1.0",
+  version: "0.2.0",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -2620,6 +2630,10 @@ var package_default = {
       "react-server": "./src/rsc/handler.ts",
       default: "./src/rsc/handler.ts"
     },
+    "./internal/browser/dev-discovery": {
+      types: "./dist/types/browser/dev-discovery.d.ts",
+      default: "./src/browser/dev-discovery.ts"
+    },
     "./cache": {
       types: "./dist/types/cache/index.d.ts",
       "react-server": "./src/cache/index.ts",
@@ -2699,7 +2713,8 @@ var package_default = {
     typecheck: "tsc --noEmit && tsc -p tsconfig.strict-check.json --noEmit && tsc -p tsconfig.augment-check.json --noEmit",
     test: "playwright test",
     "test:ui": "playwright test --ui",
-    "test:hmr-local": "playwright test --project=dev-warmup --project=hmr-routes --project=hmr-basename --project=hmr-prerender --no-deps --workers=1",
+    "test:hmr-local": "playwright test --project=dev-warmup --project=hmr-basename --project=hmr-prerender --no-deps --workers=1 && RANGO_E2E_ROUTE_HMR_ONLY=1 playwright test --project=hmr-routes --no-deps --workers=1",
+    "test:hmr-routes-local": "RANGO_E2E_ROUTE_HMR_ONLY=1 playwright test --project=hmr-routes --no-deps --workers=1",
     "test:unit": "pnpm run build:types && vitest run",
     "test:unit:watch": "vitest",
     "test:unit:rsc": "vitest run --config vitest.rsc.config.ts"
@@ -4236,6 +4251,11 @@ function onwarn(warning, defaultHandler) {
 }
 function getManualChunks(id) {
   const normalized = Vite.normalizePath(id);
+  if (/\/browser\/prefetch\/(?:runtime|fetch|queue|observer|policy|resource-ready)\.[cm]?[jt]sx?(?:[?#].*)?$/.test(
+    normalized
+  )) {
+    return void 0;
+  }
   if (normalized.includes("node_modules/react/") || normalized.includes("node_modules/react-dom/") || normalized.includes("node_modules/react-server-dom-webpack/") || normalized.includes("node_modules/@vitejs/plugin-rsc/")) {
     return "react";
   }
@@ -4673,6 +4693,12 @@ import { readFileSync as readFileSync7 } from "node:fs";
 import { createRequire as createRequire3, register } from "node:module";
 import { pathToFileURL as pathToFileURL2 } from "node:url";
 
+// src/dev-discovery-protocol.ts
+var DEV_DISCOVERY_READY_EVENT = "rango:dev-discovery-ready";
+var DEV_DISCOVERY_QUERY_EVENT = "rango:dev-discovery-query";
+var DEV_DISCOVERY_PROBE_HEADER = "x-rango-dev-discovery-probe";
+var DEV_DISCOVERY_EPOCH_HEADER = "x-rango-dev-discovery-epoch";
+
 // src/rsc/shell-serve.ts
 import React from "react";
 
@@ -4955,8 +4981,6 @@ function createDiscoveryState(entryPath, opts) {
     opts,
     mergedRouteManifest: null,
     perRouterManifests: [],
-    mergedPrecomputedEntries: null,
-    mergedRouteTrie: null,
     perRouterTrieMap: /* @__PURE__ */ new Map(),
     perRouterPrecomputedMap: /* @__PURE__ */ new Map(),
     perRouterManifestDataMap: /* @__PURE__ */ new Map(),
@@ -4971,6 +4995,7 @@ function createDiscoveryState(entryPath, opts) {
     resolvedPrerenderModules: void 0,
     resolvedStaticModules: void 0,
     discoveryDone: null,
+    devDiscoveryEpoch: opts?.preset === "cloudflare" ? Date.now() : void 0,
     devServerOrigin: null,
     devServer: null,
     selfWrittenGenFiles: /* @__PURE__ */ new Map(),
@@ -5887,15 +5912,21 @@ async function renderStaticHandlers(state, rscEnv, registry) {
       if (def.options?.passthrough) continue;
       const startHandler = performance.now();
       let handled = false;
-      for (const [, routerInstance] of registry) {
+      const owner = def.$$routerId;
+      const owned = owner !== void 0 ? registry.get(owner) : void 0;
+      const candidates = owned ? [owned] : [...registry.values()];
+      for (const routerInstance of candidates) {
         if (!routerInstance.renderStaticSegment) continue;
         try {
           const result = await routerInstance.renderStaticSegment(
             def.handler,
             def.$$id,
-            def.$$routePrefix,
+            // Full route name when stamped; the historical $$routePrefix is a
+            // name PREFIX (never in the root-scope registry) kept as fallback.
+            def.$$routeName ?? def.$$routePrefix,
             state.resolvedBuildEnv,
-            !state.isBuildMode
+            !state.isBuildMode,
+            def.$$rootScoped
           );
           if (result) {
             const hasHandles = result.handles !== "";
@@ -6107,12 +6138,10 @@ async function discoverRouters(state, rscEnv) {
     throw new Error(formatNestedRouterConflictError(nestedRouterConflict));
   }
   const newMergedRouteManifest = {};
-  const newMergedPrecomputedEntries = [];
   const newPerRouterManifests = [];
   const newPerRouterManifestDataMap = /* @__PURE__ */ new Map();
   const newPerRouterPrecomputedMap = /* @__PURE__ */ new Map();
   const newPerRouterTrieMap = /* @__PURE__ */ new Map();
-  let mergedRouteTrailingSlash = {};
   let routerMountIndex = 0;
   const allManifests = [];
   const clientChunkCtx = state.opts?.clientChunkCtx;
@@ -6133,6 +6162,7 @@ async function discoverRouters(state, rscEnv) {
       router.urlpatterns,
       routerMountIndex,
       {
+        routerId: id,
         ...router.__basename ? { urlPrefix: router.__basename } : {},
         ...collectClientFallbackRef ? { collectClientFallbackRef } : {}
       }
@@ -6170,20 +6200,17 @@ async function discoverRouters(state, rscEnv) {
     newPerRouterManifests.push({
       id,
       routeManifest: manifest.routeManifest,
+      routeTrailingSlash: manifest.routeTrailingSlash,
       routeSearchSchemas: manifest.routeSearchSchemas,
       sourceFile: router.__sourceFile,
       factoryOnlyPrefixes
     });
-    if (manifest.routeTrailingSlash) {
-      Object.assign(mergedRouteTrailingSlash, manifest.routeTrailingSlash);
-    }
     const routerPrecomputed = [];
     flattenLeafEntries(
       manifest.prefixTree,
       manifest.routeManifest,
       routerPrecomputed
     );
-    newMergedPrecomputedEntries.push(...routerPrecomputed);
     newPerRouterManifestDataMap.set(id, manifest.routeManifest);
     newPerRouterPrecomputedMap.set(id, routerPrecomputed);
     console.log(
@@ -6205,44 +6232,8 @@ async function discoverRouters(state, rscEnv) {
     allManifests.length,
     (performance.now() - manifestGenStart).toFixed(1)
   );
-  let newMergedRouteTrie = null;
   const trieStart = debug10 ? performance.now() : 0;
   if (Object.keys(newMergedRouteManifest).length > 0) {
-    const routeToStaticPrefix = {};
-    for (const { manifest } of allManifests) {
-      for (const name of Object.keys(manifest.routeManifest)) {
-        if (!(name in routeToStaticPrefix)) {
-          routeToStaticPrefix[name] = "";
-        }
-      }
-      buildRouteToStaticPrefix(manifest.prefixTree, routeToStaticPrefix);
-    }
-    const prerenderRouteNames = /* @__PURE__ */ new Set();
-    const passthroughRouteNames = /* @__PURE__ */ new Set();
-    const mergedResponseTypeRoutes = {};
-    for (const { manifest } of allManifests) {
-      if (manifest.prerenderRoutes) {
-        for (const name of manifest.prerenderRoutes) {
-          prerenderRouteNames.add(name);
-        }
-      }
-      if (manifest.passthroughRoutes) {
-        for (const name of manifest.passthroughRoutes) {
-          passthroughRouteNames.add(name);
-        }
-      }
-      if (manifest.responseTypeRoutes) {
-        Object.assign(mergedResponseTypeRoutes, manifest.responseTypeRoutes);
-      }
-    }
-    newMergedRouteTrie = buildRouteTrie(
-      newMergedRouteManifest,
-      routeToStaticPrefix,
-      mergedRouteTrailingSlash,
-      prerenderRouteNames,
-      passthroughRouteNames,
-      mergedResponseTypeRoutes
-    );
     for (const { id, manifest } of allManifests) {
       const perRouterTrie = buildPerRouterTrie(manifest);
       if (perRouterTrie) {
@@ -6255,15 +6246,10 @@ async function discoverRouters(state, rscEnv) {
     (performance.now() - trieStart).toFixed(1)
   );
   state.mergedRouteManifest = newMergedRouteManifest;
-  state.mergedPrecomputedEntries = newMergedPrecomputedEntries;
   state.perRouterManifests = newPerRouterManifests;
   state.perRouterManifestDataMap = newPerRouterManifestDataMap;
   state.perRouterPrecomputedMap = newPerRouterPrecomputedMap;
   state.perRouterTrieMap = newPerRouterTrieMap;
-  state.mergedRouteTrie = newMergedRouteTrie;
-  if (serverMod.setRouteTrie && newMergedRouteTrie) {
-    serverMod.setRouteTrie(newMergedRouteTrie);
-  }
   const perRouterSetters = [
     [newPerRouterManifestDataMap, "setRouterManifest"],
     [newPerRouterTrieMap, "setRouterTrie"],
@@ -6696,12 +6682,18 @@ function supplementGenFilesWithRuntimeRoutes(state) {
 import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync5 } from "node:fs";
 import { dirname as dirname4, basename, join as join6 } from "node:path";
 var MANIFEST_EXTERNALIZE_THRESHOLD = 512 * 1024;
+function devDiscoveryBootstrap(state) {
+  if (state.isBuildMode || state.opts?.preset !== "cloudflare" || state.devDiscoveryEpoch === void 0) {
+    return [];
+  }
+  const epoch = state.devDiscoveryEpoch;
+  return [`globalThis.__RANGO_DEV_DISCOVERY_EPOCH = ${epoch};`];
+}
 function generateRoutesManifestModule(state) {
   const hasManifest = state.mergedRouteManifest && Object.keys(state.mergedRouteManifest).length > 0;
   if (hasManifest) {
     const genFileImports = [];
-    const genFileVars = [];
-    const routersWithoutGenFile = [];
+    const genFileVarByEntry = [];
     let varIdx = 0;
     for (const entry of state.perRouterManifests) {
       if (entry.sourceFile) {
@@ -6718,16 +6710,19 @@ function generateRoutesManifestModule(state) {
         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 lines = [
-      `import { setCachedManifest, setRouterManifest, registerRouterManifestLoader, clearAllRouterData } from "@rangojs/router/server";`,
+    const serverImports = [
+      "setCachedManifest",
+      "setRouterManifest",
+      ...state.isBuildMode ? ["registerRouterManifestLoader"] : [],
+      "clearAllRouterData"
+    ];
+    const lines2 = [
+      `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
@@ -6736,53 +6731,56 @@ function generateRoutesManifestModule(state) {
       // handler finds stale trie data and never rebuilds from updated urlpatterns.
       `clearAllRouterData();`
     ];
-    if (genFileVars.length > 0) {
-      lines.push(
+    if (varIdx > 0) {
+      lines2.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]}));`);
+    const routerMapVars = [];
+    for (const [i, entry] of state.perRouterManifests.entries()) {
+      const mapVar = `__m${i}`;
+      const genVar = genFileVarByEntry[i];
+      const init = genVar ? `__flat(${genVar})` : jsonParseExpression(entry.routeManifest);
+      lines2.push(`const ${mapVar} = ${init};`);
+      routerMapVars.push(mapVar);
+    }
+    if (routerMapVars.length === 1) {
+      lines2.push(`setCachedManifest(${routerMapVars[0]});`);
     } else {
-      const parts = [];
-      for (const v of genFileVars) parts.push(`...__flat(${v})`);
-      for (const { manifest } of routersWithoutGenFile)
-        parts.push(`...${jsonParseExpression(manifest)}`);
-      lines.push(`setCachedManifest({ ${parts.join(", ")} });`);
+      lines2.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()) {
+      lines2.push(
+        `setRouterManifest(${JSON.stringify(entry.id)}, ${routerMapVars[i]});`
+      );
+    }
+    if (state.isBuildMode) {
+      for (const routerId of state.perRouterManifestDataMap.keys()) {
+        lines2.push(
+          `registerRouterManifestLoader(${JSON.stringify(routerId)}, () => import(${JSON.stringify(VIRTUAL_ROUTES_MANIFEST_ID + "/" + routerId)}));`
         );
       }
     }
-    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(
+      lines2.push(
         `globalThis.__PRERENDER_DEV_URL = ${JSON.stringify(state.devServerOrigin)};`
       );
     }
-    return lines.join("\n");
+    lines2.push(...devDiscoveryBootstrap(state));
+    return lines2.join("\n");
   }
+  const lines = [];
   if (!state.isBuildMode) {
     const origin = state.devServerOrigin || state.devServer?.resolvedUrls?.local?.[0]?.replace(/\/$/, "") || state.devServer && `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`;
 }
 function shortHash(input) {
   let h = 2166136261;
@@ -6965,7 +6963,7 @@ function postprocessBundle(state) {
         );
         writeFileSync6(manifestPath, manifestCode);
         totalBytes += Buffer.byteLength(manifestCode);
-        const injection = `import "./__static-manifest.js";
+        const injection = `globalThis.__loadStaticManifestModule = () => import("./__static-manifest.js");
 `;
         writeFileSync6(rscEntryPath, injection + rscCode);
         const totalKB = (totalBytes / 1024).toFixed(1);
@@ -7300,6 +7298,43 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
       if (s.isBuildMode) return;
       if (globalThis.__rscRouterDiscoveryActive) return;
       s.devServer = server;
+      let workerReadyEpoch;
+      const publishDevDiscoveryReady = (epoch) => {
+        if (epoch <= (workerReadyEpoch ?? -1)) return;
+        workerReadyEpoch = epoch;
+        server.environments?.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 = /* @__PURE__ */ new Set();
+        const registerDevDiscoveryHotChannels = () => {
+          const clientHot = server.environments?.client?.hot;
+          if (clientHot && !registeredClientHotChannels.has(clientHot)) {
+            registeredClientHotChannels.add(clientHot);
+            clientHot.on(
+              DEV_DISCOVERY_QUERY_EVENT,
+              (_payload, client) => {
+                if (workerReadyEpoch === void 0) 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);
+        }
+      }
       server.middlewares.use(internalDebugNoCacheMiddleware());
       let resolveDiscovery;
       const discoveryPromise = new Promise((resolve13) => {
@@ -7309,9 +7344,11 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
       const beginDiscoveryGate = gate.beginGate;
       const resolveDiscoveryGate = gate.resolveGate;
       const getDevServerOrigin = () => server.resolvedUrls?.local?.[0]?.replace(/\/$/, "") || `http://localhost:${server.config.server.port || 5173}`;
+      let devServerClosed = false;
       let prerenderTempServer = null;
       let prerenderNodeRegistry = null;
       server.httpServer?.on("close", () => {
+        devServerClosed = true;
         if (prerenderTempServer) {
           prerenderTempServer.close().catch(() => {
           });
@@ -7587,12 +7624,6 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
         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 = [
           [s.perRouterManifestDataMap, "setRouterManifest"],
           [s.perRouterTrieMap, "setRouterTrie"],
@@ -7928,6 +7959,21 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
             writeCombinedRouteTypesWithTracking(s);
           }
         };
+        const routeShapeSignature = () => JSON.stringify(
+          s.perRouterManifests.map(
+            ({
+              id,
+              routeManifest,
+              routeTrailingSlash,
+              routeSearchSchemas
+            }) => ({
+              id,
+              routeManifest,
+              routeTrailingSlash,
+              routeSearchSchemas
+            })
+          )
+        );
         const maybeHandleGeneratedRouteFileMutation = (filePath) => {
           if (!isGeneratedRouteFile(filePath)) return false;
           if (consumeSelfGenWrite(s, filePath)) return true;
@@ -7941,6 +7987,7 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
           const rscEnv = server.environments?.rsc;
           const hasMainRunner = !!rscEnv?.runner;
           if (!hasMainRunner && s.perRouterManifests.length === 0) return;
+          let previousRouteShape = routeShapeSignature();
           await gate.runRefreshCycle(async () => {
             const hmrStart = performance.now();
             try {
@@ -7989,7 +8036,19 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
                 );
                 s.lastDiscoveryError = null;
               }
-              if (rscEnv && !rscEnv.runner) forceCloudflareWorkerReload(rscEnv);
+              if (rscEnv && !rscEnv.runner) {
+                const nextRouteShape = routeShapeSignature();
+                let expectedEpoch;
+                if (nextRouteShape !== previousRouteShape) {
+                  expectedEpoch = Math.max(
+                    Date.now(),
+                    (s.devDiscoveryEpoch ?? 0) + 1
+                  );
+                  s.devDiscoveryEpoch = expectedEpoch;
+                }
+                previousRouteShape = nextRouteShape;
+                forceCloudflareWorkerReload(rscEnv, expectedEpoch);
+              }
             } catch (err) {
               s.lastDiscoveryError = {
                 message: err?.message ?? String(err),
@@ -8010,10 +8069,10 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
             }
           });
         };
-        const forceCloudflareWorkerReload = (rscEnv) => {
+        const forceCloudflareWorkerReload = (rscEnv, expectedEpoch) => {
           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");
@@ -8022,12 +8081,40 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
             debugDiscovery?.(
               "hmr: forced workerd rsc env reload (full-reload)"
             );
-          } catch (err) {
+          };
+          reloadWorkerd();
+          if (expectedEpoch === void 0) return;
+          void (async () => {
+            const deadline = Date.now() + 15e3;
+            do {
+              if (devServerClosed || expectedEpoch !== s.devDiscoveryEpoch) {
+                return;
+              }
+              await new Promise((resolve13) => setTimeout(resolve13, 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(1e3)
+                });
+                if (!devServerClosed && expectedEpoch === s.devDiscoveryEpoch && response.headers.get(DEV_DISCOVERY_EPOCH_HEADER) === String(expectedEpoch)) {
+                  publishDevDiscoveryReady(expectedEpoch);
+                  return;
+                }
+                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 = () => {
           clearTimeout(routeChangeTimer);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",
@@ -100,6 +100,10 @@
       "react-server": "./src/rsc/handler.ts",
       "default": "./src/rsc/handler.ts"
     },
+    "./internal/browser/dev-discovery": {
+      "types": "./dist/types/browser/dev-discovery.d.ts",
+      "default": "./src/browser/dev-discovery.ts"
+    },
     "./cache": {
       "types": "./dist/types/cache/index.d.ts",
       "react-server": "./src/cache/index.ts",
@@ -172,18 +176,6 @@
     "access": "public",
     "tag": "latest"
   },
-  "scripts": {
-    "build": "pnpm run build:types && pnpm exec esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm exec esbuild src/testing/vitest.ts --bundle --format=esm --outfile=dist/testing/vitest.js --platform=node --packages=external && pnpm exec esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js",
-    "build:types": "rm -rf dist/types && pnpm exec tsc -p tsconfig.types.json",
-    "prepublishOnly": "pnpm build",
-    "typecheck": "tsc --noEmit && tsc -p tsconfig.strict-check.json --noEmit && tsc -p tsconfig.augment-check.json --noEmit",
-    "test": "playwright test",
-    "test:ui": "playwright test --ui",
-    "test:hmr-local": "playwright test --project=dev-warmup --project=hmr-routes --project=hmr-basename --project=hmr-prerender --no-deps --workers=1",
-    "test:unit": "pnpm run build:types && vitest run",
-    "test:unit:watch": "vitest",
-    "test:unit:rsc": "vitest run --config vitest.rsc.config.ts"
-  },
   "dependencies": {
     "@types/debug": "^4.1.12",
     "@vitejs/plugin-rsc": "^0.5.27",
@@ -199,19 +191,19 @@
     "@opentelemetry/context-async-hooks": "^2.9.0",
     "@opentelemetry/sdk-trace-base": "^2.9.0",
     "@playwright/test": "^1.49.1",
-    "@shared/e2e": "workspace:*",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2",
     "@types/node": "^24.10.1",
-    "@types/react": "catalog:",
-    "@types/react-dom": "catalog:",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
     "esbuild": "^0.28.1",
     "happy-dom": "^20.10.1",
     "jiti": "^2.7.0",
-    "react": "catalog:",
-    "react-dom": "catalog:",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
     "typescript": "^5.3.0",
-    "vitest": "^4.1.9"
+    "vitest": "^4.1.9",
+    "@shared/e2e": "0.0.1"
   },
   "peerDependencies": {
     "@cloudflare/vite-plugin": "^1.42.1",
@@ -250,5 +242,17 @@
   },
   "engines": {
     "node": ">=24.0.0"
+  },
+  "scripts": {
+    "build": "pnpm run build:types && pnpm exec esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm exec esbuild src/testing/vitest.ts --bundle --format=esm --outfile=dist/testing/vitest.js --platform=node --packages=external && pnpm exec esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js",
+    "build:types": "rm -rf dist/types && pnpm exec tsc -p tsconfig.types.json",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.strict-check.json --noEmit && tsc -p tsconfig.augment-check.json --noEmit",
+    "test": "playwright test",
+    "test:ui": "playwright test --ui",
+    "test:hmr-local": "playwright test --project=dev-warmup --project=hmr-basename --project=hmr-prerender --no-deps --workers=1 && RANGO_E2E_ROUTE_HMR_ONLY=1 playwright test --project=hmr-routes --no-deps --workers=1",
+    "test:hmr-routes-local": "RANGO_E2E_ROUTE_HMR_ONLY=1 playwright test --project=hmr-routes --no-deps --workers=1",
+    "test:unit": "pnpm run build:types && vitest run",
+    "test:unit:watch": "vitest",
+    "test:unit:rsc": "vitest run --config vitest.rsc.config.ts"
   }
-}
+}

package/skills/cache-guide/SKILL.md

@@ -131,8 +131,10 @@ recompute for a merely-aging entry.
   layer.
 - **Client forward/back** is SWR after a mutation — see "Correctness &
   invalidation" → Client cache.
-- **Edge / document layer** uses the HTTP `stale-while-revalidate` directive; see
-  `/document-cache`.
+- **Store-backed document layer** uses the HTTP `stale-while-revalidate`
+  directive as policy for `createDocumentCacheMiddleware`; see
+  `/document-cache`. A platform CDN may independently consume the same header
+  and bypass the function on hits; see `/deployment-caching`.
 
 SWR softens normal TTL expiry, **not** a cross-deploy cold cache — a new build
 has no stale entry to serve (see version-segmented store keys above).
@@ -485,5 +487,6 @@ overrides — see `/loader` for the full reference.
 
 - `/caching` — cache() DSL setup, stores, nested boundaries
 - `/use-cache` — "use cache" directive details, profiles, transforms, guards
-- `/document-cache` — Edge caching with Cache-Control headers (different layer)
+- `/document-cache` — store-backed complete-response middleware
+- `/deployment-caching` — in-function versus external CDN cache boundaries
 - `/ppr` — PPR shell caching: cached HTML shell + live loader holes (different layer)

package/skills/caching/SKILL.md

@@ -171,7 +171,7 @@ export async function POST() {
 | `updateTag(...tags)`     | awaitable (`Promise<void>`) | server actions            | immediate; next read is fresh                         |
 | `revalidateTag(...tags)` | background (`void`)         | route handlers / webhooks | background (non-blocking); next read re-renders fresh |
 
-Both built-in stores support tags. For `CFCacheStore`, distributed (cross-colo)
+All three built-in stores support tags. For `CFCacheStore`, distributed (cross-colo)
 invalidation requires a `kv` namespace — the tag-invalidation markers live in
 that same namespace; there is **no** separate tag-invalidation store to wire.
 If no tag-capable store is configured, `updateTag`/`revalidateTag` warn and no-op.

package/skills/catalog.json

@@ -69,9 +69,15 @@
       "argumentHint": "",
       "path": "skills/defer-hydration/SKILL.md"
     },
+    {
+      "name": "deployment-caching",
+      "description": "Choose the deployment cache boundary for a Rango app: in-function segment/prerender/PPR caches, store-backed whole-response caching, or an external CDN cache. Use when comparing Cloudflare, Vercel, and Node deployments; deciding whether Cache-Control can reduce origin work; or reasoning about middleware, live loaders, PPR, and CDN behavior.",
+      "argumentHint": "[cloudflare|vercel|node]",
+      "path": "skills/deployment-caching/SKILL.md"
+    },
     {
       "name": "document-cache",
-      "description": "Cache the whole HTTP response at the edge with Cache-Control headers. Use when caching an entire page or response at a CDN edge, setting Cache-Control headers, or cutting origin hits for public pages — not for caching a single segment or function.",
+      "description": "Cache complete HTTP responses in Rango's configured app store with createDocumentCacheMiddleware, using Cache-Control s-maxage as policy. Use when reusing a whole HTML/RSC response, comparing the store-backed middleware with a platform CDN cache, or deciding whether full-response caching is safe.",
       "argumentHint": "[setup]",
       "path": "skills/document-cache/SKILL.md"
     },