@rangojs/router 0.1.0 → 0.1.1

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.1.1",
   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.1.1",
   "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",
@@ -179,7 +183,8 @@
     "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"

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/ppr/SKILL.md

@@ -170,6 +170,48 @@ On a document GET to a ppr route the router runs:
 point is after the chain, an unauthorized request NEVER sees shell bytes — put
 auth middleware anywhere (global or route DSL) and it guards PPR for free.
 
+### Soft navigation reuses the captured segment shell
+
+A usable shell snapshot also accelerates ordinary partial RSC navigations to
+the same URL. The capture records the canonical document segment tree alongside
+the HTML prelude. On a partial request the server replays only that segment
+record through the normal `matchPartial()` pipeline, which then:
+
+- preserves client-owned shared layouts by segment id;
+- returns only new or revalidating destination segments;
+- runs DSL loaders fresh with their normal `loading()` streaming behavior;
+- keeps the existing prefetch key, source scope, and in-flight lock unchanged.
+
+This is deliberately invisible to the browser: the response is the same
+`RscPayload` shape as any other partial navigation. Captured item/response values
+and loader-container pins are NOT replayed on this path, so loader reads stay
+live. A route's own `cache()` scope still resolves its normal store, key, TTL,
+SWR, tags, and condition; only the implicit document scope sees the replay
+overlay, and fresh segment writes there stay request-local rather than polluting
+the canonical `doc:` namespace. Intercepts, handler-live holes,
+`transition({ when })`, an active nonce, and an absent/corrupt segment snapshot
+fall open to the ordinary partial path when encountered by the fresh shell
+capture. A transition already replayed from an explicit cache tier remains
+frozen by that tier's normal semantics.
+
+Only fresh shells replay. Production may use either a runtime entry or the
+local build manifest; development uses runtime entries only, because probing
+`/__rsc_shell` would block the foreground navigation on an on-demand capture.
+A passive stale read does not claim SWR ownership because partial requests
+cannot recapture the HTML shell. Custom `SegmentCacheStore` implementations
+must set `supportsPassiveShellReads: true` and honor
+`getShell(key, { claimRevalidation: false })` to opt into navigation replay.
+There is still no Flight resume API; this is segment replay followed by normal
+Flight streaming, not reuse of the HTML `prelude`/`postponed` bytes.
+
+### Capture-generation invalidation
+
+If handler or bake-lane code calls `updateTag()` on one of the shell's own tags
+while capture is running, that generation is rejected. Built-in stores report it;
+Rango warns with the shell key and backs capture off instead of rendering the
+same doomed generation on every request. Move a deterministic self-invalidation
+out of render code if you want the shell to persist.
+
 ### Opting out per request with `ctx.dynamic()`
 
 Middleware and handlers can call `ctx.dynamic()` to force this request back to
@@ -405,7 +447,8 @@ Four hard edges (each e2e/unit-pinned):
   Pitfalls: the session-object bake trap).
 - **A rejecting bake-lane loader refuses.** Error UI never bakes.
 - **Baked containers show CAPTURE-time data** for the shell's lifetime on
-  document GETs (client navigations stay fresh — axis 1). That IS the bake
+  document GETs. Soft navigations may replay the captured handler segments, but
+  DSL loaders and their item/response reads remain fresh. That IS the bake
   lane's meaning; if a value must be fresh on every serve, it belongs on the
   live lane (`loading()`) or in a nested promise.
 
@@ -539,9 +582,10 @@ bake-lane container — or key per variant at the CDN tier.
 
 ## What always stays on axis 1
 
-Non-GET, RSC/partial/action/loader fetches, per-request CSP nonce,
-`streamMode: "allReady"`, redirects, 404s, error renders, routes without `ppr`,
-and any store without the shell family. A stored shell is invalidated when
+Non-GET, non-partial RSC/action/loader fetches, partial requests without an
+eligible captured segment snapshot, per-request CSP nonce, `streamMode:
+"allReady"`, redirects, 404s, error renders, routes without `ppr`, and any store
+without the shell family. A stored shell is invalidated when
 `React.version` changes (postponed state is build-coupled), so deploys
 self-heal via recapture.