@rangojs/router 0.0.0-experimental.18 → 0.0.0-experimental.19

package/src/use-loader.tsx

@@ -88,6 +88,7 @@ function useLoaderInternal<T>(
   const [fetchedData, setFetchedData] = useState<T | undefined>(undefined);
   const [isLoading, setIsLoading] = useState(false);
   const [error, setError] = useState<Error | null>(null);
+  const requestIdRef = useRef(0);
 
   // Track context data changes to reset fetched data on navigation
   const prevContextDataRef = useRef(contextData);
@@ -118,6 +119,7 @@ function useLoaderInternal<T>(
   // Supports GET (data fetching) and POST/PUT/PATCH/DELETE (mutations).
   const load = useCallback(
     async (loadOptions?: LoadOptions): Promise<T> => {
+      const requestId = ++requestIdRef.current;
       const loaderId = loaderIdRef.current;
       // Verify the loader has $$id
       if (!loaderId) {
@@ -130,7 +132,7 @@ function useLoaderInternal<T>(
       setError(null);
 
       try {
-        const url = new URL(window.location.pathname, window.location.origin);
+        const url = new URL(window.location.href);
         url.searchParams.set("_rsc_loader", loaderId);
 
         const method = loadOptions?.method ?? "GET";
@@ -212,11 +214,15 @@ function useLoaderInternal<T>(
         }
 
         const result = payload.loaderResult;
-        setFetchedData(result);
+        if (requestId === requestIdRef.current) {
+          setFetchedData(result);
+        }
         return result;
       } catch (e) {
         const err = e instanceof Error ? e : new Error(String(e));
-        setError(err);
+        if (requestId === requestIdRef.current) {
+          setError(err);
+        }
         if (throwOnError) {
           throw err;
         }
@@ -224,7 +230,9 @@ function useLoaderInternal<T>(
         // successful value or undefined). Caller should check error state.
         return dataRef.current as T;
       } finally {
-        setIsLoading(false);
+        if (requestId === requestIdRef.current) {
+          setIsLoading(false);
+        }
       }
     },
     [throwOnError],

package/src/vite/discovery/bundle-postprocess.ts

@@ -91,7 +91,10 @@ export function postprocessBundle(state: DiscoveryState): void {
   // and inject a manifest import into the RSC entry.
   if (hasPrerenderData && existsSync(rscEntryPath)) {
     const rscCode = readFileSync(rscEntryPath, "utf-8");
-    if (!rscCode.includes("__PRERENDER_MANIFEST")) {
+    // Check for the specific injection marker, not just the variable name.
+    // The runtime code (prerender store) also references __PRERENDER_MANIFEST,
+    // so a broad string check would false-positive and skip injection.
+    if (!rscCode.includes("__prerender-manifest.js")) {
       try {
         const assetsDir = resolve(state.projectRoot, "dist/rsc/assets");
         mkdirSync(assetsDir, { recursive: true });
@@ -155,17 +158,19 @@ export function postprocessBundle(state: DiscoveryState): void {
         for (const [handlerId, { encoded, handles }] of Object.entries(
           state.staticCollectedData!,
         )) {
-          const contentHash = createHash("sha256")
-            .update(encoded)
-            .digest("hex")
-            .slice(0, 8);
-          const assetFileName = `__st-${contentHash}.js`;
-          const assetPath = resolve(assetsDir, assetFileName);
           // Store both the Flight payload and handle data
           const hasHandles = Object.keys(handles).length > 0;
           const exportValue = hasHandles
             ? JSON.stringify({ encoded, handles })
             : JSON.stringify(encoded);
+          // Hash the full payload that is written so distinct handle
+          // snapshots produce distinct asset filenames.
+          const contentHash = createHash("sha256")
+            .update(exportValue)
+            .digest("hex")
+            .slice(0, 8);
+          const assetFileName = `__st-${contentHash}.js`;
+          const assetPath = resolve(assetsDir, assetFileName);
           const assetCode = `export default ${exportValue};\n`;
           writeFileSync(assetPath, assetCode);
           totalBytes += Buffer.byteLength(assetCode);

package/src/vite/discovery/discover-routers.ts

@@ -100,12 +100,15 @@ export async function discoverRouters(
   const buildMod = await rscEnv.runner.import("@rangojs/router/build");
   const generateManifestFull = buildMod.generateManifestFull;
 
-  state.mergedRouteManifest = {};
-  state.mergedPrecomputedEntries = [];
-  state.perRouterManifests = [];
-  state.perRouterManifestDataMap = new Map();
-  state.perRouterPrecomputedMap = new Map();
-  state.perRouterTrieMap = new Map();
+  // Build into local variables first. Only commit to state after the
+  // full pass succeeds, so a failed re-discovery preserves the last
+  // known-good state instead of leaving it partially wiped.
+  const newMergedRouteManifest: Record<string, string> = {};
+  const newMergedPrecomputedEntries: PrecomputedEntry[] = [];
+  const newPerRouterManifests: typeof state.perRouterManifests = [];
+  const newPerRouterManifestDataMap = new Map<string, any>();
+  const newPerRouterPrecomputedMap = new Map<string, PrecomputedEntry[]>();
+  const newPerRouterTrieMap = new Map<string, any>();
   let mergedRouteAncestry: Record<string, string[]> = {};
   let mergedRouteTrailingSlash: Record<string, string> = {};
 
@@ -128,7 +131,7 @@ export async function discoverRouters(
     const dynamicRoutes = routeCount - staticRoutes;
 
     // Merge into the combined manifest
-    Object.assign(state.mergedRouteManifest, manifest.routeManifest);
+    Object.assign(newMergedRouteManifest, manifest.routeManifest);
 
     // Compute factory-only prefixes: dot-prefixed groups in the runtime
     // manifest that the static parser cannot see. These are routes created
@@ -152,7 +155,7 @@ export async function discoverRouters(
       if (factoryOnlyPrefixes.size === 0) factoryOnlyPrefixes = undefined;
     }
 
-    state.perRouterManifests.push({
+    newPerRouterManifests.push({
       id,
       routeManifest: manifest.routeManifest,
       routeSearchSchemas: manifest.routeSearchSchemas,
@@ -175,18 +178,18 @@ export async function discoverRouters(
     flattenLeafEntries(
       manifest.prefixTree,
       manifest.routeManifest,
-      state.mergedPrecomputedEntries,
+      newMergedPrecomputedEntries,
     );
 
     // Store per-router manifest and precomputed entries for isolated virtual modules.
-    state.perRouterManifestDataMap.set(id, manifest.routeManifest);
+    newPerRouterManifestDataMap.set(id, manifest.routeManifest);
     const routerPrecomputed: PrecomputedEntry[] = [];
     flattenLeafEntries(
       manifest.prefixTree,
       manifest.routeManifest,
       routerPrecomputed,
     );
-    state.perRouterPrecomputedMap.set(id, routerPrecomputed);
+    newPerRouterPrecomputedMap.set(id, routerPrecomputed);
 
     console.log(
       `[rsc-router] Router "${id}" -> ${routeCount} routes ` +
@@ -214,10 +217,8 @@ export async function discoverRouters(
   }
 
   // Build route trie from merged manifest + ancestry
-  if (
-    state.mergedRouteManifest &&
-    Object.keys(state.mergedRouteManifest).length > 0
-  ) {
+  let newMergedRouteTrie: any = null;
+  if (Object.keys(newMergedRouteManifest).length > 0) {
     const buildRouteTrie = buildMod.buildRouteTrie;
     if (buildRouteTrie && mergedRouteAncestry) {
       // Build routeToStaticPrefix from saved manifests
@@ -252,8 +253,8 @@ export async function discoverRouters(
         }
       }
 
-      state.mergedRouteTrie = buildRouteTrie(
-        state.mergedRouteManifest,
+      newMergedRouteTrie = buildRouteTrie(
+        newMergedRouteManifest,
         mergedRouteAncestry,
         routeToStaticPrefix,
         Object.keys(mergedRouteTrailingSlash).length > 0
@@ -305,11 +306,22 @@ export async function discoverRouters(
             ? manifest.responseTypeRoutes
             : undefined,
         );
-        state.perRouterTrieMap.set(id, perRouterTrie);
+        newPerRouterTrieMap.set(id, perRouterTrie);
       }
     }
   }
 
+  // Commit all local state to the shared discovery state atomically.
+  // This ensures a failed re-discovery (e.g. from a transient module
+  // evaluation error) preserves the last known-good state.
+  state.mergedRouteManifest = newMergedRouteManifest;
+  state.mergedPrecomputedEntries = newMergedPrecomputedEntries;
+  state.perRouterManifests = newPerRouterManifests;
+  state.perRouterManifestDataMap = newPerRouterManifestDataMap;
+  state.perRouterPrecomputedMap = newPerRouterPrecomputedMap;
+  state.perRouterTrieMap = newPerRouterTrieMap;
+  state.mergedRouteTrie = newMergedRouteTrie;
+
   // Expand prerender routes and render static handlers (build mode only)
   await expandPrerenderRoutes(state, rscEnv, registry, allManifests);
   await renderStaticHandlers(state, rscEnv, registry);

package/src/vite/discovery/prerender-collection.ts

@@ -9,7 +9,7 @@
 import { contextSet } from "../../context-var.js";
 import {
   encodePathParam,
-  escapeRegExp,
+  substituteRouteParams,
   runWithConcurrency,
   groupByConcurrency,
   notifyOnError,
@@ -33,6 +33,7 @@ export async function expandPrerenderRoutes(
     routeName: string;
     concurrency: number;
     buildVars?: Record<string, any>;
+    isPassthroughRoute?: boolean;
   };
   const entries: PrerenderEntry[] = [];
 
@@ -44,19 +45,8 @@ export async function expandPrerenderRoutes(
   const getParamsReverse = (name: string, params?: Record<string, string>) => {
     const pattern = allRoutes[name];
     if (!pattern) throw new Error(`Unknown route: "${name}"`);
-    let result = pattern;
-    if (params) {
-      for (const [key, value] of Object.entries(params)) {
-        // Strip constraint syntax: :param(a|b) -> value
-        const escaped = escapeRegExp(key);
-        result = result.replace(
-          new RegExp(`:${escaped}(\\([^)]*\\))?`),
-          encodeURIComponent(value),
-        );
-        result = result.replace(`*${key}`, encodeURIComponent(value));
-      }
-    }
-    return result;
+    if (!params) return pattern;
+    return substituteRouteParams(pattern, params);
   };
 
   for (const { manifest } of allManifests) {
@@ -65,6 +55,8 @@ export async function expandPrerenderRoutes(
     for (const routeName of manifest.prerenderRoutes) {
       const pattern = manifest.routeManifest[routeName];
       if (!pattern) continue;
+      const def = defs[routeName];
+      const isPassthroughRoute = !!def?.options?.passthrough;
       const hasDynamic = pattern.includes(":") || pattern.includes("*");
       if (!hasDynamic) {
         // Static route: use pattern directly (strip trailing slash for URL)
@@ -72,10 +64,10 @@ export async function expandPrerenderRoutes(
           urlPath: pattern.replace(/\/$/, "") || "/",
           routeName,
           concurrency: 1,
+          isPassthroughRoute,
         });
       } else {
         // Dynamic route: call getParams() to enumerate param combinations
-        const def = defs[routeName];
         if (def?.getParams) {
           try {
             const buildVars: Record<string, any> = {};
@@ -92,19 +84,11 @@ export async function expandPrerenderRoutes(
               Object.keys(buildVars).length > 0 ||
               Object.getOwnPropertySymbols(buildVars).length > 0;
             for (const params of paramsList) {
-              let url = pattern;
-              for (const [key, value] of Object.entries(
+              let url = substituteRouteParams(
+                pattern,
                 params as Record<string, string>,
-              )) {
-                const encoded = encodePathParam(value);
-                // Strip constraint syntax: :param(a|b) -> value
-                const escaped = escapeRegExp(key);
-                url = url.replace(
-                  new RegExp(`:${escaped}(\\([^)]*\\))?`),
-                  encoded,
-                );
-                url = url.replace(`*${key}`, encoded);
-              }
+                encodePathParam,
+              );
               // Anonymous wildcard fallback: use conventional keys if provided
               if (url.includes("*")) {
                 const wildcardValue =
@@ -119,6 +103,7 @@ export async function expandPrerenderRoutes(
                 routeName,
                 concurrency,
                 ...(hasBuildVars ? { buildVars } : {}),
+                isPassthroughRoute,
               });
             }
           } catch (err: any) {
@@ -187,8 +172,20 @@ export async function expandPrerenderRoutes(
               entry.urlPath,
               {},
               entry.buildVars,
+              entry.isPassthroughRoute,
             );
             if (!result) continue;
+
+            // Handler returned ctx.passthrough() — skip manifest entry
+            if (result.passthrough) {
+              const elapsed = (performance.now() - startUrl).toFixed(0);
+              console.log(
+                `[rsc-router]   PASS ${entry.urlPath.padEnd(40)} (${elapsed}ms) - live fallback`,
+              );
+              doneCount++;
+              break;
+            }
+
             const paramHash = hashParams(result.params || {});
             collectedData[`${result.routeName}/${paramHash}`] = {
               segments: result.segments,

package/src/vite/discovery/route-types-writer.ts

@@ -15,20 +15,20 @@ import {
 } from "../../build/generate-route-types.js";
 import type { DiscoveryState } from "./state.js";
 import { markSelfGenWrite } from "./self-gen-tracking.js";
+import { isAutoGeneratedRouteName } from "../../route-name.js";
 
 /**
  * Filter out auto-generated route names from a manifest.
- * Routes with names starting with "$" are internal (auto-generated from
- * patterns for unnamed routes) and should not appear in the typed gen file.
- * This keeps the runtime writer's output consistent with the static parser,
- * which never produces these names.
+ * Unnamed routes get "$path_"-prefixed names at runtime (see path-helper.ts).
+ * These should not appear in the typed gen file. User-defined names
+ * containing "$" (e.g. "$admin") are valid and preserved.
  */
 function filterUserNamedRoutes(
   manifest: Record<string, string>,
 ): Record<string, string> {
   const filtered: Record<string, string> = {};
   for (const [name, pattern] of Object.entries(manifest)) {
-    if (!name.startsWith("$")) {
+    if (!isAutoGeneratedRouteName(name)) {
       filtered[name] = pattern;
     }
   }
@@ -222,8 +222,8 @@ export function supplementGenFilesWithRuntimeRoutes(
     };
 
     for (const [name, pattern] of Object.entries(routeManifest)) {
-      // Skip auto-generated names
-      if (name.startsWith("$")) continue;
+      // Skip internal runtime-only names from unnamed routes/includes.
+      if (isAutoGeneratedRouteName(name)) continue;
       const dotIdx = name.indexOf(".");
       if (dotIdx <= 0) continue;
       const prefix = name.substring(0, dotIdx + 1);

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

@@ -42,7 +42,7 @@ export function generateRoutesManifestModule(state: DiscoveryState): string {
         const genPath = join(
           routerDir,
           `${routerBasename}.named-routes.gen.js`,
-        );
+        ).replaceAll("\\", "/");
         const varName = `_r${varIdx++}`;
         genFileImports.push(
           `import { NamedRoutes as ${varName} } from ${JSON.stringify(genPath)};`,
@@ -176,7 +176,10 @@ export function generatePerRouterModule(
       /\.(tsx?|jsx?)$/,
       "",
     );
-    const genPath = join(routerDir, `${routerBasename}.named-routes.gen.js`);
+    const genPath = join(
+      routerDir,
+      `${routerBasename}.named-routes.gen.js`,
+    ).replaceAll("\\", "/");
     lines.push(`import { NamedRoutes as _r } from ${JSON.stringify(genPath)};`);
     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; }`,

package/src/vite/plugins/client-ref-hashing.ts

@@ -1,5 +1,5 @@
 import type { Plugin } from "vite";
-import { relative, posix } from "node:path";
+import { relative } from "node:path";
 import { createHash } from "node:crypto";
 
 // Dev-mode client-reference key prefixes emitted by @vitejs/plugin-rsc
@@ -33,11 +33,11 @@ export function computeProductionHash(
     const absPath = decodeURIComponent(
       refKey.slice(CLIENT_IN_SERVER_PKG_PROXY_PREFIX.length),
     );
-    toHash = posix.normalize(relative(projectRoot, absPath));
+    toHash = relative(projectRoot, absPath).replaceAll("\\", "/");
   } else if (refKey.startsWith(FS_PREFIX)) {
     // /@fs/abs/path.tsx -> hash(relative(root, "/abs/path.tsx"))
     const absPath = refKey.slice(FS_PREFIX.length - 1); // keep leading /
-    toHash = posix.normalize(relative(projectRoot, absPath));
+    toHash = relative(projectRoot, absPath).replaceAll("\\", "/");
   } else if (refKey.startsWith("/")) {
     // /src/Button.tsx -> hash("src/Button.tsx")
     toHash = refKey.slice(1);

package/src/vite/plugins/use-cache-transform.ts

@@ -97,7 +97,7 @@ export function useCacheTransform(): Plugin {
 
       // Check for function-level "use cache" / "use cache: profileName"
       // (only if there's no file-level directive but code still contains the string)
-      return transformFunctionLevelUseCache(
+      const functionResult = transformFunctionLevelUseCache(
         code,
         ast,
         filePath,
@@ -105,6 +105,13 @@ export function useCacheTransform(): Plugin {
         isBuild,
         transformHoistInlineDirective,
       );
+
+      // Always check for near-miss directives, even when valid directives
+      // exist. A file may contain both valid and invalid "use cache" directives
+      // in different functions — the invalid ones should still warn.
+      warnOnNearMissDirectives(ast, id, this.warn.bind(this));
+
+      if (functionResult) return functionResult;
     },
   };
 }
@@ -118,19 +125,38 @@ function transformFileLevelUseCache(
   isLayoutOrTemplate: boolean,
   transformWrapExport: (typeof import("@vitejs/plugin-rsc/transforms"))["transformWrapExport"],
 ) {
+  // Collect non-function exports to report after wrapping
+  const nonFunctionExports: string[] = [];
+
   const { exportNames, output } = transformWrapExport(code, ast, {
     runtime: (value: string, name: string) => {
       const funcId = isBuild ? hashId(filePath, name) : `${filePath}#${name}`;
       return `__rango_registerCachedFunction(${value}, ${JSON.stringify(funcId)}, "default")`;
     },
     rejectNonAsyncFunction: false,
-    filter: (name: string) => {
+    filter: (name: string, meta: { isFunction?: boolean }) => {
       // Skip default export of layout/template files (they receive children)
       if (name === "default" && isLayoutOrTemplate) return false;
+      // Non-function exports cannot be wrapped with registerCachedFunction
+      if (meta.isFunction === false) {
+        nonFunctionExports.push(name);
+        return false;
+      }
       return true;
     },
   });
 
+  if (nonFunctionExports.length > 0) {
+    throw new Error(
+      `[rango:use-cache] File-level "use cache" in ${sourceId} cannot wrap ` +
+        `non-function export${nonFunctionExports.length > 1 ? "s" : ""}: ` +
+        `${nonFunctionExports.map((n) => `"${n}"`).join(", ")}. ` +
+        `Only function exports can be cached. Either remove "use cache" from ` +
+        `the file level and add it inside individual functions, or move the ` +
+        `non-function exports to a separate module.`,
+    );
+  }
+
   if (exportNames.length === 0) {
     // Even if no exports were wrapped, strip the directive
     const s = new MagicString(code);
@@ -180,7 +206,7 @@ function transformFunctionLevelUseCache(
 ) {
   try {
     const { output, names } = transformHoistInlineDirective(code, ast, {
-      directive: /^use cache(:\s*\w+)?$/,
+      directive: /^use cache(:\s*[\w-]+)?$/,
       runtime: (
         value: string,
         name: string,
@@ -233,3 +259,65 @@ function findFileLevelDirective(
   }
   return null;
 }
+
+/**
+ * The valid directive regex (must stay in sync with transformFunctionLevelUseCache).
+ */
+const VALID_DIRECTIVE_RE = /^use cache(:\s*[\w-]+)?$/;
+
+/**
+ * Regex for near-miss: starts with "use cache:" but has invalid tokens.
+ */
+const NEAR_MISS_RE = /^use cache:\s*.+$/;
+
+/**
+ * Walk the AST looking for string literals that look like malformed
+ * "use cache" directives and emit a Vite warning for each.
+ *
+ * This catches cases like `"use cache: bad.name"` or `"use cache: "`
+ * that the transform regex silently ignores.
+ */
+function warnOnNearMissDirectives(
+  ast: any,
+  fileId: string,
+  warn: (message: string) => void,
+): void {
+  const visit = (node: any) => {
+    if (!node || typeof node !== "object") return;
+
+    if (
+      node.type === "ExpressionStatement" &&
+      node.expression?.type === "Literal" &&
+      typeof node.expression.value === "string"
+    ) {
+      const value = node.expression.value;
+      if (
+        value.startsWith("use cache") &&
+        NEAR_MISS_RE.test(value) &&
+        !VALID_DIRECTIVE_RE.test(value)
+      ) {
+        const profilePart = value.slice("use cache:".length).trim();
+        warn(
+          `[rango:use-cache] "${value}" in ${fileId} has an invalid profile name "${profilePart}". ` +
+            `Profile names must match [a-zA-Z0-9_-]+. This directive will be ignored.`,
+        );
+      }
+    }
+
+    // Walk into function bodies where directives appear
+    for (const key of Object.keys(node)) {
+      const child = node[key];
+      if (Array.isArray(child)) {
+        for (const item of child) {
+          visit(item);
+        }
+      } else if (child && typeof child === "object" && child.type) {
+        visit(child);
+      }
+    }
+  };
+
+  for (const node of ast.body ?? []) {
+    visit(node);
+  }
+}

package/src/vite/rango.ts

@@ -222,9 +222,9 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
           const candidates = findRouterFiles(root, filter);
           if (candidates.length === 1) {
             const abs = candidates[0];
-            routerRef.path = abs.startsWith(root)
-              ? "./" + abs.slice(root.length + 1)
-              : abs;
+            routerRef.path = (
+              abs.startsWith(root) ? "./" + abs.slice(root.length + 1) : abs
+            ).replaceAll("\\", "/");
           } else if (candidates.length > 1) {
             const list = candidates
               .map(