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

package/README.md

@@ -21,6 +21,12 @@ Named-route RSC router with structural composability and type-safe partial rende
 - **Trailing slash control** — Per-route canonical URLs with `"never"`, `"always"`, or `"ignore"`
 - **CLI codegen** — `rango generate` for route type generation
 
+## Design Docs
+
+- [Execution model](./docs/internal/execution-model.md)
+- [Semantic change checklist](./docs/internal/semantic-change-checklist.md)
+- [Stability roadmap](./docs/internal/stability-roadmap.md)
+
 ## Installation
 
 ```bash
@@ -417,10 +423,10 @@ import { useLoader } from "@rangojs/router/client";
 import { BlogSidebarLoader } from "./loaders/blog";
 
 function BlogSidebar() {
-  const { posts } = useLoader(BlogSidebarLoader);
+  const { data } = useLoader(BlogSidebarLoader);
   return (
     <ul>
-      {posts.map((p) => (
+      {data.posts.map((p) => (
         <li key={p.slug}>{p.title}</li>
       ))}
     </ul>
@@ -482,7 +488,7 @@ function Nav() {
   return (
     <nav>
       <Link to={href("/")}>Home</Link>
-      <Link to={href("/blog")} prefetch="intent">
+      <Link to={href("/blog")} prefetch="hybrid">
         Blog
       </Link>
       <Link to={href("/about")}>About</Link>
@@ -493,20 +499,21 @@ function Nav() {
 
 `href()` validates that the path matches a registered route pattern at compile time (e.g. `/blog/my-post` matches `/blog/:slug`).
 
-### Navigation Hook
+### Navigation Hooks
 
 ```tsx
 "use client";
-import { useNavigation } from "@rangojs/router/client";
+import { useNavigation, useRouter } from "@rangojs/router/client";
 
 function SearchForm() {
-  const { navigate, isPending } = useNavigation();
+  const router = useRouter();
+  const nav = useNavigation();
 
   function handleSubmit(query: string) {
-    navigate(`/search?q=${encodeURIComponent(query)}`);
+    router.push(`/search?q=${encodeURIComponent(query)}`);
   }
 
-  return <form onSubmit={...}>{isPending && <Spinner />}</form>;
+  return <form onSubmit={...}>{nav.state !== "idle" && <Spinner />}</form>;
 }
 ```
 
@@ -554,6 +561,20 @@ export const urlpatterns = urls(({ path, include }) => [
 
 Included route names are prefixed with the include name: `reverse("api.health")`, `reverse("api.products")`.
 
+### Include name scoping
+
+The `name` option controls how child route names appear globally:
+
+| Form                               | Child names         | Generated types        | Reverse resolution                                                   |
+| ---------------------------------- | ------------------- | ---------------------- | -------------------------------------------------------------------- |
+| `include("/x", p, { name: "ns" })` | `ns.child`          | Exported as `ns.child` | `reverse("ns.child")` globally, `reverse(".child")` inside           |
+| `include("/x", p, { name: "" })`   | `child` (flattened) | Exported as-is         | `reverse("child")` globally, `reverse(".child")` inside (root-scope) |
+| `include("/x", p)`                 | Private scope       | Not exported           | `reverse(".child")` inside only                                      |
+
+Without a `name`, included routes are local to the mounted module. They still match requests and render normally, but their names are hidden from the generated route map and cannot be reversed globally. Use `{ name: "" }` to merge children into the parent namespace without adding a prefix.
+
+**`{ name: "" }` is flattening, not isolation.** Flattened routes behave as if defined inline at the include site — dot-local reverse (`.name`) can reach any sibling route at root scope, including routes from other `{ name: "" }` mounts. If you need module-level isolation, omit the `name` option or use a namespace.
+
 ## Middleware
 
 ```tsx
@@ -680,6 +701,23 @@ export const ProductPage = Prerender(
 
 With `passthrough: true`, known params are served from the build-time cache and unknown params fall through to live rendering.
 
+Handlers can also skip individual param sets with `ctx.passthrough()`, deferring them to the live handler at runtime:
+
+```tsx
+export const ProductPage = Prerender(
+  async () => {
+    const all = await db.getAllProducts();
+    return all.map((p) => ({ id: p.id }));
+  },
+  async (ctx) => {
+    const product = await db.getProduct(ctx.params.id);
+    if (!product.published) return ctx.passthrough();
+    return <Product data={product} />;
+  },
+  { passthrough: true },
+);
+```
+
 ## Theme
 
 ### Router Configuration

package/dist/bin/rango.js

@@ -119,6 +119,21 @@ var init_ast_route_extraction = __esm({
   }
 });
 
+// src/route-name.ts
+function isAutoGeneratedRouteName(name) {
+  return name.split(".").some((segment) => {
+    return segment.startsWith(AUTO_GENERATED_ROUTE_PREFIX) || segment.startsWith(INTERNAL_INCLUDE_SCOPE_PREFIX);
+  });
+}
+var AUTO_GENERATED_ROUTE_PREFIX, INTERNAL_INCLUDE_SCOPE_PREFIX;
+var init_route_name = __esm({
+  "src/route-name.ts"() {
+    "use strict";
+    AUTO_GENERATED_ROUTE_PREFIX = "$path_";
+    INTERNAL_INCLUDE_SCOPE_PREFIX = "$prefix_";
+  }
+});
+
 // src/build/route-types/codegen.ts
 function generatePerModuleTypesSource(routes) {
   const valid = routes.filter(({ name }) => {
@@ -153,13 +168,16 @@ export type routes = typeof routes;
 `;
 }
 function generateRouteTypesSource(routeManifest, searchSchemas) {
-  const entries = Object.entries(routeManifest).sort(
-    ([a], [b]) => a.localeCompare(b)
-  );
+  const entries = Object.entries(routeManifest).filter(([name]) => !isAutoGeneratedRouteName(name)).sort(([a], [b]) => a.localeCompare(b));
+  const filteredSearchSchemas = searchSchemas ? Object.fromEntries(
+    Object.entries(searchSchemas).filter(
+      ([name]) => !isAutoGeneratedRouteName(name)
+    )
+  ) : void 0;
   const objectBody = entries.map(([name, pattern]) => {
     const key = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name) ? name : `"${name}"`;
     const params = extractParamsFromPattern(pattern);
-    const search = searchSchemas?.[name];
+    const search = filteredSearchSchemas?.[name];
     return formatRouteEntry(key, pattern, params, search);
   }).join("\n");
   return `// Auto-generated by @rangojs/router - do not edit
@@ -178,6 +196,7 @@ var init_codegen = __esm({
   "src/build/route-types/codegen.ts"() {
     "use strict";
     init_param_extraction();
+    init_route_name();
   }
 });
 
@@ -410,6 +429,9 @@ function buildRouteMapFromBlock(block, fullSource, filePath, visited, searchSche
         diagnosticsOut
       );
     }
+    if (namePrefix === null) {
+      continue;
+    }
     for (const [name, pattern] of Object.entries(childResult.routes)) {
       const prefixedName = namePrefix ? `${namePrefix}.${name}` : name;
       let prefixedPattern;
@@ -460,6 +482,7 @@ function buildCombinedRouteMapWithSearch(filePath, variableName, visited, diagno
     searchSchemas,
     diagnosticsOut
   );
+  visited.delete(key);
   return { routes, searchSchemas };
 }
 var init_include_resolution = __esm({
@@ -517,8 +540,16 @@ function writePerModuleRouteTypesForFile(filePath) {
     } else {
       routes = extractRoutesFromSource(source);
     }
-    if (routes.length === 0) return;
     const genPath = filePath.replace(/\.(tsx?)$/, ".gen.ts");
+    if (routes.length === 0) {
+      if (varNames.length > 0 && !existsSync2(genPath)) {
+        writeFileSync(genPath, generatePerModuleTypesSource([]));
+        console.log(
+          `[rsc-router] Generated route types (placeholder) -> ${genPath}`
+        );
+      }
+      return;
+    }
     const genSource = generatePerModuleTypesSource(routes);
     const existing = existsSync2(genPath) ? readFileSync2(genPath, "utf-8") : null;
     if (existing !== genSource) {
@@ -546,6 +577,17 @@ var init_per_module_writer = __esm({
 import { readFileSync as readFileSync3, writeFileSync as writeFileSync2, existsSync as existsSync3, unlinkSync } from "node:fs";
 import { join as join2, dirname as dirname2, resolve as resolve2, basename as pathBasename } from "node:path";
 import ts5 from "typescript";
+function countPublicRouteEntries(source) {
+  const matches = source.matchAll(/^\s+(?:"([^"]+)"|([a-zA-Z_$][^:]*)):\s*["{]/gm) ?? [];
+  let count = 0;
+  for (const match of matches) {
+    const routeName = match[1] || match[2];
+    if (routeName && !isAutoGeneratedRouteName(routeName.trim())) {
+      count++;
+    }
+  }
+  return count;
+}
 function extractUrlsVariableFromRouter(code) {
   const sourceFile = ts5.createSourceFile(
     "router.tsx",
@@ -652,6 +694,22 @@ function detectUnresolvableIncludes(routerFilePath) {
   );
   return diagnostics;
 }
+function detectUnresolvableIncludesForUrlsFile(filePath) {
+  const realPath = resolve2(filePath);
+  let source;
+  try {
+    source = readFileSync3(realPath, "utf-8");
+  } catch {
+    return [];
+  }
+  const varNames = findUrlsVariableNames(source);
+  if (varNames.length === 0) return [];
+  const diagnostics = [];
+  for (const varName of varNames) {
+    buildCombinedRouteMapWithSearch(realPath, varName, /* @__PURE__ */ new Set(), diagnostics);
+  }
+  return diagnostics;
+}
 function findRouterFiles(root, filter) {
   const files = findTsFiles(root, filter);
   const result = [];
@@ -725,8 +783,10 @@ function writeCombinedRouteTypes(root, knownRouterFiles, opts) {
     );
     if (existing !== source) {
       if (opts?.preserveIfLarger && existing) {
-        const existingCount = (existing.match(/^\s+["a-zA-Z_$][^:]*:\s*["{]/gm) || []).length;
-        const newCount = Object.keys(result.routes).length;
+        const existingCount = countPublicRouteEntries(existing);
+        const newCount = Object.keys(result.routes).filter(
+          (name) => !isAutoGeneratedRouteName(name)
+        ).length;
         if (existingCount > newCount) {
           continue;
         }
@@ -744,6 +804,8 @@ var init_router_processing = __esm({
     init_codegen();
     init_scan_filter();
     init_include_resolution();
+    init_per_module_writer();
+    init_route_name();
   }
 });
 
@@ -758,6 +820,7 @@ var init_generate_route_types = __esm({
     init_per_module_writer();
     init_include_resolution();
     init_router_processing();
+    init_per_module_writer();
   }
 });
 
@@ -1139,7 +1202,13 @@ async function discoverAndWriteRouteTypes(opts) {
       if (!router.urlpatterns) continue;
       const manifest = generateManifest(router.urlpatterns, routerMountIndex);
       routerMountIndex++;
-      const routeManifest = manifest.routeManifest;
+      const rawManifest = manifest.routeManifest;
+      const routeManifest = {};
+      for (const [name, pattern] of Object.entries(rawManifest)) {
+        if (!isAutoGeneratedRouteName(name)) {
+          routeManifest[name] = pattern;
+        }
+      }
       let routeSearchSchemas = manifest.routeSearchSchemas;
       const sourceFile = router.__sourceFile;
       if (!sourceFile) {
@@ -1201,6 +1270,7 @@ var init_runtime_discovery = __esm({
   "src/build/runtime-discovery.ts"() {
     "use strict";
     init_generate_route_types();
+    init_route_name();
   }
 });
 
@@ -1305,16 +1375,15 @@ function runStaticGeneration(args, mode) {
     process.exit(0);
   }
   const routerFiles = [];
+  const urlsFiles = [];
   for (const filePath of files) {
     try {
       const source = readFileSync5(filePath, "utf-8");
-      const isRouter = /\bcreateRouter\s*[<(]/.test(source);
-      const isUrls = source.includes("urls(");
-      if (isRouter) {
+      if (/\bcreateRouter\s*[<(]/.test(source)) {
         routerFiles.push(filePath);
       }
-      if (isUrls) {
-        writePerModuleRouteTypesForFile(filePath);
+      if (source.includes("urls(")) {
+        urlsFiles.push(filePath);
       }
     } catch (err) {
       console.warn(
@@ -1329,21 +1398,39 @@ function runStaticGeneration(args, mode) {
       allDiagnostics.push({ ...d, routerFile });
     }
   }
-  if (allDiagnostics.length > 0 && mode === "default") {
+  const routerFileSet = new Set(routerFiles);
+  for (const urlsFile of urlsFiles) {
+    if (routerFileSet.has(urlsFile)) continue;
+    const diagnostics = detectUnresolvableIncludesForUrlsFile(urlsFile);
+    for (const d of diagnostics) {
+      allDiagnostics.push({ ...d, routerFile: urlsFile });
+    }
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const uniqueDiagnostics = allDiagnostics.filter((d) => {
+    const key = `${d.sourceFile}:${d.pathPrefix}:${d.reason}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+  if (uniqueDiagnostics.length > 0 && mode === "default") {
     console.error("\n[rango] Unresolvable includes detected:\n");
-    formatDiagnostics(allDiagnostics);
+    formatDiagnostics(uniqueDiagnostics);
     console.error(
       "\nThe static parser cannot resolve these includes because they use factory functions or dynamic expressions.\n\nOptions:\n  rango generate <path> --runtime   Use Vite-based discovery (requires vite)\n  rango generate <path> --static    Accept partial output (missing routes above)\n"
     );
     process.exit(1);
   }
-  if (allDiagnostics.length > 0 && mode === "static") {
+  if (uniqueDiagnostics.length > 0 && mode === "static") {
     console.warn(
       "\n[rango] Warning: partial output (unresolvable includes):\n"
     );
-    formatDiagnostics(allDiagnostics);
+    formatDiagnostics(uniqueDiagnostics);
     console.warn("");
   }
+  for (const urlsFile of urlsFiles) {
+    writePerModuleRouteTypesForFile(urlsFile);
+  }
   for (const routerFile of routerFiles) {
     const projectRoot = findProjectRoot(routerFile);
     writeCombinedRouteTypes(projectRoot, [routerFile]);
@@ -1398,8 +1485,8 @@ async function runRuntimeDiscovery(args, configFile) {
     }
     process.exit(1);
   }
-  const projectRoot = findProjectRoot(routerEntries[0]);
   for (const entry of routerEntries) {
+    const projectRoot = findProjectRoot(entry);
     const result = await discoverAndWriteRouteTypes2({
       root: projectRoot,
       configFile,