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

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/router.ts

@@ -98,7 +98,7 @@ import {
 } from "./router/match-api.js";
 
 import type { SegmentResolutionDeps, MatchApiDeps } from "./router/types.js";
-import { createHandlerContext, createBuildContext } from "./router/handler-context.js";
+import { createHandlerContext } from "./router/handler-context.js";
 import {
   setupLoaderAccess,
   setupLoaderAccessSilent,
@@ -1655,7 +1655,7 @@ export function createRouter<TEnv = any>(
         routes: {} as ResolvedRouteMap<any>, // Empty until first match
         trailingSlash: entry.trailingSlash,
         handler: (lazyInclude.patterns as UrlPatterns<TEnv>).handler,
-        mountIndex: entry.mountIndex,
+        mountIndex: mountIndex++,
         // Lazy evaluation fields
         lazy: true,
         lazyPatterns: lazyInclude.patterns,
@@ -1911,11 +1911,18 @@ export function createRouter<TEnv = any>(
       };
 
       return runWithRequestContext(minimalRequestContext, async () => {
-        // 6. Create BuildContext (no request/env/headers/cookies)
-        const buildCtx = createBuildContext<TEnv>(
+        // 6. Create handler context with synthetic request for pre-rendering.
+        // The synthetic request and route map are available at build time,
+        // so reverse() and other context properties work normally.
+        const buildCtx = createHandlerContext<TEnv>(
           matchedParams,
+          minimalRequestContext.request,
+          minimalRequestContext.url.searchParams,
           pathname,
-          handleStore,
+          minimalRequestContext.url,
+          {},
+          mergedRouteMap,
+          matched.routeKey,
         );
 
         // 7. Wire use() for handles only (loaders throw)
@@ -2527,7 +2534,7 @@ export function createRouter<TEnv = any>(
             routes: {} as ResolvedRouteMap<any>, // Empty until first match
             trailingSlash: trailingSlashConfig,
             handler: urlPatterns.handler,
-            mountIndex: currentMountIndex,
+            mountIndex: mountIndex++,
             // Lazy evaluation fields
             lazy: true,
             lazyPatterns: lazyInclude.patterns,

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;
@@ -1113,6 +1131,17 @@ function createIncludeHelper<TEnv>(): IncludeFn<TEnv> {
     // sibling entries (e.g., BlogLayout and ArticlesLayout under NavLayout).
     const capturedCounters = { ...ctx.counters };
 
+    // Reserve a layout slot in the parent's counter so sibling lazy includes
+    // produce different shortCode indices for their root layout.
+    // Without this, consecutive include() calls capture identical counters
+    // and their first child layouts get the same shortCode (e.g., both M0L0L0),
+    // causing the client partial-update diff to see no changes on navigation.
+    if (capturedParent?.shortCode) {
+      const layoutCounterKey = `${capturedParent.shortCode}_layout`;
+      ctx.counters[layoutCounterKey] ??= 0;
+      ctx.counters[layoutCounterKey]++;
+    }
+
     // All includes are lazy - patterns are evaluated on first matching request
     // This improves cold start time significantly for large route sets
     return {

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;