@rangojs/router 0.0.0-experimental.e9c0b2f2 → 0.0.0-experimental.ea9f40f2

package/src/vite/router-discovery.ts

@@ -19,6 +19,10 @@ import {
   createScanFilter,
 } from "../build/generate-route-types.js";
 import { firstCodeMatchIndex } from "../build/route-types/source-scan.js";
+import {
+  injectClientDebugFlag,
+  internalDebugNoCacheMiddleware,
+} from "./inject-client-debug.js";
 import { createVersionPlugin } from "./plugins/version-plugin.js";
 import { createVirtualStubPlugin } from "./plugins/virtual-stub-plugin.js";
 import {
@@ -42,6 +46,12 @@ import {
   peekSelfGenWrite,
 } from "./discovery/self-gen-tracking.js";
 import { discoverRouters } from "./discovery/discover-routers.js";
+import { describeDiscoveryFailure } from "./discovery/discovery-errors.js";
+import {
+  createDevPrerenderCache,
+  devPrerenderCacheKey,
+  payloadBodiesFromResult,
+} from "./discovery/dev-prerender-cache.js";
 import {
   writeCombinedRouteTypesWithTracking,
   writeRouteTypesFiles,
@@ -310,19 +320,13 @@ export function createRouterDiscoveryPlugin(
   return {
     name: "@rangojs/router:discovery",
 
-    config() {
-      const config: any = {
-        define: {
-          __RANGO_DEBUG__: JSON.stringify(!!process.env.INTERNAL_RANGO_DEBUG),
-        },
-      };
-      // Prerender/static handler modules are bundled naturally with the
-      // rest of the RSC entry.  A previous design forced them into dedicated
-      // __prerender-handlers / __static-handlers chunks via manualChunks,
-      // but Rollup hoisted all shared dependencies into those chunks,
-      // inflating them to ~1 MB with active runtime code.  Handler code is
-      // evicted in closeBundle regardless of which chunk it lands in.
-      return config;
+    // Make INTERNAL_RANGO_DEBUG reach the CLIENT debug logs by just setting the
+    // env var. See injectClientDebugFlag: bakes the resolved flag into the
+    // internal-debug module so FE debug no longer depends on Vite delivering the
+    // `__RANGO_DEBUG__` define to the client (which it does only as an injected
+    // global whose presence varies across consumer setups). Runs in dev and build.
+    transform(_code, id) {
+      return injectClientDebugFlag(id);
     },
 
     configResolved(config) {
@@ -391,6 +395,11 @@ export function createRouterDiscoveryPlugin(
       if ((globalThis as any).__rscRouterDiscoveryActive) return;
       s.devServer = server;
 
+      // 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.
+      server.middlewares.use(internalDebugNoCacheMiddleware());
+
       // Discovery promise that the handler can await if requests arrive
       // before discovery completes
       let resolveDiscovery: () => void;
@@ -549,6 +558,14 @@ export function createRouterDiscoveryPlugin(
           );
           console.warn(`[rango] Failed to create temp runner: ${err.message}`);
         }
+        // Reached only on failure (runner unavailable, or create/import threw
+        // AFTER the server was created). Close the just-created server so a
+        // failed discovery does not leak it until the next call or dev shutdown,
+        // and null the refs so the reuse path above starts clean. Mirrors the
+        // close pattern used when an existing server is discarded (above).
+        await prerenderTempServer?.close().catch(() => {});
+        prerenderTempServer = null;
+        prerenderNodeRegistry = null;
         return null;
       }
 
@@ -650,6 +667,30 @@ export function createRouterDiscoveryPlugin(
         return tempRscEnv;
       }
 
+      // Surface a discovery failure on either dev path (Node RSC runner or the
+      // Cloudflare temp Node server). `hashBefore`/`hashAfter` are the discovering
+      // environment's dep-optimizer browserHash snapshots: a change across the
+      // attempt means a reload-causing re-optimization landed mid-flight, so an
+      // empty registry was the transient race (downgraded to a warning) rather
+      // than a genuine misconfig (loud, actionable error). Shared so both catch
+      // sites frame the same failure identically.
+      const emitDiscoveryFailure = (
+        err: unknown,
+        hashBefore: string | undefined,
+        hashAfter: string | undefined,
+      ): void => {
+        const reoptimizeObserved =
+          hashBefore !== undefined &&
+          hashAfter !== undefined &&
+          hashBefore !== hashAfter;
+        const report = describeDiscoveryFailure(err, { reoptimizeObserved });
+        if (report.level === "warn") {
+          console.warn(report.message);
+        } else {
+          console.error(report.message);
+        }
+      };
+
       const discover = async () => {
         const discoverStart = performance.now();
         const rscEnv = (server.environments as any)?.rsc;
@@ -665,18 +706,26 @@ export function createRouterDiscoveryPlugin(
 
           // Create a temp Node.js server to run runtime discovery and generate
           // named route types (static parser can't resolve factory calls).
+          // The temp server is a separate Vite instance with its own dep
+          // optimizer; snapshot ITS browserHash (hoisted so the catch can tell a
+          // transient re-optimization apart from a genuine empty registry, the
+          // same way the Node path below does).
+          let tempRscEnv: any;
+          let optimizerHashBefore: string | undefined;
           try {
             // Acquire build-time env bindings for dev prerender
             await timed(debugDiscovery, "acquireBuildEnv", () =>
               acquireBuildEnv(s, viteCommand, viteMode),
             );
 
-            const tempRscEnv = await timed(
+            tempRscEnv = await timed(
               debugDiscovery,
               "getOrCreateTempServer",
               () => getOrCreateTempServer(),
             );
             if (tempRscEnv) {
+              optimizerHashBefore =
+                tempRscEnv.depsOptimizer?.metadata?.browserHash;
               await timed(debugDiscovery, "discoverRouters (cloudflare)", () =>
                 discoverRouters(s, tempRscEnv),
               );
@@ -685,8 +734,10 @@ export function createRouterDiscoveryPlugin(
               );
             }
           } catch (err: any) {
-            console.warn(
-              `[rango] Cloudflare dev discovery failed: ${err.message}\n${err.stack}`,
+            emitDiscoveryFailure(
+              err,
+              optimizerHashBefore,
+              tempRscEnv?.depsOptimizer?.metadata?.browserHash,
             );
           }
 
@@ -698,6 +749,13 @@ export function createRouterDiscoveryPlugin(
           return;
         }
 
+        // Snapshot the dep-optimizer hash before discovery so the catch can tell
+        // a transient re-optimization race apart from a genuine empty registry.
+        // A reload-causing re-optimization regenerates browserHash; if it changed
+        // across the attempt, an empty read was almost certainly the race below.
+        const optimizerHashBefore: string | undefined =
+          rscEnv.depsOptimizer?.metadata?.browserHash;
+
         try {
           // Acquire build-time env bindings for dev prerender (Node.js path)
           debugDiscovery?.("dev: node path start");
@@ -705,21 +763,31 @@ export function createRouterDiscoveryPlugin(
             acquireBuildEnv(s, viteCommand, viteMode),
           );
 
-          // Set the readiness gate BEFORE discovery so early requests
-          // block until manifest is populated
-          const serverMod = await timed(
-            debugDiscovery,
-            "import @rangojs/router/server",
-            () => rscEnv.runner.import("@rangojs/router/server"),
+          // Discover routers FIRST, then arm the manifest-readiness gate on the
+          // server module discovery actually read the registry from.
+          //
+          // We deliberately do NOT pre-import "@rangojs/router/server" before the
+          // entry to arm the gate early. During a Vite dependency re-optimization
+          // (dev boot after a lockfile change, or `vite dev --force`), a module
+          // imported here before the entry resolves to the pre-optimize copy of
+          // the runner's module graph, while discoverRouters' entry import — which
+          // awaits the in-flight re-optimization — resolves to the post-optimize
+          // copy. createRouter() then populates RouterRegistry on the fresh copy,
+          // but a stale pre-imported "@rangojs/router/server" reads the other
+          // copy's empty Map and discovery throws a spurious "No routers found"
+          // even though the app is configured correctly. discoverRouters imports
+          // the entry first and reads the registry off the same instance, keeping
+          // read and write on one copy. The virtual manifest module's own gate
+          // (s.discoveryDone, armed by beginDiscoveryGate) already blocks early
+          // requests during discovery on the Node path, so arming
+          // manifestReadyPromise after discovery is sufficient here.
+          const serverMod = await timed(debugDiscovery, "discoverRouters", () =>
+            discoverRouters(s, rscEnv),
           );
           if (serverMod?.setManifestReadyPromise) {
             serverMod.setManifestReadyPromise(discoveryPromise);
           }
 
-          await timed(debugDiscovery, "discoverRouters", () =>
-            discoverRouters(s, rscEnv),
-          );
-
           // Store server origin for dev prerender endpoint (virtual module injection)
           s.devServerOrigin = getDevServerOrigin();
 
@@ -737,8 +805,10 @@ export function createRouterDiscoveryPlugin(
             propagateDiscoveryState(rscEnv),
           );
         } catch (err: any) {
-          console.warn(
-            `[rango] Router discovery failed: ${err.message}\n${err.stack}`,
+          emitDiscoveryFailure(
+            err,
+            optimizerHashBefore,
+            rscEnv.depsOptimizer?.metadata?.browserHash,
           );
         } finally {
           debugDiscovery?.(
@@ -771,6 +841,15 @@ export function createRouterDiscoveryPlugin(
       // Registry from the main server's RSC environment (populated by discoverRouters)
       let mainRegistry: Map<string, any> | null = null;
 
+      // Memoized /__rsc_prerender render results, keyed by router-instance
+      // identity (#654). The per-request entry re-import below is what makes
+      // identity a valid freshness key: an HMR-invalidated chain re-runs
+      // createRouter() and replaces the registry instance, so cached bodies
+      // for the old instance become unreachable; an untouched chain returns
+      // the same instance and the cached body is byte-identical to a fresh
+      // render. See dev-prerender-cache.ts for the full invariant.
+      const devPrerenderCache = createDevPrerenderCache();
+
       // Push discovery state (manifest, trie, precomputed entries) to the
       // server module so runtime request handling uses the current routes.
       // Shared by initial discovery and HMR-triggered re-discovery.
@@ -861,9 +940,28 @@ export function createRouterDiscoveryPlugin(
 
         if (!registry) {
           // No main registry: the RSC env has no module runner (Cloudflare dev).
-          // Lazily create a Node.js temp server for prerender evaluation.
-          if (!prerenderNodeRegistry) {
-            await getOrCreateTempServer();
+          // Lazily create a Node.js temp server for prerender evaluation, and
+          // re-import the entry through it on EVERY request — the temp server
+          // has its own file watcher, so a handler-only edit (a file without
+          // urls()/createRouter() that the main watcher's route-file sniff
+          // ignores) invalidates its module graph; the re-import re-evaluates
+          // exactly the dirty subgraph and re-registers fresh router
+          // instances. Before #654 the cached registry was only refreshed on
+          // route-file edits, so handler-only edits served stale prerender
+          // content on this path. Warm-cache re-imports are module-cache hits.
+          const tempRscEnv = await getOrCreateTempServer();
+          if (tempRscEnv) {
+            try {
+              await importEntryAndRegistry(tempRscEnv);
+            } catch (err: any) {
+              console.warn(
+                `[rango] Dev prerender module refresh failed: ${err.message}`,
+              );
+              res.statusCode = 500;
+              res.end(`Prerender handler error: ${err.message}`);
+              logResult(500, "temp module refresh failed");
+              return;
+            }
           }
           registry = prerenderNodeRegistry;
         }
@@ -879,8 +977,38 @@ export function createRouterDiscoveryPlugin(
         const wantRouteName = url.searchParams.get("routeName");
         const wantPassthrough = url.searchParams.get("passthrough") === "1";
 
+        // One render warms BOTH variant keys (matchForPrerender computes the
+        // intercept segments unconditionally), so a route's main and modal
+        // variants cost a single render per HMR generation.
+        const variantDims = {
+          passthrough: wantPassthrough,
+          routeName: wantRouteName,
+        };
+        const keyMain = devPrerenderCacheKey(pathname, {
+          intercept: false,
+          ...variantDims,
+        });
+        const keyIntercept = devPrerenderCacheKey(pathname, {
+          intercept: true,
+          ...variantDims,
+        });
+        const requestedKey = wantIntercept ? keyIntercept : keyMain;
+
         for (const [, routerInstance] of registry) {
           if (!routerInstance.matchForPrerender) continue;
+          // Cache is consulted per router IN LOOP ORDER so multi-router
+          // fall-through semantics are identical to the uncached path: a
+          // router that never produced a payload for this key still runs
+          // its matchForPrerender (cheap trie miss / intentionally-uncached
+          // error retry) before the next router is considered.
+          const cached = devPrerenderCache.get(routerInstance, requestedKey);
+          if (cached !== undefined) {
+            res.setHeader("content-type", "application/json");
+            res.setHeader("x-rango-prerender-cache", "HIT");
+            res.end(cached);
+            logResult(200, "cache hit");
+            return;
+          }
           try {
             const result = await routerInstance.matchForPrerender(
               pathname,
@@ -896,19 +1024,19 @@ export function createRouterDiscoveryPlugin(
             // This prevents returning the wrong entry when multiple routers
             // have prerenderable routes sharing the same pathname.
             if (wantRouteName && result.routeName !== wantRouteName) continue;
+            // Pre-encoded MERGED handle string in the intercept body comes
+            // from the producer (handles are Flight-encoded so
+            // Promise/ReactNode values survive the wire).
+            const bodies = payloadBodiesFromResult(result);
+            devPrerenderCache.set(routerInstance, keyMain, bodies.main);
+            devPrerenderCache.set(
+              routerInstance,
+              keyIntercept,
+              bodies.intercept,
+            );
             res.setHeader("content-type", "application/json");
-            let payload: Record<string, unknown>;
-            if (wantIntercept && result.interceptSegments?.length) {
-              payload = {
-                segments: [...result.segments, ...result.interceptSegments],
-                // Pre-encoded MERGED handle string from the producer (handles are
-                // Flight-encoded so Promise/ReactNode values survive the wire).
-                handles: result.interceptHandles ?? "",
-              };
-            } else {
-              payload = { segments: result.segments, handles: result.handles };
-            }
-            res.end(JSON.stringify(payload));
+            res.setHeader("x-rango-prerender-cache", "MISS");
+            res.end(wantIntercept ? bodies.intercept : bodies.main);
             logResult(200, `match ${result.routeName}`);
             return;
           } catch (err: any) {

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

@@ -10,12 +10,10 @@ import {
 import { resolve } from "node:path";
 
 import { escapeRegExp } from "../../regex-escape.js";
+import { encodePathRemainder } from "../../router/url-params.js";
 
 export function encodePathParam(value: unknown): string {
-  return String(value)
-    .split("/")
-    .map((segment) => encodeURIComponent(segment))
-    .join("/");
+  return encodePathRemainder(String(value), encodeURIComponent);
 }
 
 export function substituteRouteParams(
@@ -28,6 +26,21 @@ export function substituteRouteParams(
 
   for (const [key, value] of Object.entries(params)) {
     const escaped = escapeRegExp(key);
+    // Named catch-all `:key+` / `:key*` (issue #634). Like the runtime reverse,
+    // the value is multi-segment: encode each segment and keep the `/` separators
+    // (a whole-value encode would turn `a/b` into `a%2Fb`), and consume the
+    // trailing modifier so it does not leak into the URL. `*` (zero-or-more)
+    // absent collapses via the trailing cleanup below.
+    const catchAllRe = new RegExp(`:${escaped}[+*]`);
+    if (catchAllRe.test(result)) {
+      if (value === "") {
+        result = result.replace(catchAllRe, "");
+        hadOmittedOptional = true;
+      } else {
+        result = result.replace(catchAllRe, encodePathRemainder(value, encode));
+      }
+      continue;
+    }
     if (value === "") {
       result = result.replace(
         new RegExp(`:${escaped}(\\([^)]*\\))?(?!\\?)`),

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

@@ -1,5 +1,6 @@
 import type { Plugin, ResolvedConfig } from "vite";
 import * as Vite from "vite";
+import { isAbsolute, resolve } from "node:path";
 import { getPublishedPackageName } from "./package-resolution.js";
 import { performanceTracksOptimizeDepsPlugin } from "../plugins/performance-tracks.js";
 import {
@@ -55,6 +56,52 @@ export const sharedRolldownOptions: {
   plugins: [versionRolldownPlugin, performanceTracksOptimizeDepsPlugin()],
 };
 
+/**
+ * Normalize an explicit `hostRouter` option into the specifier emitted as the
+ * host entry's `import ... from "<path>"`, and — for the forms that resolve
+ * unambiguously against the project root — verify the file exists (failing with
+ * a rango message instead of a downstream bundler "failed to resolve").
+ *
+ * Only a BARE specifier ("src/worker.rsc.tsx") that exists under the root is
+ * rewritten (to "./src/...") so it is not read as a package. A bare specifier
+ * that does NOT exist under the root is passed through VERBATIM: it may be a
+ * Vite alias ("@/worker.rsc.tsx"), an imports-map entry ("#app/worker"), or a
+ * workspace package the bundler resolves — rewriting or rejecting those was a
+ * regression (aliases worked before normalization existed). "./"/"../", a
+ * leading-slash (Vite root-relative), and a filesystem-absolute path are
+ * emitted unchanged — Vite resolves each. A leading-slash path and a
+ * filesystem-absolute path are indistinguishable on POSIX, so both are treated
+ * as "rooted": passed through WITHOUT an existence check (guessing between the
+ * two would wrongly reject a valid file — this was a regression the first time
+ * the check was added). Only the explicitly-relative forms, which resolve
+ * unambiguously against the root, fail fast with a rango message.
+ *
+ * `exists` is injected so the logic is unit-testable without a real filesystem.
+ */
+export function normalizeHostRouterEntry(
+  rawInput: string,
+  root: string,
+  exists: (absPath: string) => boolean,
+): string {
+  const raw = rawInput.replaceAll("\\", "/");
+  const isRelative = raw.startsWith("./") || raw.startsWith("../");
+  const isRooted = raw.startsWith("/") || isAbsolute(rawInput);
+  if (isRooted) return raw;
+  if (isRelative) {
+    if (!exists(resolve(root, raw))) {
+      throw new Error(
+        `[rango] hostRouter entry not found: "${rawInput}" (resolved under ` +
+          `${root}). Point it at your createHostRouter() module, e.g. ` +
+          `rango({ hostRouter: "./src/worker.rsc.tsx" }).`,
+      );
+    }
+    return raw;
+  }
+  // Bare specifier: an existing root-relative file gets the explicit "./";
+  // anything else (alias, imports-map, package) is the bundler's to resolve.
+  return exists(resolve(root, raw)) ? "./" + raw : raw;
+}
+
 /**
  * Create a virtual modules plugin for default entry files.
  * Provides virtual module content when entries use VIRTUAL_IDS (no custom entry configured).

package/src/network-error-thrower.tsx

@@ -1,18 +0,0 @@
-"use client";
-
-import type { ReactNode } from "react";
-import type { NetworkError } from "./errors.js";
-
-interface NetworkErrorThrowerProps {
-  error: NetworkError;
-}
-
-/**
- * Client component that throws a NetworkError during render.
- * Errors thrown during render are caught by error boundaries; async errors are not.
- */
-export function NetworkErrorThrower({
-  error,
-}: NetworkErrorThrowerProps): ReactNode {
-  throw error;
-}