@rangojs/router 0.0.0-experimental.259 → 0.0.0-experimental.25dbaac3

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/find-match.ts

@@ -52,8 +52,10 @@ export function createFindMatch<TEnv = any>(
       : undefined;
 
     // Phase 1: Try trie match (O(path_length))
-    // Prefer per-router trie (isolated) over global trie (merged).
-    const routeTrie = getRouterTrie(deps.routerId) ?? getRouteTrie();
+    // Only use the per-router trie. The global trie merges routes from ALL
+    // routers and must not be used — in multi-router setups (host routing)
+    // overlapping paths like "/" would match the wrong app's route.
+    const routeTrie = getRouterTrie(deps.routerId);
     if (routeTrie) {
       const trieStart = performance.now();
       const trieResult = tryTrieMatch(routeTrie, pathname);

package/src/router/handler-context.ts

@@ -5,11 +5,21 @@
  */
 
 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 {
+  contextGet,
+  contextSet,
+  isNonCacheable,
+  type ContextSetOptions,
+} from "../context-var.js";
+import { isInsideCacheScope } from "../server/context.js";
+import { NOCACHE_SYMBOL, assertNotInsideCacheExec } from "../cache/taint.js";
+import { isAutoGeneratedRouteName } from "../route-name.js";
+import { PRERENDER_PASSTHROUGH } from "../prerender.js";
+import { encodePathSegment } from "./url-params.js";
+import { fireAndForgetWaitUntil } from "../types/request-scope.js";
 
 /**
  * Strip internal _rsc* query params from a URL.
@@ -28,11 +38,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 +79,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 +104,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 wrapped with " +
+          "Passthrough(). Remove the passthrough() call or wrap the " +
+          "Prerender definition with Passthrough(prerenderDef, liveHandler).",
+      );
+    }
+    return PRERENDER_PASSTHROUGH;
+  };
+}
+
 /**
  * Create a reverse function for URL generation from route names.
  * Used by both HandlerContext and MiddlewareContext.
@@ -87,6 +139,7 @@ export function createReverseFunction(
   routeMap: Record<string, string>,
   currentRoutePrefix?: string,
   currentParams?: Record<string, string>,
+  rootScoped?: boolean,
 ): (
   name: string,
   hrefParams?: Record<string, string>,
@@ -94,7 +147,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,18 +167,43 @@ 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)
+    // Optional params (:param?) are omitted when not provided
     if (effectiveParams) {
+      let hadOmittedOptional = false;
+      // First pass: optional params (trailing ?)
+      result = result.replace(
+        /:([a-zA-Z_][a-zA-Z0-9_]*)(\([^)]*\))?(\?)/g,
+        (_, key) => {
+          const value = effectiveParams[key];
+          // Empty string is treated as omitted — the trie matcher fills
+          // unmatched optional params with "" (not undefined), so reverse
+          // must collapse those segments instead of leaving empty slots.
+          if (value === undefined || value === "") {
+            hadOmittedOptional = true;
+            return "";
+          }
+          return encodePathSegment(value);
+        },
+      );
+      // Second pass: required params (no trailing ?)
       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) {
             throw new Error(`Missing param "${key}" for route "${name}"`);
           }
-          return encodeURIComponent(value);
+          return encodePathSegment(value);
         },
       );
+      // Clean up slashes only when an optional param was actually omitted,
+      // so intentional trailing-slash patterns like "/blog/" are preserved.
+      if (hadOmittedOptional) {
+        const hadTrailingSlash = pattern.length > 1 && pattern.endsWith("/");
+        result = result.replace(/\/\/+/g, "/").replace(/\/+$/, "") || "/";
+        if (hadTrailingSlash && !result.endsWith("/")) result += "/";
+      }
     }
 
     // Append search params as query string
@@ -146,11 +229,12 @@ 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 variables: any = requestContext?.var ?? {};
+  const requestContext = _getRequestContext();
+  const variables: any = requestContext?._variables ?? {};
 
   // If route has a search schema, parse URLSearchParams into typed object
   const searchSchema = routeName ? getSearchSchema(routeName) : undefined;
@@ -162,26 +246,70 @@ export function createHandlerContext<TEnv>(
   const stubResponse =
     requestContext?.res ?? new Response(null, { status: 200 });
 
-  const ctx: InternalHandlerContext<any, TEnv> = {
+  // Guard mutating Headers methods so they throw inside "use cache" or cache() scope.
+  // Uses lazy `ctx` reference (assigned below) — only the specific handler ctx
+  // is stamped by cache-runtime, not the shared request context.
+  const MUTATING_HEADERS_METHODS = new Set(["set", "append", "delete"]);
+  let ctx: InternalHandlerContext<any, TEnv>;
+  const guardedHeaders = new Proxy(stubResponse.headers, {
+    get(target, prop, receiver) {
+      const value = Reflect.get(target, prop, receiver);
+      if (typeof value === "function") {
+        if (MUTATING_HEADERS_METHODS.has(prop as string)) {
+          return (...args: any[]) => {
+            assertNotInsideCacheExec(ctx, "headers");
+            if (isInsideCacheScope()) {
+              throw new Error(
+                `ctx.headers.${String(prop)}() cannot be called inside a cache() boundary. ` +
+                  `On cache hit the handler is skipped, so this side effect would be lost. ` +
+                  `Move header mutations to a middleware or layout outside the cache() scope.`,
+              );
+            }
+            return value.apply(target, args);
+          };
+        }
+        return value.bind(target);
+      }
+      return value;
+    },
+  });
+
+  ctx = {
     params,
     build: false,
+    dev: false,
     request,
     searchParams,
     search: searchSchema ? resolvedSearchParams : {},
     pathname,
     url,
+    originalUrl: requestContext?.originalUrl ?? new URL(request.url),
     env: bindings,
-    var: variables,
-    get: ((keyOrVar: any) => contextGet(variables, keyOrVar)) as HandlerContext<
-      any,
-      TEnv
-    >["get"],
-    set: ((keyOrVar: any, value: any) => {
-      contextSet(variables, keyOrVar, value);
+    waitUntil: requestContext
+      ? requestContext.waitUntil.bind(requestContext)
+      : fireAndForgetWaitUntil,
+    executionContext: requestContext?.executionContext,
+    _variables: variables,
+    get: ((keyOrVar: any) => {
+      // Read-time guard: non-cacheable var inside cache() → throw.
+      // Works for both ContextVar tokens and string keys.
+      if (isNonCacheable(variables, keyOrVar) && isInsideCacheScope()) {
+        throw new Error(
+          `ctx.get() for a non-cacheable variable cannot be called inside a cache() boundary. ` +
+            `The variable was created with { cache: false } or set with { cache: false }, ` +
+            `and its value would be stale on cache hit. Move the read outside the cached scope.`,
+        );
+      }
+      return contextGet(variables, keyOrVar);
+    }) as HandlerContext<any, TEnv>["get"],
+    set: ((keyOrVar: any, value: any, options?: ContextSetOptions) => {
+      assertNotInsideCacheExec(ctx, "set");
+      // Write is dumb: store value + non-cacheable metadata.
+      // Enforcement happens at read time via ctx.get().
+      contextSet(variables, keyOrVar, value, options);
     }) 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
+    headers: guardedHeaders, // Guarded shorthand for res.headers
     // Placeholder use() - will be replaced with actual implementation during request
     use: () => {
       throw new Error("ctx.use() called before loaders were initialized");
@@ -198,9 +326,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;
@@ -212,7 +352,7 @@ export function createHandlerContext<TEnv>(
  *
  * Returns an InternalHandlerContext where params, pathname, url, searchParams,
  * search, reverse, and use(handle) work. Request-time properties
- * (request, env, headers, cookies, var, get, set, res) throw with a clear error.
+ * (request, env, headers, cookies, get, set, res) throw with a clear error.
  */
 export function createPrerenderContext<TEnv>(
   params: Record<string, string>,
@@ -220,6 +360,9 @@ export function createPrerenderContext<TEnv>(
   routeMap: Record<string, string>,
   routeName?: string,
   buildVars?: Record<string, any>,
+  isPassthroughRoute?: boolean,
+  buildEnv?: TEnv,
+  devMode?: boolean,
 ): InternalHandlerContext<any, TEnv> {
   const syntheticUrl = new URL(`http://prerender${pathname}`);
   const variables = buildVars ?? {};
@@ -234,6 +377,7 @@ export function createPrerenderContext<TEnv>(
   return {
     params,
     build: true,
+    dev: devMode ?? false,
     get request(): Request {
       return throwUnavailable("request");
     },
@@ -241,19 +385,25 @@ export function createPrerenderContext<TEnv>(
     search: {},
     pathname,
     url: syntheticUrl,
+    originalUrl: syntheticUrl,
     get env(): TEnv {
-      return throwUnavailable("env");
-    },
-    get var(): any {
-      return throwUnavailable("var");
+      if (buildEnv !== undefined) return buildEnv;
+      throw new Error(
+        "ctx.env is not available during pre-rendering. " +
+          "Configure buildEnv in your rango() plugin options to enable build-time env access.",
+      );
     },
+    // Build-time prerender has no live request. waitUntil is a true no-op
+    // (running fn() here would fire side effects during build, which is
+    // incorrect — these are meant to outlive the live response).
+    // executionContext is absent for the same reason.
+    waitUntil: () => {},
+    executionContext: undefined,
+    _variables: variables,
     get: ((keyOrVar: any) => contextGet(variables, keyOrVar)) as any,
     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 +416,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>;
 }
 
@@ -282,6 +445,8 @@ export function createPrerenderContext<TEnv>(
 export function createStaticContext<TEnv>(
   routeMap: Record<string, string>,
   routeName?: string,
+  buildEnv?: TEnv,
+  devMode?: boolean,
 ): InternalHandlerContext<any, TEnv> {
   const variables: Record<string, any> = {};
 
@@ -297,6 +462,7 @@ export function createStaticContext<TEnv>(
       return throwUnavailable("params");
     },
     build: true,
+    dev: devMode ?? false,
     get request(): Request {
       return throwUnavailable("request");
     },
@@ -312,19 +478,26 @@ export function createStaticContext<TEnv>(
     get url(): URL {
       return throwUnavailable("url");
     },
-    get env(): TEnv {
-      return throwUnavailable("env");
+    get originalUrl(): URL {
+      return throwUnavailable("originalUrl");
     },
-    get var(): any {
-      return throwUnavailable("var");
+    get env(): TEnv {
+      if (buildEnv !== undefined) return buildEnv;
+      throw new Error(
+        "ctx.env is not available in Static() handlers. " +
+          "Configure buildEnv in your rango() plugin options to enable build-time env access.",
+      );
     },
+    // Static() handlers have no live request. waitUntil is a true no-op
+    // (running fn() here would fire side effects during build, which is
+    // incorrect). executionContext is absent for the same reason.
+    waitUntil: () => {},
+    executionContext: undefined,
+    _variables: variables,
     get: ((keyOrVar: any) => contextGet(variables, keyOrVar)) as any,
     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 +510,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

@@ -11,7 +11,11 @@ import type {
   InterceptEntry,
   InterceptSelectorContext,
 } from "../server/context";
-import type { HandlerContext, ResolvedSegment } from "../types";
+import type {
+  HandlerContext,
+  InternalHandlerContext,
+  ResolvedSegment,
+} from "../types";
 import { evaluateRevalidation } from "./revalidation.js";
 import { getRequestContext } from "../server/request-context.js";
 import { executeInterceptMiddleware } from "./middleware.js";
@@ -20,6 +24,7 @@ import { getGlobalRouteMap } from "../route-map-builder.js";
 import { handleHandlerResult } from "./segment-resolution.js";
 import type { SegmentResolutionDeps } from "./types.js";
 import { debugLog } from "./logging.js";
+import { runInsideLoaderScope } from "../server/context.js";
 
 /**
  * Check if an intercept's when conditions are satisfied.
@@ -133,7 +138,7 @@ export async function resolveInterceptEntry<TEnv>(
       context.request,
       context.env,
       params,
-      context.var as Record<string, any>,
+      (context as InternalHandlerContext<any, TEnv>)._variables,
       requestCtx.res,
       createReverseFunction(getGlobalRouteMap()),
     );
@@ -188,6 +193,7 @@ export async function resolveInterceptEntry<TEnv>(
           context,
           actionContext,
           stale,
+          traceSource: "intercept-loader",
         });
 
         if (!shouldRevalidate) {
@@ -206,7 +212,7 @@ export async function resolveInterceptEntry<TEnv>(
     loaderIds.push(loader.$$id);
     loaderPromises.push(
       deps.wrapLoaderPromise(
-        context.use(loader),
+        runInsideLoaderScope(() => context.use(loader)),
         parentEntry,
         segmentId,
         context.pathname,
@@ -355,6 +361,7 @@ export async function resolveInterceptLoadersOnly<TEnv>(
         context,
         actionContext,
         stale,
+        traceSource: "intercept-loader",
       });
 
       if (!shouldRevalidate) {
@@ -372,7 +379,7 @@ export async function resolveInterceptLoadersOnly<TEnv>(
     loaderIds.push(loader.$$id);
     loaderPromises.push(
       deps.wrapLoaderPromise(
-        context.use(loader),
+        runInsideLoaderScope(() => context.use(loader)),
         parentEntry,
         segmentId,
         context.pathname,
@@ -384,10 +391,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

@@ -1,9 +1,10 @@
 import { registerRouteMap } from "../route-map-builder.js";
 import { extractStaticPrefix } from "./pattern-matching.js";
 import {
-  EntryData,
+  type EntryData,
   RSCRouterContext,
   runWithPrefixes,
+  getIsolatedLazyParent,
 } from "../server/context";
 import type { UrlPatterns } from "../urls.js";
 import type { AllUseItems, IncludeItem } from "../route-types.js";
@@ -14,6 +15,7 @@ export interface LazyEvalDeps<TEnv = any> {
   mergedRouteMap: Record<string, string>;
   nextMountIndex: () => number;
   getPrecomputedByPrefix: () => Map<string, Record<string, string>> | null;
+  routerId?: string;
 }
 
 // Detect lazy includes in handler result and create placeholder entries
@@ -28,6 +30,7 @@ export function findLazyIncludes<TEnv = any>(
     urlPrefix: string;
     namePrefix: string | undefined;
     parent: unknown;
+    rootScoped?: boolean;
   };
 }> {
   const lazyItems: Array<{
@@ -37,6 +40,7 @@ export function findLazyIncludes<TEnv = any>(
       urlPrefix: string;
       namePrefix: string | undefined;
       parent: unknown;
+      rootScoped?: boolean;
     };
   }> = [];
 
@@ -121,9 +125,8 @@ export function evaluateLazyEntry<TEnv = any>(
   // Merge captured counters from include() to maintain consistent
   // shortCode indices with sibling entries from pattern extraction
   const lazyCounters: Record<string, number> = {};
-  if (lazyContext && (lazyContext as any).counters) {
-    const captured = (lazyContext as any).counters as Record<string, number>;
-    for (const [key, value] of Object.entries(captured)) {
+  if (lazyContext?.counters) {
+    for (const [key, value] of Object.entries(lazyContext.counters)) {
       lazyCounters[key] = value;
     }
   }
@@ -135,8 +138,11 @@ export function evaluateLazyEntry<TEnv = any>(
       patternsByPrefix,
       trailingSlash: trailingSlashMap,
       namespace: "lazy",
-      parent: (lazyContext?.parent as EntryData | null) ?? null,
+      parent: getIsolatedLazyParent(lazyContext?.parent as EntryData | null),
       counters: lazyCounters,
+      cacheProfiles: lazyContext?.cacheProfiles,
+      rootScoped: lazyContext?.rootScoped,
+      includeScope: lazyContext?.includeScope,
     },
     () => {
       // Run the lazy patterns handler with the original context prefixes
@@ -196,6 +202,7 @@ export function evaluateLazyEntry<TEnv = any>(
       trailingSlash: entry.trailingSlash,
       handler: (lazyInclude.patterns as UrlPatterns<TEnv>).handler,
       mountIndex: deps.nextMountIndex(),
+      routerId: deps.routerId,
       // Lazy evaluation fields
       lazy: true,
       lazyPatterns: lazyInclude.patterns,