@rangojs/router 0.0.0-experimental.13 → 0.0.0-experimental.14

package/dist/vite/index.js

@@ -20,34 +20,6 @@ function extractRoutesFromSource(code) {
   }
   return routes;
 }
-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)}`);
-      return false;
-    }
-    return true;
-  });
-  const deduped = /* @__PURE__ */ new Map();
-  for (const { name, pattern, search } of valid) {
-    deduped.set(name, { pattern, search });
-  }
-  const sorted = [...deduped.entries()].sort(([a], [b]) => a.localeCompare(b));
-  const body = sorted.map(([name, { pattern, search }]) => {
-    const key = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name) ? name : `"${name}"`;
-    if (search && Object.keys(search).length > 0) {
-      const searchBody = Object.entries(search).map(([k, v]) => `${k}: "${v}"`).join(", ");
-      return `  ${key}: { path: "${pattern}", search: { ${searchBody} } },`;
-    }
-    return `  ${key}: "${pattern}",`;
-  }).join("\n");
-  return `// Auto-generated by @rangojs/router - do not edit
-export const routes = {
-${body}
-} as const;
-export type routes = typeof routes;
-`;
-}
 function isWhitespace(ch) {
   return ch === " " || ch === "	" || ch === "\n" || ch === "\r";
 }
@@ -299,29 +271,6 @@ function findTsFiles(dir, filter) {
   }
   return results;
 }
-function writePerModuleRouteTypes(root, filter) {
-  const files = findTsFiles(root, filter);
-  for (const filePath of files) {
-    writePerModuleRouteTypesForFile(filePath);
-  }
-}
-function writePerModuleRouteTypesForFile(filePath) {
-  try {
-    const source = readFileSync(filePath, "utf-8");
-    if (!source.includes("urls(")) return;
-    const routes = extractRoutesFromSource(source);
-    if (routes.length === 0) return;
-    const genPath = filePath.replace(/\.(tsx?)$/, ".gen.ts");
-    const genSource = generatePerModuleTypesSource(routes);
-    const existing = existsSync(genPath) ? readFileSync(genPath, "utf-8") : null;
-    if (existing !== genSource) {
-      writeFileSync(genPath, genSource);
-      console.log(`[rsc-router] Generated route types -> ${genPath}`);
-    }
-  } catch (err) {
-    console.warn(`[rsc-router] Failed to generate route types for ${filePath}: ${err.message}`);
-  }
-}
 function extractIncludesFromSource(code) {
   const results = [];
   const regex = /\binclude\s*\(/g;
@@ -1984,7 +1933,7 @@ import { resolve as resolve2 } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.0.0-experimental.13",
+  version: "0.0.0-experimental.14",
   type: "module",
   description: "Django-inspired RSC router with composable URL patterns",
   author: "Ivo Todorov",
@@ -2717,7 +2666,6 @@ Set an explicit \`id\` on createRouter() or check the call site.`
         });
       }
       if (opts?.staticRouteTypesGeneration !== false) {
-        writePerModuleRouteTypes(projectRoot, scanFilter);
         cachedRouterFiles = findRouterFiles(projectRoot, scanFilter);
         writeCombinedRouteTypes(projectRoot, cachedRouterFiles, { preserveIfLarger: true });
       }
@@ -2870,9 +2818,6 @@ ${err.stack}`
             const hasUrls = source.includes("urls(");
             const hasCreateRouter = /\bcreateRouter\s*[<(]/.test(source);
             if (!hasUrls && !hasCreateRouter) return;
-            if (hasUrls) {
-              writePerModuleRouteTypesForFile(filePath);
-            }
             if (hasCreateRouter) {
               cachedRouterFiles = void 0;
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.13",
+  "version": "0.0.0-experimental.14",
   "type": "module",
   "description": "Django-inspired RSC router with composable URL patterns",
   "author": "Ivo Todorov",

package/skills/rango/SKILL.md

@@ -30,6 +30,7 @@ Django-inspired RSC router with composable URL patterns, type-safe href, and ser
 | `/response-routes` | JSON/text/HTML/XML/stream endpoints with `path.json()`, `path.text()` |
 | `/mime-routes` | Content negotiation — same URL, different response types via Accept header |
 | `/fonts` | Load web fonts with preload hints |
+| `/testing` | Unit test route trees with `buildRouteTree()` |
 
 ## Quick Start
 

package/skills/testing/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: testing
+description: Unit test route trees with buildRouteTree()
+argument-hint:
+---
+
+# Route Tree Unit Testing
+
+Unit test route definitions by inspecting the route tree, segment IDs, middleware, intercepts, loaders, and pattern matching without running a dev server.
+
+## Setup
+
+The `buildRouteTree` helper lives in `src/__tests__/helpers/route-tree.ts` (not shipped with npm). Import it in your test files:
+
+```typescript
+import { buildRouteTree } from "./helpers/route-tree.js";
+```
+
+## buildRouteTree(urlPatterns)
+
+Takes a `urls()` result and returns a `RouteTree` with inspection methods:
+
+```typescript
+import { urls } from "@rangojs/router";
+import { buildRouteTree } from "./helpers/route-tree.js";
+
+const tree = buildRouteTree(
+  urls(({ path, layout, middleware, loader, intercept, when }) => [
+    layout(RootLayout, () => [
+      middleware(authMiddleware),
+      path("/", HomePage, { name: "home" }),
+      path("/blog/:slug", BlogPost, { name: "blog.post" }, () => [
+        loader(PostLoader),
+      ]),
+    ]),
+  ])
+);
+```
+
+## RouteTree API
+
+### Route Patterns
+
+```typescript
+tree.routes()       // { home: "/", "blog.post": "/blog/:slug" }
+tree.routeNames()   // ["home", "blog.post"]
+```
+
+### URL Matching
+
+```typescript
+const m = tree.match("/blog/hello");
+m.routeKey  // "blog.post"
+m.params    // { slug: "hello" }
+
+tree.match("/nonexistent")  // null
+```
+
+### Segment IDs
+
+```typescript
+tree.segmentId("home")       // "M0L0L0R0"
+tree.segmentIds()            // { home: "M0L0L0R0", "blog.post": "M0L0L0R1" }
+tree.segmentPath("blog.post")
+// [
+//   { id: "M0L0",     type: "layout" },  // synthetic root
+//   { id: "M0L0L0",   type: "layout" },  // RootLayout
+//   { id: "M0L0L0R1", type: "route", pattern: "/blog/:slug" },
+// ]
+```
+
+### Entry Access
+
+```typescript
+tree.entry("blog.post")                   // EntryData
+tree.entry("blog.post")!.parent!.type     // "layout"
+tree.entryByPattern("/blog/:slug")        // EntryData (lookup by URL pattern)
+```
+
+### Middleware
+
+```typescript
+tree.hasMiddleware("home")                // true (inherited from layout)
+tree.middleware("home")                   // [authMiddleware] (direct only)
+tree.middlewareChain("home")
+// [{ segmentId: "M0L0L0", count: 1 }]   // all middleware root-to-route
+```
+
+### Loaders
+
+```typescript
+tree.hasLoaders("blog.post")  // true
+tree.loaders("blog.post")     // [LoaderEntry { loader, revalidate, cache? }]
+```
+
+### Intercepts
+
+```typescript
+tree.intercepts("home")
+// [{ slotName: "@modal", routeName: "card", hasWhen: true, whenCount: 1, hasLoader: false, hasMiddleware: false }]
+tree.interceptEntries("home")  // raw InterceptEntry[]
+```
+
+### Parallel Slots
+
+```typescript
+tree.parallelSlots("home")       // EntryData[] of type="parallel"
+tree.parallelSlotNames("home")   // ["@sidebar", "@main"]
+```
+
+### Boundaries
+
+```typescript
+tree.hasErrorBoundary("home")      // boolean
+tree.hasNotFoundBoundary("home")   // boolean
+```
+
+### Cache & Loading
+
+```typescript
+tree.hasCache("home")     // boolean
+tree.hasLoading("home")   // boolean
+```
+
+### Debug
+
+```typescript
+console.log(tree.debug());
+// Route Tree:
+//   home: / [M0L0L0R0] (M0L0 > M0L0L0 > M0L0L0R0) {mw:1}
+//   blog.post: /blog/:slug [M0L0L0R1] (M0L0 > M0L0L0 > M0L0L0R1) {mw:1, ld:1}
+```
+
+## Segment ID Format
+
+| Prefix | Meaning |
+|--------|---------|
+| `M0`   | Mount index (router instance) |
+| `L`    | Layout |
+| `R`    | Route |
+| `P`    | Parallel slot |
+| `D`    | Loader (data) |
+| `C`    | Cache boundary |
+
+Example: `M0L0L0R1` = mount 0, synthetic root layout, user layout, second route.
+
+## Examples
+
+### include() with prefix
+
+```typescript
+const blogPatterns = urls(({ path }) => [
+  path("/", BlogIndex, { name: "index" }),
+  path("/:slug", BlogPost, { name: "post" }),
+]);
+
+const tree = buildRouteTree(
+  urls(({ path, include }) => [
+    path("/", HomePage, { name: "home" }),
+    include("/blog", blogPatterns, { name: "blog" }),
+  ])
+);
+
+expect(tree.routes()).toEqual({
+  home: "/",
+  "blog.index": "/blog",
+  "blog.post": "/blog/:slug",
+});
+```
+
+### Middleware chain
+
+```typescript
+const authMw = async (ctx, next) => next();
+const logMw = async (ctx, next) => next();
+
+const tree = buildRouteTree(
+  urls(({ path, layout, middleware }) => [
+    layout(RootLayout, () => [
+      middleware(logMw),
+      layout(AuthLayout, () => [
+        middleware(authMw),
+        path("/dashboard", Dashboard, { name: "dashboard" }),
+      ]),
+    ]),
+  ])
+);
+
+expect(tree.middlewareChain("dashboard")).toEqual([
+  { segmentId: "M0L0L0", count: 1 },   // logMw on RootLayout
+  { segmentId: "M0L0L0L0", count: 1 }, // authMw on AuthLayout
+]);
+```
+
+### Intercepts with when()
+
+```typescript
+const tree = buildRouteTree(
+  urls(({ path, layout, intercept, when }) => [
+    layout(ShopLayout, () => [
+      path("/products", ProductList, { name: "products" }),
+      path("/products/:id", ProductDetail, { name: "product.detail" }),
+      intercept("@modal", "product.detail", ProductModal, () => [
+        when((ctx) => ctx.from.pathname.startsWith("/products")),
+      ]),
+    ]),
+  ])
+);
+
+const intercepts = tree.intercepts("products");
+// Note: intercepts are on the parent where intercept() is called
+```
+
+### Constrained parameters
+
+```typescript
+const tree = buildRouteTree(
+  urls(({ path }) => [
+    path("/:locale(en|fr)?/about", AboutPage, { name: "about" }),
+  ])
+);
+
+expect(tree.match("/about")).not.toBeNull();
+expect(tree.match("/fr/about")!.params).toEqual({ locale: "fr" });
+expect(tree.match("/de/about")).toBeNull();
+```

package/skills/typesafety/SKILL.md

@@ -45,22 +45,35 @@ export const urlpatterns = urls(({ path, layout }) => [
 
 ## Type-Safe href()
 
-### Server: ctx.reverse + scopedReverse
+### Server: ctx.reverse with global route names
 
-In route handlers, use `scopedReverse()` for local route name autocomplete:
+In route handlers, use `ctx.reverse()` with the global dotted route names
+from `router.named-routes.gen.ts`:
 
 ```typescript
-import { scopedReverse } from "@rangojs/router";
-
-path("/product/:slug", (ctx) => {
-  const reverse = scopedReverse<typeof shopPatterns>(ctx.reverse);
+import type { Handler } from "@rangojs/router";
 
-  reverse("cart");                        // Type-safe local name
-  reverse("product", { slug: "widget" }); // Type-safe with params
-  reverse("blog.post");                   // Absolute names always allowed
+export const ProductHandler: Handler<"shop.product"> = (ctx) => {
+  ctx.reverse("shop.cart");                       // Global name
+  ctx.reverse("shop.product", { slug: "widget" }); // With params
+  ctx.reverse("blog.post", { postId: "1" });       // Cross-module
 
   return <ProductPage slug={ctx.params.slug} />;
-}, { name: "product" })
+};
+```
+
+For opt-in per-module isolation (after running `npx rango generate urls/shop.tsx`),
+use `scopedReverse()` with a local route map:
+
+```typescript
+import { scopedReverse } from "@rangojs/router";
+import type { routes } from "./shop.gen.js";
+
+export const ProductHandler: Handler<"product", routes> = (ctx) => {
+  const reverse = scopedReverse<routes>(ctx.reverse);
+  reverse("cart");                        // Local name
+  reverse("product", { slug: "widget" }); // Local with params
+};
 ```
 
 ### Client: href + useHref
@@ -192,13 +205,14 @@ export const SearchPage: Handler<"search"> = (ctx) => {
 ```
 
 This avoids circular references because `Handler` defaults to `GeneratedRouteMap`
-(standalone gen file) instead of `RegisteredRoutes` (which depends on `router.tsx`).
+(from `router.named-routes.gen.ts`) instead of `RegisteredRoutes` (which depends on `router.tsx`).
 
-You can also pass an explicit route map if needed:
+You can also pass an explicit route map for per-module isolation (opt-in,
+after running `npx rango generate`):
 
 ```typescript
 import type { Handler } from "@rangojs/router";
-import type { routes } from "../urls.gen.js";
+import type { routes } from "./urls.gen.js";
 
 export const SearchPage: Handler<"search", routes> = (ctx) => { ... };
 ```
@@ -240,16 +254,15 @@ type P = RouteParams<"blogPost", routes>;
 
 ### Generated route types
 
-In the generated route types (`urls.gen.ts` and `GeneratedRouteMap`), routes with
-search schemas use `{ path, search }` objects:
+In the generated `router.named-routes.gen.ts`, routes with search schemas
+use `{ path, search }` objects:
 
 ```typescript
-// urls.gen.ts (auto-generated by `npx rango extract-names`)
-export const routes = {
-  search: { path: "/search", search: { q: "string", page: "number?", sort: "string?" } },
-  home: "/",  // No search schema -> plain string
+// router.named-routes.gen.ts (auto-generated)
+export const NamedRoutes = {
+  "search.index": { path: "/search", search: { q: "string", page: "number?", sort: "string?" } },
+  "home.index": "/",  // No search schema -> plain string
 } as const;
-export type routes = typeof routes;
 ```
 
 ## Loader Type Safety
@@ -474,8 +487,7 @@ export const ProductLoader = createLoader("product", async (ctx) => {
 
 // 5. Server: ctx.reverse for named routes
 path("/product/:slug", (ctx) => {
-  const reverse = scopedReverse<typeof urlpatterns>(ctx.reverse);
-  return <Link to={reverse("shop")}>Back to Shop</Link>;
+  return <Link to={ctx.reverse("shop")}>Back to Shop</Link>;
 }, { name: "product" })
 
 // 6. Client: useHref for mounted paths, href for absolute

package/src/index.rsc.ts

@@ -67,13 +67,22 @@ export type {
   NotFoundInfo,
   NotFoundBoundaryFallbackProps,
   NotFoundBoundaryHandler,
+  // Error handling callback types
+  ErrorPhase,
+  OnErrorContext,
+  OnErrorCallback,
 } from "./types.js";
 
 // Router options type (server-only, so import directly)
 export type { RSCRouterOptions } from "./router.js";
 
 // Server-side createLoader and redirect
-export { createLoader, redirect } from "./route-definition.js";
+export {
+  createLoader,
+  redirect,
+  type RouteHelpers,
+  type RouteHandlers,
+} from "./route-definition.js";
 
 // Handle API
 export { createHandle, isHandle, type Handle } from "./handle.js";
@@ -167,3 +176,6 @@ export {
   type LocationStateDefinition,
   type LocationStateEntry,
 } from "./browser/react/location-state-shared.js";
+
+// Path-based response type lookup from RegisteredRoutes
+export type { PathResponse } from "./href-client.js";

package/src/index.ts

@@ -68,6 +68,10 @@ export type {
   NotFoundInfo,
   NotFoundBoundaryFallbackProps,
   NotFoundBoundaryHandler,
+  // Error handling callback types
+  ErrorPhase,
+  OnErrorContext,
+  OnErrorCallback,
 } from "./types.js";
 
 // Search params schema types
@@ -77,6 +81,9 @@ export type { SearchSchema, SearchSchemaValue, ResolveSearchSchema, RouteSearchP
 // Use this when defining loaders that will be imported by client components
 export { createLoader } from "./loader.js";
 
+// Route definition types (safe to import anywhere)
+export type { RouteHelpers, RouteHandlers } from "./route-definition.js";
+
 // Response route types (usable in both server and client contexts)
 export type {
   ResponseHandler,

package/src/route-definition.ts

@@ -517,6 +517,10 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
  */
 const hasRoutesInItem = (item: AllUseItems): boolean => {
   if (item.type === "route") return true;
+  // Lazy includes contain deferred routes — treat them as having routes
+  // to prevent the parent layout from being misclassified as orphan,
+  // which would clear its parent pointer and break the middleware chain.
+  if (item.type === "include") return true;
   if (item.type === "cache" && item.uses) {
     return item.uses.some((child) => hasRoutesInItem(child));
   }
@@ -823,6 +827,11 @@ const parallel: RouteHelpers<any, any>["parallel"] = (slots, use) => {
     invariant(false, "No parent entry available for parallel()");
   }
 
+  invariant(
+    ctx.parent.type !== "parallel",
+    "parallel() cannot be nested inside another parallel()"
+  );
+
   const namespace = `${ctx.namespace}.$${store.getNextIndex("parallel")}`;
 
   // Unwrap any static handler definitions in parallel slots
@@ -888,6 +897,11 @@ const intercept: RouteHelpers<any, any>["intercept"] = (
     invariant(false, "No parent entry available for intercept()");
   }
 
+  invariant(
+    ctx.parent.type !== "parallel",
+    "intercept() cannot be used inside parallel()"
+  );
+
   const namespace = `${ctx.namespace}.$${store.getNextIndex("intercept")}.${slotName}`;
 
   // Apply name prefix to routeName (from include())
@@ -1080,6 +1094,12 @@ const layout: RouteHelpers<any, any>["layout"] = (handler, use) => {
   const store = getContext();
   const ctx = store.getStore();
   if (!ctx) throw new Error("layout() must be called inside map()");
+
+  invariant(
+    !ctx.parent || ctx.parent.type !== "parallel",
+    "layout() cannot be used inside parallel()"
+  );
+
   const isRoot = !ctx.parent || ctx.parent === null;
   const nextIndex = isRoot ? "$root" : store.getNextIndex("layout");
   const namespace = `${ctx.namespace}.${nextIndex}`;
@@ -1127,6 +1147,17 @@ const layout: RouteHelpers<any, any>["layout"] = (handler, use) => {
     result.some((item) => hasRoutesInItem(item));
 
   if (!hasRoutes) {
+    // Orphan layouts must not contain other layouts as children.
+    // If we're here, all child layouts are also orphan (if any had routes,
+    // hasRoutesInItem would have returned true). Nested orphan chains are
+    // confusing — use sibling orphan layouts instead.
+    if (result) {
+      invariant(
+        !result.some((item) => item?.type === "layout"),
+        `orphan layout cannot contain other layouts as children [${namespace}]`
+      );
+    }
+
     const parent = ctx.parent;
 
     // Allow orphan layouts at root level if they're part of map() builder result

package/src/router/match-middleware/cache-store.ts

@@ -104,8 +104,8 @@ import type { ResolvedSegment } from "../../types.js";
 import { getRequestContext } from "../../server/request-context.js";
 import type { MatchContext, MatchPipelineState } from "../match-context.js";
 import { getRouterContext } from "../router-context.js";
-import type { GeneratorMiddleware } from "./cache-lookup.js";
 import { debugLog, debugWarn } from "../logging.js";
+import type { GeneratorMiddleware } from "./cache-lookup.js";
 
 /**
  * Creates cache store middleware

package/src/server.ts

@@ -1,95 +1,20 @@
 /**
- * rsc-router/server
+ * @rangojs/router/server — Internal subpath
  *
- * Server-only exports for route definition and building
- * These should only be imported in server-side handler files
+ * This module is NOT user-facing. Import from "@rangojs/router" instead.
+ *
+ * Exports here are consumed by the Vite plugin (discovery, manifest injection,
+ * virtual modules) and the RSC handler internals. They are not part of the
+ * public API and may change without notice.
  */
 
-// Route definition helpers (server-only)
-export {
-  createLoader,
-  redirect,
-  type RouteHelpers,
-  type RouteHandlers,
-} from "./route-definition.js";
-
-// Django-style URL patterns (server-only)
+// Router registry (used by Vite plugin for build-time discovery)
 export {
-  urls,
-  RESPONSE_TYPE,
-  type PathHelpers,
-  type PathOptions,
-  type UrlPatterns,
-  type IncludeOptions,
-  type ResponseHandler,
-  type ResponseHandlerContext,
-  type JsonResponseHandler,
-  type TextResponseHandler,
-  type JsonValue,
-  type ResponsePathFn,
-  type JsonResponsePathFn,
-  type TextResponsePathFn,
-  type RouteResponse,
-  type ResponseError,
-  type ResponseEnvelope,
-} from "./urls.js";
-
-// Re-export IncludeItem from route-types
-export type { IncludeItem } from "./route-types.js";
-
-// Core router (server-only)
-export {
-  createRouter,
   RSC_ROUTER_BRAND,
   RouterRegistry,
-  type RSCRouter,
-  type RSCRouterOptions,
-  type RootLayoutProps,
 } from "./router.js";
 
-// Type-safe reverse utilities (Django-style URL reversal)
-export {
-  createReverse,
-  type ReverseFunction,
-  type PrefixedRoutes,
-  type PrefixRoutePatterns,
-  type ParamsFor,
-  type SanitizePrefix,
-  type MergeRoutes,
-} from "./reverse.js";
-
-// Segment system (server-only)
-export { renderSegments } from "./segment-system.js";
-
-// Performance tracking (server-only)
-export { track } from "./server/context.js";
-
-// Handle API (works in both server and client contexts)
-export { createHandle, isHandle, type Handle } from "./handle.js";
-
-// Pre-render handler API
-export {
-  Prerender,
-  isPrerenderHandler,
-  type PrerenderHandlerDefinition,
-  type PrerenderOptions,
-  type BuildContext,
-} from "./prerender.js";
-
-// Static handler API
-export {
-  Static,
-  isStaticHandler,
-  type StaticHandlerDefinition,
-} from "./static-handler.js";
-
-// Built-in handles
-export { Meta } from "./handles/meta.js";
-
-// Loader registry (for GET-based loader fetching)
-export { registerLoaderById, setLoaderImports } from "./server/loader-registry.js";
-
-// Route map builder (for build-time manifest registration)
+// Route map builder (Vite plugin injects these via virtual modules)
 export {
   registerRouteMap,
   setCachedManifest,
@@ -103,87 +28,17 @@ export {
   ensureRouterManifest,
 } from "./route-map-builder.js";
 
-// Request context (for accessing request data in server components/actions)
+// Loader registry (Vite plugin registers lazy loader imports)
+export { registerLoaderById, setLoaderImports } from "./server/loader-registry.js";
+
+// Request context creation (used by RSC handler, not user-facing)
 export {
-  getRequestContext,
-  requireRequestContext,
   createRequestContext,
-  type RequestContext,
   type CreateRequestContextOptions,
 } from "./server/request-context.js";
 
-// Meta types
-export type { MetaDescriptor, MetaDescriptorBase } from "./router/types.js";
-
-// Middleware context types (Middleware type is exported from types.ts)
-export type {
-  MiddlewareContext,
-  CookieOptions,
-} from "./router/middleware.js";
-
-// Error classes and utilities
-export {
-  RouteNotFoundError,
-  DataNotFoundError,
-  notFound,
-  MiddlewareError,
-  HandlerError,
-  BuildError,
-  InvalidHandlerError,
-  sanitizeError,
-  RouterError,
-} from "./errors.js";
-
-// Component utilities
+// Component utilities (used internally for server/client boundary checks)
 export {
   isClientComponent,
   assertClientComponent,
 } from "./component-utils.js";
-
-// Debug utilities for route matching (development only)
-export {
-  enableMatchDebug,
-  getMatchDebugStats,
-} from "./router/pattern-matching.js";
-
-// Types (re-exported for convenience - user-facing only)
-export type {
-  // Configuration types
-  RouterEnv,
-  DefaultEnv,
-  RouteDefinition,
-  RouteConfig,
-  RouteDefinitionOptions,
-  TrailingSlashMode,
-  // Handler types
-  Handler,            // Supports params object, path pattern, or route name
-  HandlerContext,
-  ExtractParams,
-  GenericParams,
-  // Middleware types (also exported from router/middleware.js above)
-  Middleware,         // Supports env type and optional route name for params
-  // Revalidation types
-  RevalidateParams,
-  Revalidate,
-  RouteKeys,
-  // Loader types
-  LoaderDefinition,
-  LoaderFn,
-  LoaderContext,
-  // Error boundary types
-  ErrorInfo,
-  ErrorBoundaryFallbackProps,
-  ErrorBoundaryHandler,
-  ClientErrorBoundaryFallbackProps,
-  // NotFound boundary types
-  NotFoundInfo,
-  NotFoundBoundaryFallbackProps,
-  NotFoundBoundaryHandler,
-  // Error handling callback types
-  ErrorPhase,
-  OnErrorContext,
-  OnErrorCallback,
-} from "./types.js";
-
-// Path-based response type lookup from RegisteredRoutes
-export type { PathResponse } from "./href-client.js";

package/src/urls.ts

@@ -813,6 +813,24 @@ function createPathHelper<TEnv>(): PathFn<TEnv> {
     const ctx = store.getStore();
     if (!ctx) throw new Error("path() must be called inside urls()");
 
+    invariant(
+      !ctx.parent || ctx.parent.type !== "parallel",
+      "path() cannot be used inside parallel()"
+    );
+
+    // Walk the parent chain to prevent path() nested under another path(),
+    // even when separated by intermediate layouts (e.g. path(layout(path())))
+    {
+      let ancestor = ctx.parent;
+      while (ancestor) {
+        invariant(
+          ancestor.type !== "route",
+          "path() cannot be nested inside another path()"
+        );
+        ancestor = ancestor.parent;
+      }
+    }
+
     // Determine options and use based on argument types
     let options: PathOptions | undefined;
     let use: (() => RouteUseItem[]) | undefined;

package/src/vite/index.ts

@@ -7,8 +7,6 @@ import { createRequire } from "node:module";
 import { mkdirSync, writeFileSync, readFileSync, existsSync, unlinkSync } from "node:fs";
 import {
   generateRouteTypesSource,
-  writePerModuleRouteTypes,
-  writePerModuleRouteTypesForFile,
   writeCombinedRouteTypes,
   findRouterFiles,
   createScanFilter,
@@ -111,9 +109,8 @@ interface RangoBaseOptions {
   banner?: boolean;
 
   /**
-   * Generate static route type files (.gen.ts) by parsing url modules at startup.
-   * Creates per-module route maps and per-router named-routes.gen.ts for type-safe
-   * Handler<"name", routes> and href() without executing router code.
+   * Generate named-routes.gen.ts by parsing url modules at startup.
+   * Provides type-safe Handler<"name"> and href() without executing router code.
    * Set to `false` to disable (run `npx rango extract-names` manually instead).
    * @default true
    */
@@ -964,15 +961,13 @@ function createRouterDiscoveryPlugin(
           exclude: opts.exclude,
         });
       }
-      // Generate per-module route types from static source parsing.
-      // Runs before the dev server starts so .gen.ts files exist immediately for IDE.
+      // Generate combined named-routes.gen.ts from static source parsing.
+      // Runs before the dev server starts so the gen file exists immediately for IDE.
       // In build mode, the runtime discovery in buildStart produces the definitive
-      // named-routes.gen.ts (including dynamically generated routes). However, we
-      // still need to write initial gen files here so discovery can import router
-      // modules that reference them. preserveIfLarger prevents overwriting a
-      // previously generated complete file with a partial one.
+      // named-routes.gen.ts (including dynamically generated routes).
+      // preserveIfLarger prevents overwriting a previously generated complete
+      // file with a partial one.
       if (opts?.staticRouteTypesGeneration !== false) {
-        writePerModuleRouteTypes(projectRoot, scanFilter);
         cachedRouterFiles = findRouterFiles(projectRoot, scanFilter);
         writeCombinedRouteTypes(projectRoot, cachedRouterFiles, { preserveIfLarger: true });
       }
@@ -1173,8 +1168,8 @@ function createRouterDiscoveryPlugin(
         res.end("No prerender match");
       });
 
-      // Watch url module and router files for changes and regenerate route types.
-      // Process files containing urls( (per-module types) or createRouter( (per-router types).
+      // Watch url module and router files for changes and regenerate named-routes.gen.ts.
+      // Process files containing urls( or createRouter( to update the combined route map.
       if (opts?.staticRouteTypesGeneration !== false) {
         server.watcher.on("change", (filePath) => {
           if (filePath.endsWith(".gen.ts")) return;
@@ -1188,9 +1183,6 @@ function createRouterDiscoveryPlugin(
             const hasUrls = source.includes("urls(");
             const hasCreateRouter = /\bcreateRouter\s*[<(]/.test(source);
             if (!hasUrls && !hasCreateRouter) return;
-            if (hasUrls) {
-              writePerModuleRouteTypesForFile(filePath);
-            }
             // Invalidate cache when a router file changes (new router added/removed)
             if (hasCreateRouter) {
               cachedRouterFiles = undefined;