@rangojs/router 0.0.0-experimental.259 → 0.0.0-experimental.26

package/src/route-definition/dsl-helpers.ts

@@ -16,7 +16,7 @@ import {
 } from "../server/context";
 import { invariant } from "../errors";
 import { isCachedFunction } from "../cache/taint.js";
-import { getCacheProfile } from "../cache/profile-registry.js";
+import { RSCRouterContext } from "../server/context";
 import { isStaticHandler } from "../static-handler.js";
 import RootLayout from "../server/root-layout";
 import type {
@@ -227,7 +227,9 @@ const cache: RouteHelpers<any, any>["cache"] = (
     children = undefined;
   } else if (typeof optionsOrChildren === "string") {
     // cache('profileName') or cache('profileName', () => [...])
-    const profile = getCacheProfile(optionsOrChildren);
+    // Resolve from context-scoped profiles (set per-router via HelperContext).
+    const ctxStore = RSCRouterContext.getStore();
+    const profile = ctxStore?.cacheProfiles?.[optionsOrChildren];
     invariant(
       profile,
       `cache("${optionsOrChildren}"): unknown cache profile. ` +
@@ -245,7 +247,9 @@ const cache: RouteHelpers<any, any>["cache"] = (
     children = maybeChildren;
   }
 
-  const name = `$${store.getNextIndex("cache")}`;
+  // Allocate a single index for this cache() call (used in all paths)
+  const cacheIndex = store.getNextIndex("cache");
+  const name = `$${cacheIndex}`;
   const cacheConfig = { options };
 
   // If no children, create an orphan cache entry (like orphan layouts)
@@ -262,7 +266,7 @@ const cache: RouteHelpers<any, any>["cache"] = (
 
     // Create orphan cache entry (like orphan layout)
     // Subsequent siblings in the same array will attach to this entry
-    const namespace = `${ctx.namespace}.${store.getNextIndex("cache")}`;
+    const namespace = `${ctx.namespace}.${cacheIndex}`;
     const cacheUrlPrefix = getUrlPrefix();
 
     const entry = {
@@ -297,8 +301,7 @@ const cache: RouteHelpers<any, any>["cache"] = (
   }
 
   // With children: create a cache entry (like layout with caching semantics)
-  const cacheNextIndex = store.getNextIndex("cache");
-  const namespace = `${ctx.namespace}.${cacheNextIndex}`;
+  const namespace = `${ctx.namespace}.${cacheIndex}`;
   const cacheShortCode = store.getShortCode("cache");
 
   const cacheUrlPrefix2 = getUrlPrefix();

package/src/route-definition/index.ts

@@ -1,6 +1,3 @@
-// Route definition
-export { route, type RouteDefinitionResult } from "./route-function.js";
-
 // Type definitions
 export type { RouteHelpers } from "./helpers-types.js";
 export type {

package/src/route-definition/redirect.ts

@@ -43,11 +43,16 @@ import {
 export function redirect(url: string, status?: number): Response;
 export function redirect(
   url: string,
-  options: { status?: number; state?: LocationStateEntry[] },
+  options: {
+    status?: number;
+    state?: LocationStateEntry | LocationStateEntry[];
+  },
 ): Response;
 export function redirect(
   url: string,
-  statusOrOptions?: number | { status?: number; state?: LocationStateEntry[] },
+  statusOrOptions?:
+    | number
+    | { status?: number; state?: LocationStateEntry | LocationStateEntry[] },
 ): Response {
   const status =
     typeof statusOrOptions === "number"
@@ -62,7 +67,14 @@ export function redirect(
 
     if (process.env.NODE_ENV !== "production") {
       const reqCtx = getRequestContext();
-      if (reqCtx && !reqCtx.url.searchParams.has("_rsc_partial")) {
+      // Warn only on true full-page SSR loads. SPA partial requests and server
+      // actions both deliver state through Flight payloads, so suppress for those.
+      if (
+        reqCtx &&
+        !reqCtx.url.searchParams.has("_rsc_partial") &&
+        !reqCtx.request.headers.has("rsc-action") &&
+        !reqCtx.url.searchParams.has("_rsc_action")
+      ) {
         console.warn(
           `[Router] redirect() with state during a full-page (SSR) request to "${url}". ` +
             "Location state is only delivered during SPA navigations and will be lost on this request.",

package/src/route-map-builder.ts

@@ -128,15 +128,23 @@ const perRouterPrecomputedEntriesMap: Map<
 > = new Map();
 
 /**
- * Clear all per-router cached data (manifest, trie, precomputed entries).
+ * Clear all cached route data (global and per-router).
  * Called during HMR when route definitions change so the handler rebuilds
  * the trie from the updated router.urlpatterns on the next request.
+ *
+ * The virtual module calls this before repopulating with fresh data,
+ * preventing stale entries from removed routes from accumulating.
  */
 export function clearAllRouterData(): void {
+  globalRouteMap = {};
+  cachedManifest = null;
+  cachedPrecomputedEntries = null;
+  cachedRouteTrie = null;
+  rootScopeRoutes.clear();
+  globalSearchSchemas.clear();
   perRouterManifestMap.clear();
   perRouterTrieMap.clear();
   perRouterPrecomputedEntriesMap.clear();
-  cachedRouteTrie = null;
 }
 
 export function setRouterManifest(
@@ -217,6 +225,34 @@ export function waitForManifestReady(): Promise<void> | null {
   return manifestReadyPromise;
 }
 
+// ============================================================================
+// Route Scope Registry
+// ============================================================================
+
+// Tracks whether each route is at root scope (no named include boundary above).
+// Used by dot-local reverse resolution to decide whether bare-name fallback
+// is allowed after scoped lookups are exhausted.
+const rootScopeRoutes: Map<string, boolean> = new Map();
+
+/**
+ * Register whether a route is at root scope.
+ * Called by path() during route evaluation.
+ */
+export function registerRouteRootScope(
+  routeName: string,
+  rootScoped: boolean,
+): void {
+  rootScopeRoutes.set(routeName, rootScoped);
+}
+
+/**
+ * Check if a route is at root scope.
+ * Returns undefined if the route has not been registered (e.g. in unit tests).
+ */
+export function isRouteRootScoped(routeName: string): boolean | undefined {
+  return rootScopeRoutes.get(routeName);
+}
+
 // ============================================================================
 // Search Schema Registry
 // ============================================================================

package/src/route-name.ts

@@ -0,0 +1,53 @@
+/**
+ * Route name utilities for filtering internal route names.
+ *
+ * Internal names stay active in the runtime manifest for matching and local
+ * reverse() resolution, but they must not leak into public APIs or generated
+ * route maps.
+ */
+
+export const AUTO_GENERATED_ROUTE_PREFIX = "$path_";
+export const INTERNAL_INCLUDE_SCOPE_PREFIX = "$prefix_";
+
+const RESERVED_PREFIXES = [
+  AUTO_GENERATED_ROUTE_PREFIX,
+  INTERNAL_INCLUDE_SCOPE_PREFIX,
+] as const;
+
+/**
+ * Check if a route name is internal.
+ * Internal names include:
+ * - unnamed path() routes like "$path__health" or "docs.$path__health"
+ * - hidden include scopes like "$prefix_0.index" or "blog.$prefix_1.post"
+ *
+ * User-defined names containing "$" (e.g. "docs.$admin") are valid and must
+ * be preserved.
+ */
+export function isAutoGeneratedRouteName(name: string): boolean {
+  return name.split(".").some((segment) => {
+    return (
+      segment.startsWith(AUTO_GENERATED_ROUTE_PREFIX) ||
+      segment.startsWith(INTERNAL_INCLUDE_SCOPE_PREFIX)
+    );
+  });
+}
+
+/**
+ * Validate that a user-provided route name does not collide with
+ * reserved internal prefixes. Checks every dot-separated segment,
+ * mirroring the same rule used by isAutoGeneratedRouteName().
+ *
+ * Throws with a clear message when a reserved prefix is detected.
+ */
+export function validateUserRouteName(name: string): void {
+  for (const segment of name.split(".")) {
+    for (const prefix of RESERVED_PREFIXES) {
+      if (segment.startsWith(prefix)) {
+        throw new Error(
+          `Route name "${name}" contains segment "${segment}" which uses reserved internal prefix "${prefix}". ` +
+            `Choose a different name to avoid collision with auto-generated route names.`,
+        );
+      }
+    }
+  }
+}

package/src/route-types.ts

@@ -169,6 +169,13 @@ export type IncludeItem = {
     parent: unknown; // EntryData - avoid circular import
     /** Counter snapshot from pattern extraction for consistent shortCode indices */
     counters?: Record<string, number>;
+    /** Cache profiles for DSL-time cache("profileName") resolution */
+    cacheProfiles?: Record<
+      string,
+      import("./cache/profile-registry.js").CacheProfile
+    >;
+    /** Root scope flag for dot-local reverse resolution */
+    rootScoped?: boolean;
   };
   [IncludeBrand]: void;
 };

package/src/router/content-negotiation.ts

@@ -52,7 +52,7 @@ export function parseAcceptTypes(accept: string): AcceptEntry[] {
   for (let i = 0; i < parts.length; i++) {
     const part = parts[i]!;
     const segments = part.split(";");
-    const mime = segments[0]!.trim();
+    const mime = segments[0]!.trim().toLowerCase();
     if (!mime) continue;
     let q = 1.0;
     for (let j = 1; j < segments.length; j++) {

package/src/router/debug-manifest.ts

@@ -45,10 +45,23 @@ export async function buildDebugManifest<TEnv = any>(
         if (promiseResult !== null) {
           const load = await (promiseResult as Promise<any>);
           if (load && typeof load === "object" && "default" in load) {
-            const useItems = load.default;
-            if (typeof useItems === "function") {
-              useItems(helpers);
+            // Promise<{ default: fn }> — e.g. dynamic import
+            if (typeof load.default !== "function") {
+              throw new Error(
+                `[@rangojs/router] Unsupported async handler: { default } must be a function, ` +
+                  `got ${typeof load.default}. Use () => import('./urls') for lazy loading.`,
+              );
             }
+            load.default(helpers);
+          } else if (typeof load === "function") {
+            // Promise<fn>
+            load(helpers);
+          } else {
+            // Reject unsupported async handler results (same policy as manifest.ts)
+            throw new Error(
+              `[@rangojs/router] Unsupported async handler result (${typeof load}). ` +
+                `Lazy route handlers must resolve to a function or { default: fn }.`,
+            );
           }
         }
       },

package/src/router/handler-context.ts

@@ -5,11 +5,13 @@
  */
 
 import type { HandlerContext, InternalHandlerContext } from "../types";
-import { getRequestContext } from "../server/request-context.js";
-import { getSearchSchema } from "../route-map-builder.js";
+import { _getRequestContext } from "../server/request-context.js";
+import { getSearchSchema, isRouteRootScoped } from "../route-map-builder.js";
 import { parseSearchParams, serializeSearchParams } from "../search-params.js";
 import { contextGet, contextSet } from "../context-var.js";
 import { NOCACHE_SYMBOL } from "../cache/taint.js";
+import { isAutoGeneratedRouteName } from "../route-name.js";
+import { PRERENDER_PASSTHROUGH } from "../prerender.js";
 
 /**
  * Strip internal _rsc* query params from a URL.
@@ -28,11 +30,15 @@ export function stripInternalParams(url: URL): URL {
 /**
  * Resolve route name with namespace prefix support.
  * Supports local names (dot-prefixed) and absolute names (global lookup).
+ *
+ * @param rootScoped - Explicit override for root-scope check. When undefined,
+ *   falls back to the global scope registry, then to a heuristic.
  */
 function resolveRouteName(
   name: string,
   routeMap: Record<string, string>,
   currentRoutePrefix?: string,
+  rootScoped?: boolean,
 ): string | undefined {
   // 1. Dot-prefixed (".article", ".author.posts") — local resolution only.
   //    Resolves within the current include() scope using the mount prefix.
@@ -65,6 +71,23 @@ function resolveRouteName(
       }
     }
 
+    // Fallback: try bare name at root scope only.
+    // Routes inside { name: "" } mounts are at root scope — their dot-local
+    // names can fall back to bare names (e.g., "sub.detail" reaching "flatIndex").
+    // Routes inside named mounts (e.g., { name: "magazine" }) are NOT at root
+    // scope — dot-local must not leak into unrelated global names.
+    //
+    // Resolution order: explicit param > scope registry > heuristic.
+    const isRootScoped =
+      rootScoped ??
+      isRouteRootScoped(currentRoutePrefix) ??
+      !currentRoutePrefix.includes(".");
+    if (isRootScoped) {
+      if (routeMap[lookupName] !== undefined) {
+        return routeMap[lookupName];
+      }
+    }
+
     return undefined;
   }
 
@@ -73,6 +96,27 @@ function resolveRouteName(
   return routeMap[name];
 }
 
+function createPrerenderPassthroughFn(
+  build: boolean,
+  isPassthroughRoute: boolean,
+): () => typeof PRERENDER_PASSTHROUGH {
+  return () => {
+    if (!build) {
+      throw new Error(
+        "ctx.passthrough() can only be called during build-time prerendering.",
+      );
+    }
+    if (!isPassthroughRoute) {
+      throw new Error(
+        "ctx.passthrough() is only available on routes declared with " +
+          "{ passthrough: true }. Remove the passthrough() call or add " +
+          "{ passthrough: true } to the Prerender options.",
+      );
+    }
+    return PRERENDER_PASSTHROUGH;
+  };
+}
+
 /**
  * Create a reverse function for URL generation from route names.
  * Used by both HandlerContext and MiddlewareContext.
@@ -87,6 +131,7 @@ export function createReverseFunction(
   routeMap: Record<string, string>,
   currentRoutePrefix?: string,
   currentParams?: Record<string, string>,
+  rootScoped?: boolean,
 ): (
   name: string,
   hrefParams?: Record<string, string>,
@@ -94,7 +139,12 @@ export function createReverseFunction(
 ) => string {
   return (name, hrefParams, search) => {
     // Resolve route name with namespace support
-    const pattern = resolveRouteName(name, routeMap, currentRoutePrefix);
+    const pattern = resolveRouteName(
+      name,
+      routeMap,
+      currentRoutePrefix,
+      rootScoped,
+    );
 
     if (pattern === undefined) {
       throw new Error(
@@ -109,10 +159,10 @@ export function createReverseFunction(
       ? { ...currentParams, ...hrefParams }
       : hrefParams;
 
-    // Substitute params (strip constraint syntax: :param(a|b) -> value)
+    // Substitute params (strip constraint and optional syntax: :param(a|b)? -> value)
     if (effectiveParams) {
       result = result.replace(
-        /:([a-zA-Z_][a-zA-Z0-9_]*)(\([^)]*\))?/g,
+        /:([a-zA-Z_][a-zA-Z0-9_]*)(\([^)]*\))?\??/g,
         (_, key) => {
           const value = effectiveParams[key];
           if (value === undefined) {
@@ -146,10 +196,11 @@ export function createHandlerContext<TEnv>(
   routeMap: Record<string, string> = {},
   routeName?: string,
   responseType?: string,
+  isPassthroughRoute: boolean = false,
 ): InternalHandlerContext<any, TEnv> {
   // Get variables from request context - this is the unified context
   // shared between middleware and route handlers
-  const requestContext = getRequestContext();
+  const requestContext = _getRequestContext();
   const variables: any = requestContext?.var ?? {};
 
   // If route has a search schema, parse URLSearchParams into typed object
@@ -179,7 +230,6 @@ export function createHandlerContext<TEnv>(
     set: ((keyOrVar: any, value: any) => {
       contextSet(variables, keyOrVar, value);
     }) as HandlerContext<any, TEnv>["set"],
-    _originalRequest: request, // Raw request for advanced use
     res: stubResponse, // Stub response for setting headers
     headers: stubResponse.headers, // Shorthand for res.headers
     // Placeholder use() - will be replaced with actual implementation during request
@@ -198,9 +248,21 @@ export function createHandlerContext<TEnv>(
       }
       requestContext.setLocationState(entries);
     },
-    // Scoped reverse for URL generation (auto-fills current request params)
-    reverse: createReverseFunction(routeMap, routeName, params),
+    routeName: (routeName && !isAutoGeneratedRouteName(routeName)
+      ? routeName
+      : undefined) as HandlerContext["routeName"],
+    // Scoped reverse for URL generation (auto-fills current request params).
+    // Resolve rootScoped eagerly so the reverse function is self-contained
+    // and does not depend on the global rootScopeRoutes registry at call time.
+    reverse: createReverseFunction(
+      routeMap,
+      routeName,
+      params,
+      routeName ? isRouteRootScoped(routeName) : undefined,
+    ),
+    passthrough: createPrerenderPassthroughFn(false, isPassthroughRoute),
     _responseType: responseType,
+    _routeName: routeName,
   };
   // Brand with taint symbol so "use cache" excludes ctx from cache keys
   (ctx as any)[NOCACHE_SYMBOL] = true;
@@ -220,6 +282,7 @@ export function createPrerenderContext<TEnv>(
   routeMap: Record<string, string>,
   routeName?: string,
   buildVars?: Record<string, any>,
+  isPassthroughRoute?: boolean,
 ): InternalHandlerContext<any, TEnv> {
   const syntheticUrl = new URL(`http://prerender${pathname}`);
   const variables = buildVars ?? {};
@@ -251,9 +314,6 @@ export function createPrerenderContext<TEnv>(
     set: ((keyOrVar: any, value: any) => {
       contextSet(variables, keyOrVar, value);
     }) as any,
-    get _originalRequest(): Request {
-      return throwUnavailable("request");
-    },
     get res(): Response {
       return throwUnavailable("res");
     },
@@ -266,10 +326,23 @@ export function createPrerenderContext<TEnv>(
     },
     theme: undefined,
     setTheme: undefined,
+    routeName: (routeName && !isAutoGeneratedRouteName(routeName)
+      ? routeName
+      : undefined) as HandlerContext["routeName"],
     setLocationState: () => {
       throwUnavailable("setLocationState");
     },
-    reverse: createReverseFunction(routeMap, routeName, params),
+    reverse: createReverseFunction(
+      routeMap,
+      routeName,
+      params,
+      routeName ? isRouteRootScoped(routeName) : undefined,
+    ),
+    passthrough: createPrerenderPassthroughFn(
+      true,
+      isPassthroughRoute === true,
+    ),
+    _routeName: routeName,
   } as InternalHandlerContext<any, TEnv>;
 }
 
@@ -322,9 +395,6 @@ export function createStaticContext<TEnv>(
     set: ((keyOrVar: any, value: any) => {
       contextSet(variables, keyOrVar, value);
     }) as any,
-    get _originalRequest(): Request {
-      return throwUnavailable("request");
-    },
     get res(): Response {
       return throwUnavailable("res");
     },
@@ -337,9 +407,18 @@ export function createStaticContext<TEnv>(
     },
     theme: undefined,
     setTheme: undefined,
+    routeName: (routeName && !isAutoGeneratedRouteName(routeName)
+      ? routeName
+      : undefined) as HandlerContext["routeName"],
     setLocationState: () => {
       throwUnavailable("setLocationState");
     },
-    reverse: createReverseFunction(routeMap, routeName),
+    reverse: createReverseFunction(
+      routeMap,
+      routeName,
+      undefined,
+      routeName ? isRouteRootScoped(routeName) : undefined,
+    ),
+    _routeName: routeName,
   } as InternalHandlerContext<any, TEnv>;
 }

package/src/router/intercept-resolution.ts

@@ -384,10 +384,12 @@ export async function resolveInterceptLoadersOnly<TEnv>(
     return null;
   }
 
-  const loaderDataPromise =
-    interceptEntry.loading !== undefined
-      ? Promise.all(loaderPromises)
-      : await Promise.all(loaderPromises);
+  // Match fresh-path semantics: only defer (no await) when loading is truthy.
+  // `loading: false` means "no loading UI, await loaders before render" —
+  // same as the fresh path's `if (interceptEntry.loading && ...)` check.
+  const loaderDataPromise = interceptEntry.loading
+    ? Promise.all(loaderPromises)
+    : await Promise.all(loaderPromises);
 
   return { loaderDataPromise, loaderIds };
 }

package/src/router/lazy-includes.ts

@@ -28,6 +28,7 @@ export function findLazyIncludes<TEnv = any>(
     urlPrefix: string;
     namePrefix: string | undefined;
     parent: unknown;
+    rootScoped?: boolean;
   };
 }> {
   const lazyItems: Array<{
@@ -37,6 +38,7 @@ export function findLazyIncludes<TEnv = any>(
       urlPrefix: string;
       namePrefix: string | undefined;
       parent: unknown;
+      rootScoped?: boolean;
     };
   }> = [];
 
@@ -137,6 +139,8 @@ export function evaluateLazyEntry<TEnv = any>(
       namespace: "lazy",
       parent: (lazyContext?.parent as EntryData | null) ?? null,
       counters: lazyCounters,
+      cacheProfiles: (lazyContext as any)?.cacheProfiles,
+      rootScoped: (lazyContext as any)?.rootScoped,
     },
     () => {
       // Run the lazy patterns handler with the original context prefixes

package/src/router/loader-resolution.ts

@@ -22,7 +22,7 @@ import type { LoaderRevalidationResult, ActionContext } from "./types";
 import { isHandle, type Handle } from "../handle.js";
 import type { HandleStore } from "../server/handle-store.js";
 import { getFetchableLoader } from "../server/fetchable-loader-store.js";
-import { getRequestContext } from "../server/request-context.js";
+import { _getRequestContext } from "../server/request-context.js";
 import { debugLog } from "./logging.js";
 
 /**
@@ -182,7 +182,7 @@ function createLoaderExecutor<TEnv>(
   callerLoaderId: string | null,
 ) => Promise<any> {
   // Capture RequestContext eagerly for cookie access (ALS protection on Cloudflare)
-  const reqCtxRef = getRequestContext();
+  const reqCtxRef = _getRequestContext();
 
   // Dependency graph: loaderId -> set of loader IDs it directly depends on.
   const dependsOn = new Map<string, Set<string>>();
@@ -243,6 +243,7 @@ function createLoaderExecutor<TEnv>(
     const currentLoaderId = loader.$$id;
     const loaderCtx: LoaderContext<Record<string, string | undefined>, TEnv> = {
       params: ctx.params,
+      routeParams: (ctx.params ?? {}) as Record<string, string>,
       request: ctx.request,
       searchParams: ctx.searchParams,
       search: (ctx as any).search,
@@ -251,12 +252,6 @@ function createLoaderExecutor<TEnv>(
       env: ctx.env,
       var: ctx.var,
       get: ctx.get,
-      cookie(name: string) {
-        return reqCtxRef?.cookie(name);
-      },
-      cookies() {
-        return reqCtxRef?.cookies() ?? {};
-      },
       use: <TDep, TDepParams = any>(
         dep: LoaderDefinition<TDep, TDepParams>,
       ): Promise<TDep> => {
@@ -267,7 +262,7 @@ function createLoaderExecutor<TEnv>(
       reverse: ctx.reverse as LoaderContext["reverse"],
     };
 
-    const doneLoader = track(`loader:${loader.$$id}`);
+    const doneLoader = track(`loader:${loader.$$id}`, 2);
     const promise = Promise.resolve(
       loaderFn(loaderCtx as LoaderContext<any, TEnv>),
     ).finally(() => {
@@ -300,7 +295,7 @@ export function setupLoaderAccess<TEnv>(
   // can disrupt AsyncLocalStorage, causing getRequestContext() to return
   // undefined when handlers later call ctx.use(handle). Capturing early
   // ensures the store reference survives ALS disruption.
-  const handleStoreRef = getRequestContext()?._handleStore;
+  const handleStoreRef = _getRequestContext()?._handleStore;
 
   const useLoader = createLoaderExecutor(ctx, loaderPromises);
 
@@ -342,7 +337,7 @@ export function setupLoaderAccess<TEnv>(
  */
 export function setupBuildUse<TEnv>(ctx: HandlerContext<any, TEnv>): void {
   // Eagerly capture the HandleStore (same ALS protection as setupLoaderAccess).
-  const handleStoreRef = getRequestContext()?._handleStore;
+  const handleStoreRef = _getRequestContext()?._handleStore;
 
   ctx.use = ((item: LoaderDefinition<any, any> | Handle<any, any>) => {
     // Handle case: return a push function bound to the current segment