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

package/src/router/pattern-matching.ts

@@ -16,6 +16,7 @@ export interface ParsedSegment {
   value: string; // static text, param name, or "*"
   optional: boolean;
   constraint?: string[]; // enum values like ["en", "gb"]
+  suffix?: string; // literal text after param in same segment (e.g., ".html")
 }
 
 /**
@@ -39,11 +40,21 @@ export function parsePattern(pattern: string): ParsedSegment[] {
   // - :param(a|b)?
   // - *
   const segmentRegex =
-    /\/(:([a-zA-Z_][a-zA-Z0-9_]*)(\(([^)]+)\))?(\?)?|(\*)|([^/]+))/g;
+    /\/(:([a-zA-Z_][a-zA-Z0-9_]*)(\(([^)]+)\))?(\?)?([^/]*)|(\*)|([^/]+))/g;
 
   let match;
   while ((match = segmentRegex.exec(pattern)) !== null) {
-    const [, , paramName, , constraint, optional, wildcard, staticText] = match;
+    const [
+      ,
+      ,
+      paramName,
+      ,
+      constraint,
+      optional,
+      suffix,
+      wildcard,
+      staticText,
+    ] = match;
 
     if (wildcard) {
       segments.push({ type: "wildcard", value: "*", optional: false });
@@ -53,6 +64,7 @@ export function parsePattern(pattern: string): ParsedSegment[] {
         value: paramName,
         optional: optional === "?",
         constraint: constraint ? constraint.split("|") : undefined,
+        suffix: suffix || undefined,
       });
     } else if (staticText) {
       segments.push({ type: "static", value: staticText, optional: false });
@@ -139,16 +151,19 @@ export function compilePattern(pattern: string): CompiledPattern {
       regexPattern += "/(.*)";
     } else if (segment.type === "param") {
       paramNames.push(segment.value);
+      const suffixPattern = segment.suffix ? escapeRegex(segment.suffix) : "";
       const valuePattern = segment.constraint
-        ? `(${segment.constraint.join("|")})`
-        : "([^/]+)";
+        ? `(${segment.constraint.map(escapeRegex).join("|")})`
+        : segment.suffix
+          ? "([^/]+?)"
+          : "([^/]+)";
 
       if (segment.optional) {
         optionalParams.add(segment.value);
         // Optional: make the whole /segment optional
-        regexPattern += `(?:/${valuePattern})?`;
+        regexPattern += `(?:/${valuePattern}${suffixPattern})?`;
       } else {
-        regexPattern += `/${valuePattern}`;
+        regexPattern += `/${valuePattern}${suffixPattern}`;
       }
     } else {
       // Static segment
@@ -388,6 +403,9 @@ export function findMatch<TEnv>(
       const prFlag = entry.prerenderRouteKeys?.has(routeKey)
         ? { pr: true as const }
         : {};
+      const ptFlag = entry.passthroughRouteKeys?.has(routeKey)
+        ? { pt: true as const }
+        : {};
 
       // Try exact match first
       const match = regex.exec(pathname);
@@ -419,6 +437,7 @@ export function findMatch<TEnv>(
             optionalParams,
             redirectTo: pathname + "/",
             ...prFlag,
+            ...ptFlag,
           };
         } else if (trailingSlashMode === "never" && pathnameHasTrailingSlash) {
           // Mode says never have trailing slash, but pathname has it
@@ -429,10 +448,18 @@ export function findMatch<TEnv>(
             optionalParams,
             redirectTo: pathname.slice(0, -1),
             ...prFlag,
+            ...ptFlag,
           };
         }
 
-        return { entry, routeKey, params, optionalParams, ...prFlag };
+        return {
+          entry,
+          routeKey,
+          params,
+          optionalParams,
+          ...prFlag,
+          ...ptFlag,
+        };
       }
 
       // Try alternate pathname (opposite trailing slash)
@@ -446,7 +473,14 @@ export function findMatch<TEnv>(
         // Determine redirect behavior based on mode
         if (trailingSlashMode === "ignore") {
           // Match without redirect
-          return { entry, routeKey, params, optionalParams, ...prFlag };
+          return {
+            entry,
+            routeKey,
+            params,
+            optionalParams,
+            ...prFlag,
+            ...ptFlag,
+          };
         } else if (trailingSlashMode === "never") {
           // Redirect to no trailing slash
           if (pathnameHasTrailingSlash) {
@@ -457,9 +491,17 @@ export function findMatch<TEnv>(
               optionalParams,
               redirectTo: alternatePathname,
               ...prFlag,
+              ...ptFlag,
             };
           }
-          return { entry, routeKey, params, optionalParams, ...prFlag };
+          return {
+            entry,
+            routeKey,
+            params,
+            optionalParams,
+            ...prFlag,
+            ...ptFlag,
+          };
         } else if (trailingSlashMode === "always") {
           // Redirect to with trailing slash
           if (!pathnameHasTrailingSlash) {
@@ -470,9 +512,17 @@ export function findMatch<TEnv>(
               optionalParams,
               redirectTo: alternatePathname,
               ...prFlag,
+              ...ptFlag,
             };
           }
-          return { entry, routeKey, params, optionalParams, ...prFlag };
+          return {
+            entry,
+            routeKey,
+            params,
+            optionalParams,
+            ...prFlag,
+            ...ptFlag,
+          };
         } else {
           // No explicit mode - use pattern-based detection
           // Redirect to canonical form (what the pattern defines)
@@ -486,6 +536,7 @@ export function findMatch<TEnv>(
             optionalParams,
             redirectTo: canonicalPath,
             ...prFlag,
+            ...ptFlag,
           };
         }
       }

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();
@@ -110,6 +115,7 @@ export async function matchForPrerender<TEnv = any>(
       setCookie: () => {},
       deleteCookie: () => {},
       header: () => {},
+      setStatus: () => {},
       use: (() => {
         throw new Error("use() not available during pre-rendering");
       }) as any,
@@ -120,10 +126,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,
       ),
     };
 
@@ -137,6 +145,7 @@ export async function matchForPrerender<TEnv = any>(
         deps.mergedRouteMap,
         matched.routeKey,
         variables,
+        matchedPassthroughRoute,
       );
 
       // 7. Wire use() for handles only (loaders throw)
@@ -153,17 +162,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);
@@ -175,7 +198,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.
@@ -320,6 +343,7 @@ export async function renderStaticSegment<TEnv = any>(
     setCookie: () => {},
     deleteCookie: () => {},
     header: () => {},
+    setStatus: () => {},
     use: (() => {
       throw new Error("use() not available during static pre-rendering");
     }) as any,
@@ -330,7 +354,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,28 +80,54 @@ export async function evaluateRevalidation<TEnv>(
     context,
     actionContext,
     stale,
+    traceSource,
   } = options;
   const nextParams = segment.params || {};
   const paramsChanged = !paramsEqual(nextParams, prevParams);
 
+  // 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
@@ -102,16 +137,29 @@ export async function evaluateRevalidation<TEnv>(
       // Route segments revalidate when params change
       // Routes are the primary param-dependent content and always need updates
       defaultShouldRevalidate = paramsChanged;
+      defaultReason = paramsChanged
+        ? "nav:params-changed"
+        : "nav:params-unchanged";
       if (paramsChanged) {
         debugLog("revalidation", "route params changed, revalidating", {
           segmentId: segment.id,
         });
       }
+    } else if (segment.belongsToRoute && paramsChanged) {
+      // Children of the route path (loaders, orphan layouts/parallels)
+      // revalidate when params change — they likely depend on route params
+      defaultShouldRevalidate = true;
+      defaultReason = "nav:route-child-params-changed";
+      debugLog("revalidation", "route child revalidating (params changed)", {
+        segmentId: segment.id,
+        segmentType: segment.type,
+      });
     } 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 +180,7 @@ export async function evaluateRevalidation<TEnv>(
         segmentId: segment.id,
       });
     }
+    pushTrace(defaultShouldRevalidate, defaultShouldRevalidate, defaultReason);
     return defaultShouldRevalidate;
   }
 
@@ -142,6 +191,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 +219,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 +237,7 @@ export async function evaluateRevalidation<TEnv>(
         revalidator: name,
         revalidate: result,
       });
+      pushTrace(defaultShouldRevalidate, result, `hard:${name}`);
       return result;
     } else if (
       result &&
@@ -206,5 +268,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
@@ -181,6 +183,12 @@ export interface RouterContext<TEnv = any> {
     context: HandlerContext<any, TEnv>;
     actionContext?: any;
     stale?: boolean;
+    traceSource?:
+      | "segment-resolution"
+      | "cache-hit"
+      | "loader"
+      | "parallel"
+      | "orphan-layout";
   }) => Promise<boolean>;
 
   // Request context
@@ -234,6 +242,7 @@ export interface RouterContext<TEnv = any> {
     nextUrl: URL,
     routeKey: string,
     actionContext?: any,
+    stale?: boolean,
   ) => Promise<{ segments: ResolvedSegment[]; matchedIds: string[] }>;
 
   // Entry revalidation map
@@ -241,6 +250,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,