@rangojs/router 0.0.0-experimental.fb4fdc18 → 0.0.0-experimental.fce7fbd1

package/README.md

@@ -602,7 +602,7 @@ export function Nav({ home, post }: { home: string; post: string }) {
 }
 ```
 
-For client-side navigation to static paths (no named-route lookup), use `href()` — see below. For URLs tied to named routes, always generate on the server and pass the string in.
+For client-side navigation to static paths (no named-route lookup), use `href()` — see below. For URLs tied to named routes, you have two options: import the per-module generated `routes` map and use `useReverse(routes)` for in-module names (see [`/links` skill](./skills/links/SKILL.md)), or generate the URL on the server and pass the string in for cross-module URLs.
 
 ### `href()` for Path Validation (Client Components)
 
@@ -943,9 +943,9 @@ import { createHostRouter } from "@rangojs/router/host";
 
 const hostRouter = createHostRouter();
 
-hostRouter.host(["*.localhost"]).map(() => import("./apps/admin/handler.js"));
-hostRouter.host(["localhost"]).map(() => import("./apps/site/handler.js"));
-hostRouter.fallback().map(() => import("./apps/site/handler.js"));
+hostRouter.host(["*.localhost"]).lazy(() => import("./apps/admin/handler.js"));
+hostRouter.host(["localhost"]).lazy(() => import("./apps/site/handler.js"));
+hostRouter.fallback().lazy(() => import("./apps/site/handler.js"));
 
 export default {
   async fetch(request, env, ctx) {
@@ -954,7 +954,7 @@ export default {
 };
 ```
 
-Each sub-app has its own `createRouter()` and `urls()`. The host router lazily imports the matched app's handler. Patterns are matched in registration order — register more specific patterns (subdomains) before catch-alls.
+Use `.lazy(() => import("./sub-app"))` to mount a lazily-imported sub-app (a module whose `default` export is a handler or nested host router), and `.map((request) => Response)` for an inline request handler. Only `.lazy()` mounts are imported during build-time discovery; `.map(() => import(...))` is a type error. Each sub-app has its own `createRouter()` and `urls()`. Patterns are matched in registration order — register more specific patterns (subdomains) before catch-alls.
 
 ## Meta Tags
 
@@ -993,16 +993,16 @@ Auto-detects file type:
 
 ## Type Safety
 
-The Vite plugin automatically generates a `router.named-routes.gen.ts` file that globally registers route names, patterns, and search schemas via `RSCRouter.GeneratedRouteMap`. This powers server-side named-route typing such as `Handler<"name">`, `ctx.reverse()`, `getRequestContext().reverse()`, and `RouteParams<"name">` without any manual route registration. The gen file is updated on dev server startup, HMR, and production builds.
+The Vite plugin automatically generates a `router.named-routes.gen.ts` file that globally registers route names, patterns, and search schemas via `Rango.GeneratedRouteMap`. This powers server-side named-route typing such as `Handler<"name">`, `ctx.reverse()`, `getRequestContext().reverse()`, and `RouteParams<"name">` without any manual route registration. The gen file is updated on dev server startup, HMR, and production builds.
 
-Use the generated map by default. Augment `RSCRouter.RegisteredRoutes` only when you need the richer `typeof router.routeMap` shape globally, especially for response-aware and path-based utilities.
+Use the generated map by default. Augment `Rango.RegisteredRoutes` only when you need the richer `typeof router.routeMap` shape globally, especially for response-aware and path-based utilities.
 
 ```typescript
 // router.tsx
 const router = createRouter<AppBindings>({}).routes(urlpatterns);
 
 declare global {
-  namespace RSCRouter {
+  namespace Rango {
     interface Env extends AppEnv {}
     interface Vars extends AppVars {}
     interface RegisteredRoutes extends typeof router.routeMap {}
@@ -1014,7 +1014,7 @@ Quick rule of thumb:
 
 - `GeneratedRouteMap` (auto-generated) — use for server-side named-route typing: `Handler<"name">`, `ctx.reverse()`, `Prerender<"name">`
 - `typeof router.routeMap` — use when you need route entries with response metadata
-- `RegisteredRoutes` (manual augmentation) — use to expose `typeof router.routeMap` globally for `href()`, `PathResponse`, `ValidPaths`, and other path/response-aware utilities
+- `RegisteredRoutes` (manual augmentation) — use to expose `typeof router.routeMap` globally for `href()`, `Rango.Path`, `Rango.PathResponse`, and other path/response-aware utilities
 
 For extracted reusable loaders or middleware, prefer global dotted names on
 `ctx.reverse()` by default. If you want type-safe local names for a specific

package/dist/bin/rango.js

@@ -139,7 +139,7 @@ function generatePerModuleTypesSource(routes) {
   const valid = routes.filter(({ name }) => {
     if (!name || /["'\\`\n\r]/.test(name)) {
       console.warn(
-        `[rsc-router] Skipping route with invalid name: ${JSON.stringify(name)}`
+        `[rango] Skipping route with invalid name: ${JSON.stringify(name)}`
       );
       return false;
     }
@@ -149,7 +149,7 @@ function generatePerModuleTypesSource(routes) {
   for (const { name, pattern, params, search } of valid) {
     if (deduped.has(name)) {
       console.warn(
-        `[rsc-router] Duplicate route name "${name}" \u2014 keeping first definition`
+        `[rango] Duplicate route name "${name}" \u2014 keeping first definition`
       );
       continue;
     }
@@ -186,7 +186,7 @@ ${objectBody}
 } as const;
 
 declare global {
-  namespace RSCRouter {
+  namespace Rango {
     interface GeneratedRouteMap extends Readonly<typeof NamedRoutes> {}
   }
 }
@@ -211,7 +211,7 @@ function findTsFiles(dir, filter) {
     entries = readdirSync(dir, { withFileTypes: true });
   } catch (err) {
     console.warn(
-      `[rsc-router] Failed to scan directory ${dir}: ${err.message}`
+      `[rango] Failed to scan directory ${dir}: ${err.message}`
     );
     return results;
   }
@@ -456,7 +456,7 @@ function buildCombinedRouteMapWithSearch(filePath, variableName, visited, diagno
   const realPath = resolve(filePath);
   const key = variableName ? `${realPath}:${variableName}` : realPath;
   if (visited.has(key)) {
-    console.warn(`[rsc-router] Circular include detected, skipping: ${key}`);
+    console.warn(`[rango] Circular include detected, skipping: ${key}`);
     return { routes: {}, searchSchemas: {} };
   }
   visited.add(key);
@@ -543,12 +543,12 @@ function writePerModuleRouteTypesForFile(filePath) {
     } else {
       routes = extractRoutesFromSource(source);
     }
-    const genPath = filePath.replace(/\.(tsx?)$/, ".gen.ts");
+    const genPath = filePath.replace(/\.(tsx?|jsx?)$/, ".gen.ts");
     if (routes.length === 0) {
       if (varNames.length > 0 && !existsSync2(genPath)) {
         writeFileSync(genPath, generatePerModuleTypesSource([]));
         console.log(
-          `[rsc-router] Generated route types (placeholder) -> ${genPath}`
+          `[rango] Generated route types (placeholder) -> ${genPath}`
         );
       }
       return;
@@ -557,11 +557,11 @@ function writePerModuleRouteTypesForFile(filePath) {
     const existing = existsSync2(genPath) ? readFileSync2(genPath, "utf-8") : null;
     if (existing !== genSource) {
       writeFileSync(genPath, genSource);
-      console.log(`[rsc-router] Generated route types -> ${genPath}`);
+      console.log(`[rango] Generated route types -> ${genPath}`);
     }
   } catch (err) {
     console.warn(
-      `[rsc-router] Failed to generate route types for ${filePath}: ${err.message}`
+      `[rango] Failed to generate route types for ${filePath}: ${err.message}`
     );
   }
 }
@@ -576,6 +576,75 @@ var init_per_module_writer = __esm({
   }
 });
 
+// src/build/route-types/source-scan.ts
+function isLineTerminator(ch) {
+  const c = ch.charCodeAt(0);
+  return c === 10 || c === 13 || c === 8232 || c === 8233;
+}
+function makeCodeClassifier(code) {
+  const n = code.length;
+  let i = 0;
+  let skipStart = -1;
+  let skipEnd = -1;
+  return (q) => {
+    if (q >= skipStart && q < skipEnd) return false;
+    while (i < n && i <= q) {
+      const c = code[i];
+      const d = i + 1 < n ? code[i + 1] : "";
+      let end = -1;
+      if (c === "/" && d === "/") {
+        let j = i + 2;
+        while (j < n && !isLineTerminator(code[j])) j++;
+        end = j;
+      } else if (c === "/" && d === "*") {
+        let j = i + 2;
+        while (j < n && !(code[j] === "*" && code[j + 1] === "/")) j++;
+        end = Math.min(n, j + 2);
+      } else if (c === '"' || c === "'" || c === "`") {
+        let j = i + 1;
+        while (j < n) {
+          if (code[j] === "\\") {
+            j += 2;
+            continue;
+          }
+          if (code[j] === c) {
+            j++;
+            break;
+          }
+          j++;
+        }
+        end = j;
+      }
+      if (end >= 0) {
+        if (q < end) {
+          skipStart = i;
+          skipEnd = end;
+          return false;
+        }
+        i = end;
+      } else {
+        i++;
+      }
+    }
+    return true;
+  };
+}
+function firstCodeMatchIndex(code, pattern) {
+  const inCode = makeCodeClassifier(code);
+  pattern.lastIndex = 0;
+  let m;
+  while ((m = pattern.exec(code)) !== null) {
+    if (inCode(m.index)) return m.index;
+    if (pattern.lastIndex <= m.index) pattern.lastIndex = m.index + 1;
+  }
+  return -1;
+}
+var init_source_scan = __esm({
+  "src/build/route-types/source-scan.ts"() {
+    "use strict";
+  }
+});
+
 // src/build/route-types/router-processing.ts
 import {
   readFileSync as readFileSync3,
@@ -612,7 +681,7 @@ function findRouterFilesRecursive(dir, filter, results) {
     entries = readdirSync2(dir, { withFileTypes: true });
   } catch (err) {
     console.warn(
-      `[rsc-router] Failed to scan directory ${dir}: ${err.message}`
+      `[rango] Failed to scan directory ${dir}: ${err.message}`
     );
     return;
   }
@@ -630,7 +699,7 @@ function findRouterFilesRecursive(dir, filter, results) {
     if (filter && !filter(fullPath)) continue;
     try {
       const source = readFileSync3(fullPath, "utf-8");
-      if (ROUTER_CALL_PATTERN.test(source)) {
+      if (ROUTER_CALL_PATTERN.test(source) && firstCodeMatchIndex(source, ROUTER_CALL_PATTERN_G) >= 0) {
         routerFilesInDir.push(fullPath);
       }
     } catch {
@@ -668,7 +737,7 @@ function findNestedRouterConflict(routerFiles) {
   }
   return null;
 }
-function formatNestedRouterConflictError(conflict, prefix = "[rsc-router]") {
+function formatNestedRouterConflictError(conflict, prefix = "[rango]") {
   return `${prefix} Nested router roots are not supported.
 Router root: ${conflict.ancestor}
 Nested router: ${conflict.nested}
@@ -764,19 +833,38 @@ function extractBasenameFromRouter(code) {
   visit(sourceFile);
   return result;
 }
-function applyBasenameToRoutes(result, basename2) {
+function applyBasenameToRoutes(result, basename) {
   const prefixed = {};
   for (const [name, pattern] of Object.entries(result.routes)) {
     if (pattern === "/") {
-      prefixed[name] = basename2;
-    } else if (basename2.endsWith("/") && pattern.startsWith("/")) {
-      prefixed[name] = basename2 + pattern.slice(1);
+      prefixed[name] = basename;
+    } else if (basename.endsWith("/") && pattern.startsWith("/")) {
+      prefixed[name] = basename + pattern.slice(1);
     } else {
-      prefixed[name] = basename2 + pattern;
+      prefixed[name] = basename + pattern;
     }
   }
   return { routes: prefixed, searchSchemas: result.searchSchemas };
 }
+function genFileTsPath(sourceFile) {
+  const base = pathBasename(sourceFile).replace(/\.(tsx?|jsx?)$/, "");
+  return join2(dirname2(sourceFile), `${base}.named-routes.gen.ts`);
+}
+function resolveSearchSchemas(publicRouteNames, runtimeSchemas, sourceFile) {
+  if (runtimeSchemas && Object.keys(runtimeSchemas).length > 0) {
+    return runtimeSchemas;
+  }
+  const staticParsed = buildCombinedRouteMapForRouterFile(sourceFile);
+  if (Object.keys(staticParsed.searchSchemas).length === 0) {
+    return runtimeSchemas;
+  }
+  const filtered = {};
+  for (const name of publicRouteNames) {
+    const schema = staticParsed.searchSchemas[name];
+    if (schema) filtered[name] = schema;
+  }
+  return Object.keys(filtered).length > 0 ? filtered : runtimeSchemas;
+}
 function buildCombinedRouteMapForRouterFile(routerFilePath) {
   let routerSource;
   try {
@@ -789,7 +877,7 @@ function buildCombinedRouteMapForRouterFile(routerFilePath) {
     return { routes: {}, searchSchemas: {} };
   }
   const rawBasename = extractBasenameFromRouter(routerSource);
-  const basename2 = rawBasename ? ("/" + rawBasename.replace(/^\/+|\/+$/g, "")).replace(/^\/$/, "") : void 0;
+  const basename = rawBasename ? ("/" + rawBasename.replace(/^\/+|\/+$/g, "")).replace(/^\/$/, "") : void 0;
   let result;
   if (extraction.kind === "inline") {
     result = buildCombinedRouteMapWithSearch(
@@ -814,8 +902,8 @@ function buildCombinedRouteMapForRouterFile(routerFilePath) {
       result = buildCombinedRouteMapWithSearch(routerFilePath, extraction.name);
     }
   }
-  if (basename2) {
-    result = applyBasenameToRoutes(result, basename2);
+  if (basename) {
+    result = applyBasenameToRoutes(result, basename);
   }
   return result;
 }
@@ -897,7 +985,7 @@ function writeCombinedRouteTypes(root, knownRouterFiles, opts) {
     if (existsSync3(oldCombinedPath)) {
       unlinkSync(oldCombinedPath);
       console.log(
-        `[rsc-router] Removed stale combined route types: ${oldCombinedPath}`
+        `[rango] Removed stale combined route types: ${oldCombinedPath}`
       );
     }
   } catch {
@@ -919,18 +1007,12 @@ function writeCombinedRouteTypes(root, knownRouterFiles, opts) {
       }
       if (!extractUrlsFromRouter(routerSource)) continue;
     }
-    const routerBasename = pathBasename(routerFilePath).replace(
-      /\.(tsx?|jsx?)$/,
-      ""
-    );
-    const outPath = join2(
-      dirname2(routerFilePath),
-      `${routerBasename}.named-routes.gen.ts`
-    );
+    const outPath = genFileTsPath(routerFilePath);
     const existing = existsSync3(outPath) ? readFileSync3(outPath, "utf-8") : null;
     if (Object.keys(result.routes).length === 0) {
       if (!existing) {
         const emptySource = generateRouteTypesSource({});
+        opts?.onWrite?.(outPath, emptySource);
         writeFileSync2(outPath, emptySource);
       }
       continue;
@@ -950,22 +1032,25 @@ function writeCombinedRouteTypes(root, knownRouterFiles, opts) {
           continue;
         }
       }
+      opts?.onWrite?.(outPath, source);
       writeFileSync2(outPath, source);
       console.log(
-        `[rsc-router] Generated route types (${Object.keys(result.routes).length} routes) -> ${outPath}`
+        `[rango] Generated route types (${Object.keys(result.routes).length} routes) -> ${outPath}`
       );
     }
   }
 }
-var ROUTER_CALL_PATTERN;
+var ROUTER_CALL_PATTERN, ROUTER_CALL_PATTERN_G;
 var init_router_processing = __esm({
   "src/build/route-types/router-processing.ts"() {
     "use strict";
     init_codegen();
+    init_source_scan();
     init_include_resolution();
     init_per_module_writer();
     init_route_name();
     ROUTER_CALL_PATTERN = /\bcreateRouter\s*[<(]/;
+    ROUTER_CALL_PATTERN_G = /\bcreateRouter\s*[<(]/g;
   }
 });
 
@@ -1003,7 +1088,7 @@ import {
 import { createElement, StrictMode } from "react";
 import { hydrateRoot } from "react-dom/client";
 import { rscStream } from "@rangojs/router/internal/deps/html-stream-client";
-import { initBrowserApp, RSCRouter } from "@rangojs/router/browser";
+import { initBrowserApp, Rango } from "@rangojs/router/browser";
 
 async function initializeApp() {
   const deps = {
@@ -1018,7 +1103,7 @@ async function initializeApp() {
 
   hydrateRoot(
     document,
-    createElement(StrictMode, null, createElement(RSCRouter))
+    createElement(StrictMode, null, createElement(Rango))
   );
 }
 
@@ -1050,7 +1135,8 @@ export const renderHTML = createSSRHandler({
 // src/vite/plugins/version-plugin.ts
 var version_plugin_exports = {};
 __export(version_plugin_exports, {
-  createVersionPlugin: () => createVersionPlugin
+  createVersionPlugin: () => createVersionPlugin,
+  isViteDepCachePath: () => isViteDepCachePath
 });
 import { parseAst } from "vite";
 function isCodeModule(id) {
@@ -1062,7 +1148,7 @@ function normalizeModuleId(id) {
 function getClientModuleSignature(source) {
   let program;
   try {
-    program = parseAst(source, { jsx: true });
+    program = parseAst(source, { lang: "tsx" });
   } catch {
     return void 0;
   }
@@ -1145,11 +1231,12 @@ function createVersionPlugin() {
   let currentVersion = buildVersion;
   let isDev = false;
   let server = null;
+  let resolvedCacheDir;
   const clientModuleSignatures = /* @__PURE__ */ new Map();
   let versionCounter = 0;
   const bumpVersion = (reason) => {
     currentVersion = Date.now().toString(16) + String(++versionCounter);
-    console.log(`[rsc-router] ${reason}, version updated: ${currentVersion}`);
+    console.log(`[rango] ${reason}, version updated: ${currentVersion}`);
     const rscEnv = server?.environments?.rsc;
     const versionMod = rscEnv?.moduleGraph?.getModuleById(
       "\0" + VIRTUAL_IDS.version
@@ -1163,6 +1250,7 @@ function createVersionPlugin() {
     enforce: "pre",
     configResolved(config) {
       isDev = config.command === "serve";
+      resolvedCacheDir = config.cacheDir ? String(config.cacheDir).replace(/\\/g, "/") : void 0;
     },
     configureServer(devServer) {
       server = devServer;
@@ -1204,6 +1292,7 @@ function createVersionPlugin() {
       if (!isDev) return;
       const isRscModule = this.environment?.name === "rsc";
       if (!isRscModule) return;
+      if (isViteDepCachePath(ctx.file, resolvedCacheDir)) return;
       if (ctx.modules.length === 1 && ctx.modules[0].id === "\0" + VIRTUAL_IDS.version) {
         return;
       }
@@ -1233,6 +1322,17 @@ function createVersionPlugin() {
     }
   };
 }
+function isViteDepCachePath(filePath, cacheDir) {
+  if (!filePath) return false;
+  const normalized = filePath.replace(/\\/g, "/");
+  if (cacheDir) {
+    const normalizedCacheDir = cacheDir.replace(/\\/g, "/").replace(/\/+$/, "");
+    if (normalized === normalizedCacheDir || normalized.startsWith(normalizedCacheDir + "/")) {
+      return true;
+    }
+  }
+  return /\/node_modules\/\.vite[^/]*\//.test(normalized) || normalized.includes("/.vite-isolated/");
+}
 var init_version_plugin = __esm({
   "src/vite/plugins/version-plugin.ts"() {
     "use strict";
@@ -1278,7 +1378,7 @@ var runtime_discovery_exports = {};
 __export(runtime_discovery_exports, {
   discoverAndWriteRouteTypes: () => discoverAndWriteRouteTypes
 });
-import { dirname as dirname3, join as join3, basename, resolve as resolve3 } from "node:path";
+import { resolve as resolve3 } from "node:path";
 import { existsSync as existsSync4, readFileSync as readFileSync4, writeFileSync as writeFileSync3 } from "node:fs";
 async function discoverAndWriteRouteTypes(opts) {
   let createViteServer;
@@ -1388,22 +1488,12 @@ This means createRouter() stack trace parsing matched an internal frame.
 Set an explicit \`id\` on createRouter() or check the call site.`
         );
       }
-      if (!routeSearchSchemas || Object.keys(routeSearchSchemas).length === 0) {
-        const staticParsed = buildCombinedRouteMapForRouterFile(sourceFile);
-        if (Object.keys(staticParsed.searchSchemas).length > 0) {
-          const filtered = {};
-          for (const name of Object.keys(routeManifest)) {
-            const schema = staticParsed.searchSchemas[name];
-            if (schema) filtered[name] = schema;
-          }
-          if (Object.keys(filtered).length > 0) {
-            routeSearchSchemas = filtered;
-          }
-        }
-      }
-      const routerDir = dirname3(sourceFile);
-      const routerBasename = basename(sourceFile).replace(/\.(tsx?|jsx?)$/, "");
-      const outPath = join3(routerDir, `${routerBasename}.named-routes.gen.ts`);
+      routeSearchSchemas = resolveSearchSchemas(
+        Object.keys(routeManifest),
+        routeSearchSchemas,
+        sourceFile
+      );
+      const outPath = genFileTsPath(sourceFile);
       const source = generateRouteTypesSource(
         routeManifest,
         routeSearchSchemas && Object.keys(routeSearchSchemas).length > 0 ? routeSearchSchemas : void 0
@@ -1440,7 +1530,7 @@ var init_runtime_discovery = __esm({
 
 // src/bin/rango.ts
 init_generate_route_types();
-import { resolve as resolve4, dirname as dirname4 } from "node:path";
+import { resolve as resolve4, dirname as dirname3 } from "node:path";
 import { readFileSync as readFileSync5, statSync, existsSync as existsSync5 } from "node:fs";
 var [command, ...rawArgs] = process.argv.slice(2);
 if (command === "generate") {
@@ -1511,12 +1601,12 @@ Examples:
   );
 }
 function findProjectRoot(fromPath) {
-  let dir = dirname4(resolve4(fromPath));
-  while (dir !== dirname4(dir)) {
+  let dir = dirname3(resolve4(fromPath));
+  while (dir !== dirname3(dir)) {
     if (existsSync5(resolve4(dir, "package.json")) || existsSync5(resolve4(dir, "vite.config.ts")) || existsSync5(resolve4(dir, "vite.config.js"))) {
       return dir;
     }
-    dir = dirname4(dir);
+    dir = dirname3(dir);
   }
   return process.cwd();
 }

package/dist/testing/vitest.js

@@ -0,0 +1,48 @@
+// src/testing/vitest.ts
+import { fileURLToPath } from "node:url";
+function here(relativeFromRoot) {
+  return fileURLToPath(new URL(`../../${relativeFromRoot}`, import.meta.url));
+}
+function rangoTestAliases(opts = {}) {
+  const aliases = [
+    // Real impls (index.rsc.ts) for the bare specifier ONLY — exact regex so
+    // subpaths (/testing, /client, /cache, ...) are untouched. React stays the
+    // client build, so createContext and "use client" modules work.
+    { find: /^@rangojs\/router$/, replacement: here("src/index.rsc.ts") },
+    {
+      find: "@rangojs/router:version",
+      replacement: here("src/testing/vitest-stubs/version.ts")
+    },
+    {
+      find: /^@vitejs\/plugin-rsc\/rsc$/,
+      replacement: here("src/testing/vitest-stubs/plugin-rsc.ts")
+    }
+  ];
+  if (opts.cloudflare) {
+    aliases.push(
+      {
+        find: "cloudflare:workers",
+        replacement: here("src/testing/vitest-stubs/cloudflare-workers.ts")
+      },
+      {
+        find: "cloudflare:email",
+        replacement: here("src/testing/vitest-stubs/cloudflare-email.ts")
+      }
+    );
+  }
+  return aliases;
+}
+var rangoInlineDeps = [/@rangojs[/\\]router/];
+function rangoTestConfig(opts = {}) {
+  return {
+    alias: rangoTestAliases(opts),
+    // fresh copy so the shared rangoInlineDeps const is never aliased into (or
+    // mutated through) a consumer's resolved config
+    server: { deps: { inline: [...rangoInlineDeps] } }
+  };
+}
+export {
+  rangoInlineDeps,
+  rangoTestAliases,
+  rangoTestConfig
+};