@rangojs/router 0.0.0-experimental.fa8a383a → 0.0.0-experimental.fb4fdc18

package/src/route-definition/resolve-handler-use.ts

@@ -0,0 +1,155 @@
+import type { AllUseItems } from "../route-types.js";
+import { isPrerenderHandler, isPassthroughHandler } from "../prerender.js";
+import { isStaticHandler } from "../static-handler.js";
+
+/**
+ * Extract the .use callback from any handler shape.
+ *
+ * Checks definition brands first (objects with __brand), then plain functions.
+ * ReactNode handlers return undefined (no .use possible).
+ */
+export function resolveHandlerUse(handler: unknown): (() => any[]) | undefined {
+  if (handler == null) return undefined;
+
+  // Check branded definitions first — they're objects but also have typeof "object"
+  if (isPassthroughHandler(handler)) {
+    return (handler as any).use;
+  }
+  if (isPrerenderHandler(handler)) {
+    return (handler as any).use;
+  }
+  if (isStaticHandler(handler)) {
+    return (handler as any).use;
+  }
+  // Loader definitions from createLoader() — branded objects with optional .use
+  if (typeof handler === "object" && (handler as any).__brand === "loader") {
+    return (handler as any).use;
+  }
+  // Plain handler function
+  if (typeof handler === "function") {
+    return (handler as any).use;
+  }
+  // ReactNode or other — no .use
+  return undefined;
+}
+
+/**
+ * Allowed item types per mount site.
+ * Mirrors the RouteUseItem / ParallelUseItem / InterceptUseItem / LayoutUseItem unions
+ * from route-types.ts for runtime validation.
+ */
+const MOUNT_SITE_ALLOWED_TYPES: Record<string, Set<string>> = {
+  path: new Set([
+    "layout",
+    "parallel",
+    "intercept",
+    "middleware",
+    "revalidate",
+    "loader",
+    "loading",
+    "errorBoundary",
+    "notFoundBoundary",
+    "cache",
+    "transition",
+  ]),
+  // Response routes (path.json, path.text, etc.) — mirrors ResponseRouteUseItem
+  response: new Set(["middleware", "cache"]),
+  route: new Set([
+    "layout",
+    "parallel",
+    "intercept",
+    "middleware",
+    "revalidate",
+    "loader",
+    "loading",
+    "errorBoundary",
+    "notFoundBoundary",
+    "cache",
+    "transition",
+  ]),
+  // layout allows AllUseItems — no validation needed, but included for completeness
+  layout: new Set([
+    "layout",
+    "route",
+    "middleware",
+    "revalidate",
+    "parallel",
+    "intercept",
+    "loader",
+    "loading",
+    "errorBoundary",
+    "notFoundBoundary",
+    "cache",
+    "transition",
+    "include",
+  ]),
+  parallel: new Set([
+    "revalidate",
+    "loader",
+    "loading",
+    "errorBoundary",
+    "notFoundBoundary",
+    "transition",
+  ]),
+  intercept: new Set([
+    "middleware",
+    "revalidate",
+    "loader",
+    "loading",
+    "errorBoundary",
+    "notFoundBoundary",
+    "layout",
+    "route",
+    "when",
+    "transition",
+  ]),
+  // LoaderUseItem — only revalidate + cache can attach to a loader entry
+  loader: new Set(["revalidate", "cache"]),
+};
+
+/**
+ * Validate that items from handler.use() are valid for the given mount site.
+ * Throws a descriptive error if any item is not allowed.
+ */
+export function validateHandlerUseItems(
+  items: AllUseItems[],
+  mountSite: string,
+): void {
+  const allowed = MOUNT_SITE_ALLOWED_TYPES[mountSite];
+  if (!allowed) return;
+  for (const item of items) {
+    if (item == null) continue;
+    if (!allowed.has((item as any).type)) {
+      throw new Error(
+        `handler.use() returned ${(item as any).type}() which is not valid inside ${mountSite}(). ` +
+          `Allowed types: ${[...allowed].join(", ")}.`,
+      );
+    }
+  }
+}
+
+/**
+ * Create a merged use callback from handler.use and explicit use.
+ * handler.use items come first (defaults), explicit items second (overrides).
+ * Returns undefined if both are absent.
+ */
+export function mergeHandlerUse(
+  handlerUse: (() => any[]) | undefined,
+  explicitUse: (() => any[]) | undefined,
+  mountSite: string,
+): (() => any[]) | undefined {
+  if (!handlerUse && !explicitUse) return undefined;
+  if (!handlerUse) return explicitUse;
+  if (!explicitUse) {
+    return () => {
+      const items = handlerUse().flat(3);
+      validateHandlerUseItems(items, mountSite);
+      return items;
+    };
+  }
+  return () => {
+    const hItems = handlerUse().flat(3);
+    validateHandlerUseItems(hItems, mountSite);
+    return [...hItems, ...explicitUse()];
+  };
+}

package/src/route-types.ts

@@ -176,6 +176,13 @@ export type IncludeItem = {
     >;
     /** Root scope flag for dot-local reverse resolution */
     rootScoped?: boolean;
+    /**
+     * Positional include scope token composed from the parent scope plus this
+     * include's sibling index (`${parentScope}I${idx}`). Applied to direct-
+     * descendant shortCodes during lazy evaluation so routes inside the
+     * include cannot collide with siblings declared outside it.
+     */
+    includeScope?: string;
   };
   [IncludeBrand]: void;
 };
@@ -257,3 +264,14 @@ export type LoaderUseItem = RevalidateItem | CacheItem;
  * runtime via .flat(3).
  */
 export type UseItems<T> = (T | readonly T[])[];
+
+/**
+ * Union of all items that handler.use() may return.
+ * A handler doesn't know its mount site at definition time, so the type
+ * is intentionally broad — validation happens per-mount-site at runtime.
+ */
+export type HandlerUseItem =
+  | RouteUseItem
+  | LayoutUseItem
+  | ParallelUseItem
+  | InterceptUseItem;

package/src/router/content-negotiation.ts

@@ -2,10 +2,18 @@
  * Content Negotiation Utilities
  *
  * Pure functions for HTTP Accept header parsing and response type matching.
- * Used by createRouter's previewMatch for content negotiation between
+ * Used by previewMatch and classifyRequest for content negotiation between
  * RSC routes and response routes (JSON, text, image, stream, etc.).
  */
 
+import type { EntryData } from "../server/context.js";
+import type { CollectedMiddleware } from "./middleware-types.js";
+import { collectRouteMiddleware } from "./middleware.js";
+import { loadManifest } from "./manifest.js";
+import { traverseBack } from "./pattern-matching.js";
+import type { RouteMatchResult } from "./pattern-matching.js";
+import type { RouteSnapshot } from "./route-snapshot.js";
+
 // Response type -> MIME type used for Accept header matching
 export const RESPONSE_TYPE_MIME: Record<string, string> = {
   json: "application/json",
@@ -114,3 +122,94 @@ export function pickNegotiateVariant(
   // No match -- use first candidate as default
   return candidates[0]!;
 }
+
+/**
+ * Result of content negotiation for a route with negotiate variants.
+ */
+export interface NegotiationResult {
+  /** The winning response type */
+  responseType: string;
+  /** Handler function for the winning variant */
+  handler: Function;
+  /** Manifest entry for the winning variant (may differ from primary) */
+  manifestEntry: EntryData;
+  /** Route middleware for the winning variant */
+  routeMiddleware: CollectedMiddleware[];
+  /** Always true — negotiation occurred */
+  negotiated: true;
+}
+
+/**
+ * Perform content negotiation for a route with negotiate variants.
+ *
+ * Returns a NegotiationResult when a response route wins negotiation.
+ * Returns null when RSC wins or no negotiation is needed.
+ *
+ * Shared by previewMatch and classifyRequest to avoid duplicating
+ * the candidate-building and variant-loading logic.
+ */
+export async function negotiateRoute(
+  request: Request,
+  pathname: string,
+  snapshot: RouteSnapshot,
+): Promise<NegotiationResult | null> {
+  const { matched, manifestEntry, routeMiddleware, responseType } = snapshot;
+  if (!matched.negotiateVariants || matched.negotiateVariants.length === 0) {
+    return null;
+  }
+
+  const acceptEntries = parseAcceptTypes(request.headers.get("accept") || "");
+
+  // Build candidate list preserving definition order.
+  const variants = matched.negotiateVariants;
+  let candidates: Array<{ routeKey: string; responseType: string }>;
+  if (responseType) {
+    candidates = [...variants, { routeKey: matched.routeKey, responseType }];
+  } else {
+    const rscCandidate = {
+      routeKey: matched.routeKey,
+      responseType: RSC_RESPONSE_TYPE,
+    };
+    candidates = matched.rscFirst
+      ? [rscCandidate, ...variants]
+      : [...variants, rscCandidate];
+  }
+
+  const variant = pickNegotiateVariant(acceptEntries, candidates);
+
+  // RSC won negotiation
+  if (variant.responseType === RSC_RESPONSE_TYPE) {
+    return null;
+  }
+
+  // Primary response-type won — use existing manifest entry and middleware
+  if (responseType && variant.routeKey === matched.routeKey) {
+    return {
+      responseType,
+      handler: manifestEntry.handler as Function,
+      manifestEntry,
+      routeMiddleware,
+      negotiated: true,
+    };
+  }
+
+  // Different variant won — load its manifest entry
+  const negotiateEntry = await loadManifest(
+    matched.entry,
+    variant.routeKey,
+    pathname,
+    undefined,
+    false,
+  );
+  const variantMiddleware = collectRouteMiddleware(
+    traverseBack(negotiateEntry),
+    matched.params,
+  );
+  return {
+    responseType: variant.responseType,
+    handler: negotiateEntry.handler as Function,
+    manifestEntry: negotiateEntry,
+    routeMiddleware: variantMiddleware,
+    negotiated: true,
+  };
+}

package/src/router/handler-context.ts

@@ -8,10 +8,18 @@ import type { HandlerContext, InternalHandlerContext } from "../types";
 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 {
+  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.
@@ -108,9 +116,9 @@ function createPrerenderPassthroughFn(
     }
     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.",
+        "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;
@@ -160,17 +168,43 @@ export function createReverseFunction(
       : hrefParams;
 
     // 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,
+        /:([a-zA-Z_][a-zA-Z0-9_]*)(\([^)]*\))?(\?)/g,
+        (_, key) => {
+          const value = effectiveParams[key];
+          // The matcher omits absent optional params (so `value` is
+          // `undefined` here), but caller-supplied params or `getParams()`
+          // shapes may still pass `""` explicitly. Treat both as the
+          // absent form so the segment collapses cleanly.
+          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,
         (_, 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
@@ -201,7 +235,7 @@ export function createHandlerContext<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 variables: any = requestContext?._variables ?? {};
 
   // If route has a search schema, parse URLSearchParams into typed object
   const searchSchema = routeName ? getSearchSchema(routeName) : undefined;
@@ -213,7 +247,7 @@ export function createHandlerContext<TEnv>(
   const stubResponse =
     requestContext?.res ?? new Response(null, { status: 200 });
 
-  // Guard mutating Headers methods so they throw inside "use cache" functions.
+  // 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"]);
@@ -225,6 +259,13 @@ export function createHandlerContext<TEnv>(
         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);
           };
         }
@@ -237,21 +278,36 @@ export function createHandlerContext<TEnv>(
   ctx = {
     params,
     build: false,
+    dev: false,
     request,
     searchParams,
     search: searchSchema ? resolvedSearchParams : {},
     pathname,
     url,
-    originalUrl: new URL(request.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) => {
+    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");
-      contextSet(variables, keyOrVar, value);
+      // 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"],
     res: stubResponse, // Stub response for setting headers
     headers: guardedHeaders, // Guarded shorthand for res.headers
@@ -297,7 +353,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>,
@@ -306,6 +362,8 @@ export function createPrerenderContext<TEnv>(
   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 ?? {};
@@ -320,6 +378,7 @@ export function createPrerenderContext<TEnv>(
   return {
     params,
     build: true,
+    dev: devMode ?? false,
     get request(): Request {
       return throwUnavailable("request");
     },
@@ -329,11 +388,19 @@ export function createPrerenderContext<TEnv>(
     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);
@@ -379,6 +446,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> = {};
 
@@ -394,6 +463,7 @@ export function createStaticContext<TEnv>(
       return throwUnavailable("params");
     },
     build: true,
+    dev: devMode ?? false,
     get request(): Request {
       return throwUnavailable("request");
     },
@@ -413,11 +483,18 @@ export function createStaticContext<TEnv>(
       return throwUnavailable("originalUrl");
     },
     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 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);

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()),
     );
@@ -207,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,
@@ -374,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,

package/src/router/lazy-includes.ts

@@ -1,7 +1,7 @@
 import { registerRouteMap } from "../route-map-builder.js";
 import { extractStaticPrefix } from "./pattern-matching.js";
 import {
-  EntryData,
+  type EntryData,
   RSCRouterContext,
   runWithPrefixes,
   getIsolatedLazyParent,
@@ -125,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;
     }
   }
@@ -141,8 +140,9 @@ export function evaluateLazyEntry<TEnv = any>(
       namespace: "lazy",
       parent: getIsolatedLazyParent(lazyContext?.parent as EntryData | null),
       counters: lazyCounters,
-      cacheProfiles: (lazyContext as any)?.cacheProfiles,
-      rootScoped: (lazyContext as any)?.rootScoped,
+      cacheProfiles: lazyContext?.cacheProfiles,
+      rootScoped: lazyContext?.rootScoped,
+      includeScope: lazyContext?.includeScope,
     },
     () => {
       // Run the lazy patterns handler with the original context prefixes