@rangojs/router 0.0.0-experimental.18 → 0.0.0-experimental.1878aa49

package/src/router/prerender-match.ts

@@ -11,6 +11,8 @@ import {
   createStaticContext,
   createReverseFunction,
 } from "./handler-context.js";
+import { isPrerenderPassthrough } from "../prerender.js";
+import { isRouteRootScoped } from "../route-map-builder.js";
 import { setupBuildUse } from "./loader-resolution.js";
 import { loadManifest } from "./manifest.js";
 import { traverseBack } from "./pattern-matching.js";
@@ -51,6 +53,7 @@ export async function matchForPrerender<TEnv = any>(
   params: Record<string, string>,
   deps: PrerenderMatchDeps<TEnv>,
   buildVars?: Record<string, any>,
+  isPassthroughRoute?: boolean,
 ): Promise<{
   segments: SerializedSegmentData[];
   handles: Record<string, SegmentHandleData>;
@@ -58,6 +61,7 @@ export async function matchForPrerender<TEnv = any>(
   params: Record<string, string>;
   interceptSegments?: SerializedSegmentData[];
   interceptHandles?: Record<string, SegmentHandleData>;
+  passthrough?: true;
 } | null> {
   // 1. Find the matching route entry
   const matched = deps.findMatch(pathname);
@@ -65,6 +69,7 @@ export async function matchForPrerender<TEnv = any>(
 
   // Use params from trie match if available, fall back to provided params
   const matchedParams = matched.params ?? params;
+  const matchedPassthroughRoute = isPassthroughRoute ?? matched.pt === true;
 
   // Build RouterContext for loadManifest/traverseBack
   const routerCtx = deps.buildRouterContext();
@@ -96,9 +101,10 @@ export async function matchForPrerender<TEnv = any>(
       env: {} as TEnv,
       request: new Request("http://prerender" + pathname),
       url: new URL("http://prerender" + pathname),
+      originalUrl: new URL("http://prerender" + pathname),
       pathname,
       searchParams: new URLSearchParams(),
-      var: variables,
+      _variables: variables,
       get: ((keyOrVar: any) => contextGet(variables, keyOrVar)) as any,
       set: ((keyOrVar: any, value: any) => {
         contextSet(variables, keyOrVar, value);
@@ -111,6 +117,7 @@ export async function matchForPrerender<TEnv = any>(
       deleteCookie: () => {},
       header: () => {},
       setStatus: () => {},
+      _setStatus: () => {},
       use: (() => {
         throw new Error("use() not available during pre-rendering");
       }) as any,
@@ -121,10 +128,12 @@ export async function matchForPrerender<TEnv = any>(
       _onResponseCallbacks: [],
       setLocationState() {},
       _locationState: undefined,
+      _reportedErrors: new WeakSet<object>(),
       reverse: createReverseFunction(
         deps.mergedRouteMap,
         matched.routeKey,
         matchedParams,
+        matched.routeKey ? isRouteRootScoped(matched.routeKey) : undefined,
       ),
     };
 
@@ -138,6 +147,7 @@ export async function matchForPrerender<TEnv = any>(
         deps.mergedRouteMap,
         matched.routeKey,
         variables,
+        matchedPassthroughRoute,
       );
 
       // 7. Wire use() for handles only (loaders throw)
@@ -154,17 +164,31 @@ export async function matchForPrerender<TEnv = any>(
         { skipLoaders: true },
       );
 
-      // 9. Filter out any loader segments (belt-and-suspenders)
+      // 9. Detect passthrough sentinel: handler returned ctx.passthrough()
+      for (const seg of allSegments) {
+        if (isPrerenderPassthrough(seg.component)) {
+          return {
+            segments: [],
+            handles: {},
+            routeName: matched.routeKey,
+            params: matchedParams,
+            passthrough: true as const,
+          };
+        }
+      }
+
+      // 10. Filter out any loader segments (belt-and-suspenders)
       const nonLoaderSegments = allSegments.filter((s) => s.type !== "loader");
 
-      // 10. Wait for handles to settle
+      // 11. Wait for handles to settle
+      handleStore.seal();
       await handleStore.settled;
 
-      // 11. Serialize segments using the cache serializer
+      // 12. Serialize segments using the cache serializer
       const { serializeSegments } = await import("../cache/segment-codec.js");
       const serializedSegments = await serializeSegments(nonLoaderSegments);
 
-      // 12. Collect handle data per segment (skip segments with no handle data)
+      // 13. Collect handle data per segment (skip segments with no handle data)
       const handles: Record<string, SegmentHandleData> = {};
       for (const seg of nonLoaderSegments) {
         const segHandles = handleStore.getDataForSegment(seg.id);
@@ -176,7 +200,7 @@ export async function matchForPrerender<TEnv = any>(
       // Use the trie-level route key (e.g., "docs", "docs.article")
       const routeName = matched.routeKey;
 
-      // 13. Resolve intercept segments for this route (if any ancestor defines
+      // 14. Resolve intercept segments for this route (if any ancestor defines
       //     an intercept targeting this route). At build time we skip when()
       //     evaluation -- we pre-render all intercepts unconditionally and let
       //     runtime matching decide which to serve.
@@ -309,9 +333,10 @@ export async function renderStaticSegment<TEnv = any>(
     env: {} as TEnv,
     request: syntheticRequest,
     url: syntheticUrl,
+    originalUrl: syntheticUrl,
     pathname: "/",
     searchParams: syntheticUrl.searchParams,
-    var: {},
+    _variables: {},
     get: () => undefined as any,
     set: () => {},
     params: {},
@@ -322,6 +347,7 @@ export async function renderStaticSegment<TEnv = any>(
     deleteCookie: () => {},
     header: () => {},
     setStatus: () => {},
+    _setStatus: () => {},
     use: (() => {
       throw new Error("use() not available during static pre-rendering");
     }) as any,
@@ -332,7 +358,13 @@ export async function renderStaticSegment<TEnv = any>(
     _onResponseCallbacks: [],
     setLocationState() {},
     _locationState: undefined,
-    reverse: createReverseFunction(mergedRouteMap, routeName, {}),
+    _reportedErrors: new WeakSet<object>(),
+    reverse: createReverseFunction(
+      mergedRouteMap,
+      routeName,
+      {},
+      routeName ? isRouteRootScoped(routeName) : undefined,
+    ),
   };
 
   return runWithRequestContext(minimalRequestContext, async () => {

package/src/router/preview-match.ts

@@ -122,9 +122,15 @@ export async function previewMatch<TEnv = any>(
               undefined,
               false,
             );
+            // Recompute middleware from the selected variant's entry tree
+            // since different variants can have different middleware chains.
+            const variantMiddleware = collectRouteMiddleware(
+              traverseBack(negotiateEntry),
+              matched.params,
+            );
             return {
               routeMiddleware:
-                routeMiddleware.length > 0 ? routeMiddleware : undefined,
+                variantMiddleware.length > 0 ? variantMiddleware : undefined,
               responseType: variant.responseType,
               handler:
                 negotiateEntry.type === "route"

package/src/router/revalidation.ts

@@ -6,7 +6,14 @@
 
 import type { ResolvedSegment, HandlerContext } from "../types";
 import type { ActionContext } from "./types";
-import { debugLog } from "./logging.js";
+import {
+  debugLog,
+  pushRevalidationTraceEntry,
+  isTraceActive,
+} from "./logging.js";
+import type { RevalidationTraceEntry } from "./logging.js";
+import { _getRequestContext } from "../server/request-context.js";
+import { isAutoGeneratedRouteName } from "../route-name.js";
 
 function paramsEqual(
   a: Record<string, string>,
@@ -50,6 +57,8 @@ interface EvaluateRevalidationOptions<TEnv> {
   actionContext?: ActionContext;
   /** If true, this is a stale cache revalidation request */
   stale?: boolean;
+  /** Trace source hint for the revalidation trace */
+  traceSource?: RevalidationTraceEntry["source"];
 }
 
 /**
@@ -71,47 +80,97 @@ export async function evaluateRevalidation<TEnv>(
     context,
     actionContext,
     stale,
+    traceSource,
   } = options;
   const nextParams = segment.params || {};
   const paramsChanged = !paramsEqual(nextParams, prevParams);
+  const searchChanged = prevUrl.search !== nextUrl.search;
+
+  // Trace helper: push a structured entry to the request-scoped trace buffer.
+  // Guarded by isTraceActive() so object construction is skipped in production.
+  function pushTrace(
+    defaultVal: boolean,
+    finalVal: boolean,
+    reason: string,
+  ): void {
+    if (!isTraceActive()) return;
+    pushRevalidationTraceEntry({
+      segmentId: segment.id,
+      segmentType: segment.type,
+      belongsToRoute: segment.belongsToRoute ?? false,
+      source: traceSource ?? "segment-resolution",
+      defaultShouldRevalidate: defaultVal,
+      finalShouldRevalidate: finalVal,
+      reason,
+      customRevalidators: revalidations.length || undefined,
+    });
+  }
 
   // Calculate default revalidation based on segment type and request method
   let defaultShouldRevalidate: boolean;
+  let defaultReason: string;
 
   if (request.method === "POST") {
     // Actions: revalidate segments that belong to the route, skip parent chain
     if (segment.type === "route") {
       // Route segment always revalidates on actions
       defaultShouldRevalidate = true;
+      defaultReason = "action:route-segment";
     } else if (segment.type === "loader") {
       // Loaders always revalidate on actions - they often contain action-sensitive data
       // (e.g., cart count after add-to-cart action)
       defaultShouldRevalidate = true;
+      defaultReason = "action:loader-segment";
     } else if (segment.belongsToRoute) {
       // Segment belongs to route (orphan layouts/parallels) - revalidate
       defaultShouldRevalidate = true;
+      defaultReason = "action:belongs-to-route";
     } else {
       // Parent chain segment (shared layouts/parallels) - don't revalidate
       defaultShouldRevalidate = false;
+      defaultReason = "action:parent-chain-skip";
     }
   } else {
     // Navigation (GET): Conservative defaults to minimize unnecessary revalidations
     // Only the route segment revalidates by default - all others require explicit opt-in
 
     if (segment.type === "route") {
-      // Route segments revalidate when params change
-      // Routes are the primary param-dependent content and always need updates
-      defaultShouldRevalidate = paramsChanged;
-      if (paramsChanged) {
-        debugLog("revalidation", "route params changed, revalidating", {
+      // Route segments revalidate when path params OR search params change.
+      // Search params (e.g., ?page=2&sort=price) are server-parsed via ctx.search,
+      // so the handler must re-execute to produce updated content.
+      const routeChanged = paramsChanged || searchChanged;
+      defaultShouldRevalidate = routeChanged;
+      defaultReason = paramsChanged
+        ? "nav:params-changed"
+        : searchChanged
+          ? "nav:search-changed"
+          : "nav:params-unchanged";
+      if (routeChanged) {
+        debugLog("revalidation", "route revalidating", {
           segmentId: segment.id,
+          paramsChanged,
+          searchChanged,
         });
       }
+    } else if (segment.belongsToRoute && (paramsChanged || searchChanged)) {
+      // Children of the route path (loaders, orphan layouts/parallels)
+      // revalidate when path params or search params change
+      defaultShouldRevalidate = true;
+      defaultReason = paramsChanged
+        ? "nav:route-child-params-changed"
+        : "nav:route-child-search-changed";
+      debugLog("revalidation", "route child revalidating", {
+        segmentId: segment.id,
+        segmentType: segment.type,
+        paramsChanged,
+        searchChanged,
+      });
     } else {
-      // Layouts and parallels default to no revalidation
+      // Parent layouts and parallels default to no revalidation
       // Cannot assume these segments depend on params without explicit declaration
       // Use custom revalidation functions to opt-in when needed
       defaultShouldRevalidate = false;
+      defaultReason = "nav:non-route-skip";
       debugLog("revalidation", "non-route segment skipped by default", {
         segmentId: segment.id,
         segmentType: segment.type,
@@ -132,6 +191,7 @@ export async function evaluateRevalidation<TEnv>(
         segmentId: segment.id,
       });
     }
+    pushTrace(defaultShouldRevalidate, defaultShouldRevalidate, defaultReason);
     return defaultShouldRevalidate;
   }
 
@@ -142,6 +202,16 @@ export async function evaluateRevalidation<TEnv>(
   // Execute revalidation functions with soft/hard decision pattern
   let currentSuggestion = defaultShouldRevalidate;
 
+  // Compute public route names (filtered: undefined for auto-generated routes)
+  const toRouteName =
+    routeKey && !isAutoGeneratedRouteName(routeKey) ? routeKey : undefined;
+  const reqCtx = _getRequestContext();
+  const prevRouteKey = reqCtx?._prevRouteKey;
+  const fromRouteName =
+    prevRouteKey && !isAutoGeneratedRouteName(prevRouteKey)
+      ? prevRouteKey
+      : undefined;
+
   for (const { name, fn } of revalidations) {
     const result = fn({
       currentParams: prevSegment?.params || prevParams, // Use segment params if available, else route params
@@ -160,7 +230,9 @@ export async function evaluateRevalidation<TEnv>(
       actionResult: actionContext?.actionResult,
       formData: actionContext?.formData,
       method: request.method, // GET for navigation, POST for actions
-      routeName: routeKey, // User-friendly route name (e.g., "products.detail")
+      routeName: toRouteName, // Navigation target route name (filtered)
+      fromRouteName, // Navigation source route name (filtered)
+      toRouteName, // Navigation target route name (filtered)
       // Stale cache context (only true for background revalidation after stale cache render)
       stale,
     });
@@ -176,6 +248,7 @@ export async function evaluateRevalidation<TEnv>(
         revalidator: name,
         revalidate: result,
       });
+      pushTrace(defaultShouldRevalidate, result, `hard:${name}`);
       return result;
     } else if (
       result &&
@@ -206,5 +279,11 @@ export async function evaluateRevalidation<TEnv>(
     segmentId: segment.id,
     revalidate: currentSuggestion,
   });
+  const softNames = revalidations.map((r) => r.name).join(",");
+  pushTrace(
+    defaultShouldRevalidate,
+    currentSuggestion,
+    `soft-chain:${softNames}`,
+  );
   return currentSuggestion;
 }

package/src/router/router-context.ts

@@ -18,6 +18,7 @@ import type {
   ShouldRevalidateFn,
 } from "../types.js";
 import type { RouteMatchResult } from "./pattern-matching.js";
+import type { TelemetrySink } from "./telemetry.js";
 
 /**
  * Revalidation context passed to segment resolution
@@ -79,6 +80,7 @@ export interface RouterContext<TEnv = any> {
     routeMap?: Record<string, string>,
     routeName?: string,
     responseType?: string,
+    isPassthroughRoute?: boolean,
   ) => HandlerContext<any, TEnv>;
 
   // Loader setup
@@ -136,6 +138,7 @@ export interface RouterContext<TEnv = any> {
     interceptResult: InterceptResult | null,
     localRouteName: string,
     pathname: string,
+    stale?: boolean,
   ) => Promise<{ segments: ResolvedSegment[]; matchedIds: string[] }>;
 
   // Generator-based segment resolution (for pipeline)
@@ -181,6 +184,15 @@ export interface RouterContext<TEnv = any> {
     context: HandlerContext<any, TEnv>;
     actionContext?: any;
     stale?: boolean;
+    traceSource?:
+      | "segment-resolution"
+      | "cache-hit"
+      | "loader"
+      | "parallel"
+      | "orphan-layout"
+      | "route-handler"
+      | "layout-handler"
+      | "intercept-loader";
   }) => Promise<boolean>;
 
   // Request context
@@ -198,6 +210,7 @@ export interface RouterContext<TEnv = any> {
     params: Record<string, string>,
     handlerContext: HandlerContext<any, TEnv>,
     loaderPromises: Map<string, Promise<any>>,
+    options?: { skipLoaders?: boolean },
   ) => Promise<ResolvedSegment[]>;
 
   // Generator-based simple resolution
@@ -234,6 +247,7 @@ export interface RouterContext<TEnv = any> {
     nextUrl: URL,
     routeKey: string,
     actionContext?: any,
+    stale?: boolean,
   ) => Promise<{ segments: ResolvedSegment[]; matchedIds: string[] }>;
 
   // Entry revalidation map
@@ -241,6 +255,12 @@ export interface RouterContext<TEnv = any> {
     entries: EntryData[],
   ) => Map<string, { revalidate: ShouldRevalidateFn[] }>;
 
+  // Telemetry sink (optional, no-op when undefined)
+  telemetry?: TelemetrySink;
+
+  // Request ID for telemetry span correlation (set per-request in match handlers)
+  requestId?: string;
+
   // Intercept loaders only (for cache hit + intercept scenarios)
   resolveInterceptLoadersOnly?: (
     intercept: InterceptEntry,

package/src/router/router-interfaces.ts

@@ -2,6 +2,7 @@ import type { ComponentType, ReactNode } from "react";
 import type { SerializedManifest } from "../debug.js";
 import type { ReverseFunction } from "../reverse.js";
 import type { UrlPatterns } from "../urls.js";
+import type { UrlBuilder } from "../urls/pattern-types.js";
 import type { EntryData } from "../server/context";
 import type { ErrorInfo, MatchResult } from "../types";
 import type { NonceProvider } from "../rsc/types.js";
@@ -14,6 +15,7 @@ import type { MiddlewareEntry, MiddlewareFn } from "./middleware.js";
 import { RSC_ROUTER_BRAND } from "./router-registry.js";
 import type { RSCRouterOptions, RootLayoutProps } from "./router-options.js";
 import type { DefaultVars } from "../types/global-namespace.js";
+import type { ResolvedTimeouts, OnTimeoutCallback } from "./timeout.js";
 
 /**
  * Options passed to router.fetch(), router.match(), and other request entrypoints.
@@ -67,12 +69,24 @@ export interface RSCRouter<
   readonly id: string;
 
   /**
-   * Register routes using URL patterns from urls()
+   * URL prefix applied to all routes. Undefined when no basename is configured.
+   */
+  readonly basename: string | undefined;
+
+  /**
+   * Register routes using URL patterns from urls() or a builder function
    *
    * @example
    * ```typescript
-   * createRouter({})
-   *   .routes(urlpatterns)
+   * // With urls()
+   * createRouter({}).routes(urlpatterns)
+   *
+   * // With builder function (urls() is implicit)
+   * createRouter({}).routes(({ path, layout }) => [
+   *   layout(RootLayout, () => [
+   *     path("/", HomePage),
+   *   ]),
+   * ])
    * ```
    */
   routes<T extends UrlPatterns<TEnv, any>>(
@@ -84,6 +98,7 @@ export interface RSCRouter<
         ? MergeRoutesWithResponses<NonNullable<T["_routes"]>, T["_responses"]>
         : Record<string, string>)
   >;
+  routes(builder: UrlBuilder<TEnv>): RSCRouter<TEnv, TRoutes>;
 
   /**
    * Add global middleware that runs on all routes
@@ -187,8 +202,11 @@ export interface RSCRouterInternal<
    */
   readonly id: string;
 
+  /** URL prefix applied to all routes. */
+  readonly basename: string | undefined;
+
   /**
-   * Register routes using URL patterns from urls()
+   * Register routes using URL patterns from urls() or a builder function
    */
   routes<T extends UrlPatterns<TEnv, any>>(
     patterns: T,
@@ -199,6 +217,7 @@ export interface RSCRouterInternal<
         ? MergeRoutesWithResponses<NonNullable<T["_routes"]>, T["_responses"]>
         : Record<string, string>)
   >;
+  routes(builder: UrlBuilder<TEnv>): RSCRouter<TEnv, TRoutes>;
 
   /**
    * Add global middleware that runs on all routes
@@ -246,12 +265,28 @@ export interface RSCRouterInternal<
    */
   readonly themeConfig: import("../theme/types.js").ResolvedThemeConfig | null;
 
+  /**
+   * Cache profiles for "use cache" per-request resolution.
+   * Always includes at least the "default" profile.
+   */
+  readonly cacheProfiles: Record<
+    string,
+    import("../cache/profile-registry.js").CacheProfile
+  >;
+
   /**
    * Cache-Control header value for prefetch responses.
-   * False means no browser caching of prefetch responses.
+   * False means no caching of prefetch responses.
+   * Derived from prefetchCacheTTL.
    */
   readonly prefetchCacheControl: string | false;
 
+  /**
+   * TTL in milliseconds for the client-side in-memory prefetch cache.
+   * 0 means caching is disabled.
+   */
+  readonly prefetchCacheTTL: number;
+
   /**
    * Whether connection warmup is enabled.
    * When true, the client sends HEAD /?_rsc_warmup after idle periods
@@ -259,12 +294,28 @@ export interface RSCRouterInternal<
    */
   readonly warmupEnabled: boolean;
 
+  /**
+   * Whether router-wide performance debugging is enabled.
+   * Used by the request handler to create metrics before middleware runs.
+   */
+  readonly debugPerformance?: boolean;
+
   /**
    * Whether ?__debug_manifest is allowed in production.
    * Always enabled in development.
    */
   readonly allowDebugManifest: boolean;
 
+  /**
+   * Resolved timeout configuration (merged from shorthand + structured).
+   */
+  readonly timeouts: ResolvedTimeouts;
+
+  /**
+   * Custom timeout response handler.
+   */
+  readonly onTimeout?: OnTimeoutCallback<TEnv>;
+
   /**
    * App-level middleware entries
    * These wrap the entire request/response cycle
@@ -286,6 +337,18 @@ export interface RSCRouterInternal<
    */
   readonly urlpatterns?: UrlPatterns<TEnv, any>;
 
+  /**
+   * SSR configuration. resolveStreaming determines stream vs allReady
+   * per HTML request (undefined = always stream).
+   */
+  readonly ssr?: import("./router-options.js").SSROptions<TEnv>;
+
+  /**
+   * Cross-origin request protection configuration.
+   * Default: true (enabled).
+   */
+  readonly originCheck: import("../rsc/origin-guard.js").OriginCheckConfig<TEnv>;
+
   /**
    * Source file path where createRouter() was called.
    * Set via Error.stack parsing at construction time.
@@ -293,6 +356,9 @@ export interface RSCRouterInternal<
    */
   readonly __sourceFile?: string;
 
+  /** @internal basename for runtime manifest generation */
+  readonly __basename?: string;
+
   match(
     request: Request,
     input?: RouterRequestInput<TEnv>,
@@ -307,6 +373,7 @@ export interface RSCRouterInternal<
     pathname: string,
     params: Record<string, string>,
     buildVars?: Record<string, any>,
+    isPassthroughRoute?: boolean,
   ): Promise<{
     segments: SerializedSegmentData[];
     handles: Record<string, SegmentHandleData>;
@@ -314,6 +381,7 @@ export interface RSCRouterInternal<
     params: Record<string, string>;
     interceptSegments?: SerializedSegmentData[];
     interceptHandles?: Record<string, SegmentHandleData>;
+    passthrough?: true;
   } | null>;
 
   /**